@sema-agent/core 7.15.0 → 7.17.0

package/dist/core/memory-engine/layout.d.ts

@@ -1,4 +1,5 @@
 import { type MemoryAnnouncement } from "./types.js";
+import type { AssertAllKeysHandled } from "../ask-origin.js";
 /** Cursor sidecar for the design/84 Seam B pair on the FileBackend (`{ [scope]: cursor }`). B3: control plane. */
 export declare const CURSORS_FILE = "cursors.json";
 /** The control-plane subdir name under a key dir — ONE spelling for every derivation and for the
@@ -127,41 +128,126 @@ export declare function scopeDirName(scope: string): string;
  * Exported for the layout pins; not part of the package surface.
  */
 export declare function dirCaseFolds(dir: string): boolean | undefined;
-/** Which scope owns the memory dir ROOT (undefined = unclaimed). */
-export declare function rootScopeOf(controlDir: string): string | undefined;
-/**
- * Claim the memory dir root for `scope` iff unclaimed (idempotent, first-writer-wins, durable).
- * Returns the (possibly pre-existing) root owner. Lock-serialized (独立轨 F5): two first-users of a
- * shared mount race the claim under the sidecar lock — exactly one wins, the other SEES the winner.
- */
-export declare function claimRootScope(controlDir: string, scope: string): string;
-/** Register `scope` in the durable registry (idempotent) and return its home dir under `memoryDir`.
- *  H5 fail-closed: a dir-name collision with a DIFFERENT registered scope throws — two scopes must
- *  never share one directory (silent cross-scope merge). The collision test has TWO arms:
- *   - exact: two scopes whose labels are the SAME string (hash collision / caller-declared registry);
- *   - case-fold (2026-08-12): two labels differing ONLY in letter case are distinct strings to this
- *     registry yet ONE physical directory on a case-folding volume — cross-scope bleed the exact arm
- *     cannot see. The fold arm compares the FINAL dir labels (ASCII by construction, so toLowerCase
- *     is an exact fold) and only fires when the volume actually folds — probed lazily on a fold-equal
- *     candidate ({@link dirCaseFolds}), so the no-collision path never pays the probe and a
- *     case-SENSITIVE volume keeps hosting case-differing scope pairs as the genuinely distinct
- *     directories they are there. An UNPROBEABLE volume (neither probe leg answers) refuses the
- *     fold-equal pair too — an unresolved semantics guess would fail open exactly where the guard
- *     is needed. `opts.caseFoldingFs` overrides the probe for callers (and pins) that already
- *     measured the volume's semantics. The scope→dir MAPPING itself is unchanged on purpose:
- *     folding scopeDirName would re-home every existing mixed-case scope's directory.
- *  Both arms compare the scope's EFFECTIVE label — the registered one when present (a registered
- *  scope's home NEVER moves; entries live there), the formula only for a never-registered scope —
- *  so a registry whose stored labels drifted from the current formula is judged by the directories
- *  it actually serves, not by labels nobody uses. Lock-serialized (独立轨 F5). */
+/** The closure of every label {@link scopeDirName} can mint: a safe-form scope verbatim, or the
+ *  folded form (leading `.`/`-` stripped) plus a hash suffix. One non-hidden path segment — never
+ *  empty, never `.`/`..`, never a separator — so two labels are two distinct directory entries. */
+export declare const SCOPE_DIR_LABEL_RE: RegExp;
+/** Prefix of the case-fold probe files the layout leaves (briefly) at a memory root. One spelling
+ *  for the probe writer and for the migration's residue removal. */
+export declare const CASEFOLD_PROBE_PREFIX = ".casefold-probe-";
+/** The four shapes a scope registry read can take. */
+export declare const SCOPE_REGISTRY_SHAPES: readonly ["absent", "v1", "v2", "migrating"];
+export type ScopeRegistryShape = (typeof SCOPE_REGISTRY_SHAPES)[number];
+/** Which shapes the path-deriving read faces (`registerScope` / `scopeDirFor` / `registeredScopes`)
+ *  may serve. `v1` (the pre-v2 file: a root-owning scope, `""` labels) and `migrating` (a v2 file
+ *  carrying an unfinished move marker) are refused fail-closed: the registry then does not describe
+ *  where entries physically live until {@link adoptRootScopeLayout} has run to completion. */
+export declare const REGISTRY_SHAPE_DERIVES_PATHS: {
+    readonly absent: true;
+    readonly v1: false;
+    readonly v2: true;
+    readonly migrating: false;
+};
+export type DerivesPathsTableCoversEveryRegistryShape = AssertAllKeysHandled<Exclude<ScopeRegistryShape, keyof typeof REGISTRY_SHAPE_DERIVES_PATHS>>;
+/** The unfinished-move marker: the physical root whose loose content is being moved into
+ *  `<root>/<label>` for `owner`. Durable across crashes; whoever holds the registry lock next
+ *  finishes it before doing anything else. */
+export interface ScopeLayoutMigratingMarker {
+    root: string;
+    owner: string;
+    label: string;
+}
+/** The v2 registry record. `rootOwner` is the scope that historically owned the memory root; it is
+ *  consulted only to attribute loose root content during adoption and never derives a path. */
+export interface ScopesRecordV2 {
+    v: 2;
+    scopes: Record<string, string>;
+    rootOwner?: string;
+    migrating?: ScopeLayoutMigratingMarker;
+}
+/** A parsed registry, tagged by shape. `v1` keeps the pre-v2 fields for the one-time conversion. */
+export type ScopeRegistryRead = {
+    shape: "absent";
+    rec: ScopesRecordV2;
+} | {
+    shape: "v1";
+    rootScope?: string;
+    scopes: Record<string, string>;
+} | {
+    shape: "v2";
+    rec: ScopesRecordV2;
+} | {
+    shape: "migrating";
+    rec: ScopesRecordV2 & {
+        migrating: ScopeLayoutMigratingMarker;
+    };
+};
+/** Register `scope` in the durable registry (idempotent) and return its home `<memoryDir>/<label>`.
+ *  The registered label is the truth for a scope that has one (a home never moves); the
+ *  {@link scopeDirName} formula mints the label for a never-registered scope. Both collision arms
+ *  run over the effective labels; the home is created on first registration and its physical form
+ *  is proven on every call. Lock-serialized; a `v1`/`migrating` registry is refused. */
 export declare function registerScope(memoryDir: string, controlDir: string, scope: string, opts?: {
     caseFoldingFs?: boolean;
 }): string;
-/** All registered scopes → home dir name (`""` = the root). */
+/** All registered scopes → label. A `v1`/`migrating` registry is refused. */
 export declare function registeredScopes(controlDir: string): Record<string, string>;
-/** The stable home directory of `scope`'s entry files: the root when it owns the root, else the
- *  REGISTERED subdir (falls back to the {@link scopeDirName} formula for a never-registered scope). */
+/** The stable home directory of `scope`'s entry files: `<memoryDir>/<label>`, the REGISTERED label
+ *  when there is one, the formula otherwise. Registers nothing. A `v1`/`migrating` registry is refused. */
 export declare function scopeDirFor(memoryDir: string, controlDir: string, scope: string): string;
+/** The scope registry's shape as it stands on disk (lock-free, journal-aware). Exported for the
+ *  backend's cheap pre-check and for the layout pins; not part of the package surface. */
+export declare function scopeRegistryShape(controlDir: string): ScopeRegistryShape;
+/** The v1 path-key resolver (design A6): maps a memory-dir-relative persistent key written under the
+ *  root-owning layout onto the ledger form `(scope, rel)`. The first segment names a registered
+ *  non-owner label ⇒ that scope's home; otherwise the key belonged to the root owner. `undefined`
+ *  when the row cannot be attributed (no root owner on record) — the caller keeps the row in its
+ *  old form and refuses the operations that depend on it. Reads any registry shape (the conversion
+ *  is independent of the physical move). */
+export declare function v1MemoryPathKeyResolver(controlDir: string): (relPath: string) => {
+    scope: string;
+    rel: string;
+} | undefined;
+/** Options of {@link adoptRootScopeLayout}. `ownerCandidate` attributes loose root content when the
+ *  registry records no root owner (the mount's write scope / a standalone batch's first add scope).
+ *  `renew` is the caller's outer-lock heartbeat (the backend's transaction lock) — called before
+ *  every filesystem action and every sidecar write, together with the registry lock's own. */
+export interface AdoptRootScopeLayoutOptions {
+    ownerCandidate?: string | null;
+    onIncident?: MemoryPartitionIncidentSink;
+    renew?: () => void;
+    /** The one-time v1 sidecar key conversions, run in the adoption (before any later scope
+     *  registration can change what a v1 key's first segment names). Each conversion is idempotent
+     *  and takes its own sidecar lock. */
+    convertSidecars?: (controlDir: string) => void;
+}
+/** The lock-free pre-check the backend's public faces ask before a registry-derived path: does the
+ *  tree at `root` still need the adoption (a v1/migrating registry, or loose content at the root)?
+ *  One journal-aware registry read plus one readdir; the adoption re-enumerates under the locks. */
+export declare function layoutNeedsAdoption(root: string, controlDir: string): boolean;
+/**
+ * Adopt the per-scope layout for the physical tree at `root` (the engine's memory dir, or the
+ * backend's directory root; both when they differ — they share one control plane, so the registry
+ * conversion happens once). Runs under the registry lock; the caller holds any outer lock. Every
+ * step is idempotent and the two-phase marker makes an interrupted move resumable by whoever holds
+ * the lock next:
+ *   0. registry shape: `absent` ⇒ an empty v2 record; `v1` ⇒ v2 with `rootOwner` = the old
+ *      `rootScope` (the root owner is also given its label); `migrating` ⇒ that move is finished
+ *      FIRST, whichever tree it names. The root's loose content is enumerated on every call — a v2
+ *      registry proves nothing about THIS tree.
+ *   1. loose content ⇒ owner = `rootOwner ?? ownerCandidate`; neither ⇒ `memory.layout_unowned_root_content`
+ *      (names capped), registry converted, nothing moved.
+ *   2. pre-checks, zero writes: the control plane inside the root; the owner's home a link/file, or
+ *      a real non-empty directory without a marker for it; any loose name already present in the
+ *      home — each refuses with {@link ControlPlaneCorruptError}.
+ *   3. commit A: the v2 record with the owner registered, `rootOwner`, and the `migrating` marker.
+ *   4. move: per entry, lstat the destination (absent ⇒ rename; present ⇒ refuse; source gone ⇒
+ *      already moved); probe residue removed. No sidecar key and no index text is rewritten (the
+ *      ledger form keys are location-free; the index heals through its rebuild law).
+ *   5. `index-revs.json` cleared (fail-open snapshot; the next rebuild keeps model wording once).
+ *   6. commit B: the marker removed; `memory.layout_migrated` disclosed.
+ */
+export declare function adoptRootScopeLayout(rootPath: string, controlDir: string, opts?: AdoptRootScopeLayoutOptions): void;
 /** Canonicalize a path for containment checks (resolves symlinks on the EXISTING prefix). */
 export declare function canonicalize(p: string): string;
 /** True iff `child` (canonicalized) is `root` or inside it. */
@@ -297,7 +383,10 @@ export declare function enqueueMemoryAnnouncement(controlDir: string, ann: Memor
 export declare function drainMemoryAnnouncements(controlDir: string): AnnouncementsRecord;
 /** Test/observability peek (journal-aware, non-destructive). */
 export declare function peekMemoryAnnouncements(controlDir: string): AnnouncementsRecord;
-/** S2-C — record one write-time scan rejection for `key` (canonical file path); returns the count
+/** The fuse key for a memory file: the ledger form `(scope, rel)` (`rel` relative to the scope's
+ *  home, `/`-separated) — location-free, so a home move never re-keys a count. */
+export declare function scanFuseKey(scope: string, rel: string): string;
+/** S2-C — record one write-time scan rejection for `key` ({@link scanFuseKey}); returns the count
  *  BEFORE this bump (callers mute the feedback when it is already ≥ {@link SCAN_FUSE_THRESHOLD}). */
 export declare function bumpScanFuse(controlDir: string, key: string): number;
 export declare function readIndexRevs(controlDir: string): Record<string, string>;
@@ -816,48 +905,57 @@ export declare function recordChallengedHistory(controlDir: string, rows: Readon
 /** Journal-aware read (observability/tests only — no engine consumer exists, on purpose). */
 export declare function readChallengedHistory(controlDir: string): Record<string, ChallengedHistoryRow>;
 export declare const PROJECTION_DEBTS_FILE = "projection-debts.json";
-/** One standing debt: the plane file at `relPath` (memory-dir-relative, canonical base) belongs to
- *  committed entry `entryId`, whose id write-back has not landed; `rev` is the rev the projection
- *  was staged against (the CAS baseline a reconciling harvest hands its update). */
+/** One standing debt: the plane file at `(scope, rel)` — `rel` relative to the scope's home,
+ *  `/`-separated — belongs to committed entry `entryId`, whose id write-back has not landed; `rev`
+ *  is the rev the projection was staged against (the CAS baseline a reconciling harvest hands its
+ *  update). The key is the ledger form: location-free, so a home move never re-keys a row. */
 export interface ProjectionDebtRow {
-    relPath: string;
+    scope: string;
+    rel: string;
     entryId: string;
     rev: string;
     at: number;
 }
-/** WRITE-AHEAD staging. Upsert discipline (adversarial round 2): a stage lands only when the seat
- *  has NO standing row, the standing row is the stager's OWN entry (a rev refresh), or the
- *  standing row is the entry the stager itself just judged stale (`replaces` — the same-harvest
- *  stale-then-remint lane). It never blindly replaces ANOTHER writer's protection: a lagging
- *  process that validated an old row before pausing must not overwrite the row a faster sibling
- *  staged at the same path (its own commit then CAS-conflicts and its tuple-keyed clear misses
- *  the survivor — the account converges instead of emptying). Called before the backend
- *  transaction; the caller degrades LOUDLY (report warning) on a refused stage rather than
- *  refusing the harvest — the ledger is duplicate-admission protection, not the commit's
- *  integrity. */
+/** WRITE-AHEAD staging. Upsert discipline: a stage lands only when the seat has NO standing row,
+ *  the standing row is the stager's OWN entry (a rev refresh), or the standing row is the entry the
+ *  stager itself just judged stale (`replaces` — the same-harvest stale-then-remint lane). It never
+ *  blindly replaces ANOTHER writer's protection: a lagging process that validated an old row before
+ *  pausing must not overwrite the row a faster sibling staged at the same seat (its own commit then
+ *  CAS-conflicts and its tuple-keyed clear misses the survivor — the account converges instead of
+ *  emptying). Called before the backend transaction; the caller degrades LOUDLY (report warning)
+ *  on a refused stage rather than refusing the harvest — the ledger is duplicate-admission
+ *  protection, not the commit's integrity. */
 export declare function stageProjectionDebts(controlDir: string, rows: ReadonlyArray<{
-    relPath: string;
+    scope: string;
+    rel: string;
     entryId: string;
     rev: string;
     replaces?: string;
 }>, now: () => number): {
     refused: Array<{
-        relPath: string;
+        scope: string;
+        rel: string;
         entryId: string;
     }>;
 };
-/** Settle (remove) rows by ROW IDENTITY — (relPath, entryId), never the bare path: the write-back
+/** Settle (remove) rows by ROW IDENTITY — (scope, rel, entryId), never the bare seat: the write-back
  *  landed, the staged claim turned out stale, or a materialize re-projected the seat. Identity
- *  matters (adversarial review F1): a stale-clear judged against an OLD row must not delete the
- *  NEWER row a later staging upserted at the same path (same harvest: stale X cleared while fresh
- *  Y's write-back failed — a path-keyed drop would erase Y and re-open the duplicate window; same
- *  shape across processes for a lagging sibling's clear). Missing rows are a no-op (idempotent). */
+ *  matters: a stale-clear judged against an OLD row must not delete the NEWER row a later staging
+ *  upserted at the same seat. Missing rows are a no-op (idempotent). */
 export declare function settleProjectionDebts(controlDir: string, rows: ReadonlyArray<{
-    relPath: string;
+    scope: string;
+    rel: string;
     entryId: string;
 }>): void;
-/** Strict read (ENOENT ⇒ empty; corrupt ⇒ throws — the caller's fail-closed arm owns the refusal). */
+/** Strict read (ENOENT ⇒ empty; corrupt ⇒ throws — the caller's fail-closed arm owns the refusal).
+ *  A v1 record is converted in the ledger's lock on this first read. Rows the registry
+ *  could not attribute stay on the record's `unresolved` seat and are not served. */
 export declare function readProjectionDebts(controlDir: string): ProjectionDebtRow[];
+/** The rows a key-form conversion could not attribute (audit read; empty on a converted ledger). */
+export declare function unresolvedProjectionDebts(controlDir: string): Array<{
+    relPath: string;
+    entryId: string;
+}>;
 /**
  * REF-C6 — write EVERY byte of `data` to `fd`, looping until the OS has taken all of them.
  *