@remnic/core 9.69.56 → 9.69.57

package/dist/coding/action-gate.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Action-site failure gate (issue #2382, slice 1 — core contract).
+ *
+ * The H6 study (#1963) measured that a failure memory delivered in the prompt
+ * preamble barely changes behaviour, while the same memory delivered at the
+ * moment the agent proposes the matched action removes the repeated failure.
+ * This module productionises that delivery point: `ActionGateService` wraps the
+ * experimental `PreActionFailureGate` primitive, adds failure-class memory
+ * candidates, a per-turn budget, cross-channel suppression, and telemetry.
+ *
+ * Scope, per the study's honest limit: the gate removes a known failure mode.
+ * It does not improve task completion. It is advisory only — it never blocks an
+ * action, never outruns its deadline, and fails open on every error path.
+ */
+import type { ActionIntent, ActionStrategyId } from "../causal-trajectory.js";
+import type { CodingContext, MemoryFile } from "../types.js";
+import { type PreActionFailureGate } from "./pre-action-gate.js";
+export declare const ACTION_GATE_DEFAULT_MAX_ADVISORIES_PER_TURN = 3;
+export interface ActionGateConfig {
+    /**
+     * Master gate. Default `false`: when disabled no lookup, no matching, and no
+     * suppression bookkeeping runs on any path.
+     */
+    enabled: boolean;
+    /** Hard latency cap for a whole gate evaluation. Overrun fails open. */
+    timeoutMs: number;
+    /** Advisories injected per turn. `0` disables injection and all lookups. */
+    maxAdvisoriesPerTurn: number;
+}
+export declare const ACTION_GATE_DEFAULTS: ActionGateConfig;
+export declare function parseActionGateConfig(raw: unknown): ActionGateConfig;
+export type ActionGateStatus = "DISABLED" | "NO_MATCH" | "MATCH_WARN" | "ERROR_FAIL_OPEN";
+export interface ActionGateRequest {
+    sessionKey: string;
+    /** Turn identity: the per-turn budget and dedupe reset when this changes. */
+    turnId: string;
+    strategyId: ActionStrategyId;
+    intent: ActionIntent;
+    codingContext: CodingContext;
+    /** Memory directory ALREADY resolved for the caller's readable namespace. */
+    memoryDir: string;
+    /** Resolved readable namespace, passed verbatim to candidate sources. */
+    namespace?: string;
+    causalTrajectoryStoreDir?: string;
+    signal?: AbortSignal;
+}
+export interface ActionGateAdvisory {
+    /** Trajectory id or memory id — the unit of dedupe and suppression. */
+    memoryId: string;
+    sourceId: string;
+    text: string;
+}
+export interface ActionGateDecision {
+    status: ActionGateStatus;
+    advisories: ActionGateAdvisory[];
+    /** Candidates withheld: already delivered this turn/session, or over budget. */
+    suppressedIds: string[];
+    /** Source failures, kept distinct from "no candidates" (rule 22). */
+    degradations: string[];
+    fingerprint?: string;
+    reason?: string;
+    latencyMs: number;
+}
+export interface ActionGateCandidate {
+    memoryId: string;
+    advisoryText: string;
+    /** Deterministic ranking key; higher wins, ties break on `memoryId`. */
+    score?: number;
+}
+export interface ActionGateCandidateQuery {
+    sessionKey: string;
+    fingerprint: string;
+    /** Normalized, deduplicated lexical terms describing the proposed action. */
+    actionTerms: string[];
+    strategyId: ActionStrategyId;
+    intent: ActionIntent;
+    codingContext: CodingContext;
+    memoryDir: string;
+    namespace?: string;
+    causalTrajectoryStoreDir?: string;
+    signal?: AbortSignal;
+}
+export type ActionGateSourceResult = {
+    ok: true;
+    candidates: ActionGateCandidate[];
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ActionGateCandidateSource {
+    readonly id: string;
+    find(query: ActionGateCandidateQuery): Promise<ActionGateSourceResult>;
+}
+export interface ActionGateAuditRecord {
+    ts: string;
+    sessionKey: string;
+    turnId: string;
+    status: ActionGateStatus;
+    latencyMs: number;
+    fingerprint?: string;
+    deliveredIds: string[];
+    suppressedIds: string[];
+    degradations: string[];
+    reason?: string;
+}
+export type ActionGateAuditSink = (record: ActionGateAuditRecord) => void | Promise<void>;
+export interface ActionGateServiceDependencies {
+    sources?: ActionGateCandidateSource[];
+    audit?: ActionGateAuditSink;
+    clock?: () => number;
+    now?: () => Date;
+}
+/**
+ * Deterministic, local term extraction from a proposed action. No LLM and no
+ * I/O: this runs in the hot path ahead of the tool call.
+ */
+export declare function actionTermsFor(intent: ActionIntent): string[];
+/**
+ * Failure-class markers on stored memories, read from frontmatter only so the
+ * decision stays deterministic: explicit corrections, procedures flagged for
+ * repair by library maintenance, and memories whose recorded outcomes are
+ * failure-dominant.
+ */
+export declare function isFailureClassMemory(memory: MemoryFile): boolean;
+export interface FailureMemorySourceDependencies {
+    /**
+     * Namespace-scoped listing of candidate memories. Callers wire this to a
+     * storage read for the SAME namespace the gate request resolved, so a
+     * principal can never receive another principal's advisories.
+     */
+    listMemories: (options: {
+        namespace?: string;
+        memoryDir: string;
+        signal?: AbortSignal;
+    }) => Promise<MemoryFile[]>;
+}
+/**
+ * Failure-class memory candidates, matched by bounded lexical overlap against
+ * the proposed action's terms. Deterministic and local by construction.
+ */
+export declare function createFailureMemoryCandidateSource(deps: FailureMemorySourceDependencies): ActionGateCandidateSource;
+/**
+ * Candidate source over recorded causal-trajectory failures, delegating the
+ * fingerprint match to the existing `PreActionFailureGate` primitive.
+ */
+export declare function createTrajectoryCandidateSource(gate: PreActionFailureGate): ActionGateCandidateSource;
+/**
+ * Advisory gate evaluated immediately before an agent action.
+ *
+ * Delivery is bounded three ways: a hard deadline, `maxAdvisoriesPerTurn`, and
+ * dedupe per memory per turn. Cross-channel suppression keeps one memory from
+ * arriving twice in a session — once here and once from turn-start recall.
+ */
+export declare class ActionGateService {
+    private readonly config;
+    private readonly sources;
+    private readonly audit?;
+    private readonly clock;
+    private readonly now;
+    private readonly sessions;
+    constructor(config: ActionGateConfig, deps?: ActionGateServiceDependencies);
+    /**
+     * Memory ids the gate already delivered in this session. Turn-start recall
+     * filters these out before its own cap, honouring the filter-then-cap order.
+     */
+    suppressedForTurnStart(sessionKey: string): string[];
+    /** Record ids turn-start recall injected, so the gate will not repeat them. */
+    noteTurnStartDelivery(sessionKey: string, memoryIds: readonly string[]): void;
+    resetSession(sessionKey: string): void;
+    evaluate(request: ActionGateRequest): Promise<ActionGateDecision>;
+    private collect;
+    private finish;
+    private sessionState;
+    private addTracked;
+}
+//# sourceMappingURL=action-gate.d.ts.map

package/dist/coding/action-gate.d.ts.map

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

package/dist/coding/architecture-card.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Maximum byte size of the serialised card. When the deterministic card
+ * exceeds this, it is truncated with a visible marker so consumers know
+ * information was elided (rule 34 — never silently incomplete).
+ */
+export declare const ARCHITECTURE_CARD_MAX_BYTES = 4096;
+/**
+ * Visible marker appended when the card is truncated. Exported so callers
+ * that read stored card content can detect truncation from the content
+ * itself, without depending on a frontmatter tag that may go stale on
+ * content-only updates (cursor review: "stale truncated tag on update").
+ */
+export declare const ARCHITECTURE_CARD_TRUNCATION_MARKER = "\u2026 card truncated to fit size cap \u2026";
+/**
+ * Maximum byte size of the LLM summary prefix. The summary is additive —
+ * the deterministic card (manifests, languages, entry points) must ALWAYS
+ * survive truncation. Clamping the summary before prepending prevents a
+ * misbehaving or prompt-injected summariser from crowding out the
+ * deterministic sections (codex review).
+ */
+export declare const ARCHITECTURE_CARD_MAX_SUMMARY_BYTES = 1024;
+/**
+ * Manifest files the scanner knows how to parse for project metadata
+ * (name, entry points). Single source of truth (rule 53 analog).
+ */
+export declare const KNOWN_MANIFEST_FILES: readonly ["package.json", "Cargo.toml", "go.mod", "pyproject.toml", "setup.py", "pom.xml", "build.gradle", "build.gradle.kts", "Gemfile", "composer.json", "mix.exs", "deno.json"];
+/**
+ * Directories the scanner skips (would distort the histogram or are
+ * universally non-source). Kept conservative — operators with unusual
+ * layouts still get useful output.
+ */
+export declare const SCAN_IGNORE_DIRS: ReadonlySet<string>;
+/**
+ * Result of a deterministic architecture-card build.
+ */
+export interface ArchitectureCard {
+    /** The markdown card body (may be truncated to fit the byte cap). */
+    readonly content: string;
+    /** ISO timestamp of the build. */
+    readonly generatedAt: string;
+    /** Byte length of `content`. */
+    readonly byteSize: number;
+    /** Whether the card was truncated to fit `maxBytes`. */
+    readonly truncated: boolean;
+}
+/**
+ * Injectable LLM summariser. Receives the deterministic card and the
+ * repo root; returns a summary string, or `null` to keep the
+ * deterministic card unchanged. Implementations MUST NOT throw —
+ * failures should return `null` (rule 13).
+ */
+export type ArchitectureCardSummariser = (deterministicCard: string, repoRoot: string) => Promise<string | null>;
+/**
+ * Minimal chat-completion surface for the architecture-card summariser.
+ * Structural — satisfied by both `FallbackLlmClient` (gateway model
+ * chain) and `LocalLlmClient` (Ollama / OpenAI-compatible local
+ * endpoints) without this pure module importing either (rule 48 — the
+ * builder stays free of orchestrator/client references). The shape
+ * mirrors `Orchestrator.fastLlmForRerank` so callers resolve the client
+ * gateway-first, matching LCM routing precedence.
+ */
+export interface ArchitectureCardLlmClient {
+    chatCompletion(messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>, options?: {
+        temperature?: number;
+        maxTokens?: number;
+        timeoutMs?: number;
+        operation?: string;
+        priority?: "background" | "recall-critical";
+    }): Promise<{
+        content: string;
+    } | null>;
+}
+/**
+ * Build an {@link ArchitectureCardSummariser} backed by an LLM client.
+ * The client is a structural type so this module does NOT import
+ * `LocalLlmClient` / `FallbackLlmClient` (rule 48 — pure builder). The
+ * caller resolves which client to use (gateway-first, matching LCM) and
+ * may pass `null` when none is configured — then the summariser is
+ * `undefined` so the builder's LLM branch stays inert (no silent no-op).
+ *
+ * Failures return `null` (rule 13) so the deterministic card ships
+ * unchanged; `buildArchitectureCard` additionally defends against
+ * implementations that throw.
+ */
+export declare function createArchitectureCardSummariser(client: ArchitectureCardLlmClient | null): ArchitectureCardSummariser | undefined;
+/**
+ * Optional dependencies for `buildArchitectureCard`.
+ */
+export interface BuildArchitectureCardOptions {
+    /** Injected clock — makes tests deterministic. */
+    now?: Date;
+    /** Override the byte cap (defaults to {@link ARCHITECTURE_CARD_MAX_BYTES}). */
+    maxBytes?: number;
+    /**
+     * When `true`, invoke `summariser` to prepend an LLM overview.
+     * Callers gate this on `codingKnowledge.architectureCardLlmSummary`
+     * (rule 48 — opt-in).
+     */
+    llmSummary?: boolean;
+    /** The summariser implementation (required when `llmSummary` is true). */
+    summariser?: ArchitectureCardSummariser;
+}
+/**
+ * Tagged failure from the build (rule 34).
+ */
+export type ArchitectureCardBuildFailure = {
+    ok: false;
+    code: "invalid_root" | "scan_failed";
+    detail: string;
+};
+/**
+ * Tagged result: success carries the card; failure carries a code.
+ */
+export type ArchitectureCardBuildResult = {
+    ok: true;
+    card: ArchitectureCard;
+} | ArchitectureCardBuildFailure;
+/**
+ * Deterministically build an architecture card for a repository.
+ *
+ * The scan:
+ *  1. Reads top-level directory entries (sorted, rule 38).
+ *  2. Parses any present manifest files for project name + entry points.
+ *  3. Walks up to two levels deep to compute a language histogram by
+ *     extension (capped to keep the scan fast on large repos).
+ *  4. Renders a compact markdown card, sorted throughout.
+ *
+ * File *contents* are never read except for manifest files. The walker
+ * only reads directory entries and file extensions (privacy + speed).
+ */
+export declare function buildArchitectureCard(repoRoot: string, options?: BuildArchitectureCardOptions): Promise<ArchitectureCardBuildResult>;
+//# sourceMappingURL=architecture-card.d.ts.map

package/dist/coding/architecture-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"architecture-card.d.ts","sourceRoot":"","sources":["../../src/coding/architecture-card.ts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,iDAAuC,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,OAAO,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,oLAavB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAqB/C,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE5B;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACxC,cAAc,CACZ,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,EAC3E,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAAC;KAC7C,GACA,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACxC;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,yBAAyB,GAAG,IAAI,GACvC,0BAA0B,GAAG,SAAS,CAiBxC;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,kDAAkD;IAClD,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,0BAA0B,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,4BAA4B,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,2BAA2B,GACnC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACpC,4BAA4B,CAAC;AAMjC;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,2BAA2B,CAAC,CA4FtC"}

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

@@ -0,0 +1,166 @@
+/**
+ * Architecture-card surface contract + handler (issue #1548 Track A PR 3).
+ *
+ * Mirrors the decision-surfaces pattern (PR 2): one shared implementation
+ * behind the MCP, HTTP, and CLI surfaces. All three transports dispatch
+ * through the `coding_architecture` boundary operation, which calls
+ * {@link handleCodingArchitecture} via the service delegate.
+ *
+ * Gate (rule 39): `codingKnowledge.enabled + architectureCard + coding
+ * context` — one predicate, identical on every surface. The tools/list
+ * visibility gate checks conditions 1–2 only (config-level).
+ *
+ * Persistence (rule 43): the card is written through the storage
+ * manager's normal persist pipeline (writeMemory for the initial card,
+ * updateMemory for refreshes) so catalog recording + reindex fire. No
+ * direct `fs` writes of memory content. Each refresh snapshots the
+ * prior content via page-versioning before overwriting (rule 25 —
+ * preserve the old before the new is ready).
+ *
+ * Subcommands:
+ *  - `get`: return the current architecture card (or not-found).
+ *  - `refresh`: build a fresh card from the repo, persist it, and
+ *    snapshot the prior version.
+ */
+import type { CodingKnowledgeConfig, CodingContext, MemoryFile, MemoryFrontmatter, MemoryStatus } from "../types.js";
+import type { VersionTrigger, VersioningConfig } from "../page-versioning.js";
+import type { MemoryWriteResult } from "../storage.js";
+import { type ArchitectureCardBuildResult } from "./architecture-card.js";
+import { type SealedMemoryEnvelope } from "../write-envelope.js";
+export declare const ARCHITECTURE_SUBCOMMANDS: readonly ["get", "refresh"];
+export type ArchitectureSubcommand = (typeof ARCHITECTURE_SUBCOMMANDS)[number];
+/** Type guard — narrows an unknown subcommand string. */
+export declare function isArchitectureSubcommand(value: unknown): value is ArchitectureSubcommand;
+/** Human-readable subcommand list for error messages (rule 51). */
+export declare function formatArchitectureSubcommands(): string;
+/** Canonical surface request — one shape for all three transports. */
+export interface ArchitectureSurfaceRequest {
+    subcommand: ArchitectureSubcommand;
+    sessionKey?: string;
+    namespace?: string;
+}
+/** Surface response — discriminated union on `subcommand`. */
+export type ArchitectureSurfaceResponse = {
+    subcommand: "get";
+    found: boolean;
+    card?: {
+        content: string;
+        generatedAt: string;
+        byteSize: number;
+        truncated: boolean;
+    };
+} | {
+    subcommand: "refresh";
+    refreshed: boolean;
+    memoryId: string;
+    byteSize: number;
+    truncated: boolean;
+    buildCode?: string;
+    /**
+     * Present when the refresh was tombstone-blocked (#1579): the new card
+     * content landed pending_review (no active overwrite). Callers/UI surface
+     * this so operators see why the active card didn't update (#1645).
+     */
+    blockedReason?: string;
+    /** The tombstone id that blocked the write, when `blockedReason` is set. */
+    blockedBy?: string;
+};
+/** Tag identifying the architecture card memory (single card per namespace). */
+export declare const ARCHITECTURE_CARD_TAG = "architecture-card";
+/** Structured attribute marking a memory as the architecture card. */
+export declare const ARCHITECTURE_CARD_KIND = "architecture";
+/**
+ * Structural subset of StorageManager the architecture handler reads or
+ * writes. Kept narrow so the module stays decoupled from storage.ts and
+ * is unit-testable with a stub.
+ */
+export interface ArchitectureSurfaceStorage {
+    readonly dir: string;
+    /** The resolved namespace — used for logging/observability. */
+    readonly namespace: string;
+    readAllMemories(): Promise<readonly MemoryFile[]>;
+    /** Sealed-envelope write entry point (issue #1989 PR4). */
+    writeSealedMemory(envelope: SealedMemoryEnvelope, extras: {
+        status?: MemoryStatus;
+    }): Promise<MemoryWriteResult>;
+    updateMemory(id: string, newContent: string, options?: {
+        supersedes?: string;
+        lineage?: string[];
+        actor?: string;
+        sourceConnector?: string;
+    }): Promise<boolean>;
+}
+/**
+ * Card-builder dependency. The handler delegates repo scanning to this
+ * function so tests can inject a fixed card without touching the
+ * filesystem.
+ */
+export type ArchitectureCardBuilder = (repoRoot: string) => Promise<ArchitectureCardBuildResult>;
+/**
+ * Page-versioning snapshot dependency. The handler calls this BEFORE
+ * overwriting the card content so the prior version is preserved
+ * (rule 25).
+ */
+export interface ArchitectureVersioningHook {
+    /**
+     * Snapshot the current content of the card memory before refresh.
+     * Failures are logged but do not block the refresh (best-effort).
+     */
+    snapshotIfExists(memory: MemoryFile): Promise<void>;
+}
+/**
+ * Dependencies the handler borrows from the service. The service
+ * constructs this context per call; the handler never touches the
+ * orchestrator directly.
+ */
+export interface ArchitectureSurfaceContext {
+    readonly codingKnowledge: CodingKnowledgeConfig;
+    getCodingContext(sessionKey: string): CodingContext | null;
+    /** Resolve storage through the SAME namespace path as memory_store. */
+    resolveStorage(request: ArchitectureSurfaceRequest): Promise<ArchitectureSurfaceStorage>;
+    /** Build the architecture card from a repo root. */
+    buildCard: ArchitectureCardBuilder;
+    /** Snapshot the prior card version before refresh (rule 25). */
+    versioning: ArchitectureVersioningHook;
+    /** Throw the surface-appropriate input-validation error. */
+    throwInputError(message: string): never;
+    /** Server-resolved connector identity for provenance. */
+    readonly sourceConnector?: string;
+}
+/**
+ * The single shared implementation behind the MCP, HTTP, and CLI
+ * architecture-card surfaces.
+ *
+ * Gate (rule 39): `codingKnowledge.enabled + architectureCard + coding
+ * context`. Persistence (rule 43): cards are written through the storage
+ * manager's normal persist pipeline. Refresh (rule 25): the prior card
+ * is snapshotted via page-versioning BEFORE the content is overwritten.
+ */
+export declare function handleCodingArchitecture(request: ArchitectureSurfaceRequest, ctx: ArchitectureSurfaceContext): Promise<ArchitectureSurfaceResponse>;
+/**
+ * Find the existing architecture-card memory in the namespace, if any.
+ * Identified by the `architecture-card` tag + `cardKind=architecture`
+ * structured attribute. A single card per namespace is the invariant;
+ * if multiple exist (race), the most recently updated wins.
+ */
+export declare function findArchitectureCardMemory(storage: ArchitectureSurfaceStorage): Promise<MemoryFile | null>;
+/**
+ * Build a {@link MemoryFrontmatter}-shaped patch that marks a memory as
+ * the architecture card. Exported for test fixtures.
+ */
+export declare function architectureCardFrontmatterMarker(): Partial<MemoryFrontmatter>;
+/** Page-version snapshot writer (decoupled type — matches page-versioning.createVersion's call). */
+type CreatePageVersion = (pagePath: string, content: string, trigger: VersionTrigger, config: VersioningConfig, logger: undefined, note: string, memoryDir: string) => Promise<unknown>;
+/**
+ * Build the page-versioning snapshot hook from operator config.
+ *
+ * - Skips entirely when versioning is disabled — no sidecars written for a
+ *   feature the operator turned off (codex review: hardcoded config ignored
+ *   operator settings).
+ * - Reads the FULL file (frontmatter + body) from disk so a revert restores
+ *   the complete memory, not just the body (codex review: snapshot was
+ *   body-only).
+ */
+export declare function createArchitectureVersioningHook(enabled: boolean, maxVersionsPerPage: number, sidecarDir: string, memoryDir: string, readFile: (path: string) => Promise<string>, writeVersion: CreatePageVersion): ArchitectureVersioningHook;
+export {};
+//# sourceMappingURL=architecture-surfaces.d.ts.map

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

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