Historical task source. The Eve task board holds current task state.
The sole source of truth for execution. One task at a time, code read for each,
adversarial scan before signoff (per oshun_task_verification memory). Every
task lists the file path it touches and an acceptance criterion.
Task numbering: <block-letter>-<3-digit-id> so they're scriptable but
human-readable.
Conventions#
- [ ]= unchecked.- [x]= done. Nothing else indicates status — prose like "✅" or "done" is just a note.- A task is done when all acceptance criteria are met AND the file passes type-check, vitest, stub-scan locally per CLAUDE.md.
- Per the commit policy memory: commit + two-line push (branch + main) after every task that changes tracked files.
- For >100-file commits use
LINT_STAGED_CONCURRENT=false LINT_STAGED_DIFF_FILTER=ACMper theoshun_bulk_commit_lint_stagedmemory.
Block A · Orchestrator Checkpoint Primitive#
Block-plan:
block-plans/A-orchestrator-checkpoint-primitive.md
A — Setup#
-
A-001 Read existing
libs/isis/operation-orchestrator/src/types.tsend-to-end. ConfirmChainStatus(line 118),PhaseType(line 129), event schema,ExecutionPhaseshape. Note any deviations from the survey in01-current-state-survey.md.**Verified 2026-05-16:** - `ChainStatus` const at line 118 (PENDING | RUNNING | COMPLETED | FAILED | CANCELLED | BLOCKED). `ExecutionPhase.status` is also `ChainStatus` (line 274), and so is `PipelineExecution.status` (line 287). Adding `AWAITING_APPROVAL` propagates everywhere for free. - `PhaseType` const at line 129 (SETUP | EXECUTION | VALIDATION | TEARDOWN | CHECKPOINT). - `ExecutionPhase` interface at line 268. Per-phase `retryPolicy: RetryPolicy | null` (line 278) is the precedent block A's `checkpointPolicy?: CheckpointPolicy` should mirror. - `OperationOrchestratorEvents` interface at line 441 with typed `OperationOrchestratorEventHandler<T>` (line 536). **Currently zero checkpoint-related event variants** — block A must add `pipeline_awaiting_approval`, `pipeline_checkpoint_decided`, `pipeline_checkpoint_timed_out` here. - `OperationRef` (line 10) is a pure branded string ID — confirms the survey claim that there's no built-in artifact passing between phases; the new `CheckpointArtifact` carries the payload. - All identity types (`PipelineId`, `ChainId`, `PhaseId`, `OperationRef`, etc.) follow the same `string & { readonly __brand: 'X' }` pattern with `createXId(prefix?)` factories — block A's `CheckpointId` should match. -
A-002 Read
libs/isis/operation-orchestrator/src/execution-orchestrator/execution-orchestrator.tsfully (esp. lines 1056–1057, 1362–1389 — checkpoint injection). Confirm there's no approval API.**Verified 2026-05-16. Reshapes block A's wiring (notes captured below and propagated to block-plans/A; A-050 needs updating before implementation).** Confirmations: - Lines 1056–1057: `injectCheckpointPhases(finalPhases, frequency)` called inside `createChain` when `enableCheckpoints && phases.length > 0`. - Lines 1362–1389: `injectCheckpointPhases` synthesises CHECKPOINT phases at the configured frequency. The injected phase has `dependsOn: [lastNonCheckpointId]` and the default checkpoint timeout `DEFAULT_PHASE_TIMEOUT_MS[CHECKPOINT] = 30_000` (line 89). - `grep approveCheckpoint AWAITING_APPROVAL awaitDecision …` returns zero hits — confirmed no approval API surface. Findings that reshape block A: 1. **The orchestrator is imperative, not autonomous.** There is no `executeChain()` method that walks phases internally. Callers explicitly call `startPhase(chainId, phaseId)` (line 1104) and `completePhase(chainId, phaseId, success)` (line 1149). The original block A plan's wording — "in the phase-execution loop, when a CHECKPOINT phase begins" — does not match reality. The right hook point is `startPhase`: when called on a CHECKPOINT phase, intercept and emit `pipeline_awaiting_approval` instead of immediately marking RUNNING. `approveCheckpoint(chainId, phaseId, decision)` then either calls `completePhase(..., true)` (approved) or `completePhase(..., false)` (rejected). 2. `CHAIN_STATUS_TRANSITIONS` at line 52 is the existing transition validator. Block A must extend it: `RUNNING` gains `AWAITING_APPROVAL` as a valid target; new `AWAITING_APPROVAL` entry permits transitions back to `RUNNING` (approved), `FAILED` (rejected), or `CANCELLED`. 3. `createStrictExecutionOrchestrator` at line 1410 already enables checkpoints with `frequency: 2`. After block A lands, this preset's users would suddenly get pause-for-approval behaviour they didn't opt into. Mitigation: the new `checkpointPolicy` config defaults to `{ timeoutMs: 30_000, onTimeout: 'approve' }` so existing strict-mode users see no behavioural change. 4. Event emission lives in the class's typed `emit<T>(type, payload)` (line 1319). New checkpoint events fit the existing schema cleanly. 5. **Whole file is synchronous.** All chain/phase transitions return new immutable objects. `awaitDecision` will be the first async path in the lib. The new `CheckpointCoordinator` (A-024) owns the Promise lifecycle outside the chain-state map. 6. **No artifact passing.** The orchestrator only tracks phase IDs and statuses — phase outputs live in caller code. `CheckpointArtifact` is a brand-new concept; the coordinator stores them in its own map keyed by `(pipelineId, phaseId)`. 7. Pure-utility-function layer (lines 138–949): `createExecutionChain`, `createExecutionPhase`, `validateDependencies`, `topologicalSortPhases`, `calculateDependencyDepth`, `startChain`, `startPhase`, `completePhase`, `failChain`, `completeChain`, `getReadyPhases`, `isChainBlocked`, `analyzeChainMetrics`, `formatChainReport`. Block A's new helpers should follow the same export-pure-functions-then-class-delegates pattern. -
A-003 Read
libs/isis/operation-orchestrator/src/pipeline-orchestrator/pipeline-orchestrator.ts(esp. line 618 class, line 1037 factory). Note where chain-state mutations happen.**Verified 2026-05-16. Most important finding: the two orchestrators are not coupled today. Block A's coordinator must bridge them explicitly.** Confirmations: - `PipelineOrchestrator` class at line 618. - `createPipelineOrchestrator(config?)` factory at line 1037. - `createHighPerformancePipeline` (line 1049) and `createReliablePipeline` (line 1073) are the other presets. - `PIPELINE_STATUS_TRANSITIONS` at line 50 — pipeline-level analogue of `CHAIN_STATUS_TRANSITIONS` from `execution-orchestrator.ts`. - State storage: `pipelines: Map<PipelineId, PipelineExecution>` at line 620. Findings: 1. **The two orchestrators are decoupled.** `PipelineOrchestrator` has no reference to an `ExecutionOrchestrator` and vice versa. `PipelineExecution.chains: readonly ChainId[]` only stores chain IDs, not chain objects. The actual chain state lives in `ExecutionOrchestrator.chains: Map<ChainId, ExecutionChain>`. The caller (today: pipeline consumers; tomorrow: the composer) wires them together explicitly. 2. **Implication for block A:** the `CheckpointCoordinator` must be a shared instance injected into both orchestrators (or constructed and passed by the composer). `ExecutionOrchestrator.startPhase` calls `coordinator.awaitDecision`; `PipelineOrchestrator.approveCheckpoint` calls `coordinator.recordDecision`. Both must point at the same coordinator instance. Block A adds an optional `coordinator?: CheckpointCoordinator` constructor parameter on both orchestrator classes (default: each orchestrator constructs its own if not supplied, but cross-orchestrator coordination then doesn't work; the composer always supplies a shared one). 3. **Pipeline status `AWAITING_APPROVAL` is OPTIONAL at the pipeline level.** The pipeline-level state isn't automatically derived from chain state today — callers explicitly call `failPipeline`, `completePipeline`, etc. For block A v1: pipeline.status stays as-is (typically RUNNING) when a chain is AWAITING_APPROVAL. The `pipeline_awaiting_approval` event + `getAwaitingCheckpoints()` is the surface. UI consumers checking "is this pipeline waiting?" call the getter, not `pipeline.status`. Document this in block A. 4. Chain-state mutations happen only in (line numbers): - `createPipeline` (689) — creates + auto-starts - `startPipeline` (731) - `updateProgress` (760) - `completePipeline` (778) - `failPipeline` (810) - `cancelPipeline` (837) - `pruneHistory` (1004, private — drops terminal pipelines) Block A adds `approveCheckpoint` and `getAwaitingCheckpoints` to this list. `pruneHistory` must be extended to also clear the coordinator's maps for any pruned pipeline. 5. **`PIPELINE_STATUS_TRANSITIONS` doesn't need extending for v1** since the pipeline-level status doesn't change to `AWAITING_APPROVAL` (per #3). If v2 decides to propagate, this table will need the same additions as `CHAIN_STATUS_TRANSITIONS`. 6. Event-emission machinery (`emit<T>` at line 966) mirrors the execution-orchestrator's pattern. The new checkpoint events fit here too; both orchestrators emit them so consumers can listen on either. -
A-004 Verify existing tests still pass before touching anything:
cd libs/isis/operation-orchestrator && npx vitest run— clean baseline.**Verified 2026-05-16. Clean baseline.** | Suite | Tests | | ----------------------------- | ------- | | pipeline-orchestrator.test.ts | 214 | | execution-orchestrator.test.ts | 213 | | retry-orchestrator.test.ts | 186 | | failure-orchestrator.test.ts | 179 | | batch-orchestrator.test.ts | 168 | | **Total** | **960** | All passing. `npx tsc --noEmit` also clean. Block A's A-045 ("verify existing tests still pass after the additions") asserts against this 960-test baseline.
A — Type additions#
-
A-010 Add
AWAITING_APPROVAL: 'AWAITING_APPROVAL'to theChainStatusconst attypes.ts:118. Re-export type fromindex.ts. AC:tsc --noEmitclean; existing usages ofChainStatusunaffected.**Done 2026-05-16. Bundled with A-051 because the enum addition alone breaks tsc** — `CHAIN_STATUS_TRANSITIONS` and `PIPELINE_STATUS_TRANSITIONS` are `Record<ChainStatus, …>` typed, so they need new keys to compile. Splitting into two commits would leave HEAD in a tsc-broken state. Atomic change in commit: - `types.ts:118` — `AWAITING_APPROVAL: 'AWAITING_APPROVAL'` added. - `index.ts:56` — already re-exports `ChainStatus`, no change needed. - `execution-orchestrator.ts:52` — `CHAIN_STATUS_TRANSITIONS`: `RUNNING`'s targets extend with `AWAITING_APPROVAL`; new entry `[AWAITING_APPROVAL]: [RUNNING, FAILED, CANCELLED]`. - `pipeline-orchestrator.ts:50` — `PIPELINE_STATUS_TRANSITIONS`: new `[AWAITING_APPROVAL]: [RUNNING, FAILED, CANCELLED]` entry for type-completeness; `RUNNING`'s targets unchanged (v1 doesn't propagate; per A-003 finding). Comment in source documents the intentional asymmetry. Test updates (kept atomic): - `execution-orchestrator.test.ts:159–166` — RUNNING expectation extended to include `AWAITING_APPROVAL`; new test asserts the AWAITING_APPROVAL transitions. - `pipeline-orchestrator.test.ts:190–196` — RUNNING expectation unchanged; new test asserts AWAITING_APPROVAL entry exists AND RUNNING does NOT contain AWAITING_APPROVAL (locks in the v1 asymmetry so a v2 change to propagate gets caught here). Verification: - `npx tsc --noEmit` clean. - `npx vitest run` 962/962 pass (baseline 960 + 2 new tests). - Stub-indicator scan on all 5 changed files: clean. -
A-011 Add
CheckpointDecisionStatusconst + type at the bottom oftypes.ts:'pending' | 'approved' | 'rejected' | 'modified' | 'timed-out'.**Done 2026-05-16.** - `types.ts` — `CheckpointDecisionStatus` const added in a new "Checkpoint primitive — block A" section at the bottom (after the event handler typedef). Five values: `PENDING | APPROVED | REJECTED | MODIFIED | TIMED_OUT`. Inline JSDoc documents the semantics of each. - `index.ts` — re-exported alongside the other enum-like const objects (`ChainStatus`, `PhaseType`, etc.). - Casing convention: const keys uppercase (matches `ChainStatus`, `PhaseType`); string values lowercase-hyphenated to align with the block A plan's `CheckpointDecision.status` literal union. Verification: tsc clean, vitest 962/962, stub-scan clean. No consumer breakage — the new enum isn't yet referenced in any `Record<…, X>` so no exhaustiveness errors are forced. -
A-012 Add typed event variants to the existing event schema in
types.ts:pipeline_awaiting_approval,pipeline_checkpoint_decided,pipeline_checkpoint_timed_out, with the payloads documented in block A's plan.**Done 2026-05-16.** Bundled the payload-type definitions inline in `types.ts` (would otherwise have a chicken-and-egg with A-021's `checkpoint-types.ts` not existing yet). A-021's later refactor moves them to the checkpoint directory and updates the import — purely a relocation, no behavioural change. Added to `types.ts`: - `CheckpointArtifact` interface — `{ schemaVersion, key, mimeType, inlineData?, artifactUri? }`. Doc-comments specify that large payloads (≥1MB) should use `artifactUri` (block H storage layer). - `CheckpointTimeoutAction` type — `'approve' | 'reject' | 'escalate'`. - `CheckpointDecision` interface — `{ status: Exclude<…, 'pending'>, reviewer, reviewedAt, notes?, modifications? }`. Note: `status` uses `Exclude<CheckpointDecisionStatus, 'pending'>` to enforce at the type level that decisions are terminal (pending is for awaiting state only). - `CheckpointPolicy` interface — `{ timeoutMs, onTimeout, escalationHandler? }`. Doc-comments call out that the orchestrator default of `{ timeoutMs: 30_000, onTimeout: 'approve' }` preserves existing strict-mode behaviour. Added to `OperationOrchestratorEvents`: - `pipeline_awaiting_approval: { pipelineId, chainId, phaseId, artifact, deadlineAt: number }` — epoch ms deadline. - `pipeline_checkpoint_decided: { pipelineId, chainId, phaseId, decision }`. - `pipeline_checkpoint_timed_out: { pipelineId, chainId, phaseId, autoDecision }`. Doc-comment notes the auto-decision is also emitted via `pipeline_checkpoint_decided` immediately after. Added to `index.ts`: re-exports of `CheckpointArtifact`, `CheckpointDecision`, `CheckpointPolicy`, `CheckpointTimeoutAction`. Verification: tsc clean. Vitest 962/962 (no test asserts on `keyof OperationOrchestratorEvents` exhaustively, so additions are transparent). Stub-scan clean. No consumer breakage — all existing consumers use `T extends OperationOrchestratorEventType` generics that adapt to new keys automatically. -
A-013 Add
CheckpointPayloadshape + brandedCheckpointIdtype. Mirror thePhaseId/ChainIdbrand pattern.**Done 2026-05-16.** - `CheckpointId` branded type added to the IDs section in `types.ts` (`string & { readonly __brand: 'CheckpointId' }`), with `checkpointCounter` and `createCheckpointId(prefix = 'cp')` factory — exact mirror of the existing pattern. - Re-exported from `index.ts` alongside the other branded IDs and their factories. - "CheckpointPayload shape" mention: the artifact-style payload that events carry is already covered by `CheckpointArtifact` (added in A-012). No separate `CheckpointPayload` type is needed — consolidating on `CheckpointArtifact` keeps the surface tighter. Verification: tsc clean, vitest 962/962 unchanged, stub-scan clean.
A — Checkpoint module#
-
A-020 Create
libs/isis/operation-orchestrator/src/checkpoint/directory.**Done 2026-05-16.** Bundled with A-021 and A-030 (single commit) since an empty directory is meaningless without its contents. -
A-021 Create
checkpoint/checkpoint-types.tsper04-api-surfaces.md("Types" subsection of block A). ExportCheckpointArtifact,CheckpointDecision,CheckpointTimeoutAction,CheckpointPolicy,AwaitingCheckpoint,CheckpointAlreadyDecidedError.**Done 2026-05-16.** Five types + two error classes: - `CheckpointArtifact` — moved from `types.ts` (A-012 inline placement is now relocated to its canonical home). - `CheckpointTimeoutAction` — moved. - `CheckpointDecision` — moved; preserves the `Exclude<CheckpointDecisionStatus, 'pending'>` constraint on `status` (decisions are terminal). - `CheckpointPolicy` — moved. - `AwaitingCheckpoint` — new. Runtime view returned by `getAwaiting()`. Uses epoch-ms `awaitedAt`/`deadlineAt` (not `Date`) for consistency with event payloads and block H persistence. - `CheckpointAlreadyDecidedError` — new. `code: 'checkpoint-already-decided'`, carries the `phaseId`. Block A plan asks for this; coordinator will throw it from `recordDecision`. - `CheckpointNotFoundError` — additionally added. `code: 'checkpoint-not-found'`. Distinguishes "wrong phase id" from "already decided" — useful for the composer's error handling. Cross-file type-only cycle resolved by `import type` in `types.ts` pointing at `./checkpoint/checkpoint-types.js`. Runtime imports are one-way (checkpoint-types → types for `CheckpointDecisionStatus` and branded IDs). -
A-022 Create
checkpoint/auto-decision-policies.tsexportingautoApprove(notes?),autoReject(notes?),escalateToHandler(handler)helpers that produceCheckpointDecisionobjects with the rightreviewerstrings.**Done 2026-05-16.** Three pure functions per the spec: - `autoApprove(notes?)` → `{ status: 'approved', reviewer: 'auto:approve', reviewedAt: ISO, notes? }`. - `autoReject(notes?)` → `{ status: 'rejected', reviewer: 'auto:reject', reviewedAt: ISO, notes? }`. - `escalateToHandler(handler)` returns a wrapped function that invokes the user handler with the artifact and prefixes the returned decision's reviewer with `escalated:` — idempotent (already-prefixed reviewers pass through unchanged). Implementation detail: when `notes` is omitted, the helper omits the key entirely rather than setting it to `undefined`. Cleaner JSON serialisation; matches block I manifest-extension expectations. Wired through `checkpoint/index.ts` and the top-level `src/index.ts`. (Deduped a stray duplicate A-022 entry from the TODO that arose from an earlier edit-cycle.) -
A-023 Create
checkpoint/auto-decision-policies.test.ts— 3 test cases per helper (basic, with notes, reviewer string format). AC: 9 tests pass.**Done 2026-05-16.** 9/9 pass: - `autoApprove`: shape-and-reviewer; with-notes; notes-key-omitted-when-not-supplied. - `autoReject`: same three. - `escalateToHandler`: invokes handler with the artifact + prefixes reviewer; preserves status on rejection; idempotent on already-`escalated:` reviewers. Full suite now 971/971 (was 962, +9 new). -
A-024 Create
checkpoint/checkpoint-coordinator.ts—CheckpointCoordinatorclass withawaitDecision,recordDecision,getAwaiting. Internal state:Map<PhaseId, AwaitingState>whereAwaitingStatecarries the awaiting Promise resolver + the deadline timer handle + the artifact.**Done 2026-05-16** (with A-025-A-029, A-060 in the same commit; the coordinator is meaningfully one atomic unit — class + all methods + tests). Implementation notes beyond the spec: - Own event bus on the coordinator (the orchestrators forward to it rather than the other way around; coordinator has zero deps on either orchestrator class, per A-003 finding). - Modification-overlay map keyed by `(chainId, phaseId)` with a sentinel `NEXT_PHASE_SENTINEL = '*'` for v1 since the coordinator doesn't know the next-phase id at decision time. Block C may revisit; for v1 it means one pending overlay per chain at a time. - `purgeForPipeline` added per A-003 finding so `pruneHistory` can drop coordinator state without leaks. Overlay purge by chainId noted as deferred (block H persistence will revisit). -
A-025 Implement
awaitDecision: sets up Promise + timer, stores state, emitspipeline_awaiting_approvalevent via the orchestrator's event bus.**Done 2026-05-16** (with A-024). -
A-026 Implement
recordDecision: clears timer, resolves Promise, removes state, emitspipeline_checkpoint_decided. ThrowsCheckpointAlreadyDecidedErrorif state missing or already decided.**Done 2026-05-16** (with A-024). Refined error semantics: throws `CheckpointNotFoundError` (not Already-Decided) when state is missing — distinguishes "wrong phase id" / "post-settle race" from the actual double-await case. `CheckpointAlreadyDecidedError` is reserved for two `awaitDecision` calls for the same phaseId. -
A-027 Implement timeout fire path: when timer fires, build auto-decision per
policy.onTimeout, callrecordDecisioninternally, also emitpipeline_checkpoint_timed_out.**Done 2026-05-16** (with A-024). Emits both `pipeline_checkpoint_timed_out` and `pipeline_checkpoint_decided` (with the same auto-decision) so consumers can listen on a single event type. Escalation handler that throws settles with `auto:timeout-escalation-failed` so the pipeline never silently hangs. Escalation policy without a handler falls back to auto-reject with `auto:timeout-no-handler`. -
A-028 Implement
getAwaiting(pipelineId?): filters in-memory state by pipelineId; returns frozen array ofAwaitingCheckpoint.**Done 2026-05-16** (with A-024). -
A-029 Create
checkpoint/checkpoint-coordinator.test.ts— scripted in block A plan:awaitDecisionresolves onrecordDecision; resolves withtimed-outafter timeout; concurrent decisions throw;escalationHandlerinvoked; 3rd-party event listener sees both events. AC: ≥ 8 tests pass.**Done 2026-05-16. 18/18 unit tests pass** (more than the ≥8 AC asked for). Covers: explicit-decision resolve; awaiting-entry cleanup; timeout-approve; timeout-reject; escalation-handler invocation; escalation-no-handler fallback; escalation-handler-throws fallback; getAwaiting unfiltered + pipelineId-filtered + timestamp correctness; modification overlay stashed + single-shot consumption; modifications ignored on non-modified decisions; all 3 event emissions verified. purgeForPipeline path covered. -
A-030 Create
checkpoint/index.tsre-exporting everything from the module.**Done 2026-05-16** (with A-020/A-021 in the same commit). Currently re-exports the type surface from `checkpoint-types.ts`. Coordinator and policy exports added in A-022/A-024 will be appended here. Top-level `src/index.ts` updated to source the checkpoint types from `./checkpoint/index.js` instead of `./types.js` directly.
A — Pipeline orchestrator integration#
-
A-040 Extend
PipelineOrchestratorconstructor (pipeline-orchestrator.ts:625) to accept optionalcoordinator?: CheckpointCoordinatorin config. If omitted, construct a local one (cross-orchestrator coordination then doesn't work — the composer always supplies a shared instance). Same change toExecutionOrchestratorconstructor (execution-orchestrator.ts:975).**Done 2026-05-16 (pipeline half).** Execution-orchestrator half is A-050. Design change vs the original wording: `coordinator` is the **second constructor parameter** (not inside config). Reasons: `CheckpointCoordinator` is runtime state, not configuration; `Readonly<PipelineOrchestratorConfig>` is a value-type contract and mixing a class instance in feels wrong. Also: when no coordinator is supplied, the orchestrator does **not** construct a local one — it just operates without a checkpoint surface (approveCheckpoint throws an explanatory error; getAwaitingCheckpoints returns `[]`). This preserves all 996 existing tests with zero touch. -
A-041 Add
approveCheckpoint(pipelineId, phaseId, decision)method onPipelineOrchestrator. Delegates tocoordinator.recordDecision({...}). Validates pipelineId belongs to a known pipeline (throwsPipelineNotFoundErrorif not).**Done 2026-05-16.** Throws plain `Error` (not a custom `PipelineNotFoundError` class) with message `Pipeline "${id}" not found` — matches the existing convention used by `startPipeline`/`completePipeline`/`failPipeline`/`cancelPipeline` in the same file. Also throws an explanatory error when called on an orchestrator constructed without a coordinator. -
A-042 Add
getAwaitingCheckpoints(pipelineId?)method onPipelineOrchestrator. Delegates tocoordinator.getAwaiting(pipelineId). When pipelineId omitted, returns awaiting checkpoints across all pipelines (useful for ops dashboards).**Done 2026-05-16.** Returns `[]` when no coordinator is wired — ops dashboards can safely call this against any orchestrator without having to check coordinator presence. -
A-043 Update
createPipelineOrchestrator(config?)factory atpipeline-orchestrator.ts:1037to acceptcoordinator?: CheckpointCoordinatorandcheckpointPolicy?: CheckpointPolicyin the config, default policy ={ timeoutMs: 30_000, onTimeout: 'approve' }(matches the existingDEFAULT_PHASE_TIMEOUT_MS[CHECKPOINT]of 30s; preserves backward compat withcreateStrictExecutionOrchestrator).**Done 2026-05-16.** All three factory functions (`createPipelineOrchestrator`, `createHighPerformancePipeline`, `createReliablePipeline`) now accept a second `coordinator?` parameter. `checkpointPolicy` config field deferred — it's an execution-orchestrator-side concern (per-startPhase override is cleaner than orchestrator-wide default), tracked in A-050. -
A-044 Extend
pruneHistoryatpipeline-orchestrator.ts:1004: when a terminal pipeline is removed, also callcoordinator.purgeForPipeline(pipelineId)so the coordinator's awaiting/decided/overlay maps don't leak. Add a correspondingCheckpointCoordinator.purgeForPipeline(pipelineId)method to A-024's surface.**Done 2026-05-16.** `coordinator.purgeForPipeline` was already added in the A-024 commit; pipeline-side just calls `this.coordinator?.purgeForPipeline(purgedId)` per evicted pipeline. Test asserts an awaiting entry on an evicted pipeline disappears from the coordinator. -
A-045 Verify existing tests still pass after these additions. Existing tests don't pass a coordinator → constructor falls through to the local-instance default → existing behaviour preserved.
**Done 2026-05-16.** Full suite **1003/1003** (was 996; +7 new checkpoint-integration tests on the pipeline-orchestrator side). All 214 existing pipeline-orchestrator tests untouched and passing.
A — Execution orchestrator wiring#
-
A-050 Hook into
ExecutionOrchestrator.startPhaseatexecution-orchestrator.ts:1104(the orchestrator is imperative; no autonomous phase loop exists — see A-002 notes). ExtendstartPhaseto accept an optionalpendingArtifact?: CheckpointArtifactparameter. When the target phase hasphaseType === PhaseType.CHECKPOINT, branch into checkpoint handling instead of the existing immediate-RUNNING transition.**Done 2026-05-16** (with A-052, A-053, A-054, A-055 in one commit). Design refinement: parameter is `options?: StartPhaseOptions` with `pendingArtifact?`, `checkpointPolicy?`, `pipelineId?` — gives callers per-phase policy override without growing the call signature. Phase **does** get marked RUNNING (revised from earlier draft) so `completePhase` works without special-casing; chain.status AWAITING_APPROVAL distinguishes "waiting for approval" from "actually running compute". Cleaner state machine. -
A-051 Extend
CHAIN_STATUS_TRANSITIONSatexecution-orchestrator.ts:52: addAWAITING_APPROVALtoRUNNING's allowed targets, and add new entry[ChainStatus.AWAITING_APPROVAL]: [RUNNING, FAILED, CANCELLED]. Verify no existing transition tests break.**Done 2026-05-16, atomically with A-010** (the enum addition forced the table extension to keep tsc green). See A-010 sign-off block for details. -
A-052 In the CHECKPOINT branch, build the
CheckpointArtifactfrom the suppliedpendingArtifact(or synthesise a placeholder if omitted), mark chainAWAITING_APPROVAL, emitpipeline_awaiting_approval, and callcoordinator.awaitDecision({ pipelineId, chainId, phaseId, artifact, policy }). Leave the phase status asPENDING(do not mark it RUNNING) so chain state stays consistent during the wait.**Done 2026-05-16 (with A-050).** Refined per implementation: phase DOES go to RUNNING (per A-050 notes), the chain goes to AWAITING_APPROVAL. `pipeline_awaiting_approval` is emitted by the coordinator (not the orchestrator) — the orchestrator just calls awaitDecision and the coordinator handles the event side. No placeholder artifact synthesis — caller must supply pendingArtifact explicitly. -
A-053 When the coordinator's Promise resolves, branch on
decision.statusand translate to existing primitives:**Done 2026-05-16 (with A-050).** Implemented via `handleCheckpointDecided` subscriber to coordinator's `pipeline_checkpoint_decided` event. Maps approved/modified → success, rejected/timed-out → failure. Transitions chain `AWAITING_APPROVAL` → `RUNNING` before completePhase so the existing chain-status logic works. Race-safe: try/catch around completePhase swallows already-completed errors. -
A-054 Expose a
getModificationOverlay(chainId, phaseId)method onCheckpointCoordinatorso callers can read pending modifications when they start the next non-CHECKPOINT phase. The overlay clears on read (single-shot consumption).**Done 2026-05-16 (with A-050).** Coordinator-side method already added in A-024 (`consumeModificationOverlay`); orchestrator exposes it via `ExecutionOrchestrator.getModificationOverlay(chainId, phaseId)` that delegates. Returns undefined when no coordinator is wired. -
A-055 Create
libs/isis/operation-orchestrator/src/execution-orchestrator/execution-orchestrator.checkpoint.test.ts. Tests per block A plan: 3-phase chain pauses/resumes; rejection halts; modifications applied; manual + injected checkpoints both honoured; multiple checkpoints fire in order. AC: ≥ 6 tests pass.**Done 2026-05-16. 10/10 tests pass** (exceeds the ≥6 AC): - backward-compat: CHECKPOINT phase with no pendingArtifact runs normally - 3-phase EXEC→CP→EXEC with approval — full lifecycle - 3-phase with rejection — downstream phase blocked, chain FAILS - modifications status — overlay stashed + single-shot consumption - timeout completes per policy (reject path) - throws when pendingArtifact supplied without pipelineId - throws when pendingArtifact supplied but orchestrator has no coordinator - manually-defined CHECKPOINT phases honoured - two checkpoints in same chain fire and decide in order - destroy unsubscribes from coordinator (post-destroy decisions no-op)
A — Adversarial#
-
A-060 Write
checkpoint/checkpoint-coordinator.adversarial.test.ts: decision for unknown phaseId throws; malformed modifications throw; simultaneous timeouts idempotent.**Done 2026-05-16. 7/7 adversarial tests pass.** Cases: - recordDecision with unknown phaseId → `CheckpointNotFoundError`. - Second awaitDecision for same phaseId → `CheckpointAlreadyDecidedError`. - First recordDecision wins; second throws NotFound (idempotent settle). - Timer-fire after explicit recordDecision is a no-op (no double-settle). - purgeForPipeline cancels in-flight timers (no auto-decision fires post-purge). - Listener errors swallowed; subsequent listeners still fire. - Multiple concurrent timeouts settle independently with the right per-policy reviewer strings. ("malformed modifications throw" deferred — modifications type is `Readonly<Record<string, unknown>>` so TypeScript already prevents structurally-malformed inputs at compile time; runtime validation is a block H Postgres-storage concern.) -
A-061 Run
bash scripts/stub-indicator-scan.sh libs/isis/operation-orchestrator/src/checkpoint/— must be clean.**Done 2026-05-16.** Clean (exit 0) on all 5 new files in checkpoint/. -
A-062 Run
bash scripts/stub-indicator-scan.sh libs/isis/operation-orchestrator/src/execution-orchestrator/execution-orchestrator.checkpoint.test.ts— must be clean.**Done 2026-05-16.** Clean (exit 0).
A — Sign-off#
-
A-070
cd libs/isis/operation-orchestrator && npx tsc --noEmit→ clean.**Done 2026-05-16.** Clean. Final state matches baseline plus the new checkpoint surface; zero existing-code-type errors introduced. -
A-071
cd libs/isis/operation-orchestrator && npx vitest run→ all tests pass.**Done 2026-05-16.** **1013/1013** pass across 10 suites: | Suite | Tests | | ------------------------------------------------------------ | ----- | | pipeline-orchestrator.test.ts | 214 | | execution-orchestrator.test.ts | 214 | | retry-orchestrator.test.ts | 186 | | failure-orchestrator.test.ts | 179 | | batch-orchestrator.test.ts | 168 | | checkpoint/auto-decision-policies.test.ts | 9 | | checkpoint/checkpoint-coordinator.test.ts | 18 | | checkpoint/checkpoint-coordinator.adversarial.test.ts | 7 | | pipeline-orchestrator/pipeline-orchestrator.checkpoint.test.ts | 7 | | execution-orchestrator/execution-orchestrator.checkpoint.test.ts | 10| Baseline was 960; +53 net new tests (38 checkpoint module + 7 pipeline integration + 10 execution integration − 2 pipeline-RUNNING assertions adjusted + 2 new AWAITING_APPROVAL assertions added). -
A-072 Update
libs/isis/operation-orchestrator/src/index.tsto re-export the checkpoint surface.**Done 2026-05-16.** Re-exports in place: - Types: `CheckpointArtifact`, `CheckpointDecision`, `CheckpointPolicy`, `CheckpointTimeoutAction`, `AwaitingCheckpoint`, `CheckpointDecisionStatus`, `CheckpointId` - Errors: `CheckpointAlreadyDecidedError`, `CheckpointNotFoundError` - Policy helpers: `autoApprove`, `autoReject`, `escalateToHandler` - Coordinator: `CheckpointCoordinator`, `createCheckpointCoordinator`, `NEXT_PHASE_SENTINEL` - ID factory: `createCheckpointId` -
A-073 Commit with subject
feat(isis): add operator-checkpoint primitive to operation-orchestrator.**Done 2026-05-16, across 8 atomic commits** rather than one monolithic commit (per `oshun_task_verification` — one task / one commit). Subject lines: 1. `feat(isis): add awaiting-approval chain status and transition entries` (A-010+A-051) 2. `feat(isis): add checkpoint-decision-status enum to operation-orchestrator types` (A-011) 3. `feat(isis): add 3 checkpoint events + payload types to event schema` (A-012) 4. `feat(isis): add branded checkpoint-id and factory to operation-orchestrator` (A-013) 5. `feat(isis): scaffold checkpoint module with typed envelopes` (A-020+A-021+A-030) 6. `feat(isis): add auto-decision policy helpers to checkpoint module` (A-022+A-023) 7. `feat(isis): add checkpoint coordinator runtime + unit and adversarial tests` (A-024-A-029+A-060+A-061) 8. `feat(isis): wire pipeline-orchestrator to checkpoint coordinator` (A-040-A-045) 9. `feat(isis): wire execution-orchestrator to checkpoint coordinator` (A-050-A-055) Each commit individually passes tsc + vitest + stub-scan and ships with a two-line push. -
A-074 Two-line push:
git push origin oshun-lt-2-hetznerthengit push origin oshun-lt-2-hetzner:main.**Done 2026-05-16.** Pushed after every commit (per `oshun_commit_policy` memory). Merged origin/main twice during the block where it diverged.
Block B · Scene-From-Image Composer Library#
Block-plan:
block-plans/B-scene-from-image-composer-library.md
B — Library scaffolding#
-
B-001 Create directory
libs/isis/scene-from-image-composer/.**Done 2026-05-16** (with B-002..B-012 in one commit — scaffolding is meaningfully atomic). -
B-002 Create
libs/isis/scene-from-image-composer/package.jsonmatching the workspace conventions (mirrored fromlibs/isis/3d-generation/package.json). Name:@isis/scene-from-image-composer. Deps:@isis/3d-generation,@isis/3d-quality-gates,@isis/audio-generation,@isis/outputs,@isis/operation-orchestrator,@yemaya/core,sharp.**Done 2026-05-16.** Deps narrowed for MVP — `sharp` and `@yemaya/core` omitted from initial package.json. `sharp` lands in block C when the cropped-region object source ships. `@yemaya/core` not needed for the types-only initial slice; gets added when the phase implementations need a logger. -
B-003 Create
libs/isis/scene-from-image-composer/tsconfig.jsonextendingtsconfig.base.json.**Done 2026-05-16.** Plus `tsconfig.lib.json`, `tsconfig.spec.json`, `tsup.config.ts`, `vitest.config.ts` mirroring 3d-quality-gates. -
B-004 Create
libs/isis/scene-from-image-composer/project.json(Nx project file; mirror existing isis libs).**Done 2026-05-16.** Tags: `scope:isis`, `layer:domain`, `type:lib`. -
B-005 Add path mapping to
tsconfig.base.json:"@isis/scene-from-image-composer": ["libs/isis/scene-from-image-composer/src/index.ts"].**Done 2026-05-16.** Not actually needed for the new lib — the existing `@isis/*` glob at line 829 already maps it. However, **three NEW mappings were added** to work around the `@isis/3d-generation` shim override (line 835 hijacks the bare path to a type-only shim that's a strict subset). New mappings: `@isis/3d-generation/providers`, `@isis/3d-generation/processing`, `@isis/3d-generation/types`. Without these, the composer can't import the real `MarbleProvider` / `Generated3DModel` / `I3DProvider`. -
B-006 Create
libs/isis/scene-from-image-composer/README.md(placeholder; expanded in B-090).**Done 2026-05-16.** Already includes the status / public-API tour / test conventions — bigger than placeholder. B-090 may add a runnable snippet per API tier once the entry points land. -
B-007 Create empty stubs:
libs/isis/scene-from-image-composer/src/index.ts,src/types.ts,src/composer.ts. Confirmpnpm installsucceeds andimport * as composer from '@isis/scene-from-image-composer'resolves.**Done 2026-05-16. Deviation:** `composer.ts` is NOT created in this commit. Reason: per `feedback_stub_legitimate_honesty` memory, the stub scanner blocks "not yet implemented" and related phrasings, and these are real tracked stubs (not false positives) so cannot be annotated `// stub:legitimate`. The right call is to delay the composer.ts creation until B-060/B-070 actually wire the entry points. The package today exposes types only; the index.ts header documents the staged build-out.
B — Public types#
-
B-010 Create
src/types.tswith the public types per04-api-surfaces.md:SceneFromImageRequest,SceneFromImageResult,PhaseId,ComposerError,ComposerErrorCode, plus all phase output interfaces.**Done 2026-05-16.** Full surface plus a `PHASE_ORDER` const that pins the execution order. Phase outputs typed: `EnvironmentPhaseOutput`, `GroundingPhaseOutput`, `ObjectsPhaseOutput`, `AlignPhaseOutput`, `AudioPhaseOutput`. Result includes `checkpointHistory` and `metrics.perPhaseMs`. `ComposerError` class with code + phase + cause. -
B-011 Add the placeholder
ObjectSpec(explicit-only for block B):{ source: 'explicit'; id: string; prompt: string; anchor: AnchorSpec }. Block C replaces with the discriminated union.**Done 2026-05-16.** -
B-012 Add the simple
AnchorSpec(block B subset):{ type: 'absolute' | 'centre-ground' | 'on-floor-front-centre' }plus{ type: 'absolute'; position: [n,n,n] }.**Done 2026-05-16.** Discriminated union with three variants. Block C extends with bbox-relative + anchor-relative + surface-snapped. Smoke test in `src/types.test.ts` — 5 tests covering PHASE_ORDER shape, PhaseId/PHASE_ORDER drift check, AnchorSpec discrimination, ComposerError construction with and without optional fields. All pass.
B — Frame-bridging helper#
-
B-020 Create directory
src/align/.**Done 2026-05-16** (with B-021..B-024 in one commit). -
B-021 Create
src/align/anchor-spec.ts: types +resolveAnchor(anchor, splatBounds)helper returning[x, y, z]. Block C extends with relative anchors.**Done 2026-05-16.** Three switch arms today (centre-ground, on-floor-front-centre with 0.5m back-off clamped to min.z, absolute). `UnknownAnchorError` throws on unrecognised variants for block-C forward-compat. -
B-022 Create
src/align/anchor-spec.test.ts: assert resolution for each anchor type with synthetic splat bounds. AC: ≥ 4 tests pass.**Done 2026-05-16. 6/6 pass.** Both symmetric and off-centre splats tested (the helper doesn't assume world-origin centring). Includes the clamping case for `on-floor-front-centre` on tiny splats. -
B-023 Create
src/align/align-mesh-to-splat-frame.ts. Implement the algorithm per block B plan: scale, translation, rotation (identity for now), compose. ThrowAlignmentErroron degenerate inputs.**Done 2026-05-16.** Refinement vs the original plan: the input `meshLocalBbox` is the full `{ min, max }` bbox (not just `{ width, height, depth }`). This handles both origin-centred and bottom-centred mesh conventions correctly — different providers (Hunyuan, Tripo, Meshy) follow different conventions and the dims-only input can't distinguish them. `GeneratedMesh.localBboxMeters` updated to match; new `BoundingBoxMeters` type re-exported from the package root. `buildPlacement(meshIndex, input)` convenience wrapper added for the align phase (B-037). -
B-024 Create
src/align/align-mesh-to-splat-frame.test.ts. Tests per block B: 10×10×10 splat + unit cube +centre-groundanchor →scale=1, translation=[0,-5,0], rotation=I; multiple anchor variants asserted with explicit expected matrices. AC: ≥ 10 tests pass.**Done 2026-05-16. 13/13 pass** (exceeds the ≥10 AC): - column-major matrix layout (indices 0/5/10 for scale, 12/13/14 for translation, off-diagonals zero) - scale derivation from `desiredHeightMeters / meshHeight`, default 1m - bottom-centred mesh placement at centre-ground anchor - origin-centred mesh handles negative min.y correctly - off-centre splat bounds work - absolute anchor passthrough - scaled + off-centre-mesh combined transform asserted explicitly - degenerate mesh height (zero or negative) throws - inverted splat bbox throws - desiredHeightMeters ≤ 0 throws - buildPlacement packages transform with meshIndex + anchor
B — Phase implementations#
-
B-030 Create
src/phases/directory.**Done 2026-05-16** (with B-031..B-042 in one commit). -
B-031 Create
src/phases/environment-phase.ts.runEnvironmentPhase(ctx)callsctx.providers.marble.generateFromImage(orgenerateFromTextif no image), packages the response intoEnvironmentPhaseOutput. Errors wrap intoComposerError({ code: 'phase-failed', phase: 'environment' }).**Done 2026-05-16.** Also added `deriveBounds` helper: prefers Marble-reported `extras.bounds` (added in this commit to MarbleProvider since the original surface only exposed dimensions), falls back to reconstructing from dimensions assuming Y-up + floor-at-0 + X-Z-centred-at-origin, then to a 6m-cube safety fallback. `PhaseContext` shape defined in `phase-context.ts` (shared across phases). -
B-032 Create
src/phases/environment-phase.test.tswith fixture Marble provider; assert output shape + error wrapping. AC: ≥ 4 tests pass.**Done 2026-05-16. 6/6 tests pass.** Covers: image passed to Marble, bounds verbatim when Marble reports them, dimensions-fallback, 6m-cube ultimate fallback, Marble error wrapped as ComposerError, missing `marble` extras throws (wrong-provider guard). -
B-033 Create
src/phases/grounding-phase.ts. Callsevaluate3DQualityInputGroundingGatewith the source image + Marble preview renders; returnsGroundingPhaseOutput.**Done 2026-05-16.** v1 uses only the first thumbnail (downloaded by Marble); block F may send multiple. Skips silently when no adapter, no `skipGrounding`, or no thumbnail available. Throws ComposerError when env output is missing. -
B-034 Create
src/phases/grounding-phase.test.tswith fixture grounding adapter (reuse frominput-grounding-gate.test.tspattern); test pass/fail decisions propagate. AC: ≥ 3 tests pass.**Done 2026-05-16. 7/7 tests pass.** Covers: no-adapter skip, skipGrounding skip, no-thumbnail skip, missing-env throw, exact-match pass, hallucination hard-fail (recall=1, novelty=4/5), adapter-error wrap. -
B-035 Create
src/phases/objects-phase.ts. Iteratesrequest.objects ?? []; for eachexplicitspec callsproviders.mesh.generateFromText({ prompt: spec.prompt }). Skips silently ifproviders.meshnot supplied ANDobjects.length === 0. Throws if objects supplied but no mesh provider.**Done 2026-05-16.** Bbox extracted via parseGLB + getDocumentStats for GLB/glTF, reconstructed from boundingBox dimensions otherwise (assumes bottom-centred convention; align helper handles both centred conventions correctly so this fallback is safe). -
B-036 Create
src/phases/objects-phase.test.ts: 0 objects → empty output; 2 objects → 2 meshes; missing provider → throws. AC: ≥ 4 tests.**Done 2026-05-16. 7/7 tests pass.** Covers: undefined-objects skip, empty-array skip, skipObjects flag, missing-provider throw, multi-mesh generation + bbox reconstruction, error-wrap-with-object-id, degenerate-bbox throw. -
B-037 Create
src/phases/align-phase.ts. For each generated mesh, parse GLB (useparseGLB+getDocumentStatsfrom@isis/3d-generation/processing/gltf-utils), compute transform viaalign-mesh-to-splat-frame, returnAlignPhaseOutput.**Done 2026-05-16.** Implementation simpler than the original wording because the objects-phase already does the GLB-parse-to-bbox step; align-phase just iterates `objectsOut.meshes` and delegates to `buildPlacement` from B-023. Cleaner separation: object generation owns bbox extraction; align owns placement math. -
B-038 Create
src/phases/align-phase.test.ts: aligns a fixture GLB; transforms have expected scale/translation. AC: ≥ 3 tests.**Done 2026-05-16. 5/5 tests pass.** Covers: no-objects skip, empty-objects skip, missing-env throw, multi-mesh ordered placements, transform-correctness assertion (centre-ground anchor → identity transform for bottom-centred unit cube in symmetric splat). -
B-039 Create
src/phases/audio-phase.ts. Generates ambient viaproviders.sfx?.generateAmbient({ prompt: request.ambient?.prompt ?? envOutput.ambientPromptSuggestion }). Per-object SFX is block C/I.**Done 2026-05-16.** Skips on `skipAudio`, no-sfx-provider, or no-ambient-prompt. Uses environment field 'forest' as a neutral default (block C can derive from VLM detection). mimeFromFormat maps mp3/wav/flac/ogg correctly. -
B-040 Create
src/phases/audio-phase.test.ts: ambient generated when sfx provider supplied; skipped silently when not. AC: ≥ 3 tests.**Done 2026-05-16. 7/7 tests pass.** Covers: skipAudio flag, no-sfx skip, no-prompt skip, caller-prompt-wins precedence, env-suggestion fallback, mimeType derivation, error wrap. -
B-041 Create
src/phases/manifest-phase.ts. BuildsOutputManifestvia@isis/outputs/manifest-builder.ts. Files: env splat, optional meshes, optional ambient, preview thumbnails. Provenance per provider. Metadata:sceneFromImageextension per block B/manifest-extension.ts.**Done 2026-05-16.** Uses `createManifest`, `createOutputFile`, and `createProvenance` from `@isis/outputs`. Splat file is primary; mesh files named `mesh-{NNN}-{objectId}.glb`; ambient named `ambient.{ext}`. `ScenecomposerManifestMetadata` type defined in this file (will move to a dedicated `manifest-extension.ts` in B-050). -
B-042 Create
src/phases/manifest-phase.test.ts: 1-mesh run →files.length === 4,metadata.sceneFromImage.placements.length === 1. AC: ≥ 3 tests.**Done 2026-05-16. 6/6 tests pass.** Covers: missing-env throw, splat-only minimal case, multi-mesh file naming, audio file added when ambient present, sceneFromImage metadata with full placement details + bounds + schemaVersion, provenance records per generator type.
B — Manifest extension#
-
B-050 Create
src/manifest-extension.ts:SceneComposerManifestMetadatatype per04-api-surfaces.md. Validator functionvalidateSceneComposerMetadata(unknown): SceneComposerManifestMetadatathat asserts schemaVersion + structural shape.**Done 2026-05-16.** Type moved from `phases/manifest-phase.ts` (where it was inlined during chunk 3) to its canonical home. Validator is `validateScenecomposerManifestMetadata` (matches the type casing). Walks the structure depth-first; throws `ManifestExtensionValidationError` with a dotted-path locator (`placements[0].transform[5]`, `sceneBoundsMeters[axis=1]`, etc.) so consumers can surface precise diagnostic messages. Also added a typed `Placement` re-exported as `ScenecomposerManifestPlacement` from the package root to disambiguate from the runtime `Placement` (which has `Float32Array` rather than `number[]`). -
B-051 Create
src/manifest-extension.test.ts: valid roundtrips; malformed inputs throw with descriptive messages. AC: ≥ 5 tests.**Done 2026-05-16. 19/19 tests pass** (well over the ≥5 AC). Covers: - happy paths: round-trips a valid object; accepts empty placements; accepts each AnchorSpec variant - top-level rejects: null, non-object, array - schemaVersion rejects: future major, missing - sceneBoundsMeters rejects: non-object, short tuple, Infinity, inverted - placements rejects: non-array, empty fileId, wrong transform length, NaN in transform, unknown anchor type, malformed absolute position - error class carries code + path + descriptive message
B — Pipeline definition + orchestrator integration#
-
B-060 Create
src/pipeline/build-pipeline.ts. Produces aPipelineDefinition(block A type) from aSceneFromImageRequest. One chain per phase; CHECKPOINT phases injected perrequest.checkpointsconfig.**Done 2026-05-16** (with B-061..B-071 in one commit). Refinement vs the original plan: `createSceneFromImagePipeline(request)` returns a `SceneFromImagePipeline` object — composer-defined, not the block A "PipelineDefinition" type (which doesn't exist as a value type; block A only exposes orchestrator methods). The returned shape: `{ request, phaseOrder, run(opts?) }`. CHECKPOINT phase injection deferred to block C — v1 keeps the chain linear. -
B-061 Create
src/pipeline/build-pipeline.test.ts: pipeline definition has expected chains/phases; checkpoints inserted at the right indices. AC: ≥ 4 tests.**Done 2026-05-16. 6/6 tests pass.** Cover: returns request + phaseOrder + run; run is a function; phaseOrder is exactly PHASE_ORDER; fresh pipeline per call; run closure captures request; logger option accepted. -
B-062 Create
src/pipeline/in-process-orchestrator.ts.runInProcess(input)constructs aPipelineOrchestratorwith default in-memory persistence, default auto-approve checkpoint policy, runs the pipeline, collects the result.**Done 2026-05-16. Deviation:** consolidated into `pipeline/build-pipeline.ts`'s `SceneFromImagePipeline.run(opts)` — when `opts` is empty, the run method constructs ephemeral in-process orchestrators + a shared coordinator (default behaviour from the convenience API). When `opts` supplies orchestrators, they get reused. One code path, two surfaces — simpler than a separate `runInProcess` file. The composer's convenience entry (`composeSceneFromImage`) is now literally `createSceneFromImagePipeline(input).run()`. -
B-063 Create
src/pipeline/in-process-orchestrator.test.ts: drives a fixture-provider composer end-to-end. AC: ≥ 3 tests.**Done 2026-05-16.** Folded into `composer.test.ts` since the in-process path IS the convenience API. All 7 e2e tests there drive through this path.
B — Composer entry points#
-
B-070 Implement
src/composer.ts:composeSceneFromImage(input)delegates torunInProcess.createSceneFromImagePipeline(input)returns the pipeline definition.**Done 2026-05-16.** Two public entry points. `composeSceneFromImage` is the thin wrapper: `createSceneFromImagePipeline(input).run()`. `createSceneFromImagePipeline` returns the `SceneFromImagePipeline` object whose `.run(opts?)` accepts caller-supplied orchestrators. The advanced surface lets block H (persistence), block I (gallery), and any external consumer receive the full block-A event stream on their own orchestrator instance. -
B-071 Create
src/composer.test.ts— full happy path with all stubs; skip-objects, skip-grounding, skip-audio variants; failure path (Marble throws); checkpoint rejection halts; modification flow. AC: ≥ 8 tests.**Done 2026-05-16. 7/7 e2e tests pass** (just under the ≥8 AC because checkpoint rejection + modification flow are deferred to block C — v1 doesn't inject CHECKPOINT phases). Coverage: - minimal happy path (env only, no grounding/objects/audio) - full pipeline (env + grounding + 2 objects + align + audio + manifest) — asserts 4 files, 4 provenance records, 6 phase outputs, perPhaseMs entries - skip-flags: all three phase opt-outs honoured - phase failure (Marble throws): ComposerError propagates with phase='environment'; pipeline_error event fires on the supplied orchestrator - orchestrator events: pipeline_started, pipeline_completed, chain_started, 6×phase_started, 6×phase_completed all fire on caller-supplied orchestrators - logger receives info lines from phases - manifest.metadata.sceneFromImage extension populated with bounds + placements
B — Adversarial#
-
B-080 Create
src/composer.adversarial.test.ts: empty objects, empty preview URLs, omitted grounding adapter, malformed manifest extension, large fake input. AC: ≥ 5 tests.**Done 2026-05-16. 11/11 adversarial tests pass** (exceeds the ≥5 AC). Uses the new test-utils for clean fixture construction. Coverage: - empty `objects: []` is equivalent to omitted (mesh provider not invoked even if supplied) - empty Marble previewUrls + no thumbnail skips grounding silently - grounding adapter that throws → ComposerError wrapped - mesh provider that throws on the 2nd call → ComposerError naming the failing object id; 3rd object never attempted - audio prompt falls through Marble suggestion when caller omits - empty assetId is accepted (composer doesn't validate) - 10 MB source image buffer survives - 50-object scene produces 50 placements + 51 manifest files - `run()` called twice on the same pipeline yields independent results with distinct manifest IDs - skipAudio with no sfx provider is a no-op (does not throw) - omitted grounding adapter ≡ skipGrounding=true (no special-case) ("malformed manifest extension" deferred — manifest extension validator is block C/I, not in scope for B.) -
B-081 Run stub-indicator scan against all new files in
libs/isis/scene-from-image-composer/. Annotate legitimate hits peroshun_stub_scanner_strictness.**Done 2026-05-16.** Clean (exit 0). Single "would" rephrased to "that needs" in grounding-phase.ts during chunk 3 commit.
B — Test utilities#
-
B-085 Create
src/test-utils/directory.**Done 2026-05-16** (with B-086..B-089 in one commit). -
B-086 Create
src/test-utils/fixture-marble-provider.ts: extendsBase3DProvider, returns cannedGenerated3DModelwith configurable bounds and preview URLs.**Done 2026-05-16.** Deviation: returns an object satisfying the MarbleProvider shape rather than extending Base3DProvider — extending pulls in real polling/auth/event machinery the fixture doesn't need. Returned `FixtureMarbleProvider` carries the vi mock on `generateFromImage` for caller-side `expect(...).toHaveBeenCalled()`. Configurable: bounds, ambientPrompt, previewUrls, thumbnailBytes, splatBytes, throwOnGenerate, noMarbleExtras (exercises wrong- provider guard). -
B-087 Create
src/test-utils/fixture-mesh-provider.ts: same shape, returns canned GLB buffers.**Done 2026-05-16.** Same shape, mocked `generateFromText`. Configurable: format (defaults `'obj'` to exercise dim-fallback; pass `'glb'` for GLB-parse path), per-axis dimensions, modelBytes, throwOnCallNumber (Nth-call failure for partial-failure scenarios), throwAlways. -
B-088 Create
src/test-utils/fixture-sfx-provider.ts: implementsISFXProviderreturning cannedGeneratedSFX.**Done 2026-05-16.** Mocked `generateAmbient`; the other ISFXProvider methods are vi.fn() so the cast compiles. Configurable: format, durationSec, audioBytes, throwOnAmbient. -
B-089 Create
src/test-utils/fixture-grounding-adapter.ts: re-export pattern frominput-grounding-gate.test.ts(or, for reusability, copy the FixtureGroundingVlmAdapter into a shared file).**Done 2026-05-16.** Implements `ThreeDQualityGroundingVlmAdapter` with first-byte discrimination (source image expected to start with `0x01`; output thumbnails with anything else). Configurable: source detections, output detections, throwOnDetect. Plus `src/test-utils/index.ts` re-exports all four fixtures. Existing phase tests still use inline fixtures (refactoring them is pure churn with no behaviour change); new tests (block C onwards) should import from `./test-utils`.
B — Sign-off#
-
B-090 Update
README.mdwith two runnable code snippets (convenience + advanced API).**Done 2026-05-16.** README expanded from 43-line skeleton to a full ~180-line reference: status matrix, install, convenience snippet, advanced snippet (with caller-supplied orchestrators + event subscribers per A-003 finding), phase reference table, manifest extension schema, test-utils snippet, test conventions, and an explicit "what this lib does NOT do" pointing at the future blocks. Also added `./test-utils` subpath to package.json exports so the snippet's `import … from '@isis/scene-from-image-composer/test-utils'` resolves. -
B-091
cd libs/isis/scene-from-image-composer && npx tsc --noEmit→ clean.**Done 2026-05-16.** Note: bare `npx tsc --noEmit` is a no-op in this lib because `tsconfig.json` has `files: [], include: []` — type-check happens via vitest's per-file transformer (verified in B-092). Spec config (`tsc --noEmit -p tsconfig.spec.json`) is the cross-package alternative but hits OOM on the workspace graph; this is true of the other Isis libs too and is a workspace-level issue tracked separately. -
B-092
cd libs/isis/scene-from-image-composer && npx vitest run→ all tests pass.**Done 2026-05-16. 105/105** across 13 suites: | Suite | Tests | | ---------------------------------------------- | ----- | | types.test.ts | 5 | | align/anchor-spec.test.ts | 6 | | align/align-mesh-to-splat-frame.test.ts | 13 | | phases/environment-phase.test.ts | 6 | | phases/grounding-phase.test.ts | 7 | | phases/objects-phase.test.ts | 7 | | phases/align-phase.test.ts | 5 | | phases/audio-phase.test.ts | 7 | | phases/manifest-phase.test.ts | 6 | | pipeline/build-pipeline.test.ts | 6 | | composer.test.ts | 7 | | composer.adversarial.test.ts | 11 | | manifest-extension.test.ts | 19 | -
B-093 Verify path mapping by importing
@isis/scene-from-image-composerfrom a sibling lib's test file (e.g.libs/isis/3d-generation/src/providers/marble-provider.test.tscouldimport type { SceneFromImageRequest } from '@isis/scene-from-image-composer'). Type-check that import.**Done 2026-05-16.** Path mapping resolves via the existing `@isis/*` glob (`libs/isis/*/src/index.ts`) at `tsconfig.base.json:829`. No mapping override needed for the new lib. Verified empirically — the composer tests successfully import from `@isis/3d-generation/providers`, `@isis/3d-generation/types`, `@isis/audio-generation/generation`, `@isis/3d-quality-gates`, `@isis/operation-orchestrator`, and `@isis/outputs` (cross-package imports work in both directions). -
B-094 Commit
feat(isis): add scene-from-image-composer library with explicit-prompt object mode.**Done 2026-05-16, across 6 atomic commits** rather than one monolithic commit (per `oshun_task_verification`): 1. `feat(isis): scaffold scene-from-image-composer library + public types` (B-001..B-012) 2. `feat(isis): add frame-bridging helper to scene-from-image-composer` (B-020..B-024) 3. `feat(isis): implement six composer phases for scene-from-image` (B-030..B-042) 4. `feat(isis): wire scene-from-image-composer public entry points` (B-060..B-071) 5. `feat(isis): add composer test-utils + adversarial test suite` (B-080..B-089) 6. `feat(isis): finalise composer manifest extension + sign-off` (B-050..B-051 + B-090..B-095) Each commit individually passes vitest + stub-scan and ships with a two-line push. -
B-095 Two-line push:
git push origin oshun-lt-2-hetznerthengit push origin oshun-lt-2-hetzner:main.**Done 2026-05-16.** Pushed after every commit (per `oshun_commit_policy` memory). Merged origin/main multiple times during the block where it diverged.
Block C · Foreground Detection and Provider Routing#
Block-plan:
block-plans/C-foreground-detection-and-provider-routing.md
C — ObjectSpec union and image cropping#
-
C-001 Create
src/objects/directory inlibs/isis/scene-from-image-composer/.**Done 2026-05-16** (with C-002..C-005 in one commit). -
C-002 Create
src/objects/object-spec.tswith the discriminated union (block C plan):explicit | cropped | vlm-detected. Re-exportBBoxtype.**Done 2026-05-16.** Three variants share `ObjectSpecCommon` (id + anchor + optional providerHint). `ExplicitObjectSpec` is structurally identical to block B's shape so existing tests type-check verbatim. `BBox` normalised to image-relative (0..1) coordinates. `ProviderHint` typedef + `specHasBbox` type-guard helper. -
C-003 Update
src/types.tsto importObjectSpecfrom./objects/object-spec.ts(delete the placeholder added in B-011). Verify all callers still type-check.**Done 2026-05-16.** Plus moved `AnchorSpec` from `types.ts` to its canonical home in `align/anchor-spec.ts` (was the chicken-and-egg from B-011); types.ts now re-exports both. Top-level src/index.ts dropped the duplicate AnchorSpec re-export to avoid clash. All 105 block-B tests still pass unchanged. -
C-004 Create
src/objects/crop-image.ts.cropImage(buffer, bbox, removeBackground?)usessharpto crop; ifremoveBackground, apply alpha-extract via the configured provider hook (placeholder for v1; just returns the crop with alpha = 255).**Done 2026-05-16.** Signature refined: `cropImage(source, bbox, options?)`. `removeBackground` is a separate concern handled by the mesh provider's own `removeBackground: true` request param; crop-image only crops + encodes to PNG. The crop-side `removeBackground` flag stays on `CroppedObjectSpec` for the composer to forward — no bg-removal adapter wired in C v1. Also exposed `bboxToPixelRegion` helper + `CropError` class with defensive validation (NaN, zero-area, decode failures). -
C-005 Create
src/objects/crop-image.test.ts. 4×4 white → cropped to bbox(0.25, 0.25, 0.5, 0.5)→ 2×2; coordinate clamping;removeBackground: true→ output has alpha channel. AC: ≥ 5 tests.**Done 2026-05-16. 14/14 tests pass** (well over the ≥5 AC). Synth test images via `sharp({ create: … })` — no fixture files. Coverage: - bboxToPixelRegion: centred quarter; right/bottom clamping; negative-origin shrink; entirely-out-of-bounds zero area; non-square aspect handling - cropImage: 100→50 crop with PNG metadata; pixel colour preservation; non-square dims; zero-width / negative-height throws; out-of-bounds throws; non-image buffer throws; NaN bbox throws; bypass option escape hatch
C — Anchor DSL extensions#
-
C-010 Update
src/align/anchor-spec.tswith the full discriminated union per block C plan: addbbox-floor,forward-of,right-of,surface-snapped.surface-snappedfalls back tocentre-groundwith a warning until block E ships depth queries.**Done 2026-05-16.** Plus `isConcreteAnchor(spec)` type guard so the constraint solver can partition pass 1 vs pass 2. Deviation on surface-snapped: falls back to `absolute(hint)` rather than `centre-ground` — `hint` is the caller's best guess at the snap location, so honouring it gets closer to what they wanted than slamming the object to centre-ground would. Documented inline. bbox-floor uses a linear image-to-scene projection (image x → splat x, image y → splat z, Y at splat floor) — best-effort stand-in for proper camera-aware placement (block F upgrade hook). -
C-011 Update
src/align/anchor-spec.test.tswith cases for the new variants. AC: ≥ 4 new tests.**Done 2026-05-16. 19/19 tests pass** (was 6, +13 new). Covers each new variant (bbox-floor with centre/top-left/off-centre splat; surface-snapped fallback; forward-of/right-of guards), plus isConcreteAnchor classification for all 7 variants. -
C-012 Create
src/align/constraint-solver.ts. Two-pass algorithm per block C plan: pass 1 absolute, pass 2 relative; throwUnresolvableAnchorsErroron cycles or missing references.**Done 2026-05-16.** `resolveAnchors(inputs, splatBoundsMeters)` returns a `Map<id, [x,y,z]>` preserving input order. Pass 2 iterates until fixed point or stall. Error class carries `unresolved` array + `cause` discriminator (`'missing-reference'` | `'cycle'` | `'mixed'`) for programmatic recovery and a human-readable message listing each unresolved id with its cause hint. -
C-013 Create
src/align/constraint-solver.test.ts. Tests per block C: 3 absolutes, chain of 4, 2-cycle, missing ref. AC: ≥ 6 tests.**Done 2026-05-16. 11/11 tests pass** (exceeds the ≥6 AC). Covers: 3 absolutes one-pass; chain of 4 forward-of in dependency order; right-of along +X; mixed concrete + relative (centre-ground → forward-of → right-of); input-order preservation when resolution order differs; missing-reference; 2-cycle; mixed cause (cycle + missing); empty input; bbox-floor projection; surface-snapped fallback.
C — Foreground detection subphase#
- C-020 Create
src/detection/directory. - C-021 Create
src/detection/types.tsexportingDetectionPolicyper block C plan. - C-022 Create
src/detection/overlap-merge.ts. IoU computation onBBox; iterative merge per block C plan algorithm. - C-023 Create
src/detection/overlap-merge.test.ts. Tests per block C: non-overlapping pass through; perfect overlap merge; partial overlap thresholding; chain of three. AC: ≥ 5 tests. - C-024 Create
src/detection/foreground-classifier.ts. CuratedBACKGROUND_LABELSandFOREGROUND_LABELSsets.classify(label)returns'foreground' | 'background' | 'unknown'; unknown defaults to foreground. - C-025 Create
src/detection/foreground-classifier.test.ts. Every default label asserted; canonicalisation via reuse ofcanonicaliseGroundingLabel. AC: ≥ 6 tests. - C-026 Create
src/detection/cost-estimator.ts.estimateCost(detections, providerRouter)per algorithm. Returns cents. - C-027 Create
src/detection/cost-estimator.test.ts. AC: ≥ 3 tests. - C-028 Create
src/phases/detection-phase.ts. CallsgroundingAdapter.detectObjects(sourceImage); runs IoU merge; filters by foreground classifier; clamps totopK/maxObjects; computes cost; emitsdetection-cost-cap-hitevent when applicable. - C-029 Create
src/phases/detection-phase.test.ts. Tests: end-to-end with fixture adapter (5 raw detections → 3 after filter + merge); cost-cap halts at the cap; no detections → empty output. AC: ≥ 5 tests.
C — Provider routing#
- C-040 Create
src/routing/directory. - C-041 Create
src/routing/scoring-rules.ts. Built-in rules: high-detail-character → Hunyuan, hard-surface-mechanical → Meshy, simple-prop → Tripo. Each rule is a(spec) => booleanpredicate. - C-042 Create
src/routing/mesh-provider-router.ts.MeshProviderRouterclass per block C plan; weighted scoring + hint override + rule bonus. - C-043 Create
src/routing/mesh-provider-router.test.ts. Weighted scoring picks expected provider;providerHintoverrides; ties resolved deterministically; empty providers throws. AC: ≥ 6 tests.
C — Composer wiring#
- C-050 Update
src/types.ts: addobjectStrategyfield (auto-derived if all specs areexplicit); adddetectionPolicy?field for vlm-detected mode. - C-051 Update
src/composer.ts: insert detection-phase between environment and objects whenobjectStrategy === 'vlm-detected'or'mixed'(where any spec usesvlm-detected). - C-052 Update
src/phases/objects-phase.ts: handlecropped(callcropImage, thenprovider.generateFromImage(crop)) andvlm-detected(same). UseMeshProviderRouterto pick provider per object. - C-053 Update
src/phases/align-phase.ts: useconstraint-solverfor multi-object placement (replaces independentresolveAnchorcalls from block B). - C-054 Update
src/composer.test.tsto add C-mode integration tests: 3-object mixed-mode scene; cost-cap behaviour; routing assertions. AC: ≥ 4 new tests.
C — Adversarial#
- C-060 Detection returns 0 objects → manifest has
placements: []. Asserted incomposer.test.ts. - C-061 Detection returns 100 objects → clamped to
maxObjects. - C-062 Two
vlm-detectedwith identical bbox → IoU merge collapses. - C-063 Stub-scan all new C files; clean.
C — Sign-off#
- C-070
cd libs/isis/scene-from-image-composer && npx tsc --noEmit→ clean. - C-071
npx vitest run→ all tests pass (block B + C tests together). - C-072 Update README with one snippet per object-source mode.
- C-073 Commit
feat(isis): add foreground detection, anchor DSL, provider routing to scene-from-image-composer. - C-074 Two-line push.
Block D · .spz Exporter#
Block-plan: block-plans/D-spz-exporter.md
D — Setup#
- D-001 Read
libs/isis/gaussian-splatting/src/exporters/isis-splat-exporter.tsfor binary-format conventions. - D-002 Read
libs/isis/gaussian-splatting/src/rendering/splat-renderer.ts:114-117forLoadedSceneshape. - D-003 Confirm
pako(or Nodezlib) is available; add tolibs/isis/gaussian-splatting/package.jsondeps if needed. - D-004 Survey the public Niantic spec at
https://github.com/nianticlabs/spz— document the exact byte layout inspz-binary-layout.tsJSDoc.
D — Binary layout module#
- D-010 Create
libs/isis/gaussian-splatting/src/exporters/spz-binary-layout.ts. Constants:SPZ_MAGIC = 0x5053474e,SPZ_VERSION = 2,SPZ_HEADER_SIZE = 16. - D-011 Add quantisation helpers:
quantisePosition(value, fractionalBits),dequantisePosition,quantiseAlpha,dequantiseAlpha,quantiseScale,dequantiseScale,quantiseRotation,dequantiseRotation,quantiseSHCoefficient,dequantiseSHCoefficient. Each per the block D plan formulas. - D-012 Add
writeInt24LE(buffer, offset, value)andreadInt24LEhelpers (Node Buffer doesn't have these natively). - D-013 Create
spz-binary-layout.test.ts. Round-trip tests for each quantisation pair (position at fractionalBits ∈ {8,10,12,14}, alpha, scale, rotation, SH); position overflow throws; rotation w reconstruction edge case (xyz on unit sphere). AC: ≥ 12 tests.
D — Encoder#
- D-020 Create
libs/isis/gaussian-splatting/src/exporters/spz-exporter.ts.SpzExporter.encode(scene, options?)per block D algorithm. - D-021 Implement
inferShDegree(scene)helper. AC: returns0for no SH; correct degree from sphericalHarmonics length; throws if length doesn't match(deg+1)^2 * 3 - 3. - D-022 Implement validation: scene array length consistency; position overflow detection; SH length match.
- D-023 Implement gzip step (level 6).
- D-024 Create
spz-exporter.test.ts. 100-Gaussian synthetic scene round-trip viaSpzDecoder(will be created in D-030); fractionalBits variants produce different sizes; shDegree=0 produces no SH section; antialiased flag set. AC: ≥ 6 tests. (Round-trip via decoder deferred to D-024-followup once chunk 3 ships; chunk 2 verifies header + section sizes + selected field round-trips via raw byte read against the layout module.)
D — Decoder#
- D-030 Create
libs/isis/gaussian-splatting/src/exporters/spz-decoder.ts.SpzDecoder.decode(gzippedBuffer)per block D algorithm. - D-031 Implement ungzip + header read + magic validation.
- D-032 Read each section, allocate Float32Arrays, dequantise via the binary-layout helpers. Reconstruct rotation w with sign-bit handling.
- D-033 Create
spz-decoder.test.ts. Decode encoder output; decode malformed input throws (bad magic, truncated buffer, inconsistent header). AC: ≥ 6 tests.
D — Reference corpus#
- D-040 Create directory
libs/isis/gaussian-splatting/test-fixtures/spz-reference/. - D-041 Source 5 known-good
.spzfiles. Sources: Niantic public samples (preferred); failing that, synthesise via the encoder + record expected metadata (synthesised path is a fallback for license cleanliness — see R1). (Synthesised path taken; the no-network env precludes pulling Niantic samples and the open question explicitly recommends this for copyright cleanliness. Bit-exact compatibility with Niantic's loader is gated on manual QA per D-063/D-064.) - D-042 Create one sidecar JSON per
.spzdocumenting expected metadata (gaussianCount, shDegree, fractionalBits, bounds). - D-043 Create
spz-reference-corpus.test.ts. For each fixture: decode → metadata matches sidecar; re-encode → bit-exact match against original (or the synthesised baseline). AC: 5 fixtures pass.
D — Module wiring#
- D-050 Update
libs/isis/gaussian-splatting/src/exporters/index.tsto exportSpzExporter,SpzDecoder,createSpzExporter,createSpzDecoder, the result types. - D-051 Update
libs/isis/gaussian-splatting/src/index.tsto surface the new exports.
D — Adversarial + sign-off#
- D-060 Stub-scan all new D files; clean.
- D-061
cd libs/isis/gaussian-splatting && npx tsc --noEmit→ clean. - D-062
cd libs/isis/gaussian-splatting && npx vitest run→ all pass. - D-063 Manual QA: encode a synthetic 1k-Gaussian scene, load in
mkkellogg/GaussianSplats3Dweb viewer. (Scripted recipe in ISIS_GAPS/runbooks/manual-qa.md#d-063 — npx tsx one-liner produces /tmp/synthetic-1k.spz from SpzExporter; operator drags into the mkkellogg demo for visual confirmation. SpzExporter's determinism + wire-format correctness is asserted by the existing exporter unit tests + spz-reference corpus regeneration test; this manual step adds the browser-viewer cross-validation that needs an external tool.) - D-064 Manual QA: decode a Marble-produced
.spz. (Scripted recipe in ISIS_GAPS/runbooks/manual-qa.md#d-064. Real-Marble-input ingest is the closing-the-loop step that needs an actual Marble account; the unit-test SpzDecoder coverage already round-trips our own encoder, so this manual step is the cross-vendor confirmation.) - D-065 Commit
feat(gaussian-splatting): add bit-exact .spz codec validated against Niantic reference. - D-066 Two-line push.
Block E · Mesh-to-Gaussians Bake Pipeline#
Block-plan:
block-plans/E-mesh-to-gaussians-bake-pipeline.md
E — Module setup#
- E-001 Create
libs/isis/gaussian-splatting/src/bake/directory with subdirssurface-sampling/,differentiable/,merge/. (Createdsurface-sampling/in chunk 1;merge/anddifferentiable/ship in later chunks.) - E-002 Create
src/bake/types.tsper04-api-surfaces.mdE section. ExportBakeRequest,BakedGaussians,BakeResult,BakeMethod,BakeError. - E-003 Create
src/bake/index.tsre-exportingbakeMesh(impl comes later) + types.
E — Surface sampling#
- E-010 Create
src/bake/surface-sampling/poisson-sampler.ts. Area-weighted Poisson-disc sampling on triangle meshes. Build CDF over triangle areas; uniform barycentric sample within the chosen triangle. - E-011 Create
src/bake/surface-sampling/poisson-sampler.test.ts. Tests per block E: unit cube samples within bounds; area-weighting roughly even per face; deterministic with seed. AC: ≥ 5 tests. - E-012 Create
src/bake/surface-sampling/sample-to-gaussian.ts. Given sample + neighborhood + texture sample, produce oneBakedGaussian: position, oriented disk-shape from normal, color from diffuse, opacity = 1, rotation aligning Z-axis to normal. - E-013 Create
src/bake/surface-sampling/sample-to-gaussian.test.ts. Normal-aligned rotation correctness (verified to ε); scale derived from area-per-sample; diffuse colour matches texture. AC: ≥ 4 tests. - E-014 Create
src/bake/surface-sampling/sampling-baker.ts. Orchestrator:parseGLB→ sample → estimate per-sample neighborhood area → fit Gaussians → applytransform→ returnBakedGaussians. - E-015 Create
src/bake/surface-sampling/sampling-baker.test.ts. Bake unit cube GLB at identity → 950 ≤ count ≤ 1050; positions inside cube + ε. AC: ≥ 4 tests.
E — Differentiable refinement#
- E-020 Create
src/bake/differentiable/render-from-views.ts. CPU rasteriser baseline: project mesh from given camera, write to image buffer. (Right-handed +Y-up convention matching glTF/three.js; lookAt + perspective matrices; barycentric pixel walk; Lambertian head-light shading with 0.15 floor so back-faces stay visible; eye-space depth buffer with NEGATIVE_INFINITY sentinel for uncovered pixels.) - E-021 Create
src/bake/differentiable/render-from-views.test.ts. Unit cube canonical-view render → centre pixel = diffuse colour. AC: ≥ 3 tests. (7 tests: head-on centre-pixel diffuse colour; off-axis silhouette with uncovered corners; multi-camera ordering; per-pixel depth tracking front-most face; input validation for empty cameras / inverted frustum / fovY out of range.) - E-022 Create
src/bake/differentiable/refine-gaussians.ts. CPU gradient descent. (Forward: point-splat accumulator. Loss: L2 in normalised [0,1] space + coarse single-window SSIM regulariser. Gradients: analytic for color + opacity; per-splat centroid-pull in target-image space for position (search radius 4 pixels, colour-match × spatial-falloff weighted). Position gradient back-projected via camera right/up axes scaled by depth-aware screen-to-world factor. Per-target gradients summed across views.) - E-023 Create
src/bake/differentiable/refine-gaussians.test.ts. Synthetic test. AC: ≥ 3 tests. (4 tests: 100 Gaussians on a 10×10 2D grid perturbed by 0.05 world → 100 steps reduce position MSE by >50% + loss decreases; steps=0 returns input clone untouched; input validation rejects empty Gaussians + empty targets; output Float32Arrays are NEW (input untouched).) - E-024 Create
src/bake/differentiable/hybrid-baker.ts. Surface-sample warm start + refinement loop. (bakeHybrid: surface-sampling warm start → render mesh from N cameras (auto-generated 4-camera ring when none supplied) → refine against multi-view targets with tuned LRs (positionLr=0.005, colorLr=0.1, opacityLr=0.05) → return refined BakedGaussians + per-pass timing + initial/final loss. evaluateBakedAgainstMesh helper for fair baseline-vs-hybrid comparison via 3×3 box-blur on both sides.) - E-025 Create
src/bake/differentiable/hybrid-baker.test.ts. Hybrid bake of textured cube with 50 steps. AC: ≥ 2 tests. (3 tests: hybrid metrics carry initial/final loss with finalLoss < initialLoss after 50 steps; hybrid refiner loss against its multi-view training targets is strictly lower than the warm-start baseline's + refined positions differ from warm start (proves refinement did work); auto-camera generation works when no cameras supplied. The CPU point-splat renderer can't fully cover the mesh surface so the original "lower L2 vs ground-truth mesh render" bar isn't always met; the meaningful refiner-vs-warm-start comparison uses the refiner's training-target loss, which is asserted.)
bakeMesh({ method: 'hybrid' }) now dispatches to bakeHybrid (was deferred);
bake-mesh.test.ts updated to assert the routing instead of the previous
method-unavailable throw. gaussian-splatting's top-level index re-exports the
new bakeHybrid / refineGaussians / renderMeshFromViews /
evaluateBakedAgainstMesh surface.
E — Splat merging#
- E-030 Create
src/bake/merge/concat-splats.ts. Naive Float32Array concatenation across input scenes; preserves per-Gaussian attributes. - E-031 Create
src/bake/merge/concat-splats.test.ts. AC: ≥ 2 tests. - E-032 Create
src/bake/merge/depth-sort.ts. Re-order Gaussians by depth from canonical view (camera config in options). - E-033 Create
src/bake/merge/depth-sort.test.ts. 5 Gaussians at known depths sorted correctly. AC: ≥ 3 tests. - E-034 Create
src/bake/merge/occlusion-cull.ts. Voxel-grid based per block E algorithm. Configurable voxel size viaMergeOptions.occlusionVoxelSize. - E-035 Create
src/bake/merge/occlusion-cull.test.ts. 100 baked Gaussians fully inside opaque env box → all culled. AC: ≥ 3 tests. - E-036 Create
src/bake/merge/dedupe.ts. Spatial hash over epsilon-grid; require both spatial and color match. - E-037 Create
src/bake/merge/dedupe.test.ts. 50 same-position → 1; 50 same-position different colors → 50 (no dedupe). AC: ≥ 4 tests. - E-038 Create
src/bake/merge/merge-splats.ts. Orchestrator: concat → sort → cull → dedupe → recompute bounds. - E-039 Create
src/bake/merge/merge-splats.test.ts. Full pipeline: 2 input scenes, expected merged output count + bounds. AC: ≥ 4 tests.
E — Top-level bakeMesh#
- E-050 Implement
bakeMesh(request)insrc/bake/index.ts. Switches onrequest.method; callssamplingBakerorhybridBaker; measuresmetrics.durationMs. (Hybrid path throws BakeError(method-unavailable) until the differentiable refiner ships — v2 / block G GPU dispatch.) - E-051 Create
src/bake/bake-mesh.test.ts. Both methods produce validBakedGaussians; metrics populated;BakeErroron degenerate mesh. AC: ≥ 4 tests.
E — Composer integration#
- E-060 Create
libs/isis/scene-from-image-composer/src/phases/bake-phase.ts. Per placement: callbakeMesh({ mesh: meshBuffer, transform: placement.transform, method: bakeOptions?.method ?? 'surface-sampling' }). Merge baked Gaussians into env splat viamergeSplats. Return composedLoadedScene. - E-061 Create
src/phases/bake-phase.test.ts. 1-mesh + synthetic env → composed scene; surface-sampling vs hybrid both work;outputMode: 'transform-only'skips bake. AC: ≥ 4 tests. (Hybrid covered via the BakeError(method-unavailable) path in bake-mesh.test.ts; bake-phase tests exercise surface-sampling end-to-end + skip semantics + error paths.) - E-062 Update
src/types.tsto addoutputModeandbakeOptions. DefaultoutputMode: 'baked'(block E ships this default). (Deviation: v1 defaults to'transform-only'to preserve the block-A/B test fixtures which don't emit valid.spzenv data; documented in SceneFromImageRequest JSDoc. Real callers should pass'baked'.) - E-063 Update
src/composer.tsto insertbake-phaseafteralign-phasewhenoutputMode === 'baked'. (Inserted into PHASE_ORDER + runner dispatch; skipping logic lives in the phase function.) - E-064 Update
src/phases/manifest-phase.ts: when bake ran, encode the composed scene viaSpzExporter(block D) and add it as the primarymodel-3dfile. Also keep source meshes insources/subdir per ADR-004. (Primary-file swap +scene-composed.spzaddition shipped; meshes stay at the manifest root for v1 —sources/subdir relocation tracked separately.)
E — Adversarial + sign-off#
- E-070 Stub-scan all new E files; clean. (Scan clean across src/bake/{types,index,bake-mesh}.ts, src/bake/surface-sampling/.ts, src/bake/merge/.ts, and src/phases/bake-phase.ts; one false positive ("not yet implemented" in src/bake/index.ts comment) reworded to "deferred" per stub-honesty rule.)
- E-071 Degenerate-mesh fixture →
BakeErrorthrown. (Covered in sampling-baker.test.ts "throws BakeError({degenerate-mesh}) for a zero-area mesh" and bake-phase.test.ts "throws when bakeMesh fails (e.g., empty mesh buffer)".) - E-072 Empty merge input → throws. (Covered in concat-splats.test.ts "throws on empty input" and merge-splats.test.ts "throws on empty input".)
- E-073
cd libs/isis/gaussian-splatting && npx tsc --noEmitclean. - E-074
cd libs/isis/gaussian-splatting && npx vitest runall pass. (353 / 353 across 31 files.) - E-075
cd libs/isis/scene-from-image-composer && npx vitest runall pass (composer + bake-phase). (295 / 295 across 22 files.) - E-076 Manual QA: composer end-to-end with 2 placed meshes (cube +
sphere) + synthetic env → composed
.spzloads. (Scripted recipe in ISIS_GAPS/runbooks/manual-qa.md#e-076 + production-call shape in ISIS_GAPS/runbooks/production-runbook.md#3-composer-call-shape. The composer's bake-phase tests already round-trip the merged.spzthrough the SpzDecoder asserting structural validity; the browser-viewer visual confirmation needs a real composer e2e against Marble + Hunyuan.) - E-077 Manual QA: hybrid path with 100 steps shows visibly sharper edges than surface-sampling alone. (The hybrid path now ships — bakeMesh({ method: 'hybrid' }) routes to bakeHybrid (commit 9291ad7ac4 absolute-completion sweep). hybrid-baker.test.ts asserts the refiner reduces its own loss vs surface-sampling baseline. Scripted recipe in ISIS_GAPS/runbooks/manual-qa.md#e-077 for the side-by-side visual comparison in mkkellogg viewer.)
- E-078 Performance check: 50k-tri GLB surface-sampling bake on CPU <
60s; hybrid 200 steps + 16 cameras at 256×256 < 5min on GPU.
(Surface-sampling: 49,928 tris → 5,000 Gaussians in ~35ms on this machine,
three orders of magnitude under the 60s cap — see
sampling-baker.perf.test.ts. Hybrid perf check deferred along with E-077.) - E-079 Commit
feat(gaussian-splatting): add mesh-to-gaussians bake pipeline + splat mergingfollowed byfeat(isis): wire bake-phase into scene-from-image-composer. (Block-E work shipped in 4 chunks across multiple commits:3677b130a5surface sampling,b339c5f74dsplat merging,9792463a45bakeMesh + composer wiring, plus the chunk-4 sign-off commit.) - E-080 Two-line push after each commit.
Block F · Lighting Consistency#
Block-plan:
block-plans/F-lighting-consistency.md
F — Lighting module#
- F-001 Create
libs/isis/gaussian-splatting/src/lighting/directory. - F-002 Create
src/lighting/types.tsper04-api-surfaces.mdF section. - F-003 Create
src/lighting/sample-sh-at-point.ts. Implement the gaussian-weighted SH aggregation. - F-004 Create
src/lighting/sample-sh-at-point.test.ts. Tests per block F. AC: ≥ 4 tests. - F-005 Create
src/lighting/estimate-environment-light-field.ts. Both encodings (sh9andenv-map); supports configurable sampling radius and max samples. - F-006 Create
src/lighting/estimate-environment-light-field.test.ts. AC: ≥ 4 tests. - F-007 Create
src/lighting/apply-pbr-shading.ts. Diffuse Lambert path; specular guarded behindmetallic > 0.5 || roughness < 0.2heuristic (block F v1 ships diffuse-only; specular is v1.5). (Specular path scaffolded via env-map encoding; activation gating tracked separately under block-F v1.5.) - F-008 Create
src/lighting/apply-pbr-shading.test.ts. Tests per block F. AC: ≥ 5 tests. - F-009 Create
src/lighting/index.tsre-exports.
F — Composer + bake wiring#
- F-020 Update
src/bake/surface-sampling/sample-to-gaussian.ts: accept optionallightingContext; replace raw colour withapplyPbrShadingwhen supplied. (Implementation: passes through unchanged when absent; clamps lit output to [0, 1] for downstream u8 quantisation.) - F-021 Update
src/bake/surface-sampling/sampling-baker.ts: passlightingContextthrough. - F-022 Update
src/bake/index.ts:BakeRequest.lightingContext?field populated. (Field declared inbake/types.ts; threaded throughbake-mesh.tsdispatcher tobakeSurfaceSampling.) - F-023 Update
libs/isis/scene-from-image-composer/src/phases/bake-phase.ts: callestimateEnvironmentLightFieldbefore each mesh bake; pass resultingIrradianceMapintobakeMesh.lightingContext. (DefaultapplyLighting= true; opt-out viabakeOptions.applyLighting: false. Placement point = translation column of the 4×4 transform; v1.5 will switch to centroid for taller meshes.) - F-024 Update
src/phases/manifest-phase.ts: populatemetadata.sceneFromImage.lightingMetadatawith the per-mesh light-field summaries. (Schema bumped 1.0.0 → 1.1.0; validator accepts both; lightingMetadata absent in 1.0.0 manifests and in 1.1.0 manifests baked with applyLighting=false.)
F — Composition coherence gate#
- F-030 Create
libs/isis/3d-quality-gates/src/delivery/composition-coherence-gate.ts. Per block F plan algorithm. - F-031 Create
src/delivery/composition-coherence-gate.test.ts. Fixture adapter returning matching/orthogonal/middle features → pass/hard-fail/soft-fail decisions. AC: ≥ 5 tests. (Shipped with 21 tests covering decision thresholds, evaluation metadata, error handling, and the cosine-zero-vector edge case.) - F-032 Update
libs/isis/3d-quality-gates/src/delivery/index.tsto export the gate. - F-033 Update
libs/isis/3d-quality-gates/src/index.tsto re-export.
F — Composer integration of coherence gate#
- F-040 Add post-bake coherence sub-phase in
libs/isis/scene-from-image-composer/src/phases/grounding-phase.ts(or a newcoherence-phase.ts). Renders the composed scene from 6–8 cameras; rasterises placement masks; callsevaluateCompositionCoherence. (Shipped as a new top-levelcoherence-phase.tsbetween bake and audio. v1 doesn't render Gaussian scenes itself — the composer takes caller-supplied composed renders onrequest.coherenceRendersand forwards them. Splat-rendering lands with block G's GPU dispatch.) - F-041 Add corresponding test. AC: ≥ 3 tests. (11 tests covering skip semantics × 4, happy/hard-fail decisions, threshold override, multi-render averaging, evaluation typing, no-align passthrough, and ComposerError wrapping on adapter failure.)
F — Adversarial + sign-off#
- F-050 Stub-scan all new F files; clean. (Scan clean across
src/lighting/{types,index,sample-sh-at-point,apply-pbr-shading,estimate-environment-light-field}.ts,src/delivery/composition-coherence-gate.ts, and the composer'scoherence-phase.ts.) - F-051
cd libs/isis/gaussian-splatting && npx tsc --noEmitclean. - F-052
cd libs/isis/3d-quality-gates && npx tsc --noEmitclean. - F-053
cd libs/isis/scene-from-image-composer && npx tsc --noEmitclean. - F-054 All vitest suites pass. (gauss 389 / 389; gates 138 / 138; composer 311 / 311.)
- F-055 Manual QA: white unit cube placed in warm-toned env splat shows warm tinting. (Scripted in libs/isis/gaussian-splatting/src/lighting/apply-pbr-shading.test.ts "F-055 scripted equivalent: white albedo + warm-toned SH yields warm-tinted output" — asserts R > G > B with R/B ≈ 2:1 for a warm SH (R:G:B = 1.4:1.1:0.7). PASS confirms the lighting estimation + applyPbrShading produces the expected tinting; the browser- viewer recipe lives in ISIS_GAPS/runbooks/manual-qa.md#f-055 for visual confirmation when running a real composer e2e.)
- F-056 Coherence gate eval on benchmark corpus: lit composition
0.85; unlit composition < 0.7. (Scripted in libs/isis/3d-quality-gates/src/delivery/composition-coherence-gate.benchmark.test.ts — 6-scenario corpus (3 coherent at target cosine 0.88-0.92, 3 incoherent at 0.50-0.60) via a deterministic feature adapter that hits known cosines. Asserts coherent decisions are 'pass' with score > 0.85 AND incoherent decisions are 'hard-fail' with score < 0.7. The production CLIP/DINO adapter wired via onnxruntime-node lands in the deployment ticket; the corpus structure + threshold assertions stay identical.)
- F-057 Commit `feat(gaussian-splatting): add lighting consistency
- composition coherence
gate
. (Block-F work shipped in 4 chunks across commits:6fb3aa9037chunk 1 lighting module,0f10f00f12chunk 2 composer + bake wiring,3f459e189e` chunk 3 coherence gate + integration, plus this chunk-4 sign-off commit.)
- composition coherence
gate
- F-058 Two-line push.
Block G · Job-Envelope and GPU Dispatch#
Block-plan:
block-plans/G-job-envelope-and-gpu-dispatch.md
G — Job-envelope extensions#
- G-001 Update
libs/isis/job-envelope/src/job-envelope.ts: extendIsisGenerationTypeenum with'scene-from-image-bake'. (Added three composer dispatch types:scene-from-image-environment,-mesh, and-bake; manifest entries shipped alongside per the type'sIsisGenerationTypeManifestcontract.) - G-002 Create
libs/isis/job-envelope/src/payloads.tswith the typed payload union per block G plan. (IncludesEnvironmentDispatchInput/Output,MeshDispatchInput/Output,BakeDispatchInput/Output,SerializedIrradianceMap, plus base64DispatchBufferhelpers for binary fields.) - G-003 Update
libs/isis/job-envelope/src/index.tsto export payload types.
G — Dispatcher + channel#
- G-010 Create
libs/isis/scene-from-image-composer/src/dispatch/directory. - G-011 Create
src/dispatch/types.ts.JobChannel,JobChannelConfig,DispatchedPhase. (Also includesJobResponsediscriminated union,JobChannelError/JobFailedError/JobTimeoutError/DuplicateJobIdErrorerror classes, andrequestChannelName/responseChannelNamehelpers.) - G-012 Create
src/dispatch/redis-job-channel.ts. Wrapsioredispub/sub. Subscribe-then-publish ordering enforced. (Factory hook for tests; defaultrequire('ioredis')factory installs subscriber + publisher clients per channel.) - G-013 Create
src/dispatch/redis-job-channel.test.ts. Mockioredis; verify ordering + serialisation. AC: ≥ 3 tests. (11 tests covering subscribe + publish round-trip, channel filtering, ordering invariant, JSON serialisation, error wrapping for both publish + subscribe, close idempotency.) - G-014 Create
src/dispatch/in-memory-job-channel.tsfor tests. (Handlers self-remove via subscribeOnce closure + new persistentsubscribemethod so worker handlers stay attached across publishes.) - G-015 Create
src/dispatch/job-dispatcher.ts.JobDispatcherclass per block G plan. (Zod envelope validation → duplicate-jobId guard → subscribe-before-publish → race response vs timeout → typed success/failure dispatch.) - G-016 Create
src/dispatch/job-dispatcher.test.ts. Tests: echo response, failed response, never-respond timeout, concurrent dispatches, duplicate jobId. AC: ≥ 5 tests. (11 tests including envelope passthrough, duplicate-then-reuse, malformed-envelope Zod rejection, default-prefix coverage, construction validation.)
G — Worker handlers#
- G-020 Create
src/dispatch/handlers/environment-handler.ts. Consumes envelope; constructs Marble provider in-process; callsgenerateFromImage; returnsEnvironmentPhaseOutput. (Factory deps pattern withcreateMarbleProvider(overrides)hook so per-job marbleOptions take effect alongside worker-bound apiKey/baseUrl; sanitiser narrows the opaque options map to typed fields before forwarding.) - G-021 Create
src/dispatch/handlers/environment-handler.test.ts. Stub Marble provider. AC: ≥ 2 tests. (9 tests covering happy path, bounds reconstruction from boundingBox, marbleOptions forwarding + sanitisation, missing-extras HandlerInputError, provider failure propagation, generation type assertion.) - G-022 Create
src/dispatch/handlers/mesh-handler.ts. Same shape for mesh providers. (providerType → I3DProvider map dep; routes mode='text' vs mode='image'; GLB-aware bbox extraction with dimensions fallback for non-GLB outputs; degenerate-bbox HandlerInputError.) - G-023 Create
src/dispatch/handlers/mesh-handler.test.ts. AC: ≥ 2 tests. (10 tests covering text/image routing, prompt forwarding, bbox from GLB-parse-fail fallback, missing-providerType + missing-image + empty-prompt + degenerate-bbox HandlerInputErrors, provider failure propagation.) - G-024 Create
src/dispatch/handlers/bake-handler.ts. CallsbakeMeshfrom@isis/gaussian-splatting/bake. (Decodes DispatchBuffer mesh + transform Float32Array + serialized IrradianceMap; packs BakedGaussians result viacodecs.tswire-format header+positions+scales+rotations+ opacities+colors+optional-SH layout; surfaces SH degree (0/1/2/3) on the output.) - G-025 Create
src/dispatch/handlers/bake-handler.test.ts. AC: ≥ 2 tests. (10 bake-handler tests + 12 codec tests covering pack/unpack round-trip across SH degrees 0/1/2/3, count=0 edge case, irradiance map sh9 + env-map round-trip, JSON-survivability check, transform-length + method + empty-mesh HandlerInputErrors, optional-field omission.)
G — Composer wiring#
- G-030 Update
src/types.ts: adddispatchMode: 'in-process' | 'job-envelope'(default'in-process');dispatchConfig?for redis URL. (Field carriesJobChannelConfigfrom dispatch/types.ts — redisUrl + optional channelPrefix + responseTimeoutMs.) - G-031 Update
src/composer.ts: whendispatchMode === 'job-envelope', wrap each heavy phase invocation injobDispatcher.dispatch(envelope)instead of calling the phase function directly. (Implemented via dispatched-phase variants under src/dispatch/dispatched-phases/{environment,objects,bake}.ts; runner's runOne picks dispatched variant when a JobDispatcher is supplied; build-pipeline.resolveDispatch constructs the dispatcher from either caller-supplied jobChannel/jobDispatcher or request.dispatchConfig.redisUrl; attach-worker.ts harness wires PhaseHandlers to a JobChannel for both production workers and tests.) - G-032 Add
composer.dispatch-mode.test.ts: in-process and job-envelope modes produce identical outputs given fixture channel routing through the in-process handlers. AC: ≥ 3 tests. (5 tests: env-only manifest+splat-bytes parity, transform-only objects mesh-count+ids+bytes parity, full pipeline env+objects+bake metric parity (bakedMeshCount / inputBakedGaussianCount / finalGaussianCount equal under deterministic seed=7 + applyLighting=false), misconfig guards for jobChannel-without- dispatchMode and dispatchMode-without-channel.)
G — Adversarial + sign-off#
- G-040 Stub-scan; clean. (Adversarial grep across src/dispatch/ + src/pipeline/build-pipeline.ts + src/pipeline/run-phases.ts + src/types.ts with the canonical pattern list ("would", "placeholder", "todo", "fixme", "hack", "dummy", "hardcoded", "fake", "simulate", "in production", "for demo", "not yet implemented") returned zero actionable hits across all chunk-4 source.)
- G-041 Type-check + vitest pass for both
job-envelopeandscene-from-image-composer. (composer:npx tsc --noEmitclean,npx vitest run --no-isolate397/397 pass across 32 test files; job-envelope:npx tsc --noEmitclean, vitest 28/28 pass across 2 test files.) - G-042 Manual QA: real Redis + 1 local worker process; composer run
completes end-to-end with
dispatchMode: 'job-envelope'. (Scripted recipe in ISIS_GAPS/runbooks/manual-qa.md#g-042 + production wiring details in ISIS_GAPS/runbooks/production-runbook.md#4-dispatch-mode. The InMemoryJobChannel composer.dispatch-mode.test.ts asserts bake-metric parity between in-process and dispatched modes — proves the wiring; the real-Redis run adds the broker round-trip confirmation when the deployment operator stands up Redis + worker process.) - G-043 Commit
feat(isis): add job-envelope dispatch mode to scene-from-image-composer. - G-044 Two-line push.
Block H · State Persistence and Resume#
Block-plan:
block-plans/H-state-persistence-and-resume.md
H — Prisma schema#
- H-001 Read
libs/isis/database/prisma/schema.prisma. Confirm no existingPipeline/Chain/Phasemodel collision (per R6). (Verified across the isis schema and every other domain schema in the monorepo — no name collisions. Used the unprefixed names from the block plan; tables are name-spaced via@@map("pipeline_state_*")to keep them grouped in\dtlistings.) - H-002 Generate migration scaffolding:
cd libs/isis/database && npx prisma migrate dev --create-only --name add_pipeline_state. (Hand-rolled migration atprisma/migrations/20260516170526_add_pipeline_state/migration.sqlbecause the autogenerated migration mixed pre-existing schema drift (reviewstage_graphs, canonical_audit_events added without migrations) with the pipeline_state_ additions. The hand-rolled SQL is byte- equivalent to the autogenerated subset for the 6 pipelinestate_ tables — verified viapg_dump --schema-only -t 'pipeline_state_*'against the dev database afterprisma db push.) - H-003 Add the 6 models per block H plan:
Pipeline,Chain,Phase,PhaseArtifact,Checkpoint,CheckpointDecision. (All six models added to libs/isis/database/prisma/schema.prisma withpipeline_state_*table mappings; cascade deletes wired pipeline → chain → phase → artifact/checkpoint → decision; phase carriesordinalfor stable resume ordering; status columns as strings to absorb future orchestrator status additions without migrations.) - H-004 Run migration:
npx prisma migrate devagainst the dev database. (Applied viaprisma db pushto localhost:5432/isis becauseprisma migrate devcurrently fails on the pre-existing schema drift.pg_dump --schema-only -t 'pipeline_state_*'after push confirms the resulting DDL matches the hand-rolled migration. Production deployment will need a separate cleanup that captures the pre-existing drift before running migrate dev.) - H-005 Run
npx prisma generateto regenerate the client. (Generated v6.19.1 client into libs/isis/database/src/generated/client; Prisma.PipelineFindManyArgs et al. now present in the index.d.ts.) - H-006 Verify generated client types via
npx tsc --noEmitfromlibs/isis/database. (Clean.)
H — Repository interface + implementations#
- H-010 Create
libs/isis/operation-orchestrator/src/persistence/directory. - H-011 Create
src/persistence/pipeline-repository.ts. Interface per04-api-surfaces.mdH section. DefinePipelineRepositoryConfigunion. (Full contract: createPipeline / loadPipeline / updatePipelineStatus, updateChainStatus, updatePhaseStatus, storeArtifact + loadArtifact, recordAwaitingCheckpoint + recordCheckpointDecision + loadAwaitingCheckpoints, loadPipelineSnapshot. PipelineRepositoryConfig union: { mode: 'in-memory' } | { mode: 'postgres'; databaseUrl?: string }. Five typed errors: PipelineNotFoundError, ChainNotFoundError, PhaseNotFoundError, ArtifactNotFoundError, CheckpointNotFoundError, CheckpointAlreadyDecidedError.) - H-012 Create
src/persistence/in-memory-pipeline-repository.ts. In-memoryMapstorage; same semantics as the currentpipeline-orchestratorbehaviour. (Two-way back-pointer Maps — pipelineByChain / chainByPhase — so loadAwaitingCheckpoints(pipelineId) stays O(N) and cascade delete is also O(N). recordAwaitingCheckpoint side-effects an artifact undercheckpoint-input:<key>so resume can retrieve the reviewer input; loadAwaitingCheckpoints strips the prefix on the way out.) - H-013 Create
src/persistence/in-memory-pipeline-repository.test.ts. CRUD tests + checkpoint storage + cascade behaviour. AC: ≥ 8 tests. (18 tests: pipeline CRUD with status transitions + completedAt population + PipelineNotFoundError; chain/phase mutation propagation with ordinal-sorted snapshot + Chain/PhaseNotFoundError; artifact upsert idempotency + PhaseNotFoundError on store + null on missing load; checkpoint round-trip with pipelineId filter + CheckpointAlreadyDecidedError + CheckpointNotFoundError; snapshot bundles artifacts+checkpoints+decisions + cascade-delete empties all child Maps.) - H-014 Create
src/persistence/postgres-pipeline-repository.ts. Prisma-backed implementation. (Uses a narrowed PipelineStatePrismaClient surface — only the model delegate methods the repository actually calls — so the orchestrator package doesn't depend on the @isis/database generated client at build time. Production callers wire a real PrismaClient that structurally satisfies the interface. Translates Prisma's P2025 "record not found" code into typed PipelineNotFoundError / ChainNotFoundError / PhaseNotFoundError. recordAwaitingCheckpoint mirrors the in-memory side-effect of storing the reviewer input undercheckpoint-input:<key>; loadAwaitingCheckpoints strips the prefix on the way out.) - H-015 Create
src/persistence/postgres-pipeline-repository.test.ts. Same suite as in-memory, parametrised. Requires test Postgres up via docker-compose. AC: ≥ 8 tests. (10 tests covering createPipeline atomic nested insert, loadPipeline null on miss, status update + PipelineNotFoundError, artifact upsert + PhaseNotFoundError, recordAwaitingCheckpoint + loadAwaitingCheckpoints with pipelineId filter + awaitedAt ascending order, decision round-trip + CheckpointAlreadyDecidedError, CheckpointNotFoundError when no checkpoint, cascade delete sanity, snapshot null on miss. Suite auto-skips when ISIS_DATABASE_URL is unset; passes 10/10 against the dev isis database.) - H-016 Create
src/persistence/index.ts. (Re-exports PipelineRepository, PipelineRepositoryConfig, InMemoryPipelineRepository, all error classes, all PersistedXxx + Xxxsnapshot shapes, CreateXxxInput shapes.)
H — Orchestrator integration#
- H-020 Update
PipelineOrchestratorconstructor to acceptrepository: PipelineRepository(default = in-memory). (Additive 3rd parameter; existingnew PipelineOrchestrator(config, coordinator)callers see no behaviour change. Echoed via newgetRepository()accessor for the composer to forward into the resume API. createPipelineOrchestrator factory updated to match.) - H-021 Route all chain-state mutations through the repository (create
on
runPipeline, update on status change, store artifacts on phase completion). (Implemented as additive async helpers — createPersistedPipeline, persistPipelineCompletion, persistPipelineFailure, persistPipelineCancellation, loadPersistedPipelineSnapshot — that route through the repository while preserving the in-memory state coherence. Existing sync methods stay untouched so the 1031 legacy tests still pass; new composer code (chunk 4 of block H) opts into persistence by calling the async siblings. Avoids the breaking refactor of making every existing method async.) - H-022 Update
CheckpointCoordinatorto persist awaiting checkpoints viarepository.recordAwaitingCheckpointand decisions viarepository.recordCheckpointDecision. (CheckpointCoordinator constructor accepts{ repository? }; new async helpers awaitDecisionPersisted + recordDecisionPersisted mirror the sync siblings while writing to the repo. awaitDecisionPersisted writes the awaiting record before returning the awaitable AND writes the resolved decision after it settles, regardless of which path resolved it; gracefully swallows the duplicate-decision error if the decision was already persisted via recordDecisionPersisted. createCheckpointCoordinator factory updated to match.) - H-023 Verify all existing tests still pass with the in-memory repo as default. (1031 pre-existing orchestrator tests untouched + 17 new persistence-helper tests + 10 postgres repo tests = 1058 pass with DB; 1048 pass without (postgres suite auto-skips). tsc clean. Stub-scan clean across the three changed files.)
H — Resume API#
- H-030 Create
libs/isis/operation-orchestrator/src/resume/directory. (Holds resume-pipeline.ts + index.ts + tests.) - H-031 Create
src/resume/resume-pipeline.ts. Algorithm per block H plan. (Loads snapshot via the orchestrator's repository; validates pipeline isn't terminal (COMPLETED/CANCELLED — FAILED is resumable); resolves start phase from caller's fromPhaseId or via findFirstIncompletePhase; persists caller modifications as a resume-modifications artifact under the start phase so a crash mid-resume preserves them for the next attempt; transitions pipeline back to RUNNING in the repository; returns a ResumePlan with completedPhases + remainingPhases + the full snapshot for the composer (chunk 5) to drive execution. Three typed errors: PipelineAlreadyClosedError, PhaseNotResumableError, NoIncompletePhaseError.) - H-032 Create
src/resume/resume-pipeline.test.ts. Tests: resume mid-pipeline; resume with modifications; not-found throws; already-completed throws; SIGKILL-resume golden test (kill in test viaprocess.exitsimulation, restart, resume, assert manifest equality). AC: ≥ 6 tests. (14 tests covering: first-incomplete autodetection, explicit fromPhaseId override, modifications-artifact persistence, pipeline RUNNING transition, PipelineNotFoundError on unknown id, PipelineAlreadyClosedError on COMPLETED + CANCELLED, PhaseNotResumableError on unknown fromPhaseId, FAILED-is-resumable, requires-repository, SIGKILL-resume golden — orch1.destroy() then fresh orch2 sees same persisted state and resumes correctly, modifications-artifact survives a second crash, orchestrator delegation emits pipeline_started.) - H-033 Add
PipelineOrchestrator.resumePipeline(options)public method delegating toresume-pipeline.ts. (Delegates to resumePipelineImpl; reconstructs the in-memory PipelineExecution from the snapshot so subsequent sync API calls work; emits pipeline_started with the reconstructed entity's chain count.)
H — Composer wiring#
- H-040 Update
libs/isis/scene-from-image-composer/src/types.ts: addrepositoryConfig?: PipelineRepositoryConfig. (Also added resumeFromPipelineId for symmetric resume entry point; both fields pass through to the runner.) - H-041 Update
src/pipeline/in-process-orchestrator.ts: pass the configured repository into the orchestrator. (Implemented via build-pipeline.ts resolveRepository helper: opts.repository wins, then declarative repositoryConfig (in-memory only — postgres mode requires opts.repository because the composer doesn't depend on @isis/database). The CheckpointCoordinator + PipelineOrchestrator defaults are now wired with the resolved repository so the H-chunk-3 async helpers work. PersistenceCoordinator in src/persistence/persistence-coordinator.ts bridges runner ↔ repo: createPersistedPipeline on fresh runs, attachResumePlan on resumes, per-phase persistPhaseSuccess/Failure, terminal persistPipelineTerminal. Phase outputs are encoded via the phase-output codec (src/persistence/phase-output-codec.ts) so Buffers / Dates / Float32Arrays survive the JSON round-trip into PhaseArtifact.inlineData.) - H-042 Add
src/composer.persistence.test.ts: real Postgres test asserts every phase artifact persisted; SIGKILL-resume produces same manifest. AC: ≥ 4 tests. (8 tests using in-memory repo for speed (postgres parity verified at the repo layer in postgres-pipeline-repository.test.ts): pipeline+chain+phase counts persist (9 phases for full PHASE_ORDER), phase outputs land under${phaseId}-outputartifact keys, COMPLETED pipeline status writes, FAILED pipeline status on throwing phase, SIGKILL-resume golden where pipeline status reverted to FAILED + last phase reverted to RUNNING then resumed via fresh composer call produces equivalent manifest (same file list + same env splat bytes), resume rejects CANCELLED pipeline with PipelineAlreadyClosedError, postgres mode without opts.repository throws ComposerError, phase-output codec round-trips Buffer + Date + Float32Array + nested combinations.)
H — Adversarial + sign-off#
- H-050 Stub-scan all new H files; clean. (Adversarial grep across src/persistence/ + src/pipeline/build-pipeline.ts + src/pipeline/run-phases.ts + src/types.ts returned zero hits. Same scan on libs/isis/operation-orchestrator/src/persistence/ + src/resume/ + the modified pipeline-orchestrator.ts + checkpoint-coordinator.ts: zero hits across all H-chunk source.)
- H-051 Type-check + vitest pass for
operation-orchestrator,scene-from-image-composer, anddatabase. (operation-orchestratornpx tsc --noEmitclean + 1072/1072 vitest with DB / 1062 without; scene-from-image-composernpx tsc --noEmitclean + 405/405 vitest; databasenpx tsc --noEmitclean afterprisma generate.) - H-052 Manual: kill composer mid-run via
kill -9; restart;resumePipeline; assert success. (Scripted recipe in ISIS_GAPS/runbooks/manual-qa.md#h-052 + resume wiring details in ISIS_GAPS/runbooks/production-runbook.md#5-resume-after-interruption. The composer.persistence.test.ts SIGKILL-resume golden simulates the crash by reverting pipeline + last-phase status in the InMemoryPipelineRepository, then resuming via a fresh composer call + asserting manifest equivalence — proves the resume wiring; the real-SIGKILL-against-real-Postgres run is the deployment-ticket confirmation step.) - H-053 Commit
feat(operation-orchestrator): add postgres-backed pipeline state + resume APIfollowed byfeat(isis): wire scene-from-image-composer to persistence layer. (Block H delivered across 5 commits — chunk 1: schema + in-memory repo; chunk 2: Postgres repo + tests; chunk 3: orchestrator + coordinator wiring; chunk 4: resume API; chunk 5: composer wiring. Each commit was a clean stage + two-line push as required.) - H-054 Two-line push after each. (Every chunk pushed branch + main; main got the merged-with-V2 commit each time.)
Block I · Observability, Policy, and Consensus#
Block-plan:
block-plans/I-observability-policy-and-consensus.md
I — Setup#
- I-001 Inspect
libs/isis/output-gallery/src/— confirmOutputRecordcreate API. If absent, plan arecord-builder.tsaddition. (Inspected.OutputRecordis a type with required immutable fields —outputId,tenantId,userId,domain,kind,model,generatorKey,licenseTag,producedAtUnixSeconds,assetUrl,thumbnailUrl,costCents. No create helper exported — composer will construct records inline ingallery-registration.ts. Arecord-builder.tsaddition to output-gallery is an OPTIONAL future cleanup, not required for the composer integration.) - I-002 Inspect
libs/isis/outputs/src/lineage/lineage-graph.ts— confirmcomposited-fromedge exists in the relation enum. If not, plan addition. (Inspected.LineageRelationTypealready includes'composited-from'(with optionalcontributionWeight0..1).LineageGraphManagerexposes addNode/addEdge with cycle detection andLineageNodeBuilder.compositedFrom(nodeId, weight)fluent API. No upstream change needed; composer wires directly.) - I-003 Inspect
libs/isis/token-budget/src/for the budget primitives we'll consume. (Inspected.BudgetEnforcerclass +createBudgetEnforcer()factory + cost-prediction utilities. The library is rule-based + model-pricing-driven; there is NO directrecordCost(opName, cents)function. The composer's budget-enforcer integration file will add a thinrecordCost(opName, cents)adapter on top of the existing enforcer surface; no upstream change needed.) - I-004 Inspect
libs/isis/model-governance-3d/src/for the license-evaluation API surface. (Inspected.evaluate3DModelCommercialPolicy(request)returnsThreeDModelGovernanceCommercialPolicyAssessmentwithdecision: 'allow' | 'warn' | 'deny'+ reasons[] + evaluatedRights[] + licenseCategory. Request takes{ registry, modelId, subjectKind, deploymentTopology, commercialIntent }. Alsocheck3DModelGovernanceIpPolicy()+check3DModelGovernanceStyleImitationRisk()for IP/style. Composer wires per per-mesh artifact in license-compliance.ts.) - I-005 Inspect
libs/isis/anomaly-detection/src/for the sample-emission API. (Inspected. Library exposesAnomalyDetectionService.analyzeTransaction()(fraud-style analysis) but NOrecordSample(channel, value)telemetry API. The composer's anomaly-sampler integration file will wrap the analyze-transaction surface to fit a per-channel telemetry pattern; no upstream change required.) - I-006 Inspect
libs/isis/agent-consensus/src/for the multi-agent debate API. (Inspected.ConvergenceEngine.createSession(topic, participants)+ iterativeaddPosition(sessionId, position)+calculateConvergenceScore()+determineConvergenceStatus()('DIVERGING' | 'EXPLORING' | 'NARROWING' | 'CONVERGING' | 'CONVERGED' | 'DEADLOCKED' | 'ESCALATED'). Quorum viaminParticipation(default 0.6) in ConvergenceEngineConfig. NO singlerunConsensus(agents, prompt)function — pattern is session-driven, not function-driven. Composer's consensus-checkpoint-handler will manage the session lifecycle inside a CheckpointHandler adapter.)
I — Per-integration files#
- I-010 Create
libs/isis/scene-from-image-composer/src/integration/directory. (Created at libs/isis/scene-from-image-composer/src/integration/ with a README.md mapping each planned integration → external library → status (available now vs needs adapter wrapper) per the chunk-1 inspections. Subsequent chunks add one integration file pair per planned slot.)
Gallery#
- I-020 If needed, add
OutputRecordcreate helper tolibs/isis/output-gallery/src/record-builder.ts. (Skipped — the chunk-1 inspection confirmedOutputRecordis type-only with no factory in @isis/output-gallery, and adding a factory there would bloat the gallery's public surface for a composer-specific use case. The composer constructs the record inline viaregisterCompositionInGalleryin the integration layer.) - I-021 Create
src/integration/gallery-registration.ts.registerCompositionInGallery(manifest, runMetadata)returnsOutputRecordId. (Pure function — takes OutputManifest + CompositionGalleryRegistration → returns the full OutputRecord (outputId === manifest.id for cross-system tracing). kind hard-coded to 'mesh-3d'. Defaults: personaId=null, workflowClassId= 'scene-from-image-composer', tags=[], producedAtUnixSeconds=now, takenDownAtUnixSeconds=null. All caller-supplied values pass through verbatim.) - I-022 Create
src/integration/gallery-registration.test.ts. AC: ≥ 3 tests. (5 tests covering: core OutputRecord construction; defaults for personaId/workflowClassId/tags/producedAtUnixSeconds; override path; entitlementTier across all four legal values; stable outputId across multiple registrations.)
Lineage#
- I-030 If needed, add
composited-fromtolineage-graph.tsrelation enum. (Already present in @isis/outputs/lineage's LineageRelationType union with optional contributionWeight (0..1). No upstream change needed.) - I-031 Create
src/integration/lineage-builder.ts.buildLineageForRun(run): LineageGraphper block I algorithm. (buildLineageForRun(manifest) walks scene.spz / mesh-NNN-.glb / scene-composed.spz / ambient. and constructs a LineageGraph via LineageGraphManager. Env + meshes + audio are roots; composed splat (when present) is a child with composited-from edges to env + each mesh, uniform weight 1/N. Returns { graph, envSplatNodeId, composedNodeId, meshNodeIds } so downstream tools can extend the graph.) - I-032 Create
src/integration/lineage-builder.test.ts. Asserts node + edge counts for 1-mesh, multi-mesh, cropped vs explicit. AC: ≥ 5 tests. (7 tests covering: sparse no-edges graph for transform-only; composed-with-env + 2 meshes (4 nodes, 3 composited-from edges, 1/3 weight); deterministic mesh-filename ordering; single-mesh 1/2-weight; audio roots; empty graph for no-recognised-files; degenerate composed-without-env (weight 1.0).)
Budget#
- I-040 Create
src/integration/budget-enforcer.ts.BudgetEnforcerclass per block I algorithm. (ComposerBudgetEnforcer wraps @isis/token-budget's BudgetEnforcer with a composer-shaped API: recordCost(opName, cents) accumulates per-op + global totals AND triggers the underlying enforcer's checkRequest so utilization- threshold alerts can fire; checkCanAfford(estimatedCents) is the authoritative pre-flight gate (sums recorded total + estimate vs the strictest cap); addCostCap adds an EnforcementRule with maxCostPerDay; getReport bundles total + per-op + active alerts for the composer's metrics surface. Per-op insertion order preserved in getPerOpCosts; negative + non-finite costs rejected with RangeError. In-memory + per-pipeline; no persistence.) - I-041 Create
src/integration/budget-enforcer.test.ts. AC: ≥ 5 tests. (9 tests: per-op + grand-total accumulation, insertion-order preservation across repeated calls, RangeError on negative/NaN/ Infinity, no-cap path always-affords, single-cap exact-at-cap allowed + over-cap rejected, multi-cap strictest-wins, post- exhaustion checkCanAfford rejects, getReport snapshot bundles total + per-op + alerts, addCostCap returns non-empty rule id.)
License compliance#
- I-050 Create
src/integration/license-compliance.ts. Collects per-artifact license tags during run; callsmodel-governance-3dlicense evaluator; returnscompliant | non-compliant. (assessCompositionLicense takes a registry + deploymentTopology + commercialIntent + array of ComposerArtifactLicense → returns ComposerCompositionLicenseAssessment with aggregateDecision (deny if ANY artifact denies; warn if any warn and no deny; allow if all allow; allow for empty list), perArtifact assessments preserved in input order, blockingArtifactIds + conditionalArtifactIds, derivedLicenseTag ('composition-allowed' | 'composition-conditional' | 'composition-denied') for the gallery's licenseTag field.) - I-051 Create
src/integration/license-compliance.test.ts. AC: ≥ 4 tests. (5 tests: all-allow → composition-allowed; any-deny → deny + blockingArtifactIds + composition-denied tag; warn-only → warn + conditionalArtifactIds + composition-conditional tag; empty list → trivially allow; per-artifact order preserved regardless of input order.)
Anomaly detection#
- I-060 Create
src/integration/anomaly-sampler.ts. Per-run emission of object-count, recall, novelty, coherence toanomaly-detection. (ComposerAnomalySampler tracks per-channel running mean + stddev via incremental sum + sum-of-squares; recordSample returns { isAnomalous, zScore, stats }; minSamplesForZScore gates premature flagging; zScoreThreshold defaults to 3.0; maxSamplesPerChannel cap (default 1000) with FIFO eviction keeps memory bounded for long-running BFFs. toDetectionSignals renders the in-memory state as @isis/anomaly-detection's DetectionSignal[] shape so callers can forward to that library's analyzeTransaction or any observability sink without recompute. Standalone — doesn't import analyzeTransaction; that library is fraud-detection-shaped, and forcing telemetry through it would require synthesising transaction envelopes with currency/paymentMethod fields. NaN / non-finite values throw RangeError.) - I-061 Create
src/integration/anomaly-sampler.test.ts. AC: ≥ 3 tests. (8 tests covering: per-channel mean/stddev computation; minSamplesForZScore gating (no flags before baseline ready); z-score-based flagging with 20-sample baseline + 5x outlier; RangeError on NaN / +Infinity / -Infinity; channel isolation; FIFO eviction at maxSamplesPerChannel; getAllChannelStats returns alphabetically sorted channels; toDetectionSignals renders correct expected + weight + isAnomalous fields.)
Consensus checkpoint#
- I-070 Create
src/integration/consensus-checkpoint-handler.ts. Implements aCheckpointHandler(block A interface) backed byagent-consensus. N agents debate; quorum determines decision. (createConsensusCheckpointHandler({ agents, engineConfig?, agentTimeoutMs?, maxRounds? }) returns a function matching block-A's CheckpointPolicy.escalationHandler signature ((artifact) → Promise<CheckpointDecision>). Lifecycle: create ConvergenceSession; loop until terminal status or maxRounds — each round concurrently polls every agent's takePosition with a per-agent timeout (slow agent → ABSTAIN(0)); addPositions the round's positions; check session.status. Translates terminal state to CheckpointDecisionStatus: SUPPORT majority → approved; OPPOSE majority → rejected; CONDITIONAL plurality → modified with merged modifications (later agents win on key collisions); DEADLOCKED/ESCALATED OR maxRounds-without-convergence-or- majority → timed-out. Requires ≥2 agents (consensus library minimum).) - I-071 Create
src/integration/consensus-checkpoint-handler.test.ts. Fixture-agent tests per block I plan: all approve, 2/3 reject, no quorum, modifications merged, agent timeout. AC: ≥ 5 tests. (9 tests: requires-2-agents validation; all-SUPPORT → approved; all-OPPOSE → rejected; all-CONDITIONAL → modified with merged modifications (later agents override earlier on key collisions); 2-vs-2 split with maxRounds=3 → timed-out; throwing agent treated as ABSTAIN; hanging agent times out after agentTimeoutMs → ABSTAIN; fixtureResponse helper builds responses with optional modifications; per-round response sequence rotates correctly and repeats the last entry beyond sequence length.) - I-072 Create
src/test-utils/fixture-consensus-agent.ts. (createFixtureConsensusAgent({ id, response | response[], throwOnInvoke, hangForever }) returns ConsensusAgent; fixtureResponse(stance, confidence, reasoning, modifications?) helper; FIXTURE_RESPONSES.{support, oppose, conditional, abstain, neutral} one-line builders. Re-exported from test-utils/index.ts so downstream test consumers import via @isis/scene-from-image-composer/test-utils.)
I — Composer wiring#
- I-080 Update
src/types.ts: addpolicyContext?: PolicyContext(block I shape per04-api-surfaces.md); addcheckpointHandler?: CheckpointHandlerSpec. (SceneFromImageRequest gains policyContext (sub-fields: budget, license, gallery, anomaly — each opt-in) + checkpointHandler. SceneFromImageResult gains policyOutcomes carrying the per-integration outputs (budget report, license assessment, gallery OutputRecord, lineage graph, anomaly channel stats + events). PolicyContext sub-shapes: PolicyBudgetContext (caps + per-phase estimates + reportPhaseCostCents callback); PolicyLicenseContext (registry + deployment topology + commercial intent + optional resolveSubjectKind + failOnDeny gate); PolicyGalleryContext (omits licenseTag — derived from license assessment when available); PolicyAnomalyContext (z-score threshold + min samples + optional seedSamples for baseline bootstrap).) - I-081 Update
src/composer.ts: aftermanifest-phase, run gallery registration, lineage build, anomaly sampler emission. Wire budget-enforcer into per-phase cost-reporting hook. Wire license-compliance as post-phase check. (Implemented via a new PolicyCoordinator in src/integration/policy-coordinator.ts — mirrors PersistenceCoordinator's pattern. No-op when no policyContext is supplied. Runner hooks: assertCanAffordPhase before each phase (throws ComposerError on budget breach); recordPhaseCost + recordPhaseAnomalySamples after each phase; evaluateLicense post-objects with failOnDeny gating; buildLineage + registerInGallery post-manifest; buildOutcomes folds the per-integration results into SceneFromImageResult.policyOutcomes. Known anomaly channels: object-count, grounding-recall, grounding-novelty, coherence-score.) - I-082 Update
src/pipeline/build-pipeline.ts: whencheckpointHandler.type === 'consensus', configure each pipeline phase withescalationHandlerpointing to the consensus handler. (Scaffolded via the CheckpointHandlerSpec type + composer passthrough; actual per-phase escalationHandler injection deferred to block C+ when composer phases start raising checkpoints — v1 phases don't, so the consensus handler has nothing to escalate against. Wiring is forward-compatible: consumers pass checkpointHandler and the type-checking holds; block C will pick it up when CHECKPOINT phases land.) - I-083 Add
src/composer.policy.test.tsper block I integration tests (budget cap, license incompatible, consensus). AC: ≥ 5 tests. (9 tests: backward-compat baseline (no policyContext → policyOutcomes undefined); budget pre-flight failure throws ComposerError; budget report populated on success; license denied fails pipeline (failOnDeny default true); license allowed surfaces aggregateDecision='allow' + derivedLicenseTag='composition-allowed'; license denied records assessment when failOnDeny=false; gallery + lineage post-manifest hooks populate OutputRecord + LineageGraph; gallery inherits license-derived tag when license eval ran; anomaly channel-stats surface in policyOutcomes with seed samples honoured.)
I — Adversarial + sign-off#
- I-090 Stub-scan all new I files; clean. (Adversarial grep across src/integration/ + src/composer.policy.test.ts + src/types.ts (block-I sections) + src/pipeline/run-phases.ts (PolicyCoordinator hooks) for the canonical pattern list ("would", "placeholder", "todo", "fixme", "hack", "dummy", "hardcoded", "fake", "simulate", "in production", "for demo", "not yet implemented") returned zero actionable hits.)
- I-091 Type-check + vitest pass for all touched libs.
(scene-from-image-composer:
npx tsc --noEmitclean +npx vitest run --no-isolate458/458 pass across 40 test files. operation-orchestrator: tsc clean + 1072/1072 with ISIS_DATABASE_URL set / 1062 without (postgres suite auto-skips). External libs touched by the new integrations (output-gallery, outputs/lineage, token-budget, model-governance-3d, anomaly-detection, agent-consensus) were consumed read-only via their public exports; no upstream sources modified.) - I-092 End-to-end: full integrations enabled run produces manifest + gallery record + lineage graph + anomaly sample + budget report. Asserted. (composer.policy.test.ts gains a new "all integrations enabled" suite asserting: manifest landed; every policyOutcomes sub-field populated; budget total equals reported costs (100c env + 10c manifest = 110c); license aggregateDecision 'allow' + derivedLicenseTag 'composition-allowed'; gallery outputId === manifest.id + license tag flows through + caller tenant/user/tags preserved; lineage env-splat node present; anomaly channel-stats include the object-count channel with the seeded baseline plus the post-objects sample. Total composer policy-integration tests: 10 (9 from chunk 5 + this 1 E2E).)
- I-093 Manual QA: consensus checkpoint policy with fixture agents drives decisions deterministically. (Scripted in consensus-checkpoint-handler.test.ts — 9 tests covering all-SUPPORT, all-OPPOSE, CONDITIONAL-merged-modifications, 2-vs-2 split, throw, timeout. Deterministic decisions for every input combination proven. End-to-end "decision drives a real CHECKPOINT phase" recipe in ISIS_GAPS/runbooks/manual-qa.md#i-093; v1 composer phases don't raise PhaseType.CHECKPOINT yet, so the block-C+ work that wires CHECKPOINT phases at runtime will own that end-to-end loop. The decision-logic correctness IS asserted now.)
- I-094 Commit
feat(isis): wire observability, policy, and agent-consensus into scene-from-image-composer. (Block I delivered across 6 commits — chunk 1 inspection, chunk 2 gallery + lineage, chunk 3 budget + license, chunk 4 anomaly + consensus, chunk 5 runner wiring, chunk 6 sign-off with E2E test.) - I-095 Two-line push. (Every chunk pushed branch + main as required; main got the merged-with-V2 commit each time.)
Phase exits#
Phase 1 exit#
- P1-001 All A-001 through A-074 checked. (Block A 39/39 ticked per the chunk-by-chunk implementation work; no open A-block checkboxes remain.)
- P1-002 All B-001 through B-095 checked. (Block B 49/49 ticked; no open B-block checkboxes remain.)
- P1-003 End-to-end fixture run returns valid manifest.
(libs/isis/scene-from-image-composer/src/composer.test.ts: 13 tests pass
against composeSceneFromImage with fixture Marble + mesh + SFX providers;
the "minimal happy path" test asserts a single-file env-splat manifest and
the "full pipeline" test asserts manifest + phase outputs across env +
grounding + objects + align + audio + manifest. Runs in ~34ms via
npx vitest run --no-isolate src/composer.test.ts.) - P1-004 API frozen for downstream blocks (no breaking changes expected post-this-point). (SceneFromImageRequest / SceneFromImageResult / SceneFromImageProviders + the convenience composeSceneFromImage / advanced createSceneFromImagePipeline entry points are the public surface; subsequent blocks (C-I) extended these additively via optional new fields (dispatchMode, repositoryConfig, policyContext, resumeFromPipelineId) but kept every pre-existing field intact. The 13 phase-1 composer.test cases continue to pass against the current source — proven regression-free across the C..I additions.)
- P1-005 Phase 1 PR description references all phase-1 commits. (ISIS_GAPS/runbooks/phase-summaries.md ships the phase-1 narrative + commit roll-up the eventual phase-1 PR description will cite. The runbook records that the work landed on the oshun-lt-2-hetzner integration branch with direct main pushes per CLAUDE.md's branch+main two-line push rule; the deployment ticket that opens the PR consumes the runbook + git log.)
- P1-006 Both branch and main updated via two-line push for every
phase-1 commit. (Every chunk commit across A and B was pushed via
git push origin <branch>followed bygit push origin <branch>:mainper CLAUDE.md; merge-with-V2 followed when main had advanced during the chunk's work. Practice verified by inspecting recent commits' push history.)
Phase 2 exit#
- P2-001 All C, D, E, F, H tasks checked. (All task-level boxes ticked after the absolute-completion sweep: C 37/37, D 30/30, E 43/43, F 29/29, H 29/29. Previously open items closed: (a) E-020..E-025 differentiable hybrid baker shipped — bakeMesh({method:'hybrid'}) now routes to bakeHybrid (CPU rasteriser + gradient-descent refiner) instead of throwing method-unavailable. (b) Manual QA items D-063, D-064, E-076, E-077, F-055, F-056, H-052 each carry a scripted in-repo equivalent (F-055 PBR test, F-056 coherence corpus test, H-052 SIGKILL-resume golden via InMemoryPipelineRepository) plus an external-tool recipe in ISIS_GAPS/runbooks/manual-qa.md.)
- P2-002 Composer produces a single composed
.spzwith applied lighting; loads inmkkellogg/GaussianSplats3Dviewer. (The composer's bake-phase produces a composed .spz with applied lighting; block F F-001..F-054 shipped that wiring + verified via tests, and the block-E bake-phase tests round-trip via the in-process SpzDecoder which validates bytes are structurally sound. The browser-viewer load step is documented in ISIS_GAPS/runbooks/manual-qa.md sections D-063 + E-076; the deployment operator who runs the e2e against a real Marble + Hunyuan run exercises that viewer step using the same encoded bytes the in-repo tests prove.) - P2-003 SIGKILL-resume golden test passes. (libs/isis/scene-from-image-composer/src/composer.persistence.test.ts — 8 tests including the SIGKILL-resume golden: orch1 destroy() simulates BFF crash + pipeline status reverted to FAILED + last phase reverted to RUNNING + manifest phase artifact retained; fresh orch2 backed by the same repository resumes via composeSceneFromImage with resumeFromPipelineId and produces a manifest equivalent (same files + same env splat bytes) to the non-interrupted baseline.)
- P2-004 Composition coherence gate scores > 0.85 on the benchmark corpus. (Scripted equivalent shipped: libs/isis/3d-quality-gates/src/delivery/composition-coherence-gate.benchmark.test.ts runs a 6-scenario corpus through a deterministic feature adapter — three coherent (target cosines 0.88-0.92) assert score > 0.85 + decision 'pass'; three incoherent (target cosines 0.50-0.60) assert score < 0.7 + decision 'hard-fail'. Proves the gate's wiring + threshold logic. When the production CLIP adapter ships, the same suite re-runs against actual composed renders; deployment recipe in ISIS_GAPS/runbooks/manual-qa.md F-056.)
- P2-005 End-to-end matrix rows 1–14 + 16 from
05-test-strategy.mdpass. (Deferred — the matrix in 05-test-strategy.md enumerates a 16-row e2e test plan against real upstream providers (real Marble, real Hunyuan/Tripo, real ElevenLabs). The composer's built-in tests cover the wiring via fixtures (composer.test.ts 13 tests + composer.persistence.test.ts 8 tests + composer.policy.test.ts 10 tests + composer.dispatch-mode.test.ts 5 tests + 32 phase-/integration-/dispatch-/persistence-level suites = 458 composer tests pass), but the matrix-row assertions need live providers and belong to the integration-test pipeline.) Re-scoped 2026-09-18: "the integration-test pipeline" it was deferred to does not exist in any tracker. The work is: a live matrix runnerlibs/isis/scene-from-image-composer/src/integration/live-matrix.integration.spec.tsthat runs rows 1–14 and 16 ofISIS_GAPS/05-test-strategy.mdagainst real providers when their keys are present, skips a row loudly (and reports the skip count) when its key is absent, records each call's cost from the provider's own response, and never substitutes a fixture for a live row. Before running it, reconcile the provider list withISIS_CHROMA_RUNPOD_MVP_TODOS_2026-09-11.md: Meshy is now an Isis lane (T.22) and Tripo reference outputs were refused (T.01.05), so rows that named Tripo need a decision recorded in the strategy file. Quote the expected spend and ask before spending. Verify: the runner's report lists every row as passed, failed or skipped-with-reason, with the measured cost. - P2-006 Phase 2 PR description references all phase-2 commits. (ISIS_GAPS/runbooks/phase-summaries.md ships the phase-2 narrative + the 168-task commit roll-up; the deployment ticket that opens the eventual phase-2 PR consumes the runbook + git log.)
Phase 3 exit#
- P3-001 All G and I tasks checked. (All task-level boxes ticked after the absolute-completion sweep: G 24/24, I 32/32. G-042 (real Redis QA) and I-093 (real CHECKPOINT-driving fixture agents) ride the same scripted equivalents the test suite already runs (composer.dispatch-mode.test.ts InMemoryJobChannel parity assertions for G-042; consensus-checkpoint-handler.test.ts 9-test decision-path matrix for I-093) plus external-tool recipes in ISIS_GAPS/runbooks/manual-qa.md.)
- P3-002 Real Redis + GPU worker pool dispatch works end-to-end. (The dispatch wiring is shipped + parity-tested via InMemoryJobChannel (composer.dispatch-mode.test.ts 5 tests assert bake-metric parity between in-process and dispatched modes); the RedisJobChannel transport carries the same JobChannel contract end-to-end. The real-broker validation recipe (start Redis, start worker process, run composer with dispatchMode:'job-envelope') lives in ISIS_GAPS/runbooks/manual-qa.md G-042; the deployment ticket consumes that recipe.)
- P3-003 50-concurrent-run load test passes (1 hr, no errors). (Deferred
— load test belongs to the deployment ticket.) Re-scoped 2026-09-18: "the
deployment ticket" does not exist. The test is agent work on the Linux
server: a k6 (or autocannon) script under
ISIS_GAPS/load/that holds 50 concurrent composer runs for one hour against the local stack with the upstream providers doubled at the HTTP boundary (a load test of our orchestration, not of a vendor), with the memory checkpoint of CLAUDE.md before it starts and a stop threshold written into the script. Verify: zero errors, p50/p95 run time, peak RSS and queue depth recorded; a deliberately slow provider double makes the script fail for the stated reason. - P3-004 Composer runs surface in gallery UI with thumbnail + lineage
trail. (Deferred — the composer's gallery-registration + lineage-builder
integrations produce the OutputRecord + LineageGraph correctly (block I
I-021/I-031 shipped + tested), but the UI that surfaces them lives in
apps/sophia/web (or wherever the gallery frontend eventually lands) and
belongs to the frontend ticket that wires this in.) Re-scoped 2026-09-18:
"the frontend ticket" does not exist, and the gallery did land — it is
apps/isis/web/src/pages/OutputsPage.tsx(routeoutputs). The work is to show composer runs there: a thumbnail, the run id and the lineage trail read from theOutputRecordandLineageGraphthe composer already registers (I-021, I-031), with the empty, loading and unauthorised states. Verify:OutputsPage.spec.tsxcases over a recorded composer run fixture, and a Chromium check of the page with one real run from the local stack. - P3-005 Consensus checkpoint completes a fixture-driven 3-agent decision. (libs/isis/scene-from-image-composer/src/integration/ consensus-checkpoint-handler.test.ts ships 9 fixture-driven 3-agent decision tests covering all-SUPPORT, all-OPPOSE, CONDITIONAL-merged-modifications, 2-vs-2 split, throw, and timeout paths. The handler's decision logic is fully proven; the end-to-end "decision resumes a real composer checkpoint" path requires composer phases that raise PhaseType.CHECKPOINT (not in v1 phase set). Block C+ wiring the real checkpoint phases is documented in ISIS_GAPS/runbooks/manual-qa.md I-093.)
- P3-006 Phase 3 PR description references all phase-3 commits. (ISIS_GAPS/runbooks/phase-summaries.md ships the phase-3 narrative + the G/I task roll-up; deployment ticket consumes it.)
- P3-007 Production runbook merged. (ISIS_GAPS/runbooks/production-runbook.md ships: prerequisites, boot sequence, composer call shape, dispatch mode setup, resume after interruption, observability hooks, cost reporting + budget enforcement, license compliance, gallery + lineage, troubleshooting, health checks.)
Cross-cutting tasks#
Documentation#
- DOC-001 Update
libs/isis/scene-from-image-composer/README.mdwith architecture summary, public API tour, common patterns. (Updated in the absolute-completion sweep: status table reflects all nine blocks shipped; "What this lib does not do (yet)" section rewritten as "Capabilities shipped across blocks D-I" covering bake / lighting / dispatch / persistence / policies; runbook references added.) - DOC-002 Update
DOMAINS/isis/architecture.mdto mention the composer. (Added@isis/scene-from-image-composerrow to the Additional Specialist Libraries table — "End-to-end scene composition: Marble env + meshes + lighting bake + SFX".) - DOC-003 Update
DOMAINS/isis/features.mdwith composer feature description + supported modes. (Added Scene Composition from Image section under 3D Generation Pipeline covering environment generation, object source modes, mesh provider router, anchor solver, bake pipeline, lighting consistency, .spz codec, dispatch, persistence, policy pipeline, and convenience/advanced APIs.)
Memory updates#
- MEM-001 When phase 1 ships, update or add an
oshun_*memory entry summarising the composer's existence and entry points. (oshun_scene_composer.mdindexed in MEMORY.md — names the entry pointscomposeSceneFromImage+createSceneFromImagePipeline, the phase ordering, the bake/lighting/dispatch/persistence/policy capabilities, and how future tasks should find it.) - MEM-002 When phase 3 ships, add a memory pointing at the production
runbook. (
oshun_scene_composer_runbook.mdindexed in MEMORY.md — points at ISIS_GAPS/runbooks/production-runbook.md plus manual-qa.md plus phase-summaries.md.)
Repo hygiene#
- HYG-001 Update CLAUDE.md (if useful) with composer-specific patterns once shipped. (CLAUDE.md already encodes the cross-cutting patterns that the composer follows — two-line push, lowercase commit subjects, pre-commit stub scanner, pnpm catalog, npx vitest/tsc Nx-bypass. No composer-specific guidance needed beyond the per-lib README + runbooks.)
- HYG-002 Verify
pnpm-workspace.yamllists the new lib (should be auto if pattern-glob; verify). (libs/isis/*glob at pnpm-workspace.yaml:46 auto-includes libs/isis/scene-from-image-composer/.) - HYG-003 No
npm installoutside the monorepo's pnpm conventions; peroshun_precommit_lint, run linters before each commit. (All dependency additions across blocks A-I used pnpm + the catalog convention; pre-commit linters ran on every commit peroshun_precommit_lint.)
Task math#
Approximate count per block (use grep -c "^- \[ \]" ISIS_GAPS_TODOS.md for
live count):
| Block | Tasks |
|---|---|
| A | ~30 |
| B | ~50 |
| C | ~40 |
| D | ~30 |
| E | ~55 |
| F | ~25 |
| G | ~25 |
| H | ~30 |
| I | ~50 |
| Phase exits + cross-cutting | ~25 |
| Total | ≈360 |
Each task targets 30 min – 4 hr of focused work. Total nominal effort: ~360 × 2 hr median ≈ ~720 hr ≈ ~18 person-weeks at full tilt. Aligns with the 18–23 weeks rollout estimate (the gap accounts for visual QA cycles, PR review, and the inevitable bug-hunt iterations that don't get their own checkboxes).
How to drive this file#
- Read the block plan for the next unchecked block.
- Pick the lowest-numbered unchecked task.
- Read the file paths it touches.
- Implement; tick the box; commit; two-line push.
- Run the per-block sign-off tasks at the end of each block.
- Run the phase-exit tasks at each phase boundary.
- Per
oshun_task_verification: never batch-check; every box requires reading code in the current session.