@smartmemory/compose 0.5.0 → 0.5.1

package/lib/flow-state.js

@@ -35,3 +35,41 @@ export function readFlowRound(flowId) {
     return Number.isInteger(r) && r >= 0 ? r : 0;
   } catch { return 0; }
 }
+
+/** Strict persisted snapshot: callers must hold on unreadable or mismatched evidence. */
+export function readFlowSnapshot(flowId, { revisionDigest, gateStepId, gateToken } = {}) {
+  const refuse = message => { throw Object.assign(new Error(message), { code: 'WAVE_COST_UNVERIFIED' }); };
+  if (typeof flowId !== 'string' || !/^[\w-]+$/.test(flowId)) refuse('Invalid flow identity');
+  let state;
+  try {
+    const root = process.env.STRATUM_STATE_ROOT || join(homedir(), '.stratum', 'ts', 'flows');
+    state = JSON.parse(readFileSync(join(root, `${flowId}.json`), 'utf8'));
+  } catch (error) { refuse(`Cannot read persisted flow: ${error.message}`); }
+  if (state?.id !== flowId || !revisionDigest || state.revisionDigest !== revisionDigest) refuse('Flow revision/identity differs');
+  if (gateStepId && (state.steps?.[gateStepId]?.status !== 'waiting_gate'
+    || state.steps[gateStepId].gateToken !== gateToken)) refuse('Persisted gate token differs');
+  return state;
+}
+
+export function readFlowSpend(flowId, options, pending = []) {
+  const snapshot = readFlowSnapshot(flowId, options);
+  const fail = message => { throw Object.assign(new Error(message), { code: 'WAVE_COST_UNVERIFIED' }); };
+  if (pending.some(p => p.state !== 'acknowledged')) fail('Unacknowledged usage receipts');
+  if (!Array.isArray(snapshot.receipts)) fail('Missing receipt spine');
+  const ids = new Set();
+  let spent = 0;
+  for (const receipt of snapshot.receipts) {
+    if (!receipt.dispatchId || ids.has(receipt.dispatchId)) fail('Invalid/duplicate receipt identity');
+    ids.add(receipt.dispatchId);
+    const usd = receipt.amount?.usd;
+    if (receipt.detail?.costUnknown) fail('Model call has no attributed cost');
+    if (usd === undefined) {
+      if (receipt.amount?.tokens > 0 || receipt.amount?.ms > 0) fail('Paid call cost missing');
+      continue;
+    }
+    if (!Number.isFinite(usd) || usd < 0 || !['reported', 'estimated'].includes(receipt.usdSource)) fail('Unattributed USD');
+    spent += usd;
+  }
+  for (const p of pending) if (!ids.has(p.dispatchId)) fail('Acknowledged receipt absent from snapshot');
+  return { spent, input: snapshot.input };
+}

package/lib/gsd.js

@@ -26,7 +26,7 @@ import { validateBoundaryMap } from './boundary-map.js';
 import { enrichTaskGraph } from './gsd-decompose-enrich.js';
 import { buildTaskDescription } from './gsd-prompt.js';
 import { writeAll, validate as validateTaskResult, read as readBlackboard } from './gsd-blackboard.js';
-import { executeShipStep, toPhaseResultOutput, runConsumerIssuance, ConsumerStuckError, filesOwnedConflict, toEngineUsage, reportUsageReceipts } from './build.js';
+import { executeShipStep, toPhaseResultOutput, runConsumerIssuance, ConsumerStuckError, filesOwnedConflict, toEngineUsage, reportUsageReceipts, loadPipelineProfiles, preflightPipelineProfiles, admitConsumerWave, publishConsumerCheckpoint, evaluateConfiguredGate, reportWaveEvidence, waveProfilesEnabled } from './build.js';
 import {
   ConsumerFanoutArtifacts,
   ConsumerMergeDecisionError,
@@ -144,7 +144,8 @@ export async function runGsd(featureCode, opts = {}) {
   const preMergeGate = resolvePreMergeGate(cwd, opts.preMergeGate);
 
   // 4. Load pipeline spec
-  const specPath = join(PACKAGE_ROOT, 'pipelines', 'gsd.stratum.yaml');
+  const localPath = join(cwd, 'pipelines', 'gsd.stratum.yaml');
+  const specPath = existsSync(localPath) ? localPath : join(PACKAGE_ROOT, 'pipelines', 'gsd.stratum.yaml');
   // 4a. COMP-GSD-4: inject the stratum flow budget block from `gsd.budget.*`.
   // injectBudget is IDENTITY when nothing is configured, so an un-budgeted gsd
   // run (and plain `compose build`) is byte-identical.
@@ -152,6 +153,9 @@ export async function runGsd(featureCode, opts = {}) {
   const specYaml = injectBudget(readFileSync(specPath, 'utf-8'), budgetCfg);
   const localSpec = YAML.parse(specYaml);
   const localSpecDigest = sha256(JSON.stringify(localSpec));
+  const profileCheck = preflightPipelineProfiles(loadPipelineProfiles(specPath), localSpec, specPath);
+  const pipelineProfiles = profileCheck.normalized;
+  const profileDigest = waveProfilesEnabled(pipelineProfiles) ? profileCheck.profilesDigest : undefined;
 
   // 4a. COMP-GSD-4: cumulative cross-session ceiling pre-check (tokens/cost).
   // Refuse to start/resume a run that has already spent its lifetime budget —
@@ -235,7 +239,7 @@ export async function runGsd(featureCode, opts = {}) {
     stepCtx = {
       stratum, cwd, featureCode, blueprintText, gateCommands, preMergeGate,
       receiptsMode,
-      localSpec, localSpecDigest,
+      localSpec, localSpecDigest, pipelineProfiles, profileDigest,
       filesChanged: [],
       stuckDetector,
       // D2(a): per-ITEM wall-clock ceiling from gsd.budget.per_task_ms, enforced
@@ -294,6 +298,11 @@ export async function runGsd(featureCode, opts = {}) {
     }, { workspaceRoot: cwd });
     const flowId = response.runId;
     stepCtx.flowId = flowId;
+    if (waveProfilesEnabled(pipelineProfiles)) {
+      stepCtx.consumerArtifacts = new ConsumerFanoutArtifacts({ runId: flowId, targetCwd: cwd,
+        revisionDigest: response.revisionDigest, specDigest: localSpecDigest, profilesDigest: profileDigest });
+      stepCtx.artifacts = stepCtx.consumerArtifacts;
+    }
     flushState(stepCtx, { flowId, phase: 'decompose' });
     emitPhaseOnce(stepCtx, 'decompose'); // COMP-GSD-7-EVENTLOG
 
@@ -303,11 +312,17 @@ export async function runGsd(featureCode, opts = {}) {
       response.status !== 'completed' &&
       response.status !== 'failed' &&
       response.status !== 'stuck' &&
+      response.status !== 'waiting_gate' &&
       response.status !== 'budget_exhausted'
     ) {
       response = await runOneStep(response, stepCtx);
     }
 
+    if (response.status === 'waiting_gate') {
+      flushState(stepCtx, { status: 'waiting_gate', gateToken: response.gateToken, reason: response.reason });
+      return response;
+    }
+
     if (response.status === 'stuck') {
       // Artifacts (stuck.md/json + pause.json) were written by runOneStep.
       // COMP-GSD-7-EVENTLOG: flush any completions that finished before the stuck
@@ -494,25 +509,35 @@ async function runOneStep(response, ctx) {
           targetCwd: cwd,
           revisionDigest: descriptor.revisionDigest,
           specDigest: localSpecDigest,
+          profilesDigest: ctx.profileDigest,
         });
       }
       ctx.consumerArtifacts.bindRunRevision({
         revisionDigest: descriptor.revisionDigest,
         specDigest: localSpecDigest,
+        profilesDigest: ctx.profileDigest,
       });
+      ctx.artifacts = ctx.consumerArtifacts;
+      // This audit already serves issuance recovery on legacy runs; admission
+      // uses it only when this step opts into wave policies.
+      const audit = await stratum.audit(flowId);
+      const configured = ctx.pipelineProfiles?.[descriptor.step]?.tier_from || ctx.pipelineProfiles?._consumer?.[descriptor.step];
+      const admission = configured ? await admitConsumerWave({ descriptor, descriptors: ready.filter(isConsumerDescriptor), audit,
+        localSpec, profiles: ctx.pipelineProfiles, artifacts: ctx.consumerArtifacts, stratum, flowId }) : null;
       // D7(a): render the exact TaskResult path from the item's task id (the
       // fanout `over` is decompose_gsd.output.tasks, indexed by itemIndex).
-      const consumerItem = ctx.lastTaskGraph?.tasks?.[descriptor.itemIndex];
+      const consumerItem = descriptor.item;
       const taskResultPath = consumerItem?.id
         ? gsdTaskResultPath(featureCode, consumerItem.id)
         : undefined;
       try {
         return await runConsumerIssuance({
           descriptor,
+          admission,
           flowId,
           stratum,
           artifacts: ctx.consumerArtifacts,
-          audit: await stratum.audit(flowId),
+          audit,
           localSpec,
           // D2(b): onUsage debits each item's agent usage into the cumulative
           // ledger. D2(a): per-item wall-clock ceiling from gsd.budget.per_task_ms.
@@ -523,12 +548,15 @@ async function runOneStep(response, ctx) {
           // by definition a GSD task, so timing.json + diffs/<id>.diff are written
           // for the milestone report. The build consumer path omits it (no marker),
           // so build-mode fanout stays byte-identical.
-          context: { cwd, projectCwd: cwd, featureCode, flowId, receiptsMode: ctx.receiptsMode, gsd: true, gsdTaskId: consumerItem?.id, filesChanged: ctx.filesChanged, onUsage: (usage, meta) => recordTsAgentUsage(ctx, usage, meta), taskResultPath },
+          context: { pipelineProfiles: ctx.pipelineProfiles, artifacts: ctx.consumerArtifacts, cwd, projectCwd: cwd, featureCode, flowId, receiptsMode: ctx.receiptsMode, gsd: true, gsdTaskId: consumerItem?.id, filesChanged: ctx.filesChanged, onUsage: (usage, meta) => recordTsAgentUsage(ctx, usage, meta), taskResultPath },
           // runAndNormalize narrates via progress.debug/warn/info/toolUse — gsd
           // has no cockpit, so a COMPLETE no-op (not just stepStart/stepDone) is
           // required or the item throws "progress.debug is not a function".
           progress: NOOP_PROGRESS,
-          streamWriter: { write() {} },
+          streamWriter: { write(event) {
+            if (event.type === 'step_model') appendGsdEvent(cwd, featureCode, 'step_model', event);
+          } },
+          profile: ctx.pipelineProfiles?.[descriptor.step]?.default ?? ctx.pipelineProfiles?.[descriptor.step],
           perItemTimeoutMs: ctx.perItemTimeoutMs,
           stuckDetector: ctx.stuckDetector,
         });
@@ -555,7 +583,7 @@ async function runOneStep(response, ctx) {
         featureCode,
         cwd,
         cwd,
-        { cwd, featureCode, mode: 'feature', filesChanged: ctx.filesChanged ?? [] },
+        { ...ctx, cwd, featureCode, mode: 'feature', artifacts: ctx.consumerArtifacts, filesChanged: ctx.filesChanged ?? [] },
         '',
         null,
       );
@@ -663,46 +691,65 @@ async function runOneStep(response, ctx) {
     const gateStep = steps.find((step) => step.id === gateStepId);
     const predecessorIds = new Set(gateStep?.after ?? []);
     const fanoutStep = steps.find((step) => predecessorIds.has(step.id) && step.fanout?.dispatch === 'consumer');
-    if (!fanoutStep) {
-      throw new Error(`runGsd: unexpected non-consumer gate ${gateStepId} on the TS path`);
-    }
-    if (!ctx.consumerArtifacts) {
-      ctx.consumerArtifacts = new ConsumerFanoutArtifacts({
-        runId: flowId,
-        targetCwd: cwd,
-        revisionDigest: response.revisionDigest,
-        specDigest: localSpecDigest,
-      });
-    }
-    const artifacts = ctx.consumerArtifacts;
-    artifacts.recordGateBinding({ gateStepId, fanoutStepId: fanoutStep.id });
-    let transaction;
-    let outcome = 'approve';
-    let rationale = 'consumer fanout artifacts merged';
-    try {
-      transaction = artifacts.prepareMerge({
-        gateStepId,
-        gateToken: gateState.gateToken,
-        fanoutStepId: fanoutStep.id,
-        audit,
-      });
-      await artifacts.applyMerge(transaction);
-    } catch (error) {
-      if (!(error instanceof ConsumerMergeDecisionError)) throw error;
-      outcome = gateStep?.gate?.on_revise ? 'revise' : 'kill';
-      rationale = `${error.code}: ${error.message}`;
-      transaction ??= artifacts.journal.mergeTransactions.find(
-        (entry) => entry.gateToken === gateState.gateToken,
-      );
-      if (transaction) artifacts.restoreMergeBaseline(transaction, audit);
-    }
-    const next = await stratum.gateResolve(
-      flowId, gateStepId, outcome, rationale, 'system', gateState.gateToken,
-    );
-    artifacts.markGateResolved(transaction, outcome);
-    if (outcome !== 'revise') artifacts.cleanupWorktrees(`GSD merge gate ${outcome}`);
-    if (outcome === 'approve') ctx.filesChanged = collectChangedFiles(cwd);
-    return next;
+    const outputDecision = ctx.artifacts ? await evaluateConfiguredGate(ctx, { localSpec, gateStepId,
+      gateToken: gateState.gateToken, audit }) : null;
+    if (outputDecision && !outputDecision.outcome) return { status: 'waiting_gate', flowId,
+      gateToken: gateState.gateToken, reason: outputDecision.reason };
+    const resolveGateWithConsumerMerge = async (requestedOutcome, requestedRationale) => {
+      if (!fanoutStep && !outputDecision) throw new Error(`runGsd: unexpected non-consumer gate ${gateStepId} on the TS path`);
+      if (fanoutStep && !ctx.consumerArtifacts) {
+        ctx.consumerArtifacts = new ConsumerFanoutArtifacts({ runId: flowId, targetCwd: cwd,
+          revisionDigest: response.revisionDigest, specDigest: localSpecDigest, profilesDigest: ctx.profileDigest });
+      }
+      const artifacts = fanoutStep ? ctx.consumerArtifacts : null;
+      if (artifacts) ctx.artifacts = artifacts;
+      if (ctx.pipelineProfiles?._consumer?.[fanoutStep?.id]?.checkpoint_gate === gateStepId) {
+        artifacts.initializeWave({ ref: `refs/heads/compose/wave/${flowId}`, profilesDigest: ctx.profileDigest });
+      }
+      let transaction;
+      let outcome = requestedOutcome;
+      let rationale = requestedRationale;
+      if (artifacts) {
+        artifacts.recordGateBinding({ gateStepId, fanoutStepId: fanoutStep.id });
+        try {
+          transaction = artifacts.prepareMerge({ gateStepId, gateToken: gateState.gateToken, fanoutStepId: fanoutStep.id, audit });
+          if (outcome === 'approve') await artifacts.applyMerge(transaction);
+          else artifacts.restoreMergeBaseline(transaction, audit);
+        } catch (error) {
+          if (!(error instanceof ConsumerMergeDecisionError)) throw error;
+          outcome = gateStep?.gate?.on_revise ? 'revise' : 'kill';
+          rationale = `${error.code}: ${error.message}`;
+          transaction ??= artifacts.journal.mergeTransactions.find(e => e.gateToken === gateState.gateToken);
+          if (transaction) artifacts.restoreMergeBaseline(transaction, audit);
+        }
+      }
+      let next;
+      try {
+        next = await stratum.gateResolve(flowId, gateStepId, outcome, rationale, 'system', gateState.gateToken);
+      } catch (error) {
+        const current = await stratum.audit(flowId);
+        const ordinal = (audit.events ?? []).filter(e => e.type === 'gate_resolved' && e.stepId === gateStepId).length;
+        const confirmed = (current.events ?? []).filter(e => e.type === 'gate_resolved' && e.stepId === gateStepId)[ordinal]?.detail?.decision;
+        if (!confirmed) throw error;
+        outcome = confirmed;
+        if (artifacts && outcome === 'approve') {
+          artifacts.markGateResolved(transaction, outcome);
+          await publishConsumerCheckpoint(ctx, transaction);
+        }
+        next = await stratum.resume(flowId);
+      }
+      if (artifacts) {
+        artifacts.markGateResolved(transaction, outcome);
+        if (outcome === 'approve') await publishConsumerCheckpoint(ctx, transaction);
+        if (outcome !== 'revise') artifacts.cleanupWorktrees(`GSD merge gate ${outcome}`,
+          artifacts.journal.wave ? { dispatchTokens: transaction.acceptedDispatchTokens } : {});
+        if (outcome === 'approve' && !artifacts.journal.wave) ctx.filesChanged = collectChangedFiles(cwd);
+      }
+      if (outputDecision) await reportWaveEvidence(ctx, 'gate_decision', gateState.gateToken,
+        { ...outputDecision, outcome, rationale }, 'accepted');
+      return next;
+    };
+    return resolveGateWithConsumerMerge(outputDecision?.outcome ?? 'approve', outputDecision?.rationale ?? 'consumer fanout artifacts merged');
   }
 
   return response;

package/lib/model-pricing.js

@@ -1,7 +1,7 @@
 /**
  * model-pricing.js — Token cost lookup and USD calculation.
  *
- * Prices are per-million tokens (MTok) as of 2025.
+ * Prices are per-million tokens (MTok) updated for COMP-FABLE-ASTRA slice 1 (2026-09).
  * Input price includes standard prompt tokens.
  * Cache write tokens (cache_creation_input_tokens) are billed at 1.25x input rate.
  * Cache read tokens (cache_read_input_tokens) are billed at 0.1x input rate.
@@ -12,6 +12,9 @@
  * Keys are matched by prefix so 'claude-sonnet-4-6' matches 'claude-sonnet-4-6-20250514' etc.
  */
 export const MODEL_PRICING = {
+  'claude-fable-5-1':  { inputPerMTok: 10,  outputPerMTok: 50 },
+  'claude-opus-5':     { inputPerMTok: 5,   outputPerMTok: 25 },
+  'claude-sonnet-5':   { inputPerMTok: 2,   outputPerMTok: 10 },
   'claude-opus-4-7':    { inputPerMTok: 5,   outputPerMTok: 25 },
   'claude-opus-4-6':    { inputPerMTok: 5,   outputPerMTok: 25 },
   'claude-sonnet-4-6':  { inputPerMTok: 3,   outputPerMTok: 15 },

package/lib/output-gate.js

@@ -0,0 +1,81 @@
+/** Pure output-gate decision. Callers supply current recorded step states. */
+import { ownField, normalizeOwnedPath, validateGateConfig, validateWaveAdmission, profilesDigest } from './pipeline-profiles.js';
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const strings = value => Array.isArray(value) && value.every(v => typeof v === 'string');
+function validateDecision(decision, review, validator, { executeProfile, executeProvider }) {
+  const findings = [];
+  const add = (code, message) => findings.push({ code, message });
+  const tasks = ownField(decision, validator.tasks_field ?? 'tasks');
+  const findingShape = f => object(f) && typeof f.severity === 'string' && strings(f.files)
+    && typeof f.claim === 'string' && typeof f.evidence === 'string';
+  const taskShape = t => object(t) && typeof t.id === 'string' && t.id.length > 0
+    && typeof t.description === 'string' && strings(t.files_owned) && strings(t.files_read)
+    && strings(t.depends_on) && (t.tier_rationale === undefined || typeof t.tier_rationale === 'string');
+  if (!object(decision) || !['repair', 'implement', 'complete', 'blocked'].includes(decision.action)
+    || typeof decision.rationale !== 'string' || typeof decision.blocking !== 'boolean'
+    || !Number.isInteger(decision.open_count) || decision.open_count < 0
+    || !Array.isArray(decision.open_findings) || !decision.open_findings.every(findingShape)
+    || !Array.isArray(decision.addressed_findings) || !decision.addressed_findings.every(findingShape)
+    || !Array.isArray(tasks) || !tasks.every(taskShape)) {
+    add('WAVE_DECISION_SHAPE', 'Invalid WaveDecision/task/finding shape');
+    return findings;
+  }
+  if (decision.open_count !== decision.open_findings.length) add('WAVE_OPEN_COUNT_MISMATCH', 'open_count differs from open_findings length');
+  if (typeof review?.blocking !== 'boolean' || review.blocking !== decision.blocking) add('WAVE_BLOCKING_MISMATCH', 'blocking differs from recorded review');
+  if (decision.action === 'complete' && (decision.open_count !== 0 || decision.blocking)) add('WAVE_COMPLETE_WITH_OPEN_FINDINGS', 'Complete requires no open findings and no blocking');
+  if (decision.action === 'blocked' && decision.open_count === 0) add('WAVE_BLOCKED_WITHOUT_FINDINGS', 'Blocked requires open findings');
+  if (['repair', 'implement'].includes(decision.action)) {
+    if (tasks.length < 1 || tasks.length > 6) add('WAVE_REPAIR_EMPTY', 'Implementation/repair requires 1–6 tasks');
+    findings.push(...validateWaveAdmission(executeProfile, tasks,
+      { provider: executeProvider, ownership: true, independent: true }).findings);
+  }
+  if (decision.action === 'repair') {
+    try {
+      const files = new Set(decision.open_findings.flatMap(f => f.files.map(normalizeOwnedPath)));
+      for (const task of tasks) if (!task.files_owned.some(file => files.has(normalizeOwnedPath(file)))) {
+        add('WAVE_REPAIR_UNOWNED_FINDING', `Repair task ${task.id} owns no open finding file`);
+      }
+    } catch (error) { add('WAVE_DECISION_SHAPE', error.message); }
+  }
+  return findings;
+}
+/**
+ * Resolve only from current recorded source, waiting gate and configured review states.
+ * executeProfile (the configured execute entry) and executeProvider are required.
+ * reviewOutput is ignored; validators always use the configured review step's recorded output.
+ */
+export function decideGateFromOutput(config, stepOutputs, { gateStepId, gateToken, reviewOutput, ceiling, executeProfile, executeProvider } = {}) {
+  const hold = (reason, extra = {}) => ({ outcome: null, reason, ...extra });
+  try { validateGateConfig(config); }
+  catch (error) { return hold('GATE_CONFIG_INVALID', { findings: [{ code: 'GATE_CONFIG_INVALID', message: error.message }] }); }
+  if (!executeProfile || typeof executeProvider !== 'string' || !executeProvider.trim()) return hold('GATE_CONFIG_INVALID');
+  if (ceiling !== undefined) {
+    if (!Number.isFinite(ceiling.spent) || ceiling.spent < 0 || !Number.isFinite(ceiling.ceiling) || ceiling.ceiling <= 0) return hold('COST_CEILING_INVALID');
+    if (ceiling.spent > ceiling.ceiling) return hold('COST_CEILING_BREACHED', { breach: { spent: ceiling.spent, ceiling: ceiling.ceiling } });
+  }
+  const sourceState = stepOutputs?.[config.decide_from.step];
+  if (!object(sourceState) || sourceState.status !== 'succeeded' || !object(sourceState.output)) return hold('GATE_SOURCE_MISSING');
+  const gate = stepOutputs?.[gateStepId];
+  if (!object(gate) || gate.status !== 'waiting_gate' || typeof gateToken !== 'string' || !gateToken
+    || gate.gateToken !== gateToken || !Number.isInteger(gate.epoch) || gate.epoch < 0
+    || sourceState.epoch !== gate.epoch) return hold('GATE_SOURCE_STALE');
+  const output = sourceState.output;
+  const action = ownField(output, config.decide_from.field);
+  const outcome = ['approve', 'revise', 'kill'].find(key => config.decide_from[key].includes(action));
+  if (!outcome) return hold('GATE_ACTION_UNKNOWN');
+  const findings = [];
+  for (const validator of config.validators ?? []) {
+    const reviewState = stepOutputs?.[validator.review_step];
+    const review = reviewState?.status === 'succeeded' ? reviewState.output : undefined;
+    if (reviewState && reviewState.epoch !== gate.epoch) return hold('GATE_SOURCE_STALE');
+    findings.push(...validateDecision(output, review, validator, { executeProfile, executeProvider }));
+  }
+  if (findings.length) return hold('GATE_VALIDATION_FAILED', { findings });
+  return {
+    outcome, rationale: output.rationale ?? `Mapped ${String(action)} to ${outcome}`,
+    source: { step: config.decide_from.step, field: config.decide_from.field, action, gateStepId, gateToken,
+      epoch: sourceState.epoch, acceptedDispatchToken: sourceState.acceptedDispatchToken,
+      outputDigest: profilesDigest(output), output: structuredClone(output) },
+  };
+}

package/lib/pipeline-profiles.js

@@ -0,0 +1,200 @@
+/** Compose-owned sidecar schema and whole-wave admission. No dispatch or I/O. */
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import YAML from 'yaml';
+import { validateAgentString, resolveAgentConfig } from './agent-string.js';
+
+export class PipelineProfileError extends Error {
+  constructor(code, message) { super(message); this.name = 'PipelineProfileError'; this.code = code; }
+}
+const fail = (message, code = 'PIPELINE_PROFILE_INVALID') => { throw new PipelineProfileError(code, message); };
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const keys = (value, allowed) => {
+  if (!object(value) || Object.keys(value).some(key => !allowed.includes(key))) fail(`Invalid configuration fields: ${JSON.stringify(value)}`);
+};
+export function ownField(value, path) {
+  if (typeof path !== 'string' || !/^[A-Za-z_][\w]*(\.[A-Za-z_][\w]*)*$/.test(path)
+    || path.split('.').some(key => ['__proto__', 'prototype', 'constructor'].includes(key))) fail('Invalid field path');
+  for (const key of path.split('.')) {
+    if (!object(value) || !Object.hasOwn(value, key)) return undefined;
+    value = value[key];
+  }
+  return value;
+}
+export function normalizeOwnedPath(path) {
+  if (typeof path !== 'string' || !path.length || /^[\\/]|^[A-Za-z]:/.test(path)
+    || /[\0*?\[\]{}]/.test(path)) fail('Ownership requires literal repository-relative file paths', 'WAVE_OWNERSHIP_INVALID');
+  const parts = path.replaceAll('\\', '/').split('/');
+  if (parts.includes('..') || parts.some(part => part.toLowerCase() === '.git')) fail(`Unsafe ownership path: ${path}`, 'WAVE_OWNERSHIP_INVALID');
+  const normalized = posix.normalize(parts.join('/'));
+  if (normalized === '.' || normalized.endsWith('/')) fail(`Not a file path: ${path}`, 'WAVE_OWNERSHIP_INVALID');
+  return normalized;
+}
+function agent(profile, provider) {
+  if (typeof profile !== 'string' || !profile.trim() || profile.split(':').length > 3) fail('Profile must be a non-empty agent string');
+  validateAgentString(profile);
+  const resolved = resolveAgentConfig(profile);
+  if (provider && resolved.provider !== provider) fail(`Profile provider ${resolved.provider} differs from stage ${provider}`);
+  return { ...resolved, profile };
+}
+export function validateGateConfig(entry) {
+  keys(entry, ['decide_from', 'validators']);
+  keys(entry.decide_from, ['step', 'field', 'approve', 'revise', 'kill']);
+  const mapping = entry.decide_from;
+  if (typeof mapping.step !== 'string' || !mapping.step) fail('decide_from.step is required');
+  ownField({}, mapping.field);
+  const seen = new Set();
+  for (const outcome of ['approve', 'revise', 'kill']) {
+    if (!Array.isArray(mapping[outcome])) fail(`${outcome} must be a value array`);
+    for (const value of mapping[outcome]) {
+      if (typeof value !== 'string' || !value || seen.has(value)) fail('Gate values must be nonempty, disjoint strings');
+      seen.add(value);
+    }
+  }
+  if (entry.validators !== undefined && !Array.isArray(entry.validators)) fail('validators must be an array');
+  for (const validator of entry.validators ?? []) {
+    keys(validator, ['name', 'review_step', 'tasks_field']);
+    if (validator.name !== 'WaveDecision' || typeof validator.review_step !== 'string' || !validator.review_step) fail('Unknown validator or missing review_step');
+    ownField({}, validator.tasks_field ?? 'tasks');
+  }
+  return entry;
+}
+function ancestor(steps, from, gate, visited = new Set()) {
+  if (visited.has(gate)) return false;
+  visited.add(gate);
+  return (steps.find(step => step.id === gate)?.after ?? []).some(id => id === from || ancestor(steps, from, id, visited));
+}
+export function normalizePipelineProfiles(raw, spec) {
+  if (!object(raw)) fail('Profiles must be an object');
+  const parsed = typeof spec === 'string' ? YAML.parse(spec) : spec;
+  const flows = Object.values(parsed?.flows ?? {}).filter(flow => Array.isArray(flow?.steps));
+  const steps = flows.flatMap(flow => flow.steps);
+  const normalized = structuredClone(raw);
+  for (const [id, entry] of Object.entries(raw)) {
+    if (id.startsWith('_')) continue;
+    const matches = steps.filter(step => step.id === id);
+    if (!matches.length) fail(`Step ${id} not found in spec`);
+    for (const step of matches) {
+      if (object(entry) && Object.hasOwn(entry, 'decide_from')) {
+        validateGateConfig(entry);
+        if (!step.gate || step.agent || step.fanout || id === 'review_gate') fail(`Step ${id} is not an available output gate`);
+        const flowSteps = flows.find(flow => flow.steps.includes(step)).steps;
+        for (const source of [entry.decide_from.step, ...(entry.validators ?? []).map(v => v.review_step)]) {
+          if (!ancestor(flowSteps, source, id)) fail(`Source ${source} must be an ancestor of ${id}`);
+        }
+        continue;
+      }
+      if (step.gate && !step.agent && !step.fanout) fail(`Gate ${id} requires decide_from`);
+      if (object(entry)) {
+        keys(entry, ['default', 'tier_from']);
+        if (entry.tier_from !== undefined && (entry.tier_from !== 'item.tier' || step.fanout?.dispatch !== 'consumer')) fail('tier_from requires a consumer fanout and item.tier');
+      } else if (typeof entry !== 'string') fail(`Invalid profile for ${id}`);
+      for (const stage of step.fanout?.steps ?? [step]) {
+        const resolved = agent(typeof entry === 'string' ? entry : entry.default, stage.agent ?? 'claude');
+        if (step.fanout?.dispatch === 'engine' && (resolved.tier || resolved.template)) fail('Engine dispatch cannot apply Compose templates or tiers');
+        if (entry.tier_from) for (const tier of ['critical', 'standard', 'fast']) resolveConsumerProfile(entry, { tier }, resolved.provider);
+      }
+    }
+  }
+  if (raw._consumer !== undefined) {
+    if (!object(raw._consumer)) fail('_consumer must be an object');
+    for (const [id, policy] of Object.entries(raw._consumer)) {
+      keys(policy, ['ownership', 'independent', 'checkpoint_gate']);
+      if (policy.ownership !== undefined && policy.ownership !== 'item.files_owned') fail('ownership must be item.files_owned');
+      if (policy.independent !== undefined && typeof policy.independent !== 'boolean') fail('independent must be boolean');
+      const matches = steps.filter(step => step.id === id);
+      if (!matches.length) fail(`Consumer ${id} not found`);
+      for (const step of matches) {
+        if (step.fanout?.dispatch !== 'consumer') fail(`${id} is not consumer-dispatched`);
+        if ((policy.ownership || policy.checkpoint_gate) && step.fanout.isolation !== 'worktree') fail('Ownership/checkpoints require worktree isolation');
+        if (policy.checkpoint_gate !== undefined) {
+          const flow = flows.find(flow => flow.steps.includes(step));
+          const gate = flow.steps.find(s => s.id === policy.checkpoint_gate);
+          if (!gate?.gate || gate.after?.length !== 1 || gate.after[0] !== id || gate.when) fail('checkpoint_gate must be the direct unconditional merge gate');
+        }
+      }
+    }
+  }
+  if (raw._costCeiling !== undefined) {
+    const c = raw._costCeiling;
+    keys(c, ['input', 'default', 'gates']);
+    if (typeof c.input !== 'string' || !/^[A-Za-z_]\w*$/.test(c.input)
+      || !Number.isFinite(c.default) || c.default <= 0 || !Array.isArray(c.gates) || !c.gates.length
+      || c.gates.some(id => !steps.some(s => s.id === id && s.gate))) fail('Invalid _costCeiling');
+  }
+  return normalized;
+}
+/** Replacing a default must never erase the per-item routing policy. Re-preflight the result. */
+export function mergeRuntimeProfiles(normalized, runtime = {}) {
+  const result = structuredClone(normalized);
+  for (const [id, override] of Object.entries(runtime)) {
+    if (id.startsWith('_') || object(result[id]) && result[id].decide_from) fail(`Runtime override is not an agent profile: ${id}`);
+    const previous = result[id];
+    if (object(override)) {
+      keys(override, ['default', 'tier_from']);
+      if (override.tier_from !== undefined && override.tier_from !== previous?.tier_from) fail('Runtime overrides cannot change tier_from');
+    } else if (typeof override !== 'string') fail('Runtime override must be an agent profile');
+    result[id] = object(previous) ? { ...previous, default: typeof override === 'string' ? override : override.default } : structuredClone(override);
+    agent(typeof result[id] === 'string' ? result[id] : result[id].default);
+  }
+  return result;
+}
+export function resolveConsumerProfile(entry, item, provider) {
+  const resolved = agent(typeof entry === 'string' ? entry : entry?.default, provider);
+  if (!entry?.tier_from) return resolved;
+  if (entry.tier_from !== 'item.tier') fail('Unsupported tier_from');
+  const tier = ownField({ item }, entry.tier_from);
+  if (tier === undefined && !Object.hasOwn(item ?? {}, 'tier')) return resolved;
+  if (!['critical', 'standard', 'fast'].includes(tier)) fail(`Unknown item tier: ${String(tier)}`, 'WAVE_TIER_INVALID');
+  return agent(`${resolved.provider}:${resolved.template ?? ''}:${tier}`, provider);
+}
+export function validateWaveAdmission(entry, items, opts = {}) {
+  const findings = [];
+  const profiles = [];
+  const owners = new Map();
+  const add = (code, itemIndex, message) => findings.push({ code, itemIndex, message, severity: 'error' });
+  if (!Array.isArray(items)) return { ok: false, findings: [{ code: 'WAVE_INPUT_INVALID', message: 'Recorded wave input must be an array' }] };
+  items.forEach((item, itemIndex) => {
+    try { profiles.push(resolveConsumerProfile(entry, item, opts.provider)); }
+    catch (error) { add(error.code ?? 'WAVE_TIER_INVALID', itemIndex, error.message); }
+    if (opts.independent && (!Array.isArray(item?.depends_on) || item.depends_on.length)) add('WAVE_DEPENDENCIES_NOT_EMPTY', itemIndex, 'Independent tasks require empty depends_on');
+    if (opts.ownership || Object.hasOwn(item ?? {}, 'files_owned')) {
+      try {
+        if (!Array.isArray(item?.files_owned)) fail('files_owned is required', 'WAVE_OWNERSHIP_INVALID');
+        for (const file of item.files_owned.map(normalizeOwnedPath)) {
+          if (owners.has(file) && owners.get(file) !== itemIndex) add('WAVE_OWNERSHIP_CONFLICT', itemIndex, `Multiple tasks own ${file}`);
+          owners.set(file, itemIndex);
+        }
+      } catch (error) { add(error.code, itemIndex, error.message); }
+    }
+  });
+  return { ok: findings.length === 0, findings, profiles };
+}
+export function profilesDigest(normalized) {
+  const canonical = value => Array.isArray(value) ? value.map(canonical) : object(value)
+    ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+  return createHash('sha256').update(JSON.stringify(canonical(normalized))).digest('hex');
+}
+/** Dispatch 2 replaces the string-only wrapper with this, after resolving spec inputs. */
+export function preflightPipelineProfiles(raw, spec, runtime = {}) {
+  const normalized = normalizePipelineProfiles(mergeRuntimeProfiles(normalizePipelineProfiles(raw, spec), runtime), spec);
+  const resolved = {};
+  const overrides = {};
+  for (const [id, entry] of Object.entries(normalized)) {
+    if (!id.startsWith('_') && !entry?.decide_from) {
+      resolved[id] = resolveConsumerProfile(entry, {});
+      if (entry.tier_from) overrides[id] = ['critical', 'standard', 'fast'].map(tier => resolveConsumerProfile(entry, { tier }));
+    }
+  }
+  const parsed = typeof spec === 'string' ? YAML.parse(spec) : spec;
+  for (const step of Object.values(parsed?.flows ?? {}).flatMap(flow => flow?.steps ?? [])) {
+    if (Object.hasOwn(normalized, step.id)) continue;
+    const stages = step.fanout?.steps ?? (step.agent ? [step] : []);
+    for (const [index, stage] of stages.entries()) {
+      const resolution = agent(stage.agent ?? 'claude');
+      if (step.fanout?.dispatch === 'engine' && (resolution.template || resolution.tier)) fail('Engine dispatch cannot apply Compose templates or tiers');
+      resolved[stages.length === 1 ? step.id : `${step.id}/${index}`] = resolution;
+    }
+  }
+  return { ok: true, normalized, resolved, profilesDigest: profilesDigest({ normalized, resolved, overrides }) };
+}

package/lib/result-normalizer.js

@@ -696,6 +696,19 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
       if (!usageTotals.model && runResult.telemetry?.model) usageTotals.model = runResult.telemetry.model;
     }
 
+    // The connector's final result is authoritative for cost: when the streamed
+    // step_usage events carried no dollar value (stratum's codex event omits
+    // cost_usd when the turn reports none; older servers hardcoded 0) but the
+    // result reports one WITH provenance, adopt it instead of filing the call as
+    // free/estimated. Found by the COMP-FABLE-ASTRA wave golden: every codex
+    // worker reached the cost gate as costUnknown.
+    if (usageFromEvents && !(usageTotals.cost_usd > 0)
+      && typeof runUsage?.usd === 'number' && Number.isFinite(runUsage.usd) && runUsage.usd > 0
+      && ['reported', 'estimated'].includes(runResult?.usdSource)) {
+      usageTotals.cost_usd = runUsage.usd;
+      primaryUsdSource = runResult.usdSource;
+    }
+
     const usages = [];
     const primaryFromEvents = usageFromEvents || primaryUsdSource !== null;
     if (primaryFromEvents) {

package/lib/stratum-mcp-client.js

@@ -152,10 +152,10 @@ export function resolveStepProfile(profiles, stepId) {
 }
 
 /** The stratum MCP surface version compose's request vocabulary requires.
- *  Pinned in stratum at ts/contracts/mcp-surface.json ("surface": 19) and asserted by
- *  ts/tests/mcp/contracts-grammar.test.ts. Bump this and the package floor together. */
-export const REQUIRED_STRATUM_SURFACE = 19;
-export const REQUIRED_STRATUM_RANGE = '>=0.5.0';
+ *  Pinned in stratum at ts/contracts/mcp-surface.json ("surface": 20, receipt.detail)
+ *  and asserted by ts/tests/mcp/contracts-grammar.test.ts. Package versions bump at release. */
+export const REQUIRED_STRATUM_SURFACE = 20;
+export const REQUIRED_STRATUM_RANGE = '>=0.5.2';
 
 /**
  * Build the TS `stratum_agent_run` request from an agent string + compose-side

package/lib/team-flag.js

@@ -5,7 +5,7 @@
  * side effects that prevent clean import in test files).
  */
 
-export const KNOWN_TEAMS = ['review', 'research', 'feature'];
+export const KNOWN_TEAMS = ['review', 'research', 'feature', 'fable-astra'];
 
 /**
  * Parse and validate the --team flag from CLI args.