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

package/dist/qualified-links.js

@@ -0,0 +1,117 @@
+/**
+ * Qualified (cross-bundle) links: `[text](okf://<alias>/<path>.md[#fragment])`.
+ *
+ * `alias` is declared in the linking bundle's `docs/dependencies`; `path` is a concept id plus
+ * `.md`, relative to the TARGET bundle's root and used literally (never resolved against the
+ * linking file). The display text is the link's type, as for local typed links.
+ *
+ * The local link resolver ({@link parseLinksFromDoc}) treats `okf://` as external and ignores it,
+ * so local edges, backlinks and the renderer are unchanged; this module is the one parser for the
+ * qualified form. Pure and browser-safe.
+ */
+import { isBundleAlias } from "./dependencies.js";
+import { InvalidInputError } from "./errors.js";
+import { extractMarkdownLinks } from "./links.js";
+import { assertSafeConceptId, isReservedFile } from "./paths.js";
+export const QUALIFIED_HREF_PREFIX = "okf://";
+/**
+ * True when the href uses the `okf:` scheme in any letter case. A true answer means "this is a
+ * cross-bundle link"; {@link parseQualifiedHref} then says whether it is well formed (a malformed
+ * one is reported as `invalid_ref`, never silently ignored).
+ */
+export function isQualifiedHref(href) {
+    return /^okf:/i.test(href.trim());
+}
+/**
+ * Parse an `okf://` href. Refused (`ok: false`, read as `invalid_ref`): another scheme or a
+ * non-lower-case `okf://`, an alias outside `^[a-z][a-z0-9-]{0,62}$`, a leading `/` in the path,
+ * an empty, `.`, `..` or dot-prefixed segment, a query, a `%`, a non-`.md` target, `index.md` or
+ * `log.md` in any letter case, and any id the storage seam would refuse. The fragment is returned but plays no part in resolution.
+ */
+export function parseQualifiedHref(href) {
+    const raw = href.trim();
+    if (!raw.startsWith(QUALIFIED_HREF_PREFIX)) {
+        return { ok: false, detail: "a cross-bundle link must start with okf://" };
+    }
+    const hash = raw.indexOf("#");
+    const target = hash >= 0 ? raw.slice(QUALIFIED_HREF_PREFIX.length, hash) : raw.slice(QUALIFIED_HREF_PREFIX.length);
+    const fragment = hash >= 0 ? raw.slice(hash + 1) : undefined;
+    if (target.includes("?"))
+        return { ok: false, detail: "a query is not allowed" };
+    if (target.includes("%"))
+        return { ok: false, detail: "percent-encoding is not allowed" };
+    const slash = target.indexOf("/");
+    if (slash < 0)
+        return { ok: false, detail: "expected okf://<alias>/<path>.md" };
+    const alias = target.slice(0, slash);
+    const path = target.slice(slash + 1);
+    if (!isBundleAlias(alias))
+        return { ok: false, detail: "alias must match ^[a-z][a-z0-9-]{0,62}$" };
+    if (path.startsWith("/"))
+        return { ok: false, detail: "the path is relative to the target bundle's root and must not start with /" };
+    if (path.split("/").some((segment) => segment.startsWith("."))) {
+        return { ok: false, detail: "'.', '..' and dot-prefixed segments are not allowed" };
+    }
+    if (!path.endsWith(".md"))
+        return { ok: false, detail: "the target must be a .md document" };
+    // Case-insensitive: `INDEX.md` names the reserved file on a case-insensitive filesystem.
+    if (isReservedFile(path.toLowerCase()))
+        return { ok: false, detail: "index.md and log.md are not documents" };
+    const id = path.slice(0, -".md".length);
+    try {
+        assertSafeConceptId(id);
+    }
+    catch (error) {
+        if (error instanceof InvalidInputError)
+            return { ok: false, detail: error.message };
+        throw error;
+    }
+    return fragment === undefined ? { ok: true, ref: { alias, id } } : { ok: true, ref: { alias, id }, fragment };
+}
+/** Emit `okf://<alias>/<id>.md[#fragment]`. Throws {@link InvalidInputError} for a ref that would not parse back. */
+export function qualifiedHref(ref, fragment) {
+    const href = `${QUALIFIED_HREF_PREFIX}${ref.alias}/${ref.id}.md${fragment === undefined ? "" : `#${fragment}`}`;
+    const parsed = parseQualifiedHref(href);
+    if (!parsed.ok || parsed.ref.alias !== ref.alias || parsed.ref.id !== ref.id || parsed.fragment !== fragment) {
+        throw new InvalidInputError(`Not a valid cross-bundle target: ${parsed.ok ? "it does not parse back to the same alias and id" : parsed.detail}.`);
+    }
+    return href;
+}
+/**
+ * Every `okf:` link in a document body, in document order, malformed ones included. A link inside
+ * an inline code span or a fenced or indented code block is example text, not a link.
+ */
+export function parseQualifiedLinks(doc) {
+    const out = [];
+    for (const raw of extractMarkdownLinks(doc.body, { skipCode: true })) {
+        if (!isQualifiedHref(raw.href))
+            continue;
+        const parsed = parseQualifiedHref(raw.href);
+        out.push(parsed.ok
+            ? { from: doc.id, text: raw.text, href: raw.href, ref: parsed.ref }
+            : { from: doc.id, text: raw.text, href: raw.href, ref: null, detail: parsed.detail });
+    }
+    return out;
+}
+/** A well-formed qualified link as an edge: `to` is the id in the target bundle, `bundle` its alias. */
+export function qualifiedLinkEdge(link) {
+    if (link.ref === null)
+        return null;
+    return { from: link.from, to: link.ref.id, text: link.text, href: link.href, bundle: link.ref.alias };
+}
+/**
+ * Read a Kind link target (`links: {pours: "beers:Beer"}`). The target is qualified when the text
+ * before the first `:` matches the alias grammar; anything else (`Beer`, `Some: Thing`) is a local
+ * Kind name and returns null, as does a qualified target with no Kind (`beers:`).
+ */
+export function parseQualifiedKindTarget(target) {
+    const colon = target.indexOf(":");
+    if (colon < 0)
+        return null;
+    const alias = target.slice(0, colon);
+    if (!isBundleAlias(alias))
+        return null;
+    const kind = target.slice(colon + 1).trim();
+    return kind === "" ? null : { alias, kind };
+}
+//# sourceMappingURL=qualified-links.js.map

package/dist/qualified-links.js.map

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

package/dist/query-filter.d.ts

@@ -1,7 +1,8 @@
 /** Browser-safe, storage-free query predicate shared by every head-projection consumer. */
-import type { ConceptId, Frontmatter, QueryFilter } from "./types.js";
+import type { ConceptId, Frontmatter, QueryFilter, SourceIdentity } from "./types.js";
 /**
- * THE canonical {@link QueryFilter} predicate — every facet (`prefix`, `type`, `tags`, `fields`),
+ * THE canonical {@link QueryFilter} predicate — every facet (`prefix`, `type`, `tags`, `fields`,
+ * `sources`),
  * ANDed. Kept in a storage-free module so both Node consumers and the browser View bridge can use
  * the same scalar/array/string-coercion semantics without importing the filesystem-backed engine.
  */
@@ -9,4 +10,17 @@ export declare function matchesFilter(doc: {
     id: ConceptId;
     frontmatter: Frontmatter;
 }, filter: QueryFilter): boolean;
+/**
+ * The identity one `sources[]` entry carries: its own string `resource` and `id`, each omitted when
+ * absent, inherited or not a string. Undefined when the entry is not a mapping. The one reading of
+ * an entry's identity, shared by {@link matchesSourceIdentity} and identity indexes.
+ */
+export declare function sourceIdentityOf(entry: unknown): {
+    resource?: string;
+    id?: string;
+} | undefined;
+/** THE `sources[]` identity predicate for one entry; see {@link SourceIdentity} for the rule. */
+export declare function matchesSourceIdentity(entry: unknown, identity: SourceIdentity): boolean;
+/** True when a frontmatter `sources` value is a list holding an entry with this identity. */
+export declare function hasSourceIdentity(sources: unknown, identity: SourceIdentity): boolean;
 //# sourceMappingURL=query-filter.d.ts.map

package/dist/query-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-filter.d.ts","sourceRoot":"","sources":["../src/query-filter.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,EAChD,MAAM,EAAE,WAAW,GAClB,OAAO,CAmBT"}
+{"version":3,"file":"query-filter.d.ts","sourceRoot":"","sources":["../src/query-filter.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,EAChD,MAAM,EAAE,WAAW,GAClB,OAAO,CAsBT;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAQ/F;AAED,iGAAiG;AACjG,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CASvF;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAErF"}

package/dist/query-filter.js

@@ -1,5 +1,6 @@
 /**
- * THE canonical {@link QueryFilter} predicate — every facet (`prefix`, `type`, `tags`, `fields`),
+ * THE canonical {@link QueryFilter} predicate — every facet (`prefix`, `type`, `tags`, `fields`,
+ * `sources`),
  * ANDed. Kept in a storage-free module so both Node consumers and the browser View bridge can use
  * the same scalar/array/string-coercion semantics without importing the filesystem-backed engine.
  */
@@ -24,6 +25,44 @@ export function matchesFilter(doc, filter) {
                 return false;
         }
     }
+    if (filter.sources && (filter.sources.resource !== undefined || filter.sources.id !== undefined)) {
+        if (!hasSourceIdentity(doc.frontmatter.sources, filter.sources))
+            return false;
+    }
+    return true;
+}
+/**
+ * The identity one `sources[]` entry carries: its own string `resource` and `id`, each omitted when
+ * absent, inherited or not a string. Undefined when the entry is not a mapping. The one reading of
+ * an entry's identity, shared by {@link matchesSourceIdentity} and identity indexes.
+ */
+export function sourceIdentityOf(entry) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+        return undefined;
+    const row = entry;
+    const identity = {};
+    for (const key of ["resource", "id"]) {
+        if (Object.hasOwn(row, key) && typeof row[key] === "string")
+            identity[key] = row[key];
+    }
+    return identity;
+}
+/** THE `sources[]` identity predicate for one entry; see {@link SourceIdentity} for the rule. */
+export function matchesSourceIdentity(entry, identity) {
+    const own = sourceIdentityOf(entry);
+    if (!own)
+        return false;
+    for (const key of ["resource", "id"]) {
+        const expected = identity[key];
+        if (expected === undefined)
+            continue;
+        if (own[key] === undefined || own[key] !== expected)
+            return false;
+    }
     return true;
 }
+/** True when a frontmatter `sources` value is a list holding an entry with this identity. */
+export function hasSourceIdentity(sources, identity) {
+    return Array.isArray(sources) && sources.some((entry) => matchesSourceIdentity(entry, identity));
+}
 //# sourceMappingURL=query-filter.js.map

package/dist/query-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-filter.js","sourceRoot":"","sources":["../src/query-filter.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAgD,EAChD,MAAmB;IAEnB,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,IAAI,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACpE,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,WAAW,GAAG,GAAG,CAAC,WAAsC,CAAC;QAC/D,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5D,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,MAAM,GACV,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;gBAC/B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACvE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,OAAO,KAAK,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"query-filter.js","sourceRoot":"","sources":["../src/query-filter.ts"],"names":[],"mappings":"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"}

package/dist/query-order.d.ts

@@ -0,0 +1,22 @@
+export interface MeaningfulChangeOrderKey {
+    id: string;
+    /** The raw selected clock when it is a string, else `""`. */
+    timestamp: string;
+    /** The clock parsed under the bundle's OKF edition, or `null` when missing or invalid. */
+    timestampMs: number | null;
+}
+export declare function meaningfulChangeOrderKey(id: string, frontmatter: {
+    readonly generated?: unknown;
+    readonly timestamp?: unknown;
+}, okfVersion?: string | null): MeaningfulChangeOrderKey;
+/** Newest usable meaningful-change time first; canonical ID in code-unit order for all ties. */
+export declare function compareByMeaningfulChange(a: MeaningfulChangeOrderKey, b: MeaningfulChangeOrderKey): number;
+/** Return a new array of `rows` in newest-first order; the input array is left untouched. */
+export declare function sortByMeaningfulChange<T extends {
+    id: string;
+    frontmatter: {
+        readonly generated?: unknown;
+        readonly timestamp?: unknown;
+    };
+}>(rows: readonly T[], okfVersion?: string | null): T[];
+//# sourceMappingURL=query-order.d.ts.map

package/dist/query-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-order.d.ts","sourceRoot":"","sources":["../src/query-order.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,MAAM,EACV,WAAW,EAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,EAC3E,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,wBAAwB,CAO1B;AAED,gGAAgG;AAChG,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,wBAAwB,EAAE,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAS1G;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,EAC1I,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,CAAC,EAAE,CAKL"}

package/dist/query-order.js

@@ -0,0 +1,42 @@
+/**
+ * Newest-first order shared by `list`, `home` and the View Bridge `order: "newest"` query.
+ *
+ * Rows sort by their parsed meaningful-change time (`generated.at`, else legacy `timestamp`),
+ * newest first. Rows with a missing or unparseable time follow every timed row. Every tie,
+ * including the untimed tail, breaks on the canonical ID in UTF-16 code-unit order, which every
+ * host computes identically; `localeCompare` depends on the platform's ICU data.
+ *
+ * Browser-safe and pure.
+ */
+import { parseTimestamp } from "./freshness.js";
+import { meaningfulChangeTimeValue } from "./meaningful-change-time.js";
+export function meaningfulChangeOrderKey(id, frontmatter, okfVersion) {
+    const value = meaningfulChangeTimeValue(frontmatter);
+    return {
+        id,
+        timestamp: typeof value === "string" ? value : "",
+        timestampMs: parseTimestamp(value, okfVersion ?? undefined),
+    };
+}
+/** Newest usable meaningful-change time first; canonical ID in code-unit order for all ties. */
+export function compareByMeaningfulChange(a, b) {
+    if (a.timestampMs !== null && b.timestampMs !== null) {
+        if (a.timestampMs !== b.timestampMs)
+            return b.timestampMs - a.timestampMs;
+    }
+    else if (a.timestampMs !== null) {
+        return -1;
+    }
+    else if (b.timestampMs !== null) {
+        return 1;
+    }
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** Return a new array of `rows` in newest-first order; the input array is left untouched. */
+export function sortByMeaningfulChange(rows, okfVersion) {
+    return rows
+        .map((row) => ({ row, key: meaningfulChangeOrderKey(row.id, row.frontmatter, okfVersion) }))
+        .sort((a, b) => compareByMeaningfulChange(a.key, b.key))
+        .map(({ row }) => row);
+}
+//# sourceMappingURL=query-order.js.map

package/dist/query-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-order.js","sourceRoot":"","sources":["../src/query-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAUxE,MAAM,UAAU,wBAAwB,CACtC,EAAU,EACV,WAA2E,EAC3E,UAA0B;IAE1B,MAAM,KAAK,GAAG,yBAAyB,CAAC,WAAW,CAAC,CAAC;IACrD,OAAO;QACL,EAAE;QACF,SAAS,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QACjD,WAAW,EAAE,cAAc,CAAC,KAAK,EAAE,UAAU,IAAI,SAAS,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,yBAAyB,CAAC,CAA2B,EAAE,CAA2B;IAChG,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;YAAE,OAAO,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;IAC5E,CAAC;SAAM,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;SAAM,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,sBAAsB,CACpC,IAAkB,EAClB,UAA0B;IAE1B,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,wBAAwB,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;SAC3F,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/dist/recipe-lifecycle/errors.d.ts

@@ -0,0 +1,96 @@
+import type { ConnectorErrorCode } from "../connectors.js";
+import type { ConceptId, Version } from "../types.js";
+import type { RecipeEvolutionBlocker } from "./evolution.js";
+/**
+ * One recipe target the evolution apply has handled, in plan order: `changed` when its content was
+ * updated, `stamped` when this apply wrote it (a content update or a stamp alone).
+ */
+export interface RecipeEvolutionCompletedDefinition {
+    /** Present only for Reference targets; existing definition receipts retain their shape. */
+    asset_kind?: "reference";
+    id: ConceptId;
+    changed: boolean;
+    stamped: boolean;
+    version: Version;
+}
+/** The common base: every recipe lifecycle failure is one of the subclasses below. */
+export declare class RecipeLifecycleError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The recipe itself cannot target this bundle: an unsupported edition or a contradictory field declaration. */
+export declare class RecipeInputError extends RecipeLifecycleError {
+    constructor(message: string);
+}
+/** A recipe asset (View entry, View registry or Reference) differs from what the bundle already holds there. */
+export declare class RecipeAssetConflict extends RecipeLifecycleError {
+    readonly recipe: string;
+    readonly key: string;
+    constructor(recipe: string, key: string);
+}
+/**
+ * A Connector the recipe carries maps onto a Kind this bundle (with the recipe's own conventions)
+ * does not declare, or onto fields that Kind does not allow. Install checks every connector before
+ * its first write, so nothing has been written.
+ */
+export declare class ConnectorTargetUnsatisfied extends RecipeLifecycleError {
+    readonly recipe: string;
+    readonly connector: ConceptId;
+    /** The source whose target Kind refused it. */
+    readonly source: string;
+    readonly kind: string;
+    readonly code: ConnectorErrorCode;
+    /** The mapped fields the Kind refused; empty when the Kind itself is not declared. */
+    readonly fields: readonly string[];
+    constructor(recipe: string, connector: ConceptId, source: string, kind: string, code: ConnectorErrorCode, fields: readonly string[], detail: string);
+}
+/** The bundle's OKF edition changed between the lifecycle's read of it and a write. */
+export declare class RecipeEditionChanged extends RecipeLifecycleError {
+    readonly from: string;
+    readonly to: string;
+    readonly operation: "installation" | "evolution";
+    constructor(from: string, to: string, operation: "installation" | "evolution");
+}
+/** The plan token the caller observed no longer matches the bundle's current plan. */
+export declare class RecipeEvolutionPlanChanged extends RecipeLifecycleError {
+    readonly expected: string;
+    readonly current: string;
+    constructor(expected: string, current: string);
+}
+/** The observed plan is not ready: it carries blockers, so nothing was written. */
+export declare class RecipeEvolutionBlocked extends RecipeLifecycleError {
+    readonly recipe: string;
+    readonly blockers: readonly RecipeEvolutionBlocker[];
+    constructor(recipe: string, blockers: readonly RecipeEvolutionBlocker[]);
+}
+/**
+ * Why a write loop stopped part way. `race`: a target's exact-version CAS failed or the target
+ * disappeared. `write_policy`: the write policy rejected a candidate after preflight.
+ * `edition_changed`: the bundle edition moved during the loop. `other`: any other failure, kept
+ * as `cause` for the presenting boundary to classify.
+ */
+export type RecipeEvolutionInterruptionReason = "race" | "write_policy" | "edition_changed" | "other";
+/** The evolution apply stopped after writing `completed`; `pending` names the targets still unwritten. */
+export declare class RecipeEvolutionInterrupted extends RecipeLifecycleError {
+    readonly reason: RecipeEvolutionInterruptionReason;
+    readonly completed: RecipeEvolutionCompletedDefinition[];
+    readonly pending: ConceptId[];
+    constructor(reason: RecipeEvolutionInterruptionReason, message: string, completed: RecipeEvolutionCompletedDefinition[], pending: ConceptId[], cause: unknown);
+}
+/**
+ * Every write succeeded, but the re-plan after the loop could not run (`unverifiable`) or no longer
+ * reads ready and unchanged (`changed`), because the bundle has no cross-document transaction.
+ */
+export declare class RecipeEvolutionPostcondition extends RecipeLifecycleError {
+    readonly reason: "unverifiable" | "changed";
+    readonly completed: RecipeEvolutionCompletedDefinition[];
+    readonly blockers?: readonly RecipeEvolutionBlocker[];
+    readonly postcondition_plan?: string;
+    constructor(reason: "unverifiable" | "changed", message: string, completed: RecipeEvolutionCompletedDefinition[], details?: {
+        blockers?: readonly RecipeEvolutionBlocker[];
+        postcondition_plan?: string;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/recipe-lifecycle/errors.d.ts.map

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

package/dist/recipe-lifecycle/errors.js

@@ -0,0 +1,122 @@
+/** The common base: every recipe lifecycle failure is one of the subclasses below. */
+export class RecipeLifecycleError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RecipeLifecycleError";
+    }
+}
+/** The recipe itself cannot target this bundle: an unsupported edition or a contradictory field declaration. */
+export class RecipeInputError extends RecipeLifecycleError {
+    constructor(message) {
+        super(message);
+        this.name = "RecipeInputError";
+    }
+}
+/** A recipe asset (View entry, View registry or Reference) differs from what the bundle already holds there. */
+export class RecipeAssetConflict extends RecipeLifecycleError {
+    recipe;
+    key;
+    constructor(recipe, key) {
+        super(`recipe '${recipe}' cannot install '${key}' because a different target already exists; ` +
+            "the existing bundle content was left untouched");
+        this.name = "RecipeAssetConflict";
+        this.recipe = recipe;
+        this.key = key;
+    }
+}
+/**
+ * A Connector the recipe carries maps onto a Kind this bundle (with the recipe's own conventions)
+ * does not declare, or onto fields that Kind does not allow. Install checks every connector before
+ * its first write, so nothing has been written.
+ */
+export class ConnectorTargetUnsatisfied extends RecipeLifecycleError {
+    recipe;
+    connector;
+    /** The source whose target Kind refused it. */
+    source;
+    kind;
+    code;
+    /** The mapped fields the Kind refused; empty when the Kind itself is not declared. */
+    fields;
+    constructor(recipe, connector, source, kind, code, fields, detail) {
+        super(`recipe '${recipe}' cannot install Connector '${connector}': source '${source}' maps onto ${kind}, and ${detail}; ` +
+            "nothing was written");
+        this.name = "ConnectorTargetUnsatisfied";
+        this.recipe = recipe;
+        this.connector = connector;
+        this.source = source;
+        this.kind = kind;
+        this.code = code;
+        this.fields = fields;
+    }
+}
+/** The bundle's OKF edition changed between the lifecycle's read of it and a write. */
+export class RecipeEditionChanged extends RecipeLifecycleError {
+    from;
+    to;
+    operation;
+    constructor(from, to, operation) {
+        super(`bundle OKF version changed from '${from}' to '${to}' during recipe ${operation}` +
+            (operation === "installation" ? "; retry" : ""));
+        this.name = "RecipeEditionChanged";
+        this.from = from;
+        this.to = to;
+        this.operation = operation;
+    }
+}
+/** The plan token the caller observed no longer matches the bundle's current plan. */
+export class RecipeEvolutionPlanChanged extends RecipeLifecycleError {
+    expected;
+    current;
+    constructor(expected, current) {
+        super(`recipe evolution plan changed (expected ${expected}, current ${current}); inspect a fresh plan before applying`);
+        this.name = "RecipeEvolutionPlanChanged";
+        this.expected = expected;
+        this.current = current;
+    }
+}
+/** The observed plan is not ready: it carries blockers, so nothing was written. */
+export class RecipeEvolutionBlocked extends RecipeLifecycleError {
+    recipe;
+    blockers;
+    constructor(recipe, blockers) {
+        super(`recipe '${recipe}' cannot evolve automatically (${blockers.length} blocker${blockers.length === 1 ? "" : "s"})`);
+        this.name = "RecipeEvolutionBlocked";
+        this.recipe = recipe;
+        this.blockers = blockers;
+    }
+}
+/** The evolution apply stopped after writing `completed`; `pending` names the targets still unwritten. */
+export class RecipeEvolutionInterrupted extends RecipeLifecycleError {
+    reason;
+    completed;
+    pending;
+    constructor(reason, message, completed, pending, cause) {
+        super(message, { cause });
+        this.name = "RecipeEvolutionInterrupted";
+        this.reason = reason;
+        this.completed = completed;
+        this.pending = pending;
+    }
+}
+/**
+ * Every write succeeded, but the re-plan after the loop could not run (`unverifiable`) or no longer
+ * reads ready and unchanged (`changed`), because the bundle has no cross-document transaction.
+ */
+export class RecipeEvolutionPostcondition extends RecipeLifecycleError {
+    reason;
+    completed;
+    blockers;
+    postcondition_plan;
+    constructor(reason, message, completed, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.name = "RecipeEvolutionPostcondition";
+        this.reason = reason;
+        this.completed = completed;
+        if (details.blockers !== undefined)
+            this.blockers = details.blockers;
+        if (details.postcondition_plan !== undefined)
+            this.postcondition_plan = details.postcondition_plan;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/recipe-lifecycle/errors.js.map

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

package/dist/recipe-lifecycle/evolution.d.ts

@@ -0,0 +1,108 @@
+import type { LoadedRecipe } from "../recipes.js";
+import type { Bundle, ConceptId, Version } from "../types.js";
+import { type RecipeEvolutionCompletedDefinition } from "./errors.js";
+import { type RecipeStampState } from "./stamp.js";
+export interface RecipeEvolutionDefinition {
+    id: ConceptId;
+    /**
+     * The Kind a convention governs; `Connector` on a Connector row, a value no recipe convention
+     * may govern.
+     */
+    governs: string;
+    /** Content only: whether the definition's declarations change (a Connector's, as a whole). */
+    action: "missing" | "unchanged" | "update";
+    /** The installed definition's recipe stamp relative to this recipe. */
+    stamp: RecipeStampState;
+    expected_version: Version | null;
+    desired_version: Version;
+    /** Exact additive semantic paths this automatic plan will introduce. */
+    added_paths: string[];
+    /** Proven recipe-owned field guidance replacements, with the exact observed and proposed text. */
+    description_replacements?: Array<{
+        path: string;
+        old: string;
+        new: string;
+    }>;
+}
+/** A Reference decision is separate from convention/Connector definition counts. */
+export interface RecipeEvolutionReference {
+    id: ConceptId;
+    action: "missing" | "unchanged" | "update";
+    stamp: RecipeStampState;
+    expected_version: Version | null;
+    desired_version: Version;
+}
+export interface RecipeEvolutionReferenceAssets {
+    rows: RecipeEvolutionReference[];
+    counts: {
+        updates: number;
+        stamp_writes: number;
+        unchanged: number;
+        missing: number;
+    };
+}
+export interface RecipeEvolutionBlocker {
+    code: string;
+    id: string;
+    message: string;
+    field?: string;
+}
+/** Public representation of one read-only, state-bound preflight decision. */
+export interface RecipeEvolutionPlan {
+    recipe: "evolution plan";
+    id: string;
+    version: string;
+    source: string;
+    okf_version: string;
+    ready: boolean;
+    /** Content only: whether any definition or Reference changes. */
+    changed: boolean;
+    /** Total definition and Reference writes, including stamp-only adoption. */
+    writes: number;
+    plan_token: string;
+    definitions: RecipeEvolutionDefinition[];
+    /** Present only for recipes declaring References. Top-level writes/changed cover both sets. */
+    reference_assets?: RecipeEvolutionReferenceAssets;
+    counts: {
+        definitions: number;
+        updates: number;
+        /** Writes that only record the stamp: write-set members whose action is not `update`. */
+        stamp_writes: number;
+        unchanged: number;
+        missing: number;
+        instances_checked: number;
+        blockers: number;
+    };
+    blockers: RecipeEvolutionBlocker[];
+}
+export interface RecipeEvolutionApplyResult {
+    /** `evolved`: a content update was written; `stamped`: only stamps were; `already current`: nothing. */
+    recipe: "evolved" | "stamped" | "already current";
+    id: string;
+    version: string;
+    source: string;
+    /** True whenever anything was written. */
+    changed: boolean;
+    plan_token: string;
+    definitions: RecipeEvolutionCompletedDefinition[];
+    reference_assets?: {
+        rows: RecipeEvolutionCompletedDefinition[];
+        counts: {
+            updated: number;
+            stamped: number;
+            unchanged: number;
+        };
+    };
+    counts: {
+        updated: number;
+        stamped: number;
+        unchanged: number;
+    };
+}
+/** Build a read-only, state-bound preflight for recipe definitions and Reference ownership. */
+export declare function planRecipeEvolution(bundle: Bundle, recipe: LoadedRecipe): Promise<RecipeEvolutionPlan>;
+/** Apply only the exact ready plan the caller previously observed. */
+export declare function applyRecipeEvolution(bundle: Bundle, recipe: LoadedRecipe, expectedPlanToken: string, options?: {
+    actor?: string;
+}): Promise<RecipeEvolutionApplyResult>;
+//# sourceMappingURL=evolution.d.ts.map