@superbee/core 0.1.0

package/dist/bundle.js.map

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

package/dist/content-type.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared content_type inference — PORTED from holaxis-agentstate
+ * (`packages/schemas/src/content-type.ts`, dx-05 / `specs/zod-validation-layer-spec.md` §2.7).
+ *
+ * This is the single source for "infer a MIME `content_type` from a doc path extension." In the
+ * OKF store engine it is exposed for downstream consumers (the CLI's promote/pull commands,
+ * Page assets, and any `resource`-pointing frontmatter) rather than being stamped onto concept
+ * docs — OKF concept files are always markdown, and the format favors clean, spec-minimal
+ * frontmatter, so the engine does NOT inject a `content_type` key into concept documents.
+ *
+ * IMPORTANT: this file has NO runtime `zod` import (only a type-only import of `ValidationWarning`,
+ * which the compiler erases), so it stays dependency-free.
+ *
+ * Design guardrails (unchanged from source):
+ *  - Inference only FILLS a gap: an explicit caller-supplied `content_type` always wins.
+ *  - For an unknown/ambiguous extension we keep the call site's existing default AND emit a warning —
+ *    we never guess wildly. Genuinely ambiguous extensions (e.g. `.ts` = TypeScript vs MPEG-TS) are
+ *    deliberately omitted from the table so they fall through to the fallback.
+ *  - A path with NO extension infers nothing and warns nothing.
+ *  - When the inferred type EQUALS the call site's existing default there is no behavior change, so no
+ *    warning is emitted.
+ */
+import type { ValidationWarning } from "./validation.js";
+export type { ValidationWarning } from "./validation.js";
+/**
+ * Extension (lower-case, no dot) -> MIME content_type. Text-ish types carry `; charset=utf-8`.
+ * Binary types carry no charset. Deliberately conservative — ambiguous extensions are omitted.
+ */
+export declare const EXTENSION_CONTENT_TYPES: Readonly<Record<string, string>>;
+/**
+ * Lower-cased extension (no dot) of the LAST path segment of `docKey`, or `undefined` when the final
+ * segment has no extension (no dot, or a leading-dot dotfile like `.gitignore`).
+ */
+export declare function extensionOfDocKey(docKey: string): string | undefined;
+/**
+ * Look up the inferred content_type for a `doc_key` extension, or `undefined` when the extension is
+ * absent or unrecognized. This is the low-level lookup; most callers want
+ * {@link inferContentTypeForNewBlob}, which also produces the warning.
+ */
+export declare function inferContentTypeFromDocKey(docKey: string): string | undefined;
+/** Outcome of {@link inferContentTypeForNewBlob}. */
+export type ContentTypeInference = {
+    /** The content_type to stamp on a brand-new blob (inferred type, or the call site's `fallback`). */
+    contentType: string;
+    /** True when an extension was recognized and produced `contentType`. */
+    inferred: boolean;
+    /**
+     * Non-fatal warning to surface, or `undefined` when there is nothing to report (no extension, or
+     * the inferred type equals `fallback` so behavior is unchanged).
+     */
+    warning?: ValidationWarning;
+};
+/** Fallback content-type when a blob key has no extension, or an unrecognized one, and no explicit override was supplied. */
+export declare const DEFAULT_BLOB_CONTENT_TYPE = "application/octet-stream";
+/**
+ * THE ONE place a blob's content-type is resolved (`StorageBackend.readBlob`/`writeBlob`
+ * both route through this): an explicit `override` always wins; otherwise infer from
+ * `key`'s extension via {@link inferContentTypeFromDocKey}; otherwise
+ * {@link DEFAULT_BLOB_CONTENT_TYPE}. A trimmed-empty `override` is treated as absent
+ * (never resolves to `""`).
+ */
+export declare function resolveContentType(key: string, override?: string): string;
+/**
+ * Decide the brand-new-blob content_type from a `doc_key` extension, FALLING BACK to the call site's
+ * existing default. Call this ONLY when the caller supplied no explicit content_type — explicit types
+ * always win and must short-circuit before reaching here.
+ *
+ * @param docKey   the destination document key.
+ * @param fallback the call site's pre-existing brand-new-blob default.
+ */
+export declare function inferContentTypeForNewBlob(docKey: string, fallback: string): ContentTypeInference;
+//# sourceMappingURL=content-type.d.ts.map

package/dist/content-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-type.d.ts","sourceRoot":"","sources":["../src/content-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuCnE,CAAC;AAEH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOpE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI7E;AAED,qDAAqD;AACrD,MAAM,MAAM,oBAAoB,GAAG;IACjC,oGAAoG;IACpG,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAEF,6HAA6H;AAC7H,eAAO,MAAM,yBAAyB,6BAA6B,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAqCjG"}

package/dist/content-type.js

@@ -0,0 +1,149 @@
+/**
+ * Shared content_type inference — PORTED from holaxis-agentstate
+ * (`packages/schemas/src/content-type.ts`, dx-05 / `specs/zod-validation-layer-spec.md` §2.7).
+ *
+ * This is the single source for "infer a MIME `content_type` from a doc path extension." In the
+ * OKF store engine it is exposed for downstream consumers (the CLI's promote/pull commands,
+ * Page assets, and any `resource`-pointing frontmatter) rather than being stamped onto concept
+ * docs — OKF concept files are always markdown, and the format favors clean, spec-minimal
+ * frontmatter, so the engine does NOT inject a `content_type` key into concept documents.
+ *
+ * IMPORTANT: this file has NO runtime `zod` import (only a type-only import of `ValidationWarning`,
+ * which the compiler erases), so it stays dependency-free.
+ *
+ * Design guardrails (unchanged from source):
+ *  - Inference only FILLS a gap: an explicit caller-supplied `content_type` always wins.
+ *  - For an unknown/ambiguous extension we keep the call site's existing default AND emit a warning —
+ *    we never guess wildly. Genuinely ambiguous extensions (e.g. `.ts` = TypeScript vs MPEG-TS) are
+ *    deliberately omitted from the table so they fall through to the fallback.
+ *  - A path with NO extension infers nothing and warns nothing.
+ *  - When the inferred type EQUALS the call site's existing default there is no behavior change, so no
+ *    warning is emitted.
+ */
+/**
+ * Extension (lower-case, no dot) -> MIME content_type. Text-ish types carry `; charset=utf-8`.
+ * Binary types carry no charset. Deliberately conservative — ambiguous extensions are omitted.
+ */
+export const EXTENSION_CONTENT_TYPES = Object.freeze({
+    // Text / markup / data (searchable + text-readable)
+    html: "text/html; charset=utf-8",
+    htm: "text/html; charset=utf-8",
+    md: "text/markdown; charset=utf-8",
+    markdown: "text/markdown; charset=utf-8",
+    txt: "text/plain; charset=utf-8",
+    text: "text/plain; charset=utf-8",
+    log: "text/plain; charset=utf-8",
+    csv: "text/csv; charset=utf-8",
+    tsv: "text/tab-separated-values; charset=utf-8",
+    json: "application/json; charset=utf-8",
+    jsonl: "application/json; charset=utf-8",
+    ndjson: "application/json; charset=utf-8",
+    xml: "application/xml; charset=utf-8",
+    yaml: "application/yaml; charset=utf-8",
+    yml: "application/yaml; charset=utf-8",
+    toml: "application/toml; charset=utf-8",
+    css: "text/css; charset=utf-8",
+    js: "text/javascript; charset=utf-8",
+    mjs: "text/javascript; charset=utf-8",
+    cjs: "text/javascript; charset=utf-8",
+    // Images
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    bmp: "image/bmp",
+    ico: "image/x-icon",
+    svg: "image/svg+xml",
+    // Documents / archives / binary
+    pdf: "application/pdf",
+    zip: "application/zip",
+    gz: "application/gzip",
+    tar: "application/x-tar",
+    wasm: "application/wasm",
+    woff: "font/woff",
+    woff2: "font/woff2",
+});
+/**
+ * Lower-cased extension (no dot) of the LAST path segment of `docKey`, or `undefined` when the final
+ * segment has no extension (no dot, or a leading-dot dotfile like `.gitignore`).
+ */
+export function extensionOfDocKey(docKey) {
+    const lastSegment = docKey.split("/").pop() ?? docKey;
+    const dot = lastSegment.lastIndexOf(".");
+    // No dot, or a leading-dot dotfile (".gitignore") — nothing to infer from.
+    if (dot <= 0)
+        return undefined;
+    const ext = lastSegment.slice(dot + 1).toLowerCase();
+    return ext.length > 0 ? ext : undefined;
+}
+/**
+ * Look up the inferred content_type for a `doc_key` extension, or `undefined` when the extension is
+ * absent or unrecognized. This is the low-level lookup; most callers want
+ * {@link inferContentTypeForNewBlob}, which also produces the warning.
+ */
+export function inferContentTypeFromDocKey(docKey) {
+    const ext = extensionOfDocKey(docKey);
+    if (!ext)
+        return undefined;
+    return EXTENSION_CONTENT_TYPES[ext];
+}
+/** Fallback content-type when a blob key has no extension, or an unrecognized one, and no explicit override was supplied. */
+export const DEFAULT_BLOB_CONTENT_TYPE = "application/octet-stream";
+/**
+ * THE ONE place a blob's content-type is resolved (`StorageBackend.readBlob`/`writeBlob`
+ * both route through this): an explicit `override` always wins; otherwise infer from
+ * `key`'s extension via {@link inferContentTypeFromDocKey}; otherwise
+ * {@link DEFAULT_BLOB_CONTENT_TYPE}. A trimmed-empty `override` is treated as absent
+ * (never resolves to `""`).
+ */
+export function resolveContentType(key, override) {
+    if (typeof override === "string" && override.trim() !== "")
+        return override;
+    return inferContentTypeFromDocKey(key) ?? DEFAULT_BLOB_CONTENT_TYPE;
+}
+/**
+ * Decide the brand-new-blob content_type from a `doc_key` extension, FALLING BACK to the call site's
+ * existing default. Call this ONLY when the caller supplied no explicit content_type — explicit types
+ * always win and must short-circuit before reaching here.
+ *
+ * @param docKey   the destination document key.
+ * @param fallback the call site's pre-existing brand-new-blob default.
+ */
+export function inferContentTypeForNewBlob(docKey, fallback) {
+    const ext = extensionOfDocKey(docKey);
+    if (!ext) {
+        // No extension to reason about — preserve today's silent default.
+        return { contentType: fallback, inferred: false };
+    }
+    const mime = EXTENSION_CONTENT_TYPES[ext];
+    if (mime) {
+        if (mime === fallback) {
+            // Recognized, but identical to today's default — no behavior change, so stay quiet.
+            return { contentType: mime, inferred: true };
+        }
+        return {
+            contentType: mime,
+            inferred: true,
+            warning: {
+                code: "CONTENT_TYPE_INFERRED",
+                message: `content_type not provided; inferred '${mime}' from the '.${ext}' doc_key extension.`,
+                field: "content_type",
+                severity: "info",
+            },
+        };
+    }
+    // Present-but-unrecognized extension: keep the existing default, but breadcrumb that we saw an
+    // extension we do not infer for (do not guess wildly).
+    return {
+        contentType: fallback,
+        inferred: false,
+        warning: {
+            code: "CONTENT_TYPE_INFER_FALLBACK",
+            message: `content_type not provided and the '.${ext}' doc_key extension is not recognized; defaulting to '${fallback}'.`,
+            field: "content_type",
+            severity: "info",
+        },
+    };
+}
+//# sourceMappingURL=content-type.js.map

package/dist/content-type.js.map

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

package/dist/document-mutation.d.ts

@@ -0,0 +1,83 @@
+/**
+ * CLI-neutral document mutation policy.
+ *
+ * This is the document-specific layer above {@link versionedMutation}: create-only,
+ * overwrite, and patch postures share fresh-read/CAS coupling, kind validation,
+ * timestamp ordering, semantic no-op detection, attribution, and final receipts.
+ * Consumers own their transport and presentation errors; this module throws typed
+ * core failures and never imports CLI or browser concerns.
+ */
+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";
+/** The frontmatter and body a caller wants persisted; the service supplies the id. */
+export interface DocumentMutationCandidate {
+    frontmatter: Frontmatter;
+    body: string;
+}
+/** Root-derived bundle facts supplied by the mutation authority to candidate construction. */
+export interface DocumentMutationContext {
+    okfVersion: "0.1" | "0.2";
+}
+/** Typed strict-kind rejection for trusted consumers to translate at their own boundary. */
+export declare class KindConformanceError extends InvalidInputError {
+    readonly id: ConceptId;
+    readonly governs: string;
+    readonly violations: ValidationWarning[];
+    readonly okfVersion?: "0.1" | "0.2";
+    constructor(id: ConceptId, governs: string, violations: ValidationWarning[], okfVersion?: "0.1" | "0.2");
+}
+/** Typed missing-document result for patch callers that require an existing target. */
+export declare class DocumentNotFoundError extends Error {
+    readonly id: ConceptId;
+    constructor(id: ConceptId);
+}
+export interface MutateDocumentOptions {
+    bundle: Bundle;
+    id: ConceptId;
+    mode: DocumentMutationMode;
+    /** Loaded once by the trusted caller; the service never performs registry discovery implicitly. */
+    registry: KindRegistry;
+    /** Reject rather than return a non-empty kind warning set. */
+    strict: boolean;
+    /** Recomputed against every fresh CAS attempt. */
+    buildCandidate: (existing: OkfDocument | undefined, context: DocumentMutationContext) => DocumentMutationCandidate | Promise<DocumentMutationCandidate>;
+    /** Patch only: require an existing target or allow an expect-absent create. */
+    onAbsent?: "fail" | "create";
+    /** Retry budget for overwrite and ordinary patch. */
+    maxAttempts?: number;
+    /** Include the legacy timestamp in semantic no-op comparison. */
+    compareTimestamp?: boolean;
+    /** Advisory backend-history attribution, applied only when a write occurs. */
+    actor?: string;
+    /** Also persist the advisory actor in the edition-appropriate frontmatter field after no-op detection. */
+    persistActor?: boolean;
+    /** Patch only: a caller-supplied token makes the operation a single-shot hard CAS. */
+    expectedVersion?: Version;
+    /**
+     * Read-based modes only: asserted facts about the observed document, ANDed and re-evaluated
+     * against EVERY attempt's fresh read before any candidate is built. An unsatisfied assertion is
+     * a terminal {@link PreconditionFailed} — never a retry — so the guard and the CAS write commit
+     * or refuse together.
+     */
+    preconditions?: readonly FieldPrecondition[];
+    /** Test seam for edition-specific clocks; production defaults to the current ISO instant. */
+    now?: () => string;
+    /**
+     * Seed the v0.2 generation clock (`generated: {by, at}`) on creates that carry no usable
+     * time value (default true). Definition installers (recipe application) pass false so the
+     * installed definition's bytes stay comparable to the recipe source across reinstalls.
+     */
+    seedGenerationClock?: boolean;
+}
+export interface DocumentMutationResult {
+    doc: OkfDocument;
+    changed: boolean;
+    version: Version;
+    warnings: ValidationWarning[];
+}
+export declare function mutateDocument(opts: MutateDocumentOptions): Promise<DocumentMutationResult>;
+//# sourceMappingURL=document-mutation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-mutation.d.ts","sourceRoot":"","sources":["../src/document-mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkBhD,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,kDAAkD;IAClD,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,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;AAgLD,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAmMjG"}

package/dist/document-mutation.js

@@ -0,0 +1,319 @@
+/**
+ * CLI-neutral document mutation policy.
+ *
+ * This is the document-specific layer above {@link versionedMutation}: create-only,
+ * overwrite, and patch postures share fresh-read/CAS coupling, kind validation,
+ * timestamp ordering, semantic no-op detection, attribution, and final receipts.
+ * Consumers own their transport and presentation errors; this module throws typed
+ * core failures and never imports CLI or browser concerns.
+ */
+import { InvalidInputError } from "./errors.js";
+import { applyV02MutationMetadata } from "./document-write-policy.js";
+import { assertFieldPreconditions } from "./document-precondition.js";
+import { normalizeDocumentBodyForStorage } from "./frontmatter.js";
+import { parseTimestamp } from "./freshness.js";
+import { meaningfulChangeTimeValue } from "./meaningful-change-time.js";
+import { persistMutationActor, SUPERBEE_UPDATED_BY_FIELD } from "./mutation-attribution.js";
+import { defaultTimestampAndValidateAgainstRegistry, validateAgainstKind, } from "./kinds.js";
+import { versionedMutation } from "./mutation.js";
+import { VersionConflict } from "./versioning.js";
+import { readBundleOkfVersion, readDocVersioned, writeDocVersionedForEdition, } from "./bundle.js";
+const DEFAULT_MAX_ATTEMPTS = 5;
+/** Typed strict-kind rejection for trusted consumers to translate at their own boundary. */
+export class KindConformanceError extends InvalidInputError {
+    id;
+    governs;
+    violations;
+    okfVersion;
+    constructor(id, governs, violations, okfVersion) {
+        super(`'${id}' does not satisfy the '${governs}' kind: ${violations.map((warning) => warning.message).join("; ")}`);
+        this.name = "KindConformanceError";
+        this.id = id;
+        this.governs = governs;
+        this.violations = violations;
+        this.okfVersion = okfVersion;
+    }
+}
+/** Typed missing-document result for patch callers that require an existing target. */
+export class DocumentNotFoundError extends Error {
+    id;
+    constructor(id) {
+        super(`no concept document at id '${id}'`);
+        this.name = "DocumentNotFoundError";
+        this.id = id;
+    }
+}
+/** Structural equality through plain objects and arrays, independent of object key order. */
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        return a.length === b.length && a.every((value, index) => valuesEqual(value, b[index]));
+    }
+    if (a && b && typeof a === "object" && typeof b === "object") {
+        const aRecord = a;
+        const bRecord = b;
+        const aKeys = Object.keys(aRecord);
+        const bKeys = Object.keys(bRecord);
+        return aKeys.length === bKeys.length && aKeys.every((key) => valuesEqual(aRecord[key], bRecord[key]));
+    }
+    return false;
+}
+function withoutAutomaticMutationActor(frontmatter, okfVersion, kindRequiresActor) {
+    if (okfVersion === "0.1") {
+        const { actor: _actor, ...rest } = frontmatter;
+        return rest;
+    }
+    const { [SUPERBEE_UPDATED_BY_FIELD]: _updatedBy, ...rest } = frontmatter;
+    if (!kindRequiresActor)
+        return rest;
+    const { actor: _actor, ...withoutActor } = rest;
+    return withoutActor;
+}
+function withCanonicalComparableTimestamp(frontmatter) {
+    const timestamp = frontmatter.timestamp;
+    if (typeof timestamp !== "string")
+        return frontmatter;
+    const instant = Date.parse(timestamp);
+    if (Number.isNaN(instant))
+        return frontmatter;
+    const canonical = new Date(instant).toISOString();
+    return canonical === timestamp ? frontmatter : { ...frontmatter, timestamp: canonical };
+}
+function isNoopMutation(existing, candidate, compareTimestamp, okfVersion, ignoreAutomaticActor = false, kindRequiresActor = false) {
+    if (normalizeDocumentBodyForStorage(candidate.body)
+        !== normalizeDocumentBodyForStorage(existing.body)) {
+        return false;
+    }
+    const existingFrontmatterWithActorPolicy = ignoreAutomaticActor
+        ? withoutAutomaticMutationActor(existing.frontmatter, okfVersion, kindRequiresActor)
+        : existing.frontmatter;
+    const candidateFrontmatterWithActorPolicy = ignoreAutomaticActor
+        ? withoutAutomaticMutationActor(candidate.frontmatter, okfVersion, kindRequiresActor)
+        : candidate.frontmatter;
+    const existingFrontmatter = compareTimestamp
+        ? withCanonicalComparableTimestamp(existingFrontmatterWithActorPolicy)
+        : existingFrontmatterWithActorPolicy;
+    const candidateFrontmatter = compareTimestamp
+        ? withCanonicalComparableTimestamp(candidateFrontmatterWithActorPolicy)
+        : candidateFrontmatterWithActorPolicy;
+    if (okfVersion === "0.2") {
+        const withoutGeneratedAt = (frontmatter) => {
+            const generated = frontmatter.generated;
+            if (generated === null || typeof generated !== "object" || Array.isArray(generated)) {
+                return frontmatter;
+            }
+            const { at: _at, ...generatedRest } = generated;
+            return { ...frontmatter, generated: generatedRest };
+        };
+        return valuesEqual(withoutGeneratedAt(existingFrontmatter), withoutGeneratedAt(candidateFrontmatter));
+    }
+    if (compareTimestamp)
+        return valuesEqual(existingFrontmatter, candidateFrontmatter);
+    const { timestamp: _existingTimestamp, ...existingRest } = existingFrontmatter;
+    const { timestamp: _candidateTimestamp, ...candidateRest } = candidateFrontmatter;
+    return valuesEqual(existingRest, candidateRest);
+}
+function attributeCandidate(candidate, actor, persistActor, okfVersion, registry) {
+    if (!persistActor)
+        return candidate;
+    const kind = registry.kinds.get(String(candidate.frontmatter.type));
+    return {
+        ...candidate,
+        frontmatter: persistMutationActor(candidate.frontmatter, {
+            actor,
+            okfVersion,
+            kindRequiresActor: kind?.fields.required.includes("actor") ?? false,
+        }),
+    };
+}
+/**
+ * Validate `candidate` against its own (possibly retyped) governing kind, defaulting its
+ * timestamp first. Returns the kind alongside the warnings so overwrite's ratchet (below) can
+ * reuse this ONE validation pass instead of re-deriving the candidate's kind separately.
+ */
+function validateCandidate(id, candidate, registry, strict, okfVersion, now) {
+    const result = defaultTimestampAndValidateAgainstRegistry({ id, ...candidate }, registry, { okfVersion, now });
+    if (strict && result.kind && result.warnings.length > 0) {
+        throw new KindConformanceError(id, result.kind.governs, result.warnings, okfVersion);
+    }
+    return result;
+}
+function withV02Metadata(candidate, existing, okfVersion, registry, now, seedGenerationClock) {
+    if (okfVersion !== "0.2")
+        return candidate;
+    const kind = registry.kinds.get(String(candidate.frontmatter.type));
+    return applyV02MutationMetadata({
+        existing,
+        candidate,
+        meaningfulChangeAt: now(),
+        // 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
+        // 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,
+    });
+}
+/** One stable instant per CAS decision, shared by every clock a bundle Kind explicitly carries. */
+function onceNow(now) {
+    let value;
+    return () => (value ??= now());
+}
+/**
+ * True when `existing` already satisfies ITS OWN governing kind — the monotone ratchet's
+ * precondition (probe: tasks/overwrite-ratchet-survey). Validates the RAW existing
+ * frontmatter — no timestamp defaulting — because the existing doc IS its raw bytes; nothing
+ * normalizes it unless written. This keeps the ratchet in agreement with `status`'s
+ * `conformance_debt` (both call `validateAgainstKind` on the same unmodified frontmatter;
+ * see tasks/conforms-raw-alignment). `validateAgainstKind` only reads `doc.frontmatter`, so
+ * passing `existing` directly is safe — no defensive clone needed.
+ */
+function conforms(existing, registry) {
+    const kind = registry.kinds.get(String(existing.frontmatter.type));
+    if (!kind)
+        return false;
+    return validateAgainstKind(existing, kind).length === 0;
+}
+export async function mutateDocument(opts) {
+    const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const onAbsent = opts.onAbsent ?? "fail";
+    const compareTimestamp = opts.compareTimestamp ?? false;
+    const persistActor = opts.persistActor ?? false;
+    const seedClock = opts.seedGenerationClock ?? true;
+    const okfVersion = await readBundleOkfVersion(opts.bundle) ?? "0.1";
+    if (okfVersion !== "0.1" && okfVersion !== "0.2") {
+        throw new InvalidInputError(`Unsupported OKF mutation version '${okfVersion}'. This build can mutate 0.1 and 0.2 bundles.`);
+    }
+    const now = opts.now ?? (() => new Date().toISOString());
+    const context = { okfVersion };
+    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
+        // enforcing it would leave a caller believing an unenforced guard is enforced.
+        if (opts.preconditions !== undefined && opts.preconditions.length > 0) {
+            throw new InvalidInputError("field preconditions require an observed document; 'create-only' performs no read "
+                + "(use mode 'patch' with onAbsent: 'create')");
+        }
+        const decisionNow = onceNow(now);
+        const attributed = attributeCandidate(await opts.buildCandidate(undefined, context), opts.actor, persistActor, okfVersion, opts.registry);
+        const candidate = withV02Metadata(attributed, undefined, okfVersion, opts.registry, decisionNow, seedClock);
+        const { warnings } = validateCandidate(opts.id, candidate, opts.registry, opts.strict, okfVersion, decisionNow);
+        const { doc, version } = await writeDocVersionedForEdition(opts.bundle, { id: opts.id, ...candidate }, okfVersion, {
+            expectedVersion: null,
+            actor: opts.actor,
+        });
+        return { doc, changed: true, version, warnings };
+    }
+    // The version of the read the CURRENT attempt is deciding over. `versionedMutation` withholds
+    // version tokens from `decide` so a decision can never be paired with a different read's token;
+    // this records it for the one attempt in flight, and it is only ever REPORTED (the hard-CAS
+    // comparison and a precondition refusal's `observedVersion`) — never used to build a candidate.
+    let lastReadVersion = null;
+    const readExisting = async () => {
+        try {
+            const { doc, version } = await readDocVersioned(opts.bundle, opts.id);
+            lastReadVersion = version;
+            return { state: doc, version };
+        }
+        catch (error) {
+            if (error?.code === "ENOENT") {
+                lastReadVersion = null;
+                return { state: undefined, version: null };
+            }
+            throw error;
+        }
+    };
+    if (opts.mode === "overwrite") {
+        let savedDoc;
+        let warnings = [];
+        const outcome = await versionedMutation({
+            read: readExisting,
+            decide: async (existing) => {
+                const decisionNow = onceNow(now);
+                assertFieldPreconditions(opts.id, existing?.frontmatter, opts.preconditions, lastReadVersion);
+                const attributed = attributeCandidate(await opts.buildCandidate(existing, context), opts.actor, persistActor, okfVersion, opts.registry);
+                const candidate = withV02Metadata(attributed, existing, okfVersion, opts.registry, decisionNow, seedClock);
+                const validated = validateCandidate(opts.id, candidate, opts.registry, opts.strict, okfVersion, decisionNow);
+                warnings = validated.warnings;
+                // Monotone conformance ratchet (probe: tasks/overwrite-ratchet-survey, productionized
+                // here): a doc that already satisfies its governing kind may not regress into
+                // non-conformance through a lenient (non-strict) overwrite — once clean, always clean.
+                // A doc that has NEVER conformed keeps today's lenient staging behavior (warn, don't
+                // block), and dropping only OPTIONAL fields can't trip this (validateAgainstKind never
+                // warns on those), so this only ever fires on a REAL regression. Retyping to an
+                // ungoverned type is a documented escape: an ungoverned candidate carries zero
+                // warnings by construction, so the `warnings.length > 0` guard below never sees it.
+                // Every overwrite caller, including `promote`, inherits this rule from this shared boundary.
+                if (!opts.strict && existing && warnings.length > 0 && conforms(existing, opts.registry)) {
+                    throw new KindConformanceError(opts.id, validated.kind.governs, warnings, okfVersion);
+                }
+                if (existing
+                    && isNoopMutation(existing, candidate, compareTimestamp, okfVersion, persistActor && opts.actor !== undefined, validated.kind?.fields.required.includes("actor") ?? false)) {
+                    return { action: "done", result: { doc: existing } };
+                }
+                return { action: "write", next: { id: opts.id, ...candidate }, result: {} };
+            },
+            write: async (next, expectedVersion) => {
+                const written = await writeDocVersionedForEdition(opts.bundle, next, okfVersion, {
+                    expectedVersion,
+                    actor: opts.actor,
+                });
+                savedDoc = written.doc;
+                return written.version;
+            },
+            maxAttempts,
+        });
+        return outcome.wrote
+            ? { doc: savedDoc, changed: true, version: outcome.version, warnings }
+            : { doc: outcome.result.doc, changed: false, version: outcome.version, warnings };
+    }
+    let savedDoc;
+    const hardCas = opts.expectedVersion !== undefined;
+    const outcome = await versionedMutation({
+        read: async () => {
+            const read = await readExisting();
+            if (read.state === undefined && onAbsent === "fail")
+                throw new DocumentNotFoundError(opts.id);
+            return read;
+        },
+        decide: async (existing) => {
+            const decisionNow = onceNow(now);
+            // Ahead of the version comparison on purpose: when both an asserted fact and the caller's
+            // version token are stale, the domain answer is the true one and the terminal one. Reporting
+            // a conflict instead would tell a refused caller its premise merely moved, and invite the
+            // re-read-and-retry that overwrites whoever changed the field.
+            assertFieldPreconditions(opts.id, existing?.frontmatter, opts.preconditions, lastReadVersion);
+            if (hardCas && lastReadVersion !== opts.expectedVersion) {
+                throw new VersionConflict(opts.id, opts.expectedVersion, lastReadVersion);
+            }
+            const rawCandidate = await opts.buildCandidate(existing, context);
+            const candidateForComparison = withV02Metadata(rawCandidate, existing, okfVersion, opts.registry, decisionNow, seedClock);
+            if (existing && isNoopMutation(existing, candidateForComparison, compareTimestamp, okfVersion)) {
+                return { action: "done", result: { doc: existing, warnings: [] } };
+            }
+            const attributed = attributeCandidate(rawCandidate, opts.actor, persistActor, okfVersion, opts.registry);
+            const candidate = withV02Metadata(attributed, existing, okfVersion, opts.registry, decisionNow, seedClock);
+            const { warnings } = validateCandidate(opts.id, candidate, opts.registry, opts.strict, okfVersion, decisionNow);
+            return { action: "write", next: { id: opts.id, ...candidate }, result: { warnings } };
+        },
+        write: async (next, expectedVersion) => {
+            const written = await writeDocVersionedForEdition(opts.bundle, next, okfVersion, {
+                expectedVersion: hardCas ? opts.expectedVersion : expectedVersion,
+                actor: opts.actor,
+            });
+            savedDoc = written.doc;
+            return written.version;
+        },
+        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: [] };
+}
+//# sourceMappingURL=document-mutation.js.map