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

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

@@ -0,0 +1,136 @@
+import type { LoadedRecipe } from "../recipes.js";
+import type { ConceptId, OkfDocument } from "../types.js";
+/** The frontmatter key that carries a convention's recipe stamp. */
+export declare const RECIPE_STAMP_KEY = "x_recipe";
+/** The version of the digest rules this release writes and reads. */
+export declare const DEFINITION_DIGEST_RULES = 1;
+/** One convention's (or Connector's) record of the recipe that last wrote it. */
+export interface RecipeStamp {
+    id: string;
+    version: string;
+    /** How many conventions the recipe declares. */
+    of: number;
+    /**
+     * How many Connectors the recipe declares; written only by a recipe that carries connectors, so
+     * a reader that predates the key ignores it and every other stamp keeps its bytes.
+     */
+    connectors?: number;
+    /** {@link recipeSourceDigest} of the recipe that wrote the convention. */
+    source_digest: string;
+    /** {@link definitionDigest} of the convention as that recipe wrote it. */
+    definition: string;
+    /** The rules version that produced `definition`. */
+    digest_rules: number;
+}
+/**
+ * How an existing convention's stamp relates to a recipe: `current` (this recipe's id, version,
+ * declared count and source digest), `stale` (this recipe's id, anything else different),
+ * `foreign` (another recipe's id) or `missing` (no well-formed stamp, or no convention).
+ */
+export type RecipeStampState = "current" | "stale" | "foreign" | "missing";
+/** One stamped convention: unchanged since its recipe wrote it, changed, or unreadable rules. */
+export type ConventionStampState = "current" | "diverged" | "unknown";
+/** One recipe's state across the conventions that carry its stamp. */
+export type RecipeInstallState = "installed" | "partial" | "diverged" | "unknown";
+export interface InstalledRecipeRow {
+    id: string;
+    state: RecipeInstallState;
+    version: string | null;
+    source_digest: string | null;
+    /** How many conventions carry this recipe's stamp. */
+    conventions: number;
+    of: number | null;
+    convention_ids: ConceptId[];
+    /** Present for a recipe that carries connectors: how many Connectors carry its stamp. */
+    connectors?: number;
+    /** The declared Connector count the stamps record (the stamp's `connectors`). */
+    connectors_of?: number | null;
+    connector_ids?: ConceptId[];
+    records?: Array<{
+        version: string;
+        source_digest: string;
+        conventions: number;
+        connectors?: number;
+    }>;
+    missing?: number;
+    missing_ids?: ConceptId[];
+    diverged?: ConceptId[];
+    unknown_rules?: ConceptId[];
+}
+/** The recipe-level facts every stamp a recipe writes shares; `definition` is per document. */
+export interface RecipeStampIdentity {
+    id: string;
+    version: string;
+    of: number;
+    /** Present exactly when the recipe carries connectors. */
+    connectors?: number;
+    source_digest: string;
+}
+/**
+ * JSON with object keys sorted at every depth, `Date` values as ISO strings and `undefined`
+ * members omitted, so equal values hash equally whatever their key order or YAML spelling.
+ */
+declare function canonicalJson(value: unknown): string;
+/**
+ * The definitions-digest canon, for core's other definitions digest (the Connector pin). Named apart
+ * from `site-capabilities`' canonical JSON, whose semantics differ; the subpath entry does not
+ * re-export it.
+ */
+export { canonicalJson as definitionCanonicalJson };
+/**
+ * Digest of a recipe's parsed content, taken before edition materialization: its id, version,
+ * conventions, View pairs, References and (only when it carries any) Connectors, each sorted by id,
+ * bodies with CRLF read as LF. Equal across editions, independent of how the recipe was acquired,
+ * and blind to README files. A recipe without connectors digests exactly as it did before
+ * connectors existed, so every stamp written earlier stays current.
+ */
+export declare function recipeSourceDigest(recipe: LoadedRecipe): string;
+/**
+ * Digest of a convention as written, rules version 1: its frontmatter without the stripped keys
+ * and its body with CRLF read as LF and the storage newline applied. The digest of a candidate
+ * before the write equals the digest of the document read back from any backend.
+ */
+export declare function definitionDigest(doc: Pick<OkfDocument, "frontmatter" | "body">): string;
+/**
+ * The document's stamp, or null unless it is a mapping whose every required field has its type.
+ * The optional `connectors` count is kept when it is a non-negative integer and otherwise read as
+ * absent.
+ */
+export declare function readRecipeStamp(doc: Pick<OkfDocument, "frontmatter">): RecipeStamp | null;
+/** The recipe-level stamp facts for `recipe`; `materialized` supplies the declared count. */
+export declare function recipeStampIdentity(recipe: LoadedRecipe, materialized: LoadedRecipe): RecipeStampIdentity;
+/** `doc` with its stamp replaced by this recipe's, whose `definition` is the digest of `doc`. */
+export declare function withRecipeStamp<T extends Pick<OkfDocument, "frontmatter" | "body">>(doc: T, identity: RecipeStampIdentity): T;
+/**
+ * How the stamp on `doc` (null: no document) relates to the recipe `identity` describes. The
+ * Connector count must match too: for a recipe that carries connectors a stamp without it is
+ * `stale`, and since no release writes the key for a recipe without connectors, every stamp such a
+ * recipe wrote reads as it did before the key existed.
+ */
+export declare function recipeStampState(doc: Pick<OkfDocument, "frontmatter"> | null, identity: RecipeStampIdentity): RecipeStampState;
+/** The worst of `states` in the order current, stale, foreign, missing; `current` when empty. */
+export declare function worstRecipeStampState(states: Iterable<RecipeStampState>): RecipeStampState;
+/** One stamped document's state: rules this release reads, and whether its digest still matches. */
+export declare function conventionStampState(doc: Pick<OkfDocument, "frontmatter" | "body">): ConventionStampState;
+/**
+ * Each recipe's install state, derived from the stamps on `docs` (conventions, and Connector
+ * documents under `connectors/`; documents of any other type are ignored), and the documents no
+ * recipe stamped. `known` recipes (their declared ids are visible to the caller) also report a
+ * declared id that does not carry their stamp, and get a row when an unstamped convention that
+ * declares something, or an unstamped Connector, sits at one of their ids: a bundle written before
+ * stamps. A declined Kind (a declaration-free record) or another recipe's stamp at their ids alone
+ * is no evidence they were installed.
+ *
+ * States, the first match winning: `unknown` when no document carries the recipe's stamp;
+ * `partial` when the stamps record more than one version or source digest, disagree on a declared
+ * count, fall short of the convention or Connector count, or (known recipes) a declared id is
+ * present without this recipe's stamp; `diverged` when a stamped document changed since the recipe
+ * wrote it; `unknown` when a stamp uses digest rules this release does not read; otherwise
+ * `installed`. A row carries the Connector keys only for a recipe whose stamps record connectors,
+ * so every other row reads as it did before connectors existed.
+ */
+export declare function installedRecipes(docs: Iterable<OkfDocument>, known?: readonly LoadedRecipe[]): {
+    rows: InstalledRecipeRow[];
+    unstamped: ConceptId[];
+};
+//# sourceMappingURL=stamp.d.ts.map

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

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

package/dist/recipe-lifecycle/stamp.js

@@ -0,0 +1,326 @@
+// Recipe install stamps. Every convention, Connector and Reference a recipe installs or evolves carries one
+// `x_recipe` record, written in the same compare-and-swap write as the document, so the stamp
+// exists exactly when the document does. A stamp holds only deterministic facts: two clones that apply
+// the same evolve write identical stamps. The install-state read side derives convention/Connector state from their
+// stamps alone, without the recipe source; References have separate evolution rows. Storage-neutral: no Node globals or builtins.
+import { CONNECTOR_TYPE, CONNECTORS_PREFIX } from "../connectors.js";
+import { normalizeDocumentBodyForStorage } from "../frontmatter.js";
+import { CONVENTION_TYPE } from "../kinds.js";
+import { sha256Hex } from "../versioning.js";
+/** The frontmatter key that carries a convention's recipe stamp. */
+export const RECIPE_STAMP_KEY = "x_recipe";
+/** The version of the digest rules this release writes and reads. */
+export const DEFINITION_DIGEST_RULES = 1;
+/**
+ * Keys rules version 1 leaves out of a definition digest: the stamp itself, the clocks and
+ * attribution the write policy maintains, the hosted managed fields, and bundle-local `order`.
+ */
+const DIGEST_STRIPPED_KEYS = [
+    RECIPE_STAMP_KEY,
+    "timestamp",
+    "actor",
+    "generated",
+    "verified",
+    "superbee_updated_by",
+    "okf_version",
+    "order",
+];
+const STAMP_STATE_SEVERITY = ["current", "stale", "foreign", "missing"];
+function lf(text) {
+    return text.replaceAll("\r\n", "\n");
+}
+/** Code-unit order: the same on every platform and locale. */
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * JSON with object keys sorted at every depth, `Date` values as ISO strings and `undefined`
+ * members omitted, so equal values hash equally whatever their key order or YAML spelling.
+ */
+function canonicalJson(value) {
+    if (value instanceof Date)
+        return JSON.stringify(value.toISOString());
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort(byCodeUnit)
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(",")}}`;
+}
+/**
+ * The definitions-digest canon, for core's other definitions digest (the Connector pin). Named apart
+ * from `site-capabilities`' canonical JSON, whose semantics differ; the subpath entry does not
+ * re-export it.
+ */
+export { canonicalJson as definitionCanonicalJson };
+function digest(value) {
+    return `sha256:${sha256Hex(canonicalJson(value))}`;
+}
+/**
+ * Digest of a recipe's parsed content, taken before edition materialization: its id, version,
+ * conventions, View pairs, References and (only when it carries any) Connectors, each sorted by id,
+ * bodies with CRLF read as LF. Equal across editions, independent of how the recipe was acquired,
+ * and blind to README files. A recipe without connectors digests exactly as it did before
+ * connectors existed, so every stamp written earlier stays current.
+ */
+export function recipeSourceDigest(recipe) {
+    const docs = [...recipe.docs]
+        .sort((a, b) => byCodeUnit(a.id, b.id))
+        .map((doc) => [doc.id, doc.frontmatter, lf(doc.body)]);
+    const pages = [...recipe.pages]
+        .sort((a, b) => byCodeUnit(a.registry.id, b.registry.id))
+        .map((page) => [page.registry.id, page.registry.frontmatter, lf(page.registry.body), page.entry, lf(page.html)]);
+    const references = [...recipe.references]
+        .sort((a, b) => byCodeUnit(a.doc.id, b.doc.id))
+        .map((reference) => [reference.doc.id, reference.doc.frontmatter, lf(reference.doc.body)]);
+    const connectors = [...(recipe.connectors ?? [])]
+        .sort((a, b) => byCodeUnit(a.doc.id, b.doc.id))
+        .map((connector) => [connector.doc.id, connector.doc.frontmatter, lf(connector.doc.body)]);
+    return digest({
+        id: recipe.id,
+        version: recipe.version,
+        docs,
+        pages,
+        references,
+        ...(connectors.length > 0 ? { connectors } : {}),
+    });
+}
+/**
+ * Digest of a convention as written, rules version 1: its frontmatter without the stripped keys
+ * and its body with CRLF read as LF and the storage newline applied. The digest of a candidate
+ * before the write equals the digest of the document read back from any backend.
+ */
+export function definitionDigest(doc) {
+    const frontmatter = { ...doc.frontmatter };
+    for (const key of DIGEST_STRIPPED_KEYS)
+        delete frontmatter[key];
+    return digest({ frontmatter, body: normalizeDocumentBodyForStorage(lf(doc.body ?? "")) });
+}
+function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+/**
+ * The document's stamp, or null unless it is a mapping whose every required field has its type.
+ * The optional `connectors` count is kept when it is a non-negative integer and otherwise read as
+ * absent.
+ */
+export function readRecipeStamp(doc) {
+    const value = doc.frontmatter[RECIPE_STAMP_KEY];
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const stamp = value;
+    if (typeof stamp.id !== "string" || stamp.id === ""
+        || typeof stamp.version !== "string"
+        || !nonNegativeInteger(stamp.of)
+        || typeof stamp.source_digest !== "string"
+        || typeof stamp.definition !== "string"
+        || !nonNegativeInteger(stamp.digest_rules) || stamp.digest_rules === 0)
+        return null;
+    return {
+        id: stamp.id,
+        version: stamp.version,
+        of: stamp.of,
+        ...(nonNegativeInteger(stamp.connectors) ? { connectors: stamp.connectors } : {}),
+        source_digest: stamp.source_digest,
+        definition: stamp.definition,
+        digest_rules: stamp.digest_rules,
+    };
+}
+/** The recipe-level stamp facts for `recipe`; `materialized` supplies the declared count. */
+export function recipeStampIdentity(recipe, materialized) {
+    const connectors = (recipe.connectors ?? []).length;
+    return {
+        id: recipe.id,
+        version: recipe.version,
+        of: materialized.docs.length,
+        ...(connectors > 0 ? { connectors } : {}),
+        source_digest: recipeSourceDigest(recipe),
+    };
+}
+/** `doc` with its stamp replaced by this recipe's, whose `definition` is the digest of `doc`. */
+export function withRecipeStamp(doc, identity) {
+    const { [RECIPE_STAMP_KEY]: _previous, ...frontmatter } = doc.frontmatter;
+    const stamp = {
+        id: identity.id,
+        version: identity.version,
+        of: identity.of,
+        ...(identity.connectors !== undefined ? { connectors: identity.connectors } : {}),
+        source_digest: identity.source_digest,
+        definition: definitionDigest({ frontmatter: frontmatter, body: doc.body }),
+        digest_rules: DEFINITION_DIGEST_RULES,
+    };
+    return { ...doc, frontmatter: { ...frontmatter, [RECIPE_STAMP_KEY]: stamp } };
+}
+/**
+ * How the stamp on `doc` (null: no document) relates to the recipe `identity` describes. The
+ * Connector count must match too: for a recipe that carries connectors a stamp without it is
+ * `stale`, and since no release writes the key for a recipe without connectors, every stamp such a
+ * recipe wrote reads as it did before the key existed.
+ */
+export function recipeStampState(doc, identity) {
+    const stamp = doc === null ? null : readRecipeStamp(doc);
+    if (stamp === null)
+        return "missing";
+    if (stamp.id !== identity.id)
+        return "foreign";
+    return stamp.version === identity.version
+        && stamp.of === identity.of
+        && stamp.source_digest === identity.source_digest
+        && stamp.connectors === identity.connectors
+        ? "current"
+        : "stale";
+}
+/** The worst of `states` in the order current, stale, foreign, missing; `current` when empty. */
+export function worstRecipeStampState(states) {
+    let worst = 0;
+    for (const state of states)
+        worst = Math.max(worst, STAMP_STATE_SEVERITY.indexOf(state));
+    return STAMP_STATE_SEVERITY[worst];
+}
+/** One stamped document's state: rules this release reads, and whether its digest still matches. */
+export function conventionStampState(doc) {
+    const stamp = readRecipeStamp(doc);
+    if (stamp === null || stamp.digest_rules !== DEFINITION_DIGEST_RULES)
+        return "unknown";
+    return definitionDigest(doc) === stamp.definition ? "current" : "diverged";
+}
+/** A convention that declares nothing a recipe would own: what `kind dismiss` writes. */
+function declarationFree(doc) {
+    return !["fields", "sections", "links", "expects_inbound"].some((key) => Object.hasOwn(doc.frontmatter, key));
+}
+/** A Connector declaration: the type core's connector parser owns, at the one place it reads it. */
+function isConnectorDoc(doc) {
+    return doc.frontmatter.type === CONNECTOR_TYPE && doc.id.startsWith(CONNECTORS_PREFIX);
+}
+/**
+ * Each recipe's install state, derived from the stamps on `docs` (conventions, and Connector
+ * documents under `connectors/`; documents of any other type are ignored), and the documents no
+ * recipe stamped. `known` recipes (their declared ids are visible to the caller) also report a
+ * declared id that does not carry their stamp, and get a row when an unstamped convention that
+ * declares something, or an unstamped Connector, sits at one of their ids: a bundle written before
+ * stamps. A declined Kind (a declaration-free record) or another recipe's stamp at their ids alone
+ * is no evidence they were installed.
+ *
+ * States, the first match winning: `unknown` when no document carries the recipe's stamp;
+ * `partial` when the stamps record more than one version or source digest, disagree on a declared
+ * count, fall short of the convention or Connector count, or (known recipes) a declared id is
+ * present without this recipe's stamp; `diverged` when a stamped document changed since the recipe
+ * wrote it; `unknown` when a stamp uses digest rules this release does not read; otherwise
+ * `installed`. A row carries the Connector keys only for a recipe whose stamps record connectors,
+ * so every other row reads as it did before connectors existed.
+ */
+export function installedRecipes(docs, known = []) {
+    const present = new Map();
+    const stampedByRecipe = new Map();
+    const unstamped = [];
+    for (const doc of docs) {
+        const connector = isConnectorDoc(doc);
+        if (doc.frontmatter.type !== CONVENTION_TYPE && !connector)
+            continue;
+        present.set(doc.id, doc);
+        const stamp = readRecipeStamp(doc);
+        if (stamp === null) {
+            if (connector || !declarationFree(doc))
+                unstamped.push(doc.id);
+            continue;
+        }
+        const group = stampedByRecipe.get(stamp.id) ?? [];
+        group.push({ doc, stamp, connector });
+        stampedByRecipe.set(stamp.id, group);
+    }
+    const knownById = new Map(known.map((recipe) => [recipe.id, recipe]));
+    const declaredDocs = (recipe) => [...recipe.docs, ...(recipe.connectors ?? []).map((connector) => connector.doc)];
+    const ids = new Set(stampedByRecipe.keys());
+    const unstampedIds = new Set(unstamped);
+    for (const recipe of known) {
+        if (declaredDocs(recipe).some((declared) => unstampedIds.has(declared.id)))
+            ids.add(recipe.id);
+    }
+    const rows = [...ids].sort(byCodeUnit).map((id) => {
+        const all = (stampedByRecipe.get(id) ?? []).sort((a, b) => byCodeUnit(a.doc.id, b.doc.id));
+        const stamped = all.filter((entry) => !entry.connector);
+        const stampedConnectors = all.filter((entry) => entry.connector);
+        const recipe = knownById.get(id);
+        const conventionIds = stamped.map(({ doc }) => doc.id);
+        const stampedIds = new Set(all.map(({ doc }) => doc.id));
+        const records = new Map();
+        for (const { stamp, connector } of all) {
+            const key = `${stamp.version}\u0000${stamp.source_digest}`;
+            const record = records.get(key) ?? { version: stamp.version, source_digest: stamp.source_digest, conventions: 0 };
+            if (connector)
+                record.connectors = (record.connectors ?? 0) + 1;
+            else
+                record.conventions += 1;
+            records.set(key, record);
+        }
+        const recordRows = [...records.values()].sort((a, b) => byCodeUnit(a.version, b.version) || byCodeUnit(a.source_digest, b.source_digest));
+        const declaredCounts = new Set(all.map(({ stamp }) => stamp.of));
+        const of = declaredCounts.size === 1 ? [...declaredCounts][0] : recipe ? recipe.docs.length : null;
+        // A stamp without the key records no connectors; a disagreement among stamps is partial.
+        const connectorCounts = new Set(all.map(({ stamp }) => stamp.connectors));
+        const declaredConnectors = recipe && (recipe.connectors ?? []).length > 0 ? recipe.connectors.length : undefined;
+        const connectorsOf = connectorCounts.size === 1
+            ? [...connectorCounts][0]
+            : connectorCounts.size === 0 ? declaredConnectors : declaredConnectors ?? null;
+        const carriesConnectors = stampedConnectors.length > 0 || connectorsOf !== undefined;
+        const diverged = all.filter(({ doc }) => conventionStampState(doc) === "diverged").map(({ doc }) => doc.id);
+        const unknownRules = all.filter(({ stamp }) => stamp.digest_rules !== DEFINITION_DIGEST_RULES).map(({ doc }) => doc.id);
+        const declaredIds = recipe ? declaredDocs(recipe).map((doc) => doc.id).sort(byCodeUnit) : [];
+        const missingIds = declaredIds.filter((declared) => !stampedIds.has(declared));
+        const presentWithoutStamp = missingIds.filter((declared) => present.has(declared));
+        let state;
+        if (all.length === 0)
+            state = "unknown";
+        else if (recordRows.length > 1
+            || declaredCounts.size > 1
+            || connectorCounts.size > 1
+            || stamped.length !== of
+            || stampedConnectors.length !== (connectorsOf ?? 0)
+            || presentWithoutStamp.length > 0
+            || (recipe !== undefined && missingIds.length > 0))
+            state = "partial";
+        else if (diverged.length > 0)
+            state = "diverged";
+        else if (unknownRules.length > 0)
+            state = "unknown";
+        else
+            state = "installed";
+        const single = state === "installed" || state === "diverged" ? recordRows[0] : null;
+        const row = {
+            id,
+            state,
+            version: single?.version ?? null,
+            source_digest: single?.source_digest ?? null,
+            conventions: stamped.length,
+            of,
+            convention_ids: conventionIds,
+        };
+        if (carriesConnectors) {
+            row.connectors = stampedConnectors.length;
+            row.connectors_of = connectorsOf ?? null;
+            row.connector_ids = stampedConnectors.map(({ doc }) => doc.id);
+        }
+        if (state === "partial") {
+            row.records = recordRows;
+            const missing = recipe
+                ? missingIds.length
+                : (of === null ? 0 : Math.max(0, of - stamped.length))
+                    + (typeof connectorsOf === "number" ? Math.max(0, connectorsOf - stampedConnectors.length) : 0);
+            if (missing > 0)
+                row.missing = missing;
+            if (recipe && missingIds.length > 0)
+                row.missing_ids = missingIds;
+        }
+        if (diverged.length > 0)
+            row.diverged = diverged;
+        if (unknownRules.length > 0)
+            row.unknown_rules = unknownRules;
+        return row;
+    });
+    return { rows, unstamped: unstamped.sort(byCodeUnit) };
+}
+//# sourceMappingURL=stamp.js.map

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

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

package/dist/recipes.d.ts

@@ -1,3 +1,4 @@
+import { type Connector, type ConnectorErrorCode } from "./connectors.js";
 import type { OkfDocument } from "./types.js";
 import type { ValidationWarning } from "./validation.js";
 /** One recipe file: a path relative to the recipe root (posix), with its UTF-8 text. */
@@ -19,6 +20,13 @@ export interface RecipeReference {
     /** A `type: Reference` document installed under `references/`. */
     doc: OkfDocument;
 }
+/** One Connector declaration carried by a recipe package: a definition, never an instance. */
+export interface RecipeConnector {
+    /** The `type: Connector` document installed under `connectors/`. */
+    doc: OkfDocument;
+    /** The declaration as `parseConnectorDoc` read it. */
+    connector: Connector;
+}
 /** Parsed recipe definitions. Parsing does not install, authorize or execute these assets. */
 export interface LoadedRecipe {
     id: string;
@@ -35,6 +43,12 @@ export interface LoadedRecipe {
     pages: RecipePage[];
     /** Optional operating references installed with the definitions; never project instances. */
     references: RecipeReference[];
+    /**
+     * Connector declarations the manifest's `connectors:` list carries, installed and evolved as
+     * definitions. Absent when the manifest declares none, so a recipe without connectors parses to
+     * the same value it always did.
+     */
+    connectors?: RecipeConnector[];
     /** Present only for packages opting into the strict portable definitions-only contract. */
     contentPolicy?: "definitions-only";
     /** The `type` values this recipe's conventions govern (derived at parse, for the receipt). */
@@ -42,11 +56,25 @@ export interface LoadedRecipe {
     /** Non-fatal (skipped-malformed doc / reserved manifest key / etc). Never silently dropped. */
     warnings: ValidationWarning[];
 }
-export type RecipeErrorCode = "RECIPE_NOT_FOUND" | "RECIPE_MALFORMED" | "RECIPE_EMPTY" | "RECIPE_UNSAFE_PATH";
+/**
+ * The logical workflow-field token recipe convention bodies may carry; materialization replaces it
+ * with the target edition's storage field. Part of the recipe format, so every client reads it here.
+ */
+export declare const RECIPE_PROGRESS_STATUS_TOKEN = "{{superbee:progress_status}}";
+export type RecipeErrorCode = "RECIPE_NOT_FOUND" | "RECIPE_MALFORMED" | "RECIPE_EMPTY" | "RECIPE_UNSAFE_PATH" | "RECIPE_CONNECTOR_INVALID";
 export interface RecipeError {
     code: RecipeErrorCode;
     message: string;
+    /** `RECIPE_CONNECTOR_INVALID`: the first refusal of the connector named, and how many it had. */
+    connector?: {
+        id: string;
+        code: ConnectorErrorCode;
+        path: string;
+        count: number;
+    };
 }
+/** The connectors a recipe carries; empty when its manifest declares none. */
+export declare function recipeConnectors(recipe: Pick<LoadedRecipe, "connectors">): readonly RecipeConnector[];
 export type LoadResult = {
     ok: true;
     recipe: LoadedRecipe;

package/dist/recipes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAYzD,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,uHAAuH;IACvH,QAAQ,EAAE,WAAW,CAAC;IACtB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,GAAG,EAAE,WAAW,CAAC;CAClB;AAED,8FAA8F;AAC9F,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,sFAAsF;IACtF,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,6FAA6F;IAC7F,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,2FAA2F;IAC3F,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,8FAA8F;IAC9F,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+FAA+F;IAC/F,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAE9G,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AA6LhG;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACpC,UAAU,CAwSZ"}
+{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwD,KAAK,SAAS,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAIhI,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAYzD,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,uHAAuH;IACvH,QAAQ,EAAE,WAAW,CAAC;IACtB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,GAAG,EAAE,WAAW,CAAC;CAClB;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,GAAG,EAAE,WAAW,CAAC;IACjB,sDAAsD;IACtD,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,8FAA8F;AAC9F,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,sFAAsF;IACtF,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,6FAA6F;IAC7F,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B,2FAA2F;IAC3F,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,8FAA8F;IAC9F,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+FAA+F;IAC/F,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,kBAAkB,GAClB,cAAc,GACd,oBAAoB,GACpB,0BAA0B,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,SAAS,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,kBAAkB,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACnF;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,SAAS,eAAe,EAAE,CAErG;AAED,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAgRhG;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACpC,UAAU,CA2VZ"}