@superbee/core 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/dependencies.js

@@ -0,0 +1,180 @@
+/**
+ * Bundle identity and the `docs/dependencies` declaration.
+ *
+ * A bundle names the other bundles it links into in ONE committed document, `docs/dependencies`
+ * (type `Bundle Dependencies`). Each entry maps a local alias (the `<alias>` in
+ * `okf://<alias>/<path>.md`) to the target's portable `bundle_id`, plus optional `source`, `pin`
+ * and `path`. A target confirms its own identity with `bundle_id` in its `docs/bundle` document.
+ *
+ * Pure and browser-safe: no `node:*` import, no I/O. Consumers read the documents through their
+ * own backend and hand them here.
+ */
+// ── Bundle identity ─────────────────────────────────────────────────────────
+// A portable bundle id: lower-case letters and digits joined by `.`, `_` or `-`, starting with a
+// letter, at most 128 characters. The one rule hosted `checkout`, `export` and `publish` accept an
+// id by, and the one a printed `checkout <id>` command is emitted for: an id it rejects (one
+// starting with `-` would read as an option) never appears in a command.
+const BUNDLE_ID = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const BUNDLE_ID_MAX_LENGTH = 128;
+/** True when `id` is a portable bundle id (the hosted bundle-id grammar). */
+export function isHostedBundleId(id) {
+    return id.length <= BUNDLE_ID_MAX_LENGTH && BUNDLE_ID.test(id);
+}
+/**
+ * The well-known concept id carrying a bundle's explicit display name and portable id. NOT the
+ * bundle-root `index.md` — OKF §3.1 reserves that file's frontmatter solely for `okf_version`, so
+ * the name needs its own small doc.
+ */
+export const BUNDLE_NAME_DOC_ID = "docs/bundle";
+/**
+ * The ownership marker: `docs/bundle` speaks for the bundle ONLY when it carries exactly this
+ * `type`. A `docs/bundle` doc of any other type is an ordinary document and is ignored, so an
+ * unrelated pre-existing doc is never appropriated as the bundle's name or id.
+ */
+export const BUNDLE_NAME_DOC_TYPE = "Bundle Name";
+/**
+ * The bundle's self-declared portable id: `bundle_id` in `docs/bundle` under the marker type, when
+ * it satisfies {@link isHostedBundleId}. Anything else (absent doc, other type, missing or
+ * malformed id) is `undefined`; the caller decides what a bundle without a declared id means.
+ */
+export function declaredBundleId(doc) {
+    if (!doc || doc.id !== BUNDLE_NAME_DOC_ID)
+        return undefined;
+    const type = doc.frontmatter.type;
+    if (typeof type !== "string" || type.trim() !== BUNDLE_NAME_DOC_TYPE)
+        return undefined;
+    const id = doc.frontmatter.bundle_id;
+    return typeof id === "string" && isHostedBundleId(id) ? id : undefined;
+}
+// ── docs/dependencies ───────────────────────────────────────────────────────
+export const DEPENDENCIES_DOC_ID = "docs/dependencies";
+export const DEPENDENCIES_DOC_TYPE = "Bundle Dependencies";
+/** The alias grammar shared by `okf://<alias>/…` hrefs, dependency keys and qualified Kind targets. */
+export const BUNDLE_ALIAS = /^[a-z][a-z0-9-]{0,62}$/;
+export function isBundleAlias(alias) {
+    return BUNDLE_ALIAS.test(alias);
+}
+const KNOWN_KEYS = new Set(["bundle_id", "source", "pin", "path"]);
+/** Reserved for recipe dependencies, which will reuse this declaration. */
+const RESERVED_KEYS = new Set(["use", "version", "channel"]);
+const COMMIT_PIN = /^[0-9a-f]{7,40}$/;
+const DIGEST_PIN = /^sha256:[0-9a-f]{64}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
+/**
+ * Absolute under POSIX or win32 rules, or carrying a backslash. Pure string checks (no
+ * `node:path`) so the verdict is the same on every host: `/x`, `\x`, `\\server\share`, `C:\x`,
+ * `C:/x` and the drive-relative `C:x` are all refused.
+ */
+export function isNonPortableDependencyPath(value) {
+    return value.startsWith("/") || value.includes("\\") || /^[A-Za-z]:/.test(value);
+}
+function parsePin(value) {
+    if (typeof value !== "string")
+        return null;
+    if (COMMIT_PIN.test(value))
+        return { kind: "commit", value };
+    if (DIGEST_PIN.test(value))
+        return { kind: "digest", value };
+    return null;
+}
+/**
+ * Parse `docs/dependencies`. Never throws: every defect is a problem, and an entry whose alias,
+ * `bundle_id` or `pin` is unusable is dropped (fail closed: a link under it reads as
+ * `unknown_alias`, never as resolved against the wrong copy). An unusable `source` or `path` drops
+ * only that field. Unknown and reserved keys are reported and the entry is kept.
+ */
+export function parseDependencies(doc, options = {}) {
+    const dependencies = new Map();
+    const problems = [];
+    const rejected = new Map();
+    const result = () => ({ dependencies, problems, rejected });
+    const reject = (alias, code, detail) => {
+        problems.push({ code, alias, detail });
+        rejected.set(alias, code);
+    };
+    if (!doc)
+        return result();
+    const type = doc.frontmatter.type;
+    if (typeof type !== "string" || type.trim() !== DEPENDENCIES_DOC_TYPE) {
+        problems.push({ code: "DEP_TYPE", detail: `type must be '${DEPENDENCIES_DOC_TYPE}'` });
+        return result();
+    }
+    const declared = doc.frontmatter.dependencies;
+    if (declared === undefined || declared === null)
+        return result();
+    if (!isRecord(declared)) {
+        problems.push({ code: "DEP_SHAPE", detail: "dependencies must be a mapping of alias to entry" });
+        return result();
+    }
+    const aliasByBundle = new Map();
+    for (const [alias, raw] of Object.entries(declared)) {
+        if (!isBundleAlias(alias)) {
+            problems.push({ code: "DEP_ALIAS", alias, detail: "alias must match ^[a-z][a-z0-9-]{0,62}$" });
+            continue;
+        }
+        if (!isRecord(raw)) {
+            reject(alias, "DEP_SHAPE", "entry must be a mapping");
+            continue;
+        }
+        const bundleId = raw.bundle_id;
+        if (typeof bundleId !== "string" || !isHostedBundleId(bundleId)) {
+            reject(alias, "DEP_BUNDLE_ID", "bundle_id is required and must be a portable bundle id");
+            continue;
+        }
+        let pin;
+        if (raw.pin !== undefined) {
+            const parsed = parsePin(raw.pin);
+            if (parsed === null) {
+                // A YAML scalar such as 1234567 or 3e45678 arrives as a number, so the hint says to quote.
+                reject(alias, "DEP_PIN", "pin must be a quoted commit (7-40 lower-case hex) or sha256:<64 lower-case hex>");
+                continue;
+            }
+            pin = parsed;
+        }
+        if (options.selfBundleId !== undefined && bundleId === options.selfBundleId) {
+            reject(alias, "DEP_SELF", `bundle_id '${bundleId}' is this bundle`);
+            continue;
+        }
+        const earlier = aliasByBundle.get(bundleId);
+        if (earlier !== undefined) {
+            reject(alias, "DEP_DUPLICATE_BUNDLE", `bundle_id '${bundleId}' is already declared as '${earlier}'`);
+            continue;
+        }
+        const entry = { alias, bundle_id: bundleId };
+        if (raw.source !== undefined) {
+            if (typeof raw.source === "string" && raw.source.trim() !== "")
+                entry.source = raw.source;
+            else
+                problems.push({ code: "DEP_SHAPE", alias, detail: "source must be a non-empty string" });
+        }
+        if (pin)
+            entry.pin = pin;
+        if (raw.path !== undefined) {
+            if (typeof raw.path !== "string" || raw.path.trim() === "") {
+                problems.push({ code: "DEP_SHAPE", alias, detail: "path must be a non-empty string" });
+            }
+            else if (isNonPortableDependencyPath(raw.path)) {
+                problems.push({ code: "DEP_PATH_ABSOLUTE", alias, detail: "path must be relative to this bundle's root, with '/' separators" });
+            }
+            else {
+                entry.path = raw.path;
+            }
+        }
+        for (const key of Object.keys(raw)) {
+            if (KNOWN_KEYS.has(key))
+                continue;
+            if (RESERVED_KEYS.has(key)) {
+                problems.push({ code: "DEP_RESERVED_KEY", alias, detail: `'${key}' is reserved for recipe dependencies` });
+            }
+            else {
+                problems.push({ code: "DEP_UNKNOWN_KEY", alias, detail: `unknown key '${key}'` });
+            }
+        }
+        aliasByBundle.set(bundleId, alias);
+        dependencies.set(alias, entry);
+    }
+    return result();
+}
+//# sourceMappingURL=dependencies.js.map

package/dist/dependencies.js.map

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

package/dist/document-codec.d.ts

@@ -5,8 +5,13 @@
  */
 export { parseMarkdown, stringifyDoc, stringifyWithData, normalizeDocumentBodyForStorage, MalformedDocumentError, } from "./frontmatter.js";
 export { resolveContentType } from "./content-type.js";
+export { captureRemoteFrontmatter, RemoteDocumentValueError } from "./remote-document-codec.js";
 export type { Frontmatter, OkfDocument, Version } from "./types.js";
 import type { Version } from "./types.js";
-/** SHA-256 version of exact bytes, including binary data, using Web Crypto. */
+/**
+ * SHA-256 version of exact bytes, including binary data. Minted by the same pure
+ * implementation as every other version token, so one digest owner serves Node and
+ * browser runtimes; the async signature is kept for the codec's existing callers.
+ */
 export declare function versionFromBytes(bytes: Uint8Array): Promise<Version>;
 //# sourceMappingURL=document-codec.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"document-codec.d.ts","sourceRoot":"","sources":["../src/document-codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,+BAA+B,EAC/B,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,+EAA+E;AAC/E,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAI1E"}
+{"version":3,"file":"document-codec.d.ts","sourceRoot":"","sources":["../src/document-codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,+BAA+B,EAC/B,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAChG,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAE1E"}

package/dist/document-codec.js

@@ -5,10 +5,14 @@
  */
 export { parseMarkdown, stringifyDoc, stringifyWithData, normalizeDocumentBodyForStorage, MalformedDocumentError, } from "./frontmatter.js";
 export { resolveContentType } from "./content-type.js";
-/** SHA-256 version of exact bytes, including binary data, using Web Crypto. */
+export { captureRemoteFrontmatter, RemoteDocumentValueError } from "./remote-document-codec.js";
+import { sha256HexOfBytes } from "./sha256.js";
+/**
+ * SHA-256 version of exact bytes, including binary data. Minted by the same pure
+ * implementation as every other version token, so one digest owner serves Node and
+ * browser runtimes; the async signature is kept for the codec's existing callers.
+ */
 export async function versionFromBytes(bytes) {
-    const digest = await globalThis.crypto.subtle.digest("SHA-256", new Uint8Array(bytes).buffer);
-    const hex = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
-    return `sha256:${hex}`;
+    return `sha256:${sha256HexOfBytes(bytes)}`;
 }
 //# sourceMappingURL=document-codec.js.map

package/dist/document-codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"document-codec.js","sourceRoot":"","sources":["../src/document-codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,+BAA+B,EAC/B,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAKvD,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAiB;IACtD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9F,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtG,OAAO,UAAU,GAAG,EAAE,CAAC;AACzB,CAAC"}
+{"version":3,"file":"document-codec.js","sourceRoot":"","sources":["../src/document-codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,+BAA+B,EAC/B,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAGhG,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAiB;IACtD,OAAO,UAAU,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7C,CAAC"}

package/dist/document-field-actions.d.ts

@@ -1,4 +1,3 @@
-/** Explicit frontmatter intent. Collection construction is owned here, before CAS metadata. */
 import { InvalidInputError } from "./errors.js";
 import { type KindRegistry } from "./kinds.js";
 import type { Frontmatter, OkfDocument } from "./types.js";
@@ -38,6 +37,14 @@ export type FieldAction = {
     action: "set";
     field: string;
     value: unknown;
+}
+/**
+ * Remove one field: any field `set` admits apart from `type` and the fields the document's Kind
+ * requires (refused with that Kind's `KIND_FIELD_MISSING`). A no-op when the field is absent.
+ */
+ | {
+    action: "unset";
+    field: string;
 } | {
     action: "add";
     field: "tags";
@@ -59,6 +66,19 @@ export type FieldAction = {
     field: "sources";
     selector: SourceSelector;
     patch: Record<string, unknown>;
+}
+/**
+ * Select the one entry whose (`resource`, `id`) pair equals the value's, by the shared
+ * `sources[]` identity rule, and merge the value's properties into it; append the value when
+ * no entry carries the pair. The ID must be nonempty because an upsert may mint it, and it
+ * may not already name an entry under another resource.
+ */
+ | {
+    action: "upsert";
+    field: "sources";
+    value: SourceEntry & {
+        id: string;
+    };
 } | {
     action: "replace-all";
     field: "tags";
@@ -67,6 +87,16 @@ export type FieldAction = {
     action: "replace-all";
     field: "sources";
     value: SourceEntry[];
+}
+/**
+ * The complete list of a field the document's Kind declares as `string-list` or `https-url-list`,
+ * kept in the given order: a Kind cannot say whether its list is a set, so ordering and
+ * deduplication belong to the caller (the Kind's type check refuses repeats on a strict write).
+ */
+ | {
+    action: "replace-all";
+    field: string;
+    value: string[];
 };
 export interface FieldActionScope {
     field: string;

package/dist/document-field-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-field-actions.d.ts","sourceRoot":"","sources":["../src/document-field-actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"document-field-actions.d.ts","sourceRoot":"","sources":["../src/document-field-actions.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,EAA8G,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3J,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAExE,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AACzF,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AACjG,MAAM,WAAW,uBAAuB;IAAG,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAC3F,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,kBAAkB,GAAG,eAAe,GAAG,kBAAkB,GAAG,oBAAoB,GAAG,mBAAmB,GAAG,uBAAuB,CAAC;IACzI,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,mBAAmB,CAAC,EAAE,cAAc,CAAC;IACrC,UAAU,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,4FAA4F;AAC5F,qBAAa,gBAAiB,SAAQ,iBAAiB;IACrD,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;gBAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB;CAK9D;AACD,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AAClD;;;GAGG;GACD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,GAChE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE;AAChG;;;;;GAKG;GACD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,WAAW,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC3E;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE;AACnE;;;;GAIG;GACD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;IACnE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AACD,MAAM,WAAW,kBAAkB;IAAG,QAAQ,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,KAAK,GAAG,KAAK,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE;AAC7G,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,yBAAyB,CAAC;IACrC,KAAK,EAAE,gBAAgB,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAID,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,GAAG,OAAO,CAE5F;AAiBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AACD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAOpG;AACD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAItF;AAKD,+FAA+F;AAC/F,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,yBAAyB,CAOjI;AA+DD,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,GAAG,2BAA2B,CAwJ/I"}

package/dist/document-field-actions.js

@@ -1,7 +1,11 @@
+import { assertTypedListPatch } from "./body-replace-guards.js";
 /** Explicit frontmatter intent. Collection construction is owned here, before CAS metadata. */
+import { isManagedDocumentMetadataField } from "./managed-document-metadata.js";
 import { InvalidInputError } from "./errors.js";
 import { okfValuesEqual } from "./okf-authored-values.js";
-import { kindInputFieldNames, resolveKindFieldCoordinate } from "./kinds.js";
+import { KindConformanceError } from "./kind-conformance-error.js";
+import { isKindListField, kindInputFieldNames, resolveKindFieldCoordinate, validateAgainstKind } from "./kinds.js";
+import { matchesSourceIdentity } from "./query-filter.js";
 /** Adapters can render corrective commands without parsing prose or repeating selection. */
 export class FieldActionError extends InvalidInputError {
     details;
@@ -11,7 +15,6 @@ export class FieldActionError extends InvalidInputError {
         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) {
@@ -52,7 +55,7 @@ export function assertOrdinaryPatch(existing, proposed) {
     }
 }
 function assertAssignmentName(field) {
-    if (managed.has(field))
+    if (isManagedDocumentMetadataField(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.`);
@@ -106,54 +109,114 @@ function selectorIndex(rows, selector, edit) {
     }
     return index;
 }
+/**
+ * The field `set` (and `unset`) may name on this document, resolved to its storage name: a standard
+ * set field of the edition or a field the document's Kind declares. Anything else is
+ * `unsupported-set-field`, listing what the action would accept.
+ */
+function admittedField(existing, field, context, action) {
+    const kind = context.registry.kinds.get(String(existing.frontmatter.type)) ?? undefined;
+    const coordinate = kind && resolveKindFieldCoordinate(context.okfVersion, kind, field);
+    if (context.okfVersion === "0.1" && (field === "stale_after" || field === "usage_window"))
+        throw new InvalidInputError(`'${field}' requires OKF v0.2.`);
+    if (!isStandardDocumentSetField(field, context.okfVersion) && !coordinate) {
+        const supportedFields = [...new Set([
+                ...standard,
+                ...(context.okfVersion === "0.2" ? v02 : []),
+                ...(kind ? kindInputFieldNames(context.okfVersion, kind) : []),
+            ])].filter(name => {
+            if (isManagedDocumentMetadataField(name) || name === "tags" || name === "sources")
+                return false;
+            if (context.okfVersion === "0.1" && (name === "stale_after" || name === "usage_window"))
+                return false;
+            const storage = kind && resolveKindFieldCoordinate(context.okfVersion, kind, name);
+            if (action === "unset")
+                return name !== "type" && !(kind && kind.fields.required.includes(storage?.storageField ?? name));
+            return !containsCollection(existing.frontmatter[storage?.storageField ?? name]);
+        }).sort();
+        throw new FieldActionError(`Unsupported ${action} field '${field}'; supported fields: ${supportedFields.join(", ")}.`, {
+            reason: "unsupported-set-field", field, supportedFields,
+        });
+    }
+    return { kind, storageField: coordinate?.storageField ?? field };
+}
+const timestampFor = (context) => (context.now ?? (() => new Date().toISOString()))();
 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")
+    if (action.action === "set" || action.action === "unset")
         assertAssignmentName(action.field);
     const keys = action.action === "edit" ? ["action", "field", "selector", "patch"]
         : action.action === "remove" && action.field === "sources" ? ["action", "field", "selector"]
-            : ["action", "field", "value"];
+            : action.action === "unset" ? ["action", "field"]
+                : ["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.");
+        throw new InvalidInputError("A field action value must be supplied; remove a field with unset.");
     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;
+        const admitted = admittedField(existing, action.field, context, "set");
+        storageField = admitted.storageField;
+        if (admitted.kind)
+            assertTypedListPatch(admitted.kind, storageField);
         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()))();
+            candidate.frontmatter.timestamp = timestampFor(context);
+        return { candidate, scope, storageField };
+    }
+    const prototypeName = () => { throw new InvalidInputError("'__proto__' is not a writable frontmatter field."); };
+    if (action.action === "unset") {
+        if (action.field === "__proto__")
+            prototypeName();
+        if (action.field === "type")
+            throw new InvalidInputError("'type' cannot be removed; a document keeps its type.");
+        const admitted = admittedField(existing, action.field, context, "unset");
+        storageField = admitted.storageField;
+        const fields = candidate.frontmatter;
+        if (has(fields, storageField)) {
+            delete fields[storageField];
+            scope.outcome = "removed";
+        }
+        const kind = admitted.kind;
+        if (kind && kind.fields.required.includes(storageField)) {
+            // The Kind's own finding for the candidate, so every consumer reads the code it already maps.
+            const missing = validateAgainstKind({ id: existing.id, ...candidate }, kind).filter(warning => warning.code === "KIND_FIELD_MISSING" && warning.field === storageField);
+            throw new KindConformanceError(existing.id, kind.governs, missing, context.okfVersion);
+        }
+        if (scope.outcome !== "unchanged" && context.okfVersion === "0.1")
+            candidate.frontmatter.timestamp = timestampFor(context);
+        return { candidate, scope, storageField };
+    }
+    if (action.action === "replace-all" && action.field !== "tags" && action.field !== "sources") {
+        if (action.field === "__proto__")
+            prototypeName();
+        const kind = context.registry.kinds.get(String(existing.frontmatter.type)) ?? undefined;
+        const coordinate = kind && resolveKindFieldCoordinate(context.okfVersion, kind, action.field);
+        if (isManagedDocumentMetadataField(action.field) || isStandardDocumentSetField(action.field, context.okfVersion) || !coordinate || !isKindListField(kind, coordinate.storageField)) {
+            throw new InvalidInputError(`replace-all supports tags, sources, and fields the document's Kind declares as string-list or https-url-list; '${action.field}' is none of these.`);
+        }
+        storageField = coordinate.storageField;
+        if (!Array.isArray(action.value))
+            throw new InvalidInputError("replace-all requires a complete list (including [] to empty it).");
+        if (action.value.some(member => typeof member !== "string"))
+            throw new InvalidInputError(`'${action.field}' must be a list of strings.`);
+        const rows = structuredClone(action.value);
+        if (!okfValuesEqual(existing.frontmatter[storageField], rows)) {
+            candidate.frontmatter[storageField] = rows;
+            scope.outcome = "replaced";
+            if (context.okfVersion === "0.1")
+                candidate.frontmatter.timestamp = timestampFor(context);
+        }
         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("add, remove and edit support only tags and sources; replace a Kind-declared list field whole with replace-all.");
+    if (!["add", "remove", "edit", "replace-all", "upsert"].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.");
@@ -173,8 +236,8 @@ export function prepareDocumentFieldAction(existing, action, context) {
             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 (["edit", "upsert"].includes(action.action))
+                throw new InvalidInputError(`tags supports add/remove/replace-all, not ${action.action}.`);
             if (typeof action.value !== "string")
                 throw new InvalidInputError("A tag must be a string.");
             if (action.action === "add" && !rows.includes(action.value)) {
@@ -186,6 +249,46 @@ export function prepareDocumentFieldAction(existing, action, context) {
                 scope.outcome = "removed";
             }
         }
+        else if (action.action === "upsert") {
+            sourceRow(action.value);
+            const value = action.value;
+            if (typeof value.id !== "string" || value.id.trim() === "")
+                throw new InvalidInputError("A source upsert requires a nonempty id.");
+            for (const [property, entry] of Object.entries(value)) {
+                if (entry === undefined)
+                    throw new InvalidInputError("Source upsert properties must have values.");
+                if (containsCollection(entry))
+                    throw new InvalidInputError(`Cannot assign source property '${property}': the new subtree contains a list. Use sources replace-all with an observed version.`);
+            }
+            const identity = { resource: value.resource, id: value.id };
+            const matches = rows.flatMap((row, index) => matchesSourceIdentity(row, identity) ? [index] : []);
+            if (matches.length > 1)
+                throw new FieldActionError(`Source identity is ambiguous (${matches.length} matches); repair duplicates with version-guarded replace-all.`, {
+                    reason: "ambiguous-source", field: "sources", selector: { id: value.id }, ...sourceCandidates(matches.map(index => rows[index])),
+                });
+            scope.affectedSourceIds = [value.id];
+            if (matches.length === 1) {
+                const old = rows[matches[0]];
+                for (const property of Object.keys(value)) {
+                    if (containsCollection(old[property]))
+                        throw new InvalidInputError(`Cannot assign source property '${property}': the old subtree contains a list. Use sources replace-all with an observed version.`);
+                }
+                const next = { ...old, ...structuredClone(value) };
+                if (!okfValuesEqual(old, next)) {
+                    rows[matches[0]] = next;
+                    scope.outcome = "edited";
+                }
+            }
+            else {
+                const sameId = rows.filter(row => record(row) && row.id === value.id);
+                if (sameId.length > 0)
+                    throw new FieldActionError(`Source ID '${value.id}' already names an entry under another resource; a document-local ID is never minted twice.`, {
+                        reason: "source-id-conflict", field: "sources", selector: { id: value.id }, recommendedSelector: { id: value.id }, ...sourceCandidates(sameId),
+                    });
+                rows.push(structuredClone(value));
+                scope.outcome = "added";
+            }
+        }
         else if (action.action === "add") {
             sourceRow(action.value);
             if (has(action.value, "id")) {
@@ -255,7 +358,7 @@ export function prepareDocumentFieldAction(existing, action, context) {
         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()))();
+        candidate.frontmatter.timestamp = timestampFor(context);
     return { candidate, scope, storageField };
 }
 //# sourceMappingURL=document-field-actions.js.map