@smartmemory/compose 0.4.1 → 0.5.1

package/lib/decision-blocks.js

@@ -0,0 +1,38 @@
+/**
+ * Parse markdown text containing ```decision fenced blocks.
+ * Returns { parts: Array<{ type: 'text'|'decision', content: string|object }> }.
+ *
+ * This module is shared by the shipped server and the browser source. Keep it
+ * under lib/ so npm installs do not need the otherwise development-only src/.
+ */
+export function parseDecisionBlocks(text) {
+  const parts = [];
+  const regex = /```decision\n([\s\S]*?)```/g;
+  let lastIndex = 0;
+  let match;
+
+  while ((match = regex.exec(text)) !== null) {
+    if (match.index > lastIndex) {
+      parts.push({ type: 'text', content: text.slice(lastIndex, match.index) });
+    }
+
+    const raw = match[1].trim();
+    try {
+      parts.push({ type: 'decision', content: JSON.parse(raw) });
+    } catch {
+      parts.push({ type: 'text', content: raw });
+    }
+
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < text.length) {
+    parts.push({ type: 'text', content: text.slice(lastIndex) });
+  }
+
+  if (parts.length === 0) {
+    parts.push({ type: 'text', content: text });
+  }
+
+  return { parts };
+}

package/lib/dispatch-ledger.js

@@ -58,6 +58,12 @@ const EVENT_FIELDS = {
       'build_id', 'feature_code', 'step_id', 'attempt', 'model',
       'effort_intended', 'effort_executed', 'tokens_in', 'tokens_out',
       'tokens_total', 'usd', 'duration_ms', 'note',
+      // COMP-BUILD-CANCEL S03-6 (C44): compose's DERIVED transport for the run —
+      // provider codex plus a cancellationId sent implies exec. Never `transport`:
+      // stratum reports none on its ConnectorResult, so this is a rule, not an
+      // observation. Registered here AND in the `dispatch` validator below, because
+      // this list is an allow-list and an unknown field drops the whole event.
+      'transport_derived',
     ],
   },
   settlement: {
@@ -146,6 +152,7 @@ function validateEvent(event, { allowExtra = false } = {}) {
         optionalNullableNumber(event, field);
       }
       optionalString(event, 'note');
+      optionalNullableString(event, 'transport_derived');
       break;
     case 'settlement':
       requireString(event, 'dispatch_id');

package/lib/experiment-pricing.js

@@ -6,13 +6,17 @@
  * model IDs degrade to usd:null rather than crashing — a crashed / future
  * model still yields a record with partial metrics.
  *
- * Price source: Anthropic public pricing page + OpenAI pricing (as of 2026-07).
+ * Claude 5 rates: COMP-FABLE-ASTRA slice 1 (2026-09). Earlier rates retained
+ * for historical receipts (Anthropic / OpenAI, 2026-07).
  * Keys are prefix-matched so dated variants (e.g. claude-sonnet-4-6-20250514)
  * resolve against the base key.
  */
 
 /** @type {Record<string, { inputPerMTok: number, outputPerMTok: number }>} */
 const EXPERIMENT_PRICING = {
+  'claude-fable-5-1':  { inputPerMTok: 10,  outputPerMTok: 50 },
+  'claude-opus-5':     { inputPerMTok: 5,   outputPerMTok: 25 },
+  'claude-sonnet-5':   { inputPerMTok: 2,   outputPerMTok: 10 },
   // Claude 4.x
   'claude-opus-4-8':    { inputPerMTok: 5,    outputPerMTok: 25  },
   'claude-opus-4-7':    { inputPerMTok: 5,    outputPerMTok: 25  },

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/fluid/factory.js

@@ -20,9 +20,17 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 
 import { getSmartmemoryConfig } from '../smartmemory-config.js';
+
+/**
+ * Well under the substrate's own membership cap of 100
+ * (`auth_repository.py:730`). A portfolio turn costs one round trip per member
+ * with no server-side batching, so the practical ceiling is latency, not the
+ * substrate.
+ */
+const MAX_PORTFOLIO_MEMBERS = 16;
 import { FluidConfigError, MUTATION_SCOPE, mutationScopeAtLeast } from './provider.js';
 import { LocalFluidProvider } from './local-provider.js';
 import { SmartMemoryFluidProvider } from './smartmemory-provider.js';
@@ -74,6 +82,109 @@ function loadFluidConfig(cwd) {
   return fluid;
 }
 
+/**
+ * @typedef {object} PortfolioMember
+ * @property {string} id    the label the user chose; unique within the portfolio
+ * @property {string} root  absolute path to that member's Compose project
+ */
+
+/**
+ * Parse and validate `fluid.portfolio` (FOH-7).
+ *
+ * Read HERE, in the authoritative validating reader, and deliberately not in
+ * `lib/maya-config.js`: that one swallows a malformed config as `{}`, so a
+ * portfolio with a typo in it would come back as "no portfolio declared" and the
+ * turn would quietly answer for one product instead of refusing. A config with
+ * two readers where only one validates is how a misconfiguration becomes a
+ * silent downgrade.
+ *
+ * @param {string} cwd the declaring root
+ * @returns {{members: PortfolioMember[]} | null} null when none is declared
+ */
+export function parsePortfolioConfig(cwd) {
+  const fluid = loadFluidConfig(cwd);
+  const portfolio = fluid.portfolio;
+  if (portfolio === undefined || portfolio === null) return null;
+
+  const where = join(cwd, '.compose/compose.json');
+  if (typeof portfolio !== 'object' || Array.isArray(portfolio)) {
+    throw new FluidConfigError(
+      `compose: fluid.portfolio at ${where} must be an object`, { path: where },
+    );
+  }
+  const declared = portfolio.members;
+  if (!Array.isArray(declared) || declared.length === 0) {
+    throw new FluidConfigError(
+      `compose: fluid.portfolio.members at ${where} must be a non-empty array — ` +
+      `a portfolio with no members is a portfolio that cannot answer anything`,
+      { path: where },
+    );
+  }
+  if (declared.length > MAX_PORTFOLIO_MEMBERS) {
+    throw new FluidConfigError(
+      `compose: fluid.portfolio.members at ${where} declares ${declared.length} members, ` +
+      `over the limit of ${MAX_PORTFOLIO_MEMBERS}`,
+      { path: where },
+    );
+  }
+
+  const members = [];
+  const seen = new Set();
+  for (const entry of declared) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+      throw new FluidConfigError(
+        `compose: every fluid.portfolio.members entry at ${where} must be an object`, { path: where },
+      );
+    }
+    const id = typeof entry.id === 'string' ? entry.id.trim() : '';
+    const rawRoot = typeof entry.root === 'string' ? entry.root.trim() : '';
+    if (!id || !rawRoot) {
+      throw new FluidConfigError(
+        `compose: every fluid.portfolio.members entry at ${where} needs a non-empty "id" and "root"`,
+        { path: where },
+      );
+    }
+    if (seen.has(id)) {
+      throw new FluidConfigError(
+        `compose: fluid.portfolio.members at ${where} declares "${id}" twice — ` +
+        `ids label the source of every result, so a duplicate makes the answer ambiguous`,
+        { path: where, id },
+      );
+    }
+    seen.add(id);
+
+    const root = resolve(cwd, rawRoot);
+    // A member must be a Compose project, and `.compose/compose.json` is what
+    // makes it one. Accepting a bare `.compose/` directory would fall through to
+    // the local provider and contribute an empty corpus — indistinguishable, in
+    // the answer, from a real product that happens to have no ideas.
+    if (!existsSync(join(root, '.compose/compose.json'))) {
+      throw new FluidConfigError(
+        `compose: fluid.portfolio member "${id}" at ${where} points at ${root}, ` +
+        `which is not a Compose project (no .compose/compose.json)`,
+        { path: where, id, root },
+      );
+    }
+    members.push({ id, root });
+  }
+
+  // Self-membership is never INFERRED — that would be the discovery D-FOH-7-2
+  // forbids. But a portfolio that omits the corpus the user is looking at
+  // silently answers without it, so its absence is refused by name rather than
+  // producing a quietly smaller result.
+  const declaringRoot = resolve(cwd);
+  if (!members.some((m) => m.root === declaringRoot)) {
+    throw new FluidConfigError(
+      `compose: fluid.portfolio at ${where} does not list its own declaring root. ` +
+      `Membership is never inferred, so this project would be excluded from its own ` +
+      `portfolio — add an entry with "root": "." if that is not what you meant`,
+      { path: where, declaringRoot },
+    );
+  }
+
+  return { members };
+}
+
 /**
  * Construct the configured provider.
  *

package/lib/fluid/ideabox-manifest.js

@@ -0,0 +1,203 @@
+/**
+ * lib/fluid/ideabox-manifest.js — a durable record of a migration in flight.
+ *
+ * COMP-IDEABOX-MIGRATE-DIALECT FU-1.
+ *
+ * THE FAILURE THIS EXISTS TO PREVENT
+ * ----------------------------------
+ * `importIdeabox` writes records sequentially. Crash on idea 2 and ideas 3..N
+ * were never issued, so they carry no event — and the gate's resume policy is
+ * derived from the event log, so it classifies every one of them as a
+ * hand-added stray and refuses. The recovery the refusal names (`compose
+ * ideabox add`, then `render`) runs the same gate, so the installation is
+ * stranded with no way forward.
+ *
+ * The event log can only testify about handles the import reached. The
+ * unattempted TAIL of a migration leaves no trace anywhere, which is why this
+ * has to be an intention written down BEFORE the first write rather than an
+ * inference from what happened after it.
+ *
+ * WHY IT IS SAFE TO TRUST
+ * -----------------------
+ * The manifest may only ever WIDEN the resumable set, and only under two
+ * conditions checked together: it is still open (a completed import removes
+ * it), and its hash matches the document being read right now. A hand-added
+ * idea changes the document, so the hash stops matching and the gate refuses —
+ * the protection the gate exists for is not weakened by anything here.
+ *
+ * WHERE IT LIVES
+ * --------------
+ * `.compose/data/`, beside the provider's lock. `data/` is blanket-gitignored
+ * (`.gitignore:3`); the ideabox's own directory is TRACKED, and a stray file
+ * there gets committed by accident (see the temp-file note in
+ * `render-ideabox.js`). A manifest that is missing — a fresh clone, a provider
+ * with no local lock path — degrades to REFUSE, which is the safe direction.
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * The source document changed WHILE its own migration was running.
+ *
+ * Raised by `importIdeabox` after its last write, when the file it parsed is no
+ * longer the file on disk. During a migration the ideabox is still the user's
+ * OWN SOURCE DOCUMENT, not generated output, so an edit to it is real content
+ * that never reached the store — and the projection that follows would erase
+ * it. Failing here leaves the manifest OPEN, so the next run refuses as
+ * `IDEABOX_MANIFEST_STALE` and names the mid-migration edit.
+ *
+ * Lives in this leaf module rather than beside the other migration errors
+ * because `ideabox-migrate.js` imports `importIdeabox`, so importing back from
+ * it would close a cycle.
+ */
+export class IdeaboxSourceChangedDuringImport extends Error {
+  constructor(ideaboxPath) {
+    super(
+      `compose: the ideabox at ${ideaboxPath} was edited while its migration was running, so the ` +
+      `import stopped before finishing. Until the migration completes this file is still your ` +
+      `source document rather than generated output, and continuing would have replaced it with a ` +
+      `projection built from the version read at the start — destroying whatever was just added. ` +
+      `Nothing has been changed and the unfinished migration is still recorded. Records written ` +
+      `before the edit are already in the store, so re-running will NOT pick the edit up. Decide ` +
+      `which document is right and say so: \`compose ideabox adopt-file\` finishes the migration ` +
+      `against the file as it now stands, keeping the edit; \`compose ideabox discard-edits\` puts ` +
+      `the file back as the migration read it and finishes that, after saving a copy of the current ` +
+      `file first.`
+    );
+    this.name = 'IdeaboxSourceChangedDuringImport';
+    this.code = 'IDEABOX_SOURCE_CHANGED_DURING_IMPORT';
+  }
+}
+
+/**
+ * The current manifest format.
+ *
+ * v2 adds `text`: the source markdown itself, not only its hash. That is what
+ * makes `compose ideabox discard-edits` LOSSLESS — without the original
+ * document there is nothing to put back, and the only recovery from a
+ * mid-migration edit is to adopt whatever the file now says. An ideabox is a
+ * small file and this is written once per migration.
+ *
+ * A v1 manifest is still valid and still resumes; it simply has no `text`, so
+ * `discard-edits` refuses on one and names `adopt-file` as its recovery.
+ */
+export const MANIFEST_VERSION = 2;
+
+/** Content identity of the document a migration was planned against. */
+export function hashMarkdown(markdown) {
+  return createHash('sha256').update(String(markdown ?? ''), 'utf8').digest('hex');
+}
+
+/**
+ * Where this provider keeps the manifest for this ideabox, or null when there
+ * is nowhere durable to put one.
+ *
+ * Derived from `provider.lockPath`, which is the one machine-local, gitignored
+ * location both the gate and the importer already have in hand. Keyed by the
+ * ideabox path so two ideaboxes under one project do not share a manifest.
+ * A provider with no lock path (SmartMemory — see `factory.js`) gets null and
+ * therefore no resume widening, which matches its already-documented lack of
+ * machine-local coordination.
+ */
+export function manifestPath(provider, ideaboxPath) {
+  if (!provider?.lockPath || !ideaboxPath) return null;
+  const key = createHash('sha256').update(String(ideaboxPath)).digest('hex').slice(0, 12);
+  return join(dirname(provider.lockPath), `ideabox-migration-${key}.json`);
+}
+
+/**
+ * Declare a migration BEFORE the first record is written.
+ *
+ * @param {object} provider
+ * @param {string} ideaboxPath
+ * @param {object} plan
+ * @param {string} plan.markdown the exact text that was parsed
+ * @param {string[]} plan.planned every idea handle the import intends to write
+ * @param {string[]} [plan.plannedClusters] cluster NAMES, for diagnostics only —
+ *   cluster handles are allocated by the store and are not known in advance,
+ *   and the gate's resume decision is about idea handles from the markdown.
+ * @returns {string|null} the path written, or null when there is no home
+ */
+export function openManifest(provider, ideaboxPath, { markdown, planned, plannedClusters = [] }) {
+  const path = manifestPath(provider, ideaboxPath);
+  if (!path) return null;
+  const hash = hashMarkdown(markdown);
+
+  // A RETRY MUST NOT TOUCH THE PLAN IT IS RETRYING.
+  //
+  // Every resumed import came through here again, and rewriting a manifest that
+  // already says the same thing is pure risk: the file whose entire job is to
+  // survive a crash was being destroyed and recreated by each attempt to
+  // recover from one. An open manifest carrying this hash and this plan is
+  // already correct, so it is left exactly where it is.
+  const open = readManifest(provider, ideaboxPath);
+  // An identical plan is left exactly where it is — EXCEPT when it predates the
+  // stored text. We are holding the very document a v1 manifest failed to keep,
+  // so upgrading it here costs one write and gives an in-flight migration the
+  // lossless recovery it was started without.
+  if (open && open.hash === hash && sameSet(open.planned, planned)
+      && typeof open.text === 'string') return path;
+
+  mkdirSync(dirname(path), { recursive: true });
+  const body = JSON.stringify({
+    version: MANIFEST_VERSION,
+    source: ideaboxPath,
+    hash,
+    // The document itself, so `discard-edits` has something to put back.
+    text: String(markdown ?? ''),
+    planned,
+    plannedClusters,
+    startedAt: new Date().toISOString(),
+  }, null, 2);
+
+  // Temp + rename, the pattern `publishProjection` uses on the projection.
+  // A plain `writeFileSync` truncates first, so a crash or a full disk between
+  // the truncate and the write leaves a manifest that is present but empty —
+  // and a manifest that cannot be read is a manifest that does not vouch for
+  // anything, which turns the whole remaining corpus into strays. `rename` is
+  // atomic: the manifest is either the old plan or the new one, never neither.
+  const tmp = `${path}.tmp.${randomUUID()}`;
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+  return path;
+}
+
+/** Order-insensitive equality for two handle lists. */
+function sameSet(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+  const set = new Set(a);
+  return b.every((x) => set.has(x));
+}
+
+/** The import finished. Removing the file is what makes "open" mean something. */
+export function closeManifest(provider, ideaboxPath) {
+  const path = manifestPath(provider, ideaboxPath);
+  if (!path) return;
+  rmSync(path, { force: true });
+}
+
+/**
+ * The open manifest for this ideabox, or null.
+ *
+ * An unreadable or malformed manifest reads as absent: every ambiguous state
+ * here has to fall back to refusing, because the one thing this must not do is
+ * widen the resumable set on a guess.
+ */
+export function readManifest(provider, ideaboxPath) {
+  const path = manifestPath(provider, ideaboxPath);
+  if (!path || !existsSync(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    if (!data || typeof data.hash !== 'string' || !Array.isArray(data.planned)) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}