superbee 0.4.3-pre.1 → 0.4.3-pre.11

package/dist/publication.mjs

@@ -31111,6 +31111,8 @@ function assertSafeConceptId(id) {
     );
   }
 }
+var FORMAT_AT_EDGE = new RegExp("^\\p{Cf}|\\p{Cf}$", "u");
+var FORMAT_INSIDE = new RegExp("(?![\\u200c\\u200d])\\p{Cf}", "u");
 function assertSafeBlobKey(key) {
   if (typeof key !== "string" || key.trim() === "") {
     throw new InvalidInputError("Blob key must be a non-empty string.");
@@ -31153,7 +31155,8 @@ function isExternalHref(href) {
   const h = href.trim();
   return /^[a-z][a-z0-9+.-]*:\/\//i.test(h) || h.startsWith("mailto:") || h.startsWith("#");
 }
-function extractMarkdownLinks(body) {
+function extractMarkdownLinks(source, options = {}) {
+  const body = options.skipCode ? maskMarkdownCode(source) : source;
   const out = [];
   let textOpen = -1;
   let afterClose;
@@ -31165,8 +31168,8 @@ function extractMarkdownLinks(body) {
       if (char === ")") {
         if (hrefRest.open === 0 || body[hrefRest.open - 1] !== "!") {
           out.push({
-            text: body.slice(hrefRest.open + 1, hrefRest.close),
-            href: body.slice(hrefRest.hrefStart, cursor)
+            text: source.slice(hrefRest.open + 1, hrefRest.close),
+            href: source.slice(hrefRest.hrefStart, cursor)
           });
         }
         textOpen = -1;
@@ -31197,6 +31200,150 @@ function extractMarkdownLinks(body) {
   }
   return out;
 }
+function leadingIndent(line, from, startColumn) {
+  let columns = 0;
+  let index2 = from;
+  while (index2 < line.length) {
+    const char = line[index2];
+    if (char === " ") columns += 1;
+    else if (char === "	") columns += 4 - (startColumn + columns) % 4;
+    else break;
+    index2++;
+  }
+  return { columns, chars: index2 - from };
+}
+var FENCE_OPEN = /^(`{3,}|~{3,})(.*)$/;
+var LIST_MARKER = /^([-+*]|\d{1,9}[.)])([ \t]+|$)/;
+var THEMATIC_BREAK = /^(?:(?:\*[ \t]*){3,}|(?:-[ \t]*){3,}|(?:_[ \t]*){3,})$/;
+var ATX_HEADING = /^#{1,6}(?:[ \t]|$)/;
+function maskMarkdownCode(body) {
+  const out = body.split("");
+  const blank = (from, to) => {
+    for (let index2 = from; index2 < to; index2++) if (out[index2] !== "\n" && out[index2] !== "\r") out[index2] = " ";
+  };
+  const lists = [];
+  let fence = null;
+  let inParagraph = false;
+  let segmentStart = -1;
+  const closeSegment = (end) => {
+    if (segmentStart >= 0) maskCodeSpans(body, segmentStart, end, blank);
+    segmentStart = -1;
+  };
+  let lineStart = 0;
+  while (lineStart <= body.length) {
+    const newline = body.indexOf("\n", lineStart);
+    const lineEnd = newline < 0 ? body.length : newline;
+    const line = body.slice(lineStart, lineEnd);
+    let contentAt = 0;
+    let quotes = 0;
+    for (let match = /^ {0,3}> ?/.exec(line); match; match = /^ {0,3}> ?/.exec(line.slice(contentAt))) {
+      if (fence && quotes >= fence.quotes) break;
+      contentAt += match[0].length;
+      quotes++;
+    }
+    const { columns: indent2, chars } = leadingIndent(line, contentAt, contentAt);
+    const rest = line.slice(contentAt + chars).replace(/\r$/, "");
+    const isBlank = rest.trim() === "";
+    if (fence && (quotes < fence.quotes || !isBlank && indent2 < fence.container)) fence = null;
+    if (fence) {
+      const close = indent2 - fence.container <= 3 ? FENCE_OPEN.exec(rest) : null;
+      if (close && close[1][0] === fence.char && close[1].length >= fence.length && close[2].trim() === "") fence = null;
+      blank(lineStart, lineEnd);
+    } else if (isBlank) {
+      closeSegment(lineStart);
+      inParagraph = false;
+    } else {
+      if (!inParagraph) while (lists.length > 0 && lists[lists.length - 1] > indent2) lists.pop();
+      let container = lists.length > 0 ? lists[lists.length - 1] : 0;
+      let relative = indent2 - container;
+      let text4 = rest;
+      let textAt = lineStart + contentAt + chars;
+      const marker = relative <= 3 && !THEMATIC_BREAK.test(text4) ? LIST_MARKER.exec(text4) : null;
+      if (marker) {
+        closeSegment(lineStart);
+        const markerEnd = indent2 + marker[1].length;
+        const spacing = leadingIndent(marker[2], 0, contentAt + markerEnd).columns;
+        const wide = marker[2] === "" || spacing >= 5;
+        lists.push(markerEnd + (wide ? 1 : spacing));
+        container = lists[lists.length - 1];
+        text4 = text4.slice(marker[1].length + (wide ? 0 : marker[2].length));
+        textAt += marker[1].length + (wide ? 0 : marker[2].length);
+        relative = wide ? Math.max(spacing - 1, 0) : 0;
+        inParagraph = false;
+      }
+      const open = relative <= 3 ? FENCE_OPEN.exec(text4) : null;
+      if (open && !(open[1][0] === "`" && open[2].includes("`"))) {
+        closeSegment(lineStart);
+        fence = { char: open[1][0], length: open[1].length, container, quotes };
+        blank(textAt, lineEnd);
+        inParagraph = false;
+      } else if (!inParagraph && relative >= 4) {
+        closeSegment(lineStart);
+        blank(textAt, lineEnd);
+      } else if (ATX_HEADING.test(text4) || THEMATIC_BREAK.test(text4)) {
+        closeSegment(lineStart);
+        maskCodeSpans(body, textAt, lineEnd, blank);
+        inParagraph = false;
+      } else {
+        if (segmentStart < 0) segmentStart = textAt;
+        inParagraph = text4.trim() !== "";
+      }
+    }
+    if (newline < 0) break;
+    lineStart = newline + 1;
+  }
+  closeSegment(body.length);
+  return out.join("");
+}
+function maskCodeSpans(body, from, to, blank) {
+  const runs = [];
+  for (let index2 = from; index2 < to; ) {
+    if (body[index2] !== "`") {
+      index2++;
+      continue;
+    }
+    let end = index2;
+    while (end < to && body[end] === "`") end++;
+    runs.push({ at: index2, length: end - index2 });
+    index2 = end;
+  }
+  const byLength = /* @__PURE__ */ new Map();
+  runs.forEach((run, position2) => {
+    const list3 = byLength.get(run.length);
+    if (list3) list3.push(position2);
+    else byLength.set(run.length, [position2]);
+  });
+  const next = /* @__PURE__ */ new Map();
+  const nextRun = (length, after) => {
+    const list3 = byLength.get(length);
+    if (!list3) return -1;
+    let cursor = next.get(length) ?? 0;
+    while (cursor < list3.length && list3[cursor] <= after) cursor++;
+    next.set(length, cursor);
+    return cursor < list3.length ? list3[cursor] : -1;
+  };
+  let escapeScan = from;
+  let escaped = false;
+  for (let position2 = 0; position2 < runs.length; position2++) {
+    let { at, length } = runs[position2];
+    for (; escapeScan < at; escapeScan++) escaped = body[escapeScan] === "\\" ? !escaped : false;
+    if (escaped) {
+      at += 1;
+      length -= 1;
+      escaped = false;
+      if (length === 0) continue;
+      const list3 = byLength.get(length);
+      if (!list3) continue;
+    }
+    const closer = nextRun(length, position2);
+    if (closer < 0) continue;
+    const close = runs[closer];
+    blank(at, close.at + close.length);
+    position2 = closer;
+    escapeScan = close.at + close.length;
+    escaped = false;
+  }
+}
 function resolveConceptId(fromId, href) {
   const target = (href.split("#")[0] ?? "").split("?")[0]?.trim() ?? "";
   if (target === "" || isExternalHref(target)) return null;
@@ -31269,13 +31416,22 @@ function matchesFilter(doc, filter) {
   }
   return true;
 }
-function matchesSourceIdentity(entry, identity) {
-  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return false;
+function sourceIdentityOf(entry) {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return void 0;
   const row = entry;
+  const identity = {};
+  for (const key of ["resource", "id"]) {
+    if (Object.hasOwn(row, key) && typeof row[key] === "string") identity[key] = row[key];
+  }
+  return identity;
+}
+function matchesSourceIdentity(entry, identity) {
+  const own3 = sourceIdentityOf(entry);
+  if (!own3) return false;
   for (const key of ["resource", "id"]) {
     const expected = identity[key];
     if (expected === void 0) continue;
-    if (!Object.hasOwn(row, key) || typeof row[key] !== "string" || row[key] !== expected) return false;
+    if (own3[key] === void 0 || own3[key] !== expected) return false;
   }
   return true;
 }
@@ -31994,6 +32150,12 @@ async function probeSegment(port, candidate, rel, segment) {
 function hasExact(listing, segment) {
   return listing.some((entry) => entry.name === segment);
 }
+function freshListings(port) {
+  return async (dir) => {
+    const listing = await port.entries(dir);
+    return listing === null ? null : { has: (name) => hasExact(listing, name) };
+  };
+}
 async function walkExact(port, rootResolved, segments, rel) {
   let parent = rootResolved;
   for (let index2 = 0; index2 < segments.length; index2++) {
@@ -32025,14 +32187,14 @@ async function recordWalk(port, rootResolved, segments, rel) {
   }
   return recorded;
 }
-async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle) {
+async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle, listings = freshListings(port)) {
   let parent = rootResolved;
   for (let index2 = 0; index2 < segments.length; index2++) {
     const segment = segments[index2];
     const candidate = path2.join(parent, segment);
-    const listing = await port.entries(parent);
+    const listing = await listings(parent);
     if (listing === null) return "absent";
-    const listed = hasExact(listing, segment);
+    const listed = listing.has(segment);
     if (handle !== null && index2 === segments.length - 1) {
       const verdict = classifyLeaf({ listed, probe: await probeSegment(port, candidate, rel, segment), handle });
       if (verdict === "aliased") throw new FilesystemIdentityAliasError(rel, segment);
@@ -32052,13 +32214,15 @@ function countRestart(restarts, rel) {
   return restarts + 1;
 }
 async function observeExact(port, root, rel, read) {
+  return observeWith(port, path2.resolve(root), rel, read, freshListings(port));
+}
+async function observeWith(port, rootResolved, rel, read, listings, onExact) {
   const segments = relSegments(rel);
-  const rootResolved = path2.resolve(root);
   const target = path2.join(rootResolved, ...segments);
   for (let restarts = 0; ; ) {
     const recorded = await recordWalk(port, rootResolved, segments, rel);
     if (recorded === null) return { state: "absent" };
-    const verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null);
+    const verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null, listings);
     if (verified === "absent") return { state: "absent" };
     if (verified === "restart") {
       restarts = countRestart(restarts, rel);
@@ -32080,11 +32244,14 @@ async function observeExact(port, root, rel, read) {
     try {
       value = await read(opened.handle, target);
       if (value === null) return { state: "absent" };
-      verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened);
+      verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened, listings);
     } finally {
       await port.close(opened.handle);
     }
-    if (verdict === "exact") return { state: "exact", value };
+    if (verdict === "exact") {
+      onExact?.(recorded, { dev: opened.dev, ino: opened.ino });
+      return { state: "exact", value };
+    }
     if (verdict === "absent") return { state: "absent" };
     restarts = countRestart(restarts, rel);
   }
@@ -32103,6 +32270,100 @@ async function probeExact(port, root, rel) {
     restarts = countRestart(restarts, rel);
   }
 }
+var SETTLED_AFTER_NS = 3000000000n;
+function witnessKey(witness) {
+  return `${witness.dev}:${witness.ino}:${witness.mtimeNs}:${witness.ctimeNs}`;
+}
+function openObservationPass(port, root, now = Date.now) {
+  const rootResolved = path2.resolve(root);
+  const kept = /* @__PURE__ */ new Map();
+  const reusedVerdicts = [];
+  const fresh = freshListings(port);
+  const witnessOf = port.directoryWitness?.bind(port);
+  const settled = (witness) => {
+    const nowNs = BigInt(Math.floor(now())) * 1000000n;
+    const latest = witness.mtimeNs > witness.ctimeNs ? witness.mtimeNs : witness.ctimeNs;
+    return nowNs - latest >= SETTLED_AFTER_NS;
+  };
+  const listingsFor = () => {
+    let reused = false;
+    if (witnessOf === void 0) return { source: fresh, reused: () => false };
+    const source = async (dir) => {
+      const keep = kept.get(dir);
+      if (keep !== void 0) {
+        const current = await witnessOf(dir);
+        if (current !== null && witnessKey(current) === keep.witness) {
+          reused = true;
+          return keep.names;
+        }
+        kept.delete(dir);
+      }
+      const before = await witnessOf(dir);
+      const listing = await port.entries(dir);
+      if (listing === null) return null;
+      const names = new Set(listing.map((entry) => entry.name));
+      const after = await witnessOf(dir);
+      if (before !== null && after !== null && witnessKey(before) === witnessKey(after) && settled(after)) {
+        kept.set(dir, { witness: witnessKey(after), names });
+      }
+      return names;
+    };
+    return { source, reused: () => reused };
+  };
+  return {
+    async observe(rel, read) {
+      const listings = listingsFor();
+      let exact;
+      let observed;
+      try {
+        observed = await observeWith(port, rootResolved, rel, read, listings.source, (recorded, handle) => {
+          exact = { rel, segments: relSegments(rel), recorded, handle };
+        });
+      } catch (error) {
+        if (!listings.reused()) throw error;
+        return observeExact(port, rootResolved, rel, read);
+      }
+      if (!listings.reused()) return observed;
+      if (observed.state === "absent") return observeExact(port, rootResolved, rel, read);
+      if (exact !== void 0) reusedVerdicts.push(exact);
+      return observed;
+    },
+    async finish() {
+      const retry = /* @__PURE__ */ new Set();
+      const endListings = /* @__PURE__ */ new Map();
+      const listedAtEnd = async (dir) => {
+        if (!endListings.has(dir)) {
+          const listing = await port.entries(dir);
+          endListings.set(dir, listing === null ? null : new Set(listing.map((entry) => entry.name)));
+        }
+        return endListings.get(dir);
+      };
+      try {
+        for (const verdict of reusedVerdicts) {
+          if (!await holdsAtEnd(port, rootResolved, verdict, listedAtEnd)) retry.add(verdict.rel);
+        }
+      } finally {
+        kept.clear();
+        reusedVerdicts.length = 0;
+      }
+      return [...retry];
+    }
+  };
+}
+async function holdsAtEnd(port, rootResolved, verdict, listedAtEnd) {
+  let parent = rootResolved;
+  for (let index2 = 0; index2 < verdict.segments.length; index2++) {
+    const segment = verdict.segments[index2];
+    const listing = await listedAtEnd(parent);
+    if (listing === null || !listing.has(segment)) return false;
+    const candidate = path2.join(parent, segment);
+    const probed = await port.probe(candidate);
+    const expected = index2 === verdict.segments.length - 1 ? verdict.handle : verdict.recorded[index2];
+    if (probed === null || probed.kind === "symlink" || !sameWitness(probed, expected)) return false;
+    parent = candidate;
+  }
+  return true;
+}
 var linkUnsupportedRoots = /* @__PURE__ */ new WeakMap();
 function unsupportedLinkRoots(port) {
   let roots = linkUnsupportedRoots.get(port);
@@ -32256,8 +32517,56 @@ function kindOf(stats) {
   if (stats.isFile()) return "file";
   return "other";
 }
+var LOCAL_LINUX_FILESYSTEMS = /* @__PURE__ */ new Set([
+  61267,
+  // ext2/3/4
+  1481003842,
+  // xfs
+  2435016766,
+  // btrfs
+  16914836,
+  // tmpfs
+  2240043254,
+  // ramfs
+  2035054128,
+  // overlayfs
+  801189825,
+  // zfs
+  4076150800,
+  // f2fs
+  3393526350,
+  // bcachefs
+  19780,
+  // vfat
+  538032816,
+  // exfat
+  1936094318,
+  // ntfs3
+  18475
+  // hfsplus
+]);
+function directoryWitnessTrusted(platform, filesystemType) {
+  if (platform !== "linux") return true;
+  return filesystemType !== null && LOCAL_LINUX_FILESYSTEMS.has(filesystemType);
+}
+function witnessTrust() {
+  const devices = /* @__PURE__ */ new Map();
+  return (dev, dir) => {
+    if (process.platform !== "linux") return Promise.resolve(true);
+    let trusted = devices.get(dev);
+    if (trusted === void 0) {
+      trusted = fs2.statfs(dir).then(
+        (info) => directoryWitnessTrusted("linux", Number(info.type)),
+        () => false
+      );
+      devices.set(dev, trusted);
+    }
+    return trusted;
+  };
+}
 function createNodeFilesystemIdentityPort(hostPolicy) {
   const policy = captureFilesystemHostPolicy(hostPolicy);
+  const witnessTrustedOn = witnessTrust();
   return Object.freeze({
     isTransientOpenError: policy.isTransientOpenError,
     isReplacementConflict: policy.isReplacementConflict,
@@ -32280,6 +32589,17 @@ function createNodeFilesystemIdentityPort(hostPolicy) {
         throw err;
       }
     },
+    async directoryWitness(dir) {
+      let stats;
+      try {
+        stats = await fs2.stat(dir, { bigint: true });
+      } catch (err) {
+        if (isAbsentPathError(err)) return null;
+        throw err;
+      }
+      if (!await witnessTrustedOn(stats.dev, dir)) return null;
+      return { dev: stats.dev, ino: stats.ino, mtimeNs: stats.mtimeNs, ctimeNs: stats.ctimeNs };
+    },
     async open(target) {
       const handle = await fs2.open(target, "r");
       try {
@@ -32590,10 +32910,11 @@ var FilesystemBackend = class _FilesystemBackend {
       return void 0;
     }
   }
-  async #readWithEdition(id, edition) {
+  async #readWithEdition(id, edition, pass) {
     assertSafeConceptId(id);
     const rel = pathFromConceptId(id);
-    const observed = await observeExact(this.#port, this.#root, rel, (handle) => readBytes(this.#port, handle));
+    const read = (handle) => readBytes(this.#port, handle);
+    const observed = pass ? await pass.observe(rel, read) : await observeExact(this.#port, this.#root, rel, read);
     if (observed.state === "absent") throw notFound(this.#root, rel);
     const raw = observed.value.toString("utf8");
     const { frontmatter: frontmatter2, body } = parseMarkdown(raw, rel, { okfVersion: await edition() });
@@ -32608,7 +32929,12 @@ var FilesystemBackend = class _FilesystemBackend {
     }
     let editionPromise;
     const edition = () => editionPromise ??= this.#readEdition();
-    for (const id of ids) out.push(await this.#readWithEdition(id, edition));
+    const pass = openObservationPass(this.#port, this.#root);
+    for (const id of ids) out.push(await this.#readWithEdition(id, edition, pass));
+    const retry = new Set(await pass.finish());
+    for (let index2 = 0; index2 < ids.length; index2++) {
+      if (retry.has(pathFromConceptId(ids[index2]))) out[index2] = await this.#readWithEdition(ids[index2], edition);
+    }
     return out;
   }
   async write(id, doc, options = {}) {
@@ -32768,14 +33094,36 @@ function publicationContext(backend) {
   return context;
 }
 async function readRawFilesystemDocument(backend, id) {
+  return readRawDocumentIn(backend, id);
+}
+async function readRawDocumentIn(backend, id, pass) {
   assertSafeConceptId(id);
   const { root, port } = publicationContext(backend);
   const rel = pathFromConceptId(id);
-  const observed = await observeExact(port, root, rel, (handle) => readBytes(port, handle));
+  const read = (handle) => readBytes(port, handle);
+  const observed = pass ? await pass.observe(rel, read) : await observeExact(port, root, rel, read);
   if (observed.state === "absent") throw notFound(root, rel);
   const raw = new TextDecoder("utf-8", { fatal: true }).decode(observed.value);
   return { bytes: observed.value.slice(), version: versionOfBytes(raw) };
 }
+function openRawFilesystemDocumentPass(backend) {
+  const { root, port } = publicationContext(backend);
+  const pass = openObservationPass(port, root);
+  const ids = /* @__PURE__ */ new Map();
+  return {
+    read(id) {
+      assertSafeConceptId(id);
+      ids.set(pathFromConceptId(id), id);
+      return readRawDocumentIn(backend, id, pass);
+    },
+    async finish() {
+      return (await pass.finish()).flatMap((rel) => {
+        const id = ids.get(rel);
+        return id === void 0 ? [] : [id];
+      });
+    }
+  };
+}
 async function readRawFilesystemReserved(backend, dir, name) {
   assertSafeReservedDir(dir);
   assertSafeReservedFilename(name);
@@ -32836,6 +33184,23 @@ setDefaultBackendFactory((root) => new FilesystemBackend(root));
 // ../core/src/kinds.ts
 var CONVENTIONS_PREFIX = "conventions/";
 var CONVENTION_TYPE = "Convention";
+var KIND_FIELD_TYPES = [
+  "date",
+  "datetime",
+  "https-url",
+  "https-url-list",
+  "integer",
+  "number",
+  "boolean",
+  "slug",
+  "string-list",
+  "latitude",
+  "longitude"
+];
+var KIND_FIELD_TYPE_SET = new Set(KIND_FIELD_TYPES);
+function isKindFieldType(value) {
+  return typeof value === "string" && KIND_FIELD_TYPE_SET.has(value);
+}
 function buildKindRegistry(docs, initialWarnings = [], options = {}) {
   const accepted = /* @__PURE__ */ new Map();
   const warnings = [...initialWarnings];
@@ -32987,7 +33352,8 @@ var VALID_FIELDS_KEYS = /* @__PURE__ */ new Set([
   "values",
   "value_descriptions",
   "terminal",
-  "descriptions"
+  "descriptions",
+  "types"
 ]);
 var MISPLACED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["enum", "enums", "values", "constraints"]);
 var CLAIM_COORDINATE_KEYS = [
@@ -33027,7 +33393,7 @@ function parseConventionDoc(doc, options = {}) {
       if (!VALID_FIELDS_KEYS.has(key)) {
         warnings.push({
           code: "KIND_CONVENTION_UNKNOWN_FIELDS_KEY",
-          message: `kind convention '${doc.id}' declares an unrecognized key 'fields.${key}' (valid keys: fields.required, fields.optional, fields.values, fields.value_descriptions, fields.terminal, fields.descriptions); ignoring it.`,
+          message: `kind convention '${doc.id}' declares an unrecognized key 'fields.${key}' (valid keys: fields.required, fields.optional, fields.values, fields.value_descriptions, fields.terminal, fields.descriptions, fields.types); ignoring it.`,
           field: `fields.${key}`,
           severity: "warning"
         });
@@ -33084,6 +33450,51 @@ function parseConventionDoc(doc, options = {}) {
       });
     }
   }
+  const typesSource = fieldsRaw.types;
+  const types = {};
+  if (typesSource !== void 0) {
+    if (!isPlainObject(typesSource)) {
+      warnings.push({
+        code: "KIND_CONVENTION_BAD_SHAPE",
+        message: `kind convention '${doc.id}' has a non-map 'fields.types' (${describeShape(typesSource)}; expected a map of field name -> type); ignoring it.`,
+        field: "fields.types",
+        severity: "warning"
+      });
+    } else {
+      for (const [field, declared] of Object.entries(typesSource)) {
+        if (dropReserved(field, `fields.types.${field}`)) continue;
+        if (!isKindFieldType(declared)) {
+          warnings.push({
+            code: "KIND_CONVENTION_UNKNOWN_FIELD_TYPE",
+            message: `kind convention '${doc.id}' declares 'fields.types.${field}' as ${isScalar(declared) ? `'${String(declared)}'` : describeShape(declared)}, which is not a field type (valid types: ${KIND_FIELD_TYPES.join(", ")}); ignoring it.`,
+            field: `fields.types.${field}`,
+            severity: "warning"
+          });
+          continue;
+        }
+        if (!declaredFieldNames.has(field)) {
+          warnings.push({
+            code: "KIND_CONVENTION_UNDECLARED_TYPES_FIELD",
+            message: `kind convention '${doc.id}' declares 'fields.types.${field}' but '${field}' is not in fields.required or fields.optional; ignoring it.`,
+            field: `fields.types.${field}`,
+            severity: "warning"
+          });
+          continue;
+        }
+        setOwn(types, field, declared);
+      }
+    }
+  }
+  for (const field of Object.keys(values)) {
+    if (types[field] !== "https-url-list") continue;
+    warnings.push({
+      code: "KIND_CONVENTION_VALUES_TYPE_MISMATCH",
+      message: `kind convention '${doc.id}' declares 'fields.values.${field}' on a field of type 'https-url-list', which cannot carry an enum; ignoring the values.`,
+      field: `fields.values.${field}`,
+      severity: "warning"
+    });
+    delete values[field];
+  }
   const valueDescriptionsSource = fieldsRaw.value_descriptions;
   const valueDescriptions = {};
   if (valueDescriptionsSource !== void 0) {
@@ -33376,6 +33787,7 @@ function parseConventionDoc(doc, options = {}) {
     governs,
     fields: { required, optional, values, valueDescriptions, terminal, descriptions }
   };
+  if (Object.keys(types).length > 0) kind2.fields.types = types;
   if (description !== void 0) kind2.description = description;
   if (path6 !== void 0) kind2.path = path6;
   if (links !== void 0) kind2.links = links;
@@ -42435,6 +42847,10 @@ function gfmFromMarkdown() {
 
 // ../markdown-renderer/src/index.tsx
 var import_jsx_runtime = __toESM(require_jsx_runtime(), 1);
+function renderableConceptId(fromId, raw) {
+  if (/^okf:/i.test(raw.trim())) return null;
+  return resolveConceptId(fromId, raw);
+}
 var MAX_BODY_CHARS = 262144;
 var MAX_NODES = 2e4;
 var MAX_DEPTH = 40;
@@ -42450,6 +42866,9 @@ function textOf(node2) {
   if (!Array.isArray(children)) return "";
   return children.map((child) => textOf(child)).join("");
 }
+function renderTextFallback(node2, index2) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-markdown-fallback", children: textOf(node2) }, index2);
+}
 function isBlankInline(node2) {
   if (node2.type === "break") return true;
   if (node2.type === "text") return (node2.value ?? "").trim() === "";
@@ -42460,7 +42879,7 @@ function isBareLinkBlock(node2, fromId) {
   let sawLink = false;
   for (const child of node2.children) {
     if (isBlankInline(child)) continue;
-    if (child.type === "link" && resolveConceptId(fromId, child.url ?? "") !== null) {
+    if (child.type === "link" && renderableConceptId(fromId, child.url ?? "") !== null) {
       sawLink = true;
       continue;
     }
@@ -42544,7 +42963,7 @@ function renderNode(node2, state, depth, index2) {
   state.count++;
   if (depth > MAX_DEPTH) {
     state.bounded = true;
-    return textOf(node2);
+    return renderTextFallback(node2, index2);
   }
   switch (node2.type) {
     case "text":
@@ -42588,7 +43007,7 @@ function renderNode(node2, state, depth, index2) {
       return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("br", {}, index2);
     case "link": {
       const raw = node2.url ?? "";
-      const resolved = resolveConceptId(state.options.fromId, raw);
+      const resolved = renderableConceptId(state.options.fromId, raw);
       const children = renderChildren(node2, state, depth);
       if (resolved === null) {
         const external = admitExternalLink(raw, state.options.externalLinkHosts);
@@ -42645,7 +43064,7 @@ function renderNode(node2, state, depth, index2) {
     case "html":
       return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-raw-html", children: node2.value }, index2);
     default:
-      return textOf(node2);
+      return renderTextFallback(node2, index2);
   }
 }
 function renderEdgeList(links, state, index2) {
@@ -42657,14 +43076,14 @@ function renderEdgeList(links, state, index2) {
       break;
     }
     state.count++;
-    const to = resolveConceptId(fromId, links[i].url ?? "");
+    const to = renderableConceptId(fromId, links[i].url ?? "");
     if (to === null) continue;
     const verb = textOf(links[i]).trim();
     const target = titleFor?.(to) ?? to;
     if (state.options.profile === "inert") {
       rows.push(
         /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { className: "doc-edge-row", "data-aslite-doc-id": to, children: [
-          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-edge-verb", children: verb }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-edge-verb doc-markdown-fallback", children: verb }),
           /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-edge-arrow", "aria-hidden": "true", children: "\u2192" }),
           /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-edge-target", children: target })
         ] }, i)
@@ -42679,7 +43098,7 @@ function renderEdgeList(links, state, index2) {
           href: documentHref(to, state.options),
           onClick: (event) => navigateDoc(event, to, state.options),
           children: [
-            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-edge-verb", children: verb }),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-edge-verb doc-markdown-fallback", children: verb }),
             /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-edge-arrow", "aria-hidden": "true", children: "\u2192" }),
             /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "doc-edge-target", children: target })
           ]
@@ -43605,10 +44024,20 @@ async function readInventory(backend, limits) {
     return bytes;
   };
   const documents = [];
+  const documentPass = openRawFilesystemDocumentPass(backend);
   for (const id of documentIds) {
-    const row = await readRawFilesystemDocument(backend, id);
+    const row = await documentPass.read(id);
     documents.push({ id, version: row.version, bytes: admitBytes(row.bytes, id) });
   }
+  for (const id of await documentPass.finish()) {
+    const row = await readRawFilesystemDocument(backend, id).catch((error) => {
+      if (error?.code !== "ENOENT") throw error;
+      return null;
+    });
+    if (row === null || documents.some((document3) => document3.id === id && document3.version !== row.version)) {
+      throw new PublicationError("SOURCE_CHANGED", "a publication object changed during capture", { retryable: true });
+    }
+  }
   const reserved = [];
   for (const identity of reservedIds) {
     const row = await readRawFilesystemReserved(backend, identity.dir, identity.name);