minnimemory 1.0.0-beta.1

package/dist/compile.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The compiler: turn one memory file into a cache-stable AlwaysOnMemory body plus routed
+ * OnDemandMemory files.
+ *
+ * Pure by design. Everything here is string in, strings out, so the whole compile can be
+ * tested from fixtures and diffed before anything touches a user's disk.
+ *
+ * Structure follows the tiered-memory pattern already running in production in the Minni
+ * agents (AlwaysOnMemory.md, OnDemandMemory/, fixed assembly order), and the emitted
+ * instruction block comes from the MinniMemory v1.0 research set. See instructions.ts.
+ */
+import { type Instruction, type ProfileName } from "./instructions.js";
+import { type MemoryKind } from "./episodic.js";
+/** Marker identifying a host file this tool generated, so it is never double counted. */
+export declare const STUB_MARKER = "<!-- minnimemory:stub v1 -->";
+export interface OnDemandFile {
+    /** slug, also the OnDemandMemory file id used in triggers and ordering */
+    name: string;
+    /** path relative to the compiled directory */
+    file: string;
+    heading: string;
+    content: string;
+    tokens: number;
+    triggers: string[];
+    sourceStartLine: number;
+    sourceEndLine: number;
+    /** why it was routed out of AlwaysOnMemory; `generated` is emitted by the compiler, not from the source */
+    reason: "task-specific" | "volatile" | "over-budget" | "generated";
+    /** O2: semantic (edited in place), episodic (append-only), procedural (a learned rule) */
+    kind?: MemoryKind;
+    /** true for OnDemandMemory files the compiler writes itself (the O9 write protocol) */
+    generated?: boolean;
+    /**
+     * True when this file came from splitting an oversized section at its subheadings (O7).
+     * `mergeSmall` never merges these: they were separated on purpose, and merging them back
+     * would undo the split and, worse, glue the last piece to whatever section follows.
+     */
+    split?: boolean;
+}
+/** Default always-loaded budget in tokens; matches doctor's MM001 default. */
+export declare const DEFAULT_BUDGET = 2000;
+export interface CompileOptions {
+    /** basename of the source memory file, for provenance */
+    sourceName: string;
+    /** always-loaded token budget AlwaysOnMemory must fit inside; always-on-like sections that do not fit are demoted */
+    budget?: number;
+    /** instruction profile to embed; defaults to the routing profile */
+    profile?: Instruction[];
+    /** named profile, used when `profile` is not supplied */
+    profileName?: ProfileName;
+    /** heading level to split OnDemandMemory files on; auto-detected when omitted */
+    splitLevel?: number;
+    /**
+     * Use this OnDemandMemory file list instead of the one compiled from the source. `init
+     * --update` passes the files already on disk plus any new ones, so the list and stub are
+     * rendered for the real file set.
+     */
+    onDemandFilesOverride?: OnDemandFile[];
+    /** emit the O9 write-protocol file; on unless a caller says otherwise */
+    writeProtocol?: boolean;
+    /** O3: write episodic files as JSON instead of Markdown */
+    episodicJson?: boolean;
+}
+export interface Compiled {
+    title: string;
+    sourceName: string;
+    sourceHash: string;
+    /** leading YAML frontmatter carried through verbatim; empty when the source had none */
+    frontmatter: string;
+    alwaysOnBody: string;
+    onDemandList: string;
+    /** alwaysOnBody + onDemandList joined, exactly what gets written to .minnimemory/AlwaysOnMemory.md */
+    alwaysOn: string;
+    stub: string;
+    onDemandFiles: OnDemandFile[];
+    /** always-loaded tokens before compilation */
+    before: number;
+    /** always-loaded tokens after compilation, which is the stub */
+    after: number;
+    /** how much of `after` is the injected instruction block rather than the user's content */
+    instructionTokens: number;
+    /** the budget AlwaysOnMemory placement was held to */
+    budget: number;
+    /** always-on-like sections routed to OnDemandMemory files because AlwaysOnMemory would not fit the budget with them */
+    demoted: {
+        heading: string;
+        tokens: number;
+    }[];
+}
+/** Headings whose content is identity or invariant, so it belongs in AlwaysOnMemory. */
+export declare const ALWAYS_ON_HINTS: RegExp;
+declare function hash(text: string): string;
+/**
+ * The hash MM010 and recall's drift check both compare against a manifest entry.
+ *
+ * CRLF-normalised and trailing-whitespace-trimmed on purpose: a checkout can rewrite line
+ * endings with nobody editing anything, and a file that differs only that way has not drifted.
+ * One copy, because the dated-bullet regex taught us what three copies of a rule costs
+ * (2026-09-13 audit, D7).
+ */
+export declare function driftHash(content: string): string;
+/**
+ * Shared with rules.ts's MM010 check against AlwaysOnMemory.md and the stub: sha256 slice 16
+ * with no normalisation, the caller's job (CRLF-only, no trimEnd - those files are written
+ * verbatim, so trimming would blur an edit driftHash would forgive on purpose for OnDemandMemory
+ * files but should not here).
+ */
+export { hash as verbatimHash };
+/**
+ * The list title is deliberately not derived from the document title: a title can carry a
+ * date or a status word ("Minni (renamed 2026-08-11)"), and the list must stay free of anything
+ * the volatility rules would flag. The whole list is fenced with markers so `doctor` can tell a
+ * routing manifest from prose.
+ *
+ * One line per OnDemandMemory file and nothing that restates a Part 2 rule (P4). Rules 15, 16,
+ * 22 and 23 already say how to use the list and sit in the same prefix whenever a discipline
+ * block is embedded; the previous table-plus-prose form repeated them at 159 tokens per compile.
+ * Only the `none` profile, which embeds no block, gets one routing line after the list. Assembly
+ * order is the manifest's `order`, not prefix text.
+ */
+/** The directory `init` writes next to the host file. Named here, where the stub's
+ * OnDemandMemory list is rendered, so the two can never disagree about where a file lives. */
+export declare const COMPILED_DIR_NAME = ".minnimemory";
+/** The one always-loaded file inside the compiled directory: AlwaysOnMemory body plus the
+ * OnDemandMemory list. */
+export declare const ALWAYS_ON_FILE_NAME = "AlwaysOnMemory.md";
+/** The OnDemandMemory files directory inside the compiled directory. */
+export declare const ON_DEMAND_DIR_NAME = "OnDemandMemory";
+/**
+ * Is this host file a stub this tool generated? Only a marker on the first line after any
+ * frontmatter counts. A marker quoted in a code block, or anywhere else in prose, is text
+ * (security audit 2026-09-02, finding 5).
+ */
+export declare function isStub(source: string): boolean;
+export declare function compile(source: string, options: CompileOptions): Compiled;
+export interface Manifest {
+    /**
+     * 4: renames the `modules` key to `onDemandFiles` (vocabulary sweep); loadManifest still
+     * accepts a version 3 file and normalises it in memory.
+     * 3: records the stub's hash so MM010 can see drift in the host file itself.
+     * 2: AlwaysOnMemory.md replaces the separate core.md/index.md, OnDemandMemory/ replaces modules/
+     */
+    version: 4;
+    tokenizer: string;
+    generatedFrom: string;
+    sourceHash: string;
+    /**
+     * Whether the embedded discipline block has been measured. Lives here, not in the block
+     * itself, so the agent is not charged for a disclaimer on every turn (P3). Names the
+     * measured pass and what remains unmeasured; see the README's Measurement policy
+     * for what counts.
+     */
+    instructionStatus?: string;
+    order: string[];
+    prefix: {
+        before: number;
+        after: number;
+    };
+    /** the one always-loaded file: AlwaysOnMemory body plus the OnDemandMemory list, AlwaysOnMemory.md */
+    always: {
+        file: string;
+        tokens: number;
+        hash: string;
+    };
+    /**
+     * The host file init rewrote (CLAUDE.md and friends). Hashed because it is the prefix the
+     * agent actually reloads every turn: content appended to it is un-routed and paid for on
+     * every call, and MM010 has no other way to notice.
+     */
+    stub: {
+        file: string;
+        tokens: number;
+        hash: string;
+    };
+    onDemandFiles: {
+        name: string;
+        file: string;
+        tokens: number;
+        hash: string;
+        triggers: string[];
+        sourceLines: [number, number];
+        reason: string;
+        kind?: MemoryKind;
+        generated?: boolean;
+    }[];
+}
+export declare function buildManifest(compiled: Compiled, tokenizer: string): Manifest;