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
@@ -62,7 +62,7 @@ public class PBSFrontendPhaseService implements FrontendPhaseService {
final var parsedSourceFiles = new PbsGenericProgramService().prepare(assembly.parsedSourceFiles(), sourceContexts,
assembly.moduleTable(), diagnostics, feSurfaceContext);
final var importedSemanticContexts = importedSemanticContextService.build(parsedSourceFiles, assembly.moduleTable(), assembly.siblingDeclarationsByModule());
projectLifecycleSemanticsValidator.validate(parsedSourceFiles.asList(), diagnostics);
projectLifecycleSemanticsValidator.validate(parsedSourceFiles.asList(), diagnostics, ctx);
final var failedModuleIds = assembly.mutableFailedModuleIds();
final var moduleDependencyGraph = assembly.moduleDependencyGraph();
final var canonicalModulePool = assembly.canonicalModulePool();
@@ -12,6 +12,11 @@ final class PbsProjectLifecycleSemanticsValidator {
void validate(
final java.util.List<PbsParsedSourceFile> parsedSourceFiles,
final DiagnosticSink diagnostics) {
validate(parsedSourceFiles, diagnostics, null);
}
void validate(final java.util.List<PbsParsedSourceFile> parsedSourceFiles, final DiagnosticSink diagnostics,
final p.studio.compiler.messages.FrontendPhaseContext context) {
final var frames = new ArrayList<PbsAst.FunctionDecl>();
final var hooks = new java.util.EnumMap<PbsAst.LifecycleMarker, PbsAst.FunctionDecl>(PbsAst.LifecycleMarker.class);
final var declarations = new java.util.HashSet<String>();
@@ -45,6 +50,10 @@ final class PbsProjectLifecycleSemanticsValidator {
}
}
if (functionDecl.lifecycleMarker() == PbsAst.LifecycleMarker.FRAME) {
if (context != null && context.entrypoint() != null
&& !context.entrypoint().equals(context.fileTable.get(parsedSource.fileId()).getCanonPath()))
p.studio.compiler.source.diagnostics.Diagnostics.error(diagnostics, "E_SEM_TEST_TARGET_ENTRYPOINT",
"Selected test [Frame] must belong to entrypoint " + context.entrypoint(), span);
frames.add(functionDecl);
}
}
@@ -0,0 +1,93 @@
# Shared glyph and scene authoring
Use the existing Assets workspace or the current-task `studio_assets_*` tools.
Both call the same authoring, reference analysis, packer and publication service.
Sound authoring and capacity qualification are deferred.
## Inspect, preview, publish
1. Obtain a fresh human grant and `studio_control_acquire`. Every tool below
requires the current `projectRoot` and `taskId`.
2. Query `studio_assets_catalog`, `studio_assets_inspect`,
`studio_assets_artifacts`, `studio_assets_dependencies` and
`studio_assets_budget`. Catalog accepts `offset` and `limit` (maximum 1024).
3. Freeze the complete `revision` from `studio_assets_revision`. Use that exact
object as `request.expectedRevision` in `studio_assets_preview`.
4. Review `files` (including both hashes), affected assets, producer diagnostics,
conflicts and `affectedReferences`. Preview stages bytes without publishing.
5. Commit only a ready/no-op preview using `studio_assets_commit` with its
`batchId`, exact `expectedRevision` and a fresh `clientRequestId`.
6. Recover a lost response using `studio_assets_result`. Retry the same request
with identical parameters; changing parameters under a request ID conflicts.
Cancellation after the durable commit marker cannot undo publication.
A human uses the PNG picker to authorize an external source. A task may use a
project-contained input with its exact SHA-256, or an opaque grant already issued
for this project. Caller-supplied external paths are never a grant.
## Create a glyph bank from an existing project PNG
The following is the `request` body for `studio_assets_preview`. Replace `REVISION`
with the queried object and `PNG_SHA256` with the exact bytes of `art/red.png`.
The placeholders are instructional; they are not valid submitted values.
```json
{
"expectedRevision": "REVISION",
"mutations": [
{"kind":"create","changeId":"bank","relativeRoot":"sprites","name":"sprites","family":"GLYPH_BANK","outputFormat":"GLYPH_INDEXED_V1","outputCodec":"NONE","preload":true},
{"kind":"update_contract","changeId":"geometry","bank":"asset:root:sprites","preload":true,"outputCodec":"NONE","codecFields":{},"metadataFields":{"tile_size":"16x16"}},
{"kind":"import","changeId":"source","source":{"projectRelativePath":"art/red.png","externalGrantId":null,"sha256":"PNG_SHA256"},"bank":"asset:root:sprites","destination":"red.png"},
{"kind":"compose_palettes","changeId":"palette","bank":"asset:root:sprites","palettes":[{"index":0,"rgba8888":[4278190335]}]},
{"kind":"compose_bank","changeId":"selection","bank":"asset:root:sprites","selectedPaths":["red.png"]}
],
"rebinds": [],
"ownership": []
}
```
After publication, query the assigned asset identity and its artifacts. Subsequent
requests should use those returned identities. Importing identical bytes is a
no-op; appending selected paths retains earlier identities and indices. Reorder,
removal, content/size and layout changes require reference analysis. A rejected
preview lists the exact animation/scene/metadata uses. Query
`studio_assets_artifacts` with its `batchId` to inspect candidate targets, then
submit a fresh preview request with explicit `rebinds` covering every affected use.
Targets remain stable across amended previews. No automatic rebind is inferred.
## Compose a scene
Create a `SCENE_BANK` with `outputFormat: "SCENE_TILED_V1"`. A `compose_scene`
mutation supplies exactly four layers. An active layer names its glyph bank,
tileSize, nonnegative parallax factors, width/height and exactly width*height
tiles. Active tiles name the stable `{bank, artifactId}` returned by the artifact
query, plus `paletteId`, `flipX` and `flipY`. Inactive tiles use `artifact: null`.
Inactive layers remain present. The shared scene service emits the canonical
request; callers never write the packer request file or invent glyph indices.
A draft scene may exist without accepted composition, but its missing canonical
request still blocks cartridge publication.
## Read the correct budget
Per-bank glyph content and global residency are separate. For each bank type,
inspect existing banks, declared build selection, effective final preloads (with
actual slots and dependencies), and potential dynamic banks. Scene layers and
logical maps do not allocate another bank. A scene's cold glyph dependencies must
be in the pack set; they do not become automatic preloads.
The shipped macOS arm64 profile qualifies 16 glyph and 16 scene preloads with
actual 16/17 process evidence and exact dispatcher/headless/desktop hashes.
Unknown or changed executables never inherit these limits from a version string.
Known excess fails before replacing the previous cartridge. Potential dynamic
excess is a warning, not proof of simultaneous residency. Unqualified builds may
be inspected, but managed headless/desktop starts require a matching known profile
and unchanged qualified cartridge bytes. Sound has no published limit here.
## Declare ownership without executing a generator
`ownership` entries name owner, an existing project-relative `outputPath`, a
human-readable producer, dependency bank identities and `stale`. Query the graph
with `studio_assets_dependencies`. Changes to dependency/output hashes mark an
output stale. This declaration never runs scripts, generators or transitive
regeneration. Regeneration requires explicit internal authoring mutations and a
new reviewed batch.
@@ -0,0 +1,78 @@
# Isolated guest test targets
This independent fixture demonstrates production, life and deliberately failing
life-fail selections without editing production sources or barrels. Support under
tests/support is included only by the declared targets. Assertions call existing
public life functions with ordinary PBS module visibility.
The host structured-test service requires negotiated headless protocol 1.2
log_read. Capability absence must refuse the run before guest execution. Production
build/Play remains independent. Use explicit memory_fresh media; this fixture has
no save image or durability claim. Cartridges without memcard_slots have no card
namespace or boot media choice; the fresh owned process supplies fresh RAM.
Events are emitted across three frames using sdk/log tag 41000. The helper chooses
between complete versioned JSON literals for a boolean predicate. expected/actual
are the predicate booleans, not an invented numeric health observation. Numeric or
other optional details may be omitted; the host retains their availability. Every
assertion has a distinct eventId, name and message. No runtime string formatter,
private access or extra machine budget is assumed.
A pass requires both declared cases, an assertion, explicit suite completion and
no false assertion, native fault, invalid event or log loss. life-fail deliberately
checks health against eight after subtracting three from ten; it must report a
failed assertion while still completing both cases and the suite. A fault or an
empty/incomplete transcript is never an assertion pass.
Use an explicit targetId with studio_build_start. Test artifacts belong to
.studio/test-builds/<targetId>/<buildId>/; production keeps build/. A lost response
is recovered by request/operation lookup, without replaying guest advancement.
## Run through Studio
Open the project Tests workspace, select life or life-fail, Fresh RAM and explicit
frame/time bounds, then Run tests. The same service is available through MCP:
1. After a human grant, acquire the task and call studio_tests_targets.
2. Call studio_tests_start with a unique clientRequestId and the request below.
3. Poll studio_tests_get by the original request/operation identity until
workerTerminated. SUCCEEDED is worker completion; inspect result.verdict for
the test verdict. A deliberately false assertion completes with failed.
4. Read studio_tests_transcript in bounded pages. Queries never advance the guest.
Recover a lost start response with the original identity, without a new run.
```json
{
"targetId": "life",
"maxFrames": 120,
"blockFrames": 1,
"timeoutMs": 30000,
"media": "memory_fresh",
"reopenRunId": null,
"discardUnsaved": false
}
```
Each unique event payload has a contiguous zero-based ordinal. suite_end includes
eventCount, counting every unique event including itself. Duplicate identical
events are idempotent; missing producer events are failures even when native
sequences have no gap. Each complete encoded literal fits 256 UTF-8 bytes and the
example emits at most three events/frame, within the unchanged ten-message app
budget. Ordinary application logs consume the same budget. Historical native
overflow alone is informational; unread gaps and continuity failures reject a run.
## Disposable persistence tests
A project declaring memcard_slots may explicitly use disposable_create. The
service creates its image under .studio/test-runs/<runId>/ and retains the run's
media descriptor/result. For a distinct reader target use disposable_reopen and
the creating run's ID as reopenRunId. The writer process must close before the
reader opens the same image in a new process. Assert readback through the game's
existing public API; commit acceptance alone does not establish readback.
The service never selects the configured/personal image. A native dirty or
pending-data refusal remains visible with runtimeRetained=true; choose an explicit
studio_tests_shutdown discard policy to recover. A failed advance, including
zero completed frames, is not automatically replayed. Keep its native cause and
inspect the original result before any intentional further action. The life
fixture does not test persistence; it makes no save/durability claim.
@@ -0,0 +1,52 @@
{
"name": "isolatedtests",
"version": "1.0.0",
"language": "pbs",
"stdlib": "1",
"target": "Game",
"app_id": 470396923,
"dependencies": [],
"testTargets": {
"schemaVersion": 1,
"targets": [
{
"id": "life",
"entrypoint": "tests/life/main.pbs",
"sourceRoots": [
"src",
"tests/life"
],
"supportRoots": [
"tests/support"
],
"exclusions": [
"src/main.pbs"
],
"cases": [
"damage",
"heal"
],
"logTag": 41000
},
{
"id": "life-fail",
"entrypoint": "tests/life-fail/main.pbs",
"sourceRoots": [
"src",
"tests/life-fail"
],
"supportRoots": [
"tests/support"
],
"exclusions": [
"src/main.pbs"
],
"cases": [
"damage",
"heal"
],
"logTag": 41000
}
]
}
}
@@ -0,0 +1,8 @@
declare global health: int = 10;
fn damage(amount: int) -> void { health = health - amount; }
fn heal(amount: int) -> void {
health = health + amount;
if (health > 10) { health = 10; }
}
fn current() -> int { return health; }
@@ -0,0 +1,3 @@
pub fn damage(amount: int) -> void;
pub fn heal(amount: int) -> void;
pub fn current() -> int;
@@ -0,0 +1,29 @@
import { damage, heal, current } from @isolatedtests:life;
import { emit_event, assert_true } from @isolatedtests:assertions;
declare global phase: int = 0;
[Frame]
fn frame() -> void {
if (phase == 0) {
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":null,\"eventId\":\"suite.start\",\"kind\":\"suite_start\",\"payload\":{\"ordinal\":0}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"damage\",\"eventId\":\"damage.start\",\"kind\":\"case_start\",\"payload\":{\"ordinal\":1}}");
damage(3);
phase = 1;
} else {
if (phase == 1) {
assert_true(41000, current() == 8, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"damage\",\"eventId\":\"damage.assert\",\"kind\":\"assertion\",\"payload\":{\"name\":\"damage predicate\",\"message\":\"Public health predicate\",\"expected\":true,\"actual\":true,\"passed\":true,\"ordinal\":2}}", "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"damage\",\"eventId\":\"damage.assert\",\"kind\":\"assertion\",\"payload\":{\"name\":\"damage predicate\",\"message\":\"Public health predicate\",\"expected\":true,\"actual\":false,\"passed\":false,\"ordinal\":2}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"damage\",\"eventId\":\"damage.end\",\"kind\":\"case_end\",\"payload\":{\"ordinal\":3}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"heal\",\"eventId\":\"heal.start\",\"kind\":\"case_start\",\"payload\":{\"ordinal\":4}}");
heal(99);
phase = 2;
} else {
if (phase == 2) {
assert_true(41000, current() == 10, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"heal\",\"eventId\":\"heal.assert\",\"kind\":\"assertion\",\"payload\":{\"name\":\"heal predicate\",\"message\":\"Public health predicate\",\"expected\":true,\"actual\":true,\"passed\":true,\"ordinal\":5}}", "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"heal\",\"eventId\":\"heal.assert\",\"kind\":\"assertion\",\"payload\":{\"name\":\"heal predicate\",\"message\":\"Public health predicate\",\"expected\":true,\"actual\":false,\"passed\":false,\"ordinal\":5}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"heal\",\"eventId\":\"heal.end\",\"kind\":\"case_end\",\"payload\":{\"ordinal\":6}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":null,\"eventId\":\"suite.end\",\"kind\":\"suite_end\",\"payload\":{\"ordinal\":7,\"eventCount\":8}}");
phase = 3;
}
}
}
}
@@ -0,0 +1,29 @@
import { damage, heal, current } from @isolatedtests:life;
import { emit_event, assert_true } from @isolatedtests:assertions;
declare global phase: int = 0;
[Frame]
fn frame() -> void {
if (phase == 0) {
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":null,\"eventId\":\"suite.start\",\"kind\":\"suite_start\",\"payload\":{\"ordinal\":0}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"damage\",\"eventId\":\"damage.start\",\"kind\":\"case_start\",\"payload\":{\"ordinal\":1}}");
damage(3);
phase = 1;
} else {
if (phase == 1) {
assert_true(41000, current() == 7, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"damage\",\"eventId\":\"damage.assert\",\"kind\":\"assertion\",\"payload\":{\"name\":\"damage predicate\",\"message\":\"Public health predicate\",\"expected\":true,\"actual\":true,\"passed\":true,\"ordinal\":2}}", "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"damage\",\"eventId\":\"damage.assert\",\"kind\":\"assertion\",\"payload\":{\"name\":\"damage predicate\",\"message\":\"Public health predicate\",\"expected\":true,\"actual\":false,\"passed\":false,\"ordinal\":2}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"damage\",\"eventId\":\"damage.end\",\"kind\":\"case_end\",\"payload\":{\"ordinal\":3}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"heal\",\"eventId\":\"heal.start\",\"kind\":\"case_start\",\"payload\":{\"ordinal\":4}}");
heal(99);
phase = 2;
} else {
if (phase == 2) {
assert_true(41000, current() == 10, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"heal\",\"eventId\":\"heal.assert\",\"kind\":\"assertion\",\"payload\":{\"name\":\"heal predicate\",\"message\":\"Public health predicate\",\"expected\":true,\"actual\":true,\"passed\":true,\"ordinal\":5}}", "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"heal\",\"eventId\":\"heal.assert\",\"kind\":\"assertion\",\"payload\":{\"name\":\"heal predicate\",\"message\":\"Public health predicate\",\"expected\":true,\"actual\":false,\"passed\":false,\"ordinal\":5}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":\"heal\",\"eventId\":\"heal.end\",\"kind\":\"case_end\",\"payload\":{\"ordinal\":6}}");
emit_event(41000, "{\"schemaVersion\":1,\"suiteId\":\"life\",\"caseId\":null,\"eventId\":\"suite.end\",\"kind\":\"suite_end\",\"payload\":{\"ordinal\":7,\"eventCount\":8}}");
phase = 3;
}
}
}
}
@@ -0,0 +1,8 @@
import { Log } from @sdk:log;
// Callers supply complete versioned JSON literals; no runtime string formatter is assumed.
fn emit_event(tag: int, json: str) -> void { Log.info(tag, json); }
fn assert_true(tag: int, condition: bool, passed_json: str, failed_json: str) -> void {
if (condition) { Log.info(tag, passed_json); }
else { Log.info(tag, failed_json); }
}
@@ -0,0 +1,2 @@
pub fn emit_event(tag: int, json: str) -> void;
pub fn assert_true(tag: int, condition: bool, passed_json: str, failed_json: str) -> void;