feat(studio): deliver asset authoring and automation workflows
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit

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:
2026-11-11 01:21:25 +00:00
parent b351f2e582
commit 1471b427f1
325 changed files with 61179 additions and 323 deletions
@@ -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.
@@ -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.