@crewhaus/ir 0.2.4 → 0.3.0

package/dist/index.d.ts

@@ -19,17 +19,24 @@ export type IrPermissions = {
  * MCP server configs carried through to codegen (Section 9). Lower-time
  * normalisation: optional spec fields become required IR fields with
  * empty defaults, so target codegen doesn't need `?? []` guards.
+ *
+ * 0.3.0 (breaking, pre-1.0): stdio `env` and sse `headers` VALUES are
+ * `IrSecretRef`, not plain strings — `$UPPER_SNAKE` spec values lower to
+ * `{ kind: "env" }` references exactly like every other credential field,
+ * so secrets never land in compiled artifacts. Target codegen embeds the
+ * unresolved config verbatim and the emitted bundle resolves it at process
+ * start via `resolveMcpServerConfig` from `@crewhaus/mcp-host`.
  */
 export type IrMcpStdioConfig = {
     readonly transport: "stdio";
     readonly command: string;
     readonly args: readonly string[];
-    readonly env?: Readonly<Record<string, string>>;
+    readonly env?: Readonly<Record<string, IrSecretRef>>;
 };
 export type IrMcpSseConfig = {
     readonly transport: "sse";
     readonly url: string;
-    readonly headers?: Readonly<Record<string, string>>;
+    readonly headers?: Readonly<Record<string, IrSecretRef>>;
 };
 export type IrMcpServerConfig = IrMcpStdioConfig | IrMcpSseConfig;
 export type IrMcpServers = Readonly<Record<string, IrMcpServerConfig>>;
@@ -259,20 +266,180 @@ export type IrFeedback = {
     readonly exitPrompt?: boolean;
     readonly channelReactions?: boolean;
 };
+/**
+ * v0.3.0 §3.1/§9 — the wiki (semantic tier) config, lowered from
+ * `spec.memory.wiki`. Presence (with `enabled` not `false`) registers the
+ * thredz-vocabulary `wiki_*` tools over `@crewhaus/wiki-store`. Every field
+ * is carried only when the spec declared it (absent-when-omitted).
+ */
+export type IrMemoryWiki = {
+    readonly enabled?: boolean;
+    /** Wiki hits fused into auto-recall (1–50). */
+    readonly recallK?: number;
+    /** `@crewhaus/embedder` factory grammar — enables hybrid recall on both
+     *  the wiki and the fact store. */
+    readonly embedder?: string;
+    /** Fuse wiki recall into the session-start memory bundle. */
+    readonly autoRecall?: boolean;
+    /** Learning-mode write governance: `wiki_write` rejects bodies without a
+     *  `## Sources` heading. */
+    readonly requireSources?: boolean;
+};
+/**
+ * v0.3.0 Goal 5 (§6/§9) — scheduled memory consolidation, lowered from
+ * `spec.memory.dream`. `every` is parsed to `everyMs` at lower time
+ * (>= 5m enforced there); `mode` is RESOLVED at lower time (default
+ * `"full"`) so emitters and the interpreter read one deterministic shape.
+ * `budgetUsd`/`instructions` are carried only when declared — the model
+ * phase runs only when `mode` is `"full"` AND `budgetUsd > 0`.
+ */
+export type IrMemoryDream = {
+    /** Consolidation cadence in milliseconds (`spec.memory.dream.every`). */
+    readonly everyMs: number;
+    /** `deterministic` (no model, ever) | `full` (bounded model synthesis). */
+    readonly mode: "deterministic" | "full";
+    /** Item-27 spend cap for the model phase (USD). Absent or 0 =
+     *  deterministic only. */
+    readonly budgetUsd?: number;
+    /** Playbook override; default = the builtin `dream` skill body. */
+    readonly instructions?: string;
+};
 /**
  * Feature #53 — cross-session memory config, lowered from `spec.memory`.
  * Presence of the block wires Remember/Recall into the target; the auto-*
  * switches gate auto-capture (summarize durable outcomes at teardown) and
  * auto-recall (inject top-K memories into the system prompt at session start).
- * Carried on the interactive shapes that run a chat loop (IrV0/cli,
- * IrChannelV0, IrManagedV0, IrResearchV0). Absent when the spec omits `memory`.
+ * Carried on the agent-loop shapes (IrV0/cli, IrChannelV0, IrManagedV0,
+ * IrResearchV0, IrCrewV0). Absent when the spec omits `memory`.
+ *
+ * v0.3.0 (§9) extensions, all absent-when-omitted: `backend` (`file` |
+ * reserved `thredz`), `ttlMs` (explicit fact forgetting — `spec.memory.ttl`
+ * parsed to milliseconds at lower time, >= 1h enforced there), `wiki`
+ * (see {@link IrMemoryWiki}), and `dream` (see {@link IrMemoryDream}).
  */
 export type IrMemory = {
     readonly enabled?: boolean;
+    readonly backend?: "file" | "thredz";
+    readonly ttlMs?: number;
     readonly autoCapture?: boolean;
     readonly autoCaptureThreshold?: number;
     readonly autoRecall?: boolean;
     readonly recallK?: number;
+    readonly wiki?: IrMemoryWiki;
+    readonly dream?: IrMemoryDream;
+};
+/** v0.3.0 §2.7 — the RESOLVED continuity scope. `auto` is a compiler
+ *  concern: `lower()` resolves it per shape (cli/research/crew/managed →
+ *  `spec`, channel → `session`), so the IR never carries `auto`. */
+export type IrContinuityScope = "spec" | "session";
+/**
+ * v0.3.0 Goal 1 (§2.1/§9) — continuity config, lowered from the top-level
+ * `continuity:` block. THE release's one sanctioned default-on: on the five
+ * emit-wired agent-loop shapes (IrV0/cli, IrChannelV0, IrManagedV0,
+ * IrResearchV0, IrCrewV0) an ABSENT spec key lowers to the default-on config
+ * below, and only `continuity: false` (or `enabled: false`) removes this
+ * field — presence means enabled. Also carried, when the spec declares it,
+ * on IrWorkflowV0/IrBatchV0/IrVoiceV0/IrBrowserV0, whose emitters print the
+ * 0.2.3-convention ignored-note comment instead of wiring it.
+ *
+ * All fields except `focusMaxChars` are RESOLVED at lower time (defaults
+ * filled in: plan/ledger/handoff true, proof "ladder", scope per §2.7), so
+ * emitters and the interpreter read one deterministic shape.
+ */
+export type IrContinuity = {
+    /** Plan/goal persistence + the Plan and Goal tool families; `false`
+     *  keeps only FocusRead/FocusWrite + MemoryClear. */
+    readonly plan: boolean;
+    /** §2.4 proof-of-action: `ladder` (default) | `require` | `off`. */
+    readonly proof: "ladder" | "require" | "off";
+    /** §2.3 verbatim requirements ledger (context_evicted externalization). */
+    readonly ledger: boolean;
+    /** §2.8 deterministic teardown handoff.md. */
+    readonly handoff: boolean;
+    /** Resolved store scope (§2.7/§14.5). */
+    readonly scope: IrContinuityScope;
+    /** Hard cap on the mutable tail block. Absent → runtime default (4096). */
+    readonly focusMaxChars?: number;
+};
+/**
+ * v0.3.0 Goal 3 (§4.1/§9) — the Thredz config, lowered from the top-level
+ * `thredz:` block (boolean/string shorthand or the object form — the spec
+ * shorthands are RESOLVED at lower time so this carries one deterministic
+ * shape). Presence means Thredz is on.
+ *
+ * The compiler additionally SYNTHESIZES an `mcp_servers.thredz` stdio entry
+ * (`npx -y thredz-mcp@0.2.0` with `THREDZ_API_KEY` as an `IrSecretRef` env
+ * value, riding the §4.2 secret machinery end-to-end) on the emit-wired
+ * shape (cli). A user-declared `mcp_servers.thredz` wins over synthesis
+ * (explicit beats implicit — `crewhaus lint` warns); this config block is
+ * carried either way so the wiring layer (memory-service) still routes the
+ * wiki backend and goal mirror through that server.
+ */
+export type IrThredzVisibility = "private" | "shared";
+export type IrThredz = {
+    /** The Thredz API key — credential-lowered (`$THREDZ_API_KEY` →
+     *  `{ kind: "env" }`; fail-fast on a malformed `$…` ref). */
+    readonly apiKey: IrSecretRef;
+    /** Self-hosted / local API base (`THREDZ_API_BASE`). Absent → the hosted
+     *  default inside thredz-mcp. */
+    readonly baseUrl?: string;
+    /** RESOLVED default `private` — becomes `THREDZ_DEFAULT_VISIBILITY`, so
+     *  agent memory is never public by accident (Thredz's own API defaults
+     *  new articles to globally-shared). */
+    readonly visibility: IrThredzVisibility;
+    /** RESOLVED — mirror continuity goal writes to Thredz `goal_write`/
+     *  `goal_update` (spec-scoped only, §14.5 decision 5). Defaulted at lower
+     *  time to "on when continuity goals are on". */
+    readonly goals: boolean;
+    /** Register this addressable agent handle at boot (idempotent
+     *  `agent_register`). Absent → no registration (the default). */
+    readonly agentName?: string;
+};
+/** v0.3.0 Goal 2 (§3.3, PR 17) — the first-class competency exam: dataset +
+ *  graders paths, spec-relative. Whether the files EXIST is a runtime
+ *  concern (the `run_exam` tool fails with a clear error); the compiler
+ *  validates shape only. */
+export type IrLearningExam = {
+    /** Spec-relative path to the exam dataset (jsonl). */
+    readonly dataset: string;
+    /** Spec-relative path to the graders config (yaml). */
+    readonly graders: string;
+};
+/** v0.3.0 Goal 2 (§3.3, PR 17) — unattended-study toggles, RESOLVED at lower
+ *  time (both default true) so downstream reads one deterministic shape. */
+export type IrLearningStudy = {
+    /** Prepend the study-rotation preamble (gaps first, ~3:1 study:reflect,
+     *  bounded per tick) to channel heartbeat instructions. */
+    readonly onHeartbeat: boolean;
+    /** Seed the dream model phase's findings with the top open knowledge gaps
+     *  + the next unmastered curriculum rung. */
+    readonly onDream: boolean;
+};
+/**
+ * v0.3.0 Goal 2 (§3.3, PR 17) — continual-learning config, lowered from the
+ * top-level `learning:` block. Presence means learning is ON (the compiler
+ * dropped `enabled: false` at lower time). Learning REQUIRES a wiki —
+ * `lower()` rejects the block without `memory.wiki` (local) or `thredz:`
+ * (hosted) — and deterministically stamps `memory.wiki.requireSources: true`
+ * (Sources-required write governance, what was prompt-only in the expert
+ * demo).
+ *
+ * `domain`/`curriculum`/`sources` are substituted into the builtin
+ * `learning-loop` skill body at wire time; `exam` drives the programmatic
+ * `run_exam` tool; `study` carries the resolved unattended-study toggles.
+ * Carried on the five memory shapes (IrV0/cli, IrChannelV0, IrManagedV0,
+ * IrResearchV0, IrCrewV0).
+ */
+export type IrLearning = {
+    /** One sentence naming the field of expertise. */
+    readonly domain: string;
+    /** Spec-relative path to the agent-editable curriculum ladder. Absent →
+     *  the skill keeps the ladder in the wiki. */
+    readonly curriculum?: string;
+    /** Source-allowlist hints. NOT optimizable — allowlist = security (§7.5). */
+    readonly sources?: readonly string[];
+    readonly exam?: IrLearningExam;
+    readonly study: IrLearningStudy;
 };
 /** Ops item 37 — a mitigation-ladder rung the runtime SLO monitor walks on a
  *  sustained breach, in declared order. See {@link IrSlo}. */
@@ -388,6 +555,15 @@ export type IrV0 = {
     readonly feedback?: IrFeedback;
     /** #53 cross-session memory config. Optional; absent when the spec omits `memory`. */
     readonly memory?: IrMemory;
+    /** v0.3.0 Goal 1 — continuity config. DEFAULT-ON: present unless the spec
+     *  opted out with `continuity: false`. */
+    readonly continuity?: IrContinuity;
+    /** v0.3.0 Goal 3 — Thredz config. Present when the spec declares `thredz:`;
+     *  the compiler also synthesizes `mcp_servers.thredz` on this shape. */
+    readonly thredz?: IrThredz;
+    /** v0.3.0 Goal 2 — continual-learning config (§3.3, PR 17). Present
+     *  when the spec declares an enabled `learning:` block. */
+    readonly learning?: IrLearning;
     /** Ops item 37 — SLO targets + mitigation ladder. Optional; absent when the
      *  spec omits the `observability` block. */
     readonly observability?: IrObservability;
@@ -428,6 +604,9 @@ export type IrWorkflowV0 = {
     readonly compaction: IrCompaction;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** v0.3.0 — carried when the spec declares `continuity:` (NOT default-on
+     *  here); target-workflow prints the ignored-note comment. */
+    readonly continuity?: IrContinuity;
 };
 /**
  * A secret value referenced by a channel config (Section 12). Lower-time
@@ -650,6 +829,16 @@ export type IrChannelV0 = {
     readonly feedback?: IrFeedback;
     /** #53 cross-session memory config. Optional; absent when the spec omits `memory`. */
     readonly memory?: IrMemory;
+    /** v0.3.0 Goal 1 — continuity config. DEFAULT-ON: present unless the spec
+     *  opted out with `continuity: false`. `scope` resolves to `session` here
+     *  (per-conversation stores riding the session router's sessionId, §14.5). */
+    readonly continuity?: IrContinuity;
+    /** v0.3.0 Goal 3 — Thredz config, CARRIED but not emit-wired on this shape
+     *  in this release (the emitter prints the ignored-note comment). */
+    readonly thredz?: IrThredz;
+    /** v0.3.0 Goal 2 — continual-learning config (§3.3, PR 17). Present
+     *  when the spec declares an enabled `learning:` block. */
+    readonly learning?: IrLearning;
     /** Ops item 37 — SLO targets + mitigation ladder. Optional; absent when the
      *  spec omits the `observability` block. */
     readonly observability?: IrObservability;
@@ -697,6 +886,16 @@ export type IrManagedV0 = {
     readonly budget?: IrBudget;
     /** #53 cross-session memory config. Optional; absent when the spec omits `memory`. */
     readonly memory?: IrMemory;
+    /** v0.3.0 Goal 1 — continuity config. DEFAULT-ON: present unless the spec
+     *  opted out with `continuity: false`. `scope` resolves to `spec` here;
+     *  every store is tenant-fenced at boot (deps carry the tenant, §2.7). */
+    readonly continuity?: IrContinuity;
+    /** v0.3.0 Goal 3 — Thredz config, CARRIED but not emit-wired on this shape
+     *  in this release (the emitter prints the ignored-note comment). */
+    readonly thredz?: IrThredz;
+    /** v0.3.0 Goal 2 — continual-learning config (§3.3, PR 17). Present
+     *  when the spec declares an enabled `learning:` block. */
+    readonly learning?: IrLearning;
     /** Ops item 37 — SLO targets + mitigation ladder. Optional; absent when the
      *  spec omits the `observability` block. The managed daemon's `pause-intake`
      *  rung reuses its `budget_exceeded` 429 path. */
@@ -849,6 +1048,19 @@ export type IrCrewV0 = {
     readonly compaction: IrCompaction;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** #53/v0.3.0 — cross-session memory config (crew joins the carrying
+     *  shapes in 0.3.0; roles share the spec-scoped store). Optional. */
+    readonly memory?: IrMemory;
+    /** v0.3.0 Goal 1 — continuity config. DEFAULT-ON: present unless the spec
+     *  opted out with `continuity: false`. Roles share the `spec`-scoped plan
+     *  store — the plan IS the coordination surface (§2.7). */
+    readonly continuity?: IrContinuity;
+    /** v0.3.0 Goal 3 — Thredz config, CARRIED but not emit-wired on this shape
+     *  in this release (the emitter prints the ignored-note comment). */
+    readonly thredz?: IrThredz;
+    /** v0.3.0 Goal 2 — continual-learning config (§3.3, PR 17). Present
+     *  when the spec declares an enabled `learning:` block. */
+    readonly learning?: IrLearning;
     /** §47 cross-cutting blockchain subsystem (slice 0). All optional. */
     readonly chains?: readonly IrChainBinding[];
     readonly wallets?: readonly IrWalletBinding[];
@@ -896,6 +1108,15 @@ export type IrResearchV0 = {
     readonly failureTaxonomy?: IrFailureTaxonomy;
     /** #53 cross-session memory config. Optional; absent when the spec omits `memory`. */
     readonly memory?: IrMemory;
+    /** v0.3.0 Goal 1 — continuity config. DEFAULT-ON: present unless the spec
+     *  opted out with `continuity: false`. `scope` resolves to `spec` here. */
+    readonly continuity?: IrContinuity;
+    /** v0.3.0 Goal 3 — Thredz config, CARRIED but not emit-wired on this shape
+     *  in this release (the emitter prints the ignored-note comment). */
+    readonly thredz?: IrThredz;
+    /** v0.3.0 Goal 2 — continual-learning config (§3.3, PR 17). Present
+     *  when the spec declares an enabled `learning:` block. */
+    readonly learning?: IrLearning;
     /** §47 cross-cutting blockchain subsystem (slice 0). All optional. */
     readonly chains?: readonly IrChainBinding[];
     readonly wallets?: readonly IrWalletBinding[];
@@ -940,6 +1161,9 @@ export type IrBatchV0 = {
     readonly compaction: IrCompaction;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** v0.3.0 — carried when the spec declares `continuity:` (NOT default-on
+     *  here); target-batch-worker prints the ignored-note comment. */
+    readonly continuity?: IrContinuity;
     /** §47 cross-cutting blockchain subsystem (slice 0). All optional. */
     readonly chains?: readonly IrChainBinding[];
     readonly wallets?: readonly IrWalletBinding[];
@@ -984,6 +1208,9 @@ export type IrVoiceV0 = {
     readonly compaction: IrCompaction;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** v0.3.0 — carried when the spec declares `continuity:` (NOT default-on
+     *  here); target-voice prints the ignored-note comment. */
+    readonly continuity?: IrContinuity;
 };
 /**
  * Section 25 — BROW (computer-use / browser driver) IR. The compiled
@@ -1020,6 +1247,9 @@ export type IrBrowserV0 = {
     readonly compaction: IrCompaction;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** v0.3.0 — carried when the spec declares `continuity:` (NOT default-on
+     *  here); target-browser-driver prints the ignored-note comment. */
+    readonly continuity?: IrContinuity;
 };
 /** Discriminated union over every supported target IR. */
 /**

package/dist/readme.js

@@ -6,13 +6,25 @@ import { OPAQUE_TOKEN_RE, maskCredentialTokens } from "./redact";
  * (kept, with a notice).
  */
 export const GENERATED_README_MARKER = "<!-- crewhaus:generated-readme -->";
+/**
+ * Literal refs under these keys are COMPILER-SYNTHESIZED configuration
+ * knobs (v0.3.0 `thredz:` lowering — visibility enforcement + self-hosted
+ * base URL), not user-supplied secrets: counting them would print the
+ * "supplied as literals in the spec" warning on every one-knob
+ * `thredz: true` spec whose author supplied nothing literal at all. Scoped
+ * to exactly these names so every user-declared literal keeps warning.
+ */
+const SYNTHESIZED_LITERAL_KEYS = new Set([
+    "THREDZ_DEFAULT_VISIBILITY",
+    "THREDZ_API_BASE",
+]);
 export function collectSecretRefs(ir) {
     const envNames = new Set();
     let literalCount = 0;
-    const visit = (node) => {
+    const visit = (node, parentKey) => {
         if (Array.isArray(node)) {
             for (const item of node)
-                visit(item);
+                visit(item, parentKey);
             return;
         }
         if (node === null || typeof node !== "object")
@@ -25,10 +37,12 @@ export function collectSecretRefs(ir) {
             envNames.add(record["name"]);
         }
         else if (record["kind"] === "literal" && typeof record["value"] === "string") {
-            literalCount += 1;
+            if (parentKey === undefined || !SYNTHESIZED_LITERAL_KEYS.has(parentKey)) {
+                literalCount += 1;
+            }
         }
-        for (const value of Object.values(record))
-            visit(value);
+        for (const [key, value] of Object.entries(record))
+            visit(value, key);
     };
     visit(ir);
     return { envNames: [...envNames].sort(), literalCount };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/ir",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "type": "module",
   "description": "Canonical typed intermediate representation",
   "main": "dist/index.js",