@superbee/core 0.2.0-pre.15 → 0.2.0-pre.17

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":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,kCAAkC;IACjD,EAAE,EAAE,SAAS,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,sFAAsF;AACtF,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,gHAAgH;AAChH,qBAAa,gBAAiB,SAAQ,oBAAoB;gBAC5C,OAAO,EAAE,MAAM;CAI5B;AAED,gHAAgH;AAChH,qBAAa,mBAAoB,SAAQ,oBAAoB;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CASxC;AAED,uFAAuF;AACvF,qBAAa,oBAAqB,SAAQ,oBAAoB;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,WAAW,CAAC;gBAErC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,WAAW;CAU9E;AAED,sFAAsF;AACtF,qBAAa,0BAA2B,SAAQ,oBAAoB;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAQ9C;AAED,mFAAmF;AACnF,qBAAa,sBAAuB,SAAQ,oBAAoB;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;gBAEzC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,sBAAsB,EAAE;CAQxE;AAED;;;;;GAKG;AACH,MAAM,MAAM,iCAAiC,GAAG,MAAM,GAAG,cAAc,GAAG,iBAAiB,GAAG,OAAO,CAAC;AAEtG,0GAA0G;AAC1G,qBAAa,0BAA2B,SAAQ,oBAAoB;IAClE,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAC;IACnD,QAAQ,CAAC,SAAS,EAAE,kCAAkC,EAAE,CAAC;IACzD,QAAQ,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC;gBAG5B,MAAM,EAAE,iCAAiC,EACzC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,kCAAkC,EAAE,EAC/C,OAAO,EAAE,SAAS,EAAE,EACpB,KAAK,EAAE,OAAO;CAQjB;AAED;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,oBAAoB;IACpE,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,kCAAkC,EAAE,CAAC;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACtD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;gBAGnC,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,kCAAkC,EAAE,EAC/C,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAS/G"}

package/dist/recipe-lifecycle/errors.js

@@ -0,0 +1,96 @@
+/** 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;
+    }
+}
+/** 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,71 @@
+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;
+    governs: string;
+    /** Content only: whether the convention's declarations change. */
+    action: "missing" | "unchanged" | "update";
+    /** The installed convention'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[];
+}
+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 convention's declarations change. */
+    changed: boolean;
+    /** How many conventions the apply writes: every content update and every stale or missing stamp. */
+    writes: number;
+    plan_token: string;
+    definitions: RecipeEvolutionDefinition[];
+    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[];
+    counts: {
+        updated: number;
+        stamped: number;
+        unchanged: number;
+    };
+}
+/** Build a read-only, state-bound preflight for installed recipe convention evolution. */
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"evolution.d.ts","sourceRoot":"","sources":["../../src/recipe-lifecycle/evolution.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAe,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,EAML,KAAK,kCAAkC,EACxC,MAAM,aAAa,CAAC;AAMrB,OAAO,EAOL,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAUpB,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,SAAS,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3C,uEAAuE;IACvE,KAAK,EAAE,gBAAgB,CAAC;IACxB,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,OAAO,CAAC;IACzB,wEAAwE;IACxE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,gBAAgB,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,yBAAyB,EAAE,CAAC;IACzC,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,yFAAyF;QACzF,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IACzC,wGAAwG;IACxG,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,iBAAiB,CAAC;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,kCAAkC,EAAE,CAAC;IAClD,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAgwBD,0FAA0F;AAC1F,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAE9B;AAED,sEAAsE;AACtE,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EACpB,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAsHrC"}