@superbee/core 0.2.0-pre.4 → 0.2.0-pre.40

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

@@ -0,0 +1,124 @@
+import type { LoadedRecipe } from "../recipes.js";
+import type { Bundle, ConceptId, OkfDocument, Version } from "../types.js";
+import { type RecipeEvolutionCompletedDefinition } from "./errors.js";
+import { type RecipeOrphanedDefinition, 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[];
+    /** Informational retained ownership only; never part of this plan's write set. */
+    orphaned_definitions?: RecipeOrphanedDefinition[];
+    /** 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[];
+    /** Freshly observed retained ownership after apply, with no writes to these documents. */
+    orphaned_definitions?: RecipeOrphanedDefinition[];
+    reference_assets?: {
+        rows: RecipeEvolutionCompletedDefinition[];
+        counts: {
+            updated: number;
+            stamped: number;
+            unchanged: number;
+        };
+    };
+    counts: {
+        updated: number;
+        stamped: number;
+        unchanged: number;
+    };
+}
+interface PreparedRecipeEvolution {
+    plan: RecipeEvolutionPlan;
+    /** The write set: each member's exact candidate, its new stamp included. */
+    writes: Map<ConceptId, OkfDocument>;
+}
+interface RetirementStage {
+    definition: string;
+    coordinates: readonly Pick<import("./retirement.js").RetirementDeclaration, "coordinate" | "name" | "value">[];
+}
+/** Internal actual-source stage preparation; no synthetic comparison identity is stamped. */
+export declare function prepareRecipeRetirementStage(bundle: Bundle, source: LoadedRecipe, definition: string, coordinates: RetirementStage["coordinates"]): Promise<PreparedRecipeEvolution>;
+/** 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>;
+export {};
+//# 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":"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"}