feat(studio): deliver asset authoring and automation workflows
Add shared human/task asset batches with reviewed atomic publication, explicit reference rebinds, ownership inspection and qualified glyph/scene budgets. Expose the same authoring and capacity results through Assets and MCP. Deliver isolated guest test targets, retained visual evidence and immutable runtime lifecycle/control observations. Preserve provider qualification and installed authoring examples alongside the completed discussion lessons. Close AGD-106 coordination and the delivered discussion workflows through housekeeping, updating lesson references and preserving qualification limits. Sound remains outside the asset delivery wave. Validation: 579 module tests and 31 additional desktop, process and installed checks passed; native glyph/scene 16/17 boundaries qualified. Discussion validation passed after housekeeping.
This commit is contained in:
+22
@@ -613,3 +613,25 @@ Its requirements apply in addition to this chapter; pause/resume remain independ
|
||||
Game stdlib 1 distributes executable ordinary PBS modules `@core:sprite` and `@core:animation`. Private helpers retain definition-scoped resolution and trusted origin. Reserve `generated/animations` for project-owned virtual modules `@<project>:generated/animations/b_<uuid_without_hyphens>`; physical collisions are diagnostics. Only registered build-included banks publish factories; invalid included definitions block analysis/build.
|
||||
|
||||
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
|
||||
|
||||
## Isolated test target source selection
|
||||
|
||||
`prometeu.json.testTargets` schemaVersion 1 MAY declare targets with id, entrypoint,
|
||||
sourceRoots, supportRoots, exclusions, cases and logTag. Omitted selection MUST be
|
||||
production; production is reserved and MUST NOT be redefined by this section.
|
||||
Entrypoint and roots are normalized project-relative paths; exclusions are exact
|
||||
selected source files, never globs or implicit error suppression. Resolution MUST
|
||||
validate canonical scope/existence and retain the original admitted paths/hashes.
|
||||
|
||||
Selected targets MUST use the ordinary project dependency/import resolver, SDK,
|
||||
assets and PBS visibility. Target support modules MUST be absent from production
|
||||
and all other targets unless explicitly selected there. No friend/private access,
|
||||
reflection or automatic production export is permitted. State setup MUST use
|
||||
existing public APIs plus target-only support; a missing required game API MUST be
|
||||
reported before any game patch or visibility approximation. Selecting a test MUST
|
||||
NOT edit, rename, restore or regenerate production source/barrel bytes.
|
||||
|
||||
The exclusive entrypoint/lifecycle selection MUST propagate through common compiler
|
||||
context. Test-specific output/provenance follow the common compiler target contract,
|
||||
without changing project identity, appId, AppMode or machine limits. This accepted
|
||||
contract is being implemented under PLN-0172.
|
||||
|
||||
+26
@@ -260,3 +260,29 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
|
||||
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
|
||||
bootstrap, project identity/slot validation and complete installed mem ABI.
|
||||
Its requirements apply in addition to this chapter; pause/resume remain independent.
|
||||
|
||||
## Test selection and negotiated log observation
|
||||
|
||||
Project testTargets version 1 MUST select an alternate source/lifecycle context
|
||||
without changing the production cartridge identity, appId, machine profile or
|
||||
asset/dependency rules. Test builds MUST retain target/source/configuration/assets
|
||||
provenance in their Studio result and use exclusive target/build output paths.
|
||||
Production Play MUST NOT consume a test build by recency.
|
||||
|
||||
Structured test execution MUST require negotiated headless protocol 1.2 capability
|
||||
log_read before guest execution. A provider without that capability MUST refuse
|
||||
structured tests explicitly while preserving compatible production flows. get_logs
|
||||
MUST be read-only and non-destructive, using nullable exclusive afterSequence and
|
||||
limit 1..1024. Lossless uint64 sequences include zero with a null initial cursor.
|
||||
The result MUST retain session/epoch, typed native records, retention bounds, next
|
||||
cursor and gap/overflow evidence. Wall-clock timestamps MUST NOT form deterministic
|
||||
assertion oracles. This is a tooling extension over existing sdk/log, not a new
|
||||
guest syscall/ABI or an increased execution budget.
|
||||
|
||||
Test media MUST be explicit memory_fresh or a disposable image under
|
||||
`.studio/test-runs/<runId>/`. Production/default/personal card paths MUST NOT be
|
||||
selected implicitly. Persisted-save proof requires closing the process and reopening
|
||||
the same disposable card in a new one; RAM state and commit acknowledgement are
|
||||
not durability proof. Pending-data refusals MUST remain native and require explicit
|
||||
recovery, without silent discard. Provider writes/builds await the separate runtime
|
||||
authorization gate in PLN-0172.
|
||||
|
||||
@@ -453,3 +453,62 @@ Its requirements apply in addition to this chapter; pause/resume remain independ
|
||||
A result success evaluates its payload once. Propagation and handle evaluate their operand once; only the selected recovery arm runs. Error remapping returns the enclosing error; traps are not caught. Animation advances only through explicit ticks. Queries/emissions are pure with respect to playback; repeated play/select resets the selected clip even when its name is unchanged.
|
||||
|
||||
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
|
||||
|
||||
## Isolated guest tests preserve lifecycle and visibility
|
||||
|
||||
The selected test entrypoint MUST own exactly one program lifecycle. Existing
|
||||
MemcardBoot, bootstrap, Init and Frame rules and budgets remain normative. Test
|
||||
support MUST use normal PBS visibility and exist only in explicitly selected roots.
|
||||
Work MUST be distributed across guest frames; the host MUST advance in bounded
|
||||
blocks and inspect tagged logs between blocks, including completion/failure when
|
||||
available. Timeout, cancellation and explicit completion are distinct.
|
||||
|
||||
Test-only support MUST emit versioned JSON via existing sdk/log and the target's
|
||||
declared logTag. Every envelope contains schemaVersion 1, suiteId, eventId, kind,
|
||||
nullable caseId for suite events, and payload. Kinds are suite_start, case_start,
|
||||
assertion, checkpoint, case_end and suite_end. Assertions MUST retain name/message,
|
||||
optional expected/actual and boolean passed. Checkpoints MAY reference retained
|
||||
visual evidence IDs; ordinary game log text MUST NOT be interpreted as test events.
|
||||
|
||||
Host validation MUST enforce declared tag, schema/types, event order, suite/case
|
||||
identity, expected case catalogue and consistent duplicate event IDs. Reconsulting
|
||||
a native sequence MUST NOT reapply it. Unread gaps or sequence discontinuity, malformed/conflicting events,
|
||||
session/epoch changes and native faults MUST prevent success. Case states are
|
||||
passed, failed, not_run and infrastructure_failure. Pass requires a nonempty suite,
|
||||
at least one assertion, explicit suite completion, every expected case completed,
|
||||
no failed assertion and no loss/protocol/fault condition. Fault alone, missing cases
|
||||
or an empty suite MUST NOT become a successful assertion report. Accepted contract
|
||||
implementation is in progress under PLN-0172.
|
||||
|
||||
### Structured assertion detail and host retention
|
||||
|
||||
Optional expected/actual values MUST retain independent availability flags, so an
|
||||
omitted value differs from an observed null. Native sequence/frame/timestamp,
|
||||
source/tag/application and the original event MUST remain correlated in transcript
|
||||
entries. Wall timestamps MUST NOT determine the verdict. An optional boolean
|
||||
passed on case_end/suite_end MAY explicitly reject that case/suite; it MUST NOT
|
||||
override a failed assertion. Non-boolean completion flags are invalid. Checkpoint
|
||||
artifact IDs MUST pass current project admission before inclusion as valid links.
|
||||
|
||||
The initial host accumulator retains at most 16 MiB and 100000 native records per
|
||||
run. Exceeding a host retention bound MUST report explicit infrastructure failure
|
||||
with the bound and retained position, never silently discard records or pass.
|
||||
These are host transcript bounds and do not alter firmware budgets. The installed
|
||||
isolated-tests example uses target-only helpers with complete versioned JSON
|
||||
literals and predicate booleans; it assumes no new guest string formatting ABI.
|
||||
|
||||
### Guest producer continuity and native retention
|
||||
|
||||
Every structured guest event payload MUST include a zero-based contiguous integer
|
||||
ordinal; suite_end MUST include eventCount counting all unique events including
|
||||
itself. Retries with the same event identity/content are idempotent. Missing or
|
||||
inconsistent ordinals/final counts fail as infrastructure errors, even if native
|
||||
sequences remain contiguous. Native overflow records historical eviction; only
|
||||
unread gap or actual continuity loss causes a retention failure. Preserve the
|
||||
overflow observation separately.
|
||||
|
||||
Encoded guest messages MUST fit 256 UTF-8 bytes and stay within the unchanged
|
||||
10 messages/application/frame budget, including ordinary application logs. The
|
||||
runner drains every pending native page before another bounded advance. Native
|
||||
continuity alone cannot detect events dropped before ring insertion. No new guest
|
||||
ABI, formatting facility or increased execution/logging budget is introduced.
|
||||
|
||||
@@ -374,3 +374,34 @@ This document is healthy when:
|
||||
3. the minimum result contracts are explicit,
|
||||
4. `run` no longer acts as a normative public concept,
|
||||
5. and caller-specific contexts are constrained without opening semantic drift.
|
||||
|
||||
## Isolated build target context
|
||||
|
||||
An omitted build target MUST select `production` and preserve existing source,
|
||||
output, AppMode and appId behavior. A test target is a separate explicit selection,
|
||||
not a machine profile. `prometeu.json` MAY declare `testTargets` schemaVersion 1
|
||||
with a targets array. Each target MUST have a unique non-production id, a project-
|
||||
relative entrypoint file, sourceRoots, supportRoots, exact exclusions, expected
|
||||
case IDs and a uint16 logTag. Paths MUST be normalized project-relative paths and
|
||||
canonical admission MUST prevent escapes through symlinks. Unknown IDs, duplicate
|
||||
IDs/cases/paths and exclusions that are not exact selected source files MUST fail.
|
||||
|
||||
Selection MUST propagate through the API, resolved workspace, project descriptor,
|
||||
source crawling, frontend/lifecycle context, compile/build pipeline, pack/shipper
|
||||
and result. The same dependency/import resolver and asset graph MUST be used.
|
||||
Only selected roots/support and exact exclusions determine the effective source
|
||||
set; diagnostics MUST retain original paths and source revisions. Included invalid
|
||||
files MUST NOT disappear through implicit exclusion. Each selected test program
|
||||
MUST have one lifecycle belonging to its declared entrypoint.
|
||||
|
||||
Test output MUST be immutable per target/build in
|
||||
`.studio/test-builds/<targetId>/<buildId>/`. Artifacts in use MUST NOT be overwritten.
|
||||
The usable build identity MUST be published only after complete successful output;
|
||||
failed/cancelled builds MUST NOT become bootable. Provenance MUST include selected
|
||||
target/entrypoint, effective source/configuration/dependency/asset hashes and their
|
||||
revision. Normal Play MUST always request production, irrespective of the last test
|
||||
build. No production source/barrel is edited or patched to select a test target.
|
||||
|
||||
This is the accepted DEC-0094 contract. Target propagation and structured execution
|
||||
remain in progress under PLN-0172; declaring this contract does not advertise an
|
||||
implemented capability in installed tools.
|
||||
|
||||
@@ -167,3 +167,26 @@ This specification is complete enough when:
|
||||
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude `animations.studio.json` from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
|
||||
|
||||
See the [complete animation contract](../studio/12.%20Animation%20Authoring%20Specification.md).
|
||||
|
||||
## Revision-checked authoring batches
|
||||
|
||||
The packer project write lane MUST support previewed atomic batches spanning
|
||||
declared asset bytes, manifests, registry and related Studio metadata. Preview
|
||||
leaves published state unchanged. Revalidate the complete input revision and
|
||||
relevant source hashes immediately before commit. Shared reads/builds/writes
|
||||
MUST observe the old complete batch or the new complete batch, with durable
|
||||
journal recovery before admission after interruption.
|
||||
|
||||
Registration continues to allocate identity through this registry. An
|
||||
uncommitted staged allocation is not an issued published identity. Identical
|
||||
reimport MUST preserve UUID/AssetId, stable artifact IDs, selected order, output
|
||||
hashes and references; append MUST NOT renumber existing glyphs/artifacts.
|
||||
Incompatible replacement, removal or size/order/layout change requires complete
|
||||
affected-reference analysis and explicit rebind in the same batch.
|
||||
|
||||
Cancellation/failure before commit leaves the old published state. After the
|
||||
commit point, retained result/recovery reports the applied state rather than
|
||||
claiming rollback. Request/batch correlation supports response-loss recovery
|
||||
without acting as authority. The write lane coordinates participating services;
|
||||
external writers that ignore it are detected by revision revalidation rather
|
||||
than claimed to be serialized.
|
||||
|
||||
@@ -257,3 +257,22 @@ This specification is complete enough when:
|
||||
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude `animations.studio.json` from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
|
||||
|
||||
See the [complete animation contract](../studio/12.%20Animation%20Authoring%20Specification.md).
|
||||
|
||||
## Batch composition, ownership and dependency boundaries
|
||||
|
||||
Authorized PNG import, bank creation/registration, ordered composition,
|
||||
build-inclusion and preload/contract changes MUST reuse existing declaration,
|
||||
registry and canonical scene-request rules through the shared batch service.
|
||||
No agent-specific manifest/index writer or second packer is introduced. External
|
||||
source grants and expected hashes are validated before publication.
|
||||
|
||||
Generated-output ownership and dependency metadata MUST be declared and
|
||||
queryable by asset/batch. It describes producer, output path, input asset edges
|
||||
and stale dependent state without replacing registry identity. Only explicitly
|
||||
requested internal batch operations execute. Metadata MUST NOT invoke shell,
|
||||
external generators, ROM importers or automatic transitive regeneration.
|
||||
|
||||
Composition changes MUST preserve no-op/append identities and expose affected
|
||||
animation/scene/metadata references for explicit incompatible rebind. Canonical
|
||||
scene layers retain cold glyph AssetIds; a batch MUST NOT reinterpret them as
|
||||
runtime slot numbers or synthesize hidden helper exports.
|
||||
|
||||
@@ -314,3 +314,42 @@ This specification is complete enough when:
|
||||
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude `animations.studio.json` from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
|
||||
|
||||
See the [complete animation contract](../studio/12.%20Animation%20Authoring%20Specification.md).
|
||||
|
||||
## Qualified global bank budgets and publication
|
||||
|
||||
Bank-content format limits and global residency limits are separate checks.
|
||||
The final deterministic packer preload list is the authority for effective
|
||||
slots per bank type; individual glyphs, logical scenes and stages do not add
|
||||
bank slots. Report existing, build-included, effective-preload and potential
|
||||
dynamic views separately. Cold scene dependencies follow the existing runtime
|
||||
residency contract, preserving AssetId identity rather than converting it into
|
||||
a slot. Potential dynamic excess is a warning about possible loads, not proof
|
||||
of simultaneous residency.
|
||||
|
||||
Global limits MUST come from a distributed versioned profile qualified against
|
||||
the exact selected installed executable. The profile includes contract/runtime
|
||||
versions, executable digest, per-type limits and retained positive/boundary
|
||||
evidence. Publish the initial 16-slot profile only after the selected executable
|
||||
passes 16/17 qualification for glyph and scene. Sound is outside this wave;
|
||||
profiles MUST contain only bank types with actual boundary evidence. An absent/incompatible
|
||||
profile is unknown, never unlimited or a silent constant/family fallback.
|
||||
|
||||
With a known profile, validate effective preloads before final cartridge
|
||||
publication. Excess MUST retain the previous valid output and report the type,
|
||||
limit, responsible slots/AssetIds/paths and profile. A build without a selected
|
||||
compatible profile may publish with explicit unknown qualification, but MUST
|
||||
NOT claim qualified capacity. Managed execution requires a matching profile and
|
||||
valid budget through the same shared preflight. Runtime selection or effective
|
||||
input changes invalidate the previous check. Record the checked profile and
|
||||
input revision in build provenance; ordinary builds MUST NOT inspect runtime
|
||||
checkout sources to obtain limits.
|
||||
|
||||
|
||||
The bundled macOS arm64 profile `macos-arm64-cli-0.1.0-18423f7-glyph-scene-v1`
|
||||
is qualified for glyph=16 and scene=16 against exact dispatcher, headless and
|
||||
desktop component hashes. Runtime version `0.1.0` alone does not select it.
|
||||
The distributed catalog includes hashed boundary evidence. Managed start and each
|
||||
headless BOOT MUST recheck the selected component fingerprints, the complete
|
||||
profile/evidence identity, and hashes of actual cartridge files. Admission reads
|
||||
the serialized `assets.pa` table/preload; auxiliary JSON never replaces it.
|
||||
A changed executable, evidence or build requires a new qualified build.
|
||||
|
||||
@@ -300,3 +300,26 @@ This specification is complete enough when:
|
||||
- Studio-facing operational semantics are explicit;
|
||||
- safety/preview/apply behavior is clear;
|
||||
- event/reporting integration has a stable baseline.
|
||||
|
||||
## Asset batch outcomes and lossless diagnostics
|
||||
|
||||
Batch preview/result values MUST distinguish ready, no-op, stale conflict,
|
||||
rejected rebind, cancelled before commit, committed and recovered outcomes.
|
||||
Preview lists all affected assets/files, expected revision, proposed actions,
|
||||
reference/ownership changes and available producer diagnostics. Durable staging
|
||||
and journal recovery precede publication; shared readers do not observe partial
|
||||
batches. A query after commit/response loss returns applied truth, even when
|
||||
cancellation arrives later.
|
||||
|
||||
Preserve producer and code, assetRoot/path, bank type, missing/duplicate indices,
|
||||
affected references and available used/required/limit facts through packer,
|
||||
Studio shipper, MCP and FE. Do not discard structured detail and later parse
|
||||
prose to recreate it. Unavailable producer facts remain unavailable. Diagnostic
|
||||
identity and budget results MUST agree across adapters.
|
||||
|
||||
The shared budget projection separates per-bank content from existing,
|
||||
build-included, final-preload and potential dynamic residency. Known overflow
|
||||
diagnostics identify responsible slots/AssetIds/paths and qualified profile;
|
||||
unknown qualification has an explicit reason. Service and actual Assets UI
|
||||
qualification are separate gates, alongside recovery, no-op/append identity,
|
||||
explicit rebind and installed positive/negative capacity checks.
|
||||
|
||||
@@ -278,6 +278,34 @@ advances. DEV MUST identify images from an older build/session as stale during
|
||||
edits/rebuilds. The previous execution MUST stop before rebuilding artifacts
|
||||
that it uses. Capture/build correlation MUST NOT introduce code snapshots.
|
||||
|
||||
### Lifecycle, cleanup and recovery observations
|
||||
|
||||
Shared observations MUST distinguish no session, unknown state, an explicitly
|
||||
unbooted session after reset, confirmed boot, observed guest state, lost process
|
||||
and confirmed process-tree termination. An acknowledgement alone does not prove
|
||||
an unavailable native state. Guest termination and process termination remain
|
||||
different facts. Reset requires an explicit boot before intentional advancement.
|
||||
|
||||
Control return MUST revoke task authority before cleanup. Results and the DEV
|
||||
snapshot independently expose authority, task revocation, project closure, cleanup
|
||||
`NOT_REQUIRED`, `PENDING`, `COMPLETED` or `FAILED`, and structured cleanup failure.
|
||||
A cleanup failure MUST retain the manual guard and MUST NOT reactivate the task.
|
||||
An explicit subsequent reclaim may acknowledge actual completed cleanup.
|
||||
|
||||
Advance observations preserve requested and known completed frames, session/build,
|
||||
last confirmed canonical frame, capture staleness and native structured causes.
|
||||
Unknown progress is null, not zero. Guest fault, native host watchdog, media
|
||||
refusal/action requirement, invalid protocol, transport loss and consumer deadline
|
||||
remain distinguishable without parsing messages. Zero completed frames does not
|
||||
prove that an unsuccessful advance had no internal effects.
|
||||
|
||||
The DEV inspector MUST show current authority/cleanup, current-session known facts
|
||||
and the last operation conclusion separately, including media/native details,
|
||||
unavailable inspections and recovery preconditions. Recovery descriptions are
|
||||
read-only; they MUST NOT add manual headless Play/input, implicit replay, boot,
|
||||
media discard, a new authority owner or a larger execution budget.
|
||||
|
||||
|
||||
## 8. Local MCP Admission and Functional Surface
|
||||
|
||||
Concrete tool names, input schemas, response envelopes and HTTP lifecycle are
|
||||
@@ -425,3 +453,35 @@ DEV and the existing build surface render the canonical public view: summary, co
|
||||
Language queries use a 10000 ms execution budget from admission (including queue/read/connect/initialize/analysis/query) plus a 2000 ms cleanup response window. Cancel pending requests and owned socket/listener/executors. shutdownNow is not evidence of termination. If a child remains alive, the caller may return the primary failure with workerTerminated=false, but the managed worker remains alive/busy until that child actually stops. Manual control and successor admission cannot be released early. Preserve the first failure and attach cleanup state rather than replacing it with a later failure.
|
||||
|
||||
Conformance distinguishes model/projection tests, source-navigation tests and real JavaFX desktop inspection. Model tests alone do not establish visual inspection. The integrated corpus uses production compiler/packer/LSP and authenticated MCP; controlled invalid IR and stubborn-child/protocol fixtures are explicitly identified test injections.
|
||||
|
||||
## Visual evidence and human baseline review
|
||||
|
||||
DEV MUST offer a project evidence inspector for retained publications and reports.
|
||||
It MUST show expected/actual/diff, original pixel coordinates and RGBA samples,
|
||||
ROI/masks, normalized tolerance/alpha parameters, hashes, metrics, provenance and
|
||||
current staleness. Observation during an agent grant MUST NOT add input or Play.
|
||||
|
||||
A human MAY explicitly select and authorize an external PNG reference; the adapter
|
||||
MUST canonicalize the selection and enforce its exact project-bound grant through
|
||||
symlinks. Otherwise file import MUST remain inside the canonical project. Import
|
||||
or a rejected comparison MUST NOT approve a baseline. Baseline promotion MUST be
|
||||
an explicit human action under the existing manual mutation lease, recording the
|
||||
previous revision, new revision and reference origin. Grant/revocation and failed
|
||||
or cancelled comparison MUST leave reviewed baselines unchanged.
|
||||
|
||||
Revoked tasks MUST NOT read historical evidence. A fresh authorized task in the
|
||||
same project MAY read it; another project MUST NOT. The local bound human inspector
|
||||
MAY remain read-only during a grant. Project closure MUST deny further service
|
||||
access while preserving published bytes for a later authorized reopen.
|
||||
|
||||
## Project guest tests and production Play
|
||||
|
||||
The project test surface MUST offer explicit target/media selection and shared
|
||||
start/query/cancel/transcript services, showing case states passed, failed, not_run
|
||||
and infrastructure_failure, assertions, checkpoints, native observations and run
|
||||
completion/timeout/cancellation. Human mutation MUST use existing manual authority;
|
||||
while an agent holds control the surface is observation-only. DEV retains its
|
||||
grant/reclaim/observation role. Normal Play MUST always select production, never
|
||||
the last test build. No automatic source/barrel patches, larger budgets, private
|
||||
access or implicit personal-card use are permitted. This is the accepted contract
|
||||
for PLN-0172; UI/execution delivery remains in progress.
|
||||
|
||||
@@ -422,6 +422,44 @@ return, revocation or project closure. Cleanup failures never restore authority;
|
||||
the records are still discarded after managed work stops. Neither connection
|
||||
disconnect nor polling silence discards an authorized task's records.
|
||||
|
||||
### Structured runtime observation and recovery
|
||||
|
||||
`studio_operation_get.value.observation` is the immutable operation-final
|
||||
observation, published after worker termination. `currentObservation` is a
|
||||
separate passive session snapshot and may describe later reset/rebuild/shutdown.
|
||||
Both retain available project/task/operation/request and session/build identity;
|
||||
native request identity remains separately correlated. A follow-up lookup MUST
|
||||
NOT execute another advance or rewrite the original frame/progress/cause.
|
||||
|
||||
Headless replies and failures include an `observation` when available. Its fields
|
||||
are `sessionId`, `buildId`, `lifecycle`, `source`, `observedAt`, `progress`,
|
||||
`lastFrame`, `captureStale`, `nativeDetails`, `context`, `unavailable` and `recovery`.
|
||||
Native snapshots in `nativeDetails` retain their own observation provenance.
|
||||
Unsigned frame identities are lossless; unknown completed progress is null.
|
||||
`unavailable` preserves failed inspection separately from the original error.
|
||||
Human diagnostics do not replace structured fault/error/media payloads.
|
||||
|
||||
Lifecycle values are `ABSENT`, `UNKNOWN`, `UNBOOTED`, `BOOTED`, `GUEST_OBSERVED`,
|
||||
`LOST` and `TERMINATED`; the last two describe process availability. Native guest
|
||||
status remains a separate observed fact. Every recovery action has preconditions
|
||||
and `automatic: false`. Available actions describe inspection, original-operation
|
||||
lookup, explicit boot after reset or explicit new-session creation after loss.
|
||||
They never authorize replay or media discard.
|
||||
|
||||
Acquire/release successes expose `control`; release failures preserve the same
|
||||
authority/cleanup facts in `error.details.control` and the native cleanup cause
|
||||
where available. Task revocation is independent of cleanup success. The
|
||||
authenticated `studio_project_context` includes current `control` and `runtime`
|
||||
without admitting work under a revoked task; unavailable connection authentication
|
||||
still requires human inspection/fresh grant. Embedded read-only contexts without
|
||||
an automation service report null observations and an explicit limitation.
|
||||
|
||||
The installed guide MUST cover reset → boot with the same buildId → intentional
|
||||
advance, explicit disposable media, known zero versus unknown progress and lost
|
||||
response lookup with the original clientRequestId. A native refusal is not success;
|
||||
RAM-only continuation or accepted commit is not proof of durable persistence.
|
||||
|
||||
|
||||
## 5. Project Knowledge DTOs
|
||||
|
||||
Neutral `ProjectKnowledge.Context` contains projectRoot/projectName, languages,
|
||||
@@ -670,3 +708,138 @@ When the capability is absent, preserve standard results, report ANALYSIS_DETAIL
|
||||
Details retain component, operation/method, queryId, applicable identity, executionBudgetMs, cleanupBudgetMs, workerTerminated and cleanup. Preserve existing authority, read-only, unsupported and parameter errors. The first failure wins; cleanup status is attached independently. The default budget is 10000+2000 ms as specified by Studio 10. This does not alter runtime deadlines.
|
||||
|
||||
Conformance: StructuredDiagnosticsIntegrationTest exercises all eight unchanged PBS sources (now corrected positives), F1-local and the file-private negative control through authenticated HTTP MCP and the real project LSP; McpTaskToolsTest controlled invalid common IR exercises RET/join through the production backend/gateway/build tool. DiagnosticAnalysisProtocolTest checks retained identity/mismatch/unavailable; LanguageFailureContractTest checks real-socket controlled faults, fallback and delayed child termination. Existing task tests retain deduplication, cross-project isolation and revocation gates.
|
||||
|
||||
## Visual checkpoint evidence tools
|
||||
|
||||
The existing authenticated project MCP endpoint MUST expose studio_evidence_persist,
|
||||
studio_evidence_import, studio_evidence_compare, studio_evidence_list,
|
||||
studio_evidence_metadata, studio_evidence_read, studio_evidence_image and
|
||||
studio_evidence_delete. Each tool MUST require the explicit projectRoot and current
|
||||
taskId. Artifact ID knowledge MUST NOT bypass authority or project scope. No extra
|
||||
server or arbitrary-path binary download route is permitted. Human-only baseline
|
||||
approval and external-path authorization MUST NOT be MCP tools.
|
||||
|
||||
Persist identifies the original operation with exactly one operationId or
|
||||
sourceClientRequestId and a distinct publication clientRequestId. Import/compare
|
||||
also require a publication clientRequestId; same parameters recover the retained
|
||||
publication, and changed parameters conflict. List MUST return at most 100 records
|
||||
per page with offset/nextOffset/total, including request identity for lost-response
|
||||
recovery. Read MUST validate offset/length and permit at most 1 MiB per call; image
|
||||
MUST return integrity-checked PNG image content directly, bounded to 32 MiB. Metadata
|
||||
MUST expose historical artifact identity separately from current staleness.
|
||||
|
||||
Compare MUST require explicit alpha compare/ignore; omitted channelLimit and
|
||||
allowedDifferentPixels default to zero. It MUST return the full shared report;
|
||||
passed/rejected/dimension_mismatch are comparison verdicts, while operational
|
||||
failures use the structured error envelope. Image/bytes and report inspection
|
||||
MUST use IDs inside this endpoint and require no agent transport/comparison scripts.
|
||||
|
||||
## Isolated test target and transcript contract
|
||||
|
||||
The installed task-scoped surface is studio_tests_targets, studio_tests_start,
|
||||
studio_tests_get, studio_tests_cancel, studio_tests_transcript and
|
||||
studio_tests_shutdown. Start takes a declared targetId, maxFrames (1..1000000),
|
||||
blockFrames (1..60), timeoutMs (1..3600000), explicit media and discardUnsaved.
|
||||
Media is memory_fresh, disposable_create or disposable_reopen; reopen requires
|
||||
the creating run's UUID. These are bounded host policies, not guest budget changes.
|
||||
|
||||
Get returns run/request/operation identity, progress, workerTerminated, case/run
|
||||
result, transcriptTotal and the transcript paging tool. It MUST NOT inline the
|
||||
whole transcript into the summary response. Transcript returns offset/nextOffset,
|
||||
total and at most 1024 original native/decoded entries. Paging and repeated
|
||||
summary queries are non-executing. runtimeRetained reports current ownership
|
||||
separately from the immutable original run's cleanup observation. Shutdown requires
|
||||
actual worker termination and explicit discardUnsaved; it preserves native refusal.
|
||||
|
||||
The existing project endpoint MUST support explicit build target selection and
|
||||
shared guest test start/query/cancel/transcript access under current task authority,
|
||||
operationId/clientRequestId deduplication and actual worker termination. Omitted
|
||||
build target MUST be production; a changed target under the same request ID MUST
|
||||
conflict. Tests MUST refuse before guest execution unless the installed provider
|
||||
negotiates protocol 1.2 log_read. Availability MUST reflect implemented advertised
|
||||
handlers, not the existence of these accepted requirements.
|
||||
|
||||
Run results MUST correlate project/task/request/operation/run/target/build/session,
|
||||
retain immutable source/configuration/dependency/asset provenance and separate
|
||||
completion, timeout, cancellation, native failure and infrastructure loss. Case
|
||||
results MUST retain passed/failed/not_run/infrastructure_failure, explicit assertions
|
||||
and original checkpoint IDs. Transcript pages MUST preserve source sequences and
|
||||
loss evidence; requery MUST NOT reapply events or execute another advance. The
|
||||
mandatory success conditions and tagged JSON envelope are defined in the PBS
|
||||
dynamic semantics and common guest-test contracts. Tests MUST use explicit fresh
|
||||
RAM or a disposable run image, never default/personal media implicitly. Delivery
|
||||
uses the shared installed provider; any additional provider correction requires
|
||||
separate scoped authorization before runtime repository writes.
|
||||
|
||||
### Structured assertion detail and host retention
|
||||
|
||||
Optional expected/actual values MUST retain independent availability flags, so an
|
||||
omitted value differs from an observed null. Native sequence/frame/timestamp,
|
||||
source/tag/application and the original event MUST remain correlated in transcript
|
||||
entries. Wall timestamps MUST NOT determine the verdict. An optional boolean
|
||||
passed on case_end/suite_end MAY explicitly reject that case/suite; it MUST NOT
|
||||
override a failed assertion. Non-boolean completion flags are invalid. Checkpoint
|
||||
artifact IDs MUST pass current project admission before inclusion as valid links.
|
||||
|
||||
The initial host accumulator retains at most 16 MiB and 100000 native records per
|
||||
run. Exceeding a host retention bound MUST report explicit infrastructure failure
|
||||
with the bound and retained position, never silently discard records or pass.
|
||||
These are host transcript bounds and do not alter firmware budgets. The installed
|
||||
isolated-tests example uses target-only helpers with complete versioned JSON
|
||||
literals and predicate booleans; it assumes no new guest string formatting ABI.
|
||||
|
||||
## Shared asset authoring contract
|
||||
|
||||
Task-scoped asset operations MUST expose catalog, revision, dependency/ownership
|
||||
and budget queries plus preview, explicit commit and retained result queries
|
||||
over the shared service. Agent requests use stable asset/artifact identities,
|
||||
explicit semantic mutations and request IDs; they do not edit registry or
|
||||
asset-manifest persistence internals. Human external-PNG authorization is not
|
||||
issued by an MCP tool. Project-contained inputs still use normal task read
|
||||
authority and byte validation.
|
||||
|
||||
Preview returns the expected revision, all proposed changed files/assets,
|
||||
before/after hashes, affected references, available producer facts, ownership
|
||||
and conflicts. Commit supplies the batch ID and expected revision. Deduplicate
|
||||
each operation by authenticated project/task/request ID and its complete
|
||||
parameters. Revoke/cross-project checks apply to queries and retries as well as
|
||||
mutations. Cancellation before commit reports no publication; after commit,
|
||||
query/retry returns applied or recovered truth.
|
||||
|
||||
Results preserve producer/code, assetRoot/path/type, missing/duplicate indices,
|
||||
affected references and available used/required/limit facts. FE and MCP MUST
|
||||
show those same values. Budgets distinguish bank content, existing assets,
|
||||
build-included assets, effective final preloads and potential dynamic residency.
|
||||
Unknown profile status and its reason are explicit. A supplied profile or
|
||||
numeric count from an untrusted request does not establish qualification.
|
||||
|
||||
The installed task-scoped tools are `studio_assets_catalog`,
|
||||
`studio_assets_artifacts`, `studio_assets_inspect`, `studio_assets_revision`,
|
||||
`studio_assets_dependencies`, `studio_assets_budget`, `studio_assets_preview`,
|
||||
`studio_assets_preview_get`, `studio_assets_commit` and `studio_assets_result`.
|
||||
Each requires current `projectRoot` and `taskId`. Catalog pagination is bounded;
|
||||
`studio_assets_artifacts` accepts an optional `batchId` to inspect replacement
|
||||
targets in a retained preview. Mutation discriminators are `create`, `register`,
|
||||
`import`, `compose_bank`, `compose_palettes`, `compose_scene`, `update_contract`
|
||||
and `build_participation`. Scene tiles name stable bank/artifact identities;
|
||||
only the canonical packer adapter resolves them to runtime glyph indices.
|
||||
External PNG grants can be issued only through human source selection.
|
||||
The catalog is extended only when shared implementation, authority, recovery,
|
||||
FE parity and qualification gates are present. The existing tool catalog
|
||||
remains authoritative during implementation.
|
||||
|
||||
### Guest producer continuity and native retention
|
||||
|
||||
Every structured guest event payload MUST include a zero-based contiguous integer
|
||||
ordinal; suite_end MUST include eventCount counting all unique events including
|
||||
itself. Retries with the same event identity/content are idempotent. Missing or
|
||||
inconsistent ordinals/final counts fail as infrastructure errors, even if native
|
||||
sequences remain contiguous. Native overflow records historical eviction; only
|
||||
unread gap or actual continuity loss causes a retention failure. Preserve the
|
||||
overflow observation separately.
|
||||
|
||||
Encoded guest messages MUST fit 256 UTF-8 bytes and stay within the unchanged
|
||||
10 messages/application/frame budget, including ordinary application logs. The
|
||||
runner drains every pending native page before another bounded advance. Native
|
||||
continuity alone cannot detect events dropped before ring insertion. No new guest
|
||||
ABI, formatting facility or increased execution/logging budget is introduced.
|
||||
|
||||
@@ -140,3 +140,20 @@ orchestrates persistence/layout/rendering; app composes the Packer API adapter.
|
||||
PBS alone generates PBS source; compiler/backend stay independent of Studio core.
|
||||
|
||||
Installed references, examples and MCP schemas must expose this same contract.
|
||||
|
||||
## Asset batch identity and explicit rebind
|
||||
|
||||
Animation documents and metadata MUST participate in the shared asset batch
|
||||
revision, affected-reference analysis and publication exclusion. An identical
|
||||
PNG reimport preserves artifact identities, ordering, hashes and animation
|
||||
bindings. Append allocates only new artifact identities without renumbering
|
||||
existing frames. Removal, incompatible replacement or size/order/layout change
|
||||
MUST enumerate affected animation/scene/metadata references and require explicit
|
||||
mapping in the same batch.
|
||||
|
||||
Existing prepare/apply rebind validation remains authoritative. A batch does not
|
||||
silently retarget frames by path or list position, relax validation, or publish
|
||||
the bank before its declared binding changes. Revalidate both document and bank
|
||||
revisions at commit and recover the whole declared batch before any shared
|
||||
animation reader observes it. Record stale generated dependents explicitly;
|
||||
an ownership edge does not execute a generator or promise recomposition.
|
||||
|
||||
@@ -496,3 +496,50 @@ This specification is satisfied when the Studio `Assets` workspace:
|
||||
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
|
||||
|
||||
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
|
||||
|
||||
## Shared asset authoring and budget inspection
|
||||
|
||||
Human and task callers MUST use the same authority-aware authoring service and
|
||||
packer operations. The initial batch contract covers authorized PNG import,
|
||||
bank creation/registration, ordered glyph and canonical scene composition,
|
||||
build inclusion, preload/contract updates, explicit palettes and append/reimport.
|
||||
This wave covers glyph and scene banks. Sound authoring, packing and qualification
|
||||
are deferred; existing unsupported sound diagnostics remain authoritative.
|
||||
|
||||
Every batch MUST present its expected revision, affected stable asset identities,
|
||||
proposed file changes with before/after hashes, ownership/dependencies, affected
|
||||
references, conflicts and complete producer diagnostics before explicit commit.
|
||||
A stale revision, changed source bytes or unresolved incompatible rebind MUST
|
||||
block publication. Identical reimport MUST preserve IDs, order, output hashes and
|
||||
animation links; append MUST preserve existing artifact identities.
|
||||
|
||||
Assets MUST reuse its navigator, selection/order controls and local capacity
|
||||
meters. Inspection MUST show revision/conflicts, references and generated-output
|
||||
dependencies. Global capacity MUST be shown separately from bank content, with
|
||||
distinct existing, build-included, final-preload and potential dynamic views.
|
||||
Show used/required/limit and the selected profile or explicit unknown status in
|
||||
readable text. A potential dynamic excess is a warning, not proof that all
|
||||
potential banks are simultaneously resident. A grant permits human inspection
|
||||
while keeping human mutation blocked.
|
||||
|
||||
FE and MCP MUST consume the same immutable preview/result/budget projection.
|
||||
Neither surface may reconstruct missing producer facts from prose or maintain
|
||||
its own capacity count. Existing per-bank meters remain visible. Preview,
|
||||
explicit commit, stale conflict and rejected rebind MUST be usable in the actual
|
||||
Assets flow, with actionable details readable at supported window sizes.
|
||||
|
||||
|
||||
The inline capacity area above the existing navigator/details split MUST show
|
||||
qualification, separate existing/build/preload/potential counts and producer
|
||||
facts. Existing bank composition, palettes, contract and scene acceptance actions
|
||||
use the shared preview and explicit publication dialog. Replacement artifact
|
||||
choices MUST be explicit for every affected animation, scene or metadata use.
|
||||
The PNG picker issues a project-bound source grant; it does not grant a task any
|
||||
external filesystem access. Ownership declaration records an existing output and
|
||||
its named inputs without running a producer.
|
||||
|
||||
A draft bank may be published before scene composition is accepted. A missing
|
||||
canonical scene request is still a cartridge-blocking packer diagnostic. Draft
|
||||
previews expose that fact with `cartridgeBlocking: true`; no draft publication
|
||||
qualifies it for build or execution. Unrelated unfinished banks do not prevent
|
||||
editing another bank. Invalid changed glyph compositions remain rejected.
|
||||
|
||||
@@ -231,3 +231,73 @@ Retries MUST use capped exponential backoff (2–30 seconds), reset after connec
|
||||
and stop at extension shutdown. Connection state MUST be visible without recurring
|
||||
error popups. Explicit manual mode MAY use configured host/port for other hosts.
|
||||
The server's project binding validation remains authoritative.
|
||||
|
||||
## Persistent visual evidence
|
||||
|
||||
Visual evidence MUST be retained separately from session restoration in
|
||||
`.studio/evidence/`. Immutable publication directories contain PNG objects and a
|
||||
publication record, including comparison reports and reviewed baseline revisions.
|
||||
The application filesystem adapter MUST stage and integrity-check complete objects
|
||||
and publish the directory atomically. Incomplete staging MUST NOT be listed and
|
||||
MAY be cleaned under the store lock on reopen. Rebuild, release, shutdown and
|
||||
project/application closure MUST preserve completed publications.
|
||||
|
||||
The byte quota MUST be configurable and default to 512 MiB per project. Admission
|
||||
MUST serialize concurrent publishers, include object and publication metadata
|
||||
bytes, and refuse before publication with used/required/limit. It MUST NOT evict
|
||||
evidence or replace a baseline to admit new data. Deletion MUST be explicit,
|
||||
authorized and refuse while another report or baseline references the publication.
|
||||
|
||||
Each artifact MUST retain an opaque ID, SHA-256 of original bytes, size, MIME,
|
||||
dimensions and available project/task/operation/client-request/build/session/frame
|
||||
provenance. Current staleness MUST be a separate observation, never a metadata
|
||||
rewrite. Imported references MUST identify their external origin without invented
|
||||
runtime identities. Report and baseline history MUST remain immutable.
|
||||
|
||||
## Isolated guest test artifacts
|
||||
|
||||
Test build output MUST live in `.studio/test-builds/<targetId>/<buildId>/`; test
|
||||
run media/transcript identity MUST live under `.studio/test-runs/<runId>/`. These
|
||||
are separate from session restoration and the production build output. Successful
|
||||
builds MUST retain immutable target/configuration/source/dependency/asset provenance.
|
||||
Incomplete or cancelled output MUST NOT publish a usable build identity. Test media
|
||||
MUST be disposable and explicit; default/personal card paths MUST NOT be reused.
|
||||
Closing/reopening a process for persistence proof MUST retain the same selected
|
||||
disposable image and distinguish RAM, accepted commit and demonstrated durability.
|
||||
Each run retains media.json with the explicit mode/creating image identity and
|
||||
result.json with its immutable completion/verdict, native causes, provenance and
|
||||
cleanup observation. Reopen accepts only a service-owned disposable-create run,
|
||||
never an arbitrary media path or a personal/default-image alias. These records
|
||||
are historical results, not restored task authority or permission to resume work.
|
||||
|
||||
## Recoverable asset batches and ownership
|
||||
|
||||
Asset batch staging, journals, source grants and retained request/result
|
||||
correlation MUST remain separate from session restoration. The project-local
|
||||
batch store is `.studio/asset-batches/`; ownership/dependency declarations are
|
||||
separate versioned authoring metadata at `.studio/asset-ownership.json`.
|
||||
These stores MUST NOT duplicate registry authority over AssetId, UUID, location
|
||||
or build inclusion. Restoring a journal/result MUST NOT restore task authority
|
||||
or an external source grant.
|
||||
|
||||
A revision covers the relevant project/asset manifests, the authoritative
|
||||
`assets/.prometeu/index.json`, ordered composition, Studio metadata including
|
||||
animation bindings, declared ownership/dependencies and relevant input-byte
|
||||
hashes. Missing expected inputs are explicit revision facts. Every preview
|
||||
declares all asset/manifest/registry/metadata/input changes before publication.
|
||||
Revalidation immediately before commit MUST reject changed inputs.
|
||||
|
||||
Staging and a durable recoverable journal MUST precede publication. Shared
|
||||
readers/writers MUST recover pending publication before accessing project truth.
|
||||
Before the commit point, failure/cancellation leaves the old complete state;
|
||||
after it, recovery and result queries report the new complete applied state,
|
||||
including after a lost response or late cancellation. Never expose an
|
||||
intermediate batch as committed. The service detects external changes during
|
||||
revalidation; it does not serialize external writers that ignore Studio
|
||||
coordination. Request correlation records MUST NOT act as access credentials.
|
||||
|
||||
PNG sources inside the canonical project use current project read authority.
|
||||
External PNGs require an opaque project-bound grant issued by explicit human
|
||||
source selection. Validate canonical scope, expected bytes and PNG bounds before
|
||||
staging, then revalidate relevant source bytes at commit. A path, hash or
|
||||
caller-supplied claim alone is not an external-source grant.
|
||||
|
||||
@@ -159,6 +159,34 @@ Build and advance admission MUST return a promptly queryable operation identity.
|
||||
|
||||
## Conformance Gates
|
||||
|
||||
Runtime observations and control observations are neutral immutable API values.
|
||||
The process adapter validates native state, fault, media and error payloads; Core
|
||||
retains project/task/operation/request correlation and authorization independently.
|
||||
Neither JavaFX nor MCP may infer native phases, fabricate unknown progress or
|
||||
implement recovery by replaying commands. Passive observation getters MUST perform
|
||||
no native IO and MUST be safe to read while the authority monitor is held.
|
||||
|
||||
An operation-final observation MUST remain unchanged by a later state query,
|
||||
reset, rebuild or shutdown. A separate current-session observation carries the
|
||||
latest known facts. Every retained native snapshot carries its own source and
|
||||
observation time, so an earlier state is not mislabeled as a later observation.
|
||||
Failed follow-up inspection MUST retain the original native cause and record the
|
||||
missing observation separately. Runtime wire codecs remain in application adapters; the
|
||||
API supplies plain Java values and the JavaFX adapter presents those values.
|
||||
Observation updates MUST serialize with process-loss invalidation: late native
|
||||
progress/state cannot resurrect a lost process. Inspection admission MUST serialize
|
||||
with shutdown; unavailable inspection during closing is reported without sending
|
||||
a competing native query.
|
||||
|
||||
Diagnostic defaults and immutable value trees belong to the neutral Studio API.
|
||||
Studio's bounded diagnostic aggregation belongs to the existing Core shipper
|
||||
module; it MUST preserve whole-issue/count/UTF-8 budgets and producer fields.
|
||||
Project-bound diagnostic source reads belong to the existing Core project module,
|
||||
through `DiagnosticSources` exposed by the project session. JavaFX only presents
|
||||
values and requests read-only navigation through that port; it MUST NOT perform
|
||||
filesystem admission, read source bytes or serialize diagnostic wire payloads.
|
||||
|
||||
|
||||
The architecture is conformant only when all of the following hold together:
|
||||
|
||||
- API and core compile without JavaFX, Spring, HTTP/MCP SDKs or concrete transport DTO dependencies;
|
||||
@@ -221,3 +249,111 @@ The app compiler gateway translates complete warnings and BuildException payload
|
||||
A shared public view contains issues, summary and context. Detail projection is limited to 1024 whole issues and 1 MiB of UTF-8 JSON issues. At a boundary, include a whole prefix, report partial detail coverage and LIMIT_EXCEEDED with budgets/total count, and retain full authoritative counts/evaluation separately. No issue field may be silently cut. UI and MCP consume this same view; underlying producer results remain complete.
|
||||
|
||||
Conformance: DiagnosticPayloadTest, StructuredShipperTest, StructuredDiagnosticsIntegrationTest and the compiler attribution/conversion regressions.
|
||||
|
||||
## Visual evidence service boundaries
|
||||
|
||||
The Studio API MUST expose neutral artifact, RGBA8, comparison, bounded reading,
|
||||
publication and baseline-revision values and storage/codec ports. Core MUST own
|
||||
comparison and task/operation orchestration; concrete filesystem, PNG and wire
|
||||
codecs belong to application adapters. JavaFX MUST present the shared result.
|
||||
|
||||
Persistence MUST resolve a terminated operation by operationId/clientRequestId
|
||||
and copy exactly its retained runtimeResult.capture. It MUST NOT call advance or
|
||||
capture again. Publication requests MUST deduplicate by request identity and full
|
||||
parameters; changed parameters MUST conflict. A lost response MUST be recoverable
|
||||
from retained publication identity without guest replay. Mutations MUST use the
|
||||
existing project worker or human manual lease; no second runner is introduced.
|
||||
|
||||
Comparison MUST expand PNG samples losslessly to RGBA8 without gamma/perceptual
|
||||
correction or resize. Coordinates are top-left; ROI/masks are half-open rectangles
|
||||
validated against original dimensions without clipping. Masks exclude their union
|
||||
inside the ROI, counting overlaps once. An empty compared region is invalid. Alpha
|
||||
policy MUST be explicit compare/ignore, and RGB MUST be compared even at zero
|
||||
alpha. Defaults are exact: channel limit zero, differing-pixel allowance zero.
|
||||
Tolerant comparison declares an integer channel limit 0..255 and nonnegative
|
||||
allowed differing-pixel count. A pixel differs when any compared channel exceeds
|
||||
that limit; the maximum channel error records the observed error before tolerance.
|
||||
|
||||
Dimension mismatch MUST be an explicit comparison rejection, distinct from invalid
|
||||
parameters, decode, storage and authority errors. Reports MUST retain normalized
|
||||
parameters, both original byte hashes, expected/actual/diff IDs, verdict, compared
|
||||
and differing-pixel counts, maximum error and original-coordinate difference
|
||||
bounds (null without differences). The diff MUST distinguish excluded pixels
|
||||
(transparent black), compared pixels within tolerance (opaque green), and differing
|
||||
pixels (opaque red/yellow). It MUST retain original image dimensions/coordinates.
|
||||
|
||||
## Shared isolated guest test service
|
||||
|
||||
Target selection MUST propagate through the existing project/API/compiler/shipper
|
||||
services and resolver; the host test service MUST reuse existing task authority,
|
||||
operationId/clientRequestId deduplication, cancellation and worker termination.
|
||||
It MUST NOT introduce another resolver, runner authority, guest ABI or larger
|
||||
budgets. Test-only support and ordinary PBS visibility MUST preserve production
|
||||
source/barrel bytes and identity. Usable test builds MUST be exclusive and immutable
|
||||
per target/build, retaining effective source/configuration/dependency/asset hashes.
|
||||
|
||||
The application adapter MUST validate negotiated log_read before executing a test
|
||||
guest. It translates typed native get_logs records to neutral log pages with lossless
|
||||
uint64 session/epoch/cursor/retention information. Core MUST accumulate tagged
|
||||
versioned events, validate ordering/catalogue/duplicates/loss, and produce the same
|
||||
case/assertion/checkpoint/run result for all adapters. It MUST read logs after each
|
||||
bounded frame block and at completion/failure when available, without automatic
|
||||
advance replay or destructive draining. Timeout, cancellation, native failure and
|
||||
explicit suite completion MUST remain distinct; cancelled results are final only
|
||||
after actual worker termination. Checkpoint references retain original evidence
|
||||
identity from the shared visual service. The project Tests workspace and task MCP
|
||||
tools consume one shared service. Manual runs hold the existing execution lease;
|
||||
task runs use the existing automation worker. A retained manual test runtime blocks
|
||||
grant/production execution until explicit cleanup. A provider correction requires
|
||||
its own scoped authorization before runtime writes/builds.
|
||||
|
||||
## Shared asset authoring, revisions and capacity
|
||||
|
||||
The neutral API owns immutable batch requests/previews/results, revision and
|
||||
conflict values, affected references/rebinds, generated-output ownership graphs,
|
||||
producer diagnostics and separate content/global budget values. Core owns shared
|
||||
authority admission and orchestration over existing asset, composition, metadata,
|
||||
animation and packer services. Packer owns the project write lane and atomic
|
||||
recoverable publication. App adapters own canonical file authorization,
|
||||
serialization and distributed runtime-profile loading/identity verification.
|
||||
JavaFX and MCP render the same API projection.
|
||||
|
||||
Human mutations MUST enter the existing manual guard; task mutations MUST enter
|
||||
the existing current-task/project worker and recheck revocation at execution.
|
||||
Inspection remains available under its read authority. Preview does not commit.
|
||||
Commit is explicit, revision-checked and deduplicated by project/task/request ID
|
||||
and full parameters. Identical retries return the retained result; changed
|
||||
parameters conflict. Knowing a batch/request ID cannot restore revoked access.
|
||||
All shared readers, including build and animation readers, participate in packer
|
||||
publication exclusion/recovery; an MCP wrapper cannot bypass this boundary.
|
||||
|
||||
The application distributes capacity profiles by contract version, runtime
|
||||
version and exact verified executable digest, together with qualification
|
||||
evidence for every bank type it explicitly qualifies. The first profile covers
|
||||
glyph and scene only; sound qualification is deferred. There is no runtime-family fallback
|
||||
or ordinary-build access to runtime checkout sources. Missing, malformed or
|
||||
mismatched qualification is unknown. Core's one budget/preflight projection is
|
||||
consumed by shipper, headless and desktop execution. Unqualified builds may be
|
||||
produced, explicitly marked unknown; managed execution requires the matching
|
||||
qualified profile and valid effective budget.
|
||||
|
||||
The final packer preload list is authoritative. Runtime selection/input changes
|
||||
invalidate earlier qualification and require rechecking. Build provenance MUST
|
||||
include the profile and input revision actually checked. A known excess MUST
|
||||
fail before cartridge publication, retaining the previous valid output.
|
||||
|
||||
### Guest producer continuity and native retention
|
||||
|
||||
Every structured guest event payload MUST include a zero-based contiguous integer
|
||||
ordinal; suite_end MUST include eventCount counting all unique events including
|
||||
itself. Retries with the same event identity/content are idempotent. Missing or
|
||||
inconsistent ordinals/final counts fail as infrastructure errors, even if native
|
||||
sequences remain contiguous. Native overflow records historical eviction; only
|
||||
unread gap or actual continuity loss causes a retention failure. Preserve the
|
||||
overflow observation separately.
|
||||
|
||||
Encoded guest messages MUST fit 256 UTF-8 bytes and stay within the unchanged
|
||||
10 messages/application/frame budget, including ordinary application logs. The
|
||||
runner drains every pending native page before another bounded advance. Native
|
||||
continuity alone cannot detect events dropped before ring insertion. No new guest
|
||||
ABI, formatting facility or increased execution/logging budget is introduced.
|
||||
|
||||
Reference in New Issue
Block a user