@superbee/core 0.1.0

package/dist/backend.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Storage adapters for the OKF engine.
+ *
+ * The engine's disk-facing operations are expressed against {@link StorageBackend}
+ * (declared in `types.ts`) so the store is PLUGGABLE. This module ships the DEFAULT
+ * adapter — {@link FilesystemBackend} — which wraps the local filesystem: a bundle
+ * is a directory tree of UTF-8 markdown files, written atomically (temp file +
+ * rename). It is the DEGENERATE case of the seam's hard contract: `version` is the
+ * SHA of the on-disk bytes, and `versions()` reports only the single current
+ * revision because a plain filesystem keeps no history. Compare-and-swap is
+ * serialized per logical identity across processes by a private runtime lock directory;
+ * a process-local promise queue avoids filesystem polling among callers in one process.
+ * `MemoryBackend`
+ * (`memory-backend.ts`) implements the SAME contract for the hard case; a remote
+ * (HTTP/CF/D1) adapter is a FUTURE plug-in, never a rewrite of the engine.
+ *
+ * This adapter touches no filesystem API itself. Every read and write goes through the
+ * exact-identity protocol in `filesystem-identity.ts` with its production port, which is what
+ * keeps two differently spelled ids from ever reaching one physical file on a case- or
+ * normalization-insensitive filesystem.
+ *
+ * There is exactly ONE frontmatter parser (`frontmatter.ts`); this adapter uses it.
+ * A remote backend that stores already-structured documents need not parse markdown
+ * at all — parsing is an implementation detail of THIS adapter, not of the seam.
+ */
+import type { BlobKey, ConceptId, DeleteOptions, OkfDocument, ReadBlobResult, ReadResult, ReservedFilename, ReservedReadResult, StorageBackend, Version, VersionInfo, WriteOptions } from "./types.js";
+/**
+ * The default {@link StorageBackend}: a filesystem-backed OKF bundle rooted at an
+ * absolute directory. Concept documents are markdown files at `<id>.md`; reserved
+ * files live at `<dir>/index.md` and `<dir>/log.md`.
+ */
+export declare class FilesystemBackend implements StorageBackend {
+    #private;
+    /**
+     * 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: string);
+    read(id: ConceptId): Promise<ReadResult>;
+    readMany(ids: ConceptId[]): Promise<ReadResult[]>;
+    write(id: ConceptId, doc: OkfDocument, options?: WriteOptions): Promise<Version>;
+    delete(id: ConceptId, options?: DeleteOptions): Promise<boolean>;
+    versions(id: ConceptId): Promise<VersionInfo[]>;
+    exists(id: ConceptId): Promise<boolean>;
+    list(prefix?: string): Promise<ConceptId[]>;
+    readReserved(dir: string, name: ReservedFilename): Promise<ReservedReadResult | null>;
+    writeReserved(dir: string, name: ReservedFilename, content: string, options?: WriteOptions): Promise<Version>;
+    readBlob(key: BlobKey): Promise<ReadBlobResult | null>;
+    writeBlob(key: BlobKey, bytes: Uint8Array, _contentType?: string, options?: WriteOptions): Promise<Version>;
+    deleteBlob(key: BlobKey, options?: DeleteOptions): Promise<boolean>;
+    existsBlob(key: BlobKey): Promise<boolean>;
+    listBlobs(prefix?: string): Promise<BlobKey[]>;
+    capabilities(): {
+        readonly history: false;
+        readonly enforced_cas: true;
+        readonly blobs: true;
+        readonly projections: true;
+        readonly backlinks: false;
+    };
+}
+/** Internal exact-byte authority for the publication adapter; not part of StorageBackend. */
+export declare function readRawFilesystemDocument(backend: FilesystemBackend, id: ConceptId): Promise<{
+    bytes: Uint8Array;
+    version: Version;
+}>;
+/** Internal exact-byte authority for reserved publication objects. */
+export declare function readRawFilesystemReserved(backend: FilesystemBackend, dir: string, name: ReservedFilename): Promise<{
+    bytes: Uint8Array;
+    version: Version;
+} | null>;
+/** Internal canonical inventory of reserved publication objects. */
+export declare function listFilesystemReservedObjects(backend: FilesystemBackend): Promise<Array<{
+    dir: string;
+    name: ReservedFilename;
+}>>;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAyBH,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,aAAa,EACb,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,WAAW,EACX,YAAY,EACb,MAAM,YAAY,CAAC;AAqEpB;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,cAAc;;IAGtD;;;;OAIG;gBACS,IAAI,EAAE,MAAM;IAKlB,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAUxC,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAWjD,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BpF,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBpE,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA6B/C,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAKvC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmB3C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAUrF,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAoBb,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAatD,SAAS,CACb,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAuBb,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAcvE,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAU1C,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAWpD,YAAY;;;;;;;CASb;AAQD,6FAA6F;AAC7F,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,iBAAiB,EAC1B,EAAE,EAAE,SAAS,GACZ,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAQlD;AAED,sEAAsE;AACtE,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CASzD;AAED,oEAAoE;AACpE,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAAC,CAYzD"}

package/dist/backend.js

@@ -0,0 +1,380 @@
+/**
+ * Storage adapters for the OKF engine.
+ *
+ * The engine's disk-facing operations are expressed against {@link StorageBackend}
+ * (declared in `types.ts`) so the store is PLUGGABLE. This module ships the DEFAULT
+ * adapter — {@link FilesystemBackend} — which wraps the local filesystem: a bundle
+ * is a directory tree of UTF-8 markdown files, written atomically (temp file +
+ * rename). It is the DEGENERATE case of the seam's hard contract: `version` is the
+ * SHA of the on-disk bytes, and `versions()` reports only the single current
+ * revision because a plain filesystem keeps no history. Compare-and-swap is
+ * serialized per logical identity across processes by a private runtime lock directory;
+ * a process-local promise queue avoids filesystem polling among callers in one process.
+ * `MemoryBackend`
+ * (`memory-backend.ts`) implements the SAME contract for the hard case; a remote
+ * (HTTP/CF/D1) adapter is a FUTURE plug-in, never a rewrite of the engine.
+ *
+ * This adapter touches no filesystem API itself. Every read and write goes through the
+ * exact-identity protocol in `filesystem-identity.ts` with its production port, which is what
+ * keeps two differently spelled ids from ever reaching one physical file on a case- or
+ * normalization-insensitive filesystem.
+ *
+ * There is exactly ONE frontmatter parser (`frontmatter.ts`); this adapter uses it.
+ * A remote backend that stores already-structured documents need not parse markdown
+ * at all — parsing is an implementation detail of THIS adapter, not of the seam.
+ */
+import path from "node:path";
+import { parseMarkdown, stringifyDoc } from "./frontmatter.js";
+import { resolveContentType } from "./content-type.js";
+import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, conceptIdFromPath, isReservedFile, pathFromConceptId, toPosix, } from "./paths.js";
+import { InvalidInputError } from "./errors.js";
+import { mutateExact, nodeFilesystemIdentityPort as port, observeExact, probeExact, } from "./filesystem-identity.js";
+import { mutationActorFromFrontmatter } from "./mutation-attribution.js";
+import { blobVersion, defaultActor, VersionConflict, versionOfBytes } from "./versioning.js";
+const publicationRoots = new WeakMap();
+/** First trimmed non-empty string among `vals`, else `undefined`. */
+function firstString(...vals) {
+    for (const v of vals) {
+        if (typeof v === "string" && v.trim() !== "")
+            return v;
+    }
+    return undefined;
+}
+/**
+ * True when a thrown fs error means "there is no FILE at this path" — absence (`ENOENT`,
+ * `ENOTDIR`) or a directory sitting where a file was expected (`EISDIR`, the blob-key/directory
+ * collision). Anything else (`EACCES`, `EPERM`, a disk error, …) is a REAL failure, not a "this
+ * blob doesn't exist" signal, and must propagate — a blanket catch that mapped every error to
+ * `null` would silently misreport a permissions problem as "absent."
+ */
+function isAbsentFileError(err) {
+    const code = err?.code;
+    return code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR";
+}
+/** The ENOENT-shaped rejection `read`/`readMany` promise for an absent document. */
+function notFound(root, rel) {
+    const target = path.join(root, rel);
+    const err = new Error(`ENOENT: no such file or directory, open '${target}'`);
+    err.code = "ENOENT";
+    err.syscall = "open";
+    err.path = target;
+    return err;
+}
+/** Observation read: every byte through the open handle; `null` when no file is there. */
+async function readBytes(handle) {
+    try {
+        return await port.readAll(handle);
+    }
+    catch (err) {
+        if (isAbsentFileError(err))
+            return null;
+        throw err;
+    }
+}
+/** Recursively collect bundle-relative posix paths of files `keep` accepts (skips dot-entries). */
+async function walkFiles(root, keep, sub = "") {
+    const entries = (await port.entries(path.join(root, sub))) ?? [];
+    const out = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue; // .git, temp files, dot-dirs: invisible to the walk
+        const rel = sub === "" ? entry.name : `${sub}/${entry.name}`;
+        if (entry.kind === "directory") {
+            out.push(...(await walkFiles(root, keep, rel)));
+        }
+        else if (entry.kind === "file" && keep(entry.name)) {
+            // `rel` is already assembled with `/`. Preserve any literal backslash in an entry name so
+            // `list()` can reject it as a noncanonical on-disk identity instead of silently converting
+            // it into a different nested concept id.
+            out.push(rel);
+        }
+    }
+    return out;
+}
+/** Bundle-relative reserved-file path for a directory (`""` = bundle root). */
+function reservedPath(dir, name) {
+    const d = toPosix(dir).replace(/^\.?\//, "").replace(/\/$/, "");
+    return d === "" ? name : `${d}/${name}`;
+}
+/**
+ * The default {@link StorageBackend}: a filesystem-backed OKF bundle rooted at an
+ * absolute directory. Concept documents are markdown files at `<id>.md`; reserved
+ * files live at `<dir>/index.md` and `<dir>/log.md`.
+ */
+export class FilesystemBackend {
+    #root;
+    /**
+     * 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) {
+        this.#root = path.resolve(root);
+        publicationRoots.set(this, this.#root);
+    }
+    async read(id) {
+        assertSafeConceptId(id);
+        const rel = pathFromConceptId(id);
+        const observed = await observeExact(port, this.#root, rel, readBytes);
+        if (observed.state === "absent")
+            throw notFound(this.#root, rel);
+        const raw = observed.value.toString("utf8");
+        const { frontmatter, body } = parseMarkdown(raw, rel);
+        return { doc: { id, frontmatter, body }, version: versionOfBytes(raw) };
+    }
+    async readMany(ids) {
+        // Validate every id BEFORE any path realization (not just the first that `read`
+        // would hit) — degenerate batch read: a loop of single reads, since a local
+        // filesystem has no per-read round-trip to amortize. A networked backend implements
+        // this as one multi-get, which is the whole reason `readMany` is on the seam.
+        for (const id of ids)
+            assertSafeConceptId(id);
+        const out = [];
+        for (const id of ids)
+            out.push(await this.read(id));
+        return out;
+    }
+    async write(id, doc, options = {}) {
+        assertSafeConceptId(id);
+        const raw = stringifyDoc(doc.frontmatter, doc.body ?? "");
+        const rel = pathFromConceptId(id);
+        // The whole check-then-write section runs inside one identity-keyed critical section, local
+        // and same-user cross-process; an unconditional writer holds it too so it cannot move the
+        // target between another process's version check and write.
+        return mutateExact(port, this.#root, rel, async (target) => {
+            if (options.expectedVersion !== undefined) {
+                const bytes = await target.current();
+                const current = bytes === null ? null : versionOfBytes(bytes.toString("utf8"));
+                if (current !== options.expectedVersion) {
+                    throw new VersionConflict(id, options.expectedVersion, current);
+                }
+            }
+            // `options.actor` is accepted for contract parity but NOT persisted here: the
+            // filesystem keeps no history, and stamping it into frontmatter would both change
+            // existing CLI output and diverge the document from other backends. `versions()`
+            // reports actor from the portable mutation-attribution projection if present, else a
+            // local default — an honest degenerate answer. `options.agent` is likewise
+            // accepted-but-not-persisted (this degenerate adapter records no agent at all).
+            await target.replace(Buffer.from(raw, "utf8"));
+            return versionOfBytes(raw);
+        });
+    }
+    async delete(id, options = {}) {
+        assertSafeConceptId(id);
+        return mutateExact(port, this.#root, pathFromConceptId(id), async (target) => {
+            const bytes = await target.current();
+            if (bytes === null)
+                return false; // absent ⇒ idempotent no-op, EVEN under CAS
+            const current = versionOfBytes(bytes.toString("utf8"));
+            if (options.expectedVersion !== undefined && current !== options.expectedVersion) {
+                throw new VersionConflict(id, options.expectedVersion, current);
+            }
+            await target.remove();
+            // Empty parent dirs are intentionally NOT pruned (a write never prunes either) — a later
+            // write to a sibling id under the same now-empty directory must not have to worry about
+            // a missing directory tree.
+            return true;
+        });
+    }
+    async versions(id) {
+        assertSafeConceptId(id);
+        const rel = pathFromConceptId(id);
+        const observed = await observeExact(port, this.#root, rel, async (handle, target) => {
+            try {
+                const bytes = await port.readAll(handle);
+                // mtime is taken by path rather than through the open handle: the port has no
+                // stat-by-handle call, and widening the protocol surface for a fallback timestamp used
+                // only when the frontmatter carries none is not worth it. It cannot attribute another
+                // entry's mtime to this identity: the post-walk that follows requires the leaf the
+                // requested path reaches to still be this handle's inode and every directory segment to
+                // still be its recorded one, so a swap between this call and that check restarts the
+                // observation instead of returning EXACT — under the same A11 witness limit the walk
+                // itself carries.
+                const { mtime } = await port.stat(target);
+                return { raw: bytes.toString("utf8"), mtime };
+            }
+            catch {
+                return null; // no readable document ⇒ no history
+            }
+        });
+        if (observed.state === "absent")
+            return [];
+        const { raw, mtime } = observed.value;
+        const { frontmatter } = parseMarkdown(raw, rel);
+        const actor = mutationActorFromFrontmatter(frontmatter) ?? defaultActor();
+        const timestamp = firstString(frontmatter.timestamp) ?? mtime.toISOString();
+        // Single current revision: a plain filesystem retains no prior versions.
+        return [{ version: versionOfBytes(raw), actor, timestamp }];
+    }
+    async exists(id) {
+        assertSafeConceptId(id);
+        return (await probeExact(port, this.#root, pathFromConceptId(id))).state === "exact";
+    }
+    async list(prefix) {
+        const files = await walkFiles(this.#root, (name) => name.endsWith(".md"));
+        const ids = [];
+        for (const rel of files) {
+            if (isReservedFile(rel))
+                continue;
+            const id = conceptIdFromPath(rel);
+            assertSafeConceptId(id);
+            if (pathFromConceptId(id) !== rel) {
+                throw new InvalidInputError(`Concept path '${rel}' does not round-trip through canonical id '${id}'. Rename the file to '${pathFromConceptId(id)}'.`);
+            }
+            if (prefix && !id.startsWith(prefix))
+                continue;
+            ids.push(id);
+        }
+        ids.sort((a, b) => a.localeCompare(b));
+        return ids;
+    }
+    async readReserved(dir, name) {
+        assertSafeReservedDir(dir);
+        const observed = await observeExact(port, this.#root, reservedPath(dir, name), readBytes);
+        if (observed.state === "absent")
+            return null;
+        const content = observed.value.toString("utf8");
+        // Reserved files are unparsed markdown, so the version is the content-address of the
+        // raw bytes — the same digest a concept document's on-disk bytes carry.
+        return { content, version: versionOfBytes(content) };
+    }
+    async writeReserved(dir, name, content, options = {}) {
+        assertSafeReservedDir(dir);
+        const rel = reservedPath(dir, name);
+        // Same identity-keyed critical section as `write()`. A reserved-file read-modify-write
+        // depends on a genuine `VersionConflict` under contention.
+        return mutateExact(port, this.#root, rel, async (target) => {
+            if (options.expectedVersion !== undefined) {
+                const bytes = await target.current();
+                const current = bytes === null ? null : versionOfBytes(bytes.toString("utf8"));
+                if (current !== options.expectedVersion) {
+                    throw new VersionConflict(rel, options.expectedVersion, current);
+                }
+            }
+            await target.replace(Buffer.from(content, "utf8"));
+            return versionOfBytes(content);
+        });
+    }
+    // ── blobs: opaque bytes + a content-type ──────────────────────────────────
+    async readBlob(key) {
+        assertSafeBlobKey(key);
+        // Absence (ENOENT) or a directory sitting at this path (EISDIR) is a normal "no blob here"
+        // result; `readBytes` propagates everything else (EACCES, EPERM, …) as the real failure it is.
+        const observed = await observeExact(port, this.#root, key, readBytes);
+        if (observed.state === "absent")
+            return null;
+        const bytes = observed.value; // raw bytes, NO encoding (B1)
+        // Content-type is ALWAYS inferred-on-read here: the filesystem adapter accepts but
+        // does not persist an explicit override at write time (see writeBlob's doc comment,
+        // B5) — there is no sidecar to read it back from.
+        return { bytes, contentType: resolveContentType(key), version: blobVersion(bytes) };
+    }
+    async writeBlob(key, bytes, _contentType, options = {}) {
+        assertSafeBlobKey(key);
+        // The WHOLE check-then-write section runs inside the identity lock, exactly like write(),
+        // so N concurrent CAS writers to the SAME blob key queue instead of racing the version
+        // check (B3). Raw-bytes versioning: hashing through a UTF-8 decode would corrupt binary (B1).
+        return mutateExact(port, this.#root, key, async (target) => {
+            if (options.expectedVersion !== undefined) {
+                const existing = await target.current();
+                const current = existing === null ? null : blobVersion(existing);
+                if (current !== options.expectedVersion) {
+                    throw new VersionConflict(key, options.expectedVersion, current);
+                }
+            }
+            // `contentType` (like `options.actor`) is accepted for contract parity but NOT
+            // persisted here: the filesystem keeps no sidecar metadata store, so an explicit
+            // override is honored at write time and re-inferred from the key extension on
+            // every read instead (see readBlob) — mirrors write()'s actor-parity posture
+            // exactly (B5). `MemoryBackend` persists it because it keeps state.
+            await target.replace(bytes);
+            return blobVersion(bytes);
+        });
+    }
+    async deleteBlob(key, options = {}) {
+        assertSafeBlobKey(key);
+        return mutateExact(port, this.#root, key, async (target) => {
+            const existing = await target.current();
+            if (existing === null)
+                return false; // absent (or a directory-shaped path) ⇒ idempotent no-op
+            const current = blobVersion(existing);
+            if (options.expectedVersion !== undefined && current !== options.expectedVersion) {
+                throw new VersionConflict(key, options.expectedVersion, current);
+            }
+            await target.remove();
+            return true;
+        });
+    }
+    async existsBlob(key) {
+        assertSafeBlobKey(key);
+        // A regular file only: a blob key that collides with an existing DIRECTORY (e.g. a sibling
+        // key like `artifacts/x/y.bin` leaves `artifacts/x` a directory) must report `false` here,
+        // matching MemoryBackend/RemoteBackend — neither has a filesystem notion of "a path that is
+        // a directory," so a directory-counts-as-exists answer would break tri-adapter parity.
+        const observed = await probeExact(port, this.#root, key);
+        return observed.state === "exact" && observed.value.kind === "file";
+    }
+    async listBlobs(prefix) {
+        // Skipping dot-entries is what excludes the adapter's own dot-prefixed temp files and `.git`
+        // from a blob listing (I3), not just the write-time `assertSafeBlobKey` guard. The
+        // `.md`-extension check is case-insensitive, mirroring `assertSafeBlobKey`.
+        const files = await walkFiles(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));
+        return filtered;
+    }
+    capabilities() {
+        return {
+            history: false,
+            enforced_cas: true,
+            blobs: true,
+            projections: true,
+            backlinks: false,
+        };
+    }
+}
+function publicationRoot(backend) {
+    const root = publicationRoots.get(backend);
+    if (!root)
+        throw new InvalidInputError("Unknown filesystem backend publication source.");
+    return root;
+}
+/** Internal exact-byte authority for the publication adapter; not part of StorageBackend. */
+export async function readRawFilesystemDocument(backend, id) {
+    assertSafeConceptId(id);
+    const root = publicationRoot(backend);
+    const rel = pathFromConceptId(id);
+    const observed = await observeExact(port, root, rel, readBytes);
+    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) };
+}
+/** Internal exact-byte authority for reserved publication objects. */
+export async function readRawFilesystemReserved(backend, dir, name) {
+    assertSafeReservedDir(dir);
+    const root = publicationRoot(backend);
+    const observed = await observeExact(port, root, reservedPath(dir, name), readBytes);
+    if (observed.state === "absent")
+        return null;
+    return {
+        bytes: observed.value.slice(),
+        version: versionOfBytes(observed.value.toString("utf8")),
+    };
+}
+/** Internal canonical inventory of reserved publication objects. */
+export async function listFilesystemReservedObjects(backend) {
+    const root = publicationRoot(backend);
+    const files = await walkFiles(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);
+        return { dir, name };
+    })
+        .sort((a, b) => reservedPath(a.dir, a.name).localeCompare(reservedPath(b.dir, b.name)));
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

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

package/dist/bundle.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Legacy bundle-shaped core API.
+ *
+ * Portable semantics live in `engine.ts` and receive a backend explicitly. This adapter preserves
+ * the historical `{ root, backend? }` signatures and filesystem fallback used by Node consumers.
+ */
+import * as engine from "./engine.js";
+import type { BlobKey, Bundle, ConceptId, DeleteOptions, EdgeFilter, HeadResult, InitBundleOptions, Link, OkfDocument, QueryFilter, ReadBlobResult, ReadResult, StorageBackend, Version, VersionInfo, WriteOptions } from "./types.js";
+export { matchesFilter } from "./query-filter.js";
+export type { QueryOptions, SkippedDoc, WriteResult } from "./engine.js";
+/** Resolve the backend a legacy bundle operation should use. */
+export declare function backendFor(bundle: Bundle): StorageBackend;
+export declare function readBundleOkfVersion(bundle: Bundle): Promise<string | undefined>;
+export declare const SUPPORTED_OKF_AUTHORING_VERSIONS: readonly ["0.1", "0.2"];
+export declare const DEFAULT_OKF_AUTHORING_VERSION = "0.2";
+export declare function resolveOkfAuthoringVersion(requested?: string): string;
+/** Initialize or open a filesystem-backed bundle. */
+export declare function initBundle(root: string, options?: InitBundleOptions): Promise<Bundle>;
+export declare function writeDocVersioned(bundle: Bundle, doc: OkfDocument, options?: WriteOptions): Promise<engine.WriteResult>;
+export declare function writeDocVersionedForEdition(bundle: Bundle, doc: OkfDocument, okfVersion: string, options?: WriteOptions): Promise<engine.WriteResult>;
+export declare function writeDoc(bundle: Bundle, doc: OkfDocument, options?: WriteOptions): Promise<OkfDocument>;
+export declare function readDocVersioned(bundle: Bundle, id: ConceptId): Promise<ReadResult>;
+export declare function readDoc(bundle: Bundle, id: ConceptId): Promise<OkfDocument>;
+export declare function existsDoc(bundle: Bundle, id: ConceptId): Promise<boolean>;
+export declare function docVersions(bundle: Bundle, id: ConceptId): Promise<VersionInfo[]>;
+export declare function deleteDoc(bundle: Bundle, id: ConceptId, options?: DeleteOptions): Promise<boolean>;
+export declare function query(bundle: Bundle, filter?: QueryFilter, options?: engine.QueryOptions): Promise<OkfDocument[]>;
+export declare const list: typeof query;
+export declare function queryHeads(bundle: Bundle, filter?: QueryFilter, options?: engine.QueryOptions): Promise<HeadResult[]>;
+export declare function parseLinks(_bundle: Bundle, doc: OkfDocument): Link[];
+export declare function queryEdges(bundle: Bundle, filter?: EdgeFilter): Promise<Link[]>;
+export declare function backlinks(bundle: Bundle, target: ConceptId): Promise<Link[]>;
+export declare function readBlob(bundle: Bundle, key: BlobKey): Promise<ReadBlobResult | null>;
+export declare function writeBlob(bundle: Bundle, key: BlobKey, bytes: Uint8Array, contentType?: string, options?: WriteOptions): Promise<Version>;
+export declare function existsBlob(bundle: Bundle, key: BlobKey): Promise<boolean>;
+export declare function listBlobs(bundle: Bundle, prefix?: string): Promise<BlobKey[]>;
+export declare function deleteBlob(bundle: Bundle, key: BlobKey, options?: DeleteOptions): Promise<boolean>;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

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

package/dist/bundle.js

@@ -0,0 +1,107 @@
+/**
+ * Legacy bundle-shaped core API.
+ *
+ * Portable semantics live in `engine.ts` and receive a backend explicitly. This adapter preserves
+ * the historical `{ root, backend? }` signatures and filesystem fallback used by Node consumers.
+ */
+import path from "node:path";
+import { FilesystemBackend } from "./backend.js";
+import * as engine from "./engine.js";
+import { InvalidInputError } from "./errors.js";
+import { stringifyWithData } from "./frontmatter.js";
+import { GENERATED_INDEX_MARKER } from "./index-marker.js";
+import { VersionConflict } from "./versioning.js";
+export { matchesFilter } from "./query-filter.js";
+/** Resolve the backend a legacy bundle operation should use. */
+export function backendFor(bundle) {
+    return bundle.backend ?? new FilesystemBackend(bundle.root);
+}
+export async function readBundleOkfVersion(bundle) {
+    return engine.readBundleOkfVersion(backendFor(bundle));
+}
+export const SUPPORTED_OKF_AUTHORING_VERSIONS = ["0.1", "0.2"];
+export const DEFAULT_OKF_AUTHORING_VERSION = "0.2";
+export function resolveOkfAuthoringVersion(requested) {
+    const version = requested ?? DEFAULT_OKF_AUTHORING_VERSION;
+    if (!SUPPORTED_OKF_AUTHORING_VERSIONS.includes(version)) {
+        throw new InvalidInputError(`Unsupported OKF authoring version '${version}'. This build can author ${SUPPORTED_OKF_AUTHORING_VERSIONS.join(" and ")}; ` +
+            "bundles declaring other versions can still be read or transported.");
+    }
+    return version;
+}
+/** Initialize or open a filesystem-backed bundle. */
+export async function initBundle(root, options = {}) {
+    const okfVersion = resolveOkfAuthoringVersion(options.okfVersion);
+    const resolved = path.resolve(root);
+    const backend = new FilesystemBackend(resolved);
+    if (options.expectNew || (await backend.readReserved("", "index.md")) === null) {
+        const name = path.basename(resolved);
+        const body = `${GENERATED_INDEX_MARKER}\n# ${name}\n\nAn Open Knowledge Format bundle.\n`;
+        try {
+            await backend.writeReserved("", "index.md", stringifyWithData({ okf_version: okfVersion }, body), {
+                expectedVersion: null,
+            });
+        }
+        catch (err) {
+            if (options.expectNew || !(err instanceof VersionConflict))
+                throw err;
+        }
+    }
+    return { root: resolved };
+}
+export async function writeDocVersioned(bundle, doc, options) {
+    return engine.writeDocVersioned(backendFor(bundle), doc, options);
+}
+export async function writeDocVersionedForEdition(bundle, doc, okfVersion, options) {
+    return engine.writeDocVersionedForEdition(backendFor(bundle), doc, okfVersion, options);
+}
+export async function writeDoc(bundle, doc, options) {
+    return engine.writeDoc(backendFor(bundle), doc, options);
+}
+export async function readDocVersioned(bundle, id) {
+    return engine.readDocVersioned(backendFor(bundle), id);
+}
+export async function readDoc(bundle, id) {
+    return engine.readDoc(backendFor(bundle), id);
+}
+export async function existsDoc(bundle, id) {
+    return engine.existsDoc(backendFor(bundle), id);
+}
+export async function docVersions(bundle, id) {
+    return engine.docVersions(backendFor(bundle), id);
+}
+export async function deleteDoc(bundle, id, options) {
+    return engine.deleteDoc(backendFor(bundle), id, options);
+}
+export async function query(bundle, filter = {}, options = {}) {
+    return engine.query(backendFor(bundle), filter, options);
+}
+export const list = query;
+export async function queryHeads(bundle, filter = {}, options = {}) {
+    return engine.queryHeads(backendFor(bundle), filter, options);
+}
+export function parseLinks(_bundle, doc) {
+    return engine.parseLinks(doc);
+}
+export async function queryEdges(bundle, filter = {}) {
+    return engine.queryEdges(backendFor(bundle), filter);
+}
+export async function backlinks(bundle, target) {
+    return engine.backlinks(backendFor(bundle), target);
+}
+export async function readBlob(bundle, key) {
+    return engine.readBlob(backendFor(bundle), key);
+}
+export async function writeBlob(bundle, key, bytes, contentType, options) {
+    return engine.writeBlob(backendFor(bundle), key, bytes, contentType, options);
+}
+export async function existsBlob(bundle, key) {
+    return engine.existsBlob(backendFor(bundle), key);
+}
+export async function listBlobs(bundle, prefix) {
+    return engine.listBlobs(backendFor(bundle), prefix);
+}
+export async function deleteBlob(bundle, key, options) {
+    return engine.deleteBlob(backendFor(bundle), key, options);
+}
+//# sourceMappingURL=bundle.js.map