Eve library

ISIS_GAPS_TODOS — Surgical Checklist

Tracker

Revision 1

On this page

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=ACM per the oshun_bulk_commit_lint_staged memory.

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.ts end-to-end. Confirm ChainStatus (line 118), PhaseType (line 129), event schema, ExecutionPhase shape. Note any deviations from the survey in 01-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.ts fully (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 the ChainStatus const at types.ts:118. Re-export type from index.ts. AC: tsc --noEmit clean; existing usages of ChainStatus unaffected.

    **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 CheckpointDecisionStatus const + type at the bottom of types.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 CheckpointPayload shape + branded CheckpointId type. Mirror the PhaseId/ChainId brand 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.ts per 04-api-surfaces.md ("Types" subsection of block A). Export CheckpointArtifact, 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.ts exporting autoApprove(notes?), autoReject(notes?), escalateToHandler(handler) helpers that produce CheckpointDecision objects with the right reviewer strings.

    **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 — CheckpointCoordinator class with awaitDecision, recordDecision, getAwaiting. Internal state: Map<PhaseId, AwaitingState> where AwaitingState carries 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, emits pipeline_awaiting_approval event via the orchestrator's event bus.

    **Done 2026-05-16** (with A-024).
    
  • A-026 Implement recordDecision: clears timer, resolves Promise, removes state, emits pipeline_checkpoint_decided. Throws CheckpointAlreadyDecidedError if 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, call recordDecision internally, also emit pipeline_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 of AwaitingCheckpoint.

    **Done 2026-05-16** (with A-024).
    
  • A-029 Create checkpoint/checkpoint-coordinator.test.ts — scripted in block A plan: awaitDecision resolves on recordDecision; resolves with timed-out after timeout; concurrent decisions throw; escalationHandler invoked; 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.ts re-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 PipelineOrchestrator constructor (pipeline-orchestrator.ts:625) to accept optional coordinator?: CheckpointCoordinator in config. If omitted, construct a local one (cross-orchestrator coordination then doesn't work — the composer always supplies a shared instance). Same change to ExecutionOrchestrator constructor (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 on PipelineOrchestrator. Delegates to coordinator.recordDecision({...}). Validates pipelineId belongs to a known pipeline (throws PipelineNotFoundError if 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 on PipelineOrchestrator. Delegates to coordinator.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 at pipeline-orchestrator.ts:1037 to accept coordinator?: CheckpointCoordinator and checkpointPolicy?: CheckpointPolicy in the config, default policy = { timeoutMs: 30_000, onTimeout: 'approve' } (matches the existing DEFAULT_PHASE_TIMEOUT_MS[CHECKPOINT] of 30s; preserves backward compat with createStrictExecutionOrchestrator).

    **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 pruneHistory at pipeline-orchestrator.ts:1004: when a terminal pipeline is removed, also call coordinator.purgeForPipeline(pipelineId) so the coordinator's awaiting/decided/overlay maps don't leak. Add a corresponding CheckpointCoordinator.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.startPhase at execution-orchestrator.ts:1104 (the orchestrator is imperative; no autonomous phase loop exists — see A-002 notes). Extend startPhase to accept an optional pendingArtifact?: CheckpointArtifact parameter. When the target phase has phaseType === 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_TRANSITIONS at execution-orchestrator.ts:52: add AWAITING_APPROVAL to RUNNING'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 CheckpointArtifact from the supplied pendingArtifact (or synthesise a placeholder if omitted), mark chain AWAITING_APPROVAL, emit pipeline_awaiting_approval, and call coordinator.awaitDecision({ pipelineId, chainId, phaseId, artifact, policy }). Leave the phase status as PENDING (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.status and 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 on CheckpointCoordinator so 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.ts to 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-hetzner then git 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.json matching the workspace conventions (mirrored from libs/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.json extending tsconfig.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. Confirm pnpm install succeeds and import * 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.ts with the public types per 04-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. Throw AlignmentError on 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-ground anchor → 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) calls ctx.providers.marble.generateFromImage (or generateFromText if no image), packages the response into EnvironmentPhaseOutput. Errors wrap into ComposerError({ 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.ts with 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. Calls evaluate3DQualityInputGroundingGate with the source image + Marble preview renders; returns GroundingPhaseOutput.

    **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.ts with fixture grounding adapter (reuse from input-grounding-gate.test.ts pattern); 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. Iterates request.objects ?? []; for each explicit spec calls providers.mesh.generateFromText({ prompt: spec.prompt }). Skips silently if providers.mesh not supplied AND objects.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 (use parseGLB + getDocumentStats from @isis/3d-generation/processing/gltf-utils), compute transform via align-mesh-to-splat-frame, return AlignPhaseOutput.

    **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 via providers.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. Builds OutputManifest via @isis/outputs/manifest-builder.ts. Files: env splat, optional meshes, optional ambient, preview thumbnails. Provenance per provider. Metadata: sceneFromImage extension 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: SceneComposerManifestMetadata type per 04-api-surfaces.md. Validator function validateSceneComposerMetadata(unknown): SceneComposerManifestMetadata that 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 a PipelineDefinition (block A type) from a SceneFromImageRequest. One chain per phase; CHECKPOINT phases injected per request.checkpoints config.

    **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 a PipelineOrchestrator with 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 to runInProcess. 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 per oshun_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: extends Base3DProvider, returns canned Generated3DModel with 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: implements ISFXProvider returning canned GeneratedSFX.

    **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 from input-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.md with 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-composer from a sibling lib's test file (e.g. libs/isis/3d-generation/src/providers/marble-provider.test.ts could import 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-hetzner then git 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 in libs/isis/scene-from-image-composer/.

    **Done 2026-05-16** (with C-002..C-005 in one commit).
    
  • C-002 Create src/objects/object-spec.ts with the discriminated union (block C plan): explicit | cropped | vlm-detected. Re-export BBox type.

    **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.ts to import ObjectSpec from ./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?) uses sharp to crop; if removeBackground, 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.ts with the full discriminated union per block C plan: add bbox-floor, forward-of, right-of, surface-snapped. surface-snapped falls back to centre-ground with 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.ts with 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; throw UnresolvableAnchorsError on 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.ts exporting DetectionPolicy per block C plan.
  • C-022 Create src/detection/overlap-merge.ts. IoU computation on BBox; 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. Curated BACKGROUND_LABELS and FOREGROUND_LABELS sets. 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 of canonicaliseGroundingLabel. 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. Calls groundingAdapter.detectObjects(sourceImage); runs IoU merge; filters by foreground classifier; clamps to topK / maxObjects; computes cost; emits detection-cost-cap-hit event 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) => boolean predicate.
  • C-042 Create src/routing/mesh-provider-router.ts. MeshProviderRouter class 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; providerHint overrides; ties resolved deterministically; empty providers throws. AC: ≥ 6 tests.

C — Composer wiring#

  • C-050 Update src/types.ts: add objectStrategy field (auto-derived if all specs are explicit); add detectionPolicy? field for vlm-detected mode.
  • C-051 Update src/composer.ts: insert detection-phase between environment and objects when objectStrategy === 'vlm-detected' or 'mixed' (where any spec uses vlm-detected).
  • C-052 Update src/phases/objects-phase.ts: handle cropped (call cropImage, then provider.generateFromImage(crop)) and vlm-detected (same). Use MeshProviderRouter to pick provider per object.
  • C-053 Update src/phases/align-phase.ts: use constraint-solver for multi-object placement (replaces independent resolveAnchor calls from block B).
  • C-054 Update src/composer.test.ts to 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 in composer.test.ts.
  • C-061 Detection returns 100 objects → clamped to maxObjects.
  • C-062 Two vlm-detected with 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.ts for binary-format conventions.
  • D-002 Read libs/isis/gaussian-splatting/src/rendering/splat-renderer.ts:114-117 for LoadedScene shape.
  • D-003 Confirm pako (or Node zlib) is available; add to libs/isis/gaussian-splatting/package.json deps if needed.
  • D-004 Survey the public Niantic spec at https://github.com/nianticlabs/spz — document the exact byte layout in spz-binary-layout.ts JSDoc.

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) and readInt24LE helpers (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: returns 0 for 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 via SpzDecoder (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 .spz files. 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 .spz documenting 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.ts to export SpzExporter, SpzDecoder, createSpzExporter, createSpzDecoder, the result types.
  • D-051 Update libs/isis/gaussian-splatting/src/index.ts to 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/GaussianSplats3D web 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 subdirs surface-sampling/, differentiable/, merge/. (Created surface-sampling/ in chunk 1; merge/ and differentiable/ ship in later chunks.)
  • E-002 Create src/bake/types.ts per 04-api-surfaces.md E section. Export BakeRequest, BakedGaussians, BakeResult, BakeMethod, BakeError.
  • E-003 Create src/bake/index.ts re-exporting bakeMesh (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 one BakedGaussian: 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 → apply transform → return BakedGaussians.
  • 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 via MergeOptions.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) in src/bake/index.ts. Switches on request.method; calls samplingBaker or hybridBaker; measures metrics.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 valid BakedGaussians; metrics populated; BakeError on degenerate mesh. AC: ≥ 4 tests.

E — Composer integration#

  • E-060 Create libs/isis/scene-from-image-composer/src/phases/bake-phase.ts. Per placement: call bakeMesh({ mesh: meshBuffer, transform: placement.transform, method: bakeOptions?.method ?? 'surface-sampling' }). Merge baked Gaussians into env splat via mergeSplats. Return composed LoadedScene.
  • 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.ts to add outputMode and bakeOptions. Default outputMode: '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 .spz env data; documented in SceneFromImageRequest JSDoc. Real callers should pass 'baked'.)
  • E-063 Update src/composer.ts to insert bake-phase after align-phase when outputMode === '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 via SpzExporter (block D) and add it as the primary model-3d file. Also keep source meshes in sources/ subdir per ADR-004. (Primary-file swap + scene-composed.spz addition 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 → BakeError thrown. (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 --noEmit clean.
  • E-074 cd libs/isis/gaussian-splatting && npx vitest run all pass. (353 / 353 across 31 files.)
  • E-075 cd libs/isis/scene-from-image-composer && npx vitest run all 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 .spz loads. (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 .spz through 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 merging followed by feat(isis): wire bake-phase into scene-from-image-composer. (Block-E work shipped in 4 chunks across multiple commits: 3677b130a5 surface sampling, b339c5f74d splat merging, 9792463a45 bakeMesh + 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.ts per 04-api-surfaces.md F 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 (sh9 and env-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 behind metallic > 0.5 || roughness < 0.2 heuristic (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.ts re-exports.

F — Composer + bake wiring#

  • F-020 Update src/bake/surface-sampling/sample-to-gaussian.ts: accept optional lightingContext; replace raw colour with applyPbrShading when 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: pass lightingContext through.
  • F-022 Update src/bake/index.ts: BakeRequest.lightingContext? field populated. (Field declared in bake/types.ts; threaded through bake-mesh.ts dispatcher to bakeSurfaceSampling.)
  • F-023 Update libs/isis/scene-from-image-composer/src/phases/bake-phase.ts: call estimateEnvironmentLightField before each mesh bake; pass resulting IrradianceMap into bakeMesh.lightingContext. (Default applyLighting = true; opt-out via bakeOptions.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: populate metadata.sceneFromImage.lightingMetadata with 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.ts to export the gate.
  • F-033 Update libs/isis/3d-quality-gates/src/index.ts to 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 new coherence-phase.ts). Renders the composed scene from 6–8 cameras; rasterises placement masks; calls evaluateCompositionCoherence. (Shipped as a new top-level coherence-phase.ts between bake and audio. v1 doesn't render Gaussian scenes itself — the composer takes caller-supplied composed renders on request.coherenceRenders and 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's coherence-phase.ts.)
  • F-051 cd libs/isis/gaussian-splatting && npx tsc --noEmit clean.
  • F-052 cd libs/isis/3d-quality-gates && npx tsc --noEmit clean.
  • F-053 cd libs/isis/scene-from-image-composer && npx tsc --noEmit clean.
  • 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.)
  • 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: extend IsisGenerationType enum with 'scene-from-image-bake'. (Added three composer dispatch types: scene-from-image-environment, -mesh, and -bake; manifest entries shipped alongside per the type's IsisGenerationTypeManifest contract.)
  • G-002 Create libs/isis/job-envelope/src/payloads.ts with the typed payload union per block G plan. (Includes EnvironmentDispatchInput/Output, MeshDispatchInput/Output, BakeDispatchInput/Output, SerializedIrradianceMap, plus base64 DispatchBuffer helpers for binary fields.)
  • G-003 Update libs/isis/job-envelope/src/index.ts to 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 includes JobResponse discriminated union, JobChannelError/JobFailedError/ JobTimeoutError/DuplicateJobIdError error classes, and requestChannelName/responseChannelName helpers.)
  • G-012 Create src/dispatch/redis-job-channel.ts. Wraps ioredis pub/sub. Subscribe-then-publish ordering enforced. (Factory hook for tests; default require('ioredis') factory installs subscriber + publisher clients per channel.)
  • G-013 Create src/dispatch/redis-job-channel.test.ts. Mock ioredis; 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.ts for tests. (Handlers self-remove via subscribeOnce closure + new persistent subscribe method so worker handlers stay attached across publishes.)
  • G-015 Create src/dispatch/job-dispatcher.ts. JobDispatcher class 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; calls generateFromImage; returns EnvironmentPhaseOutput. (Factory deps pattern with createMarbleProvider(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. Calls bakeMesh from @isis/gaussian-splatting/bake. (Decodes DispatchBuffer mesh + transform Float32Array + serialized IrradianceMap; packs BakedGaussians result via codecs.ts wire-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: add dispatchMode: 'in-process' | 'job-envelope' (default 'in-process'); dispatchConfig? for redis URL. (Field carries JobChannelConfig from dispatch/types.ts — redisUrl + optional channelPrefix + responseTimeoutMs.)
  • G-031 Update src/composer.ts: when dispatchMode === 'job-envelope', wrap each heavy phase invocation in jobDispatcher.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-envelope and scene-from-image-composer. (composer: npx tsc --noEmit clean, npx vitest run --no-isolate 397/397 pass across 32 test files; job-envelope: npx tsc --noEmit clean, 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 existing Pipeline / Chain / Phase model 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 \dt listings.)
  • H-002 Generate migration scaffolding: cd libs/isis/database && npx prisma migrate dev --create-only --name add_pipeline_state. (Hand-rolled migration at prisma/migrations/20260516170526_add_pipeline_state/migration.sql because 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 via pg_dump --schema-only -t 'pipeline_state_*' against the dev database after prisma 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 with pipeline_state_* table mappings; cascade deletes wired pipeline → chain → phase → artifact/checkpoint → decision; phase carries ordinal for stable resume ordering; status columns as strings to absorb future orchestrator status additions without migrations.)
  • H-004 Run migration: npx prisma migrate dev against the dev database. (Applied via prisma db push to localhost:5432/isis because prisma migrate dev currently 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 generate to 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 --noEmit from libs/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 per 04-api-surfaces.md H section. Define PipelineRepositoryConfig union. (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-memory Map storage; same semantics as the current pipeline-orchestrator behaviour. (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 under checkpoint-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 under checkpoint-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 PipelineOrchestrator constructor to accept repository: PipelineRepository (default = in-memory). (Additive 3rd parameter; existing new PipelineOrchestrator(config, coordinator) callers see no behaviour change. Echoed via new getRepository() 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 CheckpointCoordinator to persist awaiting checkpoints via repository.recordAwaitingCheckpoint and decisions via repository.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 via process.exit simulation, 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 to resume-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: add repositoryConfig?: 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}-output artifact 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, and database. (operation-orchestrator npx tsc --noEmit clean + 1072/1072 vitest with DB / 1062 without; scene-from-image-composer npx tsc --noEmit clean + 405/405 vitest; database npx tsc --noEmit clean after prisma 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 API followed by feat(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/ — confirm OutputRecord create API. If absent, plan a record-builder.ts addition. (Inspected. OutputRecord is 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 in gallery-registration.ts. A record-builder.ts addition 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 — confirm composited-from edge exists in the relation enum. If not, plan addition. (Inspected. LineageRelationType already includes 'composited-from' (with optional contributionWeight 0..1). LineageGraphManager exposes addNode/addEdge with cycle detection and LineageNodeBuilder.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. BudgetEnforcer class + createBudgetEnforcer() factory + cost-prediction utilities. The library is rule-based + model-pricing-driven; there is NO direct recordCost(opName, cents) function. The composer's budget-enforcer integration file will add a thin recordCost(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) returns ThreeDModelGovernanceCommercialPolicyAssessment with decision: 'allow' | 'warn' | 'deny' + reasons[] + evaluatedRights[] + licenseCategory. Request takes { registry, modelId, subjectKind, deploymentTopology, commercialIntent }. Also check3DModelGovernanceIpPolicy() + 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 exposes AnomalyDetectionService.analyzeTransaction() (fraud-style analysis) but NO recordSample(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) + iterative addPosition(sessionId, position) + calculateConvergenceScore() + determineConvergenceStatus() ('DIVERGING' | 'EXPLORING' | 'NARROWING' | 'CONVERGING' | 'CONVERGED' | 'DEADLOCKED' | 'ESCALATED'). Quorum via minParticipation (default 0.6) in ConvergenceEngineConfig. NO single runConsensus(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.)
  • I-020 If needed, add OutputRecord create helper to libs/isis/output-gallery/src/record-builder.ts. (Skipped — the chunk-1 inspection confirmed OutputRecord is 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 via registerCompositionInGallery in the integration layer.)
  • I-021 Create src/integration/gallery-registration.ts. registerCompositionInGallery(manifest, runMetadata) returns OutputRecordId. (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-from to lineage-graph.ts relation 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): LineageGraph per 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. BudgetEnforcer class 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; calls model-governance-3d license evaluator; returns compliant | 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 to anomaly-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 a CheckpointHandler (block A interface) backed by agent-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: add policyContext?: PolicyContext (block I shape per 04-api-surfaces.md); add checkpointHandler?: 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: after manifest-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: when checkpointHandler.type === 'consensus', configure each pipeline phase with escalationHandler pointing 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.ts per 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 --noEmit clean + npx vitest run --no-isolate 458/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 by git push origin <branch>:main per 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 .spz with applied lighting; loads in mkkellogg/GaussianSplats3D viewer. (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.md pass. (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 runner libs/isis/scene-from-image-composer/src/integration/live-matrix.integration.spec.ts that runs rows 1–14 and 16 of ISIS_GAPS/05-test-strategy.md against 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 with ISIS_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 (route outputs). The work is to show composer runs there: a thumbnail, the run id and the lineage trail read from the OutputRecord and LineageGraph the composer already registers (I-021, I-031), with the empty, loading and unauthorised states. Verify: OutputsPage.spec.tsx cases 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.md with 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.md to mention the composer. (Added @isis/scene-from-image-composer row to the Additional Specialist Libraries table — "End-to-end scene composition: Marble env + meshes + lighting bake + SFX".)
  • DOC-003 Update DOMAINS/isis/features.md with 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.md indexed in MEMORY.md — names the entry points composeSceneFromImage + 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.md indexed 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.yaml lists 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 install outside the monorepo's pnpm conventions; per oshun_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 per oshun_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#

  1. Read the block plan for the next unchecked block.
  2. Pick the lowest-numbered unchecked task.
  3. Read the file paths it touches.
  4. Implement; tick the box; commit; two-line push.
  5. Run the per-block sign-off tasks at the end of each block.
  6. Run the phase-exit tasks at each phase boundary.
  7. Per oshun_task_verification: never batch-check; every box requires reading code in the current session.