@sema-agent/core 7.54.1 → 7.55.0

package/dist/stores/file/file-history-store.d.ts

@@ -1,5 +1,5 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
-import { type FileHistoryDiffStats, type FileHistoryExport, type FileHistoryResult, type FileHistoryRestoreResult, type FileHistoryStore, type FileHistoryTrackResult } from "../../core/file-history-store.js";
+import { type FileHistoryDiffStats, type FileHistoryExport, type FileHistoryExportResult, type FileHistoryResult, type FileHistoryRestoreResult, type FileHistoryStore, type FileHistoryTrackResult } from "../../core/file-history-store.js";
 import { type FileHistoryRetentionPolicy } from "../../core/file-history-retention.js";
 import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 /**
@@ -254,7 +254,11 @@ export declare class FileFileHistoryStore implements FileHistoryStore {
     /** Replace a scope's tracked set in ONE atomic step (the DV-14 "one atomic durable record" and
      *  the version-chain commit both ride this). */
     private writeTracked;
+    /** A boundary's mapping, or `null` for "no usable boundary here" — the projection most readers want. */
     private readBoundary;
+    /** The one boundary reader: the mapping; `null` = absent; a fault = a file that is there but cannot be
+     *  used (unreadable ⇒ the caught error's judgment, damaged ⇒ terminal). */
+    private readBoundaryState;
     /**
      * A committed boundary's own publication stamp ({@link BoundaryJson.committedAt}), or `undefined`
      * when the record predates the field, came from an import, or cannot be read. Callers treat
@@ -275,13 +279,6 @@ export declare class FileFileHistoryStore implements FileHistoryStore {
      * about the ledger). A fork is the source's history continued under a new name, so an id the
      * source spent must not become mintable there.
      */
-    /**
-     * The boundary ids in `scope` that exist on disk but cannot be judged — `null` means the whole set
-     * is judgeable and safe to reason about. A directory that cannot be LISTED answers with an empty
-     * array rather than `null`, because "I cannot see them" and "I saw them and they are fine" must
-     * not be the same answer; ENOENT (no boundaries yet) is genuinely the second.
-     */
-    private unjudgeableBoundaryIdsOf;
     private carryConsumedIds;
     /**
      * The consumed-id ledger's path — a SIBLING of the scope directory, deliberately NOT a file inside
@@ -298,8 +295,8 @@ export declare class FileFileHistoryStore implements FileHistoryStore {
      */
     private reapedLogPath;
     /**
-     * The scope's consumed ids, cached by log size (see {@link reapedCache}). `null` = the log EXISTS
-     * but could not be read: a state where this store cannot tell a fresh entryId from a spent one, and
+     * The scope's consumed ids, cached by log size (see {@link reapedCache}). A {@link FileHistoryFault} = the log
+     * EXISTS but could not be read: a state where this store cannot tell a fresh entryId from a spent one, and
      * the callers below take the fail-CLOSED arm rather than guess — refusing a boundary is a turn that
      * cannot be rewound to, while guessing wrong is post-turn bytes published under a pre-turn key.
      */
@@ -323,22 +320,26 @@ export declare class FileFileHistoryStore implements FileHistoryStore {
      * imports that both believed it would each delete the other's freshly published graph.
      */
     private scopeIsEmptySync;
+    /** The import door's ONE reading of its target, before any blob is fetched and again after: the emptiness judge
+     *  above (so an unjudgeable target is refused as what it is), and — only over a readable, non-empty target — the
+     *  export digest, which tells the identical envelope (an idempotent re-publish) from a DIFFERENT history. */
+    private importTargetOf;
     /**
      * The ONE-STEP publish shared by adoptScope and importHistory: verify emptiness and swap the
      * staged directory into place with NOTHING awaited in between, so the whole claim-and-publish is
      * atomic against any other in-flight publish in this process.
      *
      * THREE answers, not two (A-082 rescan): `"published"`, `"not_empty"` (the target stopped being
-     * empty — the caller's typed `conflict`), and `"ledger_failed"` (the tombstones for the residue
-     * this publish destroys could not be written). The second failure arrived with the tombstone write
-     * below and rode the same `false` as the first, so both callers dressed an IO fault as the one
-     * code the engine's fork-carry seat is contractually silent about — the exact silence the
-     * `conflict`/`adopt_failed` split was introduced to close, re-opened one door over (and its message
-     * asserted a fact that was not true: the target had gained nothing). They are separate answers now.
+     * empty — the caller's typed `conflict`), and what made the target unjudgeable, with its fault — never
+     * the one code the engine's fork-carry seat is contractually silent about. "Empty" holds no boundary
+     * file at all (one that cannot be used is a fault, see {@link listBoundaryIds}), so the removal below
+     * destroys no id: the scope's already-spent ids live in the SIBLING ledger ({@link reapedLogPath}).
      */
     private publishStagedScopeSync;
-    /** Committed boundary ids in a scope (a corrupt boundary is NOT listed — the listing agrees with
-     *  canRestore/restore, so a half-readable directory never looks like more history than it serves). */
+    /** The scope's boundary ids — the ONE reading of "which boundaries does this scope have" for every judge that
+     *  reasons about the set (an adoption's source and target, a retraction, an export). A boundary file that cannot
+     *  be used, or a directory that cannot be listed, answers what it is with its fault, never "not there":
+     *  unreadable ≠ empty (a file gone since the listing cannot be judged either). ENOENT is no boundary yet. */
     private listBoundaryIds;
     snapshot(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryResult>;
     restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryRestoreResult>;
@@ -356,7 +357,7 @@ export declare class FileFileHistoryStore implements FileHistoryStore {
      */
     private collectBlobs;
     adoptScope(fromScope: string, toScope: string): Promise<FileHistoryResult>;
-    exportHistory(scope: string): Promise<FileHistoryExport | null>;
+    exportHistory(scope: string): Promise<FileHistoryExportResult>;
     importHistory(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
     /** The import's body, so EVERY exit (typed refusal, thrown fault, success) passes one `finally`
      *  that releases the journal + lease — an early return used to leak both, and a leaked lease is