@superbee/core 0.1.6 → 0.2.0-pre.1

package/dist/document-field-actions.js

@@ -0,0 +1,261 @@
+/** Explicit frontmatter intent. Collection construction is owned here, before CAS metadata. */
+import { InvalidInputError } from "./errors.js";
+import { okfValuesEqual } from "./okf-authored-values.js";
+import { kindInputFieldNames, resolveKindFieldCoordinate } from "./kinds.js";
+/** Adapters can render corrective commands without parsing prose or repeating selection. */
+export class FieldActionError extends InvalidInputError {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = "FieldActionError";
+        this.details = details;
+    }
+}
+const managed = new Set(["generated", "verified", "superbee_updated_by", "actor", "timestamp"]);
+const standard = new Set(["title", "description", "type", "resource"]);
+const v02 = new Set(["status", "stale_after", "usage_window"]);
+export function isStandardDocumentSetField(field, okfVersion) {
+    return standard.has(field) || (okfVersion === "0.2" && v02.has(field));
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function has(object, key) { return Object.prototype.hasOwnProperty.call(object, key); }
+function sourceCandidates(rows) {
+    return {
+        total: rows.length,
+        candidates: rows.slice(0, 5).map(row => {
+            const identity = {};
+            for (const key of ["id", "resource", "title"]) {
+                if (record(row) && has(row, key) && typeof row[key] === "string")
+                    identity[key] = row[key];
+            }
+            return identity;
+        }),
+    };
+}
+export function containsCollection(value) {
+    return Array.isArray(value) || (record(value) && Object.values(value).some(containsCollection));
+}
+export function assertNonCollectionAssignment(field, previous, value) {
+    if (containsCollection(previous) || containsCollection(value)) {
+        const correction = field === "tags" || field === "sources"
+            ? `Use an explicit ${field} add/remove/replace-all collection action.`
+            : "Use complete-document replacement: pull --doc-key <id>.md --out <file>, edit that file, then promote <file> --doc-key <id>.md --expected-version <version-from-pull>.";
+        throw new InvalidInputError(`Cannot assign '${field}': the old or new subtree contains a list. ${correction}`);
+    }
+}
+export function assertOrdinaryPatch(existing, proposed) {
+    for (const field of new Set([...Object.keys(existing), ...Object.keys(proposed)])) {
+        if (!okfValuesEqual(existing[field], proposed[field]))
+            assertNonCollectionAssignment(field, existing[field], proposed[field]);
+    }
+}
+function assertAssignmentName(field) {
+    if (managed.has(field))
+        throw new InvalidInputError(`'${field}' is managed metadata and cannot be assigned by a field action.`);
+    if (field === "tags" || field === "sources")
+        throw new InvalidInputError(`'${field}' requires an explicit collection add/remove/replace-all action.`);
+}
+/** Semantic legacy assignments retain input intent, including explicitly equal assignments. */
+export function prepareDocumentAssignments(existing, assignments) {
+    if (!record(assignments))
+        throw new InvalidInputError("assignments must be a mapping");
+    for (const [field, value] of Object.entries(assignments)) {
+        assertAssignmentName(field);
+        assertNonCollectionAssignment(field, existing.frontmatter[field], value);
+    }
+    return { frontmatter: { ...existing.frontmatter, ...structuredClone(assignments) }, body: existing.body };
+}
+function sourceRow(value) {
+    if (!record(value) || typeof value.resource !== "string" || value.resource.trim() === "")
+        throw new InvalidInputError("A source entry requires a nonempty resource string.");
+    if (has(value, "id") && typeof value.id !== "string")
+        throw new InvalidInputError("A supplied source ID must be a string.");
+}
+function selectorIndex(rows, selector, edit) {
+    if (!record(selector) || Object.keys(selector).length !== 1 || !(has(selector, "id") || has(selector, "resource")))
+        throw new InvalidInputError("Select one source by exactly one id or resource.");
+    const key = has(selector, "id") ? "id" : "resource";
+    const value = selector[key];
+    // An imported empty ID is still an existing ID; it may be selected exactly but is never minted.
+    if (typeof value !== "string" || (key === "resource" && value.trim() === ""))
+        throw new InvalidInputError(`Source ${key} selector must be a string.`);
+    const matches = rows.flatMap((row, index) => record(row) && has(row, key) && row[key] === value ? [index] : []);
+    if (matches.length > 1)
+        throw new FieldActionError(`Source selector is ambiguous (${matches.length} matches); inspect sources and use a unique ID or version-guarded replace-all.`, {
+            reason: "ambiguous-source", field: "sources", selector: structuredClone(selector), ...sourceCandidates(matches.map(index => rows[index])),
+        });
+    if (matches.length === 0) {
+        if (edit)
+            throw new FieldActionError(`Source ${key} '${value}' was not found.`, {
+                reason: "source-not-found", field: "sources", selector: structuredClone(selector), ...sourceCandidates([]),
+            });
+        return -1;
+    }
+    const index = matches[0];
+    if (key === "resource" && has(rows[index], "id")) {
+        const id = rows[index].id;
+        if (typeof id !== "string")
+            throw new FieldActionError("This source has a malformed ID; repair it with version-guarded replace-all.", {
+                reason: "invalid-source-id", field: "sources", selector: structuredClone(selector), ...sourceCandidates([rows[index]]),
+            });
+        throw new FieldActionError(`This resource has source ID '${id}'; select it with --id.`, {
+            reason: "source-has-id", field: "sources", selector: structuredClone(selector), recommendedSelector: { id }, ...sourceCandidates([rows[index]]),
+        });
+    }
+    return index;
+}
+export function prepareDocumentFieldAction(existing, action, context) {
+    if (!record(action) || typeof action.field !== "string")
+        throw new InvalidInputError("A field action requires a field name.");
+    if (action.action === "set")
+        assertAssignmentName(action.field);
+    const keys = action.action === "edit" ? ["action", "field", "selector", "patch"]
+        : action.action === "remove" && action.field === "sources" ? ["action", "field", "selector"]
+            : ["action", "field", "value"];
+    if (Object.keys(action).some(key => !keys.includes(key)) || keys.some(key => !has(action, key)))
+        throw new InvalidInputError("Field action has missing or incompatible input properties.");
+    if ("value" in action && action.value === undefined)
+        throw new InvalidInputError("A field action value must be supplied; removing a field is not supported.");
+    let storageField = action.field;
+    let candidate = { frontmatter: structuredClone(existing.frontmatter), body: existing.body };
+    const scope = { field: action.field, action: action.action, outcome: "unchanged" };
+    if (action.action === "set") {
+        const kind = context.registry.kinds.get(String(existing.frontmatter.type));
+        const coordinate = kind && resolveKindFieldCoordinate(context.okfVersion, kind, action.field);
+        if (context.okfVersion === "0.1" && (action.field === "stale_after" || action.field === "usage_window"))
+            throw new InvalidInputError(`'${action.field}' requires OKF v0.2.`);
+        if (!isStandardDocumentSetField(action.field, context.okfVersion) && !coordinate) {
+            const supportedFields = [...new Set([
+                    ...standard,
+                    ...(context.okfVersion === "0.2" ? v02 : []),
+                    ...(kind ? kindInputFieldNames(context.okfVersion, kind) : []),
+                ])].filter(field => {
+                if (managed.has(field) || field === "tags" || field === "sources")
+                    return false;
+                if (context.okfVersion === "0.1" && (field === "stale_after" || field === "usage_window"))
+                    return false;
+                const storage = kind && resolveKindFieldCoordinate(context.okfVersion, kind, field);
+                return !containsCollection(existing.frontmatter[storage?.storageField ?? field]);
+            }).sort();
+            throw new FieldActionError(`Unsupported set field '${action.field}'; supported fields: ${supportedFields.join(", ")}.`, {
+                reason: "unsupported-set-field", field: action.field, supportedFields,
+            });
+        }
+        storageField = coordinate?.storageField ?? action.field;
+        candidate = prepareDocumentAssignments(existing, { [storageField]: action.value });
+        if (!okfValuesEqual(existing.frontmatter[storageField], action.value))
+            scope.outcome = "edited";
+        if (scope.outcome !== "unchanged" && context.okfVersion === "0.1")
+            candidate.frontmatter.timestamp = (context.now ?? (() => new Date().toISOString()))();
+        return { candidate, scope, storageField };
+    }
+    if (action.field !== "tags" && action.field !== "sources")
+        throw new InvalidInputError("Collection actions support only tags and sources.");
+    if (!["add", "remove", "edit", "replace-all"].includes(action.action))
+        throw new InvalidInputError("Unknown field action.");
+    if (action.field === "sources" && context.okfVersion !== "0.2")
+        throw new InvalidInputError("sources actions require OKF v0.2.");
+    const previous = existing.frontmatter[action.field];
+    let rows;
+    if (action.action === "replace-all") {
+        if (!Array.isArray(action.value))
+            throw new InvalidInputError("replace-all requires a complete list (including [] to empty it).");
+        // Authored-value validation owns row compatibility; replacement permits deliberate duplicates.
+        rows = structuredClone(action.value);
+        if (action.field === "tags" && rows.some(value => typeof value !== "string"))
+            throw new InvalidInputError("tags must be a list of strings.");
+        scope.outcome = okfValuesEqual(previous, rows) ? "unchanged" : "replaced";
+    }
+    else {
+        if (previous !== undefined && !Array.isArray(previous))
+            throw new InvalidInputError(`'${action.field}' is not a list; repair it with version-guarded replace-all.`);
+        rows = structuredClone(previous ?? []);
+        if (action.field === "tags") {
+            if (action.action === "edit")
+                throw new InvalidInputError("tags supports add/remove/replace-all, not edit.");
+            if (typeof action.value !== "string")
+                throw new InvalidInputError("A tag must be a string.");
+            if (action.action === "add" && !rows.includes(action.value)) {
+                rows.push(action.value);
+                scope.outcome = "added";
+            }
+            if (action.action === "remove" && rows.includes(action.value)) {
+                rows = rows.filter(row => row !== action.value);
+                scope.outcome = "removed";
+            }
+        }
+        else if (action.action === "add") {
+            sourceRow(action.value);
+            if (has(action.value, "id")) {
+                const matches = rows.filter(row => record(row) && row.id === action.value.id);
+                if (matches.length > 1)
+                    throw new FieldActionError("Source ID is ambiguous; repair duplicate IDs with replace-all.", {
+                        reason: "ambiguous-source", field: "sources", selector: { id: action.value.id }, ...sourceCandidates(matches),
+                    });
+                if (matches.length === 1 && !okfValuesEqual(matches[0], action.value))
+                    throw new FieldActionError("Source ID conflicts with an existing entry; use edit with its observed version.", {
+                        reason: "source-id-conflict", field: "sources", selector: { id: action.value.id }, recommendedSelector: { id: action.value.id }, ...sourceCandidates(matches),
+                    });
+            }
+            if (!rows.some(row => okfValuesEqual(row, action.value))) {
+                rows.push(structuredClone(action.value));
+                scope.outcome = "added";
+            }
+            if (action.value.id !== undefined)
+                scope.affectedSourceIds = [action.value.id];
+        }
+        else {
+            const index = selectorIndex(rows, action.selector, action.action === "edit");
+            scope.selector = structuredClone(action.selector);
+            if (index >= 0) {
+                const old = rows[index];
+                if (typeof old.id === "string")
+                    scope.affectedSourceIds = [old.id];
+                if (action.action === "remove") {
+                    rows.splice(index, 1);
+                    scope.outcome = "removed";
+                }
+                else {
+                    if (!record(action.patch))
+                        throw new InvalidInputError("A source edit requires a property mapping.");
+                    for (const [property, value] of Object.entries(action.patch)) {
+                        if (value === undefined)
+                            throw new InvalidInputError("Source edit properties must have values.");
+                        if (containsCollection(old[property]) || containsCollection(value))
+                            throw new InvalidInputError(`Cannot assign source property '${property}': the old or new subtree contains a list. Use sources replace-all with an observed version.`);
+                    }
+                    if (has(action.patch, "id")) {
+                        if (has(old, "id")) {
+                            if (action.patch.id !== old.id)
+                                throw new InvalidInputError("An existing source ID cannot change or be removed; use replace-all.");
+                        }
+                        else {
+                            if (typeof action.patch.id !== "string" || action.patch.id.trim() === "")
+                                throw new InvalidInputError("The first source ID must be a nonempty string.");
+                            if (rows.some((row, i) => i !== index && record(row) && row.id === action.patch.id))
+                                throw new InvalidInputError("The first source ID collides with an existing ID.");
+                            scope.affectedSourceIds = [action.patch.id];
+                        }
+                    }
+                    const next = { ...old, ...structuredClone(action.patch) };
+                    if (!okfValuesEqual(old, next)) {
+                        rows[index] = next;
+                        scope.outcome = "edited";
+                    }
+                }
+            }
+        }
+    }
+    // A missing collection removed from remains missing: a membership no-op writes no normalization.
+    if (scope.outcome !== "unchanged")
+        candidate.frontmatter[action.field] = rows;
+    if (action.field === "sources" && action.action === "replace-all") {
+        scope.affectedSourceIds = [...new Set([...(Array.isArray(previous) ? previous : []), ...rows].flatMap(row => record(row) && typeof row.id === "string" ? [row.id] : []))];
+    }
+    if (scope.outcome !== "unchanged" && context.okfVersion === "0.1")
+        candidate.frontmatter.timestamp = (context.now ?? (() => new Date().toISOString()))();
+    return { candidate, scope, storageField };
+}
+//# sourceMappingURL=document-field-actions.js.map

package/dist/document-field-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-field-actions.js","sourceRoot":"","sources":["../src/document-field-actions.ts"],"names":[],"mappings":"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"}

package/dist/document-mutation.d.ts

@@ -7,12 +7,17 @@
  * Consumers own their transport and presentation errors; this module throws typed
  * core failures and never imports CLI or browser concerns.
  */
+import { type FieldAction, type FieldActionScope } from "./document-field-actions.js";
+import { type KindFieldMutation } from "./kind-field-mutation.js";
+import { type AppendVerificationOptions } from "./verification.js";
 import { InvalidInputError } from "./errors.js";
 import type { FieldPrecondition } from "./document-precondition.js";
 import type { KindRegistry } from "./kinds.js";
 import type { ValidationWarning } from "./content-type.js";
 import type { Bundle, ConceptId, Frontmatter, OkfDocument, Version } from "./types.js";
-export type DocumentMutationMode = "create-only" | "overwrite" | "patch";
+/** replace-document shares patch CAS and metadata preparation, but permits an explicit
+ * whole-document replacement instead of ordinary assignment/list protection. */
+export type DocumentMutationMode = "create-only" | "overwrite" | "patch" | "replace-document";
 /** The frontmatter and body a caller wants persisted; the service supplies the id. */
 export interface DocumentMutationCandidate {
     frontmatter: Frontmatter;
@@ -35,6 +40,21 @@ export declare class DocumentNotFoundError extends Error {
     readonly id: ConceptId;
     constructor(id: ConceptId);
 }
+export type DocumentMutationInput = {
+    kind: "field-action";
+    action: FieldAction;
+} | {
+    kind: "assign";
+    assignments: Record<string, unknown>;
+    body?: string;
+    refreshTimestamp?: boolean;
+} | {
+    kind: "verify";
+    event: AppendVerificationOptions;
+} | {
+    kind: "kind-field";
+    mutation: KindFieldMutation;
+};
 export interface MutateDocumentOptions {
     bundle: Bundle;
     id: ConceptId;
@@ -44,7 +64,11 @@ export interface MutateDocumentOptions {
     /** Reject rather than return a non-empty kind warning set. */
     strict: boolean;
     /** Recomputed against a detached copy of every fresh CAS attempt. */
-    buildCandidate: (existing: OkfDocument | undefined, context: DocumentMutationContext) => DocumentMutationCandidate | Promise<DocumentMutationCandidate>;
+    buildCandidate?: (existing: OkfDocument | undefined, context: DocumentMutationContext) => DocumentMutationCandidate | Promise<DocumentMutationCandidate>;
+    /** Actual semantic intent, evaluated on each fresh read. Mutually exclusive with buildCandidate. */
+    input?: DocumentMutationInput | ((existing: OkfDocument, context: DocumentMutationContext) => DocumentMutationInput | Promise<DocumentMutationInput>);
+    /** Adapter invariants observe every fresh candidate, regardless of input route. */
+    assertCandidate?: (existing: OkfDocument | undefined, candidate: DocumentMutationCandidate, context: DocumentMutationContext) => void | Promise<void>;
     /** Patch only: require an existing target or allow an expect-absent create. */
     onAbsent?: "fail" | "create";
     /** Retry budget for overwrite and ordinary patch. */
@@ -78,10 +102,30 @@ export interface MutateDocumentOptions {
     seedGenerationClock?: boolean;
 }
 export interface DocumentMutationResult {
+    scope?: FieldActionScope;
     doc: OkfDocument;
     changed: boolean;
     version: Version;
     warnings: ValidationWarning[];
 }
+export interface PrepareDocumentMutationOptions {
+    id: ConceptId;
+    registry: KindRegistry;
+    strict: boolean;
+    okfVersion: "0.1" | "0.2";
+    now?: () => string;
+    actor?: string;
+    /** Content producer for generated.by; defaults to actor when omitted. */
+    producer?: string;
+    persistActor?: boolean;
+    compareTimestamp?: boolean;
+    seedGenerationClock?: boolean;
+}
+/** The pure patch preparation shared by mutation commits and governed previews. */
+export declare function prepareDocumentMutationCandidate(existing: OkfDocument | undefined, rawCandidate: DocumentMutationCandidate, opts: PrepareDocumentMutationOptions): {
+    candidate: DocumentMutationCandidate;
+    changed: boolean;
+    warnings: ValidationWarning[];
+};
 export declare function mutateDocument(opts: MutateDocumentOptions): Promise<DocumentMutationResult>;
 //# sourceMappingURL=document-mutation.d.ts.map

package/dist/document-mutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-mutation.d.ts","sourceRoot":"","sources":["../src/document-mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAmBhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAA4B,MAAM,YAAY,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EACV,MAAM,EACN,SAAS,EACT,WAAW,EACX,WAAW,EACX,OAAO,EACR,MAAM,YAAY,CAAC;AAIpB,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,WAAW,GAAG,OAAO,CAAC;AAEzE,sFAAsF;AACtF,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8FAA8F;AAC9F,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,KAAK,GAAG,KAAK,CAAC;CAC3B;AAED,4FAA4F;AAC5F,qBAAa,oBAAqB,SAAQ,iBAAiB;IACzD,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;gBAGlC,EAAE,EAAE,SAAS,EACb,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,iBAAiB,EAAE,EAC/B,UAAU,CAAC,EAAE,KAAK,GAAG,KAAK;CAS7B;AAED,uFAAuF;AACvF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;gBAEX,EAAE,EAAE,SAAS;CAK1B;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,oBAAoB,CAAC;IAC3B,mGAAmG;IACnG,QAAQ,EAAE,YAAY,CAAC;IACvB,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,cAAc,EAAE,CACd,QAAQ,EAAE,WAAW,GAAG,SAAS,EACjC,OAAO,EAAE,uBAAuB,KAC7B,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACpE,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC7B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;kFAE8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0GAA0G;IAC1G,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sFAAsF;IACtF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,6FAA6F;IAC7F,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,WAAW,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AA6KD,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAkOjG"}
+{"version":3,"file":"document-mutation.d.ts","sourceRoot":"","sources":["../src/document-mutation.ts"],"names":[],"mappings":"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"}

package/dist/document-mutation.js

@@ -7,6 +7,9 @@
  * Consumers own their transport and presentation errors; this module throws typed
  * core failures and never imports CLI or browser concerns.
  */
+import { assertOrdinaryPatch, prepareDocumentAssignments, prepareDocumentFieldAction } from "./document-field-actions.js";
+import { prepareKindFieldMutation } from "./kind-field-mutation.js";
+import { appendVerificationEvent } from "./verification.js";
 import { okfValuesEqual } from "./okf-authored-values.js";
 import { InvalidInputError } from "./errors.js";
 import { assertAuthoredOkfStandardFields } from "./okf-standard-fields.js";
@@ -19,7 +22,7 @@ import { persistMutationActor, SUPERBEE_UPDATED_BY_FIELD } from "./mutation-attr
 import { defaultTimestampAndValidateAgainstRegistry, validateAgainstKind, } from "./kinds.js";
 import { versionedMutation } from "./mutation.js";
 import { VersionConflict } from "./versioning.js";
-import { readBundleOkfVersion, readDocVersioned, writeDocVersionedForEdition, } from "./bundle.js";
+import { readBundleOkfVersion, readDocVersioned, writeDocVersionedForEdition, } from "./bundle-ops.js";
 const DEFAULT_MAX_ATTEMPTS = 5;
 /** Typed strict-kind rejection for trusted consumers to translate at their own boundary. */
 export class KindConformanceError extends InvalidInputError {
@@ -56,12 +59,12 @@ function withoutAutomaticMutationActor(frontmatter, okfVersion, kindRequiresActo
     const { actor: _actor, ...withoutActor } = rest;
     return withoutActor;
 }
-function withCanonicalComparableTimestamp(frontmatter) {
+function withCanonicalComparableTimestamp(frontmatter, okfVersion) {
     const timestamp = frontmatter.timestamp;
     if (typeof timestamp !== "string")
         return frontmatter;
-    const instant = Date.parse(timestamp);
-    if (Number.isNaN(instant))
+    const instant = parseTimestamp(timestamp, okfVersion);
+    if (instant === null)
         return frontmatter;
     const canonical = new Date(instant).toISOString();
     return canonical === timestamp ? frontmatter : { ...frontmatter, timestamp: canonical };
@@ -78,10 +81,10 @@ function isNoopMutation(existing, candidate, compareTimestamp, okfVersion, ignor
         ? withoutAutomaticMutationActor(candidate.frontmatter, okfVersion, kindRequiresActor)
         : candidate.frontmatter;
     const existingFrontmatter = compareTimestamp
-        ? withCanonicalComparableTimestamp(existingFrontmatterWithActorPolicy)
+        ? withCanonicalComparableTimestamp(existingFrontmatterWithActorPolicy, okfVersion)
         : existingFrontmatterWithActorPolicy;
     const candidateFrontmatter = compareTimestamp
-        ? withCanonicalComparableTimestamp(candidateFrontmatterWithActorPolicy)
+        ? withCanonicalComparableTimestamp(candidateFrontmatterWithActorPolicy, okfVersion)
         : candidateFrontmatterWithActorPolicy;
     if (okfVersion === "0.2") {
         const withoutGeneratedAt = (frontmatter) => {
@@ -146,13 +149,15 @@ function withV02Metadata(candidate, existing, okfVersion, registry, now, seedGen
         allowGeneratedProvenanceSeed: seedGenerationClock,
         // Every v0.2 create gets one standard clock unless a usable time already exists (an explicit
         // legacy `timestamp`, a declared `generated.at`) or its kind requires `timestamp` (that one
-        // clock is defaulted instead). Ungoverned types are the point: accumulation evidence for
+        // clock is defaulted instead when absent). Present unusable legacy values are preserved.
+        // Ungoverned types are the point: accumulation evidence for
         // per-bundle modeling (designs/agent-proposed-kind-conventions-v1) must not depend on a kind
         // already existing. Callers installing definitions opt out via `seedGenerationClock: false`.
         requireGenerationClock: existing === undefined
             && seedGenerationClock
-            && !(kind?.fields.required.includes("timestamp") ?? false)
-            && parseTimestamp(meaningfulChangeTimeValue(candidate.frontmatter)) === null,
+            && (!(kind?.fields.required.includes("timestamp") ?? false)
+                || Object.hasOwn(candidate.frontmatter, "timestamp"))
+            && parseTimestamp(meaningfulChangeTimeValue(candidate.frontmatter), okfVersion) === null,
     });
 }
 /** One stable instant per CAS decision, shared by every clock a bundle Kind explicitly carries. */
@@ -160,6 +165,17 @@ function onceNow(now) {
     let value;
     return () => (value ??= now());
 }
+/** The pure patch preparation shared by mutation commits and governed previews. */
+export function prepareDocumentMutationCandidate(existing, rawCandidate, opts) {
+    const decisionNow = onceNow(opts.now ?? (() => new Date().toISOString()));
+    const comparison = withV02Metadata(structuredClone(rawCandidate), existing, opts.okfVersion, opts.registry, decisionNow, opts.seedGenerationClock ?? true, opts.actor, opts.compareTimestamp ?? false, opts.producer);
+    if (existing && isNoopMutation(existing, comparison, opts.compareTimestamp ?? false, opts.okfVersion, opts.okfVersion === "0.2" && !!opts.persistActor && opts.actor !== undefined, opts.registry.kinds.get(String(comparison.frontmatter.type))?.fields.required.includes("actor") ?? false)) {
+        return { candidate: { frontmatter: structuredClone(existing.frontmatter), body: existing.body }, changed: false, warnings: [] };
+    }
+    const candidate = attributeCandidate(comparison, opts.actor, opts.persistActor ?? false, opts.okfVersion, opts.registry);
+    const { warnings } = validateCandidate(opts.id, candidate, opts.registry, opts.strict, opts.okfVersion, decisionNow, existing);
+    return { candidate, changed: true, warnings };
+}
 /**
  * True when `existing` already satisfies ITS OWN governing kind — the monotone ratchet's
  * precondition (probe: tasks/overwrite-ratchet-survey). Validates the RAW existing
@@ -187,6 +203,50 @@ export async function mutateDocument(opts) {
     }
     const now = opts.now ?? (() => new Date().toISOString());
     const context = { okfVersion };
+    if ((opts.input === undefined) === (opts.buildCandidate === undefined))
+        throw new InvalidInputError("Supply exactly one semantic input or buildCandidate.");
+    if (opts.input !== undefined && opts.mode !== "patch")
+        throw new InvalidInputError("Semantic field/domain input requires patch mode.");
+    let scope;
+    const build = async (existing, decisionNow) => {
+        scope = undefined;
+        let candidate;
+        if (opts.input !== undefined) {
+            if (!existing)
+                throw new DocumentNotFoundError(opts.id);
+            const input = typeof opts.input === "function" ? await opts.input(structuredClone(existing), context) : opts.input;
+            if (input.kind === "field-action") {
+                if ((input.action.action === "edit" || input.action.action === "replace-all") && opts.expectedVersion === undefined)
+                    throw new InvalidInputError("edit and replace-all require expectedVersion from an observed document.");
+                const prepared = prepareDocumentFieldAction(existing, input.action, { registry: opts.registry, okfVersion, now: decisionNow });
+                candidate = prepared.candidate;
+                scope = prepared.scope;
+            }
+            else if (input.kind === "assign") {
+                candidate = prepareDocumentAssignments(existing, input.assignments);
+                if (input.body !== undefined)
+                    candidate.body = input.body;
+                if (input.refreshTimestamp && okfVersion === "0.1")
+                    candidate.frontmatter.timestamp = decisionNow();
+            }
+            else if (input.kind === "verify") {
+                if (okfVersion !== "0.2")
+                    throw new InvalidInputError("Verification events require OKF v0.2.");
+                candidate = { frontmatter: appendVerificationEvent(existing.frontmatter, input.event), body: existing.body };
+            }
+            else if (input.kind === "kind-field")
+                candidate = prepareKindFieldMutation(existing, input.mutation, okfVersion);
+            else
+                throw new InvalidInputError("Unknown document mutation input.");
+        }
+        else {
+            candidate = await opts.buildCandidate(existing === undefined ? undefined : structuredClone(existing), context);
+            if (existing && opts.mode === "patch")
+                assertOrdinaryPatch(existing.frontmatter, candidate.frontmatter);
+        }
+        await opts.assertCandidate?.(existing === undefined ? undefined : structuredClone(existing), structuredClone(candidate), context);
+        return candidate;
+    };
     if (opts.mode === "create-only") {
         // Fail closed: create-only issues NO read — its CAS basis is expect-absent — so there is no
         // observed state to evaluate an assertion against. Accepting the option and silently not
@@ -196,7 +256,7 @@ export async function mutateDocument(opts) {
                 + "(use mode 'patch' with onAbsent: 'create')");
         }
         const decisionNow = onceNow(now);
-        const withMetadata = withV02Metadata(await opts.buildCandidate(undefined, context), undefined, okfVersion, opts.registry, decisionNow, seedClock, opts.actor, compareTimestamp, opts.producer);
+        const withMetadata = withV02Metadata(await build(undefined, decisionNow), undefined, okfVersion, opts.registry, decisionNow, seedClock, opts.actor, compareTimestamp, opts.producer);
         const candidate = attributeCandidate(withMetadata, opts.actor, persistActor, okfVersion, opts.registry);
         const { warnings } = validateCandidate(opts.id, candidate, opts.registry, opts.strict, okfVersion, decisionNow);
         const { doc, version } = await writeDocVersionedForEdition(opts.bundle, { id: opts.id, ...candidate }, okfVersion, {
@@ -232,7 +292,7 @@ export async function mutateDocument(opts) {
             decide: async (existing) => {
                 const decisionNow = onceNow(now);
                 assertFieldPreconditions(opts.id, existing?.frontmatter, opts.preconditions, lastReadVersion);
-                const withMetadata = withV02Metadata(await opts.buildCandidate(existing === undefined ? undefined : structuredClone(existing), context), existing, okfVersion, opts.registry, decisionNow, seedClock, opts.actor, compareTimestamp, opts.producer);
+                const withMetadata = withV02Metadata(await build(existing, decisionNow), existing, okfVersion, opts.registry, decisionNow, seedClock, opts.actor, compareTimestamp, opts.producer);
                 const candidate = attributeCandidate(withMetadata, opts.actor, persistActor, okfVersion, opts.registry);
                 const validated = validateCandidate(opts.id, candidate, opts.registry, opts.strict, okfVersion, decisionNow, existing);
                 warnings = validated.warnings;
@@ -287,13 +347,13 @@ export async function mutateDocument(opts) {
             if (hardCas && lastReadVersion !== opts.expectedVersion) {
                 throw new VersionConflict(opts.id, opts.expectedVersion, lastReadVersion);
             }
-            const rawCandidate = await opts.buildCandidate(existing === undefined ? undefined : structuredClone(existing), context);
-            const candidateForComparison = withV02Metadata(rawCandidate, existing, okfVersion, opts.registry, decisionNow, seedClock, opts.actor, compareTimestamp, opts.producer);
-            if (existing && isNoopMutation(existing, candidateForComparison, compareTimestamp, okfVersion, okfVersion === "0.2" && persistActor && opts.actor !== undefined, opts.registry.kinds.get(String(candidateForComparison.frontmatter.type))?.fields.required.includes("actor") ?? false)) {
+            const rawCandidate = await build(existing, decisionNow);
+            const { candidate, changed, warnings } = prepareDocumentMutationCandidate(existing, rawCandidate, {
+                id: opts.id, registry: opts.registry, strict: opts.strict, okfVersion, now: decisionNow,
+                actor: opts.actor, producer: opts.producer, persistActor, compareTimestamp, seedGenerationClock: seedClock,
+            });
+            if (!changed)
                 return { action: "done", result: { doc: existing, warnings: [] } };
-            }
-            const candidate = attributeCandidate(candidateForComparison, opts.actor, persistActor, okfVersion, opts.registry);
-            const { warnings } = validateCandidate(opts.id, candidate, opts.registry, opts.strict, okfVersion, decisionNow, existing);
             return { action: "write", next: { id: opts.id, ...candidate }, result: { warnings } };
         },
         write: async (next, expectedVersion) => {
@@ -307,7 +367,7 @@ export async function mutateDocument(opts) {
         maxAttempts: hardCas ? 1 : maxAttempts,
     });
     return outcome.wrote
-        ? { doc: savedDoc, changed: true, version: outcome.version, warnings: outcome.result.warnings }
-        : { doc: outcome.result.doc, changed: false, version: outcome.version, warnings: [] };
+        ? { doc: savedDoc, changed: true, version: outcome.version, warnings: outcome.result.warnings, ...(scope ? { scope } : {}) }
+        : { doc: outcome.result.doc, changed: false, version: outcome.version, warnings: [], ...(scope ? { scope } : {}) };
 }
 //# sourceMappingURL=document-mutation.js.map