@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.
- package/CHANGELOG.md +49 -0
- package/dist/agents/repair-loop.js +1 -1
- package/dist/agents/verify.js +1 -1
- package/dist/core/engine-capabilities.d.ts +8 -1
- package/dist/core/engine-capabilities.js +1 -1
- package/dist/core/file-history-store.d.ts +229 -44
- package/dist/core/file-history-store.js +288 -93
- package/dist/core/runner/contracts.d.ts +1 -1
- package/dist/core/runner/file-history-request.d.ts +10 -2
- package/dist/core/runner/file-history-request.js +17 -1
- package/dist/core/runner/file-history-restore.d.ts +11 -4
- package/dist/core/runner/file-history-restore.js +19 -5
- package/dist/core/runner/prepare-file-history.js +3 -3
- package/dist/core/runner/rewind-files.js +11 -8
- package/dist/core/store-contracts/file-history-store-contract.js +210 -13
- package/dist/core/task-spec-members.d.ts +31 -18
- package/dist/core/task-spec-members.js +11 -8
- package/dist/core/task-spec.d.ts +7 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/orchestration/goal.js +3 -1
- package/dist/stores/file/file-history-store.d.ts +5 -3
- package/dist/stores/file/file-history-store.js +42 -60
- package/package.json +2 -2
- package/test/export-surface.snapshot.json +17 -1
- package/wire-changes/core-stores-sql@7.68.2.json +39 -0
- package/wire-changes/core-stores-sql@7.68.3.json +39 -0
- package/wire-changes/core@7.68.2.json +612 -0
- package/wire-changes/core@7.68.3.json +125 -0
- package/wire-changes/mods-kernel@7.68.2.json +39 -0
- package/wire-changes/mods-kernel@7.68.3.json +39 -0
- package/wire-changes/primitives@7.68.2.json +39 -0
- package/wire-changes/primitives@7.68.3.json +39 -0
- package/wire-changes/wiki-gate@7.68.2.json +39 -0
- 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 (
|
|
66
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
248
|
-
*
|
|
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
|
|
380
|
-
*
|
|
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
|
|
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
|
-
*
|
|
481
|
-
*
|
|
482
|
-
*
|
|
483
|
-
*
|
|
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
|
|
724
|
-
* `
|
|
725
|
-
*
|
|
726
|
-
*
|
|
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,
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
809
|
-
*
|
|
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
|
-
* ·
|
|
833
|
-
*
|
|
834
|
-
*
|
|
835
|
-
*
|
|
836
|
-
*
|
|
837
|
-
*
|
|
838
|
-
*
|
|
839
|
-
*
|
|
840
|
-
*
|
|
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
|
-
|
|
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: {
|