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:
@@ -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