@superbee/core 0.2.0-pre.40 → 0.2.0-pre.42

package/dist/document-transfer.js

@@ -11,8 +11,17 @@
  * all-or-nothing. It writes the Promotion record first (`promotion_state: applying`, with the
  * whole mapping) as the journal, then creates every document with an expect-absent write, then
  * marks the record `applied`. A failed write stops the apply and leaves the record at `applying`;
- * {@link resumeDocumentTransfer} is the one recovery path. Nothing here deletes or overwrites a
- * document.
+ * {@link resumeDocumentTransfer} is the one recovery path. Nothing here deletes a document, and only a
+ * refresh replaces one.
+ *
+ * A refresh ({@link planDocumentRefresh}, {@link applyDocumentRefresh}) brings the copies an
+ * applied record names up to date with their sources. The record's `source_version` and
+ * `target_version` per entry are the baseline: a changed source is an update, and a copy whose
+ * version differs from `target_version` was edited in the target and is a conflict unless the
+ * caller names it to overwrite or skip. The record is the journal again (`promotion_state:
+ * refreshing` with the pending rows), every copy is replaced under a hard compare-and-swap on the
+ * version the plan saw, and {@link resumeDocumentTransfer} finishes an interrupted refresh. A
+ * refresh never creates, deletes or picks up documents the record does not already name.
  *
  * v1 caveats: resume writes the remaining documents even if the target has since dropped a Kind
  * that governed them. Reference-style link definitions (`[x]: ../f.md`) are copied unchanged and
@@ -21,18 +30,20 @@
  * Storage-neutral: the source is a {@link BundleBinding} (any backend), the target is written
  * through the shared document mutation policy, and no Node module is imported.
  */
+import { computeDroppedLinks, outboundLinks } from "./body-replace-guards.js";
 import { backendFor, readBundleOkfVersion, readDocVersioned } from "./bundle-ops.js";
 import { BUNDLE_NAME_DOC_ID, declaredBundleId, DEPENDENCIES_DOC_ID, parseDependencies, } from "./dependencies.js";
 import { DocumentNotFoundError, mutateDocument, prepareDocumentMutationCandidate } from "./document-mutation.js";
 import { readManyExisting } from "./engine.js";
 import { FilesystemIdentityAliasError, InvalidInputError, OkfActorError } from "./errors.js";
-import { foldIdentityPath } from "./identity-fold.js";
+import { foldPath } from "./path-fold.js";
 import { loadKinds } from "./kinds-load.js";
 import { CONVENTIONS_PREFIX } from "./kinds.js";
 import { emitLinkHref } from "./link-emit.js";
 import { extractMarkdownLinkSpans, maskMarkdownCode, normalizeSegments, resolveConceptId, rewriteMarkdownLinks } from "./links.js";
 import { isOkfActor } from "./okf-actor.js";
-import { assertSafeConceptId, compareStorageKeys, isReservedFile, pathFromConceptId, trimTrailingSlashes } from "./paths.js";
+import { SUPERBEE_UPDATED_BY_FIELD } from "./mutation-attribution.js";
+import { assertCanonicalNewDocumentId, assertSafeConceptId, compareStorageKeys, isReservedFile, pathFromConceptId, trimTrailingSlashes } from "./paths.js";
 import { isQualifiedHref, parseQualifiedHref, qualifiedHref } from "./qualified-links.js";
 import { sha256HexOfUtf8 } from "./sha256.js";
 import { VersionConflict } from "./versioning.js";
@@ -70,16 +81,19 @@ export class TransferInterrupted extends Error {
     recordId;
     written;
     pending;
+    /** The state the record was left in: `applying` for an import, `refreshing` for a refresh. */
+    state;
     cause;
-    constructor(recordId, written, pending, cause) {
+    constructor(recordId, written, pending, cause, state = "applying") {
         const why = cause instanceof Error ? cause.message : String(cause);
-        super(`the import stopped after writing ${written.length} document${written.length === 1 ? "" : "s"}` +
+        super(`the ${state === "applying" ? "import" : "refresh"} stopped after writing ${written.length} document${written.length === 1 ? "" : "s"}` +
             `${pending.length > 0 ? ` (${pending.length} not written, first '${pending[0].target}')` : ""}: ${why}. ` +
-            `'${recordId}' stays at promotion_state applying; resume it to finish.`);
+            `'${recordId}' stays at promotion_state ${state}; resume it to finish.`);
         this.name = "TransferInterrupted";
         this.recordId = recordId;
         this.written = written;
         this.pending = pending;
+        this.state = state;
         this.cause = cause;
     }
 }
@@ -89,7 +103,7 @@ export class TransferResumeConflict extends Error {
     id;
     written;
     constructor(recordId, detail, options = {}) {
-        super(`cannot resume '${recordId}': ${detail}`);
+        super(`cannot ${options.verb ?? "resume"} '${recordId}': ${detail}`);
         this.name = "TransferResumeConflict";
         this.recordId = recordId;
         if (options.id !== undefined)
@@ -121,7 +135,7 @@ async function readSource(binding) {
     const docs = new Map(results.map((result) => [result.doc.id, result]));
     const ids = new Set([...docs.keys(), ...malformed.keys()]);
     const dependencies = parseDependencies(docs.get(DEPENDENCIES_DOC_ID)?.doc ?? null, { selfBundleId: binding.identity });
-    const folds = new Set([...ids].map(foldIdentityPath));
+    const folds = new Set([...ids].map(foldPath));
     return { ids, folds, docs, malformed, dependencies, registry: await loadKinds(bundle), bundle };
 }
 async function readTarget(target) {
@@ -221,7 +235,7 @@ function planLink(ctx, sourceId, targetId, span, conflicts) {
     const present = ctx.source.ids.has(resolved);
     // A spelling variant of a source id names no document under the exact-identity rule; qualifying
     // it would send a reader to an id the source bundle refuses to serve.
-    if (!present && ctx.source.folds.has(foldIdentityPath(resolved)))
+    if (!present && ctx.source.folds.has(foldPath(resolved)))
         return keep("case_variant", { source_target: resolved });
     const withFragment = fragment === undefined ? {} : { fragment };
     const mapped = ctx.mapping.get(resolved);
@@ -317,20 +331,24 @@ function normalizePrefix(prefix) {
     const trimmed = trimTrailingSlashes(prefix.trim());
     return trimmed === "" ? undefined : trimmed;
 }
-/** Every planned id must be safe, absent, unique and distinct under the filesystem identity fold. */
-const PROTECTED_TARGET_FOLDS = new Set([BUNDLE_NAME_DOC_ID, DEPENDENCIES_DOC_ID].map(foldIdentityPath));
-const CONVENTIONS_FOLD = `${foldIdentityPath(CONVENTIONS_PREFIX.replace(/\/$/, ""))}/`;
+/** Every planned id must be safe, absent, unique and distinct under `foldPath`. */
+const PROTECTED_TARGET_FOLDS = new Set([BUNDLE_NAME_DOC_ID, DEPENDENCIES_DOC_ID].map(foldPath));
+const CONVENTIONS_FOLD = `${foldPath(CONVENTIONS_PREFIX.replace(/\/$/, ""))}/`;
 /**
  * Throw {@link InvalidInputError} unless an import may create `id`: a safe, unreserved concept id
  * that is not the target's own identity or dependency declaration and not a Kind convention
- * (installing Kinds is not part of v1). Compared under the identity fold, so a case or
+ * (installing Kinds is not part of v1). Compared under `foldPath`, so a case or
  * normalization variant of a protected id is refused too.
  */
-function assertImportableTargetId(id) {
+function assertImportableTargetId(id, newTarget) {
     assertSafeConceptId(id);
+    // Only a planned target is a create; a stored record's targets may predate the canonical-id rule,
+    // and any create its resume still performs meets the rule in mutateDocument.
+    if (newTarget)
+        assertCanonicalNewDocumentId(id, newTarget.exists);
     if (isReservedFile(pathFromConceptId(id)))
         throw new InvalidInputError("index.md and log.md are reserved files, not documents");
-    const fold = foldIdentityPath(id);
+    const fold = foldPath(id);
     if (PROTECTED_TARGET_FOLDS.has(fold))
         throw new InvalidInputError("it is the bundle's own identity or dependency declaration");
     if (fold.startsWith(CONVENTIONS_FOLD))
@@ -339,11 +357,11 @@ function assertImportableTargetId(id) {
 function checkTargetIds(planned, existing, conflicts) {
     const folds = new Map();
     const remember = (id) => {
-        const keys = [[`${foldIdentityPath(id)}.md`, `${id}.md`]];
+        const keys = [[`${foldPath(id)}.md`, `${id}.md`]];
         const segments = id.split("/");
         for (let i = 1; i < segments.length; i++) {
             const dir = segments.slice(0, i).join("/");
-            keys.push([`${foldIdentityPath(dir)}/`, `${dir}/`]);
+            keys.push([`${foldPath(dir)}/`, `${dir}/`]);
         }
         return keys;
     };
@@ -355,7 +373,7 @@ function checkTargetIds(planned, existing, conflicts) {
     for (const row of planned) {
         const where = { ...(row.source === undefined ? {} : { source: row.source }), target: row.target };
         try {
-            assertImportableTargetId(row.target);
+            assertImportableTargetId(row.target, { exists: (candidate) => existing.has(candidate) });
         }
         catch (error) {
             if (!(error instanceof InvalidInputError))
@@ -581,8 +599,11 @@ async function computeTransfer(request) {
         if (types.has(String(doc.frontmatter.type)) || underPrefix(id))
             selected.add(id);
     }
+    // An unreadable document's type is unknowable, so a type selection cannot rule it out: report it
+    // rather than let the copy look complete. Ids already reported above are not repeated.
+    const namedIds = new Set(request.select.ids ?? []);
     for (const [id, reason] of source.malformed) {
-        if (!SOURCE_SELF_DOCS.has(id) && underPrefix(id)) {
+        if (!SOURCE_SELF_DOCS.has(id) && (underPrefix(id) || (types.size > 0 && !namedIds.has(id)))) {
             conflicts.push({ code: "source_malformed", source: id, detail: `'${id}' is malformed in the source: ${reason}` });
         }
     }
@@ -593,6 +614,15 @@ async function computeTransfer(request) {
     const mapping = new Map(selectedIds.map((id) => [id, prefix === undefined ? id : `${prefix}/${id}`]));
     const recordId = request.recordId?.trim() || defaultRecordId(request.from.alias, bundleId, prefix, selectedIds);
     checkTargetIds([...[...mapping].map(([s, t]) => ({ source: s, target: t })), { target: recordId, record: true }], target.ids, conflicts);
+    for (const conflict of conflicts) {
+        if (conflict.code !== "target_exists" || conflict.target === undefined)
+            continue;
+        const promotedBy = await promotingRecord(request.target, conflict.target, request.from.alias);
+        if (promotedBy === undefined)
+            continue;
+        conflict.record = promotedBy;
+        conflict.detail += `; it is a copy promoted by '${promotedBy}', which a refresh of that record updates`;
+    }
     const ctx = { alias: request.from.alias, source, target, mapping };
     const built = [];
     for (const id of selectedIds) {
@@ -674,7 +704,7 @@ export async function planDocumentTransfer(request) {
     return (await computeTransfer(request)).plan;
 }
 // ── Writes ─────────────────────────────────────────────────────────────────
-async function writeRecordState(target, registry, recordId, expectedVersion, state, versions, actor, now) {
+async function writeRecordState(target, registry, recordId, expectedVersion, state, versions, actor, now, edited = new Set()) {
     const result = await mutateDocument({
         bundle: target,
         id: recordId,
@@ -696,6 +726,8 @@ async function writeRecordState(target, registry, recordId, expectedVersion, sta
                     const version = versions.get(String(entry.target));
                     if (version !== undefined)
                         entry.target_version = version;
+                    if (edited.has(String(entry.target)))
+                        entry.target_edited = true;
                     return entry;
                 });
             }
@@ -719,7 +751,7 @@ export async function applyDocumentTransfer(request, planToken) {
             const record = parseRecord(plan.record.id, prior.doc);
             if (record.state === "applied")
                 return appliedResult(plan.record.id, prior.version, record.entries, false);
-            throw new TransferConflictError([{ code: "record_exists", target: plan.record.id, detail: `'${plan.record.id}' from this plan is still applying; resume it to finish` }]);
+            throw new TransferConflictError([{ code: "record_exists", target: plan.record.id, detail: `'${plan.record.id}' from this plan is still ${record.state}; resume it to finish` }]);
         }
         throw new TransferConflictError(plan.conflicts);
     }
@@ -779,14 +811,14 @@ export async function applyDocumentTransfer(request, planToken) {
     }
     return { record: { id: recordId, version: recordVersion, state: "applied" }, written, changed: true };
 }
-function parseRecord(recordId, doc) {
+function parseRecord(recordId, doc, verb = "resume") {
     const fm = doc.frontmatter;
-    const refuse = (detail) => { throw new TransferResumeConflict(recordId, detail); };
+    const refuse = (detail) => { throw new TransferResumeConflict(recordId, detail, { verb }); };
     if (String(fm.type).trim() !== PROMOTION_TYPE)
         refuse(`it is not a ${PROMOTION_TYPE} record (type '${String(fm.type)}')`);
     const state = fm.promotion_state;
-    if (state !== "applying" && state !== "applied")
-        refuse("promotion_state must be applying or applied");
+    if (state !== "applying" && state !== "applied" && state !== "refreshing")
+        refuse("promotion_state must be applying, applied or refreshing");
     if (typeof fm.from_alias !== "string" || typeof fm.from_bundle_id !== "string")
         refuse("from_alias and from_bundle_id are required");
     if (!Array.isArray(fm.entries))
@@ -803,6 +835,8 @@ function parseRecord(recordId, doc) {
         const entry = { source: r.source, source_version: r.source_version, target: r.target };
         if (typeof r.target_version === "string")
             entry.target_version = r.target_version;
+        if (r.target_edited === true)
+            entry.target_edited = true;
         // The record is a document anyone can edit: every target is recomputed from its source and
         // the record's prefix, and must pass the same rule a plan applies, before resume trusts it.
         if (SOURCE_SELF_DOCS.has(entry.source))
@@ -821,7 +855,25 @@ function parseRecord(recordId, doc) {
         }
         entries.push(entry);
     }
-    return { state: state, alias: fm.from_alias, bundleId: fm.from_bundle_id, ...(prefix === undefined ? {} : { prefix }), entries };
+    const parsed = { state: state, alias: fm.from_alias, bundleId: fm.from_bundle_id, ...(prefix === undefined ? {} : { prefix }), entries };
+    if (state === "refreshing") {
+        const journal = fm.refresh;
+        if (!journal || typeof journal !== "object" || !Array.isArray(journal.entries))
+            refuse("a refreshing record needs refresh.entries");
+        const byTarget = new Map(entries.map((e) => [e.target, e]));
+        parsed.refresh = [];
+        for (const row of journal.entries) {
+            const r = row;
+            if (!r || typeof r.source !== "string" || typeof r.source_version !== "string" || typeof r.target !== "string" || typeof r.replaces_version !== "string") {
+                refuse("every refresh entry needs source, source_version, target and replaces_version");
+            }
+            // A pending row may only name an entry the record already holds, with the same source.
+            if (byTarget.get(r.target)?.source !== r.source)
+                refuse(`refresh entry '${String(r.target)}' is not an entry of this record`);
+            parsed.refresh.push({ source: r.source, source_version: r.source_version, target: r.target, replaces_version: r.replaces_version });
+        }
+    }
+    return parsed;
 }
 /** The result an already-applied record stands for: nothing is written again. */
 function appliedResult(recordId, version, entries, changed) {
@@ -833,15 +885,57 @@ function appliedResult(recordId, version, entries, changed) {
     }
     return { record: { id: recordId, version, state: "applied" }, written, changed };
 }
-function hasProvenance(doc, recordId) {
+function provenanceEntries(doc) {
     const sources = doc.frontmatter.sources;
-    return Array.isArray(sources) && sources.some((s) => s !== null && typeof s === "object" && s.id === recordId);
+    return Array.isArray(sources) ? sources.filter((s) => s !== null && typeof s === "object" && !Array.isArray(s)) : [];
+}
+/**
+ * True when `doc` is what writing `candidate` over it would leave: the mutation service's own no-op
+ * test, attributed to whichever actor the copy names (the writer may not be the resuming actor).
+ */
+function isWrittenCopy(doc, candidate, registry, okfVersion) {
+    const attributed = doc.frontmatter[okfVersion === "0.1" ? "actor" : SUPERBEE_UPDATED_BY_FIELD];
+    try {
+        // Overwrite mode compares after attribution, so a v0.1 `actor` the writer stamped matches too.
+        return !prepareDocumentMutationCandidate(doc, structuredClone(candidate), {
+            mode: "overwrite",
+            id: doc.id,
+            registry,
+            strict: false,
+            okfVersion,
+            ...(typeof attributed === "string" ? { actor: attributed } : {}),
+            seedGenerationClock: false,
+        }).changed;
+    }
+    catch {
+        return false;
+    }
+}
+function hasProvenance(doc, recordId) {
+    return provenanceEntries(doc).some((s) => s.id === recordId);
+}
+/** The Promotion record an existing copy at `id` names as its import from `alias`, if any. */
+async function promotingRecord(target, id, alias) {
+    const read = await readOptional(target, id).catch(() => null);
+    if (!read)
+        return undefined;
+    for (const entry of provenanceEntries(read.doc)) {
+        if (typeof entry.id !== "string" || !entry.id.startsWith(PROMOTIONS_PREFIX))
+            continue;
+        if (typeof entry.resource !== "string" || !entry.resource.startsWith(`okf://${alias}/`))
+            continue;
+        const record = await readOptional(target, entry.id).catch(() => null);
+        if (record && String(record.doc.frontmatter.type).trim() === PROMOTION_TYPE)
+            return entry.id;
+    }
+    return undefined;
 }
 /**
  * Finish an `applying` Promotion record. For each entry: an absent target is created from the
  * source at the recorded source version (a changed source refuses); a present target carrying a
  * `sources` entry with this record's id is already done; anything else refuses. When every entry
  * is done the record becomes `applied`. Running it again on an `applied` record is a no-op.
+ * A `refreshing` record is finished the same way by {@link finishRefresh}.
  */
 export async function resumeDocumentTransfer(target, recordId, from, options = {}) {
     const read = await readOptional(target, recordId);
@@ -855,6 +949,8 @@ export async function resumeDocumentTransfer(target, recordId, from, options = {
     }
     if (record.state === "applied")
         return appliedResult(recordId, read.version, record.entries, false);
+    if (record.state === "refreshing")
+        return finishRefresh(target, recordId, read, record, from, options);
     const snapshot = await readTarget(target);
     assertActor(options.actor, snapshot.okfVersion);
     // The same alias and identity check a plan runs: the target's declaration may have moved since.
@@ -870,6 +966,7 @@ export async function resumeDocumentTransfer(target, recordId, from, options = {
     const registry = snapshot.registry;
     const written = [];
     const versions = new Map();
+    const edited = new Set();
     for (const entry of record.entries) {
         let existing;
         try {
@@ -887,6 +984,15 @@ export async function resumeDocumentTransfer(target, recordId, from, options = {
             }
             written.push({ source: entry.source, target: entry.target, version: existing.version });
             versions.set(entry.target, existing.version);
+            // A copy edited after the interrupted write still carries the provenance; it is adopted, but
+            // flagged so a refresh treats it as edited instead of as the import's own baseline.
+            const sourceRead = source.docs.get(entry.source);
+            const conflicts = [];
+            const built = sourceRead?.version === entry.source_version
+                ? buildEntry(ctx, record.bundleId, recordId, sourceRead, entry.target, selected, true, options.actor, now, conflicts)
+                : undefined;
+            if (!built || conflicts.length > 0 || !isWrittenCopy(existing.doc, built.candidate, registry, snapshot.okfVersion))
+                edited.add(entry.target);
             continue;
         }
         const sourceDoc = source.docs.get(entry.source);
@@ -922,7 +1028,361 @@ export async function resumeDocumentTransfer(target, recordId, from, options = {
             throw error;
         }
     }
-    const version = await writeRecordState(target, registry, recordId, read.version, "applied", versions, options.actor, options.now);
+    const version = await writeRecordState(target, registry, recordId, read.version, "applied", versions, options.actor, options.now, edited);
     return { record: { id: recordId, version, state: "applied" }, written, changed: true };
 }
+// ── Refresh ────────────────────────────────────────────────────────────────
+export const DOCUMENT_REFRESH_TOKEN_PREFIX = `${DOCUMENT_TRANSFER_CONTRACT}:refresh`;
+function matchesEntry(names, entry) {
+    return names.has(entry.target) || names.has(entry.source);
+}
+async function computeRefresh(request) {
+    const conflicts = [];
+    const now = request.now ?? (() => new Date().toISOString());
+    const read = await readOptional(request.target, request.recordId);
+    if (!read)
+        throw new DocumentNotFoundError(request.recordId);
+    const record = parseRecord(request.recordId, read.doc, "refresh");
+    const target = await readTarget(request.target);
+    assertActor(request.actor, target.okfVersion);
+    if (record.alias !== request.from.alias) {
+        conflicts.push({ code: "alias_identity", detail: `'${request.recordId}' was written for alias '${record.alias}', not '${request.from.alias}'` });
+    }
+    const identity = await sourceIdentity(request.from, target, conflicts);
+    if (identity.bundleId !== record.bundleId) {
+        conflicts.push({ code: "alias_identity", detail: `'${request.recordId}' imported from '${record.bundleId}', but '${request.from.alias}' is '${identity.bundleId}'` });
+    }
+    if (record.state !== "applied") {
+        conflicts.push({ code: "record_state", detail: `'${request.recordId}' is ${record.state}; resume it before a refresh` });
+    }
+    const overwrite = new Set(request.overwrite ?? []);
+    const skip = new Set(request.skip ?? []);
+    for (const name of [...overwrite, ...skip]) {
+        if (!record.entries.some((e) => e.target === name || e.source === name)) {
+            conflicts.push({ code: "not_in_record", target: name, detail: `'${name}' is not a copy '${request.recordId}' names` });
+        }
+    }
+    for (const name of overwrite) {
+        if (skip.has(name))
+            conflicts.push({ code: "not_in_record", target: name, detail: `'${name}' is named both to overwrite and to skip` });
+    }
+    const source = await readSource(request.from.binding);
+    const mapping = new Map(record.entries.map((e) => [e.source, e.target]));
+    const selected = new Set(mapping.keys());
+    const ctx = { alias: request.from.alias, source, target, mapping };
+    const candidates = new Map();
+    const entries = [];
+    for (const entry of record.entries) {
+        let current;
+        try {
+            current = await readOptional(request.target, entry.target);
+        }
+        catch (error) {
+            if (!(error instanceof FilesystemIdentityAliasError))
+                throw error;
+            current = null;
+            conflicts.push({ code: "case_collision", source: entry.source, target: entry.target, detail: `'${entry.target}' is spelled differently on disk: ${error.message}` });
+        }
+        const sourceRead = source.docs.get(entry.source);
+        const row = {
+            source: entry.source,
+            target: entry.target,
+            action: "unchanged",
+            recorded_source_version: entry.source_version,
+            target_version: current?.version ?? null,
+            edited: current !== null && (current.version !== entry.target_version || entry.target_edited === true),
+            dropped_links: 0,
+        };
+        if (entry.target_version !== undefined)
+            row.recorded_target_version = entry.target_version;
+        if (sourceRead)
+            row.source_version = sourceRead.version;
+        entries.push(row);
+        const where = { source: entry.source, target: entry.target };
+        const block = (code, detail) => {
+            row.action = "conflict";
+            row.detail = detail;
+            conflicts.push({ code, ...where, detail });
+        };
+        if (matchesEntry(skip, entry)) {
+            row.action = "skip";
+            continue;
+        }
+        if (entry.target_version === undefined) {
+            block("record_state", `the record holds no target_version for '${entry.target}', so a local edit cannot be told apart`);
+            continue;
+        }
+        if (source.malformed.has(entry.source)) {
+            block("source_malformed", `'${entry.source}' is malformed in the source: ${source.malformed.get(entry.source)}`);
+            continue;
+        }
+        const sourceChanged = sourceRead?.version !== entry.source_version;
+        if (!sourceRead) {
+            block("source_missing", `'${entry.source}' is no longer in ${request.from.binding.label}; a refresh never deletes the copy`);
+            continue;
+        }
+        if (current === null) {
+            if (sourceChanged)
+                block("target_missing", `'${entry.target}' is gone from the target; a refresh never recreates it`);
+            else
+                row.detail = "the copy is gone from the target; its source has not changed";
+            continue;
+        }
+        const overwriting = row.edited && matchesEntry(overwrite, entry);
+        if (!sourceChanged && !overwriting) {
+            if (row.edited)
+                row.detail = "the copy was edited in the target; its source has not changed";
+            continue;
+        }
+        if (row.edited && !overwriting) {
+            block("target_edited", `'${entry.target}' was edited in the target since '${request.recordId}' wrote it; overwrite or skip it explicitly`);
+            continue;
+        }
+        const built = buildEntry(ctx, record.bundleId, request.recordId, sourceRead, entry.target, selected, true, request.actor, now, conflicts);
+        candidates.set(entry.source, built.candidate);
+        row.action = overwriting ? "overwrite" : "update";
+        row.dropped_links = computeDroppedLinks(outboundLinks(current.doc), outboundLinks({ ...current.doc, body: built.candidate.body })).length;
+    }
+    const counts = { update: 0, overwrite: 0, unchanged: 0, skip: 0, conflict: 0 };
+    for (const row of entries)
+        counts[row.action]++;
+    const from = { alias: request.from.alias, bundle_id: identity.bundleId, label: request.from.label ?? request.from.binding.label };
+    if (identity.pin)
+        from.pin = identity.pin;
+    const ready = conflicts.length === 0;
+    const plan = {
+        contract: DOCUMENT_TRANSFER_CONTRACT,
+        record: { id: request.recordId, version: read.version, state: record.state },
+        from,
+        entries,
+        counts,
+        conflicts,
+        ready,
+    };
+    if (ready && counts.update + counts.overwrite > 0) {
+        plan.plan_token = `${DOCUMENT_REFRESH_TOKEN_PREFIX}:sha256:${hashOf({
+            contract: DOCUMENT_REFRESH_TOKEN_PREFIX,
+            record: { id: request.recordId, version: read.version },
+            from: { bundle_id: identity.bundleId, pin: identity.pin?.value ?? null },
+            target: { okf_version: target.okfVersion, bundle_id: target.bundleId ?? null, dependencies_version: target.dependenciesVersion },
+            entries: entries.map((row) => ({
+                source: row.source,
+                target: row.target,
+                action: row.action,
+                source_version: row.source_version ?? null,
+                target_version: row.target_version,
+                candidate: candidates.has(row.source) ? hashOf(candidates.get(row.source)) : null,
+            })),
+        })}`;
+    }
+    return { plan, candidates, read };
+}
+/** Read-only: compute what a refresh of an applied Promotion record would write, and its conflicts. */
+export async function planDocumentRefresh(request) {
+    return (await computeRefresh(request)).plan;
+}
+/** The record as applied, with each refreshed row's versions moved forward and the journal removed. */
+async function closeRefresh(target, registry, recordId, expectedVersion, done, token, pin, actor, now) {
+    const result = await mutateDocument({
+        bundle: target,
+        id: recordId,
+        mode: "replace-document",
+        onAbsent: "fail",
+        expectedVersion,
+        registry,
+        strict: false,
+        actor,
+        ...(now ? { now } : {}),
+        buildCandidate: (existing) => {
+            const frontmatter = structuredClone(existing.frontmatter);
+            frontmatter.promotion_state = "applied";
+            delete frontmatter.refresh;
+            if (token !== undefined)
+                frontmatter.refresh_token = token;
+            if (pin)
+                frontmatter.from_pin = pin.value;
+            frontmatter.entries = frontmatter.entries.map((row) => {
+                const entry = { ...row };
+                const moved = done.get(String(entry.target));
+                if (moved) {
+                    Object.assign(entry, moved);
+                    delete entry.target_edited;
+                }
+                return entry;
+            });
+            return { frontmatter, body: existing.body };
+        },
+    });
+    return result.version;
+}
+function refreshedResult(recordId, version, written, changed) {
+    return { record: { id: recordId, version, state: "applied" }, written, changed };
+}
+/**
+ * Recompute the refresh plan from fresh reads, refuse unless it is ready and its token equals
+ * `planToken`, then write: the record (`refreshing`, with the pending rows), each copy replaced
+ * under a hard compare-and-swap on the version the plan saw, and the record again (`applied`, its
+ * rows moved forward). A failed write throws {@link TransferInterrupted} with state `refreshing`;
+ * {@link resumeDocumentTransfer} finishes it. The same token applied again after it completed is
+ * a no-op success.
+ */
+export async function applyDocumentRefresh(request, planToken) {
+    const token = planToken.trim();
+    const { plan, candidates, read } = await computeRefresh(request);
+    if (!plan.ready)
+        throw new TransferConflictError(plan.conflicts);
+    if (plan.plan_token === undefined && read.doc.frontmatter.refresh_token === token) {
+        return refreshedResult(request.recordId, read.version, [], false);
+    }
+    if (plan.plan_token !== token)
+        throw new TransferPlanChanged(token, plan.plan_token ?? "(nothing to refresh)");
+    const registry = await loadKinds(request.target);
+    const pending = plan.entries.filter((row) => row.action === "update" || row.action === "overwrite");
+    const journal = pending.map((row) => ({
+        source: row.source,
+        source_version: row.source_version,
+        target: row.target,
+        replaces_version: row.target_version,
+    }));
+    let recordVersion;
+    try {
+        recordVersion = (await mutateDocument({
+            bundle: request.target,
+            id: request.recordId,
+            mode: "replace-document",
+            onAbsent: "fail",
+            expectedVersion: read.version,
+            registry,
+            strict: false,
+            actor: request.actor,
+            ...(request.now ? { now: request.now } : {}),
+            buildCandidate: (existing) => {
+                const frontmatter = structuredClone(existing.frontmatter);
+                frontmatter.promotion_state = "refreshing";
+                frontmatter.refresh = { plan_token: token, entries: journal.map((row) => ({ ...row })) };
+                return { frontmatter, body: existing.body };
+            },
+        })).version;
+    }
+    catch (error) {
+        if (error instanceof VersionConflict)
+            throw new TransferPlanChanged(token, `'${request.recordId}' changed during the refresh`);
+        throw error;
+    }
+    const written = [];
+    const done = new Map();
+    for (let index = 0; index < journal.length; index++) {
+        const row = journal[index];
+        try {
+            const result = await replaceCopy(request.target, registry, row, candidates.get(row.source), request.actor, request.now);
+            written.push({ source: row.source, target: row.target, version: result });
+            done.set(row.target, { source_version: row.source_version, target_version: result });
+        }
+        catch (cause) {
+            throw new TransferInterrupted(request.recordId, written, journal.slice(index).map((e) => ({ source: e.source, target: e.target })), cause, "refreshing");
+        }
+    }
+    try {
+        recordVersion = await closeRefresh(request.target, registry, request.recordId, recordVersion, done, token, plan.from.pin, request.actor, request.now);
+    }
+    catch (cause) {
+        throw new TransferInterrupted(request.recordId, written, [], cause, "refreshing");
+    }
+    return refreshedResult(request.recordId, recordVersion, written, true);
+}
+/** Replace one copy, only if it is still exactly the version the refresh planned against. */
+async function replaceCopy(target, registry, row, candidate, actor, now) {
+    const result = await mutateDocument({
+        bundle: target,
+        id: row.target,
+        mode: "replace-document",
+        onAbsent: "fail",
+        expectedVersion: row.replaces_version,
+        registry,
+        strict: false,
+        actor,
+        seedGenerationClock: false,
+        // The source is the authority for a promoted copy's body; the plan reported the links it drops.
+        bodyReplace: { replaceLinks: true },
+        ...(now ? { now } : {}),
+        buildCandidate: () => structuredClone(candidate),
+    });
+    return result.version;
+}
+/**
+ * Finish a `refreshing` record. For each pending row: a copy whose provenance already names this
+ * record at the row's source version is done; a copy still at `replaces_version` whose source is
+ * still at the row's `source_version` is replaced; any other row (the copy was deleted or edited,
+ * or the source moved on) is left as it is, keeps its old baseline in the record, and is reported,
+ * so the record always closes without overwriting anything the plan did not show.
+ */
+async function finishRefresh(target, recordId, read, record, from, options) {
+    const snapshot = await readTarget(target);
+    assertActor(options.actor, snapshot.okfVersion);
+    const identity = [];
+    const { pin } = await sourceIdentity(from, snapshot, identity);
+    if (identity.length > 0)
+        throw new TransferResumeConflict(recordId, `${identity[0].code}: ${identity[0].detail}`);
+    const source = await readSource(from.binding);
+    const mapping = new Map(record.entries.map((e) => [e.source, e.target]));
+    const ctx = { alias: from.alias, source, target: snapshot, mapping };
+    const now = options.now ?? (() => new Date().toISOString());
+    const registry = snapshot.registry;
+    const token = read.doc.frontmatter.refresh.plan_token;
+    const written = [];
+    const left = [];
+    const done = new Map();
+    for (const row of record.refresh) {
+        const leave = (detail) => { left.push({ source: row.source, target: row.target, detail }); };
+        let current;
+        try {
+            current = await readOptional(target, row.target);
+        }
+        catch (error) {
+            if (!(error instanceof FilesystemIdentityAliasError))
+                throw error;
+            leave(`'${row.target}' is spelled differently on disk: ${error.message}`);
+            continue;
+        }
+        if (!current) {
+            leave(`'${row.target}' was deleted during the refresh`);
+            continue;
+        }
+        const sourceDoc = source.docs.get(row.source);
+        if (!sourceDoc || sourceDoc.version !== row.source_version) {
+            leave(`the source '${row.source}' is ${sourceDoc ? "changed" : "missing"} since the refresh was planned`);
+            continue;
+        }
+        const conflicts = [];
+        const built = buildEntry(ctx, record.bundleId, recordId, sourceDoc, row.target, new Set(mapping.keys()), true, options.actor, now, conflicts);
+        if (conflicts.length > 0) {
+            leave(`${conflicts[0].code}: ${conflicts[0].detail}`);
+            continue;
+        }
+        if (current.version !== row.replaces_version) {
+            // Done only when the copy is exactly what this refresh writes; provenance alone would also
+            // match a copy edited after the write, and adopting it would make that edit the baseline.
+            if (isWrittenCopy(current.doc, built.candidate, registry, snapshot.okfVersion)) {
+                written.push({ source: row.source, target: row.target, version: current.version });
+                done.set(row.target, { source_version: row.source_version, target_version: current.version });
+            }
+            else {
+                leave(`'${row.target}' was changed by another writer during the refresh`);
+            }
+            continue;
+        }
+        try {
+            const version = await replaceCopy(target, registry, row, built.candidate, options.actor, options.now);
+            written.push({ source: row.source, target: row.target, version });
+            done.set(row.target, { source_version: row.source_version, target_version: version });
+        }
+        catch (error) {
+            if (!(error instanceof VersionConflict))
+                throw error;
+            leave(`'${row.target}' was changed by another writer during the resume`);
+        }
+    }
+    const version = await closeRefresh(target, registry, recordId, read.version, done, typeof token === "string" ? token : undefined, pin, options.actor, options.now);
+    return { ...refreshedResult(recordId, version, written, true), ...(left.length > 0 ? { left } : {}) };
+}
 //# sourceMappingURL=document-transfer.js.map