@superbee/core 0.1.0

package/dist/page.js

@@ -0,0 +1,151 @@
+/**
+ * Pure View registry/entry path grammar shared by every producer and consumer.
+ *
+ * `View` is the ONLY accepted kind name: the legacy `Page` spelling is no longer read
+ * (the repo's `migrate-legacy-view-names` script renames legacy content in place). Registry ids
+ * are concept ids under `views-registry/` (legacy `pages-registry/` LOCATIONS stay recognized;
+ * relocation is a separate open decision); entries are opaque blob keys under
+ * `views/` (legacy `pages/`). Both retain exact, case-preserving nested paths while
+ * rejecting spellings that discovery or storage cannot safely round-trip. ONE segment
+ * grammar, parameterized by prefix — never a parallel module per name.
+ */
+import { assertSafeBlobKey, assertSafeConceptId } from "./paths.js";
+/** Legacy registry-id prefix — the LOCATION stays recognized (only the legacy kind NAME is retired). */
+export const PAGE_REGISTRY_PREFIX = "pages-registry/";
+/** Legacy blob-key prefix for View entries — the LOCATION stays recognized. */
+export const PAGE_ENTRY_PREFIX = "pages/";
+/** Current registry-id prefix for `type: View` docs. */
+export const VIEW_REGISTRY_PREFIX = "views-registry/";
+/** Current blob-key prefix for View entries. */
+export const VIEW_ENTRY_PREFIX = "views/";
+/**
+ * The kind names the launcher/registry surfaces accept: exactly `View`. Exact, case-sensitive
+ * match. The legacy `Page` name is deliberately NOT here — a Page-typed doc no longer registers
+ * anywhere (the CLI's `status` legacy_naming finding is the loud diagnostic for leftover stock,
+ * and `migrate-legacy-view-names` is the remedy).
+ */
+export const PAGE_TYPE_NAMES = ["View"];
+/** One capability resolver shared by registry parsing and the loopback server's security gates. */
+export function resolveBridgeCapability(value) {
+    return value === "bundle-read" || value === "bundle-propose" ? value : "none";
+}
+/**
+ * THE one reader of the registry-doc capability FIELD: `access`, and ONLY `access`. The legacy
+ * `bridge` spelling is no longer read — a doc declaring only `bridge` resolves to `undefined`
+ * here and fails closed to `none` downstream (the `migrate-legacy-view-names` script renames
+ * existing stock in place; the CLI's `status` legacy_naming finding flags leftover `bridge`
+ * fields loudly).
+ */
+export function declaredAccessValue(frontmatter) {
+    // Own-property-gated: an INHERITED field (a crafted prototype, or a polluted
+    // Object.prototype) must never grant capability — only a field the doc itself declares counts.
+    return Object.hasOwn(frontmatter, "access") ? frontmatter.access : undefined;
+}
+/** Resolve a registry doc's declared capability: {@link declaredAccessValue} through the fail-closed {@link resolveBridgeCapability} — an absent or unrecognized `access` yields `none`. */
+export function resolveDeclaredAccess(frontmatter) {
+    return resolveBridgeCapability(declaredAccessValue(frontmatter));
+}
+/** True iff `value` is exactly the accepted kind name (`View`). The legacy `Page` name is rejected. */
+export function isPageTypeName(value) {
+    return value === "View";
+}
+const PAGE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+/**
+ * `.md` (checked case-insensitively) is rejected on EVERY segment, not just the last: a mid-path
+ * segment like `x.md` in `pages-registry/x.md/y` would create an on-disk DIRECTORY literally named
+ * `x.md`, blocking a future concept-doc write to id `pages-registry/x` (the exact
+ * doc/dir collision {@link assertSafeBlobKey} already documents on the entry-key side). ONE
+ * shared check for both the registry-id and
+ * entry-key grammars, so the two paths can't drift again the way they did before this fix (the
+ * entry-key side already inherited this via `assertSafeBlobKey`; the registry-id side did not).
+ */
+function hasSafePageSegments(value, prefix) {
+    if (!value.startsWith(prefix) || value.length === prefix.length)
+        return false;
+    if (value.startsWith("/") || /[\\%?#]/.test(value))
+        return false;
+    const segments = value.slice(prefix.length).split("/");
+    return segments.every((segment) => !segment.startsWith(".") && PAGE_SEGMENT.test(segment) && !segment.toLowerCase().endsWith(".md"));
+}
+function isRegistryIdUnder(id, prefix) {
+    if (typeof id !== "string" || !hasSafePageSegments(id, prefix)) {
+        return false;
+    }
+    try {
+        assertSafeConceptId(id);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isEntryKeyUnder(entry, prefix) {
+    if (typeof entry !== "string" || !hasSafePageSegments(entry, prefix))
+        return false;
+    try {
+        assertSafeBlobKey(entry);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Strict concept-id grammar for registry documents at the legacy LOCATION (`pages-registry/…`). Nested ids and ordinary dots are valid. */
+export function isPageRegistryId(id) {
+    return isRegistryIdUnder(id, PAGE_REGISTRY_PREFIX);
+}
+/** Strict concept-id grammar for View registry documents (`views-registry/…`) — the SAME segment rules as {@link isPageRegistryId}. */
+export function isViewRegistryId(id) {
+    return isRegistryIdUnder(id, VIEW_REGISTRY_PREFIX);
+}
+/** True iff `id` is a valid registry id under EITHER accepted prefix (`views-registry/` or legacy `pages-registry/`). */
+export function isAnyRegistryId(id) {
+    return isPageRegistryId(id) || isViewRegistryId(id);
+}
+/** Strict blob-key grammar for executable View entries at the legacy LOCATION (`pages/…`). */
+export function isPageEntryKey(entry) {
+    return isEntryKeyUnder(entry, PAGE_ENTRY_PREFIX);
+}
+/** Strict blob-key grammar for executable View entries (`views/…`) — the SAME segment rules as {@link isPageEntryKey}. */
+export function isViewEntryKey(entry) {
+    return isEntryKeyUnder(entry, VIEW_ENTRY_PREFIX);
+}
+/** True iff `entry` is a valid entry key under EITHER accepted prefix (`views/` or legacy `pages/`). */
+export function isAnyEntryKey(entry) {
+    return isPageEntryKey(entry) || isViewEntryKey(entry);
+}
+/** True only for the content-addressed version tokens allowed to pin executable View bytes. */
+export function isViewEntryVersion(value) {
+    return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
+}
+/**
+ * THE one registration predicate: a doc is a usable View registration iff its id satisfies
+ * an accepted registry-id grammar ({@link isAnyRegistryId}), its `type` is exactly an accepted
+ * kind name ({@link isPageTypeName}), AND its `entry` satisfies an accepted entry-key grammar
+ * ({@link isAnyEntryKey}). An explicitly declared `entry_version` must be a canonical
+ * content-addressed token. Returns the validated registration, or `null`.
+ *
+ * This is a SECURITY boundary shared by every surface that decides what counts as a registered
+ * page — the launcher/`open-page` parse (ui `parseRegisteredPage`), the `ui` command's
+ * nonce-mint allowlist, and its serve-time re-verification. All of them MUST consume this one
+ * function: a doc any surface rejects must be un-mintable and un-servable everywhere, never
+ * "rejected by the launcher but still served by the nonce route".
+ */
+export function parseRegistration(id, frontmatter) {
+    if (!isAnyRegistryId(id) || !isPageTypeName(frontmatter.type) || !isAnyEntryKey(frontmatter.entry))
+        return null;
+    const rawEntryVersion = Object.hasOwn(frontmatter, "entry_version")
+        ? frontmatter.entry_version
+        : undefined;
+    if (rawEntryVersion !== undefined &&
+        !isViewEntryVersion(rawEntryVersion)) {
+        return null;
+    }
+    return {
+        id,
+        type: frontmatter.type,
+        entry: frontmatter.entry,
+        ...(rawEntryVersion ? { entryVersion: rawEntryVersion } : {}),
+    };
+}
+//# sourceMappingURL=page.js.map

package/dist/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"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"}

package/dist/paths.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Pure path helpers for OKF concept identity and reserved-file handling.
+ *
+ * A *Concept ID* is a bundle-relative path with the trailing `.md` removed
+ * (`tables/users.md` -> `tables/users`); IDs use forward slashes. Two filenames
+ * are RESERVED at any directory level — `index.md` (§6) and `log.md` (§7) — and
+ * are NOT concept documents (they carry no `type` and are excluded from queries).
+ *
+ * Everything here is pure and dependency-free, hence directly unit-testable.
+ */
+import type { ConceptId } from "./types.js";
+/** The two OKF reserved filenames, valid at any directory level (§3.1). */
+export declare const RESERVED_FILENAMES: readonly ["index.md", "log.md"];
+/** Normalize any separators to forward slashes and collapse duplicate slashes. */
+export declare function toPosix(p: string): string;
+/**
+ * True when the bundle-relative path's final segment is a reserved OKF filename
+ * (`index.md` / `log.md`) at ANY directory level.
+ */
+export declare function isReservedFile(relPath: string): boolean;
+/**
+ * Concept ID from a bundle-relative markdown file path: normalize separators,
+ * drop a leading `./` or `/`, and strip the trailing `.md`.
+ */
+export declare function conceptIdFromPath(relPath: string): ConceptId;
+/**
+ * Bundle-relative markdown file path for an ALREADY-CANONICAL concept ID.
+ *
+ * A concept ID is the file path with exactly its FINAL `.md` suffix removed. Therefore an
+ * ordinary `x.md` file has id `x`, while a valid `x.md.md` file has id `x.md`. Do not strip a
+ * suffix here: doing so aliases those two distinct concepts onto the same physical file. User
+ * interfaces that accept file-like spellings normalize them through {@link conceptIdFromPath}
+ * before entering the engine/storage seam.
+ */
+export declare function pathFromConceptId(id: ConceptId): string;
+/**
+ * Guard the canonical concept-ID grammar before an id reaches storage. In addition to path
+ * traversal / absolute escape, aliases that a filesystem would silently normalize (`./`, `//`,
+ * `\\`, or an interior `.` segment) are rejected so every backend keys the SAME identity.
+ * File-like user input is normalized before this boundary with {@link conceptIdFromPath}.
+ */
+export declare function assertSafeConceptId(id: ConceptId): void;
+/**
+ * Guard a blob key before it is joined onto the bundle root for a filesystem read or
+ * write. Same traversal/absolute-escape shape as {@link assertSafeConceptId}, PLUS
+ * three blob-specific rejections so the blob and concept-document namespaces stay
+ * disjoint in both directions:
+ *   - ANY segment ending in `.md`, checked CASE-INSENSITIVELY (`report.MD` would collide
+ *     with `report.md` on a case-insensitive filesystem such as APFS, silently bypassing
+ *     concept-doc CAS and getting ingested as a doc by the next bundle walk) — not just
+ *     the FINAL segment: a key like `report.md/attachment.png` would otherwise pass (its
+ *     final segment is `attachment.png`) while creating an on-disk DIRECTORY literally
+ *     named `report.md`, which collides with — and blocks — any future concept doc write
+ *     to id `report` (`pathFromConceptId("report")` targets that exact path as a FILE).
+ *     This also covers the two reserved filenames (`index.md`/`log.md`), which always
+ *     carry that extension, at any depth.
+ *   - any dot-prefixed path segment (invisible to the concept walk by convention, and
+ *     the exact shape `FilesystemBackend.atomicWrite`'s own temp files use — a blob key
+ *     must never collide with that).
+ *   - a trailing-slash / empty final segment (a blob key must name a file, not a dir).
+ * Applies to EVERY blob operation — read and exists included, not just write — so a
+ * probing `readBlob`/`existsBlob` can't be used to bypass the guard writes enforce.
+ *
+ * Note (raw-vs-normalized storage): like a {@link ConceptId}, the key's non-extension
+ * segments are stored VERBATIM (case preserved, no other normalization) — this mirrors
+ * the engine's pre-existing concept-id behavior (an id's casing/spelling is exactly what
+ * the caller wrote) rather than introducing a NEW normalization rule just for blobs.
+ */
+export declare function assertSafeBlobKey(key: string): void;
+/**
+ * Guard a reserved-file directory (the `dir` argument to `readReserved`/`writeReserved`,
+ * where `""` denotes the bundle root) against path traversal / absolute escape before it
+ * is joined onto the bundle root. Unlike {@link assertSafeConceptId}, an empty string IS
+ * valid here (it means "the bundle root itself"). Throws on a non-string, an absolute
+ * dir, or any `..` segment.
+ */
+export declare function assertSafeReservedDir(dir: string): void;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,iCAAkC,CAAC;AAElE,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAO5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAwBvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA0BnD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAWvD"}

package/dist/paths.js

@@ -0,0 +1,148 @@
+/**
+ * Pure path helpers for OKF concept identity and reserved-file handling.
+ *
+ * A *Concept ID* is a bundle-relative path with the trailing `.md` removed
+ * (`tables/users.md` -> `tables/users`); IDs use forward slashes. Two filenames
+ * are RESERVED at any directory level — `index.md` (§6) and `log.md` (§7) — and
+ * are NOT concept documents (they carry no `type` and are excluded from queries).
+ *
+ * Everything here is pure and dependency-free, hence directly unit-testable.
+ */
+import { InvalidInputError } from "./errors.js";
+/** The two OKF reserved filenames, valid at any directory level (§3.1). */
+export const RESERVED_FILENAMES = ["index.md", "log.md"];
+/** Normalize any separators to forward slashes and collapse duplicate slashes. */
+export function toPosix(p) {
+    return p.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+}
+/**
+ * True when the bundle-relative path's final segment is a reserved OKF filename
+ * (`index.md` / `log.md`) at ANY directory level.
+ */
+export function isReservedFile(relPath) {
+    const base = toPosix(relPath).split("/").pop() ?? "";
+    return RESERVED_FILENAMES.includes(base);
+}
+/**
+ * Concept ID from a bundle-relative markdown file path: normalize separators,
+ * drop a leading `./` or `/`, and strip the trailing `.md`.
+ */
+export function conceptIdFromPath(relPath) {
+    const norm = toPosix(relPath)
+        .replace(/^\.?\//, "")
+        .split("/")
+        .filter((segment) => segment !== ".")
+        .join("/");
+    return norm.endsWith(".md") ? norm.slice(0, -3) : norm;
+}
+/**
+ * Bundle-relative markdown file path for an ALREADY-CANONICAL concept ID.
+ *
+ * A concept ID is the file path with exactly its FINAL `.md` suffix removed. Therefore an
+ * ordinary `x.md` file has id `x`, while a valid `x.md.md` file has id `x.md`. Do not strip a
+ * suffix here: doing so aliases those two distinct concepts onto the same physical file. User
+ * interfaces that accept file-like spellings normalize them through {@link conceptIdFromPath}
+ * before entering the engine/storage seam.
+ */
+export function pathFromConceptId(id) {
+    assertSafeConceptId(id);
+    return `${id}.md`;
+}
+/**
+ * Guard the canonical concept-ID grammar before an id reaches storage. In addition to path
+ * traversal / absolute escape, aliases that a filesystem would silently normalize (`./`, `//`,
+ * `\\`, or an interior `.` segment) are rejected so every backend keys the SAME identity.
+ * File-like user input is normalized before this boundary with {@link conceptIdFromPath}.
+ */
+export 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}'.`);
+    }
+    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).`);
+    }
+}
+/**
+ * Guard a blob key before it is joined onto the bundle root for a filesystem read or
+ * write. Same traversal/absolute-escape shape as {@link assertSafeConceptId}, PLUS
+ * three blob-specific rejections so the blob and concept-document namespaces stay
+ * disjoint in both directions:
+ *   - ANY segment ending in `.md`, checked CASE-INSENSITIVELY (`report.MD` would collide
+ *     with `report.md` on a case-insensitive filesystem such as APFS, silently bypassing
+ *     concept-doc CAS and getting ingested as a doc by the next bundle walk) — not just
+ *     the FINAL segment: a key like `report.md/attachment.png` would otherwise pass (its
+ *     final segment is `attachment.png`) while creating an on-disk DIRECTORY literally
+ *     named `report.md`, which collides with — and blocks — any future concept doc write
+ *     to id `report` (`pathFromConceptId("report")` targets that exact path as a FILE).
+ *     This also covers the two reserved filenames (`index.md`/`log.md`), which always
+ *     carry that extension, at any depth.
+ *   - any dot-prefixed path segment (invisible to the concept walk by convention, and
+ *     the exact shape `FilesystemBackend.atomicWrite`'s own temp files use — a blob key
+ *     must never collide with that).
+ *   - a trailing-slash / empty final segment (a blob key must name a file, not a dir).
+ * Applies to EVERY blob operation — read and exists included, not just write — so a
+ * probing `readBlob`/`existsBlob` can't be used to bypass the guard writes enforce.
+ *
+ * Note (raw-vs-normalized storage): like a {@link ConceptId}, the key's non-extension
+ * segments are stored VERBATIM (case preserved, no other normalization) — this mirrors
+ * the engine's pre-existing concept-id behavior (an id's casing/spelling is exactly what
+ * the caller wrote) rather than introducing a NEW normalization rule just for blobs.
+ */
+export 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}'.`);
+    }
+    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 — write it as a doc ` +
+            `instead.`);
+    }
+}
+/**
+ * Guard a reserved-file directory (the `dir` argument to `readReserved`/`writeReserved`,
+ * where `""` denotes the bundle root) against path traversal / absolute escape before it
+ * is joined onto the bundle root. Unlike {@link assertSafeConceptId}, an empty string IS
+ * valid here (it means "the bundle root itself"). Throws on a non-string, an absolute
+ * dir, or any `..` segment.
+ */
+export 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}'.`);
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/dist/portable-frontmatter.d.ts

@@ -0,0 +1,8 @@
+/** Browser/Worker-safe parsing for the bundle-root OKF edition marker. */
+import type { Frontmatter } from "./types.js";
+/**
+ * Parse only a leading YAML frontmatter block. This deliberately avoids gray-matter: that package
+ * constructs a Node Buffer while parsing even a string, so it cannot execute in a Worker runtime.
+ */
+export declare function parseLeadingFrontmatter(raw: string, context?: string): Frontmatter;
+//# sourceMappingURL=portable-frontmatter.d.ts.map

package/dist/portable-frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-frontmatter.d.ts","sourceRoot":"","sources":["../src/portable-frontmatter.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAK1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAwBlF"}

package/dist/portable-frontmatter.js

@@ -0,0 +1,35 @@
+/** Browser/Worker-safe parsing for the bundle-root OKF edition marker. */
+import yaml from "js-yaml";
+import { MalformedDocumentError } from "./frontmatter-contract.js";
+/**
+ * Parse only a leading YAML frontmatter block. This deliberately avoids gray-matter: that package
+ * constructs a Node Buffer while parsing even a string, so it cannot execute in a Worker runtime.
+ */
+export function parseLeadingFrontmatter(raw, context) {
+    // Match the legacy parser's UTF-8 text behavior without pulling its Buffer-dependent package
+    // into the portable graph. Only a single file-leading BOM is an encoding marker.
+    const input = raw.startsWith("\uFEFF") ? raw.slice(1) : raw;
+    if (!/^---(?:\r?\n|$)/.test(input))
+        return {};
+    const firstLineEnd = input.indexOf("\n");
+    const afterOpening = firstLineEnd === -1 ? "" : input.slice(firstLineEnd + 1);
+    const closing = /^---\r?$/m.exec(afterOpening);
+    if (!closing) {
+        throw new MalformedDocumentError(context, new Error("unterminated YAML frontmatter delimiter"));
+    }
+    try {
+        const parsed = yaml.safeLoad(afterOpening.slice(0, closing.index));
+        if (parsed === undefined || parsed === null)
+            return {};
+        if (typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new TypeError("YAML frontmatter must be a mapping");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof MalformedDocumentError)
+            throw error;
+        throw new MalformedDocumentError(context, error);
+    }
+}
+//# sourceMappingURL=portable-frontmatter.js.map

package/dist/portable-frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-frontmatter.js","sourceRoot":"","sources":["../src/portable-frontmatter.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,OAAO,IAAI,MAAM,SAAS,CAAC;AAE3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGnE;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW,EAAE,OAAgB;IACnE,6FAA6F;IAC7F,iFAAiF;IACjF,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC5D,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAiB,CAAC;IAE7D,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,YAAY,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,sBAAsB,CAAC,OAAO,EAAE,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC,CAAC;IAClG,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACnE,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,EAAiB,CAAC;QACtE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,MAAqB,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,sBAAsB;YAAE,MAAM,KAAK,CAAC;QACzD,MAAM,IAAI,sBAAsB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;AACH,CAAC"}

package/dist/publication-filesystem.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Publication-only filesystem capture helpers. This subpath deliberately does not widen the
+ * stable StorageBackend seam or the main `@superbee/core` export surface.
+ */
+export { listFilesystemReservedObjects, readRawFilesystemDocument, readRawFilesystemReserved, } from "./backend.js";
+//# sourceMappingURL=publication-filesystem.d.ts.map

package/dist/publication-filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publication-filesystem.d.ts","sourceRoot":"","sources":["../src/publication-filesystem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,cAAc,CAAC"}

package/dist/publication-filesystem.js

@@ -0,0 +1,6 @@
+/**
+ * Publication-only filesystem capture helpers. This subpath deliberately does not widen the
+ * stable StorageBackend seam or the main `@superbee/core` export surface.
+ */
+export { listFilesystemReservedObjects, readRawFilesystemDocument, readRawFilesystemReserved, } from "./backend.js";
+//# sourceMappingURL=publication-filesystem.js.map

package/dist/publication-filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publication-filesystem.js","sourceRoot":"","sources":["../src/publication-filesystem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,cAAc,CAAC"}

package/dist/query-filter.d.ts

@@ -0,0 +1,12 @@
+/** Browser-safe, storage-free query predicate shared by every head-projection consumer. */
+import type { ConceptId, Frontmatter, QueryFilter } from "./types.js";
+/**
+ * THE canonical {@link QueryFilter} predicate — every facet (`prefix`, `type`, `tags`, `fields`),
+ * ANDed. Kept in a storage-free module so both Node consumers and the browser View bridge can use
+ * the same scalar/array/string-coercion semantics without importing the filesystem-backed engine.
+ */
+export declare function matchesFilter(doc: {
+    id: ConceptId;
+    frontmatter: Frontmatter;
+}, filter: QueryFilter): boolean;
+//# sourceMappingURL=query-filter.d.ts.map

package/dist/query-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-filter.d.ts","sourceRoot":"","sources":["../src/query-filter.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,EAChD,MAAM,EAAE,WAAW,GAClB,OAAO,CAmBT"}

package/dist/query-filter.js

@@ -0,0 +1,29 @@
+/**
+ * THE canonical {@link QueryFilter} predicate — every facet (`prefix`, `type`, `tags`, `fields`),
+ * ANDed. Kept in a storage-free module so both Node consumers and the browser View bridge can use
+ * the same scalar/array/string-coercion semantics without importing the filesystem-backed engine.
+ */
+export function matchesFilter(doc, filter) {
+    if (filter.prefix && !doc.id.startsWith(filter.prefix))
+        return false;
+    if (filter.type && doc.frontmatter.type !== filter.type)
+        return false;
+    if (filter.tags && filter.tags.length > 0) {
+        const tags = Array.isArray(doc.frontmatter.tags) ? doc.frontmatter.tags : [];
+        if (!filter.tags.every((tag) => tags.includes(tag)))
+            return false;
+    }
+    if (filter.fields) {
+        const frontmatter = doc.frontmatter;
+        for (const [key, expected] of Object.entries(filter.fields)) {
+            const raw = frontmatter[key];
+            const actual = raw === undefined || raw === null
+                ? []
+                : (Array.isArray(raw) ? raw : [raw]).map((value) => String(value));
+            if (!actual.includes(expected))
+                return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=query-filter.js.map

package/dist/query-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-filter.js","sourceRoot":"","sources":["../src/query-filter.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAgD,EAChD,MAAmB;IAEnB,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,IAAI,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACpE,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,WAAW,GAAG,GAAG,CAAC,WAAsC,CAAC;QAC/D,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5D,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,MAAM,GACV,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;gBAC/B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACvE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,OAAO,KAAK,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/query-selection.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Browser-safe post-filtering shared by human-facing query surfaces.
+ *
+ * Storage-facing `type`/`prefix` filtering stays in `queryHeads`; this helper owns the
+ * field-set, declared-terminal, honest-count, and limit projection used after those rows arrive.
+ */
+import { type KindConvention } from "./kinds.js";
+import type { Frontmatter } from "./types.js";
+export interface QuerySelectionParams {
+    type?: string;
+    prefix?: string;
+    field?: string;
+    open?: boolean;
+    limit?: number;
+    /** Bundle-root OKF edition, used only for declaration-driven logical field aliases. */
+    okfVersion?: string;
+}
+export declare function applyQuerySelectionFilters<T extends {
+    id: string;
+    frontmatter: Frontmatter;
+}>(rows: T[], params: QuerySelectionParams, kinds?: KindConvention[]): {
+    rows: T[];
+    count: number;
+};
+//# sourceMappingURL=query-selection.d.ts.map

package/dist/query-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-selection.d.ts","sourceRoot":"","sources":["../src/query-selection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,0BAA0B,CACxC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,EAElD,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,oBAAoB,EAC5B,KAAK,GAAE,cAAc,EAAO,GAC3B;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAqC9B"}

package/dist/query-selection.js

@@ -0,0 +1,48 @@
+/**
+ * Browser-safe post-filtering shared by human-facing query surfaces.
+ *
+ * Storage-facing `type`/`prefix` filtering stays in `queryHeads`; this helper owns the
+ * field-set, declared-terminal, honest-count, and limit projection used after those rows arrive.
+ */
+import { PROGRESS_STATUS_FIELD, isTerminal, readKindField, } from "./kinds.js";
+import { matchesFilter } from "./query-filter.js";
+export function applyQuerySelectionFilters(rows, params, kinds = []) {
+    let out = rows;
+    const byGoverns = new Map(kinds.map((kind) => [kind.governs, kind]));
+    if (params.field) {
+        const eq = params.field.indexOf("=");
+        if (eq > 0) {
+            const key = params.field.slice(0, eq).trim();
+            const values = params.field
+                .slice(eq + 1)
+                .split(",")
+                .map((value) => value.trim())
+                .filter(Boolean);
+            out = out.filter((row) => {
+                if (key !== PROGRESS_STATUS_FIELD) {
+                    return values.some((value) => matchesFilter(row, { fields: { [key]: value } }));
+                }
+                const kind = byGoverns.get(String(row.frontmatter.type ?? ""));
+                if (!kind)
+                    return false;
+                const raw = readKindField(params.okfVersion, kind, row.frontmatter, key);
+                const actual = raw === undefined || raw === null
+                    ? []
+                    : (Array.isArray(raw) ? raw : [raw]).map((value) => String(value));
+                return values.some((value) => actual.includes(value));
+            });
+        }
+    }
+    if (params.open) {
+        out = out.filter((row) => {
+            const kind = byGoverns.get(String(row.frontmatter.type ?? ""));
+            return !kind || !isTerminal(kind, row.frontmatter);
+        });
+    }
+    const count = out.length;
+    if (typeof params.limit === "number" && params.limit > 0) {
+        out = out.slice(0, params.limit);
+    }
+    return { rows: out, count };
+}
+//# sourceMappingURL=query-selection.js.map

package/dist/query-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-selection.js","sourceRoot":"","sources":["../src/query-selection.ts"],"names":[],"mappings":"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"}