@remnic/core 9.69.55 → 9.69.57

package/dist/coding/coding-knowledge-config.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Track A (issue #1548 PR 1) — parse the `codingKnowledge` config block.
+ *
+ * Lives in `coding/` (not in `config.ts`) so adding a feature config block
+ * does not grow the watchlisted `config.ts` past its ratchet baseline. The
+ * function is a pure helper: it reads from the raw `cfg.codingKnowledge`
+ * sub-object, applies defaults from `CODING_KNOWLEDGE_DEFAULTS`, validates
+ * the structural-provider enum, and returns the populated
+ * `CodingKnowledgeConfig`.
+ *
+ * Parse rules (CLAUDE.md gotcha 36, rule 30, rule 48):
+ *  - booleans are coerced at the parse boundary so CLI strings like
+ *    `--config codingKnowledge.enabled=false` arrive as `false`, not truthy.
+ *  - unknown structural-provider values are rejected listing the valid
+ *    options (rule 51 — silent defaulting is a contract lie).
+ *  - `structuralProvider` defaults to `"none"` (rule 48 — least-privileged:
+ *    spawning subprocesses is an explicit operator choice).
+ *
+ * Env overrides follow the REMNIC_* + ENGRAM_* fallback already used elsewhere
+ * in `config.ts` (#1427 family). Each individual switch is `codingKnowledge.*` —
+ * the existing `ENGRAM_*` env vars from earlier releases do not pair them up.
+ */
+import type { CodingContext, CodingKnowledgeConfig } from "../types.js";
+export declare const CODING_KNOWLEDGE_DEFAULTS: Readonly<{
+    enabled: false;
+    decisionRecords: true;
+    architectureCard: true;
+    sessionDelta: true;
+    architectureCardLlmSummary: false;
+    structuralProvider: string;
+    structuralProviderCommand: string;
+    codegraphTools: false;
+    codegraphDbDir: string;
+}>;
+/**
+ * Parse the `codingKnowledge` sub-object into a fully-populated
+ * `CodingKnowledgeConfig`. Returns the documented defaults when the
+ * sub-object is missing, null, not an object, or has unknown shape.
+ *
+ * Throws when an explicit `structuralProvider` value is not one of the
+ * declared enum values (rule 51 — listing valid options in the error).
+ */
+export declare function parseCodingKnowledgeConfig(raw: unknown): CodingKnowledgeConfig;
+/** Boolean feature switches governed by the master `codingKnowledge.enabled` gate. */
+export type CodingKnowledgeFeatureFlag = "decisionRecords" | "architectureCard" | "sessionDelta";
+/**
+ * Config-only visibility gate — used by the MCP constructor to decide
+ * whether a coding tool is advertised in `tools/list`. True only when the
+ * master gate AND the feature switch are both on.
+ */
+export declare function isCodingKnowledgeFeatureVisible(config: CodingKnowledgeConfig, feature: CodingKnowledgeFeatureFlag): boolean;
+/**
+ * Full call-time gate: visibility PLUS an attached coding context
+ * (project/branch-scoped session). Handlers check this before dispatch.
+ */
+export declare function isCodingKnowledgeFeatureEnabled(config: CodingKnowledgeConfig, feature: CodingKnowledgeFeatureFlag, codingContext: CodingContext | null | undefined): boolean;
+/**
+ * Strict boolean parse for feature-gate config values.
+ *  - `undefined` falls back to `defaultValue` (the key was simply not
+ *    supplied).
+ *  - `true`/`false` (native) and the boolean-like strings listed in
+ *    `STRICT_BOOL_ACCEPTED` are honored (rule 36 — CLI string parity).
+ *  - Any other shape, including misspelled strings like `"flase"`,
+ *    numbers outside `{0, 1}`, objects, arrays — is REJECTED with an
+ *    error listing the valid inputs (rule 51). Silent defaulting on
+ *    malformed operator input is a contract lie.
+ */
+export declare function readStrictBool(value: unknown, keyName: string, defaultValue: boolean): boolean;
+//# sourceMappingURL=coding-knowledge-config.d.ts.map

package/dist/coding/coding-knowledge-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-knowledge-config.d.ts","sourceRoot":"","sources":["../../src/coding/coding-knowledge-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAwB,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAI9F,eAAO,MAAM,yBAAyB;;;;;;;;;;EAa4C,CAAC;AAKnF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CA4B9E;AASD,sFAAsF;AACtF,MAAM,MAAM,0BAA0B,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,cAAc,CAAC;AAEjG;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,0BAA0B,EACnC,aAAa,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAC9C,OAAO,CAET;AAoBD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,OAAO,GACpB,OAAO,CAUT"}

package/dist/coding/coding-namespace.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Coding-agent namespace overlay (issue #569 PR 2 + PR 3).
+ *
+ * Given a `CodingContext` (from `resolveGitContext`) and a `CodingModeConfig`,
+ * returns the namespace that recall + write paths should use — or `null` when
+ * no overlay should apply (coding mode disabled, no context supplied, or
+ * feature flags off).
+ *
+ * PR 2 ships the project overlay. PR 3 will add the branch overlay; the
+ * function here already handles both flags so the schema / types / plumbing
+ * don't have to change a second time when branch-scope lands.
+ *
+ * Pure function — no orchestrator, no config side-effects. Callers keep rule
+ * 42 (read + write through same namespace layer) by consulting the same
+ * function on both paths.
+ */
+import type { CodingContext, CodingModeConfig } from "../types.js";
+export interface CodingNamespaceOverlay {
+    /**
+     * Effective namespace to use for this session's memory operations. When
+     * `branchScope` is on, takes the form `project:<id>/branch:<b>`; otherwise
+     * `project:<id>`.
+     */
+    namespace: string;
+    /**
+     * Read fallbacks — additional namespaces a caller should include in recall
+     * so that, for example, a branch-scoped session still sees project-level
+     * memories that were written before the branch scope was enabled.
+     *
+     * Writes MUST go to `namespace` only; these are read-side only.
+     *
+     * Introduced to carry PR 3's branch→project fallback; PR 2 returns an empty
+     * array here.
+     */
+    readFallbacks: string[];
+    /**
+     * `"project"` when only project scope applies, `"branch"` when branch scope
+     * is also layered on. Used for diagnostics (`remnic doctor`) and logging.
+     */
+    scope: "project" | "branch";
+}
+/**
+ * Normalize a projectId / branch fragment so the resulting namespace passes
+ * the router's `isSafeRouteNamespace` check (`[A-Za-z0-9._-]{1,64}`).
+ *
+ * Namespaces are used as filesystem directory names and must not contain
+ * path separators (`/`, `\`) or colons — so both `:` and `/` collapse to `-`.
+ * The project-id format `origin:<8hex>` and branch names like `feat/x` both
+ * flow through this helper before hitting the storage layer.
+ *
+ * NOT a security boundary — projectIds come from `resolveGitContext` (known
+ * hex), and branch names come from local git. This defends against corrupt
+ * input only.
+ */
+/**
+ * Single-pass sanitization — each input character is visited exactly once.
+ * Rewriting as an explicit loop (instead of chained `replace()` calls with
+ * greedy quantifiers) closes the polynomial-backtracking surface that
+ * CodeQL flagged on patterns like `-+` and `^-+|-+$`.
+ */
+export declare function sanitizeFragment(input: string): string;
+/**
+ * Produce the project-scope namespace name. Exported for tests and for
+ * `remnic doctor` to render. Guaranteed to satisfy `isSafeRouteNamespace`:
+ * no `/`, no `:`, lowercase only, length-capped to 64 chars.
+ */
+export declare function projectNamespaceName(projectId: string): string;
+export declare function projectTagProjectId(projectTag: string): string;
+/**
+ * Combine a principal-derived base namespace (e.g. `default`, `alice`) with a
+ * coding-agent overlay namespace (e.g. `project-origin-abcd1234`). The result
+ * is a single safe-route token that preserves principal isolation (CLAUDE.md
+ * rule 42: read + write must resolve through the same namespace layer — and
+ * here, through the same principal-scoped prefix) while layering project or
+ * project/branch scope on top.
+ *
+ * Multiple principals working in the same repo thus get distinct namespaces:
+ *
+ *   alice + project-origin-ab12  →  alice-project-origin-ab12
+ *   bob   + project-origin-ab12  →  bob-project-origin-ab12
+ *   Alice + project-origin-ab12  →  Alice-project-origin-ab12 (distinct)
+ *
+ * The base fragment preserves case so `Alice` and `alice` remain distinct;
+ * the overlay fragment is still lowercase-sanitized because it derives from
+ * deterministic, pre-lowercased git hashes.
+ *
+ * Output is re-capped through `capLength` so a very long base + overlay
+ * combination still fits inside `isSafeRouteNamespace` (≤ 64 chars). The
+ * deterministic hash suffix on truncation keeps distinct inputs distinct.
+ */
+export declare function combineNamespaces(base: string, overlay: string): string;
+/**
+ * Produce the branch-scope namespace name. Format:
+ * `project-<id>-branch-<name>[-<hash>]`. Uses `-` as the structural separator
+ * rather than `/` or `:` so the result is a single safe route-namespace
+ * token that can be used directly as a filesystem directory.
+ *
+ * Two failure modes must not collapse distinct branches to one namespace:
+ *
+ *   1. Sanitization is lossy (`feat/x` and `feat-x` both sanitize to
+ *      `feat-x`; `Feature` and `feature` both sanitize to `feature`). When
+ *      sanitization rewrote any character, we append a short hash of the
+ *      RAW branch so distinct inputs stay distinct.
+ *   2. Truncation is applied when the total exceeds 64 chars. In that
+ *      mode `capLength` appends its own hash of the full pre-truncated
+ *      value.
+ *
+ * Long branches that also sanitize may receive both kinds of hashes — that
+ * is acceptable: the router only requires the result be unique and
+ * deterministic, and the two hashes derive from different domains so they
+ * don't conflict.
+ */
+export declare function branchNamespaceName(projectId: string, branch: string): string;
+/**
+ * Compute the namespace overlay for a session.
+ *
+ * Returns `null` when no overlay applies — callers should then use their
+ * existing `defaultNamespaceForPrincipal(...)` result unchanged. This keeps
+ * CLAUDE.md #30 (escape hatch): setting `codingMode.projectScope: false`
+ * exactly restores pre-#569 behaviour at every call site.
+ *
+ * @param codingContext — git context from the connector
+ * @param config — coding mode flags (projectScope, branchScope, globalFallback)
+ * @param defaultNamespace — retained for call-site compatibility; no longer
+ *   used. The global fallback is expressed as an empty-string sentinel in
+ *   `readFallbacks`, which `combineNamespaces(principal, "")` resolves to the
+ *   principal's own namespace at the call site.
+ */
+export declare function resolveCodingNamespaceOverlay(codingContext: CodingContext | null | undefined, config: Pick<CodingModeConfig, "projectScope" | "branchScope" | "globalFallback">, defaultNamespace?: string): CodingNamespaceOverlay | null;
+export interface CodingScopeDescription {
+    /** "none" when no overlay is active; otherwise the resolved scope level. */
+    scope: "none" | "project" | "branch";
+    /** Project id (raw, not sanitized) when a context is attached. */
+    projectId: string | null;
+    /** Branch name (raw, not sanitized) when available. */
+    branch: string | null;
+    /** Effective namespace writes route to. `null` when no overlay applies. */
+    effectiveNamespace: string | null;
+    /** Read fallbacks included in recall (non-empty only when branch-scope is on). */
+    readFallbacks: string[];
+    /**
+     * Why no overlay applies, when `scope === "none"`. One of:
+     *   - `"no-context"`  — connector didn't attach a CodingContext
+     *   - `"disabled"`   — codingMode.projectScope is false
+     *   - `"empty-project"` — codingContext.projectId was empty/whitespace
+     */
+    disabledReason: "no-context" | "disabled" | "empty-project" | null;
+}
+/**
+ * Human-readable description of the coding-agent scope that currently applies
+ * for a session. Consumed by `remnic doctor` (PR 8) and by logs to surface
+ * why recall routes where it does.
+ *
+ * Pure — callers pass the coding context + config they already have.
+ */
+export declare function describeCodingScope(codingContext: CodingContext | null | undefined, config: Pick<CodingModeConfig, "projectScope" | "branchScope" | "globalFallback">, defaultNamespace?: string): CodingScopeDescription;
+/**
+ * Build the LCM/structured-history `session_id` that a write-producing surface
+ * archives under, and that a same-session reader must search under, so reads
+ * and writes never drift (#1495, CLAUDE.md rule 42).
+ *
+ * The LCM archive filters strictly by the `session_id` string, so the writer's
+ * archival key and the reader's lookup key MUST agree byte-for-byte. The
+ * encoding frames the namespace with the reserved {@link LCM_NS_SENTINEL}
+ * (`\x1f<namespace>\x1f<sessionKey>`) whenever that namespace diverges from the
+ * single-store default; otherwise it passes the (escaped) raw `sessionKey` so
+ * single-user / no-overlay deployments keep pre-#1495 behavior exactly. The two
+ * key-spaces are provably disjoint, so a caller-controlled raw `sessionKey`
+ * cannot forge another namespace's encoded id (see the {@link LCM_NS_SENTINEL}
+ * doc comment for the full security rationale).
+ *
+ * `observe`, compaction flush/record, and the orchestrator recall readers all
+ * route through this one helper so a project-scoped (cwd/projectTag) or
+ * explicit-namespace session reads its own compressed-history / structured /
+ * targeted-fact evidence instead of missing it.
+ */
+export declare function lcmSessionKeyForNamespace(namespace: string | undefined, sessionKey: string | undefined, defaultNamespace: string): string | undefined;
+/**
+ * Map an ORDERED, read-authorized namespace set (the SAME set normal QMD/file
+ * recall searches) to the ordered set of LCM `session_id`s a same-session reader
+ * must query (#1505 thread "Include coding fallback namespaces in LCM reads").
+ *
+ * The LCM archive filters strictly by `session_id`, and `observe` archives each
+ * turn under `${effectiveNamespace}:${sessionKey}` for the namespace that was
+ * effective when it was written. A branch-scoped session that overlays
+ * `${base-project-*-branch-*}` only sees rows written under THAT namespace if it
+ * reads a single overlay key — but normal recall ALSO searches the
+ * `codingOverlay.readFallbacks` (project / root) namespaces, so rows archived at
+ * project/root scope are surfaced by QMD/file recall yet MISSED by a single-key
+ * LCM read. Deriving the LCM read keys from the SAME `recallNamespaces` set keeps
+ * the LCM read path from diverging: every namespace recall is authorized to read
+ * (read-auth gate already applied upstream in `recallNamespaces`) contributes one
+ * LCM key, ordered primary-overlay-first then fallbacks. Unreadable namespaces
+ * are never in `recallNamespaces`, so they are never searched here either (no
+ * cross-tenant read leak).
+ *
+ * Single-user / no-overlay recall passes a single-namespace set that collapses to
+ * the raw `sessionKey`, so the result is `[sessionKey]` — byte-for-byte the
+ * pre-#1505 single-key behavior.
+ *
+ * SESSIONLESS recall (`sessionKey === undefined`): returns `[undefined]` so the
+ * caller issues ONE archive-wide LCM read with no exact `session_id` filter —
+ * byte-for-byte the pre-#1505 sessionless behavior. It must NOT substitute the
+ * literal `"default"` session id (codex P2 "Preserve unscoped LCM searches
+ * without a session key"): that would filter to a session literally named
+ * `default`, silently dropping the explicit-cue / targeted / focused / response /
+ * event LCM sections for every recall that omits a session key.
+ *
+ * The result is deduped while preserving first-seen order so the caller can query
+ * keys in priority order and short-circuit on the first hit without re-querying an
+ * identical key (e.g. when two namespaces both collapse to the default store).
+ */
+export declare function lcmReadSessionIdsForNamespaces(namespaces: readonly string[], sessionKey: string | undefined, defaultNamespace: string): Array<string | undefined>;
+//# sourceMappingURL=coding-namespace.d.ts.map

package/dist/coding/coding-namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-namespace.d.ts","sourceRoot":"","sources":["../../src/coding/coding-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGnE,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAMD;;;;;;;;;;;;GAYG;AACH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAwBtD;AAoCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM9D;AAuCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAe7E;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EAC/C,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,cAAc,GAAG,aAAa,GAAG,gBAAgB,CAAC,EACjF,gBAAgB,CAAC,EAAE,MAAM,GACxB,sBAAsB,GAAG,IAAI,CAmD/B;AAMD,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;IACrC,kEAAkE;IAClE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;OAKG;IACH,cAAc,EAAE,YAAY,GAAG,UAAU,GAAG,eAAe,GAAG,IAAI,CAAC;CACpE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EAC/C,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,cAAc,GAAG,aAAa,GAAG,gBAAgB,CAAC,EACjF,gBAAgB,CAAC,EAAE,MAAM,GACxB,sBAAsB,CAyDxB;AA8DD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,gBAAgB,EAAE,MAAM,GACvB,MAAM,GAAG,SAAS,CAepB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,gBAAgB,EAAE,MAAM,GACvB,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAkB3B"}

package/dist/coding/decision-records.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Decision records — pure storage contract (issue #1548 Track A PR 1).
+ *
+ * The four-memory-shape memory layer stores architectural decisions as
+ * markdown files with YAML frontmatter under the coding namespace. This
+ * module is the **pure contract**: data shape, parse, serialise, validate,
+ * and the supersede mutation. No filesystem, no orchestrator — callers
+ * (PR 2's MCP/HTTP/CLI surfaces and the orchestrator's normal persist
+ * pipeline) hang these helpers onto real storage.
+ *
+ * Why markdown + frontmatter?
+ *  - QMD searches the body for free (rule 43 — storage chokepoint means the
+ *    orchestrator persist pipeline fires for catalog + reindex + dedup).
+ *  - Human-reviewable diff via the same tooling as any other memory page.
+ *  - The body carries prose; the frontmatter carries the searchable,
+ *    structured fields.
+ *
+ * Why this parser/serialiser and not a YAML dep?
+ *  - The surface used here is intentionally narrow: scalar strings and
+ *    flow-style arrays of strings. A full YAML dependency is heavier than
+ *    the parser we need and would unlock a footgun (block-scalar
+ *    representations, anchors, multiple-document streams) we deliberately
+ *    want to be impossible.
+ *
+ * Supersede ordering (rule 25): the replacement record MUST land on disk
+ * BEFORE the superseded record's `status` flips, so a process crash between
+ * the two writes leaves the new decision discoverable rather than nothing.
+ *
+ * Pure module — type-only import of the plugin config interface keeps this
+ * dependency-free (the entry types live in `../types.ts`).
+ */
+import type { CodingKnowledgeConfig } from "../types.js";
+export type DecisionStatus = "proposed" | "accepted" | "superseded" | "rejected";
+export declare const DECISION_STATUSES: readonly ["proposed", "accepted", "superseded", "rejected"];
+/**
+ * The "active" statuses callers surface in standing-decisions lists, briefing
+ * text, and the search-by-default index. Exported as a frozen set so the
+ * decision-records tests, the briefing helper, and the future list surface
+ * share one declaration (rule 53 — single source of truth for classification).
+ *
+ * Stand-up note: superseded + rejected are intentionally excluded. A supersede
+ * edge (`b.supersedes = "a"`) tells callers what to fall back to.
+ */
+export declare const ACTIVE_DECISION_STATUSES: ReadonlySet<DecisionStatus>;
+/**
+ * Least-privileged default for a parsed record whose frontmatter omits
+ * `status` (rule 48). "Proposed" — never "accepted" — because accepting a
+ * decision is a deliberate operator action.
+ */
+export declare const DEFAULT_DECISION_STATUS: DecisionStatus;
+export interface DecisionRecord {
+    /** Stable identifier — typically `ADR-XXXX` or `MADR-XXXX`. Must be unique. */
+    id: string;
+    /** One-line summary surfaced in briefings and `list` output. */
+    title: string;
+    /** Status lifecycle (rule 51: only the four declared values). */
+    status: DecisionStatus;
+    /** The problem / context the decision addresses. */
+    context: string;
+    /** The decision itself. */
+    decision: string;
+    /** Trade-offs, follow-ups, consequences. Optional — free-form. */
+    consequences: string | undefined;
+    /** Entity references (entity IDs, doc anchors, code paths). May be empty. */
+    entityRefs: string[];
+    /** The record this one supersedes — set by `applySupersede`, never by hand. */
+    supersedes?: string;
+}
+/**
+ * Input shape for `serializeDecisionRecord`. Mirrors `DecisionRecord` but
+ * keeps `supersedes` reachable so callers writing the replacement before
+ * applying supersede can serialise the new record alone.
+ */
+export type DecisionRecordInput = Omit<DecisionRecord, "supersedes"> & {
+    supersedes?: string;
+};
+export declare function isDecisionStatus(value: unknown): value is DecisionStatus;
+/**
+ * Render a decision record as markdown with a YAML frontmatter block.
+ *
+ * Frontmatter keys are sorted ascending (rule 38). Strings are double-quoted
+ * so reserved YAML characters (`#`, `:`, leading-digits, list-like prefixes)
+ * survive a round-trip without the caller caring.
+ */
+export declare function serializeDecisionRecord(record: DecisionRecordInput): string;
+/**
+ * Parse a decision record from a markdown string with a YAML frontmatter
+ * block. Throws (with a message listing the valid statuses, rule 51) when
+ * the document does not match the contract.
+ *
+ * Missing / undefined `status` defaults to `"proposed"` (rule 48 — least
+ * privileged).
+ */
+export declare function parseDecisionRecord(raw: string): DecisionRecord;
+/**
+ * Pure supersede mutation: given the current record set, the id of a record
+ * to supersede, and the replacement record (already accepted), returns a new
+ * list with the replacement appended and the old record flipped to
+ * `superseded`.
+ *
+ * The hook fires `event: "write:<replacementId>"` BEFORE
+ * `event: "mutate:<oldId>:superseded"` so storage callers can guarantee
+ * disk-order matches the rule-25 requirement (the replacement lands before
+ * the old record's status flips).
+ */
+export declare function applySupersede(records: readonly DecisionRecord[], targetId: string, replacement: DecisionRecord, hook?: (event: string) => void): DecisionRecord[];
+/**
+ * Filter a record set down to "standing" decisions (proposed + accepted).
+ * Uses the explicitly-exported `ACTIVE_DECISION_STATUSES` set (rule 53 — one
+ * classification source) so callers cannot drift.
+ */
+export declare function listActive(records: readonly DecisionRecord[]): DecisionRecord[];
+/**
+ * Single source of truth for "are decision records active for this operator?"
+ * (rule 39 — every behaviour dependent on Track A consults this, not raw
+ * config reads). The master gate is `codingKnowledge.enabled`; the
+ * decision-record subsystem has its own on-switch.
+ */
+export declare function isDecisionRecordsEnabled(config: CodingKnowledgeConfig): boolean;
+//# sourceMappingURL=decision-records.d.ts.map

package/dist/coding/decision-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-records.d.ts","sourceRoot":"","sources":["../../src/coding/decision-records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAMzD,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC;AAEjF,eAAO,MAAM,iBAAiB,6DAKgB,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,cAAc,CAG/D,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAA2B,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,MAAM,EAAE,cAAc,CAAC;IACvB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,GAAG;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAaF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAKxE;AAiBD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAgC3E;AAuCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAwD/D;AAwJD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,cAAc,EAC3B,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAC7B,cAAc,EAAE,CAyClB;AAMD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,cAAc,EAAE,CAE/E;AAMD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAE/E"}

package/dist/coding/decision-surfaces.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Decision-record surface contract + handler (issue #1548 Track A PR 2).
+ *
+ * Rule 39: one gate predicate, checked identically on every surface. Rule 22
+ * spirit: one implementation behind three thin wirings. The service holds
+ * only a thin delegate that builds a {@link DecisionSurfaceContext} and calls
+ * {@link handleCodingDecision}; the handler logic lives here so the
+ * access-service god file gains thin wiring only.
+ *
+ * No orchestrator imports (rule 11 — no shared mutable state). No circular
+ * dependency on access-service.ts: validation errors are thrown via
+ * `ctx.throwInputError`, which the service wires to EngramAccessInputError.
+ */
+import type { CodingKnowledgeConfig, CodingContext, MemoryFile, MemoryFrontmatter, MemoryStatus } from "../types.js";
+import { type SealedMemoryEnvelope } from "../write-envelope.js";
+import type { MemoryWriteResult } from "../storage.js";
+export declare const DECISION_SUBCOMMANDS: readonly ["list", "get", "record", "supersede"];
+export type DecisionSubcommand = (typeof DECISION_SUBCOMMANDS)[number];
+/**
+ * Type guard — narrows an unknown subcommand string to the
+ * {@link DecisionSubcommand} union.
+ */
+export declare function isDecisionSubcommand(value: unknown): value is DecisionSubcommand;
+/**
+ * Human-readable subcommand list for error messages (rule 51 — list valid
+ * options so the caller can correct rather than guess).
+ */
+export declare function formatDecisionSubcommands(): string;
+/**
+ * Canonical surface request — one shape for all three transports. The
+ * `subcommand` field selects which operation runs; the remaining fields are
+ * optional depending on the subcommand.
+ *
+ * `sessionKey` identifies the session whose coding context scopes the
+ * operation. `namespace` overrides the coding-scoped namespace (same
+ * precedence as `memory_store` — explicit namespace wins).
+ */
+export interface DecisionSurfaceRequest {
+    subcommand: DecisionSubcommand;
+    sessionKey?: string;
+    namespace?: string;
+    id?: string;
+    title?: string;
+    status?: string;
+    context?: string;
+    decision?: string;
+    consequences?: string;
+    entityRefs?: string[];
+    supersedesId?: string;
+}
+/**
+ * Surface response — a discriminated union on `subcommand`. Each surface
+ * serializes this to its transport-appropriate shape.
+ */
+export type DecisionSurfaceResponse = {
+    subcommand: "list";
+    records: DecisionSurfaceRecord[];
+    count: number;
+} | {
+    subcommand: "get";
+    found: boolean;
+    record?: DecisionSurfaceRecord;
+} | {
+    subcommand: "record";
+    memoryId: string;
+    status: string;
+} | {
+    subcommand: "supersede";
+    supersededMemoryId: string;
+    replacementMemoryId: string;
+};
+/**
+ * Flattened record projection surfaced to clients. Stored as markdown +
+ * frontmatter memory files (category `"decision"`) — this shape is the
+ * read-side projection, not the storage format.
+ */
+export interface DecisionSurfaceRecord {
+    id: string;
+    title: string;
+    status: string;
+    context?: string;
+    decision?: string;
+    consequences?: string;
+    entityRefs: string[];
+    supersedes?: string;
+}
+/**
+ * Structural subset of StorageManager the decision handler reads or writes.
+ * Kept narrow so the module stays decoupled from storage.ts and is
+ * unit-testable with a stub.
+ */
+export interface DecisionSurfaceStorage {
+    readonly dir: string;
+    /** The resolved namespace — used for catalog write recording. */
+    readonly namespace: string;
+    readAllMemories(): Promise<readonly MemoryFile[]>;
+    getMemoryById(id: string): Promise<MemoryFile | null>;
+    /**
+     * Sealed-envelope write entry point (issue #1989 PR4). The envelope owns
+     * content/category/tags/attributes; the outer lifecycle status (set to
+     * "archived" for inactive decisions so generic recall/search/maintenance
+     * exclude them — review P2) stays a per-write extra.
+     */
+    writeSealedMemory(envelope: SealedMemoryEnvelope, extras: {
+        status?: MemoryStatus;
+    }): Promise<MemoryWriteResult>;
+    writeMemoryFrontmatter(memory: MemoryFile, patch: Partial<MemoryFrontmatter>): Promise<unknown>;
+}
+/**
+ * Dependencies the handler borrows from the service. The service constructs
+ * this context per call; the handler never touches the orchestrator directly.
+ * `throwInputError` lets the handler raise the surface-appropriate error
+ * class without importing access-service.ts (no circular dependency).
+ */
+export interface DecisionSurfaceContext {
+    readonly codingKnowledge: CodingKnowledgeConfig;
+    getCodingContext(sessionKey: string): CodingContext | null;
+    /** Resolve storage through the SAME namespace path as memory_store
+     *  (principal ACL + coding overlay + default fallback). The #1522 storage
+     *  chokepoint records the catalog write automatically on every
+     *  storage.writeMemory, so the handler does NOT touch the catalog itself. */
+    resolveStorage(request: DecisionSurfaceRequest): Promise<DecisionSurfaceStorage>;
+    /** Throw the surface-appropriate input-validation error. */
+    throwInputError(message: string): never;
+    /** Server-resolved connector identity for provenance stamping. */
+    readonly sourceConnector?: string;
+}
+/**
+ * The single shared implementation behind the MCP, HTTP, and CLI
+ * decision-record surfaces. All three transports dispatch through the
+ * `coding_decision` boundary operation, which calls this function via the
+ * service delegate.
+ *
+ * Gate (rule 39): `codingKnowledge.enabled + decisionRecords + coding
+ * context`. Persistence (rule 43): records are written through the storage
+ * manager's normal persist pipeline with category `"decision"` — no direct
+ * `fs` writes of memory content. Supersede (rule 25): the replacement is
+ * written BEFORE the old record's `structuredAttributes.decisionStatus` is
+ * set to `"superseded"` — the structuredAttribute is the authoritative
+ * lifecycle marker; content is never rewritten.
+ */
+export declare function handleCodingDecision(request: DecisionSurfaceRequest, ctx: DecisionSurfaceContext): Promise<DecisionSurfaceResponse>;
+//# sourceMappingURL=decision-surfaces.d.ts.map

package/dist/coding/decision-surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-surfaces.d.ts","sourceRoot":"","sources":["../../src/coding/decision-surfaces.ts"],"names":[],"mappings":"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"}

package/dist/coding/export-okf-codegraph.d.ts

@@ -1,33 +1,15 @@
-import { P as PluginConfig } from '../types-Du6VdoAg.js';
-import '../message-parts/index.js';
-import '../bounded-jsonl-state.js';
-import '../operator-doctor-types.js';
-import '../external-wiki-config.js';
-import '../recall-state-view.js';
-import '../contradiction-config.js';
-import '../graph-path-scoring-config.js';
-import '../background-generation-config.js';
-import '../deep-recall-config.js';
-import '../recall-navigation-config.js';
-import '../recall-recognition-tier.js';
-import '../causal-trajectory.js';
-import '../objective-state.js';
-import '../active-context-config.js';
-import '../local-llm-config.js';
-import '../semantic-merge-config.js';
-import '../types-continuity.js';
-
+import type { PluginConfig } from "../types.js";
 /** Default cap on rendered module concepts (`--max-module-concepts`). */
-declare const DEFAULT_OKF_CODEGRAPH_MAX_MODULE_CONCEPTS = 500;
+export declare const DEFAULT_OKF_CODEGRAPH_MAX_MODULE_CONCEPTS = 500;
 /**
  * Visible marker written into the root index when module concepts were
  * truncated (mirrors `ARCHITECTURE_CARD_TRUNCATION_MARKER` — never
  * silently incomplete).
  */
-declare const OKF_CODEGRAPH_TRUNCATION_MARKER = "<!-- okf-codegraph-truncated -->";
-type OkfCodegraphSymbolFilter = "none" | "exported" | "all";
-declare function parseOkfCodegraphSymbolFilter(raw: unknown): OkfCodegraphSymbolFilter;
-interface ExportOkfCodegraphOptions {
+export declare const OKF_CODEGRAPH_TRUNCATION_MARKER = "<!-- okf-codegraph-truncated -->";
+export type OkfCodegraphSymbolFilter = "none" | "exported" | "all";
+export declare function parseOkfCodegraphSymbolFilter(raw: unknown): OkfCodegraphSymbolFilter;
+export interface ExportOkfCodegraphOptions {
     readonly config: PluginConfig;
     readonly memoryDir: string;
     /** Store owner; defaults to `"default"` like the access-service principal key. */
@@ -50,7 +32,7 @@ interface ExportOkfCodegraphOptions {
      */
     readonly namespace?: string;
 }
-interface ExportOkfCodegraphResult {
+export interface ExportOkfCodegraphResult {
     readonly projectId: string;
     readonly moduleConcepts: number;
     readonly moduleFilesInGraph: number;
@@ -58,6 +40,5 @@ interface ExportOkfCodegraphResult {
     readonly decisions: number;
     readonly architectureCard: boolean;
 }
-declare function exportCodegraphOkfBundle(opts: ExportOkfCodegraphOptions): Promise<ExportOkfCodegraphResult>;
-
-export { DEFAULT_OKF_CODEGRAPH_MAX_MODULE_CONCEPTS, type ExportOkfCodegraphOptions, type ExportOkfCodegraphResult, OKF_CODEGRAPH_TRUNCATION_MARKER, type OkfCodegraphSymbolFilter, exportCodegraphOkfBundle, parseOkfCodegraphSymbolFilter };
+export declare function exportCodegraphOkfBundle(opts: ExportOkfCodegraphOptions): Promise<ExportOkfCodegraphResult>;
+//# sourceMappingURL=export-okf-codegraph.d.ts.map

package/dist/coding/export-okf-codegraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-okf-codegraph.d.ts","sourceRoot":"","sources":["../../src/coding/export-okf-codegraph.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAkBhD,yEAAyE;AACzE,eAAO,MAAM,yCAAyC,MAAM,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAElF,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;AAInE,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,wBAAwB,CAKpF;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IAC5C,wDAAwD;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AA0BD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,wBAAwB,CAAC,CAgNnC"}