superbee 0.4.3-pre.16 → 0.4.3-pre.18

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target3) => (target3 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.3-pre.16" }, source: { commit: "67f0444c4d35441a06059328700c2b7ad71c6841", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.3-pre.18" }, source: { commit: "331fdf6fcc4695f3968960497e070af50865347f", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -19299,6 +19299,24 @@ function declarationFree(doc2) {
 function isConnectorDoc(doc2) {
   return doc2.frontmatter.type === CONNECTOR_TYPE && doc2.id.startsWith(CONNECTORS_PREFIX);
 }
+function recipeOrphanedDefinitions(docs, recipe2) {
+  const declared = /* @__PURE__ */ new Map([
+    ["Convention", new Set(recipe2.docs.map((doc2) => doc2.id))],
+    ["Connector", new Set((recipe2.connectors ?? []).map((connector) => connector.doc.id))],
+    ["Reference", new Set(recipe2.references.map((reference) => reference.doc.id))]
+  ]);
+  const orphans = [];
+  for (const doc2 of docs) {
+    let definitionType;
+    if (doc2.frontmatter.type === CONVENTION_TYPE && doc2.id.startsWith(CONVENTIONS_PREFIX)) definitionType = "Convention";
+    else if (isConnectorDoc(doc2)) definitionType = "Connector";
+    else if (doc2.frontmatter.type === "Reference" && doc2.id.startsWith("references/")) definitionType = "Reference";
+    else continue;
+    if (readRecipeStamp(doc2)?.id !== recipe2.id) continue;
+    if (!declared.get(definitionType).has(doc2.id)) orphans.push({ id: doc2.id, type: definitionType });
+  }
+  return orphans.sort((a, b) => byCodeUnit(a.id, b.id) || byCodeUnit(a.type, b.type));
+}
 function installedRecipes(docs, known = []) {
   const present = /* @__PURE__ */ new Map();
   const stampedByRecipe = /* @__PURE__ */ new Map();
@@ -19377,6 +19395,10 @@ function installedRecipes(docs, known = []) {
       if (missing2 > 0) row5.missing = missing2;
       if (recipe2 && missingIds.length > 0) row5.missing_ids = missingIds;
     }
+    if (recipe2) {
+      const orphaned = recipeOrphanedDefinitions(all2.map(({ doc: doc2 }) => doc2), recipe2).map(({ id: id2 }) => id2);
+      if (orphaned.length > 0) row5.orphaned_ids = orphaned;
+    }
     if (diverged.length > 0) row5.diverged = diverged;
     if (unknownRules.length > 0) row5.unknown_rules = unknownRules;
     return row5;
@@ -21242,6 +21264,7 @@ async function installRecipe(bundle, recipe2, options = {}) {
   const prepared = prepareRecipeInstall(recipe2, { okfVersion, now });
   recipe2 = { ...recipe2, docs: prepared.docs, connectors: prepared.connectors, pages: prepared.pages, references: prepared.references };
   assertConnectorsWritable(recipe2, okfVersion);
+  assertReferencesWritable(recipe2, okfVersion);
   await assertConnectorTargets(bundle, recipe2, okfVersion);
   await assertPortableTargetsCompatible(bundle, recipe2, okfVersion);
   const legacyConventionId = recipe2.docs.some((d2) => governsKind(d2, VIEW_KIND_NAME)) ? await findLegacyViewConvention(bundle) : null;
@@ -21449,6 +21472,17 @@ function assertConnectorsWritable(recipe2, okfVersion) {
     }
   }
 }
+function assertReferencesWritable(recipe2, okfVersion) {
+  if (okfVersion !== "0.2") return;
+  for (const { doc: doc2 } of recipe2.references) {
+    try {
+      assertAuthoredOkfStandardFields(doc2.frontmatter, void 0, { phase: "input" });
+    } catch (error51) {
+      if (!(error51 instanceof InvalidInputError)) throw error51;
+      throw new RecipeInputError(`recipe '${recipe2.id}' cannot install Reference '${doc2.id}': ${error51.message}; nothing was written`);
+    }
+  }
+}
 async function assertConnectorTargets(bundle, recipe2, okfVersion) {
   const connectors = recipe2.connectors ?? [];
   if (connectors.length === 0) return;
@@ -21977,6 +22011,11 @@ async function prepareRecipeEvolution(bundle, sourceRecipe) {
       `cannot prove the prospective registry while convention '${skipped.id}' is unreadable: ${skipped.reason}`
     );
   }
+  const orphaned = recipeOrphanedDefinitions([
+    ...installedConventions,
+    ...await query2(bundle, { prefix: CONNECTORS_PREFIX, type: CONNECTOR_TYPE }),
+    ...await query2(bundle, { prefix: "references/", type: "Reference" })
+  ], recipe2);
   const prospectiveById = new Map(installedConventions.map((doc2) => [doc2.id, doc2]));
   const currentRegistry = buildKindRegistry(installedConventions, [], { okfVersion });
   for (const authored2 of recipe2.docs) {
@@ -22393,6 +22432,7 @@ async function prepareRecipeEvolution(bundle, sourceRecipe) {
       writes: writes.size,
       plan_token: token,
       definitions,
+      ...orphaned.length > 0 ? { orphaned_definitions: orphaned } : {},
       ...references.length > 0 ? { reference_assets: {
         rows: references,
         counts: {
@@ -22537,6 +22577,7 @@ async function applyRecipeEvolution(bundle, recipe2, expectedPlanToken, options
     changed: written > 0,
     plan_token: plan.plan_token,
     definitions: completed.filter((row5) => row5.asset_kind !== "reference"),
+    ...postcondition.plan.orphaned_definitions ? { orphaned_definitions: postcondition.plan.orphaned_definitions } : {},
     ...plan.reference_assets ? { reference_assets: {
       rows: completed.filter((row5) => row5.asset_kind === "reference"),
       counts: {
@@ -29005,7 +29046,7 @@ var init_source_profiles = __esm({
         };
       }
     });
-    SOURCE_PLUGIN_CORE_VERSION = "0.2.0-pre.26";
+    SOURCE_PLUGIN_CORE_VERSION = "0.2.0-pre.28";
     SOURCE_PROFILES = Object.freeze([restJsonProfile].map((profile) => Object.freeze({ id: profile.id, version: profile.version, kind: profile.kind })));
   }
 });
@@ -32117,7 +32158,7 @@ function decodeBlobWriteResult(raw, expected) {
     if (error51.scope !== "principal" && error51.scope !== "bundle" || error51.resetAt !== void 0 && (typeof error51.resetAt !== "string" || !Number.isFinite(Date.parse(error51.resetAt)))) throw refuse();
   } else if (error51.scope !== void 0 || error51.resetAt !== void 0) throw refuse();
   if (error51.code === "deletions_held") {
-    if (operationId !== "blobs.delete.v1" || !count2(error51.deletions) || !count2(error51.baseline)) throw refuse();
+    if (operationId !== "blobs.delete.v1" || !count2(error51.deletions) || !Number.isSafeInteger(error51.baseline) || error51.baseline < 0) throw refuse();
   } else if (error51.deletions !== void 0 || error51.baseline !== void 0) throw refuse();
   return { ok: false, operationId, error: { ...error51 } };
 }
@@ -34284,7 +34325,7 @@ var init_write2 = __esm({
 // ../core/src/blob-journal.ts
 function captureBlobDeletionHold(value) {
   const hold = captureJournalValue(value);
-  if (!object4(hold) || !only3(hold, ["deletions", "baseline"]) || ![hold.deletions, hold.baseline].every((n) => Number.isSafeInteger(n) && n >= 1)) throw new TypeError("invalid blob deletion hold");
+  if (!object4(hold) || !only3(hold, ["deletions", "baseline"]) || !Number.isSafeInteger(hold.deletions) || hold.deletions < 1 || !Number.isSafeInteger(hold.baseline) || hold.baseline < 0) throw new TypeError("invalid blob deletion hold");
   return hold;
 }
 function captureBlobNotDispatched(value) {
@@ -103573,7 +103614,7 @@ Options:
   -h, --help            Show this help
 `;
     UNSTAMPED_CAP = 20;
-    STAMP_HELP = "partial: the recipe's conventions record different versions or fewer than it declares; a fresh 'recipe evolve <source>' plan (or 'recipe add' for an interrupted install) converges them, except a Kind declined with 'kind dismiss', which is deliberate, and a declared convention another recipe's stamp owns, which stays with that recipe; diverged: a convention changed since its recipe wrote it; an added declaration blocks the next evolve until the recipe adopts it or it is removed by hand, a removed optional one is put back, and a removed required field, section, terminal value or inbound expectation blocks until restored by hand; unknown: no stamp, or stamp rules this version does not read";
+    STAMP_HELP = "partial: the recipe's conventions record different versions or fewer than it declares; a fresh 'recipe evolve <source>' plan (or 'recipe add' for an interrupted install) can reconcile declared targets, except a Kind declined with 'kind dismiss', which is deliberate, and a declared convention another recipe's stamp owns, which stays with that recipe; retained definitions the selected recipe no longer declares are reported as orphaned_ids when its source is known and are never changed or removed by evolve; diverged: a convention changed since its recipe wrote it; an added declaration blocks the next evolve until the recipe adopts it or it is removed by hand, a removed optional one is put back, and a removed required field, section, terminal value or inbound expectation blocks until restored by hand; unknown: no stamp, or stamp rules this version does not read";
     CONNECTOR_STAMP_HELP = "a Connector a person changed reads diverged and blocks that recipe's evolve until the change is undone or the Connector is removed and added again; connectors counts the Connectors carrying the stamp, connectors_of how many the recipe declares";
   }
 });
@@ -103931,7 +103972,7 @@ async function recipeEvolve(argv2, stdout) {
     } catch (error51) {
       throw classifyBundleError(error51);
     }
-    stdout(render({ ...result3, help: [planCommand, `${cliInvocation()} kinds`] }, resolveMode(values)));
+    stdout(render({ ...result3, ...result3.orphaned_definitions ? { orphaned_help: ORPHANED_HELP } : {}, help: [planCommand, `${cliInvocation()} kinds`] }, resolveMode(values)));
     return;
   }
   let plan;
@@ -103952,6 +103993,7 @@ async function recipeEvolve(argv2, stdout) {
   } else if (plan.blockers.some((blocker) => blocker.code === "RECIPE_EVOLUTION_DEFINITION_MISSING" || blocker.code === "RECIPE_EVOLUTION_ASSET_MISSING")) {
     receipt4.commands = { install_missing: `${cliInvocation()} recipe add ${commandQuoted(ref)}${target3}` };
   }
+  if (plan.orphaned_definitions) receipt4.orphaned_help = ORPHANED_HELP;
   receipt4.help = [planCommand, `${cliInvocation()} kinds`];
   stdout(render(receipt4, resolveMode(values)));
 }
@@ -104031,7 +104073,7 @@ async function recipeAdd(argv2, stdout) {
   receipt4.help = [`${cliInvocation()} recipes`, `${cliInvocation()} kinds`];
   stdout(render(receipt4, resolveMode(values)));
 }
-var RECIPE_USAGE;
+var RECIPE_USAGE, ORPHANED_HELP;
 var init_recipe = __esm({
   "../cli/src/commands/recipe.ts"() {
     "use strict";
@@ -104084,8 +104126,9 @@ it compares definitions, permits additive declarations only, revalidates existin
 returns one exact apply command. Applying requires that plan's token, recomputes the preflight, and
 writes each changed convention with exact-version CAS. Concurrent non-target changes are detected
 by a postcondition check and reported with completed work. It never replaces existing values,
-active View assets, or artifacts omitted from the source. It may add a field type (fields.types) or
-an enum (fields.values) to a declared field only when every existing instance conforms; otherwise
+active View assets, or artifacts omitted from the source. Retained stamped definitions omitted from
+the selected source are reported as orphaned_definitions; a zero-write plan does not remove them.
+It may add a field type (fields.types) or an enum (fields.values) to a declared field only when every existing instance conforms; otherwise
 the plan names the violating documents. It never changes or removes a type or an enum. New outbound
 link types revalidate existing edges; new expects_inbound labels add status graph lint only and do
 not require existing records to have those edges. Inbound additions require an unchanged recipe
@@ -104112,6 +104155,7 @@ Options:
   --json                Emit compact JSON instead of TOON
   -h, --help            Show this help
 `;
+    ORPHANED_HELP = "orphaned_definitions are retained documents stamped by this recipe that the selected source no longer declares; evolve never changes or removes them, and a zero-write plan does not resolve them; inspect them before deciding whether to keep or remove them";
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.3-pre.16",
+  "version": "0.4.3-pre.18",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [