@remnic/core 9.69.55 → 9.69.57

package/dist/training-export/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Training-data export types.
+ *
+ * Defines the generic interface that format-specific adapters
+ * (WeClone, Axolotl, MLX, etc.) implement to convert Remnic
+ * memories into fine-tuning datasets.
+ */
+export interface TrainingExportOptions {
+    memoryDir: string;
+    since?: Date;
+    until?: Date;
+    minConfidence?: number;
+    categories?: string[];
+    includeEntities?: boolean;
+}
+export interface TrainingExportRecord {
+    instruction: string;
+    input: string;
+    output: string;
+    category?: string;
+    confidence?: number;
+    sourceIds?: string[];
+}
+export interface TrainingExportAdapter {
+    name: string;
+    formatRecords(records: TrainingExportRecord[]): string;
+    fileExtension: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/training-export/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/training-export/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAAC;IACvD,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/transcript.d.ts

@@ -1,23 +1,5 @@
-import { P as PluginConfig, T as TranscriptEntry, n as Checkpoint } from './types-Du6VdoAg.js';
-import { SessionIntegrityReport } from './session-integrity.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 { TranscriptEntry, Checkpoint, PluginConfig } from "./types.js";
+import { type SessionIntegrityReport } from "./session-integrity.js";
 /**
  * Compute the half-open UTC instant range `[start, end)` that covers an entire
  * calendar day, suitable for {@link TranscriptManager.readRange}.
@@ -31,7 +13,7 @@ import './types-continuity.js';
  *
  * @param date - A `YYYY-MM-DD` calendar day (UTC).
  */
-declare function utcDayRange(date: string): {
+export declare function utcDayRange(date: string): {
     start: string;
     end: string;
 };
@@ -44,7 +26,7 @@ declare function utcDayRange(date: string): {
  * Channel types are extracted from sessionKey (discord, slack, cron, main, etc.)
  * Checkpoints are used to preserve conversation context across compaction events.
  */
-declare class TranscriptManager {
+export declare class TranscriptManager {
     private transcriptsDir;
     private checkpointPath;
     private stateDir;
@@ -222,5 +204,4 @@ declare class TranscriptManager {
         checkpointHealthy: boolean;
     }>;
 }
-
-export { TranscriptManager, utcDayRange };
+//# sourceMappingURL=transcript.d.ts.map

package/dist/transcript.d.ts.map

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

package/dist/transfer/autodetect.d.ts

@@ -1,4 +1,3 @@
-type ImportFormat = "json" | "sqlite" | "md";
-declare function detectImportFormat(fromPath: string): Promise<ImportFormat | null>;
-
-export { type ImportFormat, detectImportFormat };
+export type ImportFormat = "json" | "sqlite" | "md";
+export declare function detectImportFormat(fromPath: string): Promise<ImportFormat | null>;
+//# sourceMappingURL=autodetect.d.ts.map

package/dist/transfer/autodetect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autodetect.d.ts","sourceRoot":"","sources":["../../src/transfer/autodetect.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;AAEpD,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAqBvF"}

package/dist/transfer/backup.d.ts

@@ -1,4 +1,4 @@
-interface BackupOptions {
+export interface BackupOptions {
     memoryDir: string;
     outDir: string;
     includeTranscripts?: boolean;
@@ -16,6 +16,5 @@ interface BackupOptions {
      */
     encrypt?: boolean;
 }
-declare function backupMemoryDir(opts: BackupOptions): Promise<string>;
-
-export { type BackupOptions, backupMemoryDir };
+export declare function backupMemoryDir(opts: BackupOptions): Promise<string>;
+//# sourceMappingURL=backup.d.ts.map

package/dist/transfer/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/transfer/backup.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CA6E1E"}

package/dist/transfer/backup.js

@@ -1,8 +1,8 @@
 import {
   backupMemoryDir
-} from "../chunk-BXLOS5AJ.js";
+} from "../chunk-2NLLXCJG.js";
 import "../chunk-765K3SAT.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-X7Y7WX73.js";
 import "../chunk-J4EB7DNW.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";

package/dist/transfer/capsule-crypto.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Capsule and backup archive encryption helpers (issue #690 PR 4/4).
+ *
+ * This module sits between the capsule export/import pipeline and the
+ * secure-store primitives (PR 1/4 cipher + PR 2/4 keyring). It handles:
+ *
+ *   - Wrapping a raw `.capsule.json.gz` payload in an AES-256-GCM sealed
+ *     envelope with a small plaintext header so auto-detection works without
+ *     decryption.
+ *   - Symmetrically: reading that header, decrypting the payload, and
+ *     returning the original `.capsule.json.gz` bytes.
+ *   - The same encrypt/decrypt helpers are re-used by the backup pipeline
+ *     (`backup --encrypt`).
+ *
+ * On-disk format for an encrypted archive (format v2, issue #690 PR 4/4)
+ * -------------------------------------------------------------------------
+ * The encrypted file uses the extension `.capsule.json.gz.enc` and starts
+ * with a small ASCII header terminated by a NUL byte so the MIME type can
+ * be determined cheaply:
+ *
+ *   "REMNIC-ENC\x00"   (11 bytes, magic + NUL sentinel)
+ *   UINT8               format version (2 — see version history below)
+ *   UINT16LE            kdf_len: byte length of the KDF params JSON blob
+ *   <kdf_len bytes>     compact JSON: { algorithm, params, salt }
+ *   <seal envelope>     rest of file: AES-256-GCM sealed envelope (cipher.ts)
+ *
+ * The magic string is chosen to be:
+ *   - ASCII-safe (no UTF-8 confusion)
+ *   - obviously non-JSON (won't parse as a JSON object)
+ *   - obviously non-gzip (gzip magic is 0x1f 0x8b; 'R' is 0x52)
+ *
+ * The sealed envelope format is documented in `cipher.ts`:
+ *   [VERSION:1][SALT:16][IV:12][AUTHTAG:16][CIPHERTEXT:...]
+ *
+ * The original gzip bytes are the ciphertext. There is no additional
+ * framing inside the ciphertext; decryption yields the original `.gz`
+ * bytes verbatim.
+ *
+ * AAD
+ * ---
+ * The file's basename (without the `.enc` suffix, as a UTF-8 buffer) is
+ * bound as AAD so the sealed envelope is tied to its filename. Renaming an
+ * encrypted capsule file causes auth-tag failure on open. This prevents a
+ * replay where an attacker substitutes one user's encrypted capsule for
+ * another's. Callers MUST supply the same basename on encrypt and decrypt.
+ *
+ * Cross-machine restore (Codex P1 / #690)
+ * ----------------------------------------
+ * Format v2 embeds the KDF params (algorithm + params + salt)
+ * in the archive header as a compact JSON blob. Any machine that knows the
+ * original passphrase can parse this blob and re-derive the exact same
+ * 256-bit AES key using the documented algorithm + params + salt — no
+ * out-of-band key material or access to the source machine's secure-store
+ * header is required. The keyring (in-memory unlocked key) is still used on
+ * the decrypt path when available (faster; avoids a re-derivation round).
+ */
+export interface EncryptCapsuleOptions {
+    /**
+     * Absolute path to the source `.capsule.json.gz` (or `.backup.tar.gz`)
+     * payload to encrypt.
+     */
+    sourceGzPath: string;
+    /**
+     * Absolute path to the memory directory whose secure-store keyring will
+     * be queried for the master key.
+     */
+    memoryDir: string;
+    /**
+     * Destination path for the encrypted output. If omitted, defaults to
+     * `sourceGzPath + ".enc"`.
+     */
+    outPath?: string;
+}
+export interface EncryptCapsuleResult {
+    /** Absolute path to the encrypted archive file. */
+    encPath: string;
+}
+export interface DecryptCapsuleOptions {
+    /**
+     * Absolute path to the `.enc` encrypted archive to decrypt.
+     */
+    encPath: string;
+    /**
+     * Absolute path to the memory directory whose secure-store keyring will
+     * be queried for the master key when no passphrase is supplied. Required
+     * for v1 archives, optional for v2 passphrase-based restores.
+     */
+    memoryDir?: string;
+    /**
+     * Original secure-store passphrase. For format-v2 archives this is used
+     * with the embedded KDF params to restore on a machine that does not have
+     * the source memory directory's unlocked keyring entry.
+     */
+    passphrase?: string;
+    /**
+     * Destination path for the decrypted output. If omitted, defaults to
+     * `encPath` with the `.enc` suffix removed.
+     */
+    outPath?: string;
+}
+export interface DecryptCapsuleResult {
+    /** Absolute path to the decrypted archive file. */
+    gzPath: string;
+}
+/**
+ * Return `true` iff the given file path ends with `.enc` AND its first bytes
+ * match the REMNIC-ENC magic header.
+ *
+ * Reads only the first `MAGIC.length` bytes of the file (open + partial read
+ * + close) so this is cheap enough to call on every import regardless of
+ * archive size. (Codex P2 / Cursor — previously read the entire file.)
+ *
+ * Throws only on I/O errors; returns `false` for files that are too short
+ * or whose magic does not match.
+ */
+export declare function isEncryptedCapsuleFile(filePath: string): Promise<boolean>;
+/**
+ * Encrypt a `.capsule.json.gz` (or `.backup.tar.gz`) payload using the
+ * secure-store master key held in the in-memory keyring for `memoryDir`.
+ *
+ * The key MUST already be unlocked in the keyring (`remnic secure-store
+ * unlock`). If the store is locked or has never been initialized, this
+ * function throws a clear error rather than silently producing an
+ * un-decryptable output.
+ *
+ * Format v2 embeds the KDF params (algorithm + params + salt) in the archive
+ * header so any machine that knows the original passphrase can re-derive the
+ * same key and decrypt the archive without access to the source machine's
+ * keyring. (Codex P1 — cross-machine restore.)
+ *
+ * Writes atomically: the output is assembled in memory and written in a
+ * single `writeFile` call so a crash mid-write cannot leave a partial file
+ * that passes the magic check but fails decryption (gotcha #54 — do not
+ * delete-before-write; here we write-new rather than replace, so no prior
+ * valid file can be destroyed).
+ */
+export declare function encryptCapsuleFile(opts: EncryptCapsuleOptions): Promise<EncryptCapsuleResult>;
+/**
+ * Decrypt a `.enc` encrypted capsule or backup archive.
+ *
+ * Validates the magic header and format version before attempting
+ * decryption. Throws with a clear message on:
+ *   - non-enc file / wrong magic
+ *   - unsupported format version
+   *   - locked/uninitialized secure-store (when keyring is not unlocked and no passphrase)
+ *   - wrong key / tampered ciphertext (AES-GCM auth failure)
+ *
+   * Format v2 archives carry embedded KDF params. If a `passphrase` is
+   * provided, the key is re-derived from the passphrase + embedded KDF params
+   * for cross-machine restore. Without a passphrase, an unlocked keyring key
+   * from `memoryDir` is used directly.
+ */
+export declare function decryptCapsuleFile(opts: DecryptCapsuleOptions): Promise<DecryptCapsuleResult>;
+/**
+ * Decrypt an encrypted capsule archive directly to a `Buffer` without writing
+ * an intermediate file. Used by `importCapsule` so the plaintext gzip bytes
+ * never touch disk during an in-memory import roundtrip.
+ *
+ * Semantics identical to {@link decryptCapsuleFile} except the output is
+ * returned as a `Buffer` rather than written to disk.
+ *
+ * Supports both format v1 (keyring-only) and format v2 (keyring preferred,
+ * passphrase re-derivation available for cross-machine restore).
+ */
+export declare function decryptCapsuleFileInMemory(encPath: string, memoryDir?: string, options?: {
+    passphrase?: string;
+}): Promise<Buffer>;
+//# sourceMappingURL=capsule-crypto.d.ts.map

package/dist/transfer/capsule-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule-crypto.d.ts","sourceRoot":"","sources":["../../src/transfer/capsule-crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AA8CH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgB/E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAkC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CA0D/B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACpC,OAAO,CAAC,MAAM,CAAC,CA8CjB"}

package/dist/transfer/capsule-export.d.ts

@@ -1,6 +1,4 @@
-import { CapsuleBlock, ExportManifestV2 } from './types.js';
-import 'zod';
-
+import { type CapsuleBlock, type ExportManifestV2 } from "./types.js";
 /**
  * Options accepted by {@link exportCapsule}.
  *
@@ -45,7 +43,7 @@ import 'zod';
  * `memoryDir` — required when `encrypt` is `true`. The memory directory whose
  * secure-store keyring holds the master key.
  */
-interface ExportCapsuleOptions {
+export interface ExportCapsuleOptions {
     name: string;
     root: string;
     since?: string;
@@ -77,7 +75,7 @@ interface ExportCapsuleOptions {
      */
     includeTranscripts?: boolean;
 }
-interface ExportCapsuleResult {
+export interface ExportCapsuleResult {
     archivePath: string;
     manifestPath: string;
     manifest: ExportManifestV2;
@@ -107,7 +105,6 @@ interface ExportCapsuleResult {
  * valid capsule and produces a well-formed manifest with an empty `files`
  * array and an archive containing the empty bundle.
  */
-declare function exportCapsule(opts: ExportCapsuleOptions): Promise<ExportCapsuleResult>;
-declare function isValidCapsuleSince(since: string): boolean;
-
-export { type ExportCapsuleOptions, type ExportCapsuleResult, exportCapsule, isValidCapsuleSince };
+export declare function exportCapsule(opts: ExportCapsuleOptions): Promise<ExportCapsuleResult>;
+export declare function isValidCapsuleSince(since: string): boolean;
+//# sourceMappingURL=capsule-export.d.ts.map

package/dist/transfer/capsule-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule-export.d.ts","sourceRoot":"","sources":["../../src/transfer/capsule-export.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,gBAAgB,EAEtB,MAAM,YAAY,CAAC;AAsBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,+EAA+E;IAC/E,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CA0H9B;AA8DD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAO1D"}

package/dist/transfer/capsule-export.js

@@ -1,9 +1,9 @@
 import {
   exportCapsule,
   isValidCapsuleSince
-} from "../chunk-VDX2J7OX.js";
+} from "../chunk-KQAFEZQX.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-X7Y7WX73.js";
 import "../chunk-J4EB7DNW.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";

package/dist/transfer/capsule-fork.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Capsule fork semantics — issue #676 PR 4/6.
+ *
+ * A fork takes an existing capsule archive, imports it into a target memory
+ * root under the `fork` conflict-resolution mode (which rebases all records
+ * under `forks/<capsule-id>/`), and then writes a lineage breadcrumb at
+ * `<targetRoot>/forks/<forkId>/lineage.json` recording the parent capsule's
+ * identity.  Subsequent forks of the same parent or of a fork produce a
+ * queryable chain.
+ *
+ * The lineage breadcrumb is a pure JSON file — no gzip, no bundle format —
+ * so downstream tooling can read it with a single `readFile` + `JSON.parse`
+ * without pulling in the transfer pipeline.
+ */
+import { type ImportCapsuleResult } from "./capsule-import.js";
+import type { CapsuleParent, ExportManifestV2 } from "./types.js";
+/**
+ * Options accepted by {@link forkCapsule}.
+ *
+ * `sourceArchive` — absolute or cwd-relative path to a `.capsule.json.gz`
+ * archive produced by `exportCapsule`.
+ *
+ * `targetRoot` — absolute or cwd-relative path to the memory directory that
+ * will receive the forked records. Must be an existing directory.
+ *
+ * `forkId` — user-chosen id for the fork.  Validated against
+ * {@link CAPSULE_ID_PATTERN}; must be unique under `<targetRoot>/forks/` (a
+ * pre-existing `forks/<forkId>/` directory is rejected before any write).
+ *
+ * `versioning` — optional page-versioning config forwarded to
+ * {@link importCapsule}. Only relevant when the target root already has files
+ * that would be overwritten (fork mode is skip-on-exist by design, so this is
+ * a no-op unless mode is changed in a future subclass).
+ *
+ * `now` — optional clock override (ms epoch) forwarded to `importCapsule` for
+ * deterministic fork-id rewriting in tests.
+ */
+export interface ForkCapsuleOptions {
+    sourceArchive: string;
+    targetRoot: string;
+    forkId: string;
+    now?: number;
+}
+/**
+ * The lineage breadcrumb written to `forks/<forkId>/lineage.json`.
+ *
+ * Fields are intentionally flat so the file is human-readable at a glance
+ * and trivially diffable by `git diff`.
+ *
+ * `forkId`          — the id supplied to `forkCapsule`.
+ * `forkedAt`        — ISO-8601 creation timestamp (UTC).
+ * `parent`          — structured linkage to the source capsule.
+ * `importedRecords` — number of records written by the fork import.
+ * `skippedRecords`  — number of records skipped (target already existed).
+ */
+export interface ForkLineage {
+    forkId: string;
+    forkedAt: string;
+    parent: CapsuleParent;
+    importedRecords: number;
+    skippedRecords: number;
+}
+export interface ForkCapsuleResult {
+    /** Absolute path to the source archive (unchanged, for chaining). */
+    archivePath: string;
+    /** The V2 manifest decoded from the source archive. */
+    manifest: ExportManifestV2;
+    /** Result of the underlying `importCapsule` call. */
+    importResult: ImportCapsuleResult;
+    /** The lineage breadcrumb that was written. */
+    lineage: ForkLineage;
+    /** Absolute path to the lineage breadcrumb file. */
+    lineagePath: string;
+}
+/**
+ * Fork a capsule archive into a target memory root.
+ *
+ * Sequence:
+ *   1. Validate `forkId` against {@link CAPSULE_ID_PATTERN}.
+ *   2. Resolve `targetRoot` and verify it is an existing directory (not a
+ *      symlink — mirrors {@link importCapsule}'s root validation).
+ *   3. Reject if `forks/<forkId>/` already exists in the target root
+ *      (gotcha #49: deduplicate batch inputs; gotcha #25: don't destroy
+ *      old state).
+ *   4. Import the archive in `"fork"` mode via {@link importCapsule}.
+ *   5. Write the lineage breadcrumb at `forks/<forkId>/lineage.json`.
+ *      The breadcrumb dir is created by step 4 (importCapsule writes records
+ *      under `forks/<sourceId>/`); if `forkId !== sourceId` we may need to
+ *      create the fork dir ourselves. We always `mkdir -p` defensively.
+ *
+ * Error semantics:
+ *   - All validation errors throw before any filesystem write (fail-closed,
+ *     gotcha #25).
+ *   - If `importCapsule` throws after writing some records, the lineage
+ *     breadcrumb is NOT written (partial state is better than a false
+ *     "fork complete" marker — gotcha #12: write rollback data before
+ *     success markers).
+ */
+export declare function forkCapsule(opts: ForkCapsuleOptions): Promise<ForkCapsuleResult>;
+/**
+ * Read the lineage breadcrumb for a given fork in a memory root.
+ *
+ * Returns `null` when no breadcrumb exists (the directory is not a fork, or
+ * was created before PR 4/6). Never throws for a missing file — callers
+ * that need to distinguish "not a fork" from "corrupt breadcrumb" should
+ * handle the JSON parse error themselves.
+ *
+ * `forkId` is validated against {@link CAPSULE_ID_PATTERN} before being
+ * joined into the breadcrumb path so a malicious value like
+ * `../../../../tmp` cannot escape the `forks/` namespace and resolve to
+ * unrelated files outside the configured memory root (Codex P2 #751).
+ * Invalid ids return `null` (same shape as "no breadcrumb"); callers that
+ * need to distinguish "invalid id" from "absent breadcrumb" should validate
+ * upstream.
+ */
+export declare function readForkLineage(targetRoot: string, forkId: string): Promise<ForkLineage | null>;
+//# sourceMappingURL=capsule-fork.d.ts.map

package/dist/transfer/capsule-fork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule-fork.d.ts","sourceRoot":"","sources":["../../src/transfer/capsule-fork.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE9E,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAOlE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,qDAAqD;IACrD,YAAY,EAAE,mBAAmB,CAAC;IAClC,+CAA+C;IAC/C,OAAO,EAAE,WAAW,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuGtF;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAuD7B"}

package/dist/transfer/capsule-import.d.ts

@@ -1,8 +1,5 @@
-import { VersioningConfig, VersioningLogger } from '../page-versioning.js';
-import { ExportManifestV2 } from './types.js';
-export { CapsuleBlock } from './types.js';
-import 'zod';
-
+import { type VersioningConfig, type VersioningLogger } from "../page-versioning.js";
+import { type CapsuleBlock, type ExportManifestV2 } from "./types.js";
 /**
  * Conflict-resolution mode for {@link importCapsule}. Inverse of the
  * `mode` selector in PR 4/6's CLI surface.
@@ -23,7 +20,7 @@ import 'zod';
  * in the bundle. Mixed-mode imports are not supported by design — that
  * would let a single corrupted manifest silently land partial state.
  */
-type ImportCapsuleMode = "skip" | "overwrite" | "fork";
+export type ImportCapsuleMode = "skip" | "overwrite" | "fork";
 /**
  * Options accepted by {@link importCapsule}.
  *
@@ -47,7 +44,7 @@ type ImportCapsuleMode = "skip" | "overwrite" | "fork";
  * `now` — optional clock override (ms epoch) used to derive deterministic
  * fork ids in tests. Production callers omit this.
  */
-interface ImportCapsuleOptions {
+export interface ImportCapsuleOptions {
     archivePath: string;
     root: string;
     mode?: ImportCapsuleMode;
@@ -71,7 +68,7 @@ interface ImportCapsuleOptions {
      */
     passphrase?: string;
 }
-interface ImportCapsuleSkippedRecord {
+export interface ImportCapsuleSkippedRecord {
     /** Original record path (capsule-relative, posix). */
     path: string;
     /**
@@ -86,7 +83,7 @@ interface ImportCapsuleSkippedRecord {
      */
     reason: "exists";
 }
-interface ImportCapsuleImportedRecord {
+export interface ImportCapsuleImportedRecord {
     /** Capsule-relative posix path the record carried. */
     sourcePath: string;
     /** Memory-dir-relative posix path the file was written to. */
@@ -96,7 +93,7 @@ interface ImportCapsuleImportedRecord {
     /** Whether the frontmatter `id:` field was rewritten (fork-mode only). */
     rewroteId: boolean;
 }
-interface ImportCapsuleResult {
+export interface ImportCapsuleResult {
     /** Records that landed on disk. */
     imported: ImportCapsuleImportedRecord[];
     /** Records that were not written. */
@@ -125,6 +122,6 @@ interface ImportCapsuleResult {
  *    locations (subsequent fork imports still skip-on-exist because the
  *    target tree is computed from the source path).
  */
-declare function importCapsule(opts: ImportCapsuleOptions): Promise<ImportCapsuleResult>;
-
-export { type ImportCapsuleImportedRecord, type ImportCapsuleMode, type ImportCapsuleOptions, type ImportCapsuleResult, type ImportCapsuleSkippedRecord, importCapsule };
+export declare function importCapsule(opts: ImportCapsuleOptions): Promise<ImportCapsuleResult>;
+export type { CapsuleBlock };
+//# sourceMappingURL=capsule-import.d.ts.map

package/dist/transfer/capsule-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule-import.d.ts","sourceRoot":"","sources":["../../src/transfer/capsule-import.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAEtB,MAAM,YAAY,CAAC;AAGpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;OASG;IACH,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,WAAW,EAAE,OAAO,CAAC;IACrB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,QAAQ,EAAE,2BAA2B,EAAE,CAAC;IACxC,qCAAqC;IACrC,OAAO,EAAE,0BAA0B,EAAE,CAAC;IACtC,6CAA6C;IAC7C,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CA6Y9B;AAyHD,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/transfer/capsule-import.js

@@ -1,6 +1,6 @@
 import {
   importCapsule
-} from "../chunk-VVX5PZFS.js";
+} from "../chunk-ZHXSOMYH.js";
 import "../chunk-JPKK466T.js";
 import "../chunk-XCB6QDL6.js";
 import "../chunk-RBOJCG4T.js";
@@ -10,7 +10,7 @@ import "../chunk-6CIAGZ6X.js";
 import "../chunk-C64XATK7.js";
 import "../chunk-42JKGUFJ.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-X7Y7WX73.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";