comisai 1.0.44 → 1.0.46

package/node_modules/@comis/observability/dist/activity/plan-stream.js

@@ -1,5 +1,5 @@
 /**
- * Create the SEP plan-stream. NO new tool is registered (§16.7).
+ * Create the SEP plan-stream. NO new tool is registered.
  */
 export function createPlanStream(deps) {
     return {
@@ -8,7 +8,7 @@ export function createPlanStream(deps) {
             const emitFromPlan = (agentId, sessionKey) => {
                 const plan = deps.executionPlanPort.getCurrentPlan();
                 if (plan === undefined || !plan.active) {
-                    // SEP inactive for this turn — nothing to project (§16.7).
+                    // SEP inactive for this turn — nothing to project.
                     return;
                 }
                 const update = projectPlan(plan, agentId, sessionKey);
@@ -62,7 +62,7 @@ function projectPlan(plan, agentId, sessionKey) {
         index: step.index,
         description: step.description,
         status: step.status,
-        // completedBy undefined ⇒ no completions yet (§16.7); the authoritative
+        // completedBy undefined ⇒ no completions yet; the authoritative
         // "done" signal is the SEP-maintained status.
         completed: step.status === "done",
     }));

package/node_modules/@comis/observability/dist/activity/shell-label-parser.js

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * shell-label-parser — deterministic OpenClaw `summarizeKnownExec()` port
- * (spec §6.3 / §13.1).
+ * shell-label-parser — a deterministic summarizer for known shell exec commands.
  *
  * `bash`/`exec`/`shell` tool calls carry a free-form command string. This pure
  * parser turns it into a concise human label so the activity stream can render

package/node_modules/@comis/observability/dist/cache-trace/event-bus-bridge.js

@@ -115,7 +115,7 @@ function translateBridgedPayload(eventName, rawPayload, state) {
                 ...(payload.durationMs !== undefined ? { durationMs: payload.durationMs } : {}),
                 ...(payload.success !== undefined ? { success: payload.success } : {}),
                 ...(payload.errorKind !== undefined ? { errorKind: payload.errorKind } : {}),
-                // D1 provenance forwarding (Phase 152 flight-recorder reads it).
+                // Provenance forwarding — the flight-recorder reads these fields.
                 // matchedToken is already sanitized+bounded at the emit (pi-event-bridge),
                 // so every field is forwarded verbatim here.
                 ...(payload.classifiedFailureBy !== undefined ? { classifiedFailureBy: payload.classifiedFailureBy } : {}),

package/node_modules/@comis/observability/dist/cache-trace/stream-fn-wrapper.js

@@ -51,7 +51,7 @@ function sha256(s) {
  * survives in the count fields (`toolUseCount` / `toolResultCount` /
  * `pairedToolResultCount`) which are plain integers and cannot vanish under
  * the bound — so the pairing/orphan invariant the descriptor feeds holds at
- * ANY turn size, including large parallel-tool fan-outs. WR-01 (Phase 126).
+ * ANY turn size, including large parallel-tool fan-outs.
  */
 const MAX_SAMPLED_IDS = 32;
 function asString(v) {
@@ -109,7 +109,7 @@ function computeAssembledShape(messages, messageRoles) {
     }
     // Pairing/orphan signal computed over the FULL id sets BEFORE sampling, so
     // the count never depends on the sampled arrays surviving the 64-item cap.
-    // (WR-01: large fan-outs used to defeat the array-based pairing check.)
+    // (A large fan-out would otherwise defeat an array-based pairing check.)
     const toolUseIdSet = new Set(toolUseIds);
     const pairedToolResultCount = toolResultIds.reduce((n, rid) => (toolUseIdSet.has(rid) ? n + 1 : n), 0);
     return {
@@ -156,7 +156,7 @@ export function buildCacheTraceWrapper(trace) {
                 messagesDigest,
                 systemDigest,
             };
-            // O2: the SMALL assembled-array shape descriptor (counts/flags + tool
+            // The SMALL assembled-array shape descriptor (counts/flags + tool
             // id pairing). Emitted OUTSIDE the includeMessages guard so it is
             // present even when the full messages array is gated off — it is not a
             // body dump, so it survives the 32 KB sanitizeForPersistence bound.

package/node_modules/@comis/observability/dist/cache-trace/types.d.ts

@@ -10,14 +10,12 @@
  * tuple so consumers can enumerate it at test time and the Zod schema's
  * `stage` field rejects unknown stages at parse time.
  *
- * Comis improvements over the legacy 16-char-digest cache-trace-writer
- * (which lived in `packages/agent/src/executor/stream-wrappers`):
+ * Design properties of this schema:
  *   - `traceSchema: "comis-cache-trace"` + `schemaVersion: 1` — explicit
  *     parser fence; downstream replay/diff tooling can reject foreign
  *     artifacts.
  *   - Full 64-char `messagesDigest` + `systemDigest` via
- *     `stableStringify` (`shared/stable-stringify.ts`) instead of the
- *     legacy 16-char truncated SHA-256.
+ *     `stableStringify` (`shared/stable-stringify.ts`).
  *   - Per-stage events emitted at lifecycle boundaries — not a single
  *     point at the LLM call.
  *   - `cacheReadInputTokens` + `cacheCreationInputTokens` attached to
@@ -33,7 +31,7 @@ import { z } from "zod";
  *
  * Order: lifecycle-relevant (session.* → prompt → model → context → tool
  * → session.after → control-plane sentinel).
- * v1 shape established 2026-05-19; rewritten 2026-05-21 to match shipped code; append-only rule applies from 2026-05-21 forward.
+ * The stage tuple is append-only: new stages are added at the end; existing entries and their order never change.
  *
  * The trailing `cache_trace.write_failures` is a control-plane sentinel
  * (not an application stage) emitted by the runtime on first queued

package/node_modules/@comis/observability/dist/cache-trace/types.js

@@ -11,14 +11,12 @@
  * tuple so consumers can enumerate it at test time and the Zod schema's
  * `stage` field rejects unknown stages at parse time.
  *
- * Comis improvements over the legacy 16-char-digest cache-trace-writer
- * (which lived in `packages/agent/src/executor/stream-wrappers`):
+ * Design properties of this schema:
  *   - `traceSchema: "comis-cache-trace"` + `schemaVersion: 1` — explicit
  *     parser fence; downstream replay/diff tooling can reject foreign
  *     artifacts.
  *   - Full 64-char `messagesDigest` + `systemDigest` via
- *     `stableStringify` (`shared/stable-stringify.ts`) instead of the
- *     legacy 16-char truncated SHA-256.
+ *     `stableStringify` (`shared/stable-stringify.ts`).
  *   - Per-stage events emitted at lifecycle boundaries — not a single
  *     point at the LLM call.
  *   - `cacheReadInputTokens` + `cacheCreationInputTokens` attached to
@@ -34,7 +32,7 @@ import { z } from "zod";
  *
  * Order: lifecycle-relevant (session.* → prompt → model → context → tool
  * → session.after → control-plane sentinel).
- * v1 shape established 2026-05-19; rewritten 2026-05-21 to match shipped code; append-only rule applies from 2026-05-21 forward.
+ * The stage tuple is append-only: new stages are added at the end; existing entries and their order never change.
  *
  * The trailing `cache_trace.write_failures` is a control-plane sentinel
  * (not an application stage) emitted by the runtime on first queued
@@ -98,11 +96,11 @@ export const CacheTraceEventSchema = z.object({
     seq: z.number().int().nonnegative(),
     agentId: z.string(),
     sessionId: z.string(),
-    // §7.2 canonical correlation key — required. Auto-derived from the
+    // The canonical correlation key — required. Auto-derived from the
     // AsyncLocalStorage RequestContext when present, falling back to
     // sessionId.
     traceId: z.string(),
-    // §7.2 envelope fields — optional; the executor wires what's reachable.
+    // Envelope fields — optional; the executor wires what's reachable.
     runId: z.string().optional(),
     sessionKey: z.string().optional(),
     tenantId: z.string().optional(),
@@ -114,7 +112,7 @@ export const CacheTraceEventSchema = z.object({
     messages: z.array(z.unknown()).optional(),
     messageCount: z.number().int().nonnegative().optional(),
     messageRoles: z.array(z.string()).optional(),
-    // O2 (Phase 126): a SMALL assembled-array shape descriptor — per-message
+    // A SMALL assembled-array shape descriptor — per-message
     // block-kind counts + a `hasToolResult` flag + tool_use/tool_result
     // id-pairing summary. It lets a test assert tool_use<->tool_result pairing
     // + array growth WITHOUT shipping the full `messages` array, so it is
@@ -124,7 +122,7 @@ export const CacheTraceEventSchema = z.object({
     // to the exempt set). The permanent provider-boundary regression gate
     // asserts against this (see provider-boundary-harness.test.ts).
     //
-    // WR-01 (Phase 126): the `toolUseIds` / `toolResultIds` arrays are a SAMPLE
+    // The `toolUseIds` / `toolResultIds` arrays are a SAMPLE
     // (capped at MAX_SAMPLED_IDS, below the 64-item array bound) so the limiter
     // never replaces them with an opaque sentinel on large tool fan-outs. The
     // authoritative pairing/growth signal lives in the integer count fields

package/node_modules/@comis/observability/dist/config-audit/types.d.ts

@@ -20,13 +20,12 @@
  *
  * Both shapes match the record schemas verbatim:
  *
- *   - `event` is the discriminant ("config.write" | "config.observe"),
- *     NOT `phase` (renamed).
+ *   - `event` is the discriminant ("config.write" | "config.observe").
  *   - `source` is the fixed literal `"config-io"`.
- *     The prior four-value enum (last-known-good-save / restore /
- *     config-patch-rpc / cli-sync-tooling) is preserved verbatim in
- *     the new `callerSource: string` field so consumers (CLI audit
- *     show, downstream forensics) keep the call-site provenance.
+ *     The call-site provenance (last-known-good-save / restore /
+ *     config-patch-rpc / cli-sync-tooling) lives in the
+ *     `callerSource: string` field so consumers (CLI audit
+ *     show, downstream forensics) can read it.
  *   - Stat fields are FLAT (previousDev / previousIno / previousMode /
  *     previousNlink / previousUid / previousGid plus next* mirrors).
  *     `dev` and `ino` are `string | null` — POSIX

package/node_modules/@comis/observability/dist/config-audit/types.js

@@ -21,13 +21,12 @@
  *
  * Both shapes match the record schemas verbatim:
  *
- *   - `event` is the discriminant ("config.write" | "config.observe"),
- *     NOT `phase` (renamed).
+ *   - `event` is the discriminant ("config.write" | "config.observe").
  *   - `source` is the fixed literal `"config-io"`.
- *     The prior four-value enum (last-known-good-save / restore /
- *     config-patch-rpc / cli-sync-tooling) is preserved verbatim in
- *     the new `callerSource: string` field so consumers (CLI audit
- *     show, downstream forensics) keep the call-site provenance.
+ *     The call-site provenance (last-known-good-save / restore /
+ *     config-patch-rpc / cli-sync-tooling) lives in the
+ *     `callerSource: string` field so consumers (CLI audit
+ *     show, downstream forensics) can read it.
  *   - Stat fields are FLAT (previousDev / previousIno / previousMode /
  *     previousNlink / previousUid / previousGid plus next* mirrors).
  *     `dev` and `ino` are `string | null` — POSIX

package/node_modules/@comis/observability/dist/index.d.ts

@@ -5,6 +5,7 @@ export type { BoundedPayloadReason, BoundedSentinel, PayloadBoundsOverrides, } f
 export { sanitizeDiagnosticPayload, isCredentialFieldName, CREDENTIAL_KEYS, } from "./shared/sanitize-diagnostic-payload.js";
 export { resolveContainedPath, resolveContainedPathOrThrow, safeTrajectorySessionFileName, resolveSafeOpenFlags, PathEscapeError, } from "./shared/path-guards.js";
 export { safeJsonStringify } from "./shared/safe-json-stringify.js";
+export { stableStringify } from "./shared/stable-stringify.js";
 export { readFileSnapshot } from "./shared/file-snapshot.js";
 export type { FileSnapshot } from "./shared/file-snapshot.js";
 export { appendRegularFile, writeRegularFile, ensureContainedDir, SymlinkParentRejected, PathEscapesConfinementError, FileSizeLimitExceeded, } from "./shared/fs-safe.js";

package/node_modules/@comis/observability/dist/index.js

@@ -23,6 +23,11 @@ export { limitPayloadValue, PAYLOAD_BOUNDS, BOUNDED_PAYLOAD_REASONS, } from "./s
 export { sanitizeDiagnosticPayload, isCredentialFieldName, CREDENTIAL_KEYS, } from "./shared/sanitize-diagnostic-payload.js";
 export { resolveContainedPath, resolveContainedPathOrThrow, safeTrajectorySessionFileName, resolveSafeOpenFlags, PathEscapeError, } from "./shared/path-guards.js";
 export { safeJsonStringify } from "./shared/safe-json-stringify.js";
+// Canonical (digest-stable) JSON serializer — sorts object keys at every depth so
+// two semantically-equal inputs hash identically. Consumers that key a digest on a
+// structured value (e.g. the content-free orchestrate replay params-digest) use it
+// so both the recording and the matching side compute the same bytes.
+export { stableStringify } from "./shared/stable-stringify.js";
 // File-snapshot helper — sha256 + POSIX stat in one pass. Used by the
 // daemon's read-side audit producer (`readConfigFileObservation`) and
 // any other consumer that needs the file-state block.
@@ -181,28 +186,27 @@ export { SYNTHETIC_ERROR_KIND_MAP, TYPED_ERROR_KIND_EVENTS, resolveErrorKind, }
 // @comis/core (the boundary the guard test locks — observability never
 // imports @comis/channels).
 export { createActivityStream } from "./activity/activity-stream.js";
-// The pure, one-pass, idempotent activity-label display-shortener
-// (spec §8.4). Consumes already-redacted / already-path-compacted strings from
-// redactValue — it shortens URLs, ISO timestamps, and long mcp_ tool names
-// only, never re-redacting or re-compacting paths.
+// The pure, one-pass, idempotent activity-label display-shortener. Consumes
+// already-redacted / already-path-compacted strings from redactValue — it
+// shortens URLs, ISO timestamps, and long mcp_ tool names only, never
+// re-redacting or re-compacting paths.
 export { compressLabel } from "./activity/label-compressor.js";
-// Deterministic OpenClaw-style shell command summarizer (spec §6.3 /
-// §13.1). Pure, self-redacting (redactValue at shell-label-parser.ts:53),
-// length-capped at 120. Consumed by the exec/process builtin tools' transform
-// hook — the top-level barrel re-export keeps the import path
-// flat: `import { parseShellCommand } from "@comis/observability"`.
+// Deterministic shell command summarizer. Pure, self-redacting (redactValue at
+// shell-label-parser.ts:53), length-capped at 120. Consumed by the exec/process
+// builtin tools' transform hook — the top-level barrel re-export keeps the
+// import path flat: `import { parseShellCommand } from "@comis/observability"`.
 export { parseShellCommand } from "./activity/shell-label-parser.js";
 // SEP plan-stream — derives PlanUpdate events from sep:plan_extracted + the
-// live ExecutionPlanPort (spec §16.7). Consumed by the daemon
-// composition root (setup-channels-runtime.ts) to wire the
-// chat ActivityTurnCoordinator with a per-agent plan-state subscription.
+// live ExecutionPlanPort. Consumed by the daemon composition root
+// (setup-channels-runtime.ts) to wire the chat ActivityTurnCoordinator with a
+// per-agent plan-state subscription.
 export { createPlanStream } from "./activity/plan-stream.js";
 // ---------------------------------------------------------------------------
-// Pipeline-authoring gate surface (TELEM-02).
+// Pipeline-authoring gate surface.
 // ---------------------------------------------------------------------------
 //
-// The pre-committed, PURE, deterministic decision rule that gates Phase 174
-// (P2/AUTHOR): `pipelineAuthoringGate(aggregate) -> { buildAuthor, reason }`.
+// The pre-committed, PURE, deterministic decision rule:
+// `pipelineAuthoringGate(aggregate) -> { buildAuthor, reason }`.
 // This package is the SINGLE SOURCE of `PipelineAuthoringAggregate` — the
 // daemon's fleet-findings reducer imports the type from here, and the daemon's
 // fleet-health assembler surfaces the verdict on the FleetHealthReport. Pure

package/node_modules/@comis/observability/dist/pipeline-authoring-gate.d.ts

@@ -1,32 +1,31 @@
 /**
- * TELEM-02 — the pre-committed, PURE, deterministic pipeline-authoring decision
- * rule that gates Phase 174 (P2/AUTHOR).
+ * The pre-committed, PURE, deterministic pipeline-authoring decision rule.
  *
- * D-RULE: the RULE is the deliverable, not a live verdict. Given the small-vs-
- * frontier authoring aggregate (counts + rates), `pipelineAuthoringGate` returns
+ * The RULE is the deliverable, not a live verdict. Given the small-vs-frontier
+ * authoring aggregate (counts + rates), `pipelineAuthoringGate` returns
  * `{ buildAuthor, reason }` — it is PURE (no I/O, no clock, no globals; the
  * `test/architecture/globals.test.ts` gate enforces this repo-wide), so the same
- * aggregate reproduces the same verdict forever (the X3 determinism /
- * Repudiation control, T-173-09). It mirrors the ordered first-match-wins
+ * aggregate reproduces the same verdict forever (determinism makes the decision
+ * reproducible and non-repudiable). It mirrors the ordered first-match-wins
  * determinism of `fleetRootCause` / `likelyRootCause`.
  *
  * The pre-committed thresholds (committed BEFORE the data exists — the
  * measure-first discipline):
  *   - non-trivial sample  := smallTierInvocations >= {@link MIN_SMALL_TIER_SAMPLE} (20)
  *   - materially below    := (frontierValidRate - smallTierValidRate) >= {@link MATERIAL_GAP_PP} (15) percentage points
- * Build P2 ONLY when BOTH hold. No data / below either threshold -> defer.
+ * Build the author pipeline ONLY when BOTH hold. No data / below either
+ * threshold -> defer.
  *
- * In a build-from-scratch run there is no production telemetry, so the aggregate
- * is `{0,0,0}` and the rule returns `defer` — Phase 174 ships gated-off
- * regardless (invariant N4).
+ * With no production telemetry the aggregate is `{0,0,0}` and the rule returns
+ * `defer` — the author pipeline stays gated-off until real data justifies it.
  *
  * LEAF ISOLATION (`test/architecture/observability-package-isolation.test.ts`):
  * this file imports NOTHING — not the daemon, agent, cli, orchestrator, or
  * memory packages, not even core — it is a pure function over a plain counts
  * interface (no DiagnosticRow, no store).
  *
- * INFO-DISCLOSURE (T-173-10): the `reason` carries ONLY counts + the pp gap — no
- * agent ids, no body, no secret.
+ * INFO-DISCLOSURE: the `reason` carries ONLY counts + the pp gap — no agent ids,
+ * no body, no secret.
  *
  * @module
  */
@@ -35,10 +34,10 @@ export declare const MIN_SMALL_TIER_SAMPLE = 20;
 /** "Materially below frontier" — the committed validity gap, in percentage points. */
 export declare const MATERIAL_GAP_PP = 15;
 /**
- * The small-vs-frontier pipeline-authoring aggregate the gate consumes. The
- * CANONICAL home of this type (Plan 173-03's reducer in fleet-findings.ts
- * imports it from here — `@comis/observability` is the single source). Field
- * names + order are load-bearing (the reducer returns this exact shape):
+ * The small-vs-frontier pipeline-authoring aggregate the gate consumes. This is
+ * the CANONICAL home of this type — the reducer in fleet-findings.ts imports it
+ * from here, so `@comis/observability` is the single source. Field names + order
+ * are load-bearing (the reducer returns this exact shape):
  * `smallTierInvocations`, `smallTierValidRate`, `frontierValidRate`.
  */
 export interface PipelineAuthoringAggregate {

package/node_modules/@comis/observability/dist/pipeline-authoring-gate.js

@@ -1,33 +1,32 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * TELEM-02 — the pre-committed, PURE, deterministic pipeline-authoring decision
- * rule that gates Phase 174 (P2/AUTHOR).
+ * The pre-committed, PURE, deterministic pipeline-authoring decision rule.
  *
- * D-RULE: the RULE is the deliverable, not a live verdict. Given the small-vs-
- * frontier authoring aggregate (counts + rates), `pipelineAuthoringGate` returns
+ * The RULE is the deliverable, not a live verdict. Given the small-vs-frontier
+ * authoring aggregate (counts + rates), `pipelineAuthoringGate` returns
  * `{ buildAuthor, reason }` — it is PURE (no I/O, no clock, no globals; the
  * `test/architecture/globals.test.ts` gate enforces this repo-wide), so the same
- * aggregate reproduces the same verdict forever (the X3 determinism /
- * Repudiation control, T-173-09). It mirrors the ordered first-match-wins
+ * aggregate reproduces the same verdict forever (determinism makes the decision
+ * reproducible and non-repudiable). It mirrors the ordered first-match-wins
  * determinism of `fleetRootCause` / `likelyRootCause`.
  *
  * The pre-committed thresholds (committed BEFORE the data exists — the
  * measure-first discipline):
  *   - non-trivial sample  := smallTierInvocations >= {@link MIN_SMALL_TIER_SAMPLE} (20)
  *   - materially below    := (frontierValidRate - smallTierValidRate) >= {@link MATERIAL_GAP_PP} (15) percentage points
- * Build P2 ONLY when BOTH hold. No data / below either threshold -> defer.
+ * Build the author pipeline ONLY when BOTH hold. No data / below either
+ * threshold -> defer.
  *
- * In a build-from-scratch run there is no production telemetry, so the aggregate
- * is `{0,0,0}` and the rule returns `defer` — Phase 174 ships gated-off
- * regardless (invariant N4).
+ * With no production telemetry the aggregate is `{0,0,0}` and the rule returns
+ * `defer` — the author pipeline stays gated-off until real data justifies it.
  *
  * LEAF ISOLATION (`test/architecture/observability-package-isolation.test.ts`):
  * this file imports NOTHING — not the daemon, agent, cli, orchestrator, or
  * memory packages, not even core — it is a pure function over a plain counts
  * interface (no DiagnosticRow, no store).
  *
- * INFO-DISCLOSURE (T-173-10): the `reason` carries ONLY counts + the pp gap — no
- * agent ids, no body, no secret.
+ * INFO-DISCLOSURE: the `reason` carries ONLY counts + the pp gap — no agent ids,
+ * no body, no secret.
  *
  * @module
  */
@@ -48,14 +47,14 @@ export function pipelineAuthoringGate(agg) {
             reason: `defer: insufficient telemetry (${agg.smallTierInvocations} small-tier invocations < ${MIN_SMALL_TIER_SAMPLE})`,
         };
     }
-    // IN-01 (Phase 173 review): fail-safe on a non-finite rate. The sole
-    // production feeder (pipelineAuthoringAggregateFromRows) guards
-    // division-by-zero and can only ever produce finite 0..1 rates, so this is
-    // unreachable today — but the gate is an exported pure function on the
-    // package's public API, and `NaN < MATERIAL_GAP_PP` / `Infinity < ...` both
-    // evaluate false, which would otherwise fall through to a WRONG buildAuthor:
-    // true. A non-finite aggregate defers (fail-safe), never builds. Pure: no I/O,
-    // no clock, no globals — Number.isFinite is a stateless numeric predicate.
+    // Fail-safe on a non-finite rate. The sole production feeder
+    // (pipelineAuthoringAggregateFromRows) guards division-by-zero and can only
+    // ever produce finite 0..1 rates, so this is unreachable today — but the gate
+    // is an exported pure function on the package's public API, and
+    // `NaN < MATERIAL_GAP_PP` / `Infinity < ...` both evaluate false, which would
+    // otherwise fall through to a WRONG buildAuthor: true. A non-finite aggregate
+    // defers (fail-safe), never builds. Pure: no I/O, no clock, no globals —
+    // Number.isFinite is a stateless numeric predicate.
     if (!Number.isFinite(agg.smallTierValidRate) || !Number.isFinite(agg.frontierValidRate)) {
         return { buildAuthor: false, reason: "defer: non-finite validity rate (invalid aggregate)" };
     }

package/node_modules/@comis/observability/dist/recall-counters/registry.d.ts

@@ -4,7 +4,7 @@
  * A process-lifetime GAUGE that accumulates lane usage, rerank
  * runs/fallbacks, consolidation throughput, and recall hit-rate inputs.
  *
- * RESET-ON-RESTART SEMANTIC (Assumption A2): the counters live in plain
+ * RESET-ON-RESTART SEMANTIC: the counters live in plain
  * closed-over numeric accumulators with NO persistence. A process restart
  * resets every counter to zero — this is intentional. These are
  * health/metrics gauges (mirroring the in-process side of `comis cache

package/node_modules/@comis/observability/dist/recall-counters/registry.js

@@ -5,7 +5,7 @@
  * A process-lifetime GAUGE that accumulates lane usage, rerank
  * runs/fallbacks, consolidation throughput, and recall hit-rate inputs.
  *
- * RESET-ON-RESTART SEMANTIC (Assumption A2): the counters live in plain
+ * RESET-ON-RESTART SEMANTIC: the counters live in plain
  * closed-over numeric accumulators with NO persistence. A process restart
  * resets every counter to zero — this is intentional. These are
  * health/metrics gauges (mirroring the in-process side of `comis cache

package/node_modules/@comis/observability/dist/recall-counters/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * In-process recall counter registry types.
  *
- * The counter registry is a process-lifetime GAUGE (Assumption A2): it
+ * The counter registry is a process-lifetime GAUGE: it
  * accumulates lane usage, rerank runs/fallbacks, consolidation throughput,
  * and recall hit-rate inputs in plain numeric accumulators that RESET ON
  * RESTART. It is deliberately NOT a durable SQLite table (unlike the

package/node_modules/@comis/observability/dist/recall-counters/types.js

@@ -2,7 +2,7 @@
 /**
  * In-process recall counter registry types.
  *
- * The counter registry is a process-lifetime GAUGE (Assumption A2): it
+ * The counter registry is a process-lifetime GAUGE: it
  * accumulates lane usage, rerank runs/fallbacks, consolidation throughput,
  * and recall hit-rate inputs in plain numeric accumulators that RESET ON
  * RESTART. It is deliberately NOT a durable SQLite table (unlike the

package/node_modules/@comis/observability/dist/recall-trace/runtime.d.ts

@@ -5,7 +5,7 @@
  * `recordRecall`. A near-verbatim sibling of `createCacheTrace`
  * (`cache-trace/runtime.ts`), simplified to a single method:
  *
- *   - The recall trace is ONE rich record per recall (Assumption A1), not a
+ *   - The recall trace is ONE rich record per recall, not a
  *     per-stage stage machine — so there is no `stage` argument, no
  *     token-usage stash, and no `session:after` terminal-emit lifecycle.
  *   - Crucially, the recall trace has NO opt-in raw-content slot (unlike

package/node_modules/@comis/observability/dist/recall-trace/runtime.js

@@ -6,7 +6,7 @@
  * `recordRecall`. A near-verbatim sibling of `createCacheTrace`
  * (`cache-trace/runtime.ts`), simplified to a single method:
  *
- *   - The recall trace is ONE rich record per recall (Assumption A1), not a
+ *   - The recall trace is ONE rich record per recall, not a
  *     per-stage stage machine — so there is no `stage` argument, no
  *     token-usage stash, and no `session:after` terminal-emit lifecycle.
  *   - Crucially, the recall trace has NO opt-in raw-content slot (unlike

package/node_modules/@comis/observability/dist/recall-trace/types.d.ts

@@ -2,8 +2,8 @@
  * Recall-trace event v1 schema — ONE rich per-recall record + Zod envelope.
  *
  * Unlike the cache-trace (a per-session stream of per-STAGE events keyed by
- * a `stage` enum), the recall trace is a SINGLE rich record per recall
- * (Assumption A1): all of the recall pipeline's
+ * a `stage` enum), the recall trace is a SINGLE rich record per recall: all of
+ * the recall pipeline's
  * data — lanes fired + candidate counts, fused order, rerank scores
  * pre/post, and the final ranked set with per-memory score breakdowns +
  * include/exclude reasons — lives in ONE `recall()` call, so it is modeled
@@ -19,17 +19,17 @@
  *
  * Security shape: the record explains
  * recall WITHOUT echoing bodies. The query is a `queryDigest` (a fingerprint
- * — NEVER raw query text; supplied by the agent in Plan 03), per-memory data
- * is `id` + numeric `breakdown` (safe) + a closed-union `reason` (safe) + an
- * OPTIONAL short `preview` that the runtime routes through
- * `sanitizeForPersistence` before write. No absolute paths, no raw content.
+ * — NEVER raw query text), per-memory data is `id` + numeric `breakdown` (safe)
+ * + a closed-union `reason` (safe) + an OPTIONAL short `preview` that the runtime
+ * routes through `sanitizeForPersistence` before write. No absolute paths, no raw content.
  *
  * Closed-union invariant (AGENTS.md §2.8): `RECALL_RERANK_OUTCOMES` and
  * `RECALL_INCLUDE_REASONS` are literal `as const` tuples (mirror
  * `CACHE_TRACE_STAGES`) so consumers can enumerate them at test time and the
  * Zod `z.enum(...)` fences reject unknown values at parse time.
  *
- * v1 shape established 2026-05-30; append-only rule applies forward.
+ * v1 shape; the append-only rule applies forward — new fields are added optional
+ * so older trace lines still parse.
  *
  * @module
  */

package/node_modules/@comis/observability/dist/recall-trace/types.js

@@ -3,8 +3,8 @@
  * Recall-trace event v1 schema — ONE rich per-recall record + Zod envelope.
  *
  * Unlike the cache-trace (a per-session stream of per-STAGE events keyed by
- * a `stage` enum), the recall trace is a SINGLE rich record per recall
- * (Assumption A1): all of the recall pipeline's
+ * a `stage` enum), the recall trace is a SINGLE rich record per recall: all of
+ * the recall pipeline's
  * data — lanes fired + candidate counts, fused order, rerank scores
  * pre/post, and the final ranked set with per-memory score breakdowns +
  * include/exclude reasons — lives in ONE `recall()` call, so it is modeled
@@ -20,17 +20,17 @@
  *
  * Security shape: the record explains
  * recall WITHOUT echoing bodies. The query is a `queryDigest` (a fingerprint
- * — NEVER raw query text; supplied by the agent in Plan 03), per-memory data
- * is `id` + numeric `breakdown` (safe) + a closed-union `reason` (safe) + an
- * OPTIONAL short `preview` that the runtime routes through
- * `sanitizeForPersistence` before write. No absolute paths, no raw content.
+ * — NEVER raw query text), per-memory data is `id` + numeric `breakdown` (safe)
+ * + a closed-union `reason` (safe) + an OPTIONAL short `preview` that the runtime
+ * routes through `sanitizeForPersistence` before write. No absolute paths, no raw content.
  *
  * Closed-union invariant (AGENTS.md §2.8): `RECALL_RERANK_OUTCOMES` and
  * `RECALL_INCLUDE_REASONS` are literal `as const` tuples (mirror
  * `CACHE_TRACE_STAGES`) so consumers can enumerate them at test time and the
  * Zod `z.enum(...)` fences reject unknown values at parse time.
  *
- * v1 shape established 2026-05-30; append-only rule applies forward.
+ * v1 shape; the append-only rule applies forward — new fields are added optional
+ * so older trace lines still parse.
  *
  * @module
  */
@@ -76,8 +76,8 @@ export const RECALL_DEGRADATION_KINDS = [
  * `usefulness` factor is the read-side payoff of the recall-utility
  * feedback loop (1.0 when the per-memory usefulness signal is absent).
  *
- * `usefulnessOutcomeShare` (OBS-02, Verified Learning WS3) is an OPTIONAL annotation —
- * the OUTCOME-attributed usefulness CONTRIBUTION (the signed deviation of the `usefulness`
+ * `usefulnessOutcomeShare` is an OPTIONAL annotation — the OUTCOME-attributed
+ * usefulness CONTRIBUTION (the signed deviation of the `usefulness`
  * factor from its 1.0 neutral), surfaced so `comis explain` shows how much of a memory's
  * rank came from learned recall-utility / outcome feedback, distinct from the lexical `base`.
  * It is NOT a multiplicand (absent from `final`). Optional so older trace lines (and the
@@ -91,7 +91,7 @@ const RecallScoreBreakdownSchema = z.object({
     proof: z.number(),
     trust: z.number(),
     usefulness: z.number(),
-    /** OBS-02 outcome-attributed usefulness contribution (annotation, NOT a multiplicand);
+    /** Outcome-attributed usefulness contribution (annotation, NOT a multiplicand);
      *  optional so older trace lines parse. Signed: + boosts, - demotes, 0 when absent. */
     usefulnessOutcomeShare: z.number().optional(),
     /** FadeMem decay factor surfaced from score.ts; optional (appended after the original
@@ -102,9 +102,8 @@ const RecallScoreBreakdownSchema = z.object({
 /**
  * One entry in the final ranked set. `id` + `reason` are mandatory; the
  * numeric `breakdown` is optional (present for included memories); `preview`
- * is an OPTIONAL short sanitized string (Plan 03 decides id-only vs preview
- * — the redaction proof in runtime.test.ts is authoritative: any preview
- * goes through `sanitizeForPersistence`).
+ * is an OPTIONAL short sanitized string — the redaction proof in runtime.test.ts
+ * is authoritative: any preview goes through `sanitizeForPersistence`.
  */
 const RecallRankedEntrySchema = z.object({
     id: z.string(),
@@ -137,10 +136,10 @@ export const RecallTraceEventSchema = z.object({
     seq: z.number().int().nonnegative(),
     agentId: z.string(),
     sessionId: z.string(),
-    // §7.2 canonical correlation key — required. Auto-derived from the
+    // Canonical correlation key — required. Auto-derived from the
     // AsyncLocalStorage RequestContext when present, falling back to sessionId.
     traceId: z.string(),
-    // §7.2 envelope cluster — optional; the agent wires what's reachable.
+    // Envelope cluster — optional; the agent wires what's reachable.
     sessionKey: z.string().optional(),
     tenantId: z.string().optional(),
     runId: z.string().optional(),

package/node_modules/@comis/observability/dist/redact/regex-bounded.d.ts

@@ -18,7 +18,7 @@
  * anchored on a fixed-byte-length prefix (`sk-`, `ghp_`, `Authorization:`,
  * etc.) or have explicit word boundaries — the chunk size is far larger
  * than any conceivable credential, so cross-chunk straddle is not a
- * practical concern. This is the design-§5 trade documented in the plan.
+ * practical concern.
  *
  * Single-pass below the threshold (≤ 32 768 chars) so the small-input
  * fast path stays a single `replace` call.

package/node_modules/@comis/observability/dist/redact/regex-bounded.js

@@ -19,7 +19,7 @@
  * anchored on a fixed-byte-length prefix (`sk-`, `ghp_`, `Authorization:`,
  * etc.) or have explicit word boundaries — the chunk size is far larger
  * than any conceivable credential, so cross-chunk straddle is not a
- * practical concern. This is the design-§5 trade documented in the plan.
+ * practical concern.
  *
  * Single-pass below the threshold (≤ 32 768 chars) so the small-input
  * fast path stays a single `replace` call.