@sema-agent/core 7.68.1 → 7.68.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/dist/agents/repair-loop.js +1 -1
  3. package/dist/agents/verify.js +1 -1
  4. package/dist/core/engine-capabilities.d.ts +8 -1
  5. package/dist/core/engine-capabilities.js +1 -1
  6. package/dist/core/file-history-store.d.ts +229 -44
  7. package/dist/core/file-history-store.js +288 -93
  8. package/dist/core/runner/contracts.d.ts +1 -1
  9. package/dist/core/runner/file-history-request.d.ts +10 -2
  10. package/dist/core/runner/file-history-request.js +17 -1
  11. package/dist/core/runner/file-history-restore.d.ts +11 -4
  12. package/dist/core/runner/file-history-restore.js +19 -5
  13. package/dist/core/runner/prepare-file-history.js +3 -3
  14. package/dist/core/runner/rewind-files.js +11 -8
  15. package/dist/core/store-contracts/file-history-store-contract.js +210 -13
  16. package/dist/core/task-spec-members.d.ts +31 -18
  17. package/dist/core/task-spec-members.js +11 -8
  18. package/dist/core/task-spec.d.ts +7 -0
  19. package/dist/index.d.ts +2 -0
  20. package/dist/index.js +1 -0
  21. package/dist/orchestration/goal.js +3 -1
  22. package/dist/stores/file/file-history-store.d.ts +5 -3
  23. package/dist/stores/file/file-history-store.js +42 -60
  24. package/package.json +2 -2
  25. package/test/export-surface.snapshot.json +17 -1
  26. package/wire-changes/core-stores-sql@7.68.2.json +39 -0
  27. package/wire-changes/core-stores-sql@7.68.3.json +39 -0
  28. package/wire-changes/core@7.68.2.json +612 -0
  29. package/wire-changes/core@7.68.3.json +125 -0
  30. package/wire-changes/mods-kernel@7.68.2.json +39 -0
  31. package/wire-changes/mods-kernel@7.68.3.json +39 -0
  32. package/wire-changes/primitives@7.68.2.json +39 -0
  33. package/wire-changes/primitives@7.68.3.json +39 -0
  34. package/wire-changes/wiki-gate@7.68.2.json +39 -0
  35. package/wire-changes/wiki-gate@7.68.3.json +39 -0
@@ -30,11 +30,18 @@ export type FileHistoryTrackKeyResolution = {
30
30
  * · `base_unavailable` — the first touch recorded that the path's pre-edit bytes could not be read (DV-14),
31
31
  * so there is no pristine version to write;
32
32
  * · `key_unresolvable` — the recorded key cannot be re-joined against this root (it would escape it, or it
33
- * came from another path family and is absolute or ambiguous here).
33
+ * came from another path family and is absolute or ambiguous here);
34
+ * · `recorded_elsewhere` — the version was recorded under another directory than the one this rewind would write
35
+ * or delete in (its place, {@link placeOfParentViaEnv}: a later leg handed another root, a fork handed another
36
+ * root, a history carried or cascaded from another session); the row's `recordedUnder` names that directory;
37
+ * · `place_unrecorded` — the version records no place (it was recorded before places were kept, by a store that
38
+ * does not keep them, or it was imported: a place never crosses the export door), so where it belongs cannot be
39
+ * told; a host that knows where such versions were recorded names it on the rewind (`unplacedHistoryRecordedUnder`).
34
40
  * Damage to the store's own records (a missing version record, a missing or corrupt blob) is not a refusal
35
- * in any backend: it is a `failed` row.
41
+ * in any backend: it is a `failed` row. A consumer reads the class as an OPEN set (a later release may add a word)
42
+ * and branches on it, never on the reason text.
36
43
  */
37
- export declare const FILE_HISTORY_REFUSAL_CLASSES: readonly ["link_safety", "base_unavailable", "key_unresolvable"];
44
+ export declare const FILE_HISTORY_REFUSAL_CLASSES: readonly ["link_safety", "base_unavailable", "key_unresolvable", "recorded_elsewhere", "place_unrecorded"];
38
45
  export type FileHistoryRefusalClass = (typeof FILE_HISTORY_REFUSAL_CLASSES)[number];
39
46
  /** The path family a track key was MINTED under — the half a bare key string cannot carry. */
40
47
  export type FileHistoryKeyFamily = "posix" | "win";
@@ -50,6 +57,24 @@ export interface FileHistoryTrackKeyDescriptor {
50
57
  kind: "root-relative" | "absolute";
51
58
  family: FileHistoryKeyFamily;
52
59
  }
60
+ /**
61
+ * Whether an entry travels with its history into another session: a fork's or a deletion cascade's carry (`adoptScope`) and an
62
+ * export (`exportHistory`) take only the entries under a ROOT-RELATIVE key. An absolute-key entry is a file this session edited
63
+ * outside its root, or a second file whose root-relative name another directory's file already keys; carried, it would restore
64
+ * the source's file where the source still works, and an import door refuses it. So, carried and imported histories aside, an
65
+ * absolute key in a history is that session's own edit. **Exported under the "MUST reuse" clause**: a backend that carries or
66
+ * exports an absolute-key entry keeps the write into the source's file.
67
+ */
68
+ export declare function fileHistoryEntryTravels(key: FileHistoryTrackKeyDescriptor): boolean;
69
+ /**
70
+ * Whether a version's recorded `parentIdent` travels with an exported history. A place (an absolute path: the directory the
71
+ * version was recorded under) does not — it names a directory on the machine that recorded it, a boundary re-reads a tracked
72
+ * file at its place, and so an import door refuses an envelope that carries one, exactly as it refuses an absolute key. The
73
+ * root-relative form an older engine recorded travels (no engine reads it as a place). **Exported under the "MUST reuse"
74
+ * clause**: a backend's export leaves out every `parentIdent` this answers `false` for, or the importing door refuses its
75
+ * envelope whole.
76
+ */
77
+ export declare function fileHistoryParentIdentTravels(parentIdent: string): boolean;
53
78
  /** The family of a root — the one place a backend asks "which family am I operating in?". */
54
79
  export declare function trackKeyFamilyOf(root: string): FileHistoryKeyFamily;
55
80
  /**
@@ -62,8 +87,9 @@ export declare function describeTrackKey(root: string, absPath: string): {
62
87
  } & FileHistoryTrackKeyDescriptor;
63
88
  /**
64
89
  * Track-key coordinate (design/381 DV-6, the CC `wZu` relativization ported to the trusted task
65
- * root): a path under `root` is recorded root-RELATIVE (worktree/moved-root safe — restore re-joins
66
- * it against the CURRENT root), a path outside `root` is recorded verbatim-absolute.
90
+ * root): a path under `root` is recorded root-RELATIVE (a restore re-joins it on the leg's root, and
91
+ * writes there only when that is the place the version records), a path outside `root` is recorded
92
+ * verbatim-absolute.
67
93
  *
68
94
  * **Exported as part of the "MUST reuse, NOT re-implement" set** (A-082 idx5, the same §3 分工
69
95
  * clause that governs the two env halves): every backend mints keys from the `(absPath, root)` pair
@@ -198,11 +224,16 @@ export type FileHistoryRestoreResult = {
198
224
  /** Track keys already equal to the target (untouched — content-hash proven, never mtime). */
199
225
  identicalSkipped: string[];
200
226
  /** Per-file security/consistency refusals (skipped, counted, never failing the whole restore); `class` is
201
- * the closed reading of why ({@link FileHistoryRefusalClass}), `reason` the sentence for a person. */
227
+ * the reading of why ({@link FileHistoryRefusalClass}), `reason` the sentence for a person (a consumer branches on
228
+ * `class` only). `recordedUnder` — on a `recorded_elsewhere` row — is the directory the version was recorded under, its
229
+ * absolute real path (where a person goes to rewind it); `action` is what the restore would have done there. A store
230
+ * that does not pass them through answers the row without them. */
202
231
  refused: Array<{
203
232
  path: string;
204
233
  reason: string;
205
234
  class: FileHistoryRefusalClass;
235
+ recordedUnder?: string;
236
+ action?: "write" | "delete";
206
237
  }>;
207
238
  /** Per-file operational failures (env write/remove errors, aborts after k writes). */
208
239
  failed: Array<{
@@ -213,11 +244,58 @@ export type FileHistoryRestoreResult = {
213
244
  modeNotPreserved?: number;
214
245
  /** Present on outcome:"failed" (operation-level cause) and optionally on "partial". */
215
246
  error?: FileHistoryError;
247
+ /** Every file the restore wrote, deleted or refused, one row each ({@link FileHistoryRewindFile}) — minted by the engine
248
+ * (`Runner.rewindFiles`, a run's restore) from what the restore did, never by a store. Absent = an engine that does not
249
+ * answer per-file facts (an older one), which is not "nothing was refused". */
250
+ files?: FileHistoryRewindFile[];
216
251
  };
252
+ /**
253
+ * One file of a rewind, as the engine answers it beside the counts and lists (`files` on a preview and on a restore): `path`
254
+ * is the key the history records the file under — its name relative to the root it was recorded against, or its absolute
255
+ * path when that relative name was already the key of a file at another place; `targetPath` is the absolute path THIS rewind
256
+ * writes or deletes for it (the key joined on this leg's root; an absolute key is its own) — on a refused row, where it would
257
+ * have landed, which is the other half of why it was refused (`refused.recordedUnder` is the first half). `filesChanged`,
258
+ * `refused` and `failed` stay as they are; `files` is the same rewind file by file.
259
+ */
260
+ export interface FileHistoryRewindFile {
261
+ path: string;
262
+ targetPath: string;
263
+ /** What the rewind does at `targetPath`; on a refused row, what it would have done (absent when the store did not say). */
264
+ action?: "write" | "delete";
265
+ refused?: {
266
+ class: FileHistoryRefusalClass;
267
+ reason: string;
268
+ recordedUnder?: string;
269
+ };
270
+ /** A file the restore wrote or deleted (`action`) that the store then answered as failed (its `failed` row's reason): the
271
+ * write landed, so it is named here. */
272
+ failed?: {
273
+ reason: string;
274
+ };
275
+ }
276
+ /** What a rewind tells the restore beyond its coordinates ({@link FileHistoryStore.restore}'s last argument). */
277
+ export interface FileHistoryRestoreOptions {
278
+ /**
279
+ * The directory this session's OLDER versions were recorded under — the ones that record no place (recorded before
280
+ * places were kept). Given, such a version is read as recorded at this directory plus the parent it names relative to
281
+ * its root, and goes through the same comparison as every other version: converged only where this rewind lands it,
282
+ * else refused `recorded_elsewhere`. Not given, it is refused `place_unrecorded`. A version that records its place never
283
+ * reads it. An absolute path, read in the rewind's env (its real path), stated by a host that knows where the session's
284
+ * legs ran before (a transcript that stamps each turn's directory) — not a promise, a fact of the same standing as the
285
+ * root the host hands a leg. It asserts where THIS HISTORY was recorded: filled with the current leg's root by default
286
+ * while the history was recorded elsewhere, it writes the older versions by relative key at the current root — the very
287
+ * shape the recorded place exists to refuse. A directory that no longer exists is a legitimate answer (it was deleted
288
+ * since): its files are refused `recorded_elsewhere`.
289
+ */
290
+ unplacedHistoryRecordedUnder?: string;
291
+ }
217
292
  export interface FileHistoryDiffStats {
218
293
  filesChanged: string[];
219
294
  insertions: number;
220
295
  deletions: number;
296
+ /** The preview file by file ({@link FileHistoryRewindFile}), refused rows included — the projection of the very plan a
297
+ * restore would carry out. Absent = an engine that does not answer per-file facts. */
298
+ files?: FileHistoryRewindFile[];
221
299
  }
222
300
  /** `Runner.rewindFiles`' request — the out-of-run code-only rewind (the reference's `rewind_files` control request). */
223
301
  export interface RewindFilesRequest {
@@ -236,6 +314,8 @@ export interface RewindFilesRequest {
236
314
  dryRun?: boolean;
237
315
  /** Caller cancel for the restore. */
238
316
  signal?: AbortSignal;
317
+ /** {@link FileHistoryRestoreOptions.unplacedHistoryRecordedUnder}, for this rewind (preview and restore alike). */
318
+ unplacedHistoryRecordedUnder?: string;
239
319
  /** The occupant the caller read the session as: `{ row: { owner, incarnation } }` (a `SessionHead` serves as `row`) — the
240
320
  * session under `sessionId` must still be that row (`sessionRowMatches` on the acquired session), or nothing is rewound and
241
321
  * the answer is `resume.session_not_found`. `row: null` and `log` are refused (`rewind.invalid_spec`). Absent ⇒ any
@@ -244,8 +324,11 @@ export interface RewindFilesRequest {
244
324
  }
245
325
  /** `Runner.rewindFiles`' answer. A refusal is a thrown `Error` carrying a `code`. */
246
326
  export type RewindFilesResult =
247
- /** `preview: null` = no preview for this request (the backend implements no `diffStats`, or answered none);
248
- * an empty `filesChanged` with zero counts = a real "nothing would change". */
327
+ /** The preview is the restore PLANNED (the store's own `restore` on a view of the env that performs no write), whatever
328
+ * optional preview verb the store has: `preview: null` = the planned restore failed as a whole (the store could not read
329
+ * the boundary), with no file to show. `filesChanged` lists only the files that would change: a preview whose every file
330
+ * is refused answers it empty with zero counts too, so read `files` (its refused rows) before telling anyone that nothing
331
+ * would change — empty `filesChanged`, zero counts and no `files` row is "nothing would change". */
249
332
  {
250
333
  dryRun: true;
251
334
  preview: FileHistoryDiffStats | null;
@@ -311,7 +394,9 @@ export interface FileHistoryExport {
311
394
  * with the graph; never inferred.
312
395
  */
313
396
  baseAvailable: boolean;
314
- /** Full retained chain (v1 first iff baseAvailable). `blobHash:null` = existed-not marker. */
397
+ /** Full retained chain (v1 first iff baseAvailable). `blobHash:null` = existed-not marker. `parentIdent`: never a place
398
+ * ({@link fileHistoryParentIdentTravels} — the door refuses one); an older engine's root-relative form only, which no
399
+ * engine reads as a place, so an imported version records no place. */
315
400
  versions: Array<{
316
401
  version: number;
317
402
  blobHash: string | null;
@@ -327,6 +412,14 @@ export interface FileHistoryExport {
327
412
  version: number;
328
413
  }>;
329
414
  }>;
415
+ /**
416
+ * How many of the exported history's files were left out because they stand under an absolute key
417
+ * ({@link fileHistoryEntryTravels}: edited outside the session's directory, or a second file whose relative name another
418
+ * directory's file keys) — their restore points do not travel with the session. A count only, never their paths (they are
419
+ * the source machine's). Absent = none left out, or an exporter from before this member. Not part of the envelope's
420
+ * identity ({@link fileHistoryExportDigest}).
421
+ */
422
+ absoluteEntriesOmitted?: number;
330
423
  }
331
424
  /**
332
425
  * The IDENTITY of an envelope — sha256 over its canonical (sorted) form, so the same graph digests
@@ -376,8 +469,8 @@ export interface FileHistoryStore {
376
469
  * are cheap no-ops). The first touch is ONE atomic durable record — pristine blob+record,
377
470
  * existence=false marker (rewind of an agent-CREATED file deletes it), or base-unavailable marker
378
471
  * (DV-14). Reads bytes via `env` (remote-safe); stores them host-side. `root` is the trusted task
379
- * root: paths under it are recorded root-RELATIVE (worktree/moved-root safe), paths outside it
380
- * verbatim-absolute; the parent-identity guard is recorded in the same frame.
472
+ * root: paths under it are recorded root-RELATIVE, paths outside it verbatim-absolute
473
+ * ({@link trackKeyForEdit}); the version's place is recorded in the same frame.
381
474
  * `{ok:false}` = NO durable first-touch state was persisted — see the discipline block: the
382
475
  * caller's default is to REFUSE the edit (DV-14), because proceeding leaves the path
383
476
  * indistinguishable from never-touched. `{ok:true, minted}` — see {@link FileHistoryTrackResult}:
@@ -456,7 +549,10 @@ export interface FileHistoryStore {
456
549
  * identical ⇒ untouched; tracked-later-than-target ⇒ fall back to its v1 (pristine) version, and a base-unavailable path (DV-14) is REFUSED with reason
457
550
  * `base_unavailable` (left at its current state — never overwritten with a fake baseline).
458
551
  * Per-file refusals SKIP that file and are counted, never failing the whole restore (CC form).
459
- * Paths recorded relative to `root` re-join against the CURRENT root (worktree/moved-cwd safe).
552
+ * Paths recorded relative to `root` re-join against the CURRENT root, and a version is converged there only when that is
553
+ * the place it was recorded at (`applyFileRestoreViaEnv`: `recorded_elsewhere` / `place_unrecorded` otherwise); `options`
554
+ * ({@link FileHistoryRestoreOptions}) is handed to that half as it is — a store that does not forward it leaves every
555
+ * version with no place refused.
460
556
  *
461
557
  * Partial outcome is FIRST-CLASS with a three-state discriminant and the per-file ledger always
462
558
  * travels: applied / identicalSkipped / refused / failed are SEPARATE columns (a security refusal
@@ -467,8 +563,13 @@ export interface FileHistoryStore {
467
563
  * the CALLER (prepare defaults to fail-loud; see DV-15). A boundary never made is `not_found` and
468
564
  * touches NOTHING — no file read or written, an empty ledger — since the engine's refusal of a
469
565
  * rewind without a boundary is exactly this answer (the contract kit checks the bytes).
566
+ *
567
+ * The engine also PLANS with this verb: it calls it with a view of `env` that reads the disk and performs no write or
568
+ * delete (each answers ok), and reads the plan's ledger as the preview and as the all-or-nothing gate. So `restore`
569
+ * changes nothing of the store's own records — a call is a read of the store, the writes are the env's — and reaches the
570
+ * working tree only through `env`.
470
571
  */
471
- restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryRestoreResult>;
572
+ restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal, options?: FileHistoryRestoreOptions): Promise<FileHistoryRestoreResult>;
472
573
  /** Whether (scope, entryId) has a USABLE boundary: `false` both for one never made and for one that is there but
473
574
  * cannot be read — `restore` is the verb that says which (`not_found` / `restore_failed` with the fault). */
474
575
  canRestore(scope: string, entryId: string): Promise<boolean>;
@@ -477,16 +578,12 @@ export interface FileHistoryStore {
477
578
  * slice 3). A-2 two-state law: `null` = preview UNAVAILABLE ≠ an empty stats object = a true
478
579
  * zero-coverage answer — an absent preview must never be rendered as "nothing will change".
479
580
  *
480
- * It is an UPPER BOUND on what a restore will touch, and the reason is worth stating rather than
481
- * discovering: the preview answers the CONTENT question (which tracked files differ from the
482
- * boundary, and by how many lines), while the per-file security preflight — symlink/kind, parent
483
- * chain — is decided by `restore` against the world as it stands THEN. A file listed here can
484
- * therefore come back refused, and a preview that pre-ran those checks would be making promises
485
- * about a world it does not own. Files whose target cannot be resolved at all (a missing version
486
- * record or blob, an unsafe key) are left OUT: the restore reports them per file, and a preview
487
- * cannot show the size of a change it cannot compute.
581
+ * The engine's own preview does not call it: `Runner.rewindFiles` previews by PLANNING the restore — this store's own
582
+ * `restore` run against a view of the env that performs no write ({@link planFileHistoryRestore}) — so a preview and the
583
+ * restore it previews are one computation and every store has one. The two bundled stores answer this verb with that same
584
+ * plan; it stays for a host that calls it directly.
488
585
  */
489
- diffStats?(scope: string, entryId: string, env: ExecutionEnv, root: string): Promise<FileHistoryDiffStats | null>;
586
+ diffStats?(scope: string, entryId: string, env: ExecutionEnv, root: string, options?: FileHistoryRestoreOptions): Promise<FileHistoryDiffStats | null>;
490
587
  /**
491
588
  * GC: drop boundaries in `scope` not in `keepEntryIds`; then drop version records (and content
492
589
  * blobs) referenced by NO surviving boundary — EXCEPT v1 records AND base-unavailable markers
@@ -714,19 +811,64 @@ export type FileBackupCapture =
714
811
  state: "unreadable";
715
812
  cause: string;
716
813
  };
814
+ /**
815
+ * Where a boundary re-reads a tracked file, and whether it may. An entry that records a place is read at the key's last segment
816
+ * under that place as it stands ({@link placeAsItStands}) — never "the key under whichever root this leg was handed" (a session
817
+ * handed another root must not read a same-named file there into its history: it never touched it, and a rewind would write it
818
+ * back) — and is HELD (not read; the boundary keeps its last version) when the place no longer resolves to itself or the file
819
+ * there is a symbolic link. An entry that records none (an older engine's, an imported one) is read at the key under `root` only
820
+ * when that path, links followed, lies under `root`'s real path; else it is held, and nothing is read or recorded: a value a
821
+ * history carries never makes a capture read outside the root. **Exported under the "MUST reuse" clause**, for every backend's
822
+ * `snapshot`.
823
+ */
824
+ export declare function resolveTrackedFile(env: ExecutionEnv, root: string, key: string, versions: ReadonlyArray<{
825
+ readonly parentIdent?: string;
826
+ }>, minted?: FileHistoryTrackKeyDescriptor, signal?: AbortSignal): Promise<{
827
+ ok: true;
828
+ abs: string;
829
+ } | {
830
+ ok: true;
831
+ held: string;
832
+ } | {
833
+ ok: false;
834
+ reason: string;
835
+ class: "key_unresolvable";
836
+ }>;
837
+ /**
838
+ * The key a first touch tracks `absPath` under, given the store's tracked set (`entryOf`): its own absolute path when the store
839
+ * already tracks it there (an edit from a leg whose root did not hold it, or a second file as below) — one file, one entry;
840
+ * else {@link describeTrackKey}'s, unless that root-relative key is already the key of a file at ANOTHER place (the session was
841
+ * handed another root since, and both roots hold a file at that relative path) — then this file's own absolute path, so two
842
+ * files never share one entry (the first one's history and the second one's edits would otherwise be one chain, and the second
843
+ * one's edits would be recorded nowhere). An entry with no place keeps its key (who it is cannot be told). **Exported under the
844
+ * "MUST reuse" clause**, for every backend's `trackEdit`; {@link trackKeyForAnnul} is its retraction twin.
845
+ */
846
+ export declare function trackKeyForEdit(env: ExecutionEnv, root: string, absPath: string, entryOf: (key: string) => {
847
+ readonly versions: ReadonlyArray<{
848
+ readonly parentIdent?: string;
849
+ }>;
850
+ } | undefined, signal?: AbortSignal): Promise<{
851
+ key: string;
852
+ } & FileHistoryTrackKeyDescriptor>;
853
+ /** The key a retraction names `absPath` by: its own absolute entry when the store holds one (then {@link trackKeyForEdit} tracked
854
+ * it there too), else {@link trackKeyOf}'s — the same choice the edit made, read from the tracked set alone. */
855
+ export declare function trackKeyForAnnul(root: string, absPath: string, has: (key: string) => boolean): string;
856
+ /** The boundary's re-version judgment on the PLACE axis, the {@link modeProvenDifferent} sibling: a capture whose place differs
857
+ * from the last version's (or whose last version records none) is versioned again even when its bytes are identical, so every
858
+ * boundary after an upgrade stands on versions that name their place. A capture with no readable place proves nothing. */
859
+ export declare function placeProvenDifferent(recorded: string | undefined, current: string | undefined): boolean;
717
860
  /**
718
861
  * Capture ONE file's current state through the ExecutionEnv — **the env-operating half every
719
862
  * backend MUST reuse** (design/381 §3 分工, the E19 captureManifest condition carried forward:
720
863
  * re-implementing it per backend is how symlink-escape/fail-closed bugs come back). Used by
721
864
  * `trackEdit` (first-touch pristine) and `snapshot` (per-file re-read). `not_found` is the sole
722
865
  * absent signal (the read itself is the authoritative existence probe — a separate stat would only
723
- * re-open the same race one window later). The parent-identity guard rides the same frame:
724
- * `canonicalPath(parent)` — root-relativized when under `root` (DV-6: a legal whole-root move must
725
- * keep verifying; an in-root parent-chain swap must keep refusing) — recorded best-effort (an env
726
- * that cannot canonicalize omits it; the slice-3 preflight then has nothing to compare, which is
727
- * the honest degraded form, never a fabricated identity).
866
+ * re-open the same race one window later). The version's PLACE rides the same frame as its
867
+ * `parentIdent` ({@link placeOfParentViaEnv}: the parent's absolute real path), omitted only when it
868
+ * cannot be read — a version with no place is refused by a restore unless the rewind names where such
869
+ * versions were recorded, never converged on a guess. `_root` stays in the signature every backend calls.
728
870
  */
729
- export declare function captureFileBackupViaEnv(env: ExecutionEnv, absPath: string, root: string, signal?: AbortSignal): Promise<FileBackupCapture>;
871
+ export declare function captureFileBackupViaEnv(env: ExecutionEnv, absPath: string, _root: string, signal?: AbortSignal): Promise<FileBackupCapture>;
730
872
  /**
731
873
  * The retraction PROOF READ (design/381 #491 + adversarial round 2), shared by every backend so the
732
874
  * evidence rule cannot drift: does the path still look exactly as the first touch recorded it? An
@@ -786,13 +928,15 @@ export type FileRestoreTarget = {
786
928
  * compare must degrade to "no opinion", never to a fabricated expectation.
787
929
  */
788
930
  export interface FileRestoreApplyOptions {
789
- /** The task root the recorded key was re-joined against — the coordinate `parentIdent` lives in. */
931
+ /** The task root the recorded key was re-joined against (the key's coordinate; the place check reads absolute places). */
790
932
  root: string;
791
- /** The parent identity recorded WITH the version being restored ({@link parentIdentityViaEnv}). */
933
+ /** The place recorded WITH the version being restored ({@link placeOfParentViaEnv}; a root-relative or absent one names none). */
792
934
  parentIdent?: string;
793
935
  /** The POSIX mode recorded with the version being restored (design/381 DV-8). */
794
936
  mode?: number;
795
937
  signal?: AbortSignal;
938
+ /** The rewind's {@link FileHistoryRestoreOptions.unplacedHistoryRecordedUnder}, handed on by the backend as it is. */
939
+ unplacedHistoryRecordedUnder?: string;
796
940
  }
797
941
  export type FileRestoreApplyOutcome =
798
942
  /** `modeNotPreserved` rides the two NON-refusal arms: the bytes converged but the recorded mode
@@ -805,12 +949,16 @@ export type FileRestoreApplyOutcome =
805
949
  outcome: "identical";
806
950
  modeNotPreserved?: true;
807
951
  }
808
- /** Every refusal this half decides is about the object at the path (its kind, its parent chain, a guarded
809
- * write's precondition), so its class is `link_safety`; a backend copies it into the ledger row. */
952
+ /** A refusal this half decides: about the object at the path (its kind, a guarded write's precondition, the recorded
953
+ * place having moved or become a link — `link_safety`), or about where the version belongs (`recorded_elsewhere`, with
954
+ * `recordedUnder`; `place_unrecorded`). `action` = what converging would have done. A backend copies all of it into the
955
+ * ledger row. */
810
956
  | {
811
957
  outcome: "refused";
812
958
  reason: string;
813
- class: "link_safety";
959
+ class: "link_safety" | "recorded_elsewhere" | "place_unrecorded";
960
+ recordedUnder?: string;
961
+ action?: "write" | "delete";
814
962
  } | {
815
963
  outcome: "failed";
816
964
  reason: string;
@@ -829,15 +977,18 @@ export type FileRestoreApplyOutcome =
829
977
  * at the leaf is refused rather than followed: the recorded bytes belong to the file the agent
830
978
  * edited, not to whatever a link now points at. A directory/socket/FIFO in its place is the same
831
979
  * refusal for the same reason.
832
- * · PARENT CHAIN — the current canonical parent identity must equal the one recorded with the
833
- * version ({@link parentIdentityViaEnv}, root-relative under the root). A legal whole-root move
834
- * keeps it equal (E4 passes); an in-root ancestor swapped for a link out of the tree does not
835
- * (E5 refuses, and nothing outside the root is written). BOTH must hold at once — relaxing to
836
- * "moves also refuse" or "swaps also pass" is a mis-fix, not a tuning choice.
837
- * · The guard is EVIDENCE-BASED, not assumption-based: a record with no parent identity (an env
838
- * that cannot canonicalize) and a parent that cannot be canonicalized NOW (the ordinary "the
839
- * directory was deleted and this restore recreates it" case) both mean "nothing to compare", and
840
- * inventing a refusal there would break the recreate arm rather than close a hole.
980
+ * · PLACE — a version is converged only where it was recorded: the place of the path (its parent's
981
+ * absolute real path, {@link placeOfParentViaEnv}) must equal the place the version records. A
982
+ * version recorded under another directory (a later leg handed another root, a fork handed
983
+ * another root, a history carried or cascaded from another session, a moved or copied root) is
984
+ * refused `recorded_elsewhere` with `recordedUnder` — unless the file at its own place already
985
+ * holds it, which is a convergence with nothing to do (`identical`). A recorded place that now
986
+ * resolves elsewhere itself (an ancestor swapped for a link) is `link_safety`, and nothing is
987
+ * written through it. A version that records no place (an older engine's, or an imported one) is
988
+ * read as recorded under `unplacedHistoryRecordedUnder` (with the key's own parent below it) when
989
+ * the rewind names one, and is otherwise refused
990
+ * `place_unrecorded`. A directory deleted since (the recreate arm) has the same place — the
991
+ * nearest existing ancestor's real path with the rest appended — so it is recreated.
841
992
  *
842
993
  * THE WRITE uses `env.writeFileGuarded` when the env has it — one atomic verify-and-write whose
843
994
  * expectation names the addressed path and forbids following a leaf link, so the window between
@@ -963,9 +1114,10 @@ export declare class InMemoryFileHistoryStore implements FileHistoryStore {
963
1114
  private annulTrackCounted;
964
1115
  snapshot(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryResult>;
965
1116
  private snapshotCounted;
966
- restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryRestoreResult>;
1117
+ restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal, options?: FileHistoryRestoreOptions): Promise<FileHistoryRestoreResult>;
967
1118
  canRestore(scope: string, entryId: string): Promise<boolean>;
968
- diffStats(scope: string, entryId: string, env: ExecutionEnv, root: string): Promise<FileHistoryDiffStats | null>;
1119
+ /** The restore PLANNED ({@link planFileHistoryRestore}), projected — one computation with the restore it previews. */
1120
+ diffStats(scope: string, entryId: string, env: ExecutionEnv, root: string, options?: FileHistoryRestoreOptions): Promise<FileHistoryDiffStats | null>;
969
1121
  reap(scope: string, keepEntryIds: string[]): Promise<number>;
970
1122
  deleteBySession(scope: string): Promise<number>;
971
1123
  deleteUnreadableSessionHistory(sessionId: string): Promise<number>;
@@ -982,6 +1134,39 @@ export declare class InMemoryFileHistoryStore implements FileHistoryStore {
982
1134
  /** The import body inside the blob lease (see {@link importHistory}). */
983
1135
  private importStaged;
984
1136
  }
1137
+ /** One mutation a restore asked of the env: the absolute path, and what it did there (`bytes` on a planned write). */
1138
+ interface EnvMutation {
1139
+ readonly at: string;
1140
+ readonly action: "write" | "delete" | "mode";
1141
+ readonly bytes?: Uint8Array;
1142
+ }
1143
+ /** A view of `env` that performs every call and records the mutations a restore made through it. */
1144
+ export declare function witnessEnvOf(env: ExecutionEnv): {
1145
+ env: ExecutionEnv;
1146
+ mutations: readonly EnvMutation[];
1147
+ };
1148
+ /** `restored` with its per-file answer ({@link FileHistoryRewindFile}), read off the mutations the restore asked for. */
1149
+ export declare function withRewindFiles(restored: FileHistoryRestoreResult, mutations: readonly EnvMutation[], root: string): FileHistoryRestoreResult & {
1150
+ files: FileHistoryRewindFile[];
1151
+ };
1152
+ /** A restore PLANNED (see the section header): the ledger the store answered on a view that performs no write, with its files,
1153
+ * and the line arithmetic of the writes and deletes it asked for (the preview's counts). */
1154
+ export interface FileHistoryRestorePlan {
1155
+ readonly restore: FileHistoryRestoreResult & {
1156
+ files: FileHistoryRewindFile[];
1157
+ };
1158
+ readonly diffStats: FileHistoryDiffStats & {
1159
+ files: FileHistoryRewindFile[];
1160
+ };
1161
+ }
1162
+ export declare function planFileHistoryRestore(store: Pick<FileHistoryStore, "restore">, input: {
1163
+ scope: string;
1164
+ entryId: string;
1165
+ env: ExecutionEnv;
1166
+ root: string;
1167
+ signal?: AbortSignal;
1168
+ options?: FileHistoryRestoreOptions;
1169
+ }): Promise<FileHistoryRestorePlan>;
985
1170
  /** Test-only window (family-aware path-coordinate pins + the DV-6 track-key coordinate): pure
986
1171
  * helpers whose behavior carries a fence/restore invariant. Not re-exported from src/index.ts. */
987
1172
  export declare const __testables: {