superbee 0.2.1 → 0.3.0-pre.2

package/dist/publication.mjs

@@ -30917,21 +30917,28 @@ function normalizeFrontmatter(data, okfVersion) {
 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(split.yamlSource);
+    parsed = yamlEngine.parse(source);
   } catch (err) {
     throw new MalformedDocumentError(context, err);
   }
-  const frontmatter2 = normalizeFrontmatter(parsed, options.okfVersion);
-  return { frontmatter: frontmatter2, body: split.body };
+  return normalizeFrontmatter(parsed, options.okfVersion);
+}
+function stringifyFrontmatter(data) {
+  return import_js_yaml.default.safeDump(data).trim();
 }
 function normalizeDocumentBodyForStorage(body) {
   return body.endsWith("\n") ? body : `${body}
 `;
 }
 function stringifyWithData(data, body) {
-  const dumped = import_js_yaml.default.safeDump(data).trim();
+  return stringifyWithSerializedFrontmatter(stringifyFrontmatter(data), body);
+}
+function stringifyWithSerializedFrontmatter(dumped, body) {
   const content3 = body ?? "";
   const newline = (value) => value.endsWith("\n") ? value : `${value}
 `;
@@ -30992,6 +30999,29 @@ function mutationActorFromFrontmatter(frontmatter2) {
 
 // ../core/src/paths.ts
 var RESERVED_FILENAMES = ["index.md", "log.md"];
+function compareStorageKeys(a, b) {
+  const primary = a.localeCompare(b);
+  if (primary !== 0 || a === b) return primary;
+  const left = Array.from(a, (character) => character.codePointAt(0));
+  const right = Array.from(b, (character) => character.codePointAt(0));
+  for (let i = 0; i < Math.min(left.length, right.length); i++) {
+    if (left[i] !== right[i]) return left[i] - right[i];
+  }
+  return left.length - right.length;
+}
+function assertPortablePath(value, label) {
+  if (/[\u0000-\u001f\u007f]/u.test(value) || /^[a-z]:/i.test(value)) {
+    throw new InvalidInputError(`${label} must not contain controls or start with a drive prefix.`);
+  }
+  if (value.includes("\\") || value.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new InvalidInputError(`${label} must be canonical and bundle-relative.`);
+  }
+}
+function assertSafeReservedFilename(name) {
+  if (!RESERVED_FILENAMES.includes(name)) {
+    throw new InvalidInputError("Reserved filename must be index.md or log.md.");
+  }
+}
 function toPosix(p) {
   return p.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
 }
@@ -31011,21 +31041,8 @@ function assertSafeConceptId(id) {
   if (typeof id !== "string" || id.trim() === "") {
     throw new InvalidInputError("Concept id must be a non-empty string.");
   }
-  if (id.startsWith("/")) {
-    throw new InvalidInputError(`Concept id must be bundle-relative, got absolute '${id}'.`);
-  }
-  if (id.includes("\\")) {
-    throw new InvalidInputError(`Concept id must use forward slashes: '${id}'.`);
-  }
+  assertPortablePath(id, "Concept id");
   const segments = id.split("/");
-  if (segments.some((seg) => seg === "..")) {
-    throw new InvalidInputError(`Concept id must not contain '..' segments: '${id}'.`);
-  }
-  if (segments.some((seg) => seg === "." || seg === "")) {
-    throw new InvalidInputError(
-      `Concept id must be canonical (no '.', duplicate-slash, leading './', or trailing-slash segments): '${id}'.`
-    );
-  }
   if (segments.slice(0, -1).some((seg) => seg.toLowerCase().endsWith(".md"))) {
     throw new InvalidInputError(
       `Concept id must not contain a non-final segment ending in '.md': '${id}' (it collides with a concept file at that path).`
@@ -31036,21 +31053,11 @@ function assertSafeBlobKey(key) {
   if (typeof key !== "string" || key.trim() === "") {
     throw new InvalidInputError("Blob key must be a non-empty string.");
   }
-  const norm = toPosix(key);
-  if (norm.startsWith("/")) {
-    throw new InvalidInputError(`Blob key must be bundle-relative, got absolute '${key}'.`);
-  }
-  const segments = norm.split("/");
-  if (segments.some((seg) => seg === "..")) {
-    throw new InvalidInputError(`Blob key must not contain '..' segments: '${key}'.`);
-  }
+  assertPortablePath(key, "Blob key");
+  const segments = key.split("/");
   if (segments.some((seg) => seg.startsWith("."))) {
     throw new InvalidInputError(`Blob key must not contain dot-prefixed segments: '${key}'.`);
   }
-  const last = segments[segments.length - 1] ?? "";
-  if (last === "") {
-    throw new InvalidInputError(`Blob key must name a file, not end with '/': '${key}'.`);
-  }
   if (segments.some((seg) => seg.toLowerCase().endsWith(".md"))) {
     throw new InvalidInputError(
       `Blob key '${key}' has a path segment ending in '.md' (checked case-insensitively, at any depth), which collides with the concept-document namespace \u2014 write it as a doc instead.`
@@ -31061,13 +31068,7 @@ function assertSafeReservedDir(dir) {
   if (typeof dir !== "string") {
     throw new InvalidInputError("Reserved-file directory must be a string.");
   }
-  const norm = toPosix(dir);
-  if (norm.startsWith("/")) {
-    throw new InvalidInputError(`Reserved-file directory must be bundle-relative, got absolute '${dir}'.`);
-  }
-  if (norm.split("/").some((seg) => seg === "..")) {
-    throw new InvalidInputError(`Reserved-file directory must not contain '..' segments: '${dir}'.`);
-  }
+  if (dir !== "") assertPortablePath(dir, "Reserved-file directory");
 }
 
 // ../core/src/links.ts
@@ -31372,7 +31373,52 @@ import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypt
 
 // ../core/src/filesystem-lock.ts
 import { promises as fs, realpathSync } from "node:fs";
-import { homedir, hostname, userInfo } from "node:os";
+import { homedir, hostname } from "node:os";
+
+// ../core/src/host-policy-snapshot.ts
+function snapshotHostPolicy(input, seen = /* @__PURE__ */ new WeakMap()) {
+  const existing = seen.get(input);
+  if (existing) return existing;
+  const result = Array.isArray(input) ? [] : {};
+  seen.set(input, result);
+  const keys = /* @__PURE__ */ new Set();
+  for (let owner = input; owner && owner !== Object.prototype && owner !== Array.prototype; owner = Object.getPrototypeOf(owner)) {
+    for (const key of Reflect.ownKeys(owner)) {
+      if (key !== "constructor" && !(Array.isArray(input) && key === "length")) keys.add(key);
+    }
+  }
+  for (const key of keys) {
+    const value = input[key];
+    Object.defineProperty(result, key, {
+      value: typeof value === "function" ? value.bind(result) : value && typeof value === "object" ? snapshotHostPolicy(value, seen) : value,
+      enumerable: true
+    });
+  }
+  if (Array.isArray(input)) result.length = input.length;
+  return Object.freeze(result);
+}
+
+// ../core/src/filesystem-host.ts
+function defaultFilesystemHostPolicy() {
+  if (process.platform !== "darwin" && process.platform !== "linux") {
+    throw new InvalidInputError(
+      "This host requires an explicit filesystem host policy; the default filesystem supports macOS and Linux."
+    );
+  }
+  return {
+    runtimeLockParent: () => "/tmp",
+    runtimeOwnerKey: () => `uid-${process.getuid()}`,
+    enforcePrivateMode: true,
+    isTransientOpenError: () => false,
+    isReplacementConflict: () => false,
+    isDirectoryContentionError: () => false
+  };
+}
+function captureFilesystemHostPolicy(policy) {
+  return snapshotHostPolicy(policy ?? defaultFilesystemHostPolicy());
+}
+
+// ../core/src/filesystem-lock.ts
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 var OWNER_FILE = "owner.json";
@@ -31392,16 +31438,6 @@ var FilesystemMutationLockError = class extends Error {
     this.malformed = details.malformed;
   }
 };
-function runtimeOwnerKey() {
-  const uid = process.getuid?.();
-  if (uid !== void 0) return `uid-${uid}`;
-  let username = "unknown";
-  try {
-    username = userInfo().username;
-  } catch {
-  }
-  return `user-${createHash("sha256").update(username).digest("hex").slice(0, 16)}`;
-}
 function canonicalExistingPath(value) {
   try {
     return realpathSync(value);
@@ -31413,11 +31449,12 @@ function pathContains(root, candidate) {
   const rel = path.relative(root, candidate);
   return rel === "" || !rel.startsWith("..") && !path.isAbsolute(rel);
 }
-function filesystemMutationLockRoot(portableRoot) {
-  const runtimeParent = process.platform === "win32" ? path.join(homedir(), "AppData", "Local") : "/tmp";
+function filesystemMutationLockRoot(portableRoot, hostPolicy) {
+  const policy = captureFilesystemHostPolicy(hostPolicy);
+  const runtimeParent = policy.runtimeLockParent();
   const tempParent = canonicalExistingPath(runtimeParent);
   const homeParent = canonicalExistingPath(homedir());
-  const ownerKey = runtimeOwnerKey();
+  const ownerKey = policy.runtimeOwnerKey();
   const candidates = [
     path.join(tempParent, `agentstate-lite-mutation-locks-${ownerKey}`),
     path.join(homeParent, ".agentstate", `mutation-locks-${ownerKey}`)
@@ -31457,14 +31494,32 @@ function parseFilesystemMutationLockOwner(value) {
     target: value.target
   };
 }
-async function readOwner(lockPath) {
+async function readOwnerRecord(lockPath) {
+  let raw;
   try {
-    return parseFilesystemMutationLockOwner(
-      JSON.parse(await fs.readFile(path.join(lockPath, OWNER_FILE), "utf8"))
-    );
+    raw = await fs.readFile(path.join(lockPath, OWNER_FILE), "utf8");
+  } catch (err) {
+    const code2 = err.code;
+    return code2 === "ENOENT" || code2 === "ENOTDIR" ? { state: "absent" } : { state: "unreadable", error: err };
+  }
+  let owner = null;
+  try {
+    owner = parseFilesystemMutationLockOwner(JSON.parse(raw));
   } catch {
-    return null;
+    owner = null;
   }
+  return owner === null ? { state: "absent" } : { state: "record", owner };
+}
+async function resolveOwnerRecord(lockPath, started, waitMs, pollMs) {
+  while (true) {
+    const record = await readOwnerRecord(lockPath);
+    if (record.state !== "unreadable" || Date.now() - started >= waitMs) return record;
+    await delay(pollMs);
+  }
+}
+async function readOwner(lockPath) {
+  const record = await readOwnerRecord(lockPath);
+  return record.state === "record" ? record.owner : null;
 }
 function processExists(pid) {
   try {
@@ -31487,7 +31542,7 @@ async function pathExists(candidate) {
     throw err;
   }
 }
-async function quarantineStaleLock(lockPath, owner) {
+async function quarantineStaleLock(lockPath, owner, policy) {
   if (owner.hostname !== hostname() || processExists(owner.pid)) return false;
   const quarantinePath = staleLockQuarantinePath(lockPath, owner);
   try {
@@ -31497,7 +31552,7 @@ async function quarantineStaleLock(lockPath, owner) {
     const code2 = err.code;
     if (code2 === "ENOENT") return false;
     if (await pathExists(quarantinePath)) return false;
-    if (process.platform === "win32" && WINDOWS_DIRECTORY_CONTENTION_CODES.has(code2 ?? "")) return false;
+    if (policy.isDirectoryContentionError(err)) return false;
     throw err;
   }
 }
@@ -31516,7 +31571,7 @@ function isPrivateFilesystemMutationLockRoot(facts) {
   const unsafeMode = facts.enforcePrivateMode && (facts.mode & 511) !== 448;
   return facts.directory && !facts.symbolicLink && !wrongOwner && !unsafeMode;
 }
-async function ensurePrivateLockRoot(root) {
+async function ensurePrivateLockRoot(root, policy) {
   try {
     await fs.mkdir(root, { recursive: true, mode: 448 });
   } catch (err) {
@@ -31530,7 +31585,7 @@ async function ensurePrivateLockRoot(root) {
     ownerUid: stat2.uid,
     expectedUid: uid,
     mode: stat2.mode,
-    enforcePrivateMode: process.platform !== "win32"
+    enforcePrivateMode: policy.enforcePrivateMode
   })) {
     throw new FilesystemMutationLockError(
       `refusing unsafe filesystem mutation lock root '${root}'; it must be a private directory owned by this user`,
@@ -31557,50 +31612,50 @@ async function resolvedPortableRoot(portableRoot) {
   if (portableRoot === void 0) return void 0;
   return fs.realpath(portableRoot).catch(() => path.resolve(portableRoot));
 }
-async function selectLockRoot(options) {
+async function selectLockRoot(options, policy) {
   const portableRoot = await resolvedPortableRoot(options.portableRoot);
-  const lockRoot = options.lockRoot !== void 0 ? explicitFilesystemMutationLockRoot(options.lockRoot, portableRoot) : filesystemMutationLockRoot(portableRoot);
-  await ensurePrivateLockRoot(lockRoot);
+  const lockRoot = options.lockRoot !== void 0 ? explicitFilesystemMutationLockRoot(options.lockRoot, portableRoot) : filesystemMutationLockRoot(portableRoot, policy);
+  await ensurePrivateLockRoot(lockRoot, policy);
   return lockRoot;
 }
-var WINDOWS_DIRECTORY_CONTENTION_CODES = /* @__PURE__ */ new Set(["EACCES", "EBUSY", "EPERM"]);
-async function classifyLockClaimFailure(error, lockPath) {
+async function classifyLockClaimFailure(error, lockPath, policy) {
   const code2 = error.code;
   if (code2 === "EEXIST") return "contention";
-  if (process.platform !== "win32" || !WINDOWS_DIRECTORY_CONTENTION_CODES.has(code2 ?? "")) return "terminal";
+  if (!policy.isDirectoryContentionError(error)) return "terminal";
   try {
     await fs.lstat(lockPath);
     return "contention";
   } catch (probeError) {
     const probeCode = probeError.code;
-    return probeCode === "ENOENT" || probeCode === "ENOTDIR" ? "unwitnessed-windows-sharing-error" : "terminal";
+    return probeCode === "ENOENT" || probeCode === "ENOTDIR" ? "unwitnessed-contention-error" : "terminal";
   }
 }
-async function claimLockPath(lockPath, owner, waitMs, pollMs) {
+async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
   const started = owner.created_at_ms;
-  let unwitnessedWindowsRetryUsed = false;
+  let unwitnessedRetryUsed = false;
   while (true) {
     try {
       await fs.mkdir(lockPath, { mode: 448 });
     } catch (err) {
-      const failure = await classifyLockClaimFailure(err, lockPath);
+      const failure = await classifyLockClaimFailure(err, lockPath, policy);
       if (failure === "terminal") throw err;
-      if (failure === "unwitnessed-windows-sharing-error") {
-        if (unwitnessedWindowsRetryUsed) throw err;
-        unwitnessedWindowsRetryUsed = true;
+      if (failure === "unwitnessed-contention-error") {
+        if (unwitnessedRetryUsed) throw err;
+        unwitnessedRetryUsed = true;
         continue;
       } else {
-        unwitnessedWindowsRetryUsed = false;
+        unwitnessedRetryUsed = false;
       }
       let existingOwner = await readOwner(lockPath);
       if (existingOwner !== null) {
-        if (await quarantineStaleLock(lockPath, existingOwner)) continue;
+        if (await quarantineStaleLock(lockPath, existingOwner, policy)) continue;
         existingOwner = await readOwner(lockPath);
       }
       if (Date.now() - started >= waitMs) throw timeoutError(lockPath, existingOwner, owner.target);
       await delay(pollMs);
       continue;
     }
+    const claimed = await fs.lstat(lockPath, { bigint: true }).catch(() => null);
     try {
       await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
 `, {
@@ -31609,28 +31664,113 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs) {
         mode: 384
       });
     } catch (err) {
-      await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {
+      const code2 = err.code;
+      if (code2 === "EEXIST") continue;
+      await rollBackOwnClaim(lockPath, owner, claimed, waitMs, pollMs, policy).catch(() => {
       });
+      if (code2 === "ENOENT" || code2 === "ENOTDIR") continue;
       throw err;
     }
-    return async () => {
-      const current = await readOwner(lockPath);
-      if (current?.token !== owner.token) {
-        throw new FilesystemMutationLockError(
-          `refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`,
-          { lockPath, owner: current, stale: false, malformed: current === null }
-        );
+    let inFlight;
+    return () => {
+      if (inFlight) return inFlight;
+      inFlight = (async () => {
+        const started2 = Date.now();
+        const current = await resolveOwnerRecord(lockPath, started2, waitMs, pollMs);
+        if (current.state === "unreadable") throw unreadableOwnerRefusal(lockPath, current.error);
+        if (current.state !== "record" || current.owner.token !== owner.token) {
+          throw changedOwnerRefusal(lockPath, current.state === "record" ? current.owner : null);
+        }
+        await removeReleasedLock(lockPath, owner, started2, waitMs, pollMs, policy);
+      })();
+      return inFlight.finally(() => {
+        inFlight = void 0;
+      });
+    };
+  }
+}
+async function rollBackOwnClaim(lockPath, owner, claimed, waitMs, pollMs, policy) {
+  const started = Date.now();
+  const record = await resolveOwnerRecord(lockPath, started, waitMs, pollMs);
+  if (record.state === "record") {
+    if (record.owner.token === owner.token) await removeReleasedLock(lockPath, owner, started, waitMs, pollMs, policy);
+    return;
+  }
+  if (record.state === "unreadable" || !await isClaimedDirectory(lockPath, claimed)) return;
+  const remnant = releasedLockRemnantPath(lockPath, owner);
+  await fs.rename(lockPath, remnant);
+  await fs.rm(remnant, { recursive: true, force: true });
+}
+async function isClaimedDirectory(lockPath, claimed) {
+  if (claimed === null || claimed.birthtimeNs <= 0n) return false;
+  const current = await fs.lstat(lockPath, { bigint: true }).catch(() => null);
+  return current !== null && current.isDirectory() && current.dev === claimed.dev && current.ino === claimed.ino && current.birthtimeNs === claimed.birthtimeNs;
+}
+function changedOwnerRefusal(lockPath, current) {
+  return new FilesystemMutationLockError(
+    `refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`,
+    { lockPath, owner: current, stale: false, malformed: current === null }
+  );
+}
+function unreadableOwnerRefusal(lockPath, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return new FilesystemMutationLockError(
+    `refusing to release filesystem mutation lock '${lockPath}' because its owner record could not be read within the wait budget (${message}); the mutation may have completed, inspect the lock before retrying.`,
+    { lockPath, owner: null, stale: false, malformed: true }
+  );
+}
+function releasedLockRemnantPath(lockPath, owner) {
+  const tokenHash = createHash("sha256").update(owner.token).digest("hex");
+  return `${lockPath}.released-${tokenHash}`;
+}
+function removalFailure(inspectPath, owner, err, attempts, detail) {
+  const message = err instanceof Error ? err.message : String(err);
+  const suffix = attempts > 1 ? ` after ${attempts} bounded attempts` : "";
+  return new FilesystemMutationLockError(
+    `mutation completed but ${detail}${suffix} (${message}); inspect the lock before retrying.`,
+    { lockPath: inspectPath, owner, stale: false, malformed: false }
+  );
+}
+async function removeReleasedLock(lockPath, owner, started, waitMs, pollMs, policy) {
+  const remnant = releasedLockRemnantPath(lockPath, owner);
+  let attempts = 0;
+  while (true) {
+    try {
+      await fs.rename(lockPath, remnant);
+      break;
+    } catch (err) {
+      attempts += 1;
+      if (attempts > 1 && err.code === "ENOENT") return;
+      if (!policy.isDirectoryContentionError(err) || Date.now() - started >= waitMs) {
+        throw removalFailure(lockPath, owner, err, attempts, `filesystem lock '${lockPath}' could not be removed`);
       }
-      try {
-        await fs.rm(lockPath, { recursive: true, force: false });
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new FilesystemMutationLockError(
-          `mutation completed but filesystem lock '${lockPath}' could not be removed (${message}); inspect the lock before retrying.`,
-          { lockPath, owner: current, stale: false, malformed: false }
+    }
+    await delay(pollMs);
+    const current = await resolveOwnerRecord(lockPath, started, waitMs, pollMs);
+    if (current.state === "record" && current.owner.token === owner.token) continue;
+    if (current.state === "unreadable") throw unreadableOwnerRefusal(lockPath, current.error);
+    if (current.state === "absent" && !await pathExists(lockPath)) return;
+    throw changedOwnerRefusal(lockPath, current.state === "record" ? current.owner : null);
+  }
+  attempts = 0;
+  while (true) {
+    try {
+      await fs.rm(remnant, { recursive: true, force: false });
+      return;
+    } catch (err) {
+      attempts += 1;
+      if (err.code === "ENOENT") return;
+      if (!policy.isDirectoryContentionError(err) || Date.now() - started >= waitMs) {
+        throw removalFailure(
+          remnant,
+          owner,
+          err,
+          attempts,
+          `filesystem lock '${lockPath}' was released yet its remnant '${remnant}' could not be removed`
         );
       }
-    };
+    }
+    await delay(pollMs);
   }
 }
 function newOwner(target) {
@@ -31648,21 +31788,20 @@ function assertIdentityKey(key) {
 }
 async function acquireFilesystemIdentityLock(key, identity, options = {}) {
   assertIdentityKey(key);
+  const policy = captureFilesystemHostPolicy(options.hostPolicy);
   const waitMs = positiveOption(options.waitMs, DEFAULT_WAIT_MS, "waitMs");
   const pollMs = positiveOption(options.pollMs, DEFAULT_POLL_MS, "pollMs");
   const owner = newOwner(identity);
-  const lockRoot = await selectLockRoot(options);
-  return claimLockPath(path.join(lockRoot, `${key}.lock`), owner, waitMs, pollMs);
+  const lockRoot = await selectLockRoot(options, policy);
+  return claimLockPath(path.join(lockRoot, `${key}.lock`), owner, waitMs, pollMs, policy);
 }
 
 // ../core/src/filesystem-identity.ts
-var WINDOWS_REPLACE_CONFLICT_CODES = /* @__PURE__ */ new Set(["EACCES", "EBUSY", "EPERM"]);
 async function replaceExistingLeaf(port, tmp, target, rel) {
   try {
     await port.rename(tmp, target);
   } catch (err) {
-    const code2 = err.code ?? "";
-    if ((port.platform ?? process.platform) === "win32" && WINDOWS_REPLACE_CONFLICT_CODES.has(code2)) {
+    if (port.isReplacementConflict?.(err)) {
       throw new ConcurrentReplacementError(rel, 1, 10);
     }
     throw err;
@@ -31829,7 +31968,7 @@ async function observeExact(port, root, rel, read) {
       opened = await port.open(target);
     } catch (err) {
       if (isAbsentPathError(err)) return { state: "absent" };
-      if (process.platform === "win32" && err.code === "EPERM") {
+      if (port.isTransientOpenError?.(err)) {
         restarts = countRestart(restarts, rel);
         continue;
       }
@@ -31863,7 +32002,15 @@ async function probeExact(port, root, rel) {
     restarts = countRestart(restarts, rel);
   }
 }
-var linkUnsupportedRoots = /* @__PURE__ */ new Set();
+var linkUnsupportedRoots = /* @__PURE__ */ new WeakMap();
+function unsupportedLinkRoots(port) {
+  let roots = linkUnsupportedRoots.get(port);
+  if (!roots) {
+    roots = /* @__PURE__ */ new Set();
+    linkUnsupportedRoots.set(port, roots);
+  }
+  return roots;
+}
 var queues = /* @__PURE__ */ new Map();
 function enqueue(key, fn) {
   const tail = queues.get(key) ?? Promise.resolve();
@@ -31945,7 +32092,7 @@ async function createExactLeaf(port, tmp, target, rel, leaf, rootResolved) {
     return;
   }
   if (outcome === "unsupported") {
-    linkUnsupportedRoots.add(rootResolved);
+    unsupportedLinkRoots(port).add(rootResolved);
     await port.rename(tmp, target);
     return;
   }
@@ -31981,7 +32128,7 @@ async function mutateExact(port, root, rel, body) {
               await replaceExistingLeaf(port, tmp, target, rel);
               return;
             }
-            if (linkUnsupportedRoots.has(rootResolved)) {
+            if (unsupportedLinkRoots(port).has(rootResolved)) {
               await port.rename(tmp, target);
               return;
             }
@@ -32008,80 +32155,84 @@ function kindOf(stats) {
   if (stats.isFile()) return "file";
   return "other";
 }
-var nodeFilesystemIdentityPort = Object.freeze({
-  platform: process.platform,
-  async probe(target) {
-    let lstats;
-    try {
-      lstats = await fs2.lstat(target);
-    } catch (err) {
-      if (isAbsentPathError(err)) return null;
-      throw err;
-    }
-    return { kind: kindOf(lstats), dev: lstats.dev, ino: lstats.ino };
-  },
-  async entries(dir) {
-    try {
-      const dirents = await fs2.readdir(dir, { withFileTypes: true });
-      return dirents.map((dirent) => ({ name: dirent.name, kind: kindOf(dirent) }));
-    } catch (err) {
-      if (isAbsentPathError(err)) return null;
-      throw err;
-    }
-  },
-  async open(target) {
-    const handle = await fs2.open(target, "r");
-    try {
-      const stats = await handle.stat();
-      return { handle, dev: stats.dev, ino: stats.ino };
-    } catch (err) {
-      await handle.close().catch(() => {
-      });
-      throw err;
-    }
-  },
-  readAll(handle) {
-    return handle.readFile();
-  },
-  close(handle) {
-    return handle.close();
-  },
-  async stat(target) {
-    return { mtime: (await fs2.stat(target)).mtime };
-  },
-  async mkdir(dir) {
-    try {
-      await fs2.mkdir(dir);
-      return "created";
-    } catch (err) {
-      if (err.code === "EEXIST") return "exists";
-      throw err;
-    }
-  },
-  async writeTemp(dir, name, bytes) {
-    await fs2.writeFile(path2.join(dir, name), bytes);
-  },
-  async link(from, to) {
-    try {
-      await fs2.link(from, to);
-      return "linked";
-    } catch (err) {
-      const code2 = err.code;
-      if (code2 === "EEXIST") return "exists";
-      if (code2 === "EPERM" || code2 === "ENOTSUP" || code2 === "EOPNOTSUPP" || code2 === "EXDEV") return "unsupported";
-      throw err;
+function createNodeFilesystemIdentityPort(hostPolicy) {
+  const policy = captureFilesystemHostPolicy(hostPolicy);
+  return Object.freeze({
+    isTransientOpenError: policy.isTransientOpenError,
+    isReplacementConflict: policy.isReplacementConflict,
+    async probe(target) {
+      let lstats;
+      try {
+        lstats = await fs2.lstat(target);
+      } catch (err) {
+        if (isAbsentPathError(err)) return null;
+        throw err;
+      }
+      return { kind: kindOf(lstats), dev: lstats.dev, ino: lstats.ino };
+    },
+    async entries(dir) {
+      try {
+        const dirents = await fs2.readdir(dir, { withFileTypes: true });
+        return dirents.map((dirent) => ({ name: dirent.name, kind: kindOf(dirent) }));
+      } catch (err) {
+        if (isAbsentPathError(err)) return null;
+        throw err;
+      }
+    },
+    async open(target) {
+      const handle = await fs2.open(target, "r");
+      try {
+        const stats = await handle.stat();
+        return { handle, dev: stats.dev, ino: stats.ino };
+      } catch (err) {
+        await handle.close().catch(() => {
+        });
+        throw err;
+      }
+    },
+    readAll(handle) {
+      return handle.readFile();
+    },
+    close(handle) {
+      return handle.close();
+    },
+    async stat(target) {
+      return { mtime: (await fs2.stat(target)).mtime };
+    },
+    async mkdir(dir) {
+      try {
+        await fs2.mkdir(dir);
+        return "created";
+      } catch (err) {
+        if (err.code === "EEXIST") return "exists";
+        throw err;
+      }
+    },
+    async writeTemp(dir, name, bytes) {
+      await fs2.writeFile(path2.join(dir, name), bytes);
+    },
+    async link(from, to) {
+      try {
+        await fs2.link(from, to);
+        return "linked";
+      } catch (err) {
+        const code2 = err.code;
+        if (code2 === "EEXIST") return "exists";
+        if (code2 === "EPERM" || code2 === "ENOTSUP" || code2 === "EOPNOTSUPP" || code2 === "EXDEV") return "unsupported";
+        throw err;
+      }
+    },
+    async rename(from, to) {
+      await fs2.rename(from, to);
+    },
+    async unlink(target) {
+      await fs2.unlink(target);
+    },
+    claim(key, identity) {
+      return acquireFilesystemIdentityLock(key, `${identity.root}:${identity.rel}`, { portableRoot: identity.root, hostPolicy: policy });
     }
-  },
-  async rename(from, to) {
-    await fs2.rename(from, to);
-  },
-  async unlink(target) {
-    await fs2.unlink(target);
-  },
-  claim(key, identity) {
-    return acquireFilesystemIdentityLock(key, `${identity.root}:${identity.rel}`, { portableRoot: identity.root });
-  }
-});
+  });
+}
 
 // ../core/src/sha256.ts
 var K = new Uint32Array([
@@ -32240,6 +32391,9 @@ function sha256HexOfUtf8(input) {
 }
 
 // ../core/src/version-transport.ts
+function isContentVersion(value) {
+  return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
+}
 var VersionConflict = class extends Error {
   name = "VersionConflict";
   id;
@@ -32271,7 +32425,7 @@ function defaultActor() {
 }
 
 // ../core/src/backend.ts
-var publicationRoots = /* @__PURE__ */ new WeakMap();
+var publicationContexts = /* @__PURE__ */ new WeakMap();
 function firstString(...vals) {
   for (const v of vals) {
     if (typeof v === "string" && v.trim() !== "") return v;
@@ -32290,22 +32444,22 @@ function notFound(root, rel) {
   err.path = target;
   return err;
 }
-async function readBytes(handle) {
+async function readBytes(port, handle) {
   try {
-    return await nodeFilesystemIdentityPort.readAll(handle);
+    return await port.readAll(handle);
   } catch (err) {
     if (isAbsentFileError(err)) return null;
     throw err;
   }
 }
-async function walkFiles(root, keep, sub = "") {
-  const entries = await nodeFilesystemIdentityPort.entries(path3.join(root, sub)) ?? [];
+async function walkFiles(port, root, keep, sub = "") {
+  const entries = await port.entries(path3.join(root, sub)) ?? [];
   const out = [];
   for (const entry of entries) {
     if (entry.name.startsWith(".")) continue;
     const rel = sub === "" ? entry.name : `${sub}/${entry.name}`;
     if (entry.kind === "directory") {
-      out.push(...await walkFiles(root, keep, rel));
+      out.push(...await walkFiles(port, root, keep, rel));
     } else if (entry.kind === "file" && keep(entry.name)) {
       out.push(rel);
     }
@@ -32313,19 +32467,20 @@ async function walkFiles(root, keep, sub = "") {
   return out;
 }
 function reservedPath(dir, name) {
-  const d = toPosix(dir).replace(/^\.?\//, "").replace(/\/$/, "");
-  return d === "" ? name : `${d}/${name}`;
+  return dir === "" ? name : `${dir}/${name}`;
 }
 var FilesystemBackend = class _FilesystemBackend {
   #root;
+  #port;
   /**
    * The root is resolved once here: a relative root would otherwise re-resolve against the
    * process's current directory on every operation, so a later `chdir` would silently move the
    * bundle and derive a different identity key.
    */
-  constructor(root) {
+  constructor(root, options = {}) {
+    this.#port = createNodeFilesystemIdentityPort(options.hostPolicy);
     this.#root = path3.resolve(root);
-    publicationRoots.set(this, this.#root);
+    publicationContexts.set(this, { root: this.#root, port: this.#port });
   }
   async read(id) {
     return this.#readWithEdition(id, () => this.#readEdition());
@@ -32341,7 +32496,7 @@ var FilesystemBackend = class _FilesystemBackend {
   async #readWithEdition(id, edition) {
     assertSafeConceptId(id);
     const rel = pathFromConceptId(id);
-    const observed = await observeExact(nodeFilesystemIdentityPort, this.#root, rel, readBytes);
+    const observed = await observeExact(this.#port, this.#root, rel, (handle) => readBytes(this.#port, handle));
     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() });
@@ -32363,7 +32518,7 @@ var FilesystemBackend = class _FilesystemBackend {
     assertSafeConceptId(id);
     const raw = stringifyDoc(doc.frontmatter, doc.body ?? "");
     const rel = pathFromConceptId(id);
-    return mutateExact(nodeFilesystemIdentityPort, this.#root, rel, async (target) => {
+    return mutateExact(this.#port, this.#root, rel, async (target) => {
       if (options.expectedVersion !== void 0) {
         const bytes = await target.current();
         const current = bytes === null ? null : versionOfBytes(bytes.toString("utf8"));
@@ -32377,7 +32532,7 @@ var FilesystemBackend = class _FilesystemBackend {
   }
   async delete(id, options = {}) {
     assertSafeConceptId(id);
-    return mutateExact(nodeFilesystemIdentityPort, this.#root, pathFromConceptId(id), async (target) => {
+    return mutateExact(this.#port, this.#root, pathFromConceptId(id), async (target) => {
       const bytes = await target.current();
       if (bytes === null) return false;
       const current = versionOfBytes(bytes.toString("utf8"));
@@ -32391,10 +32546,10 @@ var FilesystemBackend = class _FilesystemBackend {
   async versions(id) {
     assertSafeConceptId(id);
     const rel = pathFromConceptId(id);
-    const observed = await observeExact(nodeFilesystemIdentityPort, this.#root, rel, async (handle, target) => {
+    const observed = await observeExact(this.#port, this.#root, rel, async (handle, target) => {
       try {
-        const bytes = await nodeFilesystemIdentityPort.readAll(handle);
-        const { mtime: mtime2 } = await nodeFilesystemIdentityPort.stat(target);
+        const bytes = await this.#port.readAll(handle);
+        const { mtime: mtime2 } = await this.#port.stat(target);
         return { raw: bytes.toString("utf8"), mtime: mtime2 };
       } catch {
         return null;
@@ -32409,10 +32564,10 @@ var FilesystemBackend = class _FilesystemBackend {
   }
   async exists(id) {
     assertSafeConceptId(id);
-    return (await probeExact(nodeFilesystemIdentityPort, this.#root, pathFromConceptId(id))).state === "exact";
+    return (await probeExact(this.#port, this.#root, pathFromConceptId(id))).state === "exact";
   }
   async list(prefix) {
-    const files = await walkFiles(this.#root, (name) => name.endsWith(".md"));
+    const files = await walkFiles(this.#port, this.#root, (name) => name.endsWith(".md"));
     const ids = [];
     for (const rel of files) {
       if (isReservedFile(rel)) continue;
@@ -32426,20 +32581,22 @@ var FilesystemBackend = class _FilesystemBackend {
       if (prefix && !id.startsWith(prefix)) continue;
       ids.push(id);
     }
-    ids.sort((a, b) => a.localeCompare(b));
+    ids.sort(compareStorageKeys);
     return ids;
   }
   async readReserved(dir, name) {
     assertSafeReservedDir(dir);
-    const observed = await observeExact(nodeFilesystemIdentityPort, this.#root, reservedPath(dir, name), readBytes);
+    assertSafeReservedFilename(name);
+    const observed = await observeExact(this.#port, this.#root, reservedPath(dir, name), (handle) => readBytes(this.#port, handle));
     if (observed.state === "absent") return null;
     const content3 = observed.value.toString("utf8");
     return { content: content3, version: versionOfBytes(content3) };
   }
   async writeReserved(dir, name, content3, options = {}) {
     assertSafeReservedDir(dir);
+    assertSafeReservedFilename(name);
     const rel = reservedPath(dir, name);
-    return mutateExact(nodeFilesystemIdentityPort, this.#root, rel, async (target) => {
+    return mutateExact(this.#port, this.#root, rel, async (target) => {
       if (options.expectedVersion !== void 0) {
         const bytes = await target.current();
         const current = bytes === null ? null : versionOfBytes(bytes.toString("utf8"));
@@ -32454,14 +32611,14 @@ var FilesystemBackend = class _FilesystemBackend {
   // ── blobs: opaque bytes + a content-type ──────────────────────────────────
   async readBlob(key) {
     assertSafeBlobKey(key);
-    const observed = await observeExact(nodeFilesystemIdentityPort, this.#root, key, readBytes);
+    const observed = await observeExact(this.#port, this.#root, key, (handle) => readBytes(this.#port, handle));
     if (observed.state === "absent") return null;
     const bytes = observed.value;
     return { bytes, contentType: resolveContentType(key), version: blobVersion(bytes) };
   }
   async writeBlob(key, bytes, _contentType, options = {}) {
     assertSafeBlobKey(key);
-    return mutateExact(nodeFilesystemIdentityPort, this.#root, key, async (target) => {
+    return mutateExact(this.#port, this.#root, key, async (target) => {
       if (options.expectedVersion !== void 0) {
         const existing = await target.current();
         const current = existing === null ? null : blobVersion(existing);
@@ -32475,7 +32632,7 @@ var FilesystemBackend = class _FilesystemBackend {
   }
   async deleteBlob(key, options = {}) {
     assertSafeBlobKey(key);
-    return mutateExact(nodeFilesystemIdentityPort, this.#root, key, async (target) => {
+    return mutateExact(this.#port, this.#root, key, async (target) => {
       const existing = await target.current();
       if (existing === null) return false;
       const current = blobVersion(existing);
@@ -32488,14 +32645,14 @@ var FilesystemBackend = class _FilesystemBackend {
   }
   async existsBlob(key) {
     assertSafeBlobKey(key);
-    const observed = await probeExact(nodeFilesystemIdentityPort, this.#root, key);
+    const observed = await probeExact(this.#port, this.#root, key);
     return observed.state === "exact" && observed.value.kind === "file";
   }
   async listBlobs(prefix) {
-    const files = await walkFiles(this.#root, (name) => !name.toLowerCase().endsWith(".md"));
+    const files = await walkFiles(this.#port, this.#root, (name) => !name.toLowerCase().endsWith(".md"));
     const keys = files.map(toPosix);
     const filtered = prefix ? keys.filter((k) => k.startsWith(prefix)) : keys;
-    filtered.sort((a, b) => a.localeCompare(b));
+    filtered.sort(compareStorageKeys);
     return filtered;
   }
   capabilities() {
@@ -32508,24 +32665,25 @@ var FilesystemBackend = class _FilesystemBackend {
     };
   }
 };
-function publicationRoot(backend) {
-  const root = publicationRoots.get(backend);
-  if (!root) throw new InvalidInputError("Unknown filesystem backend publication source.");
-  return root;
+function publicationContext(backend) {
+  const context = publicationContexts.get(backend);
+  if (!context) throw new InvalidInputError("Unknown filesystem backend publication source.");
+  return context;
 }
 async function readRawFilesystemDocument(backend, id) {
   assertSafeConceptId(id);
-  const root = publicationRoot(backend);
+  const { root, port } = publicationContext(backend);
   const rel = pathFromConceptId(id);
-  const observed = await observeExact(nodeFilesystemIdentityPort, root, rel, readBytes);
+  const observed = await observeExact(port, root, rel, (handle) => readBytes(port, handle));
   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) };
 }
 async function readRawFilesystemReserved(backend, dir, name) {
   assertSafeReservedDir(dir);
-  const root = publicationRoot(backend);
-  const observed = await observeExact(nodeFilesystemIdentityPort, root, reservedPath(dir, name), readBytes);
+  assertSafeReservedFilename(name);
+  const { root, port } = publicationContext(backend);
+  const observed = await observeExact(port, root, reservedPath(dir, name), (handle) => readBytes(port, handle));
   if (observed.state === "absent") return null;
   return {
     bytes: observed.value.slice(),
@@ -32533,15 +32691,16 @@ async function readRawFilesystemReserved(backend, dir, name) {
   };
 }
 async function listFilesystemReservedObjects(backend) {
-  const root = publicationRoot(backend);
-  const files = await walkFiles(root, (name) => name === "index.md" || name === "log.md");
+  const { root, port } = publicationContext(backend);
+  const files = await walkFiles(port, root, (name) => name === "index.md" || name === "log.md");
   return files.map((relative) => {
     const slash = relative.lastIndexOf("/");
     const dir = slash === -1 ? "" : relative.slice(0, slash);
     const name = relative.slice(slash + 1);
     assertSafeReservedDir(dir);
+    assertSafeReservedFilename(name);
     return { dir, name };
-  }).sort((a, b) => reservedPath(a.dir, a.name).localeCompare(reservedPath(b.dir, b.name)));
+  }).sort((a, b) => compareStorageKeys(reservedPath(a.dir, a.name), reservedPath(b.dir, b.name)));
 }
 
 // ../core/src/bundle-ops.ts
@@ -32581,7 +32740,7 @@ setDefaultBackendFactory((root) => new FilesystemBackend(root));
 var CONVENTIONS_PREFIX = "conventions/";
 var CONVENTION_TYPE = "Convention";
 function buildKindRegistry(docs, initialWarnings = [], options = {}) {
-  const kinds = /* @__PURE__ */ new Map();
+  const accepted = /* @__PURE__ */ new Map();
   const warnings = [...initialWarnings];
   for (const doc of [...docs].sort((a, b) => a.id.localeCompare(b.id))) {
     const parsed = parseConventionDoc(doc, options);
@@ -32604,10 +32763,10 @@ function buildKindRegistry(docs, initialWarnings = [], options = {}) {
         severity: "warning"
       });
     }
-    if (kinds.has(kind.governs)) {
+    if (accepted.has(kind.governs)) {
       warnings.push({
         code: "KIND_DUPLICATE_GOVERNS",
-        message: `duplicate kind convention for '${kind.governs}': '${doc.id}' ignored, keeping the first-declared '${kinds.get(kind.governs).id}'.`,
+        message: `duplicate kind convention for '${kind.governs}': '${doc.id}' ignored, keeping the first-declared '${accepted.get(kind.governs).id}'.`,
         field: kind.governs,
         severity: "warning"
       });
@@ -32621,10 +32780,18 @@ function buildKindRegistry(docs, initialWarnings = [], options = {}) {
         severity: "warning"
       });
     }
-    kinds.set(kind.governs, kind);
+    accepted.set(kind.governs, kind);
   }
+  const kinds = /* @__PURE__ */ new Map();
+  for (const kind of [...accepted.values()].sort(compareReadingOrder)) kinds.set(kind.governs, kind);
   return { kinds, warnings };
 }
+function compareReadingOrder(a, b) {
+  if (a.order !== void 0 && b.order !== void 0 && a.order !== b.order) return a.order - b.order;
+  if (a.order !== void 0 && b.order === void 0) return -1;
+  if (a.order === void 0 && b.order !== void 0) return 1;
+  return a.id.localeCompare(b.id);
+}
 var PROGRESS_STATUS_FIELD = "progress_status";
 var SUPERBEE_PROGRESS_STATUS_FIELD = "superbee_progress_status";
 function progressStatusStorageField(okfVersion) {
@@ -33093,6 +33260,19 @@ function parseConventionDoc(doc, options = {}) {
   const path6 = typeof fm.path === "string" && fm.path.trim() !== "" ? fm.path.trim() : void 0;
   const freshnessHorizon = typeof fm.freshness_horizon === "string" && fm.freshness_horizon.trim() !== "" ? fm.freshness_horizon.trim() : void 0;
   const browseCollapsed = fm.browse_collapsed === true ? true : void 0;
+  let order;
+  if (fm.order !== void 0) {
+    if (typeof fm.order === "number" && Number.isFinite(fm.order)) {
+      order = fm.order;
+    } else {
+      warnings.push({
+        code: "KIND_CONVENTION_BAD_SHAPE",
+        message: `kind convention '${doc.id}' has an invalid 'order' (${describeShape(fm.order)}; expected a finite number such as 10); ignoring it.`,
+        field: "order",
+        severity: "warning"
+      });
+    }
+  }
   const kind = {
     id: doc.id,
     title,
@@ -33107,6 +33287,7 @@ function parseConventionDoc(doc, options = {}) {
   if (sections && sections.length > 0) kind.sections = sections;
   if (freshnessHorizon !== void 0) kind.freshnessHorizon = freshnessHorizon;
   if (browseCollapsed !== void 0) kind.browseCollapsed = browseCollapsed;
+  if (order !== void 0) kind.order = order;
   if (claim !== void 0) kind.claim = claim;
   return {
     ok: true,
@@ -33257,7 +33438,7 @@ function isAnyEntryKey(entry) {
   return isPageEntryKey(entry) || isViewEntryKey(entry);
 }
 function isViewEntryVersion(value) {
-  return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
+  return isContentVersion(value);
 }
 function parseRegistration(id, frontmatter2) {
   if (!isAnyRegistryId(id) || !isPageTypeName(frontmatter2.type) || !isAnyEntryKey(frontmatter2.entry)) return null;
@@ -42193,6 +42374,35 @@ function isBareLinkBlock(node2, fromId) {
 function safeLanguageClass(lang) {
   return typeof lang === "string" && /^[\w+-]{1,24}$/.test(lang) ? `doc-code-${lang}` : void 0;
 }
+function isIpLiteralHost(hostname2) {
+  return hostname2.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname2);
+}
+function normalizeAllowedHost(entry) {
+  if (typeof entry !== "string" || entry === "" || /[\s/?#@:\\]/.test(entry)) return null;
+  let url;
+  try {
+    url = new URL(`https://${entry}/`);
+  } catch {
+    return null;
+  }
+  if (url.href !== `https://${url.hostname}/` || isIpLiteralHost(url.hostname)) return null;
+  return url.hostname;
+}
+function admitExternalLink(raw, hosts) {
+  if (!Array.isArray(hosts) || hosts.length === 0) return null;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "") return null;
+  if (isIpLiteralHost(url.hostname)) return null;
+  for (const entry of hosts) {
+    if (normalizeAllowedHost(entry) === url.hostname) return url.href;
+  }
+  return null;
+}
 function documentHref(id, options) {
   const href = options.hrefForDoc?.(id) ?? `?view=doc&id=${encodeURIComponent(id)}`;
   const base = "https://renderer.invalid/";
@@ -42267,9 +42477,14 @@ function renderNode(node2, state, depth, index2) {
     case "break":
       return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("br", {}, index2);
     case "link": {
-      const resolved = resolveConceptId(state.options.fromId, node2.url ?? "");
+      const raw = node2.url ?? "";
+      const resolved = resolveConceptId(state.options.fromId, raw);
       const children = renderChildren(node2, state, depth);
       if (resolved === null) {
+        const external = admitExternalLink(raw, state.options.externalLinkHosts);
+        if (external !== null) {
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", { href: external, rel: "noopener noreferrer", target: "_blank", className: "doc-link-external", children }, index2);
+        }
         return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
           "span",
           {
@@ -42413,8 +42628,11 @@ function renderMarkdownToStaticHtml(body, options) {
   );
   return { html, bounded: rendered.bounded, limits: rendered.limits };
 }
-function renderDocumentToStaticHtml(document3) {
-  const rendered = renderMarkdownToStaticHtml(document3.body, { fromId: document3.id });
+function renderDocumentToStaticHtml(document3, options = {}) {
+  const rendered = renderMarkdownToStaticHtml(document3.body, {
+    fromId: document3.id,
+    externalLinkHosts: options.externalLinkHosts
+  });
   return { html: rendered.html, bounded: rendered.bounded };
 }
 
@@ -42447,9 +42665,45 @@ var MAX_QUERY_ROWS = 500;
 var MAX_EDGE_ROWS = 1e3;
 var MAX_DOCUMENT_BODY_BYTES = 1024 * 1024;
 var MAX_REPLY_BYTES = 2 * 1024 * 1024;
+var GRAPH_MAX_DOCUMENTS = 1e3;
+var GRAPH_MAX_RELATIONSHIPS = 1e4;
 var MAX_CHANGE_ROWS = 100;
 var MAX_CHANGE_BYTES = 256 * 1024;
 var MAX_SUBSCRIPTION_HEADS = 1e4;
+var MAX_HOST_CAPABILITY_BYTES = 128;
+var MAX_HOST_REQUEST_BYTES = 64 * 1024;
+var HOST_CAPABILITY_NAME = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+var BRIDGE_SERVICE_LIMITS = Object.freeze({
+  query: MAX_QUERY_ROWS,
+  edges: MAX_EDGE_ROWS,
+  graphDocuments: GRAPH_MAX_DOCUMENTS,
+  graphRelationships: GRAPH_MAX_RELATIONSHIPS,
+  replyBytes: MAX_REPLY_BYTES
+});
+var BRIDGE_HOST_CAPABILITIES = Object.freeze({
+  queryKindProjection: "query.kind-projection",
+  queryFieldOr: "query.field-or",
+  queryOpen: "query.open",
+  queryCount: "query.count",
+  edges: "edges",
+  renderDocument: "render-document",
+  openPage: "open-page",
+  subscribeDeltas: "subscribe-deltas",
+  graph: "graph",
+  graphModel: "graph.model",
+  recordOpen: "record.open",
+  frameResize: "frame.resize"
+});
+var BRIDGE_SERVICE_CAPABILITIES = Object.freeze([
+  BRIDGE_HOST_CAPABILITIES.queryKindProjection,
+  BRIDGE_HOST_CAPABILITIES.queryFieldOr,
+  BRIDGE_HOST_CAPABILITIES.queryOpen,
+  BRIDGE_HOST_CAPABILITIES.queryCount,
+  BRIDGE_HOST_CAPABILITIES.edges,
+  BRIDGE_HOST_CAPABILITIES.graph,
+  BRIDGE_HOST_CAPABILITIES.renderDocument
+]);
+var V0_REQUEST_TYPES = /* @__PURE__ */ new Set(["hello", "query", "read", "render-document", "edges", "graph", "subscribe", "host", "open-page"]);
 function isPlainRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
   const prototype = Object.getPrototypeOf(value);
@@ -42582,6 +42836,45 @@ function parseBridgeRequest(value) {
     const params = normalizeEdgeParams(value.params);
     return params ? { bridge: BRIDGE_PROTOCOL, type: "edges", id, params } : null;
   }
+  if (value.type === "graph") {
+    const expected = value.includeBodies === void 0 ? ["bridge", "type", "id"] : ["bridge", "type", "id", "includeBodies"];
+    if (!exactKeys(value, expected)) return null;
+    if (value.includeBodies !== void 0 && typeof value.includeBodies !== "boolean") return null;
+    return { bridge: BRIDGE_PROTOCOL, type: "graph", id, includeBodies: value.includeBodies === true };
+  }
+  if (value.type === "host") {
+    const expected = value.input === void 0 ? ["bridge", "type", "id", "capability"] : ["bridge", "type", "id", "capability", "input"];
+    if (!exactKeys(value, expected)) return null;
+    const capability = boundedString(value.capability, MAX_HOST_CAPABILITY_BYTES);
+    if (!capability || !HOST_CAPABILITY_NAME.test(capability)) return null;
+    if (value.input !== void 0 && !isPlainRecord(value.input)) return null;
+    let bytes;
+    try {
+      bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+    } catch {
+      return null;
+    }
+    if (bytes > MAX_HOST_REQUEST_BYTES) return null;
+    return {
+      bridge: BRIDGE_PROTOCOL,
+      type: "host",
+      id,
+      capability,
+      ...value.input === void 0 ? {} : { input: value.input }
+    };
+  }
+  return null;
+}
+function unsupportedRequest(value) {
+  if (!isPlainRecord(value) || typeof value.type !== "string") return null;
+  if (value.bridge === BRIDGE_PROTOCOL) {
+    return V0_REQUEST_TYPES.has(value.type) ? null : { bridge: BRIDGE_PROTOCOL, id: requestId(value.id) ?? void 0 };
+  }
+  if (value.bridge === ACTION_BRIDGE_PROTOCOL) {
+    if (value.type === "read-versioned") return null;
+    const id = value.type === "action.propose" ? value.requestId : value.id;
+    return { bridge: ACTION_BRIDGE_PROTOCOL, id: requestId(id) ?? void 0 };
+  }
   return null;
 }
 function ok3(id, bridge, type, result) {
@@ -42606,6 +42899,17 @@ var BridgeService = class {
   async handle(launchId, rawRequest) {
     const request = parseBridgeRequest(rawRequest);
     if (!request) {
+      const unsupported = unsupportedRequest(rawRequest);
+      if (unsupported) {
+        return {
+          reply: fail(
+            unsupported.id,
+            unsupported.bridge,
+            "FORBIDDEN",
+            "this host does not offer the requested bridge operation"
+          )
+        };
+      }
       return {
         reply: fail(
           invalidV0RequestId(rawRequest),
@@ -42615,16 +42919,6 @@ var BridgeService = class {
         )
       };
     }
-    if (request.bridge === ACTION_BRIDGE_PROTOCOL && this.options.allowActionProtocol === false) {
-      return {
-        reply: fail(
-          request.id,
-          request.bridge,
-          "FORBIDDEN",
-          "this host admits only the read-only v0 View bridge"
-        )
-      };
-    }
     const dataBearing = request.type !== "open-page";
     const before = await this.options.launches.resolve(launchId, dataBearing);
     if (!before) {
@@ -42730,6 +43024,73 @@ var BridgeService = class {
       [...rows].sort((a, b) => a.id.localeCompare(b.id)).map((row) => [row.id, row.version])
     );
   }
+  /**
+   * Whole-bundle projection for graph-shaped Views. The documents come from one head scan and
+   * the relationships from `queryEdges`, which is a second full-bundle scan; the two scans are
+   * accepted because the reply is bounded by the exported graph limits and the host never
+   * caches bundle state on a View's behalf. No `model` or `definitions` are answered here: the
+   * owner of that shape is undecided, and a host that has one declares the `graph.model`
+   * capability before adding them.
+   */
+  async graph(launch, request) {
+    const heads = await queryHeads2(this.options.bundle, {});
+    if (heads.length > GRAPH_MAX_DOCUMENTS) {
+      return {
+        reply: fail(request.id, request.bridge, "TOO_LARGE", `the graph exceeded ${GRAPH_MAX_DOCUMENTS} documents`)
+      };
+    }
+    const [registry, declaredOkfVersion, edges] = await Promise.all([
+      loadKinds(this.options.bundle),
+      readBundleOkfVersion2(this.options.bundle),
+      queryEdges2(this.options.bundle, {})
+    ]);
+    if (edges.length > GRAPH_MAX_RELATIONSHIPS) {
+      return {
+        reply: fail(request.id, request.bridge, "TOO_LARGE", `the graph exceeded ${GRAPH_MAX_RELATIONSHIPS} relationships`)
+      };
+    }
+    const okfVersion = declaredOkfVersion ?? "0.1";
+    const includeBodies = request.includeBodies && (launch.capability === "bundle-read" || launch.capability === "bundle-propose");
+    const documents = [];
+    for (const head of heads) {
+      const source = includeBodies ? await readDocVersioned2(this.options.bundle, head.id).then((result) => ({
+        version: result.version,
+        frontmatter: result.doc.frontmatter,
+        body: result.doc.body
+      })) : { version: head.version, frontmatter: head.frontmatter };
+      if (source.body !== void 0 && Buffer.byteLength(source.body, "utf8") > MAX_DOCUMENT_BODY_BYTES) {
+        return { reply: fail(request.id, request.bridge, "TOO_LARGE", "a document body exceeded the 1 MiB View limit") };
+      }
+      const kind = registry.kinds.get(String(source.frontmatter.type ?? ""));
+      const frontmatter2 = kind ? projectLogicalKindFields(okfVersion, kind, source.frontmatter) : source.frontmatter;
+      documents.push({
+        id: head.id,
+        version: source.version,
+        frontmatter: frontmatter2,
+        ...source.body === void 0 ? {} : { body: source.body }
+      });
+    }
+    const relationships = edges.map(({ from, to, text: text4 }) => ({ from, to, text: text4 }));
+    return {
+      reply: ok3(request.id, request.bridge, request.type, {
+        okfVersion,
+        documents,
+        relationships,
+        counts: { documents: documents.length, relationships: relationships.length }
+      })
+    };
+  }
+  hostDescriptor() {
+    const declared = new Set(this.options.host.capabilities);
+    for (const name of Object.keys(this.options.hostHandlers ?? {})) declared.add(name);
+    return {
+      kind: this.options.host.kind,
+      capabilities: [...declared].sort(),
+      limits: { ...this.options.host.limits },
+      ...this.options.host.frame ? { frame: { ...this.options.host.frame } } : {},
+      ...this.options.host.theme ? { theme: { ...this.options.host.theme } } : {}
+    };
+  }
   async execute(launch, request) {
     if (request.type === "open-page") {
       if (this.options.consumeOpenPage === true) {
@@ -42753,10 +43114,25 @@ var BridgeService = class {
           bundle: { root: config.root, name: config.name },
           mode: config.mode,
           protocol: BRIDGE_PROTOCOL,
-          grant: launch.capability === "bundle-propose" ? "propose" : "read"
+          grant: launch.capability === "bundle-propose" ? "propose" : "read",
+          ...config.mode === "dir" && this.options.host.kind === "oss" && launch.capability === "bundle-propose" ? { actionProtocol: "v1", actions: ["document.set-field", "document.set-body", "document.update"] } : {},
+          host: this.hostDescriptor()
         })
       };
     }
+    if (request.type === "host") {
+      const handlers = this.options.hostHandlers ?? {};
+      if (!Object.hasOwn(handlers, request.capability)) {
+        return { reply: fail(request.id, request.bridge, "FORBIDDEN", "this host does not offer the requested capability") };
+      }
+      const outcome = await handlers[request.capability]({
+        capability: request.capability,
+        input: request.input,
+        launch
+      });
+      if (!outcome.ok) return { reply: fail(request.id, request.bridge, outcome.code, outcome.message) };
+      return { reply: ok3(request.id, request.bridge, request.type, { capability: request.capability, output: outcome.output }) };
+    }
     if (request.type === "query") {
       const rows = await queryHeads2(this.options.bundle, {
         ...request.params.type ? { type: request.params.type } : {},
@@ -42834,6 +43210,9 @@ var BridgeService = class {
       const projected = edges.map(({ from, to, text: text4 }) => ({ from, to, text: text4 }));
       return { reply: ok3(request.id, request.bridge, request.type, { edges: projected, count: projected.length }) };
     }
+    if (request.type === "graph") {
+      return this.graph(launch, request);
+    }
     if (this.options.enablePolling) {
       this.subscriptions.set(launch.launchId, {
         baseline: await this.subscriptionSnapshot()
@@ -43291,7 +43670,7 @@ function buildSnapshot(first) {
   const snapshotDigest = sha256(utf8(canonicalJson(withoutDigest)));
   return new SnapshotHandle({ ...withoutDigest, snapshotDigest }, objects);
 }
-async function capturePublicationSnapshot(options) {
+async function capturePublicationSnapshot(options, runtimeOptions = {}) {
   if (options.schema !== PUBLICATION_SNAPSHOT_V1) {
     throw new PublicationError("CAPABILITY_UNAVAILABLE", "the requested publication snapshot schema is unsupported");
   }
@@ -43302,6 +43681,7 @@ async function capturePublicationSnapshot(options) {
     throw new PublicationError("INVALID_OBJECT_IDENTITY", "the filesystem publication root must be absolute");
   }
   const requestedRoot = path5.resolve(options.source.root);
+  const backend = new FilesystemBackend(requestedRoot, { hostPolicy: runtimeOptions.filesystemHostPolicy });
   let rootIdentity;
   try {
     rootIdentity = await authorizePublicationRoot(requestedRoot);
@@ -43324,7 +43704,6 @@ async function capturePublicationSnapshot(options) {
     }
   }
   const maxAttempts = options.maxAttempts ?? 2;
-  const backend = new FilesystemBackend(root);
   let lastError;
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
     let handle;
@@ -43466,6 +43845,10 @@ var STATIC_LAUNCH_ID = "publication-snapshot";
 function digest(bytes) {
   return `sha256:${createHash4("sha256").update(bytes).digest("hex")}`;
 }
+var STATIC_BRIDGE_CAPABILITIES = Object.freeze([
+  ...BRIDGE_SERVICE_CAPABILITIES,
+  BRIDGE_HOST_CAPABILITIES.openPage
+]);
 function createPublicationBridge(options) {
   if (options.protocol !== PUBLICATION_BRIDGE_V0) {
     throw new PublicationError("CAPABILITY_UNAVAILABLE", "the requested publication bridge protocol is unsupported");
@@ -43513,7 +43896,11 @@ function createPublicationBridge(options) {
           if (!rendered || rendered.id !== id) throw new Error(`document '${id}' is not available`);
           return { html: rendered.html, bounded: rendered.bounded };
         },
-        allowActionProtocol: false,
+        host: {
+          kind: options.host?.kind ?? "oss",
+          capabilities: options.host?.capabilities ?? STATIC_BRIDGE_CAPABILITIES,
+          limits: BRIDGE_SERVICE_LIMITS
+        },
         enablePolling: false,
         consumeOpenPage: false
       });