@egildo/provenance 0.6.2 → 0.7.0

package/README.md

@@ -109,7 +109,9 @@ the edit lands in exactly the bytes of that value, every other byte untouched, a
 file changing on disk in the meantime ([the design](docs/write-back.md),
 [the editing spec](specs/editing/spec.md)). Writing is granted, never ambient. Since 0.6.0 it
 also inserts and deletes entries ([insert-delete](specs/insert-delete/spec.md)), and an edit staged on a file that a
-colleague is mid-way through saving waits for it to parse again. Format plug-ins come from outside —
+colleague is mid-way through saving waits for it to parse again. Since 0.7.0 a commit lands every file or
+none ([atomic-commit](specs/atomic-commit/spec.md)), and the staged edits can be saved and restored across a
+reload ([saveable-index](specs/saveable-index/spec.md)). Format plug-ins come from outside —
 Cascata's YAML and JSON writers are the first.
 
 What's next: **stamps** (outputs that carry their source address, so an edit on a rendered page

package/dist/index.d.ts

@@ -21,16 +21,31 @@ export interface Session {
     index(): readonly StagedEdit[];
     /** Drops the staged edit at `path`, or every staged edit of the source. */
     unstage(location: string, path?: string): Promise<void>;
+    /**
+     * The index as plain data (specs/saveable-index/spec.md): per staged source its location, base version and base
+     * bytes, and each edit's operation, path, value and status, in staging order. It survives a structured clone.
+     * Writing it anywhere is the embedder's.
+     */
+    save(): SavedIndex;
+    /**
+     * Stages a saved index again (specs/saveable-index/spec.md): per source, its edits are staged against the saved base
+     * bytes through the writer, in saved order, and then rebased onto the version the session holds. A source that
+     * already has staged edits, or whose bytes do not hash to the saved base, is refused and the others restored.
+     */
+    restore(saved: SavedIndex): Promise<RestoreReport>;
     /** The source's base with every staged edit spliced in, or `undefined` when none is staged. */
     preview(id: string): Promise<Preview | undefined>;
     /**
-     * Writes every source with staged edits, one file at a time and each atomically, rebasing first
-     * where the disk moved. Not atomic across files: the report says exactly what landed.
+     * Writes every source with staged edits, or none: each is checked and rebased first, and one that cannot
+     * be written (or an edit dropped on rebase) aborts the commit; a write that fails puts back the files
+     * already written. Each file is written atomically by the host. The report says exactly what landed.
      */
     commit(): Promise<CommitReport>;
     close(): void;
 }
 export interface CommitReport {
+    /** `committed`: every source landed (an empty index is committed). `aborted`: nothing did, bar any `unrestored` source. */
+    readonly outcome: "committed" | "aborted";
     /** One entry per source that had staged edits, in the order they were first staged. */
     readonly sources: readonly SourceCommit[];
 }
@@ -38,13 +53,15 @@ export interface SourceCommit {
     readonly source: string;
     readonly location: string;
     /**
-     * `written`; `refused` (outside every writable root, or the host has no write verb); `failed`
-     * (the host's reason; the edits are kept); `conflicted` (every edit's target was gone, so
-     * nothing was written).
+     * `written`; `refused` (outside every writable root, the host has no write verb, or the disk version does not
+     * open); `failed` (the host's reason; the edits are kept); `conflicted` (at least one edit was dropped on
+     * rebase, and `edits` lists the dropped ones); `aborted` (this source was fine, but another one stopped the
+     * commit, and `reason` names it; nothing of this source is on disk and its edits stay staged); `unrestored`
+     * (this commit wrote it and could not put it back; `reason` says why, its edits are on disk and left the index).
      */
-    readonly outcome: "written" | "refused" | "failed" | "conflicted";
+    readonly outcome: "written" | "refused" | "failed" | "conflicted" | "aborted" | "unrestored";
     readonly reason?: string;
-    /** The version written. */
+    /** The version this commit wrote (also for `unrestored`). */
     readonly version?: string;
     /** What became of each edit that was written or dropped; empty when refused or failed. */
     readonly edits: readonly {
@@ -108,6 +125,51 @@ export interface StagedEdit {
     /** Present while the source's newest version does not open: the writer's words. The edit waits against its base (FIX-001). */
     readonly waiting?: string;
 }
+/** What `session.save()` returns: the index as plain data, `Uint8Array` and `Map` the only objects in it. */
+export interface SavedIndex {
+    /** Which shape this is; `restore` refuses a number it does not know. */
+    readonly format: 1;
+    readonly sources: readonly {
+        /** The canonical location the session staged under. */
+        readonly location: string;
+        /** The base version the edits were staged against, and the bytes that hash to it. */
+        readonly base: string;
+        readonly bytes: Uint8Array;
+        readonly edits: readonly SavedEdit[];
+    }[];
+}
+/** One saved edit: the semantic half only. Byte ranges are made again by the writer on restore. */
+export interface SavedEdit {
+    readonly op: EditOperation["op"];
+    readonly path: string;
+    readonly value?: EditData;
+    readonly status: "staged" | "overrides";
+    readonly disk?: Uint8Array;
+}
+export interface RestoreReport {
+    /** `refused`: the whole save, for a `format` this version does not know (`reason` says so, and `sources` is empty). */
+    readonly outcome: "restored" | "refused";
+    readonly reason?: string;
+    /** One entry per saved source, in the save's order. */
+    readonly sources: readonly SourceRestore[];
+}
+export interface SourceRestore {
+    readonly location: string;
+    /**
+     * `refused`: the source is not in the session's graph, no writer claims it, it already has staged edits, its saved
+     * bytes do not hash to its base, or none of its edits could be staged; `reason` says which. Otherwise `restored`:
+     * what the rebase onto the session's version then did arrives as the usual `Change` notices.
+     */
+    readonly outcome: "restored" | "refused";
+    readonly reason?: string;
+    /** Per saved edit, in saved order; empty when the source was refused before its edits were tried. */
+    readonly edits: readonly {
+        readonly path: string;
+        readonly outcome: "restored" | "refused";
+        /** The writer's or the stage's words, as `StageResult` carries them. */
+        readonly reason?: string;
+    }[];
+}
 /** A source's base plus its staged edits, with the content hash that names it as a version. */
 export interface Preview {
     readonly bytes: Uint8Array;

package/dist/session.js

@@ -644,8 +644,8 @@ export async function openSession(options) {
             end: () => (manifest ??= finish()),
         };
     }
-    async function stageEdit(location, operation) {
-        const { path } = operation;
+    /** Whether the source at `location` can have edits staged: in the graph, readable, and claimed by a writer. */
+    async function stageable(location) {
         const key = await keyFor(location);
         const node = nodes.get(key);
         if (!node)
@@ -657,10 +657,22 @@ export async function openSession(options) {
         const writer = writers.find(w => w.claims(key));
         if (!writer)
             return { ok: false, reason: `no writer claims ${key}` };
+        return { ok: true, key, node, writer };
+    }
+    /**
+     * Stages one edit. `against` is a restore's (saved-index FR-006): the base to stage a source's first edit against
+     * in place of the one the session holds; a source already being staged keeps the base it has.
+     */
+    async function stageEdit(location, operation, against) {
+        const { path } = operation;
+        const found = await stageable(location);
+        if (!found.ok)
+            return found;
+        const { key, node, writer } = found;
         let staging = staged.get(key);
         // The base the session holds: the bytes of the version it last took in. A disk that has moved
         // since is the rebase's business, when the host reports it.
-        const base = staging?.base ?? ("bytes" in node ? node.bytes : undefined);
+        const base = staging?.base ?? against?.bytes ?? ("bytes" in node ? node.bytes : undefined);
         if (!base)
             return { ok: false, reason: `${key} was not read` };
         let doc = staging?.doc;
@@ -729,13 +741,53 @@ export async function openSession(options) {
         if (clash)
             return { ok: false, reason: `the edit overlaps the staged edit at ${clash.path}` };
         if (!staging)
-            staged.set(key, (staging = { writer, version: node.version, base, doc, edits: [] }));
+            staged.set(key, (staging = { writer, version: against?.version ?? node.version, base, doc, edits: [] }));
         const edit = { path, start, end, bytes, status: "staged", ...(effective.op === "remove" ? { op: "remove" } : { op: effective.op, value: effective.value }) };
         // Replaced, the edit goes last: the list is in the order edits were staged, which a rebase reads.
         staging.edits = [...staging.edits.filter(e => e.path !== path), edit];
         staging.preview = undefined;
         return { ok: true };
     }
+    /** Stages one saved source again against its saved base, then rebases it onto the version the session holds (saved-index FR-006). */
+    async function restoreSource(entry) {
+        const refused = (reason) => ({ location: entry.location, outcome: "refused", reason, edits: [] });
+        const found = await stageable(entry.location);
+        if (!found.ok)
+            return refused(found.reason);
+        const { key, node } = found;
+        if (staged.has(key))
+            return refused(`${key} already has staged edits`);
+        const held = "bytes" in node ? node.bytes : undefined;
+        if (!held)
+            return refused(`${key} was not read`);
+        if ((await sha256(entry.bytes)) !== entry.base)
+            return refused("the saved bytes do not hash to the saved base version");
+        const against = { version: entry.base, bytes: entry.bytes.slice() };
+        const edits = [];
+        for (const saved of entry.edits) {
+            const operation = saved.op === "remove" ? { op: "remove", path: saved.path } : saved.value === undefined ? undefined : { op: saved.op, path: saved.path, value: saved.value };
+            const result = operation === undefined ? { ok: false, reason: `a ${saved.op} needs a value` } : await stageEdit(entry.location, operation, against);
+            if (!result.ok) {
+                edits.push({ path: saved.path, outcome: "refused", reason: result.reason });
+                continue;
+            }
+            edits.push({ path: saved.path, outcome: "restored" });
+            // Its status is part of what was saved (FR-003): staging made it plain `staged`.
+            const put = staged.get(key)?.edits.find(e => e.path === saved.path);
+            if (put) {
+                put.status = saved.status;
+                if (saved.disk !== undefined)
+                    put.disk = saved.disk.slice();
+            }
+        }
+        const staging = staged.get(key);
+        if (!staging)
+            return { location: entry.location, outcome: "refused", reason: "none of its edits could be restored", edits };
+        // The session's version is not the saved base: the usual rebase, which says what it did through the notices.
+        if (node.version !== entry.base)
+            rebase(key, staging, held, node.version);
+        return { location: entry.location, outcome: "restored", edits };
+    }
     /** Whether a commit may write here: under a writable root, judged on whole segments of canonical locations. */
     async function isWritable(key) {
         const { separator, resolve } = host.paths;
@@ -747,10 +799,14 @@ export async function openSession(options) {
         }
         return false;
     }
-    /** Commits one source's staged edits (FR-009). The edits leave the index only when written or dropped. */
-    async function commitSource(key, staging, changed) {
+    /**
+     * Prepares one source for a commit (atomic-commit FR-001): the checks, the read, the rebase, and the bytes to write.
+     * Touches no disk. A source that cannot be written, or that lost an edit, comes back as the report entry that
+     * says so (`cause`); it stops the commit.
+     */
+    async function prepare(key, staging) {
         const source = idFor(key);
-        const nothing = (outcome, reason) => ({ source, location: key, outcome, reason, edits: [] });
+        const nothing = (outcome, reason) => ({ cause: { source, location: key, outcome, reason, edits: [] } });
         if (!(await isWritable(key)))
             return nothing("refused", `${key} is outside every writable root`);
         if (host.write === undefined)
@@ -765,23 +821,107 @@ export async function openSession(options) {
         if (staging.waiting !== undefined && staged.get(key) === staging)
             return nothing("refused", `the file on disk does not open: ${staging.waiting}`);
         const dropped = notices.slice(first).filter(n => n.outcome === "conflicted" && n.source === source);
-        const edits = dropped.map(n => ({ path: n.path, outcome: "conflicted", ...(n.reason === undefined ? {} : { reason: n.reason }), ...(n.detail === undefined ? {} : { detail: n.detail }) }));
         const remaining = staged.get(key);
-        if (!remaining)
-            return { source, location: key, outcome: "conflicted", edits };
+        if (dropped.length > 0 || !remaining) {
+            const edits = dropped.map(n => ({ path: n.path, outcome: "conflicted", ...(n.reason === undefined ? {} : { reason: n.reason }), ...(n.detail === undefined ? {} : { detail: n.detail }) }));
+            return { cause: { source, location: key, outcome: "conflicted", edits } };
+        }
         const bytes = splice(remaining.base, remaining.edits);
-        const written = await host.write(key, bytes);
-        if (!written.ok)
-            return nothing("failed", written.reason);
-        for (const e of remaining.edits)
-            edits.push(e.status === "overrides" && e.disk ? { path: e.path, outcome: "overrode", disk: e.disk } : { path: e.path, outcome: "written" });
-        staged.delete(key);
-        writtenKeys.push(key);
-        const fresh = await load(key, false);
-        if (versionOf(fresh) !== versionOf(nodes.get(key)))
-            changed.push(key);
-        nodes.set(key, fresh);
-        return { source, location: key, outcome: "written", version: await sha256(bytes), edits };
+        // Analysed now, before any write (FR-012, ruled): a handler that throws on the new text stops the commit with
+        // nothing on disk. The findings are held for this piece of work, so the load after the write hits the cache.
+        const handler = handlers.find(h => h.claims(key));
+        if (handler) {
+            let text;
+            try {
+                text = decoder.decode(bytes);
+            }
+            catch {
+                text = undefined;
+            }
+            if (text !== undefined)
+                findingsFor(handler, await sha256(bytes), text);
+        }
+        const edits = remaining.edits.map((e) => (e.status === "overrides" && e.disk ? { path: e.path, outcome: "overrode", disk: e.disk } : { path: e.path, outcome: "written" }));
+        return { key, source, bytes, disk: read.bytes, version: await sha256(bytes), edits };
+    }
+    /**
+     * Commits a set of staged sources, all or none (atomic-commit): prepare every one, and only if none is a cause write
+     * them in order; a failed write puts the written ones back, newest first. `commit()` passes the whole index;
+     * a group would pass its sources.
+     */
+    async function commitSources(entries, changed) {
+        const put = (key, bytes) => (host.write ? host.write(key, bytes) : Promise.resolve({ ok: false, reason: "the host cannot write" }));
+        const prepared = [];
+        for (const [key, staging] of entries)
+            prepared.push(await prepare(key, staging));
+        let stopper = prepared.flatMap(p => ("cause" in p ? [p.cause.location] : []))[0];
+        const wrote = [];
+        const fresh = new Map();
+        let failed;
+        if (stopper === undefined) {
+            for (const p of prepared) {
+                if ("cause" in p)
+                    continue;
+                const written = await put(p.key, p.bytes);
+                if (!written.ok) {
+                    failed = { source: p.source, location: p.key, outcome: "failed", reason: written.reason, edits: [] };
+                    stopper = p.key;
+                    break;
+                }
+                writtenKeys.push(p.key);
+                wrote.push(p);
+                // Analysed before the next write: a handler that throws on the new text stops the commit here, as it always did.
+                fresh.set(p.key, await load(p.key, false));
+            }
+        }
+        // Undo (FR-004): the host's own write, after checking the disk still holds what this commit wrote (ruling 6).
+        const unrestored = new Map();
+        if (failed) {
+            for (const p of wrote.reverse()) {
+                const was = await host.read(p.key);
+                let why;
+                if (!was.ok)
+                    why = `putting ${p.key} back failed: could not read it: ${was.reason}`;
+                else if ((await sha256(was.bytes)) !== p.version)
+                    why = `${p.key} was saved by someone else after this commit wrote it; left as it is`;
+                else {
+                    // ponytail: a colleague can still save between the read above and this write; closing it needs a host verb that writes only if unchanged (parked).
+                    const back = await put(p.key, p.disk);
+                    if (!back.ok)
+                        why = `putting ${p.key} back failed: ${back.reason}`;
+                }
+                if (why === undefined)
+                    writtenKeys.splice(writtenKeys.indexOf(p.key), 1);
+                else
+                    unrestored.set(p.key, why);
+            }
+        }
+        const sources = [];
+        for (const p of prepared) {
+            if ("cause" in p)
+                sources.push(p.cause);
+            else if (failed && failed.location === p.key)
+                sources.push(failed);
+            else if (unrestored.has(p.key))
+                sources.push({ source: p.source, location: p.key, outcome: "unrestored", reason: unrestored.get(p.key), version: p.version, edits: p.edits });
+            else if (stopper !== undefined)
+                sources.push({ source: p.source, location: p.key, outcome: "aborted", reason: `the commit was aborted by ${stopper}`, edits: [] });
+            else
+                sources.push({ source: p.source, location: p.key, outcome: "written", version: p.version, edits: p.edits });
+        }
+        // What is on disk now leaves the index and the node catches up (a source put back keeps its edits and its node).
+        for (const p of prepared) {
+            if ("cause" in p || !writtenKeys.includes(p.key))
+                continue;
+            staged.delete(p.key);
+            const node = fresh.get(p.key);
+            if (!node)
+                continue;
+            if (versionOf(node) !== versionOf(nodes.get(p.key)))
+                changed.push(p.key);
+            nodes.set(p.key, node);
+        }
+        return { outcome: stopper === undefined ? "committed" : "aborted", sources };
     }
     const session = {
         read,
@@ -822,6 +962,33 @@ export async function openSession(options) {
             ...(e.disk === undefined ? {} : { disk: e.disk }),
             ...(staging.waiting === undefined ? {} : { waiting: staging.waiting }),
         }))),
+        save: () => ({
+            format: 1,
+            sources: [...staged].map(([key, staging]) => ({
+                location: key,
+                base: staging.version,
+                bytes: staging.base.slice(),
+                edits: staging.edits.map(e => ({
+                    op: e.op,
+                    path: e.path,
+                    ...(e.value === undefined ? {} : { value: e.value }),
+                    status: e.status,
+                    ...(e.disk === undefined ? {} : { disk: e.disk.slice() }),
+                })),
+            })),
+        }),
+        restore(saved) {
+            let result = { outcome: "refused", reason: "the session is closed", sources: [] };
+            if (saved.format !== 1)
+                return Promise.resolve({ outcome: "refused", reason: `the saved index has format ${String(saved.format)}, and only format 1 is known`, sources: [] });
+            return serialize(async () => {
+                const sources = [];
+                for (const entry of saved.sources)
+                    sources.push(await restoreSource(entry));
+                result = { outcome: "restored", sources };
+                return report([]);
+            }).then(() => result);
+        },
         unstage: (location, path) => serialize(async () => {
             const key = await keyFor(location);
             const staging = staged.get(key);
@@ -861,13 +1028,10 @@ export async function openSession(options) {
             }).then(() => result);
         },
         commit() {
-            let result = { sources: [] };
+            let result = { outcome: "committed", sources: [] };
             return serialize(async () => {
                 const changed = [];
-                const sources = [];
-                for (const [key, staging] of [...staged])
-                    sources.push(await commitSource(key, staging, changed));
-                result = { sources };
+                result = await commitSources([...staged], changed);
                 return report(changed);
             }).then(() => result);
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@egildo/provenance",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Knows, for one rendered document, every source involved, how the sources depend on each other, and where each came from.",
   "type": "module",
   "license": "MIT",