superbee 0.4.4-pre.13 → 0.4.4-pre.14

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.4-pre.13" }, source: { commit: "18c0655ead4adfea98f94b9bcf5224cf1e88e2ce", 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.4-pre.14" }, source: { commit: "da215d8610a39974bc39a195ad87f769c4d87560", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -57,7 +57,7 @@ var init_define_SUPERBEE_UPDATE_POLICY = __esm({
 });
 
 // ../core/src/errors.ts
-var InvalidInputError, OkfActorError, FilesystemIdentityAliasError, ConcurrentReplacementError;
+var InvalidInputError, FrontmatterRefusedError, OkfActorError, FilesystemIdentityAliasError, ConcurrentReplacementError;
 var init_errors = __esm({
   "../core/src/errors.ts"() {
     "use strict";
@@ -69,6 +69,14 @@ var init_errors = __esm({
         this.name = "InvalidInputError";
       }
     };
+    FrontmatterRefusedError = class extends InvalidInputError {
+      code;
+      constructor(code3, detail2) {
+        super(`frontmatter cannot be stored: ${detail2}`);
+        this.name = "FrontmatterRefusedError";
+        this.code = code3;
+      }
+    };
     OkfActorError = class extends InvalidInputError {
       actor;
       constructor(actor, message) {
@@ -132,8 +140,8 @@ var require_common = __commonJS({
       return target3;
     }
     function repeat2(string8, count6) {
-      var result3 = "", cycle;
-      for (cycle = 0; cycle < count6; cycle += 1) {
+      var result3 = "", cycle2;
+      for (cycle2 = 0; cycle2 < count6; cycle2 += 1) {
         result3 += string8;
       }
       return result3;
@@ -2994,23 +3002,41 @@ var require_js_yaml2 = __commonJS({
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
-    var yaml4 = require_js_yaml();
-    module.exports = yaml4;
+    var yaml3 = require_js_yaml();
+    module.exports = yaml3;
   }
 });
 
 // ../core/src/frontmatter-contract.ts
+function isFrontmatterLimitCode(value) {
+  return typeof value === "string" && FRONTMATTER_LIMIT_CODES.has(value);
+}
 function isUsableTimestamp(value) {
   return typeof value === "string" && value.trim() !== "";
 }
-var MalformedDocumentError;
+var FRONTMATTER_LIMIT_CODES, FrontmatterLimitError, MalformedDocumentError;
 var init_frontmatter_contract = __esm({
   "../core/src/frontmatter-contract.ts"() {
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
+    FRONTMATTER_LIMIT_CODES = /* @__PURE__ */ new Set([
+      "FRONTMATTER_TOO_LARGE",
+      "FRONTMATTER_TOO_DEEP",
+      "FRONTMATTER_ALIAS_LIMIT",
+      "FRONTMATTER_CYCLE"
+    ]);
+    FrontmatterLimitError = class extends Error {
+      name = "FrontmatterLimitError";
+      code;
+      constructor(code3, message) {
+        super(message);
+        this.code = code3;
+      }
+    };
     MalformedDocumentError = class extends Error {
       name = "MalformedDocumentError";
+      code;
       context;
       detail;
       constructor(context3, cause) {
@@ -3018,6 +3044,7 @@ var init_frontmatter_contract = __esm({
         super(
           `malformed frontmatter${context3 ? ` in '${context3}'` : ""}: ${detail2} \u2014 fix the YAML or remove the file`
         );
+        this.code = cause instanceof FrontmatterLimitError ? cause.code : "FRONTMATTER_MALFORMED";
         if (context3 !== void 0) this.context = context3;
         this.detail = detail2;
         if (cause !== void 0) this.cause = cause;
@@ -3026,6 +3053,165 @@ var init_frontmatter_contract = __esm({
   }
 });
 
+// ../core/src/bounded-yaml.ts
+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;
+}
+function loadBoundedYaml(source2, options = {}) {
+  if (source2.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(source2, {
+      ...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 (error51) {
+    const reason = error51.reason;
+    if (typeof reason === "string" && reason.startsWith(MERGE_KEY_LIMIT_REASON)) {
+      throw new FrontmatterLimitError("FRONTMATTER_ALIAS_LIMIT", reason);
+    }
+    throw error51;
+  }
+  new ExtentMeter().measure(value);
+  return value;
+}
+var import_js_yaml, FRONTMATTER_LIMITS, PARSE_NESTING_GUARD, ExtentMeter, AliasBudget, MERGE_KEY_LIMIT_REASON;
+var init_bounded_yaml = __esm({
+  "../core/src/bounded-yaml.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    import_js_yaml = __toESM(require_js_yaml2(), 1);
+    init_frontmatter_contract();
+    FRONTMATTER_LIMITS = Object.freeze({
+      sourceChars: 256 * 1024,
+      depth: 32,
+      aliases: 1e3,
+      expandedNodes: 1e5,
+      expandedChars: 1024 * 1024
+    });
+    PARSE_NESTING_GUARD = FRONTMATTER_LIMITS.depth * 4;
+    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 [key4, child2] of Object.entries(value)) {
+          const inner = this.measure(child2);
+          extent.nodes += inner.nodes;
+          extent.chars += inner.chars + (keyed ? key4.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;
+      }
+    };
+    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: (target3, name, receiver) => {
+            const value = Reflect.get(target3, name, receiver);
+            if (typeof name === "string") this.charge(name, value);
+            return value;
+          },
+          set: (target3, name, value, receiver) => {
+            if (typeof name === "string") {
+              this.finished.delete(name);
+              if (isCollection(value)) this.unfinished.add(value);
+            }
+            return Reflect.set(target3, 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();
+      }
+    };
+    MERGE_KEY_LIMIT_REASON = "merge keys exceeded maxTotalMergeKeys";
+  }
+});
+
 // ../core/src/frontmatter-splitter.ts
 function delimiterLineEnd(input, offset) {
   if (!input.startsWith("---", offset)) return null;
@@ -3063,12 +3249,110 @@ var init_frontmatter_splitter = __esm({
   }
 });
 
+// ../core/src/frontmatter.ts
+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;
+}
+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 parsed2 = yamlTimestampType.construct(value);
+    if (parsed2 instanceof Date) out.timestamp = parsed2.toISOString();
+  }
+  return out;
+}
+function parseMarkdown(raw, context3, options = {}) {
+  const split = splitLeadingFrontmatter(raw, context3);
+  if (!("yamlSource" in split)) return { frontmatter: {}, body: split.body };
+  return { frontmatter: parseFrontmatter(split.yamlSource, context3, options), body: split.body };
+}
+function parseFrontmatter(source2, context3, options = {}) {
+  let parsed2;
+  try {
+    parsed2 = yamlEngine.parse(source2);
+  } catch (err) {
+    throw new MalformedDocumentError(context3, err);
+  }
+  return normalizeFrontmatter(parsed2, options);
+}
+function stringifyFrontmatter(data) {
+  const dumped = import_js_yaml2.default.safeDump(data).trim();
+  try {
+    yamlEngine.parse(`${dumped}
+`);
+  } catch (error51) {
+    if (error51 instanceof FrontmatterLimitError) throw new FrontmatterRefusedError(error51.code, error51.message);
+    const detail2 = (error51 instanceof Error ? error51.message : String(error51)).split("\n")[0] ?? "";
+    throw new FrontmatterRefusedError("FRONTMATTER_MALFORMED", detail2);
+  }
+  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 content3 = body ?? "";
+  const newline = (value) => value.endsWith("\n") ? value : `${value}
+`;
+  if (dumped === "{}") return normalizeDocumentBodyForStorage(content3);
+  return `---
+${newline(dumped)}---
+${normalizeDocumentBodyForStorage(content3)}`;
+}
+function stringifyDoc(frontmatter, body) {
+  return stringifyWithData(frontmatter, body);
+}
+var import_js_yaml2, YAML_TIMESTAMP_TAG, yamlTimestampType, stringTimestampType, losslessDateSchema, yamlEngine;
+var init_frontmatter = __esm({
+  "../core/src/frontmatter.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    import_js_yaml2 = __toESM(require_js_yaml2(), 1);
+    init_bounded_yaml();
+    init_errors();
+    init_frontmatter_contract();
+    init_frontmatter_splitter();
+    init_frontmatter_contract();
+    YAML_TIMESTAMP_TAG = "tag:yaml.org,2002:timestamp";
+    yamlTimestampType = requireYamlTimestampType();
+    stringTimestampType = new import_js_yaml2.default.Type(YAML_TIMESTAMP_TAG, {
+      kind: "scalar",
+      resolve: (value) => yamlTimestampType.resolve(value),
+      construct: (value) => value
+    });
+    losslessDateSchema = new import_js_yaml2.default.Schema({
+      include: [import_js_yaml2.default.DEFAULT_SAFE_SCHEMA],
+      implicit: [stringTimestampType]
+    });
+    yamlEngine = {
+      parse(input) {
+        return loadBoundedYaml(input, { schema: losslessDateSchema }) ?? {};
+      }
+    };
+  }
+});
+
 // ../core/src/portable-frontmatter.ts
 function parseLeadingFrontmatter(raw, context3) {
   const split = splitLeadingFrontmatter(raw, context3);
   if (!("yamlSource" in split)) return {};
   try {
-    const parsed2 = import_js_yaml.default.safeLoad(split.yamlSource);
+    const parsed2 = loadBoundedYaml(split.yamlSource);
     if (parsed2 === void 0 || parsed2 === null) return {};
     if (typeof parsed2 !== "object" || Array.isArray(parsed2)) {
       throw new TypeError("YAML frontmatter must be a mapping");
@@ -3079,14 +3363,27 @@ function parseLeadingFrontmatter(raw, context3) {
     throw new MalformedDocumentError(context3, error51);
   }
 }
-var import_js_yaml;
+function assertStorableFrontmatter(raw) {
+  try {
+    parseLeadingFrontmatter(raw);
+    const split = splitLeadingFrontmatter(raw);
+    if ("yamlSource" in split) parseFrontmatter(split.yamlSource);
+  } catch (error51) {
+    if (error51 instanceof MalformedDocumentError && error51.code !== "FRONTMATTER_MALFORMED") {
+      throw new FrontmatterRefusedError(error51.code, error51.detail);
+    }
+    if (!(error51 instanceof MalformedDocumentError)) throw error51;
+  }
+}
 var init_portable_frontmatter = __esm({
   "../core/src/portable-frontmatter.ts"() {
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
-    import_js_yaml = __toESM(require_js_yaml2(), 1);
+    init_bounded_yaml();
+    init_errors();
     init_frontmatter_contract();
+    init_frontmatter();
     init_frontmatter_splitter();
   }
 });
@@ -3495,93 +3792,6 @@ var init_inventory_guard = __esm({
   }
 });
 
-// ../core/src/frontmatter.ts
-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;
-}
-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 parsed2 = yamlTimestampType.construct(value);
-    if (parsed2 instanceof Date) out.timestamp = parsed2.toISOString();
-  }
-  return out;
-}
-function parseMarkdown(raw, context3, options = {}) {
-  const split = splitLeadingFrontmatter(raw, context3);
-  if (!("yamlSource" in split)) return { frontmatter: {}, body: split.body };
-  return { frontmatter: parseFrontmatter(split.yamlSource, context3, options), body: split.body };
-}
-function parseFrontmatter(source2, context3, options = {}) {
-  let parsed2;
-  try {
-    parsed2 = yamlEngine.parse(source2);
-  } catch (err) {
-    throw new MalformedDocumentError(context3, err);
-  }
-  return normalizeFrontmatter(parsed2, 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 content3 = body ?? "";
-  const newline = (value) => value.endsWith("\n") ? value : `${value}
-`;
-  if (dumped === "{}") return normalizeDocumentBodyForStorage(content3);
-  return `---
-${newline(dumped)}---
-${normalizeDocumentBodyForStorage(content3)}`;
-}
-function stringifyDoc(frontmatter, body) {
-  return stringifyWithData(frontmatter, body);
-}
-var import_js_yaml2, YAML_TIMESTAMP_TAG, yamlTimestampType, stringTimestampType, losslessDateSchema, yamlEngine;
-var init_frontmatter = __esm({
-  "../core/src/frontmatter.ts"() {
-    "use strict";
-    init_define_SUPERBEE_BUILD_IDENTITY();
-    init_define_SUPERBEE_UPDATE_POLICY();
-    import_js_yaml2 = __toESM(require_js_yaml2(), 1);
-    init_frontmatter_contract();
-    init_frontmatter_splitter();
-    init_frontmatter_contract();
-    YAML_TIMESTAMP_TAG = "tag:yaml.org,2002:timestamp";
-    yamlTimestampType = requireYamlTimestampType();
-    stringTimestampType = new import_js_yaml2.default.Type(YAML_TIMESTAMP_TAG, {
-      kind: "scalar",
-      resolve: (value) => yamlTimestampType.resolve(value),
-      construct: (value) => value
-    });
-    losslessDateSchema = new import_js_yaml2.default.Schema({
-      include: [import_js_yaml2.default.DEFAULT_SAFE_SCHEMA],
-      implicit: [stringTimestampType]
-    });
-    yamlEngine = {
-      parse(input) {
-        return import_js_yaml2.default.safeLoad(input, { schema: losslessDateSchema }) ?? {};
-      }
-    };
-  }
-});
-
 // ../core/src/code-unit-order.ts
 function compareCodeUnits(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -5349,6 +5559,22 @@ var init_content_type = __esm({
   }
 });
 
+// ../core/src/reserved-write.ts
+function assertStorableReservedWrite(dir, name, content3) {
+  assertSafeReservedDir(dir);
+  assertSafeReservedFilename(name);
+  if (name.endsWith(".md")) assertStorableFrontmatter(content3);
+}
+var init_reserved_write = __esm({
+  "../core/src/reserved-write.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_paths();
+    init_portable_frontmatter();
+  }
+});
+
 // ../core/src/host-policy-snapshot.ts
 function snapshotHostPolicy(input, seen = /* @__PURE__ */ new WeakMap()) {
   const existing = seen.get(input);
@@ -6688,6 +6914,7 @@ var init_backend = __esm({
     init_engine();
     init_content_type();
     init_paths();
+    init_reserved_write();
     init_errors();
     init_filesystem_identity();
     init_mutation_attribution();
@@ -6884,8 +7111,7 @@ var init_backend = __esm({
         return { content: content3, version: versionOfBytes(content3) };
       }
       async writeReserved(dir, name, content3, options = {}) {
-        assertSafeReservedDir(dir);
-        assertSafeReservedFilename(name);
+        assertStorableReservedWrite(dir, name, content3);
         const rel = reservedPath(dir, name);
         return this.#mutateExact(rel, async (target3) => {
           if (options.expectedVersion !== void 0) {
@@ -9255,6 +9481,7 @@ var init_memory_backend = __esm({
     init_engine();
     init_frontmatter();
     init_paths();
+    init_reserved_write();
     init_versioning();
     MemoryBackend = class _MemoryBackend {
       #inventoryIdentity;
@@ -9377,8 +9604,7 @@ var init_memory_backend = __esm({
         return { content: content3, version: versionOfBytes(content3) };
       }
       async writeReserved(dir, name, content3, options = {}) {
-        assertSafeReservedDir(dir);
-        assertSafeReservedFilename(name);
+        assertStorableReservedWrite(dir, name, content3);
         const key4 = reservedKey(dir, name);
         const existing = this.reserved.get(key4);
         const current = existing === void 0 ? null : versionOfBytes(existing);
@@ -10204,6 +10430,7 @@ var init_remote_backend = __esm({
     init_remote_error();
     init_remote_parsers();
     init_paths();
+    init_reserved_write();
     init_uncertain_write();
     init_version_transport();
     init_remote_error();
@@ -10276,11 +10503,16 @@ var init_remote_backend = __esm({
         }
         const malformedDoc = envelope3?.error?.details?.malformed;
         if (malformedDoc && typeof malformedDoc.reason === "string") {
+          const code4 = malformedDoc.code;
           return new MalformedDocumentError(
             typeof malformedDoc.id === "string" ? malformedDoc.id : fallbackId,
-            new Error(malformedDoc.reason)
+            isFrontmatterLimitCode(code4) ? new FrontmatterLimitError(code4, malformedDoc.reason) : new Error(malformedDoc.reason)
           );
         }
+        const refused = envelope3?.error?.details?.frontmatter?.code;
+        if (res.status === 400 && (refused === "FRONTMATTER_MALFORMED" || isFrontmatterLimitCode(refused))) {
+          return new FrontmatterRefusedError(refused, envelope3?.error?.message ?? "frontmatter cannot be stored");
+        }
         const message = envelope3?.error?.message ?? `wire request failed with status ${res.status}`;
         const code3 = envelope3?.error?.code ?? (res.status === 401 ? "AUTH_REQUIRED" : res.status >= 500 ? "RUNTIME" : "USAGE");
         return new RemoteError(message, code3, res.status);
@@ -10566,8 +10798,7 @@ var init_remote_backend = __esm({
         return { content: payload.content, version: version5 };
       }
       async writeReserved(dir, name, content3, options = {}) {
-        assertSafeReservedDir(dir);
-        assertSafeReservedFilename(name);
+        assertStorableReservedWrite(dir, name, content3);
         assertValidExpectedVersion(options.expectedVersion);
         const headers = { "content-type": "application/json" };
         if (options.expectedVersion === null) headers["If-None-Match"] = "*";
@@ -15094,10 +15325,13 @@ __export(src_exports, {
   DOCUMENT_TRANSFER_CONTRACT: () => DOCUMENT_TRANSFER_CONTRACT,
   DocumentNotFoundError: () => DocumentNotFoundError,
   EXTENSION_CONTENT_TYPES: () => EXTENSION_CONTENT_TYPES,
+  FRONTMATTER_LIMITS: () => FRONTMATTER_LIMITS,
   FieldActionError: () => FieldActionError,
   FilesystemBackend: () => FilesystemBackend,
   FilesystemIdentityAliasError: () => FilesystemIdentityAliasError,
   FilesystemMutationLockError: () => FilesystemMutationLockError,
+  FrontmatterLimitError: () => FrontmatterLimitError,
+  FrontmatterRefusedError: () => FrontmatterRefusedError,
   GENERATED_INDEX_MARKER: () => GENERATED_INDEX_MARKER,
   INVENTORY_GUARD_DOMAIN: () => INVENTORY_GUARD_DOMAIN,
   IndexProjectionWriteError: () => IndexProjectionWriteError,
@@ -15157,6 +15391,7 @@ __export(src_exports, {
   assertSafeReservedDir: () => assertSafeReservedDir,
   assertSafeReservedFilename: () => assertSafeReservedFilename,
   assertSameBodyDelivery: () => assertSameBodyDelivery,
+  assertStorableFrontmatter: () => assertStorableFrontmatter,
   assertTypedListPatch: () => assertTypedListPatch,
   attachBodyPreview: () => attachBodyPreview,
   backlinks: () => backlinks2,
@@ -15239,6 +15474,7 @@ __export(src_exports, {
   latestVerifiedAt: () => latestVerifiedAt,
   list: () => list,
   listBlobs: () => listBlobs2,
+  loadBoundedYaml: () => loadBoundedYaml,
   loadKinds: () => loadKinds,
   localEdgeQualifiedDeclaration: () => localEdgeQualifiedDeclaration,
   matchesFilter: () => matchesFilter,
@@ -15367,6 +15603,9 @@ var init_src = __esm({
     init_freshness();
     init_mutation_attribution();
     init_frontmatter();
+    init_bounded_yaml();
+    init_portable_frontmatter();
+    init_frontmatter_contract();
     init_errors();
     init_document_write_policy();
     init_kinds();
@@ -26003,6 +26242,7 @@ __export(errors_exports, {
   cliErrorFromBoardGit: () => cliErrorFromBoardGit,
   cliErrorFromRecipeLifecycle: () => cliErrorFromRecipeLifecycle,
   cliErrorFromTransfer: () => cliErrorFromTransfer,
+  frontmatterDetails: () => frontmatterDetails,
   toEnvelope: () => toEnvelope,
   toExit: () => toExit
 });
@@ -26012,6 +26252,9 @@ function toEnvelope(err) {
   if (err.help !== void 0) e.help = err.help;
   return { error: e };
 }
+function frontmatterDetails(err) {
+  return { frontmatter: { code: err.code, ...err.context !== void 0 ? { document: err.context } : {} } };
+}
 function classifyBundleError(err, remoteUrl) {
   if (err instanceof CliError) return err;
   if (isBoardGitError(err)) return cliErrorFromBoardGit(err);
@@ -26023,8 +26266,9 @@ function classifyBundleError(err, remoteUrl) {
     return new CliError("USAGE", refusal6.message, { help: refusal6.help, details: { actor: err.actor } });
   }
   if (err instanceof FieldActionError) return new CliError("USAGE", err.message, { details: { ...err.details } });
+  if (err instanceof FrontmatterRefusedError) return new CliError("USAGE", err.message, { details: { frontmatter: { code: err.code } } });
   if (err instanceof InvalidInputError) return new CliError("USAGE", err.message);
-  if (err instanceof MalformedDocumentError) return new CliError("RUNTIME", err.message);
+  if (err instanceof MalformedDocumentError) return new CliError("RUNTIME", err.message, { details: frontmatterDetails(err) });
   if (err instanceof VersionConflict) {
     return new CliError("STALE_HEAD", err.message, {
       details: { expected: err.expected, actual: err.actual }
@@ -30717,6 +30961,8 @@ var init_document_codec = __esm({
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
     init_frontmatter();
+    init_errors();
+    init_portable_frontmatter();
     init_remote_document_codec();
   }
 });
@@ -33644,7 +33890,13 @@ var init_source_plugins = __esm({
 // ../cli/src/recipe-resolver.ts
 async function resolveRecipe(ref, sources = DEFAULT_SOURCES) {
   for (const source2 of sources) {
-    const result3 = await source2.resolve(ref);
+    let result3;
+    try {
+      result3 = await source2.resolve(ref);
+    } catch (error51) {
+      if (error51 instanceof MalformedDocumentError) throw new CliError("USAGE", error51.message, { details: frontmatterDetails(error51) });
+      throw error51;
+    }
     if (result3) return result3;
   }
   return {
@@ -33661,6 +33913,8 @@ var init_recipe_resolver = __esm({
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
+    init_src();
+    init_errors6();
     init_source_plugins();
     init_recipe_source_builtin();
     init_recipe_source_filesystem();
@@ -35844,9 +36098,9 @@ async function docField(argv2, deps2) {
     const source2 = await readExternalTextFile(fromFile);
     if (!source2.trim()) fail4("--from-file must contain one complete JSON/YAML value; the file is empty.");
     try {
-      value = /\.json$/i.test(fromFile) ? JSON.parse(source2) : import_js_yaml3.default.safeLoad(source2, { schema: import_js_yaml3.default.JSON_SCHEMA });
-    } catch {
-      fail4("--from-file must contain one complete valid JSON/YAML value.");
+      value = /\.json$/i.test(fromFile) ? JSON.parse(source2) : loadBoundedYaml(source2, { schema: "json" });
+    } catch (error51) {
+      fail4(error51 instanceof FrontmatterLimitError ? `--from-file was refused: ${error51.message}.` : "--from-file must contain one complete valid JSON/YAML value.");
     }
     if (value === void 0) fail4("--from-file must contain one complete JSON/YAML value.");
   }
@@ -35916,14 +36170,13 @@ async function docField(argv2, deps2) {
     throw error51;
   }
 }
-var import_js_yaml3, leaves, descriptions, DOC_FIELD_USAGE;
+var leaves, descriptions, DOC_FIELD_USAGE;
 var init_field = __esm({
   "../cli/src/commands/doc/field.ts"() {
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
     init_output2();
-    import_js_yaml3 = __toESM(require_js_yaml2(), 1);
     init_src();
     init_args();
     init_command_spec();
@@ -37902,7 +38155,7 @@ function head(value) {
     throw malformed(error51 instanceof Error ? error51.message : "malformed blob head");
   }
 }
-function tooLarge(maximum) {
+function tooLarge2(maximum) {
   return new HostedCarrierError("unavailable", { cause: new HostedAnswerTooLarge(maximum) });
 }
 function createHostedBlobReadAdapter(options) {
@@ -38001,7 +38254,7 @@ function createHostedBlobReadAdapter(options) {
           const lengthText = answer2.headers.get("content-length");
           if (answer2.status !== 200 || answer2.headers.get("content-type") !== "application/octet-stream" || answer2.headers.get("x-superbee-blob-version") !== expected.version || answer2.headers.get("x-superbee-content-type") !== expected.contentType || lengthText === null || !/^(0|[1-9][0-9]*)$/.test(lengthText) || !whole(Number(lengthText))) throw malformed("blob read headers do not match the pin");
           const length = Number(lengthText);
-          if (length > maximum) throw tooLarge(maximum);
+          if (length > maximum) throw tooLarge2(maximum);
           const bytes2 = new Uint8Array(length);
           let offset = 0;
           for (; ; ) {
@@ -38009,7 +38262,7 @@ function createHostedBlobReadAdapter(options) {
             assertOpen();
             if (chunk.done) break;
             if (!(chunk.value instanceof Uint8Array)) throw malformed("blob read yielded non-byte content");
-            if (chunk.value.byteLength > maximum - offset) throw tooLarge(maximum);
+            if (chunk.value.byteLength > maximum - offset) throw tooLarge2(maximum);
             if (chunk.value.byteLength > length - offset) throw malformed("blob read exceeded its stated length");
             bytes2.set(chunk.value, offset);
             offset += chunk.value.byteLength;
@@ -43716,6 +43969,7 @@ var init_indexeddb_backend = __esm({
     init_mutation_attribution();
     init_journaled_backend();
     init_paths();
+    init_reserved_write();
     init_portable_frontmatter();
     init_versioning();
     IndexedDbSchemaError = class extends Error {
@@ -44077,8 +44331,7 @@ var init_indexeddb_backend = __esm({
         return { content: record19.content, version: record19.version };
       }
       async writeReserved(dir, name, content3, options = {}) {
-        assertSafeReservedDir(dir);
-        assertSafeReservedFilename(name);
+        assertStorableReservedWrite(dir, name, content3);
         const path75 = reservedKey2(dir, name);
         return this.#compareAndSwap(RESERVED, path75, path75, options.expectedVersion, () => ({
           record: { path: path75, content: content3, version: versionOfBytes(content3) }
@@ -46429,6 +46682,7 @@ var init_file_journaled_backend = __esm({
     init_journaled_backend();
     init_mutation_attribution();
     init_paths();
+    init_reserved_write();
     init_portable_frontmatter();
     init_sha256();
     init_versioning();
@@ -46806,8 +47060,7 @@ var init_file_journaled_backend = __esm({
         return record19 ? { content: record19.content, version: record19.version } : null;
       }
       async writeReserved(dir, name, content3, options = {}) {
-        assertSafeReservedDir(dir);
-        assertSafeReservedFilename(name);
+        assertStorableReservedWrite(dir, name, content3);
         const key4 = reservedKey3(dir, name);
         const version5 = versionOfBytes(content3);
         const expected = options.expectedVersion;
@@ -51042,7 +51295,7 @@ function foldedPath(id) {
 function documentInputBound(stated) {
   return stated ?? WHOLE_DOCUMENT_BOUNDS.payloadBytes;
 }
-function tooLarge2(id, size, stated) {
+function tooLarge3(id, size, stated) {
   const kib = (bytes2) => Math.ceil(bytes2 / 1024);
   const bound2 = documentInputBound(stated);
   return stated === null || stated === void 0 ? `'${id}' is ${kib(size)} KiB as sent; this host accepts up to ${kib(bound2)} KiB per document (newer hosts accept about 960 KiB as sent)` : `'${id}' is ${kib(size)} KiB as sent; this host accepts up to ${kib(bound2)} KiB per document`;
@@ -51076,7 +51329,7 @@ function unsendable(id, rel, bytes2, stored, context3, fence) {
   }
   const bound2 = documentInputBound(context3.documentInputBytes);
   const screen = context3.documentInputBytes === null || context3.documentInputBytes === void 0 ? bound2 : Math.max(bound2, STORED_DOCUMENT_BYTES);
-  if (bytes2.byteLength > screen) return held(id, rel, "too_large", tooLarge2(id, bytes2.byteLength, context3.documentInputBytes));
+  if (bytes2.byteLength > screen) return held(id, rel, "too_large", tooLarge3(id, bytes2.byteLength, context3.documentInputBytes));
   const content3 = utf83(bytes2);
   if (content3 === null) return held(id, rel, "not_sendable", `'${id}' is not UTF-8 text; sending it would change its bytes`);
   let request4;
@@ -51089,7 +51342,7 @@ function unsendable(id, rel, bytes2, stored, context3, fence) {
   if (request4.kind === "delete") throw new Error(`'${id}' became a delete request`);
   const { frontmatter } = request4.payload;
   const sent = Buffer.byteLength(JSON.stringify(request4.payload));
-  if (sent > bound2) return held(id, rel, "too_large", tooLarge2(id, sent, context3.documentInputBytes));
+  if (sent > bound2) return held(id, rel, "too_large", tooLarge3(id, sent, context3.documentInputBytes));
   if (Buffer.byteLength(JSON.stringify(frontmatter)) > FRONTMATTER_JSON_BYTES || Object.keys(frontmatter).length > FRONTMATTER_KEY_LIMIT) {
     return held(id, rel, "too_large", `'${id}' has more frontmatter than the host accepts (${FRONTMATTER_JSON_BYTES / 1024} KiB, ${FRONTMATTER_KEY_LIMIT} fields)`);
   }
@@ -100105,6 +100358,9 @@ function errorFromCaught(err) {
   if (err instanceof BodyReplaceError) {
     return errorResponse(400, "USAGE", err.message, { id: err.id, ...err.finding });
   }
+  if (err instanceof FrontmatterRefusedError) {
+    return errorResponse(400, "USAGE", err.message, { frontmatter: { code: err.code } });
+  }
   if (err instanceof InvalidInputError) {
     return errorResponse(400, "USAGE", err.message);
   }
@@ -100114,7 +100370,7 @@ function errorFromCaught(err) {
   if (err instanceof MalformedDocumentError) {
     const id = err.context === void 0 ? void 0 : err.context.endsWith(".md") ? err.context.slice(0, -3) : err.context;
     return errorResponse(500, "RUNTIME", err.message, {
-      malformed: { ...id === void 0 ? {} : { id }, reason: err.detail }
+      malformed: { ...id === void 0 ? {} : { id }, reason: err.detail, code: err.code }
     });
   }
   return errorResponse(500, "RUNTIME", "internal server error");
@@ -100644,6 +100900,7 @@ function buildRouter(options) {
       return errorResponse(400, "USAGE", "request body must include a content: string field");
     }
     const writeOptions = writeOptionsFromRequest(req, attribution);
+    assertStorableFrontmatter(payload.content);
     const version5 = await backend.writeReserved(dir, name, payload.content, writeOptions);
     const status2 = writeOptions.expectedVersion === null ? 201 : 200;
     return jsonResponse(status2, { version: version5 }, versionHeaders(version5));
@@ -109452,6 +109709,9 @@ var init_files = __esm({
 });
 
 // ../cli/src/integration-author/validate.ts
+function frontmatterCode(error51) {
+  return error51 instanceof MalformedDocumentError ? { frontmatter_code: error51.code } : {};
+}
 function safeDiagnostic(code3, file2, pointer2, message) {
   return { code: code3, file: authorLocation(file2), path: authorLocation(pointer2), message: authorLocation(message) };
 }
@@ -109464,8 +109724,8 @@ async function loadAuthorRecipe(folder) {
     if (!file2.path.endsWith(".md")) continue;
     try {
       docs.push({ id: file2.path.slice(0, -3), ...parseMarkdown(file2.bytes) });
-    } catch {
-      diagnostics.push(safeDiagnostic("AUTHOR_MARKDOWN_INVALID", file2.path, "", "Invalid Markdown frontmatter; repair this file before validation."));
+    } catch (error51) {
+      diagnostics.push({ ...safeDiagnostic("AUTHOR_MARKDOWN_INVALID", file2.path, "", "Invalid Markdown frontmatter; repair this file before validation."), ...frontmatterCode(error51) });
     }
   }
   if (diagnostics.length) return { ok: false, diagnostics };
@@ -109479,8 +109739,8 @@ async function loadAuthorRecipe(folder) {
   let loaded;
   try {
     loaded = parseRecipeFiles(acquired.files, "local author package", { okfVersion: "0.2" });
-  } catch {
-    diagnostics.push(safeDiagnostic("RECIPE_MALFORMED", "recipe.md", "", "The recipe could not be parsed; repair its declarations."));
+  } catch (error51) {
+    diagnostics.push({ ...safeDiagnostic("RECIPE_MALFORMED", "recipe.md", "", "The recipe could not be parsed; repair its declarations."), ...frontmatterCode(error51) });
     return { ok: false, diagnostics };
   }
   if (!loaded.ok) {
@@ -156109,10 +156369,10 @@ function capabilityRefusal(error51, named, target3, listed2, resume2) {
       help: hostedListCommand(target3)
     });
   }
-  if (error51 instanceof RemoteError && error51.code === "result_too_large") return tooLarge3(reference, target3, null);
+  if (error51 instanceof RemoteError && error51.code === "result_too_large") return tooLarge4(reference, target3, null);
   return hostedFailure(error51, target3, resume2);
 }
-function tooLarge3(named, target3, count6, limit = CHECKOUT_DOCUMENT_LIMIT) {
+function tooLarge4(named, target3, count6, limit = CHECKOUT_DOCUMENT_LIMIT) {
   const reference = typeof named === "string" ? { slug: null, bundleId: named } : named;
   const text7 = hostedBundleReferenceText(reference);
   return new CliError("FORBIDDEN", `hosted bundle '${text7}' is too large to check out (over ${limit} documents)`, {
@@ -156567,7 +156827,7 @@ async function connectHostedBundle(typed, target3, workspaceFlag2, deps2, resume
     throw capabilityRefusal(error51, reference, target3, listed2, resume2);
   }
   const limit = Math.min(CHECKOUT_DOCUMENT_LIMIT, capabilities.paged?.documents ?? capabilities.bound.documents);
-  if (ids.length > limit) throw tooLarge3(reference, target3, ids.length, limit);
+  if (ids.length > limit) throw tooLarge4(reference, target3, ids.length, limit);
   assertProjectable(ids, bundleId2, target3);
   return { identity, reader, listed: listed2, workspace: tenantId ?? workspace, reference, client, definitionWrites: capabilities.definitionWrites, documentInputBytes: capabilities.documentInputBytes };
 }