@sema-agent/core 7.68.1 → 7.68.2
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 +34 -0
- 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 +2 -1
- package/dist/core/task-spec-members.js +1 -1
- package/dist/core/task-spec.d.ts +7 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- 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@7.68.2.json +612 -0
- package/wire-changes/mods-kernel@7.68.2.json +39 -0
- package/wire-changes/primitives@7.68.2.json +39 -0
- package/wire-changes/wiki-gate@7.68.2.json +39 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,37 @@
|
|
|
1
|
+
## 7.68.2 — 2026-11-13
|
|
2
|
+
|
|
3
|
+
### A file rewind writes a recorded version only under the directory it was recorded under — one recorded elsewhere is refused file by file, a run that does not accept a partial restore moves nothing, and the preview and the restore name every file (#4328, closes the write shapes of #4446; behavior change; narrowing: six, below, open to veto @server @cli @client-core; widening: two, below, open to veto @server @cli; hard-breaking: none at runtime — compliance-kit cells a backend that has not followed reads red, below; closed sets: `FILE_HISTORY_REFUSAL_CLASSES` +2 (`recorded_elsewhere`, `place_unrecorded`; the same two on a refused file's `FileRestoreApplyOutcome.class`), `ENGINE_CAPABILITIES` +1 (`file_history.recorded_place`), new `FileRestoreApplyOutcome.action` (`write`, `delete`); exports: +6 functions, +2 types, none removed; signatures: `restore` and `diffStats` of `FileHistoryStore` and of both bundled stores take an optional last parameter `options` (`FileHistoryRestoreOptions`); wire: optional members only — `TaskSpec.unplacedHistoryRecordedUnder`, `RewindFilesRequest.unplacedHistoryRecordedUnder`, `files` on the restore result and the preview, `recordedUnder` / `action` on a refused row, `failed` on a `files` row, `absoluteEntriesOmitted` on the export envelope)
|
|
4
|
+
|
|
5
|
+
- **Before.** (#4446, as the 7.68.1 notes disclose it.) A version carried no fact of where it belonged: its key was relative to the root of the leg that recorded it, its `parentIdent` relative to the same root, and a restore joined the key on the root of the leg that asked. A later leg handed another root — the terminal's `/cd` / `!cd`, entering or leaving a worktree, the same session continued in another worktree; an embedder's `cwd` per leg, a fork handed another root, the deletion cascade's `adoptScope` — had the file at the same relative path under its root written with the earlier root's bytes and the rewound turn's created files deleted there, answered `complete`, while the files under the earlier root stayed as they were. Two more write paths rode the same restore. A run that does not accept a partial restore wrote every restorable file before it reached the one it refused, then answered `rewind.restore_failed` (measured: a target replaced by a symbolic link — `b.txt` written, `a.txt` refused). A fork's rewind to a turn carried from its source wrote the source's edits outside its directory back over the source's later edits (measured: `o.txt` back to `o-0` over the source's `o-2`). The preview listed names and line counts only.
|
|
6
|
+
- **Now.** One rule: a tracked entry is one file, and its identity is the directory its versions record — `parentIdent` now holds the parent's absolute real path (the nearest existing ancestor's real path with the rest of the path appended; the member is unchanged). A restore writes or deletes a version only when the place it would land on (this leg's root + the key) is that directory; otherwise the file is refused `recorded_elsewhere`, its row naming the directory (`recordedUnder`) — unless the file at its own directory already holds the version, which is a restore with nothing to do (`identical`). A version that records no directory — every version an engine before this one recorded — is refused `place_unrecorded`, unless the rewind names the directory such versions were recorded under (`unplacedHistoryRecordedUnder`, an absolute path, on `TaskSpec` and `Runner.rewindFiles`): the same comparison then judges it, and a version that records its directory never reads it. A directory renamed in place only in letter case or Unicode normal form on a volume that does not tell those apart is the same directory (its real path is the recorded one folded, and no component of the recorded path is a link); a recorded directory that now resolves elsewhere through a link is not, and nothing is written through it (`link_safety`). A boundary re-reads each tracked file where it was recorded and versions it again when that place changed, so every turn this engine runs stands on versions that name their place; it HOLDS a file (keeps its last version, reads nothing) whose recorded directory no longer resolves to itself or which is a symbolic link there now; it reads the file in that recorded directory as it stands, never through the path the leg's root joined with the key spells (so a link inside the root pointed elsewhere cannot redirect the read); and it reads a file whose history records no place (an earlier engine's, an imported one) only when its path under the root, links followed, lies under the root's real path — a key that runs through a link inside the root out of it is never read and records no place (closed in this release, pre-existing: an engine ≤ 7.68.1 read such a file and stored its bytes in the history, and an export carried them; an entry such an engine already gave a place outside the root is read there — KL-4328-l, in the known limits below); a second file whose relative name another directory's file already keys is tracked under its own absolute key, and a file already tracked under its absolute key (first edited from a leg whose root did not hold it) stays that one entry when a later leg's root holds it. A run that does not accept a partial restore, and the preview, plan first — the store's own `restore` on a view of the environment that reads the disk and performs no write: the preview is that plan's projection, and the run refuses on the plan, nothing written and nothing deleted (`Runner.rewindFiles` without `dryRun`, and a run with `acceptPartialRestore`, restore file by file as before and answer the ledger). **The zero-change guarantee ends when the plan passes**: a write that fails after it is a partial restore, reported file by file with the files already written named — a file whose bytes landed stays named when the step after the write fails: a mode change that throws leaves it in the store's ledger with `modeNotPreserved` (on 7.68.1 it was reported `failed` though its content was restored), and a file the store answers `failed` after its write or delete landed is a `files` row with that `action` and `failed: { reason }` (the run's sentence names it `written` / `deleted`). A history carried into another session (a fork's carry, the deletion cascade's step 10) or exported takes only its entries under a root-relative key (`fileHistoryEntryTravels`); an export counts what it left out (`absoluteEntriesOmitted`), never naming the paths. A version's place never crosses the export door: an export leaves out every place (`fileHistoryParentIdentTravels`), the import door refuses an envelope that carries one (`unsupported_format`, in the absolute key's words), and a root-relative `parentIdent` — an older engine's form, or whatever an envelope carries — is read as no place, never joined onto a root or a named directory. So an imported version records no place, and no value an envelope this release imports becomes a path the engine reads bytes from: an imported key is read only under the root's real path (above; the gap between that check and the read is KL-4328-k, and entries an engine ≤ 7.68.1 imported and already placed outside the root are KL-4328-l, both below), and the check resolves the key's real location — a lookup that reads no bytes and answers the same either way (a carry within one store keeps its places: they were recorded on this machine). The restore result, the run's `rewind.restore_failed` detail and the preview answer `files`: one row per file, `{ path, targetPath, action, refused? }` — `path` the history key (a relative name, or an absolute key where the relative name was another directory's file's), `targetPath` the absolute path this rewind writes or deletes (on a refused row, where it would have), `refused: { class, reason, recordedUnder? }`. `reason` is for a person; a consumer branches on `class` only, and `class` is an open set. `files` absent = an engine before this one (no per-file facts — not "nothing refused"). `filesChanged` stays: the keys of the rows not refused.
|
|
7
|
+
- **More refused (narrowings, open to veto).** ① A rewind on a leg handed another root than the one the versions were recorded under: P1 parent → child, P2 child → parent, another worktree, X1 / X2, a fork handed another root, the deletion cascade on both hops — per file, nothing written; on the verb `partial` (the same-directory files restore), on a run `rewind.restore_failed` with nothing moved. ② A whole root moved or copied to another path: refused at the new path (the version records the old one). ③ Versions recorded by an earlier engine: `place_unrecorded` until the rewind names their directory; a turn this engine runs re-versions the tracked set, so a rewind to it restores. The directory is named, never read off the version: the key's own parent under it is the place, so an earlier engine's version whose parent directory was reached through a link inside the root is refused even when named (`link_safety`: the named directory's path to the file runs through the link; rare). ④ A fork's rewind to a turn carried from its source no longer restores the source's edits outside its directory: those entries are not carried, so they appear neither in the fork's preview nor in its result. ⑤ A session synced in (export, then import on another store or machine): a rewind to a turn recorded before the sync is `place_unrecorded` wherever it runs — today it writes by relative key at whatever root the rewind runs on — until the rewind names the directory those versions were recorded under (`unplacedHistoryRecordedUnder`: restored there, `recorded_elsewhere` anywhere else); the first turn after the sync records this machine's places. And an envelope an engine ≤ 7.68.1 exported carrying an absolute `parentIdent` (a parent directory that resolved outside the root through a link) is refused whole at the import door (rare; KL-4328-g). And on a lane whose root path changes from leg to leg (a remote mount rotating), the earlier legs' versions are refused (KL-4328-b). ⑥ A file a session's history records no place for (an earlier engine's version, or a synced one) whose path under the root runs through a link out of the root — a linked directory inside the repository pointing elsewhere — is no longer re-read at a boundary: no new version, and its bytes are not stored (on ≤ 7.68.1 each boundary read the outside file and stored it); edits to it from this release on get no restore point, and a rewind refuses it (`place_unrecorded`, or `link_safety` when the directory is named). A file this engine tracks first records its own place and is read there (a file the model edits through such a link records the directory the link resolves to).
|
|
8
|
+
- **Write errors closed.** Every shape in ① (the same relative path under the new root written, the rewound turn's created names deleted); the fork rewind over the source's file outside its directory (G0, above); a same-named file below the root the session never touched, written back after a leg there (K1); the write-then-discover order of a run that refuses its restore.
|
|
9
|
+
- **Widened (open to veto @server).** A session whose history held an entry under an absolute key exported an envelope the import door refused whole (`unsupported_format`, "is an ABSOLUTE key" — measured). Such a session's file history now imports without those entries (counted in `absoluteEntriesOmitted`), and the imported relative entries are written only where the rewind names the directory they were recorded under (⑤). The door's own refusal is unchanged: an envelope that carries an absolute key is refused whole (pinned). **Widened (open to veto @cli @server).** On a volume that does not tell letter case apart (the macOS default), a directory inside the root renamed only in letter case (`Sub` → `sub`), or only in Unicode normal form (NFC → NFD), since the version was recorded: 7.68.1 refused it `link_safety`, it now restores in that directory (measured on darwin, both bundled stores — the normal-form shape by the release review; the root renamed so, and a root renamed between Unicode normal forms, restored on 7.68.1 too and still do). A directory swapped for a link to another stays refused (pinned).
|
|
10
|
+
- **Not changed.** A rewind on the same directory however it is spelled (`/tmp` and `/private/tmp`, a symbolic link to it, another letter case on a case-insensitive volume, the root renamed in letter case or Unicode form only); a `cd` the model runs inside a leg (it does not change the leg's root); a file created under a new deep directory (removed) and a file whose directory was deleted since (recreated); a conversation-only rewind; two Runners on one root; a fork on its source's directory. In this release a fork that works in a tree of its own still records no file history (the coarse rule, the carry's two-root judgment and their two sentences stay; they only refuse, and leave in 7.69.0).
|
|
11
|
+
- **Known limits.** Twelve, KL-4328-a … KL-4328-l, each stated in full in the next section; none is changed by this release, and KL-4328-l reads more widely than 7.68.1 on one shape.
|
|
12
|
+
- **The 7.68.1 known defect (#4446), item by item.** *When*: every entrance it lists — `!cd` / `/cd`, entering or leaving a worktree, the session continued in another worktree, an embedder's `cwd` per leg, a fork handed another root, `adoptScope` as the deletion cascade calls it — on all three entries: closed, each file refused, nothing written or deleted. *What happens*: the same relative path under the new root written, the same-named file deleted — closed; `complete` — now `partial` on the verb, `rewind.restore_failed` on a run; the restore the person asked for still does not happen at the new root, and now says so — each refused row names the directory its version was recorded under, and a rewind from that directory restores it; the preview — now each file with the path it writes or deletes (`targetPath`) and `delete` marked; `adopt_failed`'s sentence — rewritten: a rewind to a point before the fork is refused, as a point with no boundary on the fork, or file by file as recorded elsewhere where the fork's history was filled through another channel. *Still open*: a lane handing each leg a new instance at the same path (KL-4328-a; the advice "check the preview before a rewind" still applies there), an absolute-key entry an earlier engine already carried into a fork (KL-4328-d), and versions an earlier engine recorded, refused until the rewind names their directory (③ above).
|
|
13
|
+
- **Rolling upgrade and rollback.** A version this engine records names its place as an absolute path in `parentIdent`, a member an engine ≤ 7.68.1 reads as a root-relative parent identity: such an engine refuses a rewind to a turn recorded on this release file by file (`link_safety`, its sentence "restore target's parent chain changed identity since it was recorded"), nothing written; the turns it then records are versions with no place here (`place_unrecorded` until the directory is named, ③). Measured on one file store at one root: rows this release wrote, read by the published 7.68.1 — both turns refused `link_safety`, the file untouched; 7.68.1's next turn, read back by this release — `place_unrecorded`. So workers of the two versions sharing one store, or a rollback, refuse a rewind to a turn the other version recorded; neither writes a wrong root. An export from this release carries no place, and an engine ≤ 7.68.1 imports it as an export of its own (read from code).
|
|
14
|
+
- **Rules.** −1 reading (where a version restores: the leg's root decided it; now the version's own directory), −1 reading (a root-relative `parentIdent` was joined onto the root as a parent identity; now it is no place), +1 comparison in the shared restore half (the existing link-safety check of the recorded parent is the same comparison), +1 projection (preview = plan), +2 predicates (`fileHistoryEntryTravels` read by carry and export; `fileHistoryParentIdentTravels` read by export and the import door — one rule with the absolute key's: nothing absolute crosses the door), +2 refusal classes. A file's key: its absolute key when the store already tracks it there, else its root-relative name unless another directory's file holds that name — one file, one entry, and the retraction reads the same choice from the tracked set (it replaces "the root-relative name under whichever root the leg was handed", which tracked one file under two keys after a root change). +1 judgment: a file with no recorded place is read only where its path, links followed, lies under the root (it replaces "the key joined on the leg's root is read"); one sameness of a recorded place (its real path, or the recorded spelling folded by letter case and Unicode form with no link on it) read by the restore check, the boundary re-read and the first touch's key — it replaces byte equality, no rule added; "a file whose bytes landed is named" is one reading over the mode change and the store's own failure. Retired: the bundled stores' own preview arithmetic (`diffStats` is the plan's projection). Kept until 7.69.0: the coarse fork rule and the carry's two-root judgment.
|
|
15
|
+
- **Pins.** `test/file-history-recorded-place.test.ts` — P1 / P2 / another worktree × the three entries (rows, preview = plan, nothing written), P4 × three, X2, K1, W1 / FC × three, R8, six spellings of one directory × three, D1 / D2, a root moved / copied, ATOM-symlink, the failure after the plan, O1 × three + the re-versioning turn, O3, O4, O5 (stores the released v7.68.0 wrote, `test/fixtures/file-history-v7680/`), R17, the input's door and its two statements, the capability word, R17 (synced versions refused until named; named: restored there, refused elsewhere) and R17b (the first boundary after the sync records places), a forged envelope (`id_rsa` × an absolute place / a `..` escape / a link-directory name: refused at the door or read as no place, and an env probe sees no path outside the root handed to it), a file directly under the filesystem root, a store that reads through the env's text and path members, one file one entry (absolute-key reuse, the retraction's key, a waiting touch that does not write back a stale tracked set), an imported key through a link out of the root × {link kept, link removed} and a tracked file or its directory swapped for a link (no bytes read, nothing stored, the boundary keeps the file), a mode change that throws after the write and a store that answers a landed file failed (the file named), a root / an inner directory renamed in letter case and a root renamed between Unicode forms on a case-insensitive volume (restored; a directory swapped for a link refused), a folded spelling whose directory reads as a link or cannot be read (refused), a row an older engine left through a link kept inside the root × {an edit by the model through Write, an edit by the person} × both stores, then a turn under a directory below (a rewind at the first root to that turn restores the file as it was then — a boundary that held the row at its older version wrote the older bytes back), a place a link inside the root led to × {link kept} (captured and restored) and × {the link pointed elsewhere before the boundary's read} (the read stays in the recorded directory), K1 the other way (a rewind at the first root restores the file as it was when the turn under the second root began), Write / Edit through a link inside the root × {a directory below, a sibling tree} (keyed by the real path; restored as it was then), an ordinary backslash-named directory (a POSIX name) re-read from another root, KL-4328-l as it stands × {link removed, replaced by a directory} (a known limit, not a contract). `test/file-history-carried-absolute-keys.test.ts` — G1 / G2 / G0 × three, EX. `test/file-history-same-path-new-instance.test.ts` — KL-4328-a × three (the same cells green on v7.68.0). Compliance kit (`fileHistoryStoreContract`): E4 and the track-key coordinate cell now refuse a moved root; the import round trip restores where the rewind names the directory; new cells K1, K2, W1, older versions + the input, carry, export (entries and places).
|
|
16
|
+
- **Consumers.** @server — wiring, first: **following half is the one way to write wrong: minting a second file's absolute key (`fileHistoryTrackKeyForEdit` / `fileHistoryTrackKeyForAnnul`, the W1 cell) and the carry filter (`fileHistoryEntryTravels` in `adoptScope`, the carry cell) are followed in the same release or not at all** — the first without the second has a fork's rewind write the file its source still edits, and the carry cell's failure names that combination. Hard gates on taking this release: the cells `adoptScope carries only the entries that travel…` (your `INSERT…SELECT` copies every row: filter on `key_kind = 'root-relative'` and copy only the kept keys' boundary rows), `K1 one relative name, two files…` (your boundary re-read joins the key on the leg's root: read it through `fileHistoryResolveTrackedFile(env, root, key, versions, keyDescriptor?, signal?)` — async; its `held` answer = keep the entry's last version and read nothing — and version again on `fileHistoryPlaceProvenDifferent` beside the mode rule; this signature replaces the synchronous `(root, key, versions, keyDescriptor?)` the pre-pickup notes named, so a binding wired to that form fails to compile) and `K2 a boundary reads no file through a link out of the root…` (green with the same change as K1: an imported key that runs through a link inside the root out of it, and a tracked file swapped for a link, are held and their outside bytes never read — your store reads them today, a pre-existing hole). Also a hard gate: `export carries only the entries that travel, and no version's place…` — your SQL export leaves out every `parentIdent` that `fileHistoryParentIdentTravels` answers `false` for (the places your captures record from this release on), and every absolute-key entry (`fileHistoryEntryTravels`); not following ⇒ a 7.68.2 import door refuses your envelopes whole (`unsupported_format`). Your sync entry (a client's pushed envelope → `importHistory`) refuses whole, on this release, an envelope an exporter ≤ 7.68.1 wrote with an absolute `parentIdent` (a parent directory resolved outside the root through a link; rare — KL-4328-g); a synced session's rewind to a turn before the sync is `place_unrecorded` unless your rewind entry passes `unplacedHistoryRecordedUnder` — the caller's assertion, forwarded by the host; the engine does not check it against where the imported history really came from, and a wrong one writes by relative key at the declared root (KL-4328-h). May be held back by name in your binding (`ContractAssertionRunner` receives the cell name): `W1 a second file whose root-relative name…` (never before the carry cell; not following ⇒ W1 / FC over-refuse). Green by reusing the two shared halves: the moved-root cell, the diffStats cell; the older-versions cell and the import round-trip cell need your `restore` to pass its sixth parameter (`options`) on to `applyFileRestoreViaEnv` (not passing it ⇒ older and imported versions are always `place_unrecorded`). A `files` row gains an optional `failed: { reason }` (a file whose write or delete landed and which the store then answered failed; only on a restore, never on a preview) — a reader that does not know it still sees the row's `action`. Optional: copy `recordedUnder` / `action` onto your refused rows (not copied ⇒ the directory reaches a shell only inside `reason`). The engine previews by planning your `restore` (it no longer calls your `diffStats`): your `restore` must keep writing nothing to your own tables. Not following anything ⇒ the reroot shapes, atomicity and older versions are closed on your store with zero code; K1 reads as today; W1 / FC over-refuse. The import door's code for the new refusals (a malformed `absoluteEntriesOmitted`, a version carrying a place, a non-string `parentIdent`) is `unsupported_format`. @cli @client-core: read `files`, not only `filesChanged` — a preview whose every file is refused (a rewind on a leg handed another root) answers `filesChanged: []` with zero counts, which a shell reading only those shows as "nothing to change"; show each `files` row (its `targetPath`, and `delete` as a deletion) in the rewind preview, and on a failed restore a row's `failed` as "written (or deleted), then failed"; on a refused row show `recordedUnder` ("recorded under …: rewind from that directory"); `place_unrecorded` carries no `recordedUnder` (read it as absent) and covers both versions an earlier engine recorded and versions that came with a synced session; branch on `class` only; a fork's rewind no longer lists its source's files outside its directory; gate on `file_history.recorded_place`. After a session sync, say "N files' restore points did not come with the session" from the envelope's `absoluteEntriesOmitted`. @test: black-box criteria are in the release post (the same-root forms unchanged; each reroot form refused with nothing written on all three entries; the moved root refused; the older store refused, and restored when its directory is named).
|
|
17
|
+
|
|
18
|
+
### Known limits, not changed by this release: what the first slice of the file-rewind fix (#4328) does not cover
|
|
19
|
+
|
|
20
|
+
Each limit is stated in full here. Unless an item says otherwise, its fix is the rewind's final form (#4328): a version that records the root it was recorded under.
|
|
21
|
+
|
|
22
|
+
- **KL-4328-l — entries an earlier engine imported through a link inside the root are still read outside the root after the upgrade, and on one shape more widely than on 7.68.1.** *Which sessions*: a session whose file history an engine ≤ 7.68.1 imported (a session sync) holding a key whose path under the root runs through a link inside the root to a directory outside it (`lnk/secret.txt`, `lnk` pointing elsewhere), on which that engine then ran a turn — the turn recorded the outside directory as the file's place. The engine's own write tools do not mint such an entry: they key a file by its real path, so a file the model edits through such a link is tracked under the outside file's absolute key and restores correctly (measured through the real Write and Edit tools, then a turn under a directory below or in a sibling tree, then a rewind at the first root; NotebookEdit and the tool that saves a tool result read from code). A host that calls a store's own `trackEdit` with a path through such a link does mint it, on this release too. *What happens after the upgrade*: every boundary reads that outside file and stores its bytes in the history store — as 7.68.1 did while the link stood — **and also after the link is removed or replaced by a real directory of the same name, a shape 7.68.1 does not read (it read the path under the root): this release is wider there**. A rewind to such a turn reads the outside file once more (a hash comparison) and refuses it (`recorded_elsewhere`), writing nothing; 7.68.1, with the link removed, wrote the bytes it had stored into a recreated file under the root, and with a directory in its place refused it (`link_safety`). *Why it is not closed here*: a version does not record the root it was recorded under, so the engine cannot tell "the link is gone" from "the session moved to another root"; closing it by judging the recorded path's shape made a rewind write older bytes back on such a session after a turn under a directory below, answering `complete` (measured, and withdrawn before release). *Not affected*: entries imported or recorded from this release on — an imported key through such a link is never read (the compliance kit's K2 cell); a deployment that never imported a file history on an engine ≤ 7.68.1 (and whose host never handed a store's `trackEdit` such a path) holds no such entry.
|
|
23
|
+
- **KL-4328-k — the gap between a boundary's check and its read.** A boundary checks where a tracked file really is before it reads it (an entry that records no place: under the root's real path; an entry that records one: the place still resolves to itself and the file there is no link), and then reads it; a link swapped in between the two — an ancestor directory, or the file itself — is read (reproduced with a deterministic swap). This narrows what 7.68.1 read through such a link (any history that carried such a key, unchecked) to a process rewriting the tree at the moment of the boundary. It closes when the execution environment offers a member that opens a path without following links component by component, or answers a held handle's real location, and the capture checks the handle it reads.
|
|
24
|
+
- **KL-4328-h — `unplacedHistoryRecordedUnder` is the caller's word; never fill it with the current root by default.** The engine does not check the directory named for versions that record none against where that history was really recorded. Named wrongly, those versions are written and deleted by relative key under the named directory: a host that fills it with the current leg's root by default brings the 7.68.1 defect back for them (measured: a turn recorded under one root on 7.68.1, rewound on this release under another root with that other root named — its same-named file written with the first root's bytes, answered `complete`). Pass it only when the caller knows where those versions were recorded; left out, they are refused `place_unrecorded`.
|
|
25
|
+
- **KL-4328-a — two workspace instances at one path are one place.** The place is a path, so a lane that hands each leg a new instance at the same path rewinds there as recorded (measured; what a rebuilt instance holds is the host's lane fact); the directory named for older versions is a path too.
|
|
26
|
+
- **KL-4328-b — a lane whose root path changes from leg to leg refuses the earlier legs' versions.** The place is compared as the absolute real path the leg's execution environment sees, so where the workspace path differs between instances a rewind to an earlier instance's versions is refused (read from the server's code: its container, e2b and k8s lanes use fixed workspace paths; in reach are a host lane's random temporary root, and an image or template swapped between legs that moves the workspace's real path). A host checks its lane by reading `env.canonicalPath(<workspace root>)` on two of its instances.
|
|
27
|
+
- **KL-4328-c — the same path on another machine is the same place** (not measured; as before).
|
|
28
|
+
- **KL-4328-d — an entry under an absolute key that an earlier engine already carried into a fork is still restored by the fork's rewind** (measured on a store v7.68.0 wrote).
|
|
29
|
+
- **KL-4328-e — entries under an absolute key do not travel with a session**: a fork's carry and an export leave them out (an export counts them in `absoluteEntriesOmitted`).
|
|
30
|
+
- **KL-4328-f — "nothing written when one file is refused" holds for what the plan can read.** A failure that only the write meets (a guarded write's precondition, an I/O error, a cancel) leaves a partial restore, every landed file named.
|
|
31
|
+
- **KL-4328-g — an envelope an engine ≤ 7.68.1 exported with an absolute `parentIdent` is refused whole at the import door** (`unsupported_format`; a parent directory that resolved outside the root through a link; rare).
|
|
32
|
+
- **KL-4328-i — a named directory that does not exist** refuses each file `recorded_elsewhere` (a directory deleted since is a legitimate answer, not a bad value).
|
|
33
|
+
- **KL-4328-j — two legs on two roots touching the same relative name for the first time at the same moment track it as one entry**: no wrong write (a rewind at the second root is refused), but the second file's edits have no restore point (measured at the store by the release review).
|
|
34
|
+
|
|
1
35
|
## 7.68.1 — 2026-11-13
|
|
2
36
|
|
|
3
37
|
### A tool approval an engine before 7.67.0 parked resumes when its tool names no peer — built-in, caller and host tools; an MCP tool's row is still asked again (#4424; behavior change: a v10 row that carries its tool identity without the word `raw_name_identity` is read as written when the identity recomputes from the row's own `toolName` and `contractId` for a source that names no peer; narrowing: none; widening: one, below, open to veto @server @cli @client-core; hard-breaking: none; closed sets: none; exports: none; wire: none)
|
|
@@ -39,7 +39,14 @@
|
|
|
39
39
|
* else, each handed to the model once, and a wake with nothing handed over ends `config.nothing_to_wake` before any model
|
|
40
40
|
* request. An engine without the word refuses the key (`config.spec_unknown_key`), so a shell that wakes a session gates
|
|
41
41
|
* on the word.
|
|
42
|
+
* - `file_history.recorded_place` — a file version records the directory it was recorded under (its absolute real path) and a
|
|
43
|
+
* rewind (`Runner.rewindFiles`, `rewindFilesTo`, `resumeAt` + `restoreFiles`) writes or deletes it only there: a version
|
|
44
|
+
* recorded under another directory is refused per file (`recorded_elsewhere`, with `recordedUnder`), one that records none
|
|
45
|
+
* (`place_unrecorded`) unless the rewind names where such versions were recorded (`unplacedHistoryRecordedUnder`, which an
|
|
46
|
+
* engine without the word refuses as an unknown key); a run that does not accept a partial restore moves nothing when any
|
|
47
|
+
* file would be refused (the restore is planned first); and the preview and the restore answer `files`, one row per file. A
|
|
48
|
+
* shell gates on the word, not on a version number.
|
|
42
49
|
*/
|
|
43
|
-
export declare const ENGINE_CAPABILITIES: readonly ["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat", "user_attachments.read_state", "task.wake"];
|
|
50
|
+
export declare const ENGINE_CAPABILITIES: readonly ["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat", "user_attachments.read_state", "task.wake", "file_history.recorded_place"];
|
|
44
51
|
/** One word of {@link ENGINE_CAPABILITIES}. */
|
|
45
52
|
export type EngineCapability = (typeof ENGINE_CAPABILITIES)[number];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
export const ENGINE_CAPABILITIES = Object.freeze(["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat", "user_attachments.read_state", "task.wake"]);
|
|
1
|
+
export const ENGINE_CAPABILITIES = Object.freeze(["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat", "user_attachments.read_state", "task.wake", "file_history.recorded_place"]);
|
|
@@ -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: {
|