superbee 0.4.4-pre.13 → 0.4.4-pre.15

package/README.md

@@ -127,6 +127,51 @@ In a hosted checkout, `superbee view read <id>` prints a View page's version on
 `superbee view update <id> --expected-version <version>` replaces the page there (sync never sends
 `views/`). Uploading a page never approves its execution.
 
+## Copying documents between bundles
+
+`superbee doc import` copies chosen documents from another bundle with new ids and rewritten links.
+Declare the source first, then review the plan before applying it:
+
+```sh
+superbee deps add wave --bundle-id <source-bundle-id> --path ../wave
+superbee doc import --from wave --with wave=../wave --select type=Theme --prefix wave
+superbee doc import --from wave --with wave=../wave --select type=Theme --prefix wave --apply <plan-token>
+superbee doc import --from wave --with wave=../wave --refresh <record-id>
+```
+
+The first import command only prints the plan and its token. Applying writes new documents and one
+Promotion record, and never overwrites a document. `--resume <record-id>` finishes an interrupted
+run. `--refresh <record-id>` updates the copies from their sources with the same plan and apply
+steps; a copy edited since the import is a conflict until you name it with `--overwrite <id>` or
+`--skip <id>`. The target must be a local bundle or Git board. `superbee doc import --help` has the
+full reference.
+
+## When a document cannot be read
+
+Superbee bounds how much frontmatter it parses: 262,144 characters of YAML, 32 levels of nesting, and limits on
+YAML alias use. Ordinary documents are far below these limits. A write over a limit is refused with
+`USAGE` and nothing is stored. A document already in the bundle that is over a limit, or whose YAML
+is invalid, cannot be read:
+
+- `doc read` on it fails with `RUNTIME`. `details.frontmatter.code` is `FRONTMATTER_TOO_LARGE`,
+  `FRONTMATTER_TOO_DEEP`, `FRONTMATTER_ALIAS_LIMIT`, `FRONTMATTER_CYCLE` or
+  `FRONTMATTER_MALFORMED`, and `details.frontmatter.document` names the file.
+- To find every affected document, run `superbee status` (the `malformed` count and rows) or
+  `superbee list` (the `skipped` rows). `search`, `query`, `index generate`, `link list`,
+  `link show`, `view list` and `kinds --coverage` also skip it, say so, and keep working.
+- To fix it, edit the lines between the `---` markers in a text editor, or remove the document with
+  `superbee doc delete <id>`. `doc update` and `doc field` cannot change a document they cannot read.
+
+On a Git board, `sync` holds a changed file it cannot read: it exits 5, names the file, and commits
+and pushes nothing until you fix it. If a conflict kept a version that cannot be read, the receipt
+tells you to copy your saved export over the document.
+
+In a hosted checkout, a host document this client cannot store comes back as a `held` row named with
+its `FRONTMATTER_*` code, exit 5, and everything else proceeds. The next sync places it once it is
+repaired on the host. If the checkout's own local store holds a copy it cannot read, sync stops with
+`store_damaged` and sends and places nothing. Reads continue and `status` reports it. Copy out any
+unsent edits and make a fresh checkout, as the error's help describes.
+
 ## Upgrading from aslite
 
 If you installed the earlier `@holaxis/aslite` package or its marketplace plugin: install
@@ -139,6 +184,8 @@ run `npm uninstall -g @holaxis/aslite`. Existing `.agentstate-lite/` bundles and
 The [repository](https://github.com/Holaxis-ai/superbee) holds the source, the
 [CLI contract](https://github.com/Holaxis-ai/superbee/blob/main/packages/superbee/AXI-CONTRACT.md),
 and the [wire protocol](https://github.com/Holaxis-ai/superbee/blob/main/docs/WIRE-PROTOCOL.md).
+Site builders can read a publication's Site declaration through `superbee/publication/site-manifest`;
+see [Site declarations](https://github.com/Holaxis-ai/superbee/blob/main/packages/publication/SITE-MANIFEST.md).
 
 ## License
 

package/SKILL.md

@@ -74,7 +74,7 @@ files, and stop. Use `superbee <command> --help` for exact current syntax rather
 copied command manual. Use `--body-file` for multiline Markdown. `list` / `query` filter metadata, not body text; `doc update` / `doc field` patch metadata while preserving omitted fields and body. For body edits, read the complete body with `doc read <id> --body-out <temp-file>` outside the bundle, edit that temporary file, then `doc update <id> --body-file <temp-file> --expected-version <head_version> --actor <actor>` using the version from the read. Re-read and reconcile on a version conflict. Never feed a truncated preview or a full-document `--out` export to `--body-file`: body input is Markdown only; tooling owns YAML frontmatter. With MCP, use available tools and version preconditions; check tool schemas rather than inventing search or patch verbs.
 
 Focused shipped material is available under `$REFS/recipes/` for portable examples,
-`$REFS/views/` for View authoring and examples, and `$REFS/sample-bundle/` for OKF interop. Integration authoring and explicit local source bind/run use `$REFS/author-an-integration.md`; recorded `$REFS/integrations/` examples need no credentials.
+`$REFS/views/` for View authoring and examples, and `$REFS/sample-bundle/` for OKF interop. Integration authoring and explicit local source bind/run use `$REFS/author-an-integration.md`; recorded `$REFS/integrations/` examples need no credentials. `RUNTIME` with `details.frontmatter.code` means a document cannot be read: see "When a document cannot be read" in `$REFS/modeling-and-delivery.md`, which also covers `superbee doc import`.
 Read only what the accepted work requires.
 
 ## Make the value visible

package/dist/publication/bridge-host-kind.d.ts

@@ -0,0 +1,2 @@
+export type BridgeHostKind = "oss" | "portal" | "hosted";
+//# sourceMappingURL=bridge-host-kind.d.ts.map

package/dist/publication/bridge.d.ts

@@ -1,4 +1,4 @@
-import { type BridgeHostKind } from "@superbee/view-runtime/bridge";
+import { type BridgeHostKind } from "./bridge-host-kind.js";
 import { PUBLICATION_BRIDGE_V0, type PublicationBridgeAdmissionV1, type PublicationBridgeV1, type PublicationSnapshotHandleV1 } from "./types.js";
 export interface CreatePublicationBridgeOptionsV1 {
     protocol: typeof PUBLICATION_BRIDGE_V0;

package/dist/publication-bridge.mjs

@@ -59,8 +59,8 @@ var require_common = __commonJS({
       return target;
     }
     function repeat(string, count) {
-      var result = "", cycle;
-      for (cycle = 0; cycle < count; cycle += 1) {
+      var result = "", cycle2;
+      for (cycle2 = 0; cycle2 < count; cycle2 += 1) {
         result += string;
       }
       return result;
@@ -2881,6 +2881,14 @@ var InvalidInputError = class extends Error {
     this.name = "InvalidInputError";
   }
 };
+var FrontmatterRefusedError = class extends InvalidInputError {
+  code;
+  constructor(code, detail) {
+    super(`frontmatter cannot be stored: ${detail}`);
+    this.name = "FrontmatterRefusedError";
+    this.code = code;
+  }
+};
 var FilesystemIdentityAliasError = class extends InvalidInputError {
   rel;
   segment;
@@ -2905,12 +2913,21 @@ var ConcurrentReplacementError = class extends Error {
   }
 };
 
-// ../core/src/portable-frontmatter.ts
+// ../core/src/bounded-yaml.ts
 var import_js_yaml = __toESM(require_js_yaml2(), 1);
 
 // ../core/src/frontmatter-contract.ts
+var FrontmatterLimitError = class extends Error {
+  name = "FrontmatterLimitError";
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+};
 var MalformedDocumentError = class extends Error {
   name = "MalformedDocumentError";
+  code;
   context;
   detail;
   constructor(context, cause) {
@@ -2918,12 +2935,165 @@ var MalformedDocumentError = class extends Error {
     super(
       `malformed frontmatter${context ? ` in '${context}'` : ""}: ${detail} \u2014 fix the YAML or remove the file`
     );
+    this.code = cause instanceof FrontmatterLimitError ? cause.code : "FRONTMATTER_MALFORMED";
     if (context !== void 0) this.context = context;
     this.detail = detail;
     if (cause !== void 0) this.cause = cause;
   }
 };
 
+// ../core/src/bounded-yaml.ts
+var FRONTMATTER_LIMITS = Object.freeze({
+  sourceChars: 256 * 1024,
+  depth: 32,
+  aliases: 1e3,
+  expandedNodes: 1e5,
+  expandedChars: 1024 * 1024
+});
+var PARSE_NESTING_GUARD = FRONTMATTER_LIMITS.depth * 4;
+function tooDeep() {
+  return new FrontmatterLimitError("FRONTMATTER_TOO_DEEP", `YAML nesting is deeper than ${FRONTMATTER_LIMITS.depth} levels`);
+}
+function tooLarge() {
+  return new FrontmatterLimitError(
+    "FRONTMATTER_ALIAS_LIMIT",
+    `YAML aliases expand to more than ${FRONTMATTER_LIMITS.expandedNodes} nodes or ${FRONTMATTER_LIMITS.expandedChars} characters`
+  );
+}
+function cycle() {
+  return new FrontmatterLimitError("FRONTMATTER_CYCLE", "YAML aliases form a cycle");
+}
+function scalarExtent(value) {
+  const chars = typeof value === "string" ? value.length : ArrayBuffer.isView(value) ? value.byteLength : 0;
+  return { nodes: 1, chars, depth: 0 };
+}
+function isCollection(value) {
+  if (Array.isArray(value)) return true;
+  if (value === null || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+var ExtentMeter = class {
+  known = /* @__PURE__ */ new Map();
+  path = /* @__PURE__ */ new Set();
+  unfinished;
+  constructor(unfinished = /* @__PURE__ */ new Set()) {
+    this.unfinished = unfinished;
+  }
+  measure(value) {
+    if (!isCollection(value)) return scalarExtent(value);
+    const known = this.known.get(value);
+    if (known !== void 0) return known;
+    if (this.path.has(value) || this.unfinished.has(value)) throw cycle();
+    return this.walk(value);
+  }
+  walk(value) {
+    if (this.path.size >= FRONTMATTER_LIMITS.depth) throw tooDeep();
+    this.path.add(value);
+    const keyed = !Array.isArray(value);
+    const extent = { nodes: 1, chars: 0, depth: 1 };
+    for (const [key, child] of Object.entries(value)) {
+      const inner = this.measure(child);
+      extent.nodes += inner.nodes;
+      extent.chars += inner.chars + (keyed ? key.length : 0);
+      extent.depth = Math.max(extent.depth, inner.depth + 1);
+      if (extent.nodes > FRONTMATTER_LIMITS.expandedNodes || extent.chars > FRONTMATTER_LIMITS.expandedChars) throw tooLarge();
+      if (extent.depth > FRONTMATTER_LIMITS.depth) throw tooDeep();
+    }
+    this.path.delete(value);
+    this.known.set(value, extent);
+    return extent;
+  }
+};
+var AliasBudget = class {
+  unfinished = /* @__PURE__ */ new Set();
+  finished = /* @__PURE__ */ new Set();
+  meter = new ExtentMeter(this.unfinished);
+  aliases = 0;
+  nodes = 0;
+  chars = 0;
+  /** Wrap the parser's anchor table; the parser reads it only to resolve an alias. */
+  watch(state) {
+    state.anchorMap = new Proxy(state.anchorMap, {
+      get: (target, name, receiver) => {
+        const value = Reflect.get(target, name, receiver);
+        if (typeof name === "string") this.charge(name, value);
+        return value;
+      },
+      set: (target, name, value, receiver) => {
+        if (typeof name === "string") {
+          this.finished.delete(name);
+          if (isCollection(value)) this.unfinished.add(value);
+        }
+        return Reflect.set(target, name, value, receiver);
+      }
+    });
+  }
+  /** Called when an anchored node closes: its anchor now names a complete value. */
+  close(anchor, value) {
+    this.finished.add(anchor);
+    if (isCollection(value)) this.unfinished.delete(value);
+  }
+  charge(name, value) {
+    this.aliases += 1;
+    if (this.aliases > FRONTMATTER_LIMITS.aliases) {
+      throw new FrontmatterLimitError(
+        "FRONTMATTER_ALIAS_LIMIT",
+        `YAML aliases are used more than ${FRONTMATTER_LIMITS.aliases} times`
+      );
+    }
+    if (!this.finished.has(name) && isCollection(value)) throw cycle();
+    const extent = this.meter.measure(value);
+    this.nodes += extent.nodes;
+    this.chars += extent.chars;
+    if (this.nodes > FRONTMATTER_LIMITS.expandedNodes || this.chars > FRONTMATTER_LIMITS.expandedChars) throw tooLarge();
+  }
+};
+var MERGE_KEY_LIMIT_REASON = "merge keys exceeded maxTotalMergeKeys";
+function loadBoundedYaml(source, options = {}) {
+  if (source.length > FRONTMATTER_LIMITS.sourceChars) {
+    throw new FrontmatterLimitError(
+      "FRONTMATTER_TOO_LARGE",
+      `YAML source is longer than ${FRONTMATTER_LIMITS.sourceChars} characters`
+    );
+  }
+  const schema = options.schema === "json" ? import_js_yaml.default.JSON_SCHEMA : options.schema;
+  const budget = new AliasBudget();
+  let watched;
+  let nesting = 0;
+  let value;
+  try {
+    value = import_js_yaml.default.safeLoad(source, {
+      ...schema ? { schema } : {},
+      listener(event, rawState) {
+        const state = rawState;
+        if (state.anchorMap !== watched) {
+          budget.watch(state);
+          watched = state.anchorMap;
+        }
+        if (event === "open") {
+          nesting += 1;
+          if (nesting > PARSE_NESTING_GUARD) throw tooDeep();
+        } else {
+          nesting -= 1;
+          if (state.anchor !== null) budget.close(state.anchor, state.result);
+        }
+      }
+    });
+  } catch (error) {
+    const reason = error.reason;
+    if (typeof reason === "string" && reason.startsWith(MERGE_KEY_LIMIT_REASON)) {
+      throw new FrontmatterLimitError("FRONTMATTER_ALIAS_LIMIT", reason);
+    }
+    throw error;
+  }
+  new ExtentMeter().measure(value);
+  return value;
+}
+
+// ../core/src/frontmatter.ts
+var import_js_yaml2 = __toESM(require_js_yaml2(), 1);
+
 // ../core/src/frontmatter-splitter.ts
 function delimiterLineEnd(input, offset) {
   if (!input.startsWith("---", offset)) return null;
@@ -2953,12 +3123,106 @@ function splitLeadingFrontmatter(raw, context) {
   throw new MalformedDocumentError(context, new Error("unterminated YAML frontmatter delimiter"));
 }
 
+// ../core/src/frontmatter.ts
+var YAML_TIMESTAMP_TAG = "tag:yaml.org,2002:timestamp";
+function requireYamlTimestampType() {
+  const type = import_js_yaml2.default.DEFAULT_SAFE_SCHEMA.implicit.find(
+    (candidate) => candidate.tag === YAML_TIMESTAMP_TAG
+  );
+  if (!type) throw new Error("js-yaml safe schema is missing its timestamp type");
+  return type;
+}
+var yamlTimestampType = requireYamlTimestampType();
+var stringTimestampType = new import_js_yaml2.default.Type(YAML_TIMESTAMP_TAG, {
+  kind: "scalar",
+  resolve: (value) => yamlTimestampType.resolve(value),
+  construct: (value) => value
+});
+var losslessDateSchema = new import_js_yaml2.default.Schema({
+  include: [import_js_yaml2.default.DEFAULT_SAFE_SCHEMA],
+  implicit: [stringTimestampType]
+});
+var yamlEngine = {
+  parse(input) {
+    return loadBoundedYaml(input, { schema: losslessDateSchema }) ?? {};
+  }
+};
+function normalizeFrontmatter(data, options) {
+  const out = { ...data };
+  if (options.preserveTimestamp || options.okfVersion === "0.2") return out;
+  const value = out.timestamp;
+  if (value instanceof Date) {
+    out.timestamp = value.toISOString();
+  } else if (typeof value === "number" && Number.isFinite(value)) {
+    out.timestamp = new Date(value).toISOString();
+  } else if (typeof value === "string" && yamlTimestampType.resolve(value)) {
+    const parsed = yamlTimestampType.construct(value);
+    if (parsed instanceof Date) out.timestamp = parsed.toISOString();
+  }
+  return out;
+}
+function parseMarkdown(raw, context, options = {}) {
+  const split = splitLeadingFrontmatter(raw, context);
+  if (!("yamlSource" in split)) return { frontmatter: {}, body: split.body };
+  return { frontmatter: parseFrontmatter(split.yamlSource, context, options), body: split.body };
+}
+function parseFrontmatter(source, context, options = {}) {
+  let parsed;
+  try {
+    parsed = yamlEngine.parse(source);
+  } catch (err) {
+    throw new MalformedDocumentError(context, err);
+  }
+  return normalizeFrontmatter(parsed, options);
+}
+function isStackExhaustion(error) {
+  if (error instanceof RangeError) return /call stack/i.test(error.message);
+  return error?.name === "InternalError" && /recursion/i.test(error.message);
+}
+function stringifyFrontmatter(data) {
+  let dumped;
+  try {
+    dumped = import_js_yaml2.default.safeDump(data).trim();
+  } catch (error) {
+    if (isStackExhaustion(error)) throw new FrontmatterRefusedError("FRONTMATTER_TOO_DEEP", `YAML nesting is deeper than ${FRONTMATTER_LIMITS.depth} levels`);
+    throw error;
+  }
+  try {
+    yamlEngine.parse(`${dumped}
+`);
+  } catch (error) {
+    if (error instanceof FrontmatterLimitError) throw new FrontmatterRefusedError(error.code, error.message);
+    const detail = (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+    throw new FrontmatterRefusedError("FRONTMATTER_MALFORMED", detail);
+  }
+  return dumped;
+}
+function normalizeDocumentBodyForStorage(body) {
+  return body.endsWith("\n") ? body : `${body}
+`;
+}
+function stringifyWithData(data, body) {
+  return stringifyWithSerializedFrontmatter(stringifyFrontmatter(data), body);
+}
+function stringifyWithSerializedFrontmatter(dumped, body) {
+  const content = body ?? "";
+  const newline = (value) => value.endsWith("\n") ? value : `${value}
+`;
+  if (dumped === "{}") return normalizeDocumentBodyForStorage(content);
+  return `---
+${newline(dumped)}---
+${normalizeDocumentBodyForStorage(content)}`;
+}
+function stringifyDoc(frontmatter2, body) {
+  return stringifyWithData(frontmatter2, body);
+}
+
 // ../core/src/portable-frontmatter.ts
 function parseLeadingFrontmatter(raw, context) {
   const split = splitLeadingFrontmatter(raw, context);
   if (!("yamlSource" in split)) return {};
   try {
-    const parsed = import_js_yaml.default.safeLoad(split.yamlSource);
+    const parsed = loadBoundedYaml(split.yamlSource);
     if (parsed === void 0 || parsed === null) return {};
     if (typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new TypeError("YAML frontmatter must be a mapping");
@@ -2969,6 +3233,18 @@ function parseLeadingFrontmatter(raw, context) {
     throw new MalformedDocumentError(context, error);
   }
 }
+function assertStorableFrontmatter(raw) {
+  try {
+    parseLeadingFrontmatter(raw);
+    const split = splitLeadingFrontmatter(raw);
+    if ("yamlSource" in split) parseFrontmatter(split.yamlSource);
+  } catch (error) {
+    if (error instanceof MalformedDocumentError && error.code !== "FRONTMATTER_MALFORMED") {
+      throw new FrontmatterRefusedError(error.code, error.detail);
+    }
+    if (!(error instanceof MalformedDocumentError)) throw error;
+  }
+}
 
 // ../core/src/paths.ts
 var RESERVED_FILENAMES = ["index.md", "log.md"];
@@ -3321,82 +3597,6 @@ function inventoryDigest(inventory) {
   return `sha256:${sha256HexOfUtf8(JSON.stringify(inventory.map((row) => [row.id, row.version])))}`;
 }
 
-// ../core/src/frontmatter.ts
-var import_js_yaml2 = __toESM(require_js_yaml2(), 1);
-var YAML_TIMESTAMP_TAG = "tag:yaml.org,2002:timestamp";
-function requireYamlTimestampType() {
-  const type = import_js_yaml2.default.DEFAULT_SAFE_SCHEMA.implicit.find(
-    (candidate) => candidate.tag === YAML_TIMESTAMP_TAG
-  );
-  if (!type) throw new Error("js-yaml safe schema is missing its timestamp type");
-  return type;
-}
-var yamlTimestampType = requireYamlTimestampType();
-var stringTimestampType = new import_js_yaml2.default.Type(YAML_TIMESTAMP_TAG, {
-  kind: "scalar",
-  resolve: (value) => yamlTimestampType.resolve(value),
-  construct: (value) => value
-});
-var losslessDateSchema = new import_js_yaml2.default.Schema({
-  include: [import_js_yaml2.default.DEFAULT_SAFE_SCHEMA],
-  implicit: [stringTimestampType]
-});
-var yamlEngine = {
-  parse(input) {
-    return import_js_yaml2.default.safeLoad(input, { schema: losslessDateSchema }) ?? {};
-  }
-};
-function normalizeFrontmatter(data, options) {
-  const out = { ...data };
-  if (options.preserveTimestamp || options.okfVersion === "0.2") return out;
-  const value = out.timestamp;
-  if (value instanceof Date) {
-    out.timestamp = value.toISOString();
-  } else if (typeof value === "number" && Number.isFinite(value)) {
-    out.timestamp = new Date(value).toISOString();
-  } else if (typeof value === "string" && yamlTimestampType.resolve(value)) {
-    const parsed = yamlTimestampType.construct(value);
-    if (parsed instanceof Date) out.timestamp = parsed.toISOString();
-  }
-  return out;
-}
-function parseMarkdown(raw, context, options = {}) {
-  const split = splitLeadingFrontmatter(raw, context);
-  if (!("yamlSource" in split)) return { frontmatter: {}, body: split.body };
-  return { frontmatter: parseFrontmatter(split.yamlSource, context, options), body: split.body };
-}
-function parseFrontmatter(source, context, options = {}) {
-  let parsed;
-  try {
-    parsed = yamlEngine.parse(source);
-  } catch (err) {
-    throw new MalformedDocumentError(context, err);
-  }
-  return normalizeFrontmatter(parsed, options);
-}
-function stringifyFrontmatter(data) {
-  return import_js_yaml2.default.safeDump(data).trim();
-}
-function normalizeDocumentBodyForStorage(body) {
-  return body.endsWith("\n") ? body : `${body}
-`;
-}
-function stringifyWithData(data, body) {
-  return stringifyWithSerializedFrontmatter(stringifyFrontmatter(data), body);
-}
-function stringifyWithSerializedFrontmatter(dumped, body) {
-  const content = body ?? "";
-  const newline = (value) => value.endsWith("\n") ? value : `${value}
-`;
-  if (dumped === "{}") return normalizeDocumentBodyForStorage(content);
-  return `---
-${newline(dumped)}---
-${normalizeDocumentBodyForStorage(content)}`;
-}
-function stringifyDoc(frontmatter2, body) {
-  return stringifyWithData(frontmatter2, body);
-}
-
 // ../core/src/code-unit-order.ts
 function compareCodeUnits(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -3808,24 +4008,7 @@ function hasSourceIdentity(sources, identity) {
   return Array.isArray(sources) && sources.some((entry) => matchesSourceIdentity(entry, identity));
 }
 
-// ../core/src/engine.ts
-async function readBundleOkfVersion(backend) {
-  const index = await backend.readReserved("", "index.md");
-  if (!index) return void 0;
-  const value = parseLeadingFrontmatter(index.content, "index.md").okf_version;
-  return typeof value === "string" && value.trim() !== "" ? value : void 0;
-}
-function assertReadableConceptId(id) {
-  assertSafeConceptId(id);
-  const rel = pathFromConceptId(id);
-  if (isReservedFile(rel)) {
-    throw new InvalidInputError(`'${id}' is a reserved file (index.md / log.md), not a concept document.`);
-  }
-}
-async function readDocVersioned(backend, id) {
-  assertReadableConceptId(id);
-  return backend.read(id);
-}
+// ../core/src/document-scan.ts
 function isEnoent(err) {
   return typeof err === "object" && err !== null && err.code === "ENOENT";
 }
@@ -3856,6 +4039,25 @@ async function readManyExisting(backend, ids, onMalformed, onAliased) {
     return out;
   }
 }
+
+// ../core/src/engine.ts
+async function readBundleOkfVersion(backend) {
+  const index = await backend.readReserved("", "index.md");
+  if (!index) return void 0;
+  const value = parseLeadingFrontmatter(index.content, "index.md").okf_version;
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+function assertReadableConceptId(id) {
+  assertSafeConceptId(id);
+  const rel = pathFromConceptId(id);
+  if (isReservedFile(rel)) {
+    throw new InvalidInputError(`'${id}' is a reserved file (index.md / log.md), not a concept document.`);
+  }
+}
+async function readDocVersioned(backend, id) {
+  assertReadableConceptId(id);
+  return backend.read(id);
+}
 async function scanMatching(backend, filter, onSkip) {
   const ids = await backend.list(filter.prefix);
   const results = [];
@@ -3974,6 +4176,13 @@ function resolveContentType(key, override) {
   return inferContentTypeFromDocKey(key) ?? DEFAULT_BLOB_CONTENT_TYPE;
 }
 
+// ../core/src/reserved-write.ts
+function assertStorableReservedWrite(dir, name, content) {
+  assertSafeReservedDir(dir);
+  assertSafeReservedFilename(name);
+  if (name.endsWith(".md")) assertStorableFrontmatter(content);
+}
+
 // ../core/src/filesystem-identity.ts
 import { promises as fs2 } from "node:fs";
 import path2 from "node:path";
@@ -5328,8 +5537,7 @@ var FilesystemBackend = class _FilesystemBackend {
     return { content, version: versionOfBytes(content) };
   }
   async writeReserved(dir, name, content, options = {}) {
-    assertSafeReservedDir(dir);
-    assertSafeReservedFilename(name);
+    assertStorableReservedWrite(dir, name, content);
     const rel = reservedPath(dir, name);
     return this.#mutateExact(rel, async (target) => {
       if (options.expectedVersion !== void 0) {