@elaraai/e3-cloud-files 1.0.94 → 1.0.97

package/dist/src/sync/engine.js

@@ -6,109 +6,180 @@
  * The sync: what a source's files fill, brought up to date.
  *
  * One algorithm for a local repository and a deployed workspace alike: what
- * reads a bucket, what writes a workspace's inputs and what remembers the
- * files each input took are given to it ({@link FilesReader},
+ * reads a bucket, what writes a workspace's inputs and records, and what
+ * remembers the files each target took are given to it ({@link FilesReader},
  * {@link FilesWriter}, {@link FilesLedger}), so both behave the same.
  *
- * For each mapping: list the source, compare each file with what the input
- * took last (its ETag and size), read what is new or changed, write the input,
- * and remember what it took and the value it wrote. A file the same as before
- * is never read again, so a sync with nothing new reads nothing; an input
- * whose files are as they were is not written. A file over its shape's limit
- * is refused, named in the report, and never truncated; so is a file its
- * reader cannot read (archived, changed since it was listed, or closed to the
- * reader's access: {@link FilesUnreadableError}), the sync going on with the
- * rest, and the next sync trying it again. An input is remembered only once
- * it is written, so a sync that stops part way takes the rest next time.
+ * For each mapping: list the source, compare each file with what the target
+ * took last (its ETag and size), read what is new or changed, write the
+ * target, and remember what it took and the value it wrote or the commit it
+ * made. A file the same as before is never read again, so a sync with
+ * nothing new reads nothing; a target whose files are as they were is not
+ * written. A file over its limit is refused, named in the report, and never
+ * truncated; so is a file its reader cannot read (archived, changed since it
+ * was listed, or closed to the reader's access: {@link FilesUnreadableError}),
+ * the sync going on with the rest, and the next sync trying it again. A
+ * target is remembered only once it is written, so a sync that stops part
+ * way takes the rest next time.
+ *
+ * A `file` or `latest` mapping with a type takes its file in as the beast2
+ * value it holds: the file's header is read first, through a ranged read,
+ * and a file of another type, or no beast2, is refused before any other
+ * byte of it is read; then the writer takes the file in from a stream of its
+ * bytes ({@link FilesWriter.takeTyped}: never held whole, a collection by
+ * pieces), which may outlast a round and resume in the next, the file it was
+ * taking remembered by its key and ETag so no other file is resumed as it.
+ * A record's mapping seeds the record ({@link FilesWriter.seed}: its file is
+ * the record's first state, or its state again while nothing has mutated it
+ * since, or when the sync is asked to reset it); a mutation's feeds it
+ * ({@link FilesWriter.feed}): every new file under its prefix, in key order,
+ * each applied once, by the file's hash, and never again under another name.
  *
  * A folder's new and changed files are taken in batches of at most 256 MiB
  * ({@link FOLDER_BATCH_BYTES}): each batch is read, written and remembered
  * before the next is read, so a sync holds one batch of files, however large
- * the folder. A sync can stop between inputs and between a folder's batches
- * when asked ({@link syncFilesRound}, a cloud round handing over), and the
- * next takes the rest.
+ * the folder. A sync can stop between targets, between a folder's batches,
+ * between a feed's files and within a typed intake when asked
+ * ({@link syncFilesRound}, a cloud round handing over), and the next takes
+ * the rest.
  *
- * What an input took is trusted only while the input still holds the value
- * the sync wrote, and its mapping and its source's binding are those it was
- * taken under ({@link LedgerState}'s `under`): a deploy that resets the
- * workspace's inputs, anyone setting one by hand, a changed declaration or a
- * source bound elsewhere, and the next sync takes all of its files again, even
- * when a sync under the old declarations wrote its ledger after the change.
+ * What a target took is trusted only while its mapping and its source's
+ * binding are those it was taken under ({@link LedgerState}'s `under`) and,
+ * for an input, while the input still holds the value the sync wrote: a
+ * deploy that resets the workspace's inputs, anyone setting one by hand, a
+ * changed declaration or a source bound elsewhere, and the next sync takes
+ * all of its files again, even when a sync under the old declarations wrote
+ * its ledger after the change. A record's or mutation's ledger stays
+ * trusted as the record moves on: the record itself says what a seed may do.
  *
  * Mappings that share a source and a prefix list it once a round; a glob that
  * matches only the prefix's own folder lists that folder alone.
  *
  * @packageDocumentation
  */
-import { StringType, StructType, none, printFor, some, variant } from '@elaraai/east';
-import { FILES_FILE_MAX_BYTES, FILES_FOLDER_ENTRY_MAX_BYTES, FilesShapeType, filesProblemText, } from '@elaraai/e3-cloud-types';
+import { StringType, StructType, isTypeValueEqual, none, printFor, readBeast2HeaderType, some, variant } from '@elaraai/east';
+import { FILES_FILE_MAX_BYTES, FILES_FOLDER_ENTRY_MAX_BYTES, FILES_TYPED_VALUE_MAX_BYTES, FilesShapeType, filesProblemText, filesTargetText, sameFilesTarget, } from '@elaraai/e3-cloud-types';
+import { FilesShapeTypeV1 } from '../compat.js';
 import { globMatcher, matchesTopFolderOnly } from '../paths.js';
 /**
- * A file a reader cannot read, which a sync refuses and names in its report,
- * going on with the rest; the next sync tries it again. A reader throws it
- * for what is the file's own, never for its source as a whole: a file
- * archived, changed or gone since it was listed, or closed to the reader's
- * access. Any other error ends the round, which is tried again.
+ * Thrown by a reader for a file it cannot read, which the sync refuses and
+ * goes on past: archived, changed since it was listed, gone, or closed to
+ * the reader's access. Anything else a reader throws stops the sync.
  */
 export class FilesUnreadableError extends Error {
+    /** The file's key */
     key;
+    /** Why, as the refusal says it */
     reason;
-    /**
-     * @param key - The file's key, relative to the binding
-     * @param reason - Why, completing "'<key>' …"
-     */
     constructor(key, reason) {
         super(`${key} ${reason}`);
+        this.name = 'FilesUnreadableError';
         this.key = key;
         this.reason = reason;
-        this.name = 'FilesUnreadableError';
     }
 }
-/** What an input took before its first sync: nothing. */
-export const NO_LEDGER = { entries: new Map(), value: null, under: null };
+/** What a target took before its first sync: nothing. */
+export const NO_LEDGER = { entries: new Map(), value: null, under: null, commit: null, tried: null, taking: null };
 /**
- * What an input took, as a store keeps it (e3-cloud-types' `FilesLedgerType`).
+ * What a target took, as a store keeps it (e3-cloud-types' `FilesLedgerType`).
  *
  * @param state - What it took
  * @returns Its East value
  */
 export function ledgerValueOf(state) {
     return {
-        entries: new Map([...state.entries].map(([key, e]) => [key, { etag: e.etag, size: BigInt(e.size) }])),
+        entries: new Map([...state.entries].map(([key, e]) => [key, {
+                etag: e.etag,
+                size: BigInt(e.size),
+                sha256: e.sha256 === undefined ? none : some(e.sha256),
+                modified: e.modified === undefined ? none : some(e.modified),
+            }])),
         value: state.value === null ? none : some(state.value),
         under: state.under === null ? none : some(state.under),
+        commit: state.commit === null ? none : some(state.commit),
+        tried: state.tried === null ? none : some(state.tried),
+        taking: state.taking === null ? none : some({
+            key: state.taking.key,
+            etag: state.taking.etag,
+            sha256: state.taking.sha256 === null ? none : some(state.taking.sha256),
+            staging: state.taking.staging === null ? none : some(state.taking.staging),
+        }),
     };
 }
 /**
- * What an input took, from what a store keeps.
+ * What a target took, from what a store keeps.
  *
  * @param value - Its East value
  * @returns What it took
  */
 export function ledgerStateOf(value) {
     return {
-        entries: new Map([...value.entries].map(([key, e]) => [key, { etag: e.etag, size: Number(e.size) }])),
+        entries: new Map([...value.entries].map(([key, e]) => [key, {
+                etag: e.etag,
+                size: Number(e.size),
+                ...(e.sha256.type === 'some' && { sha256: e.sha256.value }),
+                ...(e.modified.type === 'some' && { modified: e.modified.value }),
+            }])),
         value: value.value.type === 'some' ? value.value.value : null,
         under: value.under.type === 'some' ? value.under.value : null,
+        commit: value.commit.type === 'some' ? value.commit.value : null,
+        tried: value.tried.type === 'some' ? value.tried.value : null,
+        taking: value.taking.type === 'some' ? {
+            key: value.taking.value.key,
+            etag: value.taking.value.etag,
+            sha256: value.taking.value.sha256.type === 'some' ? value.taking.value.sha256.value : null,
+            staging: value.taking.value.staging.type === 'some' ? value.taking.value.staging.value : null,
+        } : null,
     };
 }
+/**
+ * The key a target's ledger is kept under: an input's name, as the first
+ * version kept it; a record's under `records/`; a mutation's under
+ * `mutations/{record}/{mutation}` (two segments: a name may hold a dot).
+ *
+ * @param target - The target
+ * @returns Its ledger's key
+ */
+export function ledgerKeyOf(target) {
+    switch (target.type) {
+        case 'input': return target.value;
+        case 'record': return `records/${target.value}`;
+        case 'mutation': return `mutations/${target.value.record}/${target.value.mutation}`;
+    }
+}
 const printUnder = printFor(StructType({ url: StringType, shape: FilesShapeType }));
+const printUnderV1 = printFor(StructType({ url: StringType, shape: FilesShapeTypeV1 }));
+/** A shape as the first version printed it, when it names no type; null when it does. */
+function untypedShape(shape) {
+    switch (shape.type) {
+        case 'file': return shape.value.type.type === 'none' ? variant('file', { key: shape.value.key }) : null;
+        case 'latest': return shape.value.type.type === 'none' ? variant('latest', { prefix: shape.value.prefix, include: shape.value.include }) : null;
+        case 'folder': return variant('folder', shape.value);
+        case 'listing': return variant('listing', shape.value);
+    }
+}
 /**
- * What an input's files are taken under: its mapping's shape and where its
+ * What a target's files are taken under: its mapping's shape and where its
  * source is bound, as one text. A ledger taken under another is not trusted:
- * its keys may name other files, and its paths another folder's.
+ * its keys may name other files, and its paths another folder's. A shape
+ * that names no type prints as the first version printed it, so a ledger it
+ * wrote stays trusted.
  *
  * @param mapping - The mapping
  * @param binding - Its source's binding
  * @returns The text
  */
 export function takenUnder(mapping, binding) {
-    return printUnder({ url: binding.url, shape: mapping.shape });
+    const untyped = untypedShape(mapping.shape);
+    return untyped === null ? printUnder({ url: binding.url, shape: mapping.shape }) : printUnderV1({ url: binding.url, shape: untyped });
 }
 /** The most bytes of a folder's files a sync holds before it writes them, when not told: 256 MiB. */
 export const FOLDER_BATCH_BYTES = 256 * 1024 * 1024;
 /** The most files of a folder a sync writes at once. */
 const FOLDER_BATCH_FILES = 4096;
+/** The head of a typed file read first for its type: 64 KiB, then wider, to at most 16 MiB. */
+const HEAD_PROBE_BYTES = 64 * 1024;
+const HEAD_MAX_BYTES = 16 * 1024 * 1024;
 /** Thrown when a sync cannot start, naming every problem. */
 export class FilesSyncError extends Error {
     problems;
@@ -126,11 +197,24 @@ function stopping(sync) {
 }
 /** A tally of nothing. */
 function emptyTally() {
-    return { added: 0n, changed: 0n, removed: 0n, unchanged: 0n, refused: [], bytes: 0n, updated: false };
+    return { added: 0n, changed: 0n, removed: 0n, unchanged: 0n, refused: [], bytes: 0n, updated: false, taken: null, commit: null, kept: null, waiting: null };
 }
 /** A mapping's report, from its tally. */
 function reportOf(mapping, tally) {
-    return { input: mapping.input, ...tally };
+    return {
+        target: mapping.target,
+        added: tally.added,
+        changed: tally.changed,
+        removed: tally.removed,
+        unchanged: tally.unchanged,
+        refused: tally.refused,
+        bytes: tally.bytes,
+        updated: tally.updated,
+        taken: tally.taken === null ? none : some(tally.taken),
+        commit: tally.commit === null ? none : some(tally.commit),
+        kept: tally.kept === null ? none : some(tally.kept),
+        waiting: tally.waiting === null ? none : some(tally.waiting),
+    };
 }
 /** A key's path relative to a prefix. */
 function relative(prefix, key) {
@@ -141,8 +225,8 @@ function same(a, b) {
     return a !== undefined && b !== undefined && a.etag === b.etag && a.size === b.size;
 }
 /** A file's ledger entry. */
-function entryOf(object) {
-    return { etag: object.etag, size: object.size };
+function entryOf(object, sha256) {
+    return { etag: object.etag, size: object.size, modified: object.modified, ...(sha256 !== undefined && { sha256 }) };
 }
 /** A mapping's binding; checked to exist before a sync starts. */
 function bindingOf(mapping, options) {
@@ -156,15 +240,23 @@ function readerOf(sync, mapping) {
     return reader;
 }
 /**
- * What an input took last, trusted only while it holds the value the sync
- * wrote and was taken under the mapping and binding as they are.
+ * What a target took last, trusted only while it was taken under the mapping
+ * and binding as they are and, for an input, while the input holds the value
+ * the sync wrote.
  */
 async function before(sync, mapping) {
-    const [state, current] = await Promise.all([sync.options.ledger.read(mapping.input), sync.options.writer.current(mapping.input)]);
+    const { target } = mapping;
+    const state = await sync.options.ledger.read(ledgerKeyOf(target));
     const under = takenUnder(mapping, bindingOf(mapping, sync.options));
-    if (state.value !== null && state.value === current && state.under === under)
-        return { entries: state.entries, trusted: true, stale: false, under };
-    return { entries: new Map(), trusted: false, stale: current !== null || state.value !== null, under };
+    if (target.type === 'input') {
+        const current = await sync.options.writer.current(target.value);
+        if (state.value !== null && state.value === current && state.under === under)
+            return { state, entries: state.entries, trusted: true, stale: false, current, under };
+        return { state, entries: new Map(), trusted: false, stale: current !== null || state.value !== null, current, under };
+    }
+    if (state.under === under)
+        return { state, entries: state.entries, trusted: true, stale: false, current: null, under };
+    return { state, entries: new Map(), trusted: false, stale: false, current: null, under };
 }
 /** A listing's key among a round's: its source, its prefix and its depth. */
 function listingKey(source, prefix, topFolderOnly) {
@@ -221,8 +313,116 @@ async function selection(sync, mapping, prefix, include) {
     }
     return files;
 }
-/** Syncs a `file` or `latest` mapping to the one file it selects, or none. */
-async function syncOne(sync, mapping, chosen, missing) {
+/** A refusal of one file. */
+function refusal(key, reason) {
+    return { key, reason };
+}
+/** The SHA-256 of bytes the sync holds, hex: a push finds a file it put unchanged by it. */
+async function sha256Of(bytes) {
+    // A view over the bytes' own buffer, as the platform's digest takes one
+    const view = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', view);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** Asked for more of a file's head than was read. */
+class NeedMore extends Error {
+    needed;
+    constructor(needed) {
+        super(`needs ${needed} bytes of the head`);
+        this.needed = needed;
+    }
+}
+/**
+ * The root type a beast2 file's header declares, read through its head:
+ * 64 KiB, then wider only for a wide type section, never the file. Refused
+ * as no beast2 when the header is malformed, or wider than any type section
+ * is. What the sync and a push's reading of a file on disk share.
+ *
+ * @param size - The file's size
+ * @param readHead - Reads the file's first bytes, as many as asked
+ * @returns The declared root type, or why the file is no beast2
+ */
+export async function beast2HeaderTypeOf(size, readHead) {
+    if (size === 0)
+        return { reason: variant('not_beast2', 'it is empty') };
+    let head = new Uint8Array(0);
+    let want = Math.min(size, HEAD_PROBE_BYTES);
+    for (;;) {
+        if (want > head.length)
+            head = await readHead(want);
+        try {
+            const type = readBeast2HeaderType({
+                size,
+                read(offset, length) {
+                    if (offset + length > head.length)
+                        throw new NeedMore(offset + length);
+                    return head.subarray(offset, offset + length);
+                },
+            });
+            return { type };
+        }
+        catch (err) {
+            const more = err instanceof NeedMore ? err : (err instanceof Error && err.cause instanceof NeedMore ? err.cause : null);
+            if (more === null)
+                return { reason: variant('not_beast2', err instanceof Error ? err.message : String(err)) };
+            if (more.needed > size || more.needed > HEAD_MAX_BYTES)
+                return { reason: variant('not_beast2', 'its header is wider than any beast2 header') };
+            want = Math.min(size, Math.max(more.needed, head.length * 4));
+        }
+    }
+}
+/** The root type a typed file's beast2 header declares, through a range of its head from the reader; a refusal names the file. */
+async function headerType(reader, file) {
+    try {
+        return await beast2HeaderTypeOf(file.size, (bytes) => reader.readRange(file, 0, bytes));
+    }
+    catch (err) {
+        if (err instanceof FilesUnreadableError)
+            return { reason: variant('unreadable', err.reason) };
+        throw err;
+    }
+}
+/**
+ * Whether a type is a collection's: an Array, Set or Dict root, which beast2
+ * stores in segments and e3 takes in by pieces, of any size.
+ *
+ * @param type - The type
+ * @returns Whether it is a collection
+ */
+export function isCollectionType(type) {
+    return type.type === 'Array' || type.type === 'Set' || type.type === 'Dict';
+}
+/** Whether two type values are the same type, as East compares types. */
+function sameType(a, b) {
+    return isTypeValueEqual(a, b);
+}
+/**
+ * A typed file's header held to the mapping's type, and its size to the
+ * limit of a value that is no collection: the refusal, or null when it fits.
+ */
+async function typedRefusal(reader, file, type) {
+    if (!isCollectionType(type) && file.size > FILES_TYPED_VALUE_MAX_BYTES) {
+        return refusal(file.key, variant('too_large', { size: BigInt(file.size), limit: BigInt(FILES_TYPED_VALUE_MAX_BYTES) }));
+    }
+    const header = await headerType(reader, file);
+    if ('reason' in header)
+        return refusal(file.key, header.reason);
+    if (!sameType(header.type, type))
+        return refusal(file.key, variant('type_mismatch', { expected: type, actual: header.type }));
+    return null;
+}
+/** The chosen file of a `file` or `latest` mapping, or why there is none. */
+async function chooseOne(sync, mapping, shape) {
+    if (shape.type === 'file') {
+        return { chosen: await readerOf(sync, mapping).stat(shape.value.key), missing: refusal(shape.value.key, variant('missing', 'no such file')) };
+    }
+    const { prefix } = shape.value;
+    const files = await selection(sync, mapping, prefix, shape.value.include.type === 'some' ? shape.value.include.value : null);
+    const greatest = [...files.keys()].sort().at(-1);
+    return { chosen: greatest === undefined ? null : files.get(greatest), missing: refusal(prefix, variant('missing', 'no file under it matches')) };
+}
+/** Syncs a `file` or `latest` input mapping with no type to the one file it selects, as a `Blob`, or none. */
+async function syncOne(sync, mapping, input, chosen, missing) {
     const { options } = sync;
     const report = emptyTally();
     if (chosen === null) {
@@ -235,7 +435,7 @@ async function syncOne(sync, mapping, chosen, missing) {
         return reportOf(mapping, report);
     }
     if (chosen.size > FILES_FILE_MAX_BYTES) {
-        report.refused.push({ key: chosen.key, reason: `is ${chosen.size} bytes, over the ${FILES_FILE_MAX_BYTES} a file input takes` });
+        report.refused.push(refusal(chosen.key, variant('too_large', { size: BigInt(chosen.size), limit: BigInt(FILES_FILE_MAX_BYTES) })));
         return reportOf(mapping, report);
     }
     const taken = () => {
@@ -258,15 +458,279 @@ async function syncOne(sync, mapping, chosen, missing) {
         if (!(err instanceof FilesUnreadableError))
             throw err;
         // The input keeps what it holds, and the next sync tries the file again
-        report.refused.push({ key: chosen.key, reason: err.reason });
+        report.refused.push(refusal(chosen.key, variant('unreadable', err.reason)));
         return reportOf(mapping, report);
     }
-    const value = await options.writer.setFile(mapping.input, bytes);
-    await options.ledger.write(mapping.input, { entries: new Map([[chosen.key, entryOf(chosen)]]), value, under: prior.under });
+    const value = await options.writer.setFile(input, bytes);
+    await options.ledger.write(ledgerKeyOf(mapping.target), { ...NO_LEDGER, entries: new Map([[chosen.key, entryOf(chosen, await sha256Of(bytes))]]), value, under: prior.under });
     taken();
     sync.progressed = true;
     return reportOf(mapping, report);
 }
+/**
+ * Syncs a typed `file` or `latest` input mapping: the file's header read
+ * first and held to the mapping's type, then the file taken in by the writer
+ * from a stream of its bytes, which may stop at the round's end and resume
+ * in the next (the same file alone: by its key and ETag). The same bytes
+ * under a new ETag are taken through the store's memo: the input's value is
+ * as it was, and nothing downstream moves.
+ */
+async function syncTyped(sync, mapping, input, type, chosen, missing) {
+    const { options } = sync;
+    const report = emptyTally();
+    const prior = await before(sync, mapping);
+    const key = ledgerKeyOf(mapping.target);
+    // An intake left under way is resumed only for the same file: its key and
+    // ETag; one left for a file since replaced or gone is forgotten
+    const taking = prior.state.taking;
+    const resuming = taking !== null && chosen !== null && taking.key === chosen.key && taking.etag === chosen.etag ? taking : null;
+    const forget = async () => {
+        if (taking !== null && resuming === null)
+            await options.ledger.write(key, { ...prior.state, taking: null });
+    };
+    if (chosen === null) {
+        report.refused.push(missing);
+        await forget();
+        return reportOf(mapping, report);
+    }
+    const previous = prior.entries.get(chosen.key);
+    if (same(previous, entryOf(chosen)) && resuming === null) {
+        report.unchanged = 1n;
+        await forget();
+        return reportOf(mapping, report);
+    }
+    const counted = () => {
+        if (!prior.trusted && !prior.stale)
+            report.added = 1n;
+        else
+            report.changed = 1n;
+        report.bytes = BigInt(chosen.size);
+    };
+    if (options.dryRun === true) {
+        counted();
+        report.updated = true;
+        return reportOf(mapping, report);
+    }
+    const reader = readerOf(sync, mapping);
+    // The header first: a file of another type, or no beast2, costs no other byte
+    const refused = await typedRefusal(reader, chosen, type);
+    if (refused !== null) {
+        report.refused.push(refused);
+        if (taking !== null)
+            await options.ledger.write(key, { ...prior.state, taking: null });
+        return reportOf(mapping, report);
+    }
+    const result = await options.writer.takeTyped(input, chosen, type, reader, {
+        ...(resuming !== null && { resume: resuming }),
+        ...(options.signal !== undefined && { signal: options.signal }),
+    });
+    switch (result.status) {
+        case 'refused':
+            report.refused.push(refusal(chosen.key, result.reason));
+            // A resumed intake refused: nothing to resume any more
+            if (taking !== null)
+                await options.ledger.write(key, { ...prior.state, taking: null });
+            return reportOf(mapping, report);
+        case 'yielded':
+            // Remembered where it stopped, under the ledger as it was, so the next
+            // round resumes it; stopped before anything was kept, the next starts again
+            if (result.taking !== null)
+                await options.ledger.write(key, { ...prior.state, under: prior.state.under ?? prior.under, taking: result.taking });
+            else if (taking !== null)
+                await options.ledger.write(key, { ...prior.state, taking: null });
+            sync.progressed = true;
+            sync.yielded = true;
+            return reportOf(mapping, report);
+        case 'taken': {
+            counted();
+            report.updated = prior.current !== result.hash;
+            report.taken = result.taken;
+            await options.ledger.write(key, { ...NO_LEDGER, entries: new Map([[chosen.key, entryOf(chosen, result.sha256)]]), value: result.hash, under: prior.under });
+            sync.progressed = true;
+            return reportOf(mapping, report);
+        }
+    }
+}
+/** How many mutations a record has taken since its seed, in words. */
+function mutatedWords(sinceSeed) {
+    if (sinceSeed === null)
+        return 'the record has a state Files did not seed';
+    return `${sinceSeed} ${sinceSeed === 1 ? 'mutation' : 'mutations'} since the seed`;
+}
+/**
+ * Syncs a record's mapping: its file is the record's first state while the
+ * record is pending; its state again while nothing has mutated it since its
+ * seed, or when the sync is asked to reset it; kept otherwise.
+ */
+async function syncSeed(sync, mapping, record, type, chosen, missing) {
+    const { options } = sync;
+    const report = emptyTally();
+    const { writer } = options;
+    if (writer.recordState === undefined || writer.seed === undefined) {
+        report.refused.push(refusal(chosen?.key ?? '', variant('other', 'records cannot be seeded here')));
+        return reportOf(mapping, report);
+    }
+    if (chosen === null) {
+        report.refused.push(missing);
+        return reportOf(mapping, report);
+    }
+    const prior = await before(sync, mapping);
+    const previous = prior.entries.get(chosen.key);
+    const state = await writer.recordState(record);
+    const unchanged = same(previous, entryOf(chosen));
+    // A record holding the seed the ledger made: its file as it was is nothing new
+    if (!state.pending && unchanged && prior.state.commit === state.head) {
+        report.unchanged = 1n;
+        return reportOf(mapping, report);
+    }
+    const reset = (options.reset ?? []).includes(record);
+    if (!state.pending && !reset && (state.sinceSeed === null || state.sinceSeed > 0)) {
+        // Seeded, then mutated: the file waits for a reset
+        report.unchanged = unchanged ? 1n : 0n;
+        report.kept = mutatedWords(state.sinceSeed);
+        return reportOf(mapping, report);
+    }
+    if (!state.pending && unchanged && !reset) {
+        // The seed's file as it was, and the record at its seed: nothing to do
+        report.unchanged = 1n;
+        return reportOf(mapping, report);
+    }
+    const counted = () => {
+        if (previous === undefined)
+            report.added = 1n;
+        else
+            report.changed = 1n;
+        report.bytes = BigInt(chosen.size);
+    };
+    if (options.dryRun === true) {
+        counted();
+        report.updated = true;
+        report.commit = state.pending ? '$init' : '$seed';
+        return reportOf(mapping, report);
+    }
+    const reader = readerOf(sync, mapping);
+    const refused = await typedRefusal(reader, chosen, type);
+    if (refused !== null) {
+        report.refused.push(refused);
+        return reportOf(mapping, report);
+    }
+    const result = await writer.seed(record, chosen, type, reader, { genesis: state.pending, ...(options.signal !== undefined && { signal: options.signal }) });
+    if (result.status === 'refused') {
+        report.refused.push(refusal(chosen.key, result.reason));
+        return reportOf(mapping, report);
+    }
+    counted();
+    report.updated = true;
+    report.commit = result.commit;
+    report.taken = { key: chosen.key, type, rows: result.rows === null ? none : some(result.rows), how: variant('carried', null) };
+    await options.ledger.write(ledgerKeyOf(mapping.target), {
+        ...NO_LEDGER, entries: new Map([[chosen.key, entryOf(chosen, result.sha256)]]), under: prior.under, commit: result.commit,
+    });
+    sync.progressed = true;
+    return reportOf(mapping, report);
+}
+/**
+ * Syncs a mutation's mapping: every new file it selects (one key, or every
+ * file under its prefix its glob matches, in key order) is applied once
+ * through the mutation, by the file's hash, and never again under another
+ * name; a file the mutation refused is not tried again until it changes,
+ * and the files after it wait; a record with no state yet makes the feed
+ * wait, before any file is read. The round may stop between files.
+ */
+async function syncFeed(sync, mapping, record, mutation, type, files, missing) {
+    const { options } = sync;
+    const report = emptyTally();
+    const { writer } = options;
+    if (writer.feed === undefined) {
+        report.refused.push(refusal(files[0]?.key ?? '', variant('other', 'mutations cannot be fed here')));
+        return reportOf(mapping, report);
+    }
+    if (missing !== null) {
+        report.refused.push(missing);
+        return reportOf(mapping, report);
+    }
+    const prior = await before(sync, mapping);
+    const entries = new Map(prior.entries);
+    const applied = new Set([...prior.entries.values()].flatMap((e) => (e.sha256 === undefined ? [] : [e.sha256])));
+    let commit = prior.state.commit;
+    const key = ledgerKeyOf(mapping.target);
+    const fresh = files.filter((file) => !same(prior.entries.get(file.key), entryOf(file)));
+    report.unchanged = BigInt(files.length - fresh.length);
+    if (fresh.length === 0) {
+        const last = files.at(-1);
+        if (last !== undefined && prior.state.tried !== null && prior.state.tried === prior.entries.get(last.key)?.sha256)
+            report.kept = 'the mutation refused it earlier: not tried again until the file changes';
+        return reportOf(mapping, report);
+    }
+    for (const file of fresh) {
+        if (file.size > FILES_TYPED_VALUE_MAX_BYTES) {
+            report.refused.push(refusal(file.key, variant('too_large', { size: BigInt(file.size), limit: BigInt(FILES_TYPED_VALUE_MAX_BYTES) })));
+            break;
+        }
+    }
+    if (report.refused.length > 0)
+        return reportOf(mapping, report);
+    if (options.dryRun === true) {
+        for (const file of fresh) {
+            if (prior.entries.has(file.key))
+                report.changed += 1n;
+            else
+                report.added += 1n;
+            report.bytes += BigInt(file.size);
+        }
+        report.updated = true;
+        return reportOf(mapping, report);
+    }
+    // A record with no state yet: nothing is read for it
+    if (writer.recordState !== undefined && (await writer.recordState(record)).pending) {
+        report.waiting = 'the record has no state yet';
+        return reportOf(mapping, report);
+    }
+    const reader = readerOf(sync, mapping);
+    let first = true;
+    for (const file of fresh) {
+        if (!first && stopping(sync))
+            break;
+        first = false;
+        const refused = await typedRefusal(reader, file, type);
+        if (refused !== null) {
+            report.refused.push(refused);
+            break;
+        }
+        const result = await writer.feed(record, mutation, file, type, reader, { applied, ...(options.signal !== undefined && { signal: options.signal }) });
+        if (result.status === 'waiting') {
+            report.waiting = result.reason;
+            break;
+        }
+        if (result.status === 'refused') {
+            // Remembered as tried: the next sync tries it again only once the file changes
+            report.refused.push(refusal(file.key, result.reason));
+            entries.set(file.key, entryOf(file, result.sha256));
+            await options.ledger.write(key, { ...prior.state, entries: new Map(entries), under: prior.under, commit, tried: result.sha256 });
+            sync.progressed = true;
+            break;
+        }
+        entries.set(file.key, entryOf(file, result.sha256));
+        applied.add(result.sha256);
+        if (result.status === 'committed') {
+            commit = result.commit;
+            report.commit = result.commit;
+            report.updated = true;
+            if (prior.entries.has(file.key))
+                report.changed += 1n;
+            else
+                report.added += 1n;
+            report.bytes += BigInt(file.size);
+        }
+        else {
+            // Its bytes applied before, under another name: remembered, nothing more
+            report.unchanged += 1n;
+        }
+        await options.ledger.write(key, { ...NO_LEDGER, entries: new Map(entries), under: prior.under, commit });
+        sync.progressed = true;
+    }
+    return reportOf(mapping, report);
+}
 /**
  * Syncs a `folder` mapping: what is new or changed read and written, what is
  * gone taken out. The files to read are taken in batches, each written and
@@ -276,7 +740,7 @@ async function syncOne(sync, mapping, chosen, missing) {
  * cannot read is refused: what the input held of it stays, and so does what
  * the ledger remembers of it, so the next sync tries it again.
  */
-async function syncFolder(sync, mapping, prefix, files) {
+async function syncFolder(sync, mapping, input, prefix, files) {
     const { options } = sync;
     const report = emptyTally();
     const prior = await before(sync, mapping);
@@ -298,7 +762,7 @@ async function syncFolder(sync, mapping, prefix, files) {
             continue;
         }
         if (object.size > FILES_FOLDER_ENTRY_MAX_BYTES) {
-            report.refused.push({ key: object.key, reason: `is ${object.size} bytes, over the ${FILES_FOLDER_ENTRY_MAX_BYTES} a folder's file may be` });
+            report.refused.push(refusal(object.key, variant('too_large', { size: BigInt(object.size), limit: BigInt(FILES_FOLDER_ENTRY_MAX_BYTES) })));
             // What the input held of it, if anything, stays
             if (previous !== undefined)
                 staying.add(object.key);
@@ -327,6 +791,7 @@ async function syncFolder(sync, mapping, prefix, files) {
     const reader = readerOf(sync, mapping);
     const entries = new Map(prior.entries);
     const batches = batched(toRead, options.batchBytes ?? FOLDER_BATCH_BYTES);
+    const key = ledgerKeyOf(mapping.target);
     let first = true;
     for (const batch of batches.length === 0 ? [[]] : batches) {
         if (!first && stopping(sync))
@@ -335,35 +800,36 @@ async function syncFolder(sync, mapping, prefix, files) {
         const read = [];
         for (const object of batch) {
             try {
-                set.set(relative(prefix, object.key), await reader.read(object));
-                read.push(object);
+                const bytes = await reader.read(object);
+                set.set(relative(prefix, object.key), bytes);
+                read.push({ object, sha256: await sha256Of(bytes) });
             }
             catch (err) {
                 if (!(err instanceof FilesUnreadableError))
                     throw err;
-                report.refused.push({ key: object.key, reason: err.reason });
+                report.refused.push(refusal(object.key, variant('unreadable', err.reason)));
             }
         }
-        const remove = first ? new Set(gone.map((key) => relative(prefix, key))) : new Set();
+        const remove = first ? new Set(gone.map((k) => relative(prefix, k))) : new Set();
         const makes = first && fresh;
         // A batch whose files were all refused changes nothing: no write
         if (set.size > 0 || remove.size > 0 || makes) {
-            const value = await options.writer.updateFolder(mapping.input, { set, remove, fresh: makes });
+            const value = await options.writer.updateFolder(input, { set, remove, fresh: makes });
             if (first) {
-                for (const key of gone)
-                    entries.delete(key);
+                for (const k of gone)
+                    entries.delete(k);
                 report.removed = BigInt(gone.length);
             }
-            for (const object of read) {
+            for (const { object, sha256 } of read) {
                 if (prior.entries.has(object.key))
                     report.changed += 1n;
                 else
                     report.added += 1n;
                 report.bytes += BigInt(object.size);
-                entries.set(object.key, entryOf(object));
+                entries.set(object.key, entryOf(object, sha256));
             }
             report.updated = true;
-            await options.ledger.write(mapping.input, { entries: new Map(entries), value, under: prior.under });
+            await options.ledger.write(key, { ...NO_LEDGER, entries: new Map(entries), value, under: prior.under });
             sync.progressed = true;
         }
         first = false;
@@ -371,7 +837,7 @@ async function syncFolder(sync, mapping, prefix, files) {
     return reportOf(mapping, report);
 }
 /** Syncs a `listing` mapping: written whole whenever any file is new, changed or gone. */
-async function syncListing(sync, mapping, files) {
+async function syncListing(sync, mapping, input, files) {
     const { options } = sync;
     const report = emptyTally();
     const prior = await before(sync, mapping);
@@ -394,33 +860,74 @@ async function syncListing(sync, mapping, files) {
     report.updated = report.added > 0n || report.changed > 0n || report.removed > 0n || !prior.trusted;
     if (options.dryRun === true || !report.updated)
         return reportOf(mapping, report);
-    const value = await options.writer.setListing(mapping.input, rows);
-    await options.ledger.write(mapping.input, { entries: after, value, under: prior.under });
+    const value = await options.writer.setListing(input, rows);
+    await options.ledger.write(ledgerKeyOf(mapping.target), { ...NO_LEDGER, entries: after, value, under: prior.under });
     sync.progressed = true;
     return reportOf(mapping, report);
 }
+/** The mappings a sync takes: every one, or those of the targets named. */
+function wantedMappings(options) {
+    const { targets } = options;
+    if (targets === undefined)
+        return [...options.manifest.mappings];
+    const declared = options.manifest.mappings;
+    const unknown = targets.filter((t) => !declared.some((m) => sameFilesTarget(m.target, t)));
+    if (unknown.length > 0) {
+        throw new Error(`No declaration fills ${unknown.map((t) => `'${filesTargetText(t)}'`).join(', ')}: the declarations fill ${declared.map((m) => filesTargetText(m.target)).join(', ') || 'nothing'}`);
+    }
+    return declared.filter((m) => targets.some((t) => sameFilesTarget(m.target, t)));
+}
+/** Syncs one mapping, by its target and shape. */
+async function syncMapping(sync, mapping) {
+    const { target, shape } = mapping;
+    if (shape.type === 'folder' || shape.type === 'listing') {
+        // Held to inputs by the checks; a record's or mutation's never reaches here
+        const input = target.type === 'input' ? target.value : filesTargetText(target);
+        const { prefix } = shape.value;
+        const files = await selection(sync, mapping, prefix, shape.value.include.type === 'some' ? shape.value.include.value : null);
+        return shape.type === 'folder' ? syncFolder(sync, mapping, input, prefix, files) : syncListing(sync, mapping, input, files);
+    }
+    const type = shape.value.type.type === 'some' ? shape.value.type.value : null;
+    if (target.type === 'mutation') {
+        // Every file the shape selects, in key order: each new one is applied
+        if (shape.type === 'file') {
+            const chosen = await readerOf(sync, mapping).stat(shape.value.key);
+            return syncFeed(sync, mapping, target.value.record, target.value.mutation, type, chosen === null ? [] : [chosen], chosen === null ? refusal(shape.value.key, variant('missing', 'no such file')) : null);
+        }
+        const { prefix } = shape.value;
+        const files = await selection(sync, mapping, prefix, shape.value.include.type === 'some' ? shape.value.include.value : null);
+        const ordered = [...files.keys()].sort().map((path) => files.get(path));
+        return syncFeed(sync, mapping, target.value.record, target.value.mutation, type, ordered, ordered.length === 0 ? refusal(prefix, variant('missing', 'no file under it matches')) : null);
+    }
+    const { chosen, missing } = await chooseOne(sync, mapping, shape);
+    switch (target.type) {
+        case 'input':
+            return type === null ? syncOne(sync, mapping, target.value, chosen, missing) : syncTyped(sync, mapping, target.value, type, chosen, missing);
+        case 'record':
+            return syncSeed(sync, mapping, target.value, type, chosen, missing);
+    }
+}
 /**
- * Brings each mapping's input up to date with its source's files, stopping
- * when asked between inputs or between a folder's batches: one round of a
- * sync that hands over, as the platform's do. What it stopped before, the
- * next round takes.
+ * Brings each mapping's target up to date with its source's files, stopping
+ * when asked between targets, between a folder's batches, between a feed's
+ * files or within a typed intake: one round of a sync that hands over, as
+ * the platform's do. What it stopped before, the next round takes. Records
+ * are seeded before mutations are fed, so a record seeded and fed in one
+ * sync takes both, in that order.
  *
  * @param options - The declarations, the bindings, what reads, writes and remembers, and when to stop
- * @returns What it did, per input it reached, and whether it stopped before the end
+ * @returns What it did, per target it reached, and whether it stopped before the end
  * @throws {FilesSyncError} When a mapping's source is not bound, before
  *   anything is read
- * @throws {Error} When an input named is not one a declaration fills
+ * @throws {Error} When a target named is not one a declaration fills
  */
 export async function syncFilesRound(options) {
     const now = options.now ?? (() => new Date());
     const started = now();
-    const declared = new Set(options.manifest.mappings.map((m) => m.input));
-    const unknown = (options.inputs ?? []).filter((input) => !declared.has(input));
-    if (unknown.length > 0) {
-        throw new Error(`No declaration fills ${unknown.map((i) => `'${i}'`).join(', ')}: the inputs files fill are ${[...declared].join(', ') || 'none'}`);
-    }
-    const wanted = options.inputs === undefined ? null : new Set(options.inputs);
-    const mappings = options.manifest.mappings.filter((m) => wanted === null || wanted.has(m.input));
+    const wanted = wantedMappings(options);
+    // Seeds before feeds: a feed on a record seeded in the same sync finds its state
+    const order = (m) => (m.target.type === 'mutation' ? 1 : 0);
+    const mappings = wanted.map((m, i) => ({ m, i })).sort((a, b) => order(a.m) - order(b.m) || a.i - b.i).map(({ m }) => m);
     const bound = new Set(options.bindings.map((b) => b.source));
     const problems = [...new Set(mappings.map((m) => m.source))]
         .filter((source) => !bound.has(source))
@@ -441,39 +948,21 @@ export async function syncFilesRound(options) {
     for (const mapping of mappings) {
         if (stopping(sync))
             break;
-        const shape = mapping.shape;
-        if (shape.type === 'file') {
-            const missing = { key: shape.value.key, reason: 'no such file' };
-            reports.push(await syncOne(sync, mapping, await readerOf(sync, mapping).stat(shape.value.key), missing));
-            continue;
-        }
-        const { prefix } = shape.value;
-        const files = await selection(sync, mapping, prefix, shape.value.include.type === 'some' ? shape.value.include.value : null);
-        switch (shape.type) {
-            case 'latest': {
-                const greatest = [...files.keys()].sort().at(-1);
-                const missing = { key: prefix, reason: 'no file under it matches' };
-                reports.push(await syncOne(sync, mapping, greatest === undefined ? null : files.get(greatest), missing));
-                break;
-            }
-            case 'folder':
-                reports.push(await syncFolder(sync, mapping, prefix, files));
-                break;
-            case 'listing':
-                reports.push(await syncListing(sync, mapping, files));
-                break;
-        }
+        reports.push(await syncMapping(sync, mapping));
+        if (sync.yielded)
+            break;
     }
     return { report: { started, finished: now(), dryRun: options.dryRun === true, mappings: reports }, yielded: sync.yielded };
 }
 /**
- * Brings each mapping's input up to date with its source's files, to the end.
+ * Brings each mapping's target up to date with its source's files, to the
+ * end.
  *
  * @param options - The declarations, the bindings, and what reads, writes and remembers
  * @returns What it did, per mapping
  * @throws {FilesSyncError} When a mapping's source is not bound, before
  *   anything is read
- * @throws {Error} When an input named is not one a declaration fills
+ * @throws {Error} When a target named is not one a declaration fills
  */
 export async function syncFiles(options) {
     return (await syncFilesRound(options)).report;