@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/chat/context-compactor.mjs

@@ -0,0 +1,250 @@
+/**
+ * lib/chat/context-compactor.mjs — the live bridge between the owned-loop's
+ * message history and the deterministic context-continuation contract
+ * (lib/chat/context-continuation.mjs, construct-6zga.1.10).
+ *
+ * The owned-loop engine keeps an ordered array of provider messages (the AI SDK
+ * `messages[]`: the user turns it pushed plus the assistant/tool messages the model
+ * produced). When a turn's reported context crosses the capability profile's
+ * compaction trigger, this module maps that live history onto the contract's layer
+ * inventory, runs compactContext, and — crucially — rebuilds a *provider-valid*
+ * message array from the result. Provider validity is the constraint the pure
+ * contract module does not own: the rebuilt array must begin with a user message,
+ * keep tool-call/tool-result pairs intact, and never place two same-role turns
+ * adjacently. The rebuild satisfies all three by collapsing the compacted prefix
+ * into a single user "continuation" message (task + every user constraint verbatim,
+ * plus one real summary of the elided assistant/tool work) followed by an
+ * assistant-led verbatim suffix of the most recent turns.
+ *
+ * No silent loss: user text (task, constraints, approvals) is always carried
+ * verbatim into the recap; only the model's own assistant reasoning and tool
+ * results are summarized. When required state alone exceeds the budget the contract
+ * returns a blocker and this module compacts nothing — it surfaces the blocker as a
+ * user-visible notice instead.
+ *
+ * Pure except for the injected async `summarize`, so the rebuild logic is tested
+ * without the AI SDK or a network call.
+ */
+
+import { compactContext, validateContinuationPacket } from './context-continuation.mjs';
+
+function estimateTextTokens(text) {
+  return Math.ceil(String(text || '').length / 4);
+}
+
+// AI SDK messages carry content either as a plain string (the user turns the
+// engine pushes) or as an array of typed parts (assistant/tool messages from the
+// model). Flatten both to text for token accounting and summarization, naming
+// tool calls and results so an elided run still reads as what it did.
+
+function partToText(part) {
+  if (typeof part === 'string') return part;
+  if (typeof part?.text === 'string') return part.text;
+  if (part?.type === 'tool-call') return `[tool ${part.toolName || 'call'} ${safeJson(part.input ?? part.args)}]`;
+  if (part?.type === 'tool-result') return `[result ${part.toolName || ''} ${safeJson(part.output ?? part.result)}]`.trim();
+  if (typeof part?.content === 'string') return part.content;
+  return '';
+}
+
+function safeJson(value) {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  try { return JSON.stringify(value); } catch { return String(value); }
+}
+
+export function messageText(message) {
+  if (typeof message?.content === 'string') return message.content;
+  if (Array.isArray(message?.content)) return message.content.map(partToText).filter(Boolean).join('\n');
+  return '';
+}
+
+function messageRole(message) {
+  return message?.role || 'user';
+}
+
+// A segment is one turn-unit: a head message (user or assistant) plus any tool
+// messages that belong to it. Segmenting on tool boundaries is what lets the
+// rebuild keep every tool-call/tool-result pair together — a tool message never
+// becomes the head of a kept suffix, so the provider never sees an orphan result.
+
+export function segmentMessages(messages = []) {
+  const segments = [];
+  let current = null;
+  messages.forEach((message, index) => {
+    const role = messageRole(message);
+    if (role === 'tool' && current) {
+      current.indices.push(index);
+      current.hasTools = true;
+      return;
+    }
+    current = { firstIndex: index, indices: [index], head: role, hasTools: role === 'tool' };
+    segments.push(current);
+  });
+  return segments;
+}
+
+// Map the live segments onto the contract inventory. The system prompt is a
+// reconstructible layer (re-derived each turn by the composer, referenced by
+// source id). The first user segment is the task packet and every other user
+// segment is a user constraint — both required, kept verbatim. Assistant segments
+// are compactible; ordering them newest-first means compactContext fills the budget
+// with the most recent turns and elides the oldest, so the kept suffix is the
+// recent contiguous tail.
+
+export function buildInventory({ systemText = '', segments = [], messages = [], estimateTokens = estimateTextTokens } = {}) {
+  const layers = [];
+  if (systemText) {
+    layers.push({ id: 'static-instructions', kind: 'static-instructions', eligibility: 'reconstructible', sourceId: 'prompt:system', tokens: estimateTokens(systemText), content: systemText });
+  }
+
+  let seenUser = false;
+  const required = [];
+  const compactible = [];
+  for (const segment of segments) {
+    const text = segment.indices.map((i) => messageText(messages[i])).join('\n');
+    const tokens = estimateTokens(text);
+    if (segment.head === 'user') {
+      const kind = seenUser ? 'user-constraints' : 'task-packet';
+      seenUser = true;
+      required.push({ id: `seg-${segment.firstIndex}`, kind, eligibility: 'required', sourceId: null, tokens, content: text, firstIndex: segment.firstIndex });
+    } else {
+      const kind = segment.hasTools ? 'tool-results' : 'conversation-summary';
+      compactible.push({ id: `seg-${segment.firstIndex}`, kind, eligibility: 'compactible', sourceId: null, tokens, content: text, firstIndex: segment.firstIndex });
+    }
+  }
+
+  compactible.sort((a, b) => b.firstIndex - a.firstIndex);
+  return [...layers, ...required, ...compactible];
+}
+
+// Rebuild a provider-valid message array from the compaction packet. The cut index
+// is the earliest message belonging to a retained (recent) compactible segment,
+// nudged forward to land on an assistant message so the recap (a single user
+// message) is followed by an assistant turn. Everything before the cut collapses
+// into the recap: user text verbatim, assistant/tool work as the summary.
+
+export function rebuildMessages({ messages = [], segments = [], packet = null, summaryText = '' } = {}) {
+  const dispositionByFirstIndex = new Map();
+  for (const layer of packet?.layers || []) {
+    const match = /^seg-(\d+)$/.exec(layer.id || '');
+    if (match) dispositionByFirstIndex.set(Number(match[1]), layer.disposition);
+  }
+
+  const retainedFirstIndices = segments
+    .filter((s) => s.head !== 'user' && dispositionByFirstIndex.get(s.firstIndex) === 'retained')
+    .map((s) => s.firstIndex);
+
+  const lastAssistantIndex = (() => {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messageRole(messages[i]) === 'assistant') return i;
+    }
+    return messages.length;
+  })();
+
+  let cut = retainedFirstIndices.length ? Math.min(...retainedFirstIndices) : lastAssistantIndex;
+  while (cut < messages.length && messageRole(messages[cut]) !== 'assistant') cut++;
+  if (cut >= messages.length) cut = lastAssistantIndex;
+
+  const userVerbatim = [];
+  for (let i = 0; i < cut; i++) {
+    if (messageRole(messages[i]) === 'user') userVerbatim.push(messageText(messages[i]));
+  }
+
+  const recap = buildRecapText({ userVerbatim, summaryText, packet });
+  return [{ role: 'user', content: recap }, ...messages.slice(cut)];
+}
+
+export function buildRecapText({ userVerbatim = [], summaryText = '', packet = null } = {}) {
+  const elidedTokens = packet?.budget?.elidedTokens || 0;
+  const lines = [
+    '[Context continuation — earlier turns were compacted to fit the model context budget. Nothing required was dropped.]',
+    '',
+    '== Task & constraints (verbatim) ==',
+    ...userVerbatim.filter(Boolean),
+  ];
+  if (summaryText) {
+    lines.push('', `== Summary of prior assistant work & tool results (~${elidedTokens} tokens compacted) ==`, summaryText);
+  }
+  return lines.join('\n');
+}
+
+function fallbackSummary(elidedSegments, messages) {
+  const count = elidedSegments.reduce((n, s) => n + s.indices.length, 0);
+  const tail = elidedSegments.slice(-1).map((s) => messageText(messages[s.firstIndex]))[0] || '';
+  const clipped = tail.length > 280 ? `${tail.slice(0, 277)}...` : tail;
+  return `Compacted ${count} earlier message(s) without a model summary. Most recent elided turn began: ${clipped}`.trim();
+}
+
+export function shouldCompact({ contextTokens = 0, triggerTokens = null } = {}) {
+  return Number.isFinite(triggerTokens) && triggerTokens > 0 && contextTokens >= triggerTokens;
+}
+
+/**
+ * The orchestrator the engine calls once per turn. Returns the compaction outcome:
+ * `compacted` with a rebuilt message array and a notice, a `blocker` with a notice
+ * and no mutation when required state exceeds the budget, or an inert result when
+ * there is no pressure or nothing safe to elide. The packet is always returned for
+ * persistence and re-verification.
+ */
+export async function maybeCompact({
+  messages = [],
+  systemText = '',
+  triggerTokens = null,
+  contextTokens = 0,
+  summarize = null,
+  estimateTokens = estimateTextTokens,
+} = {}) {
+  if (!shouldCompact({ contextTokens, triggerTokens })) return { compacted: false, packet: null, notice: null, blocker: null };
+
+  const segments = segmentMessages(messages);
+  if (segments.length <= 2) return { compacted: false, packet: null, notice: null, blocker: null };
+
+  const inventory = buildInventory({ systemText, segments, messages, estimateTokens });
+  const packet = compactContext(inventory, { triggerTokens });
+
+  if (packet.blocker) {
+    const { requiredTokens, budgetTokens, overflowTokens } = packet.blocker;
+    return {
+      compacted: false,
+      packet,
+      blocker: packet.blocker,
+      notice: `Context pressure: required context (~${requiredTokens} tokens) exceeds the model budget (~${budgetTokens}) by ~${overflowTokens}. Nothing was dropped — reduce scope or start a new session.`,
+    };
+  }
+
+  const elidedSegments = segments.filter((s) => {
+    const layer = packet.layers.find((l) => l.id === `seg-${s.firstIndex}`);
+    return layer && layer.disposition === 'elided';
+  });
+  if (!elidedSegments.length) return { compacted: false, packet, notice: null, blocker: null };
+
+  const elidedText = elidedSegments
+    .sort((a, b) => a.firstIndex - b.firstIndex)
+    .map((s) => s.indices.map((i) => messageText(messages[i])).join('\n'))
+    .join('\n\n');
+
+  let summaryText = '';
+  if (typeof summarize === 'function') {
+    try {
+      const out = await summarize(elidedText, {
+        segmentCount: elidedSegments.length,
+        tokens: packet.budget.elidedTokens,
+      });
+      summaryText = typeof out === 'string' ? out.trim() : '';
+    } catch { summaryText = ''; }
+  }
+  if (!summaryText) summaryText = fallbackSummary(elidedSegments, messages);
+
+  const newMessages = rebuildMessages({ messages, segments, packet, summaryText });
+
+  const elidedMessageCount = elidedSegments.reduce((n, s) => n + s.indices.length, 0);
+  return {
+    compacted: true,
+    messages: newMessages,
+    packet,
+    blocker: null,
+    notice: `Context compacted: summarized ${elidedMessageCount} earlier message(s) (~${packet.budget.elidedTokens} tokens) to stay within the model's ~${triggerTokens}-token budget. Task, constraints, and recent turns kept verbatim.`,
+  };
+}
+
+export { estimateTextTokens, validateContinuationPacket };

package/lib/chat/context-continuation.mjs

@@ -0,0 +1,253 @@
+/**
+ * lib/chat/context-continuation.mjs — the deterministic context-continuation
+ * contract (construct-6zga.1.9).
+ *
+ * A chat session's context is an ordered set of layers — static instructions,
+ * role guidance, the task packet, validated evidence, tool results, the
+ * conversation summary, optional learned patterns, plus the protected state
+ * (user constraints, approvals, unresolved blockers). When context pressure
+ * crosses the capability profile's compaction trigger (the execution policy's
+ * continuation budget, never a model-name fixed limit), the session must compact
+ * without silent loss: it produces a structured continuation packet that retains
+ * required state verbatim, references reconstructible layers by source id for
+ * re-derivation, elides compactible layers with a truthful marker, and — when the
+ * required state alone exceeds the budget — yields a user-visible blocker instead
+ * of dropping anything. The packet carries source ids and token accounting so a
+ * reader can re-verify it, and rehydrateContinuation feeds the same layer set back
+ * through the composer on every surface. Reference shape:
+ * schemas/continuation-packet.schema.json.
+ */
+
+export const CONTINUATION_PACKET_SCHEMA_VERSION = 1;
+
+export const CONTEXT_LAYER_KINDS = Object.freeze([
+  'static-instructions',
+  'role-guidance',
+  'task-packet',
+  'validated-evidence',
+  'tool-results',
+  'conversation-summary',
+  'learned-patterns',
+  'user-constraints',
+  'approvals',
+  'blockers',
+]);
+
+export const COMPACTION_ELIGIBILITY = Object.freeze(['required', 'reconstructible', 'compactible']);
+
+export const LAYER_DISPOSITIONS = Object.freeze(['retained', 'referenced', 'elided']);
+
+// The protected layers carry state the loop must never silently drop: user
+// constraints, approvals, the current task packet, evidence provenance, and
+// unresolved blockers. Reconstructible layers can be re-derived from a durable
+// source by id, so the packet references rather than stores them. Compactible
+// layers are conversation history that compacts lossily but is never silently
+// lost — an elided one keeps a truthful marker of what was removed.
+
+const DEFAULT_ELIGIBILITY = Object.freeze({
+  'user-constraints': 'required',
+  approvals: 'required',
+  'task-packet': 'required',
+  'validated-evidence': 'required',
+  blockers: 'required',
+  'static-instructions': 'reconstructible',
+  'role-guidance': 'reconstructible',
+  'learned-patterns': 'reconstructible',
+  'conversation-summary': 'compactible',
+  'tool-results': 'compactible',
+});
+
+function estimateTextTokens(text) {
+  return Math.ceil(String(text || '').length / 4);
+}
+
+function sumTokens(layers) {
+  return layers.reduce((total, l) => total + (Number.isFinite(l.tokens) ? l.tokens : 0), 0);
+}
+
+/**
+ * Normalize a raw layer set into a deterministic inventory: assign each layer an
+ * id, a known kind, its compaction eligibility (explicit or kind-defaulted), and a
+ * token count. Order is preserved so callers control retention priority.
+ */
+export function classifyContextLayers(layers = [], { estimateTokens = estimateTextTokens } = {}) {
+  const list = Array.isArray(layers) ? layers : [];
+  return list.map((raw, index) => {
+    const kind = CONTEXT_LAYER_KINDS.includes(raw?.kind) ? raw.kind : 'conversation-summary';
+    const eligibility = COMPACTION_ELIGIBILITY.includes(raw?.eligibility)
+      ? raw.eligibility
+      : (DEFAULT_ELIGIBILITY[kind] || 'compactible');
+    const content = typeof raw?.content === 'string' ? raw.content : '';
+    const tokens = Number.isFinite(raw?.tokens) ? raw.tokens : estimateTokens(content);
+    return {
+      id: raw?.id || `${kind}-${index}`,
+      kind,
+      eligibility,
+      sourceId: raw?.sourceId ?? null,
+      tokens,
+      content,
+    };
+  });
+}
+
+function retainedLayer(layer) {
+  return { id: layer.id, kind: layer.kind, eligibility: layer.eligibility, disposition: 'retained', tokens: layer.tokens, sourceId: layer.sourceId, content: layer.content };
+}
+
+function referencedLayer(layer) {
+  return { id: layer.id, kind: layer.kind, eligibility: layer.eligibility, disposition: 'referenced', tokens: layer.tokens, sourceId: layer.sourceId, content: null };
+}
+
+function elidedLayer(layer) {
+  return { id: layer.id, kind: layer.kind, eligibility: layer.eligibility, disposition: 'elided', tokens: layer.tokens, sourceId: layer.sourceId, content: null };
+}
+
+/**
+ * Compact a classified inventory to the continuation budget. Required layers are
+ * retained verbatim; a reconstructible layer with a source id is referenced for
+ * re-derivation (and costs no budget), while one without a source id falls back to
+ * the compactible pool so it is never lost. Compactible layers fill the remaining
+ * budget in order and are elided with a marker once it is spent. When the required
+ * state alone exceeds the budget the result is a truthful blocker — nothing is
+ * dropped to make room for it.
+ */
+export function compactContext(inventory = [], { triggerTokens = null } = {}) {
+  const layers = classifyContextLayers(inventory);
+  const required = layers.filter((l) => l.eligibility === 'required');
+  const reconstructible = layers.filter((l) => l.eligibility === 'reconstructible');
+  const compactible = layers.filter((l) => l.eligibility === 'compactible');
+
+  const requiredTokens = sumTokens(required);
+  const budget = Number.isFinite(triggerTokens) && triggerTokens > 0 ? triggerTokens : Infinity;
+
+  const referenced = [];
+  const pressurePool = [...compactible];
+  for (const layer of reconstructible) {
+    if (layer.sourceId) referenced.push(referencedLayer(layer));
+    else pressurePool.push(layer);
+  }
+
+  const blocked = requiredTokens > budget;
+  const blocker = blocked
+    ? { reason: 'required-state-exceeds-budget', requiredTokens, budgetTokens: budget, overflowTokens: requiredTokens - budget }
+    : null;
+
+  const retainedCompactible = [];
+  const elided = [];
+  let used = 0;
+  const remaining = blocked ? 0 : budget - requiredTokens;
+  for (const layer of pressurePool) {
+    if (!blocked && used + layer.tokens <= remaining) {
+      retainedCompactible.push(retainedLayer(layer));
+      used += layer.tokens;
+    } else {
+      elided.push(elidedLayer(layer));
+    }
+  }
+
+  const packetLayers = [
+    ...required.map(retainedLayer),
+    ...referenced,
+    ...retainedCompactible,
+    ...elided,
+  ];
+
+  return buildContinuationPacket({
+    layers: packetLayers,
+    requiredState: required.map((l) => ({ id: l.id, kind: l.kind, sourceId: l.sourceId, tokens: l.tokens })),
+    budget,
+    requiredTokens,
+    blocker,
+  });
+}
+
+/**
+ * Assemble a structured, JSON-serializable continuation packet from a compaction
+ * result. Token accounting balances the retained, referenced, and elided layers
+ * against the budget so the packet is independently re-verifiable.
+ */
+export function buildContinuationPacket({ layers = [], requiredState = [], budget = Infinity, requiredTokens = 0, blocker = null } = {}) {
+  const retainedTokens = sumTokens(layers.filter((l) => l.disposition === 'retained'));
+  const elidedTokens = sumTokens(layers.filter((l) => l.disposition === 'elided'));
+  const referencedCount = layers.filter((l) => l.disposition === 'referenced').length;
+
+  return {
+    schemaVersion: CONTINUATION_PACKET_SCHEMA_VERSION,
+    budget: {
+      triggerTokens: Number.isFinite(budget) ? budget : null,
+      requiredTokens,
+      retainedTokens,
+      elidedTokens,
+      referencedCount,
+    },
+    layers,
+    requiredState,
+    blocker,
+  };
+}
+
+/**
+ * Re-derive the ordered layer set a composer needs to resume a session. Required
+ * and retained layers return their stored content; a referenced layer is re-derived
+ * through resolveSource(sourceId) so reconstructible context returns intact; an
+ * elided layer returns a truthful marker of what was removed. The same call backs
+ * terminal, web, export, and resume — one rehydration path, no surface drift.
+ */
+export function rehydrateContinuation(packet, { resolveSource = null } = {}) {
+  const layers = Array.isArray(packet?.layers) ? packet.layers : [];
+  return layers.map((layer) => {
+    if (layer.disposition === 'referenced') {
+      const content = typeof resolveSource === 'function' ? resolveSource(layer.sourceId, layer) : null;
+      return { id: layer.id, kind: layer.kind, content: typeof content === 'string' ? content : null, resolved: typeof content === 'string', sourceId: layer.sourceId };
+    }
+    if (layer.disposition === 'elided') {
+      return { id: layer.id, kind: layer.kind, content: null, elided: true, tokens: layer.tokens, sourceId: layer.sourceId };
+    }
+    return { id: layer.id, kind: layer.kind, content: layer.content ?? '' };
+  });
+}
+
+/**
+ * Read the continuation budget from a compiled execution policy
+ * (lib/models/execution-policy.mjs). Capability-profile driven, never a model-name
+ * fixed limit (construct-6zga.1.2 AC4).
+ */
+export function continuationBudgetFromPolicy(policy) {
+  const c = policy && typeof policy === 'object' ? policy.continuation : null;
+  return {
+    triggerTokens: Number.isFinite(c?.compactionTriggerTokens) ? c.compactionTriggerTokens : null,
+    triggerRatio: Number.isFinite(c?.compactionTriggerRatio) ? c.compactionTriggerRatio : null,
+  };
+}
+
+/**
+ * Hand-rolled validator (no ajv — Construct stays dependency-free at startup).
+ * Beyond shape, it enforces the no-silent-loss invariant: every required layer is
+ * retained unless the packet carries a blocker.
+ */
+export function validateContinuationPacket(packet) {
+  const errors = [];
+  if (!packet || typeof packet !== 'object') return { valid: false, errors: ['packet is not an object'] };
+  if (packet.schemaVersion !== CONTINUATION_PACKET_SCHEMA_VERSION) errors.push(`schemaVersion must be ${CONTINUATION_PACKET_SCHEMA_VERSION}`);
+
+  if (!Array.isArray(packet.layers)) errors.push('layers must be an array');
+  else {
+    for (const layer of packet.layers) {
+      if (!CONTEXT_LAYER_KINDS.includes(layer?.kind)) errors.push(`layer.kind invalid: ${layer?.kind}`);
+      if (!COMPACTION_ELIGIBILITY.includes(layer?.eligibility)) errors.push(`layer.eligibility invalid: ${layer?.eligibility}`);
+      if (!LAYER_DISPOSITIONS.includes(layer?.disposition)) errors.push(`layer.disposition invalid: ${layer?.disposition}`);
+    }
+  }
+
+  if (!Array.isArray(packet.requiredState)) errors.push('requiredState must be an array');
+  if (!packet.budget || typeof packet.budget !== 'object') errors.push('budget missing');
+  else if (!Number.isInteger(packet.budget.requiredTokens) || packet.budget.requiredTokens < 0) errors.push('budget.requiredTokens invalid');
+
+  const hasBlocker = packet.blocker && typeof packet.blocker === 'object';
+  if (Array.isArray(packet.layers) && !hasBlocker) {
+    const droppedRequired = packet.layers.find((l) => l?.eligibility === 'required' && l?.disposition !== 'retained');
+    if (droppedRequired) errors.push(`required layer not retained without a blocker: ${droppedRequired.id}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/lib/chat/continuation-source.mjs

@@ -0,0 +1,58 @@
+/**
+ * lib/chat/continuation-source.mjs — the one resolveSource every surface shares to
+ * rehydrate a continuation packet's reconstructible layers (construct-6zga.1.10).
+ *
+ * A continuation packet stores required state verbatim but references reconstructible
+ * layers (static instructions, role guidance, learned patterns) by source id, so
+ * rehydration must re-derive them rather than read stored content. One shared
+ * resolver across terminal, web, export, and resume guarantees every surface
+ * reconstructs identical context (AC3). Static-instructions and role-guidance
+ * families re-derive through the same composer a live turn runs
+ * (lib/chat/system-prompt.mjs); learned-patterns re-derive from the observation
+ * store, prefetched once because rehydration runs synchronously.
+ */
+
+import { buildSystemPrompt } from './system-prompt.mjs';
+
+function observationText(record) {
+  return [record?.summary, record?.content].filter(Boolean).join(' — ').trim();
+}
+
+export function createContinuationResolver({
+  systemText = null,
+  overlay = null,
+  capabilityTier = 'full',
+  cwd = process.cwd(),
+  learnedPatterns = null,
+} = {}) {
+  const composedSystem = typeof systemText === 'string' ? systemText : buildSystemPrompt({ overlay, capabilityTier });
+  const cache = new Map([['prompt:system', composedSystem]]);
+  if (typeof learnedPatterns === 'string') cache.set('learned-patterns', learnedPatterns);
+
+  function resolveSource(sourceId) {
+    if (sourceId == null) return null;
+    if (cache.has(sourceId)) return cache.get(sourceId);
+    if (sourceId.startsWith('prompt:') || sourceId.startsWith('role:')) return composedSystem;
+    if (sourceId === 'learned-patterns' || sourceId.startsWith('observation:')) return cache.get('learned-patterns') ?? null;
+    return null;
+  }
+
+  // Learned patterns live in the observation store and load asynchronously; a
+  // surface that wants them prefetches once, after which the synchronous
+  // resolveSource serves them from cache. A store miss leaves the layer null —
+  // rehydration reports it unresolved rather than inventing content.
+
+  async function loadLearnedPatterns(query, { limit = 5 } = {}) {
+    try {
+      const { searchObservations } = await import('../observation-store.mjs');
+      const results = await searchObservations(cwd, query, { limit });
+      const text = (results || []).map(observationText).filter(Boolean).map((line) => `- ${line}`).join('\n');
+      cache.set('learned-patterns', text);
+      return text;
+    } catch {
+      return cache.get('learned-patterns') ?? null;
+    }
+  }
+
+  return { resolveSource, loadLearnedPatterns, get systemText() { return composedSystem; } };
+}

package/lib/chat/demo-guide.mjs

@@ -0,0 +1,61 @@
+/**
+ * lib/chat/demo-guide.mjs — slash-command helpers for construct chat demo mode.
+ */
+
+export function formatDemoStepLine(step, colors = {}) {
+  const dim = colors.dim || '';
+  const reset = colors.reset || '';
+  const bold = colors.bold || '';
+  const lines = [`${bold}Step ${step.index}${reset}: ${step.title || 'prompt'}`];
+  if (step.prompt) lines.push(`${step.prompt}`);
+  if (step.command) lines.push(`${dim}command: ${step.command}${reset}`);
+  return lines.join('\n');
+}
+
+export function formatDemoStepsList(guide, colors = {}) {
+  const dim = colors.dim || '';
+  const reset = colors.reset || '';
+  const bold = colors.bold || '';
+  const lines = [`${bold}Demo steps${reset}`];
+  guide.script.steps.forEach((step, i) => {
+    lines.push(`  ${i + 1}. ${step.title || step.prompt?.slice(0, 50) || 'step'}`);
+  });
+  lines.push(`${dim}Use /demo next for the next prompt${reset}`);
+  return lines.join('\n');
+}
+
+export function registerDemoCommands(HELP, demoGuide) {
+  if (!demoGuide) return HELP;
+  return [
+    ...HELP.slice(0, 1),
+    ['/demo [next|steps|reset]', 'walk the active demo script'],
+    ...HELP.slice(1),
+  ];
+}
+
+export function handleDemoCommand(arg, { demoGuide, output, colors }) {
+  if (!demoGuide) {
+    output.write(`${colors.dim}No active demo. Launch with \`construct demo <name>\`.${colors.reset}\n`);
+    return;
+  }
+  const action = (arg || 'steps').toLowerCase();
+  if (action === 'reset') {
+    demoGuide.reset();
+    output.write(`${colors.green}Demo reset to step 1.${colors.reset}\n`);
+    return;
+  }
+  if (action === 'next') {
+    const step = demoGuide.next();
+    if (!step) {
+      output.write(`${colors.dim}Demo complete — all steps shown.${colors.reset}\n`);
+      return;
+    }
+    output.write(`\n${formatDemoStepLine(step, colors)}\n\n`);
+    return;
+  }
+  output.write(`${formatDemoStepsList(demoGuide, colors)}\n`);
+  const peek = demoGuide.peek();
+  if (peek) {
+    output.write(`${colors.dim}Next: /demo next → ${peek.title || 'step'}${colors.reset}\n`);
+  }
+}