@superbee/core 0.2.0-pre.11 → 0.2.0-pre.13

package/dist/cross-bundle.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Cross-bundle link resolution: the resolver interface every backend implements, and the local
+ * resolver over explicitly bound {@link StorageBackend}s.
+ *
+ * Resolution is always explicit. A resolver reads only the copies it was constructed with; nothing
+ * is fetched or discovered. Browser-safe: bindings are backends, never filesystem paths, and pin
+ * checks are injected (the CLI probes git; core never spawns a process).
+ */
+import type { DependencyMap, DependencyProblemCode } from "./dependencies.js";
+import { type QualifiedLink, type QualifiedRef } from "./qualified-links.js";
+import type { ConceptId, OkfDocument, StorageBackend, Version } from "./types.js";
+/**
+ * Why a link did not resolve. An unresolved link is still a valid link.
+ * - `bundle_unavailable`: no copy is bound, or the bound copy is not the declared bundle.
+ * - `pin_mismatch`: the bound copy is not at the pinned version.
+ * - `target_missing`: the document is not in the bound copy.
+ * - `not_authorized`: the reader may not read the target bundle.
+ * - `unknown_alias`: the alias is not declared in `docs/dependencies`.
+ * - `invalid_ref`: the href is malformed.
+ */
+export type UnresolvedReason = "bundle_unavailable" | "pin_mismatch" | "target_missing" | "not_authorized" | "unknown_alias" | "invalid_ref";
+export declare const UNRESOLVED_REASONS: readonly UnresolvedReason[];
+/**
+ * The reasons that are the referring document's fault (fix the link or the target). The others
+ * (`bundle_unavailable`, `pin_mismatch`, `not_authorized`) describe the reader's environment or
+ * access, and a check must not blame the document for them.
+ */
+export declare const RECORD_REASONS: readonly UnresolvedReason[];
+export declare function isRecordReason(reason: UnresolvedReason): boolean;
+/** The one detail every `not_authorized` result carries, so it says nothing about the target. */
+export declare const NOT_AUTHORIZED_DETAIL = "the reader is not authorized to read this bundle";
+export type Resolution = {
+    state: "resolved";
+    ref: QualifiedRef;
+    bundle_id: string;
+    /** A backend-defined revision of the bound copy, when it has one. The local resolver sets none. */
+    revision?: string;
+    document: OkfDocument;
+    version: Version;
+} | {
+    state: "unresolved";
+    /** Null when the ref itself is malformed. */
+    ref: QualifiedRef | null;
+    href: string;
+    reason: UnresolvedReason;
+    /** Only ever the id from the reader's own declaration. */
+    bundle_id?: string;
+    detail: string;
+};
+/** A link into a target document from a bundle the reader may read. */
+export interface CrossBacklink {
+    from: {
+        bundle_id: string;
+        id: ConceptId;
+    };
+    text: string;
+    href: string;
+}
+/**
+ * Resolves `okf://` refs for ONE reader.
+ *
+ * Authorization invariants, binding on every implementation (local, hosted, any future one):
+ *
+ * 1. A resolver is built for one reader. Grants are a constructor concern, never a method
+ *    parameter.
+ * 2. The grant check comes first. For a reader without a grant on the target bundle, the answer is
+ *    `not_authorized` before any "bundle not found", "document not found" or `pin_mismatch`, and
+ *    before any revision or version is disclosed.
+ * 3. `not_authorized` results for a present target and for a missing target are deep-equal, with
+ *    the fixed detail {@link NOT_AUTHORIZED_DETAIL}. Their `bundle_id` comes only from the
+ *    reader's own declaration.
+ * 4. `backlinks()` returns only hits in readable bundles, and never names or counts the others.
+ *
+ * The local resolver reads only copies the reader bound explicitly, so it never answers
+ * `not_authorized`.
+ */
+export interface BundleResolver {
+    /** `"local"` here; `"hosted"` later. */
+    readonly kind: string;
+    readonly dependencies: DependencyMap;
+    /** Batched and positional: `result[i]` answers `refs[i]`. */
+    resolve(refs: readonly QualifiedRef[]): Promise<Resolution[]>;
+    backlinks(target: {
+        bundle_id: string;
+        id: ConceptId;
+    }, options?: {
+        text?: string;
+    }): Promise<CrossBacklink[]>;
+}
+export interface CommitPin {
+    kind: "commit";
+    value: string;
+}
+/** Whether a bound copy is at a commit pin. Injected by the caller (the CLI checks the bundle's git subtree). */
+export type PinCheck = (pin: CommitPin) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+}>;
+export interface BundleBinding {
+    backend: StorageBackend;
+    /** How the caller named the copy (a path or catalog label), for messages. */
+    label: string;
+    /** The bound copy's own portable id. Absent or different from the declaration: `bundle_unavailable`. */
+    identity?: string;
+    /** Required to satisfy a commit pin; without it a pinned dependency is `pin_mismatch`. */
+    pin?: PinCheck;
+}
+export interface LocalResolverOptions {
+    dependencies: DependencyMap;
+    /** `ParsedDependencies.rejected`: declared aliases whose entry was dropped, for the detail. */
+    rejected?: ReadonlyMap<string, DependencyProblemCode>;
+    bindings: ReadonlyMap<string, BundleBinding>;
+}
+/**
+ * The local resolver: each alias reads through the backend the caller bound to it. One
+ * delete-tolerant batch read per alias per `resolve` call. When a batch names a missing target,
+ * a backend whose `readMany` fails on the absent id (as the shipped backends do) costs one extra
+ * `read()` per id in that alias's batch, through `readManyExisting`'s per-id fallback.
+ *
+ * `backlinks()` always returns `[]`: a local reader has no index of who links into a bundle, and
+ * scanning other bound copies for inbound links is deferred until something needs it.
+ */
+export declare function createLocalResolver(options: LocalResolverOptions): BundleResolver;
+export interface QualifiedLinkResolution {
+    link: QualifiedLink;
+    resolution: Resolution;
+}
+/**
+ * Resolve parsed links (from {@link parseQualifiedLinks}) in one `resolve` call. A malformed href
+ * is `invalid_ref` here without reaching the resolver, and carries the parser's detail.
+ */
+export declare function resolveQualifiedLinks(resolver: BundleResolver, links: readonly QualifiedLink[]): Promise<QualifiedLinkResolution[]>;
+//# sourceMappingURL=cross-bundle.d.ts.map

package/dist/cross-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-bundle.d.ts","sourceRoot":"","sources":["../src/cross-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAmB,aAAa,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/F,OAAO,EAAiB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC5F,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAc,cAAc,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE9F;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,cAAc,GACd,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,GACf,aAAa,CAAC;AAElB,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAOxD,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAIpD,CAAC;AAEH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAEhE;AAED,iGAAiG;AACjG,eAAO,MAAM,qBAAqB,qDAAqD,CAAC;AAExF,MAAM,MAAM,UAAU,GAClB;IACE,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB,GACD;IACE,KAAK,EAAE,YAAY,CAAC;IACpB,6CAA6C;IAC7C,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;IACzB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,SAAS,CAAA;KAAE,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,6DAA6D;IAC7D,OAAO,CAAC,IAAI,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC9D,SAAS,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,SAAS,CAAA;KAAE,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAChH;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iHAAiH;AACjH,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjG,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,CAAC;IACxB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,wGAAwG;IACxG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,GAAG,CAAC,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,aAAa,CAAC;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IACtD,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC9C;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CA8EjF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,SAAS,aAAa,EAAE,GAC9B,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAcpC"}

package/dist/cross-bundle.js

@@ -0,0 +1,186 @@
+/**
+ * Cross-bundle link resolution: the resolver interface every backend implements, and the local
+ * resolver over explicitly bound {@link StorageBackend}s.
+ *
+ * Resolution is always explicit. A resolver reads only the copies it was constructed with; nothing
+ * is fetched or discovered. Browser-safe: bindings are backends, never filesystem paths, and pin
+ * checks are injected (the CLI probes git; core never spawns a process).
+ */
+import { readManyExisting } from "./engine.js";
+import { InvalidInputError } from "./errors.js";
+import { qualifiedHref } from "./qualified-links.js";
+export const UNRESOLVED_REASONS = Object.freeze([
+    "bundle_unavailable",
+    "pin_mismatch",
+    "target_missing",
+    "not_authorized",
+    "unknown_alias",
+    "invalid_ref",
+]);
+/**
+ * The reasons that are the referring document's fault (fix the link or the target). The others
+ * (`bundle_unavailable`, `pin_mismatch`, `not_authorized`) describe the reader's environment or
+ * access, and a check must not blame the document for them.
+ */
+export const RECORD_REASONS = Object.freeze([
+    "target_missing",
+    "unknown_alias",
+    "invalid_ref",
+]);
+export function isRecordReason(reason) {
+    return RECORD_REASONS.includes(reason);
+}
+/** The one detail every `not_authorized` result carries, so it says nothing about the target. */
+export const NOT_AUTHORIZED_DETAIL = "the reader is not authorized to read this bundle";
+function hrefOf(ref) {
+    try {
+        return { href: qualifiedHref(ref), valid: true };
+    }
+    catch (error) {
+        if (error instanceof InvalidInputError)
+            return { href: `okf://${ref.alias}/${ref.id}.md`, valid: false };
+        throw error;
+    }
+}
+function errorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The per-alias verdict before any document is read: null when the copy may be read. */
+async function bindingVerdict(entry, binding) {
+    if (!binding)
+        return { reason: "bundle_unavailable", detail: `no copy of '${entry.bundle_id}' is bound for alias '${entry.alias}'` };
+    if (binding.identity === undefined) {
+        return { reason: "bundle_unavailable", detail: `${binding.label} declares no bundle_id; expected '${entry.bundle_id}'` };
+    }
+    if (binding.identity !== entry.bundle_id) {
+        return { reason: "bundle_unavailable", detail: `${binding.label} is '${binding.identity}', not '${entry.bundle_id}'` };
+    }
+    const pin = entry.pin;
+    if (!pin)
+        return null;
+    if (pin.kind === "digest")
+        return { reason: "pin_mismatch", detail: "digest pins are verified by a hosted resolver" };
+    if (!binding.pin)
+        return { reason: "pin_mismatch", detail: `no pin check is available for ${binding.label}` };
+    try {
+        const verdict = await binding.pin({ kind: "commit", value: pin.value });
+        return verdict.ok ? null : { reason: "pin_mismatch", detail: verdict.detail };
+    }
+    catch (error) {
+        return { reason: "pin_mismatch", detail: `pin check failed: ${errorDetail(error)}` };
+    }
+}
+/**
+ * The local resolver: each alias reads through the backend the caller bound to it. One
+ * delete-tolerant batch read per alias per `resolve` call. When a batch names a missing target,
+ * a backend whose `readMany` fails on the absent id (as the shipped backends do) costs one extra
+ * `read()` per id in that alias's batch, through `readManyExisting`'s per-id fallback.
+ *
+ * `backlinks()` always returns `[]`: a local reader has no index of who links into a bundle, and
+ * scanning other bound copies for inbound links is deferred until something needs it.
+ */
+export function createLocalResolver(options) {
+    const { dependencies, bindings, rejected } = options;
+    return {
+        kind: "local",
+        dependencies,
+        async resolve(refs) {
+            const out = new Array(refs.length);
+            const unresolved = (i, ref, href, reason, detail, bundleId) => {
+                const row = { state: "unresolved", ref, href, reason, detail };
+                if (bundleId !== undefined)
+                    row.bundle_id = bundleId;
+                out[i] = row;
+            };
+            // alias -> indexes of the refs that reached the read stage
+            const pending = new Map();
+            const verdicts = new Map();
+            const hrefs = [];
+            for (let i = 0; i < refs.length; i++) {
+                const ref = refs[i];
+                const { href, valid } = hrefOf(ref);
+                hrefs[i] = href;
+                if (!valid) {
+                    unresolved(i, null, href, "invalid_ref", "not a valid cross-bundle target");
+                    continue;
+                }
+                const entry = dependencies.get(ref.alias);
+                if (!entry) {
+                    const code = rejected?.get(ref.alias);
+                    unresolved(i, ref, href, "unknown_alias", code === undefined
+                        ? `alias '${ref.alias}' is not declared in docs/dependencies`
+                        : `alias '${ref.alias}' is declared but rejected (${code})`);
+                    continue;
+                }
+                if (!verdicts.has(ref.alias))
+                    verdicts.set(ref.alias, bindingVerdict(entry, bindings.get(ref.alias)));
+                const indexes = pending.get(ref.alias) ?? [];
+                indexes.push(i);
+                pending.set(ref.alias, indexes);
+            }
+            for (const [alias, indexes] of pending) {
+                const entry = dependencies.get(alias);
+                const verdict = await verdicts.get(alias);
+                if (verdict) {
+                    for (const i of indexes)
+                        unresolved(i, refs[i], hrefs[i], verdict.reason, verdict.detail, entry.bundle_id);
+                    continue;
+                }
+                const binding = bindings.get(alias);
+                const ids = [...new Set(indexes.map((i) => refs[i].id))];
+                const malformed = new Map();
+                let found;
+                try {
+                    const results = await readManyExisting(binding.backend, ids, (skip) => malformed.set(skip.id, skip.reason));
+                    found = new Map(results.map((result) => [result.doc.id, result]));
+                }
+                catch (error) {
+                    const detail = `${binding.label} could not be read: ${errorDetail(error)}`;
+                    for (const i of indexes)
+                        unresolved(i, refs[i], hrefs[i], "bundle_unavailable", detail, entry.bundle_id);
+                    continue;
+                }
+                for (const i of indexes) {
+                    const ref = refs[i];
+                    const hit = found.get(ref.id);
+                    if (hit) {
+                        out[i] = { state: "resolved", ref, bundle_id: entry.bundle_id, document: hit.doc, version: hit.version };
+                    }
+                    else {
+                        const why = malformed.get(ref.id);
+                        const detail = why === undefined
+                            ? `'${ref.id}' is not in ${binding.label}`
+                            : `'${ref.id}' in ${binding.label} is malformed: ${why}`;
+                        unresolved(i, ref, hrefs[i], "target_missing", detail, entry.bundle_id);
+                    }
+                }
+            }
+            return out;
+        },
+        async backlinks() {
+            return [];
+        },
+    };
+}
+/**
+ * Resolve parsed links (from {@link parseQualifiedLinks}) in one `resolve` call. A malformed href
+ * is `invalid_ref` here without reaching the resolver, and carries the parser's detail.
+ */
+export async function resolveQualifiedLinks(resolver, links) {
+    const refs = [];
+    for (const link of links)
+        if (link.ref)
+            refs.push(link.ref);
+    const resolved = await resolver.resolve(refs);
+    let next = 0;
+    return links.map((link) => {
+        if (!link.ref) {
+            return {
+                link,
+                resolution: { state: "unresolved", ref: null, href: link.href, reason: "invalid_ref", detail: link.detail ?? "malformed cross-bundle link" },
+            };
+        }
+        return { link, resolution: resolved[next++] };
+    });
+}
+//# sourceMappingURL=cross-bundle.js.map

package/dist/cross-bundle.js.map

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

package/dist/dependencies.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Bundle identity and the `docs/dependencies` declaration.
+ *
+ * A bundle names the other bundles it links into in ONE committed document, `docs/dependencies`
+ * (type `Bundle Dependencies`). Each entry maps a local alias (the `<alias>` in
+ * `okf://<alias>/<path>.md`) to the target's portable `bundle_id`, plus optional `source`, `pin`
+ * and `path`. A target confirms its own identity with `bundle_id` in its `docs/bundle` document.
+ *
+ * Pure and browser-safe: no `node:*` import, no I/O. Consumers read the documents through their
+ * own backend and hand them here.
+ */
+import type { OkfDocument } from "./types.js";
+/** True when `id` is a portable bundle id (the hosted bundle-id grammar). */
+export declare function isHostedBundleId(id: string): boolean;
+/**
+ * The well-known concept id carrying a bundle's explicit display name and portable id. NOT the
+ * bundle-root `index.md` — OKF §3.1 reserves that file's frontmatter solely for `okf_version`, so
+ * the name needs its own small doc.
+ */
+export declare const BUNDLE_NAME_DOC_ID = "docs/bundle";
+/**
+ * The ownership marker: `docs/bundle` speaks for the bundle ONLY when it carries exactly this
+ * `type`. A `docs/bundle` doc of any other type is an ordinary document and is ignored, so an
+ * unrelated pre-existing doc is never appropriated as the bundle's name or id.
+ */
+export declare const BUNDLE_NAME_DOC_TYPE = "Bundle Name";
+/**
+ * The bundle's self-declared portable id: `bundle_id` in `docs/bundle` under the marker type, when
+ * it satisfies {@link isHostedBundleId}. Anything else (absent doc, other type, missing or
+ * malformed id) is `undefined`; the caller decides what a bundle without a declared id means.
+ */
+export declare function declaredBundleId(doc: OkfDocument | null | undefined): string | undefined;
+export declare const DEPENDENCIES_DOC_ID = "docs/dependencies";
+export declare const DEPENDENCIES_DOC_TYPE = "Bundle Dependencies";
+/** The alias grammar shared by `okf://<alias>/…` hrefs, dependency keys and qualified Kind targets. */
+export declare const BUNDLE_ALIAS: RegExp;
+export declare function isBundleAlias(alias: string): boolean;
+/**
+ * A dependency pin. Hex is lower-case only; an upper-case pin is rejected (`DEP_PIN`) rather than
+ * folded, so the declaration is the exact string git and a host compare. A `commit` pin (7-40 hex) is checked by an injected `PinCheck` against the
+ * bound copy's subtree. A `digest` pin (`sha256:<64 hex>`) parses, but only a hosted resolver can
+ * verify it; a local resolver fails it closed.
+ */
+export type DependencyPin = {
+    kind: "commit";
+    value: string;
+} | {
+    kind: "digest";
+    value: string;
+};
+export interface DependencyEntry {
+    alias: string;
+    bundle_id: string;
+    /** Where to get the bundle (git URL or `hosted:<host>/<bundle_id>`). Informational only. */
+    source?: string;
+    pin?: DependencyPin;
+    /** Relative to the declaring bundle's root; used only by an explicit `--with-deps`. */
+    path?: string;
+}
+/** Alias -> entry. A Map, so an alias such as `constructor` can never hit an inherited property. */
+export type DependencyMap = ReadonlyMap<string, DependencyEntry>;
+export type DependencyProblemCode = "DEP_TYPE" | "DEP_SHAPE" | "DEP_ALIAS" | "DEP_BUNDLE_ID" | "DEP_PIN" | "DEP_PATH_ABSOLUTE" | "DEP_DUPLICATE_BUNDLE" | "DEP_SELF" | "DEP_UNKNOWN_KEY" | "DEP_RESERVED_KEY";
+export interface DependencyProblem {
+    code: DependencyProblemCode;
+    alias?: string;
+    detail: string;
+}
+export interface ParsedDependencies {
+    dependencies: DependencyMap;
+    problems: DependencyProblem[];
+    /**
+     * Aliases that are declared but whose entry was dropped, with the code that dropped it, so a
+     * link under one can say "declared but rejected" instead of "not declared".
+     */
+    rejected: ReadonlyMap<string, DependencyProblemCode>;
+}
+export interface ParseDependenciesOptions {
+    /** The declaring bundle's own id; an entry naming it is `DEP_SELF`. */
+    selfBundleId?: string;
+}
+/**
+ * Absolute under POSIX or win32 rules, or carrying a backslash. Pure string checks (no
+ * `node:path`) so the verdict is the same on every host: `/x`, `\x`, `\\server\share`, `C:\x`,
+ * `C:/x` and the drive-relative `C:x` are all refused.
+ */
+export declare function isNonPortableDependencyPath(value: string): boolean;
+/**
+ * Parse `docs/dependencies`. Never throws: every defect is a problem, and an entry whose alias,
+ * `bundle_id` or `pin` is unusable is dropped (fail closed: a link under it reads as
+ * `unknown_alias`, never as resolved against the wrong copy). An unusable `source` or `path` drops
+ * only that field. Unknown and reserved keys are reported and the entry is kept.
+ */
+export declare function parseDependencies(doc: OkfDocument | null | undefined, options?: ParseDependenciesOptions): ParsedDependencies;
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../src/dependencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAY9C,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAMxF;AAID,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AACvD,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D,uGAAuG;AACvG,eAAO,MAAM,YAAY,QAA2B,CAAC;AAErD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oGAAoG;AACpG,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEjE,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,SAAS,GACT,mBAAmB,GACnB,sBAAsB,GACtB,UAAU,GACV,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,aAAa,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B;;;OAGG;IACH,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAaD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElE;AASD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,CAyFpB"}

package/dist/dependencies.js

@@ -0,0 +1,180 @@
+/**
+ * Bundle identity and the `docs/dependencies` declaration.
+ *
+ * A bundle names the other bundles it links into in ONE committed document, `docs/dependencies`
+ * (type `Bundle Dependencies`). Each entry maps a local alias (the `<alias>` in
+ * `okf://<alias>/<path>.md`) to the target's portable `bundle_id`, plus optional `source`, `pin`
+ * and `path`. A target confirms its own identity with `bundle_id` in its `docs/bundle` document.
+ *
+ * Pure and browser-safe: no `node:*` import, no I/O. Consumers read the documents through their
+ * own backend and hand them here.
+ */
+// ── Bundle identity ─────────────────────────────────────────────────────────
+// A portable bundle id: lower-case letters and digits joined by `.`, `_` or `-`, starting with a
+// letter, at most 128 characters. The one rule hosted `checkout`, `export` and `publish` accept an
+// id by, and the one a printed `checkout <id>` command is emitted for: an id it rejects (one
+// starting with `-` would read as an option) never appears in a command.
+const BUNDLE_ID = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const BUNDLE_ID_MAX_LENGTH = 128;
+/** True when `id` is a portable bundle id (the hosted bundle-id grammar). */
+export function isHostedBundleId(id) {
+    return id.length <= BUNDLE_ID_MAX_LENGTH && BUNDLE_ID.test(id);
+}
+/**
+ * The well-known concept id carrying a bundle's explicit display name and portable id. NOT the
+ * bundle-root `index.md` — OKF §3.1 reserves that file's frontmatter solely for `okf_version`, so
+ * the name needs its own small doc.
+ */
+export const BUNDLE_NAME_DOC_ID = "docs/bundle";
+/**
+ * The ownership marker: `docs/bundle` speaks for the bundle ONLY when it carries exactly this
+ * `type`. A `docs/bundle` doc of any other type is an ordinary document and is ignored, so an
+ * unrelated pre-existing doc is never appropriated as the bundle's name or id.
+ */
+export const BUNDLE_NAME_DOC_TYPE = "Bundle Name";
+/**
+ * The bundle's self-declared portable id: `bundle_id` in `docs/bundle` under the marker type, when
+ * it satisfies {@link isHostedBundleId}. Anything else (absent doc, other type, missing or
+ * malformed id) is `undefined`; the caller decides what a bundle without a declared id means.
+ */
+export function declaredBundleId(doc) {
+    if (!doc || doc.id !== BUNDLE_NAME_DOC_ID)
+        return undefined;
+    const type = doc.frontmatter.type;
+    if (typeof type !== "string" || type.trim() !== BUNDLE_NAME_DOC_TYPE)
+        return undefined;
+    const id = doc.frontmatter.bundle_id;
+    return typeof id === "string" && isHostedBundleId(id) ? id : undefined;
+}
+// ── docs/dependencies ───────────────────────────────────────────────────────
+export const DEPENDENCIES_DOC_ID = "docs/dependencies";
+export const DEPENDENCIES_DOC_TYPE = "Bundle Dependencies";
+/** The alias grammar shared by `okf://<alias>/…` hrefs, dependency keys and qualified Kind targets. */
+export const BUNDLE_ALIAS = /^[a-z][a-z0-9-]{0,62}$/;
+export function isBundleAlias(alias) {
+    return BUNDLE_ALIAS.test(alias);
+}
+const KNOWN_KEYS = new Set(["bundle_id", "source", "pin", "path"]);
+/** Reserved for recipe dependencies, which will reuse this declaration. */
+const RESERVED_KEYS = new Set(["use", "version", "channel"]);
+const COMMIT_PIN = /^[0-9a-f]{7,40}$/;
+const DIGEST_PIN = /^sha256:[0-9a-f]{64}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
+/**
+ * Absolute under POSIX or win32 rules, or carrying a backslash. Pure string checks (no
+ * `node:path`) so the verdict is the same on every host: `/x`, `\x`, `\\server\share`, `C:\x`,
+ * `C:/x` and the drive-relative `C:x` are all refused.
+ */
+export function isNonPortableDependencyPath(value) {
+    return value.startsWith("/") || value.includes("\\") || /^[A-Za-z]:/.test(value);
+}
+function parsePin(value) {
+    if (typeof value !== "string")
+        return null;
+    if (COMMIT_PIN.test(value))
+        return { kind: "commit", value };
+    if (DIGEST_PIN.test(value))
+        return { kind: "digest", value };
+    return null;
+}
+/**
+ * Parse `docs/dependencies`. Never throws: every defect is a problem, and an entry whose alias,
+ * `bundle_id` or `pin` is unusable is dropped (fail closed: a link under it reads as
+ * `unknown_alias`, never as resolved against the wrong copy). An unusable `source` or `path` drops
+ * only that field. Unknown and reserved keys are reported and the entry is kept.
+ */
+export function parseDependencies(doc, options = {}) {
+    const dependencies = new Map();
+    const problems = [];
+    const rejected = new Map();
+    const result = () => ({ dependencies, problems, rejected });
+    const reject = (alias, code, detail) => {
+        problems.push({ code, alias, detail });
+        rejected.set(alias, code);
+    };
+    if (!doc)
+        return result();
+    const type = doc.frontmatter.type;
+    if (typeof type !== "string" || type.trim() !== DEPENDENCIES_DOC_TYPE) {
+        problems.push({ code: "DEP_TYPE", detail: `type must be '${DEPENDENCIES_DOC_TYPE}'` });
+        return result();
+    }
+    const declared = doc.frontmatter.dependencies;
+    if (declared === undefined || declared === null)
+        return result();
+    if (!isRecord(declared)) {
+        problems.push({ code: "DEP_SHAPE", detail: "dependencies must be a mapping of alias to entry" });
+        return result();
+    }
+    const aliasByBundle = new Map();
+    for (const [alias, raw] of Object.entries(declared)) {
+        if (!isBundleAlias(alias)) {
+            problems.push({ code: "DEP_ALIAS", alias, detail: "alias must match ^[a-z][a-z0-9-]{0,62}$" });
+            continue;
+        }
+        if (!isRecord(raw)) {
+            reject(alias, "DEP_SHAPE", "entry must be a mapping");
+            continue;
+        }
+        const bundleId = raw.bundle_id;
+        if (typeof bundleId !== "string" || !isHostedBundleId(bundleId)) {
+            reject(alias, "DEP_BUNDLE_ID", "bundle_id is required and must be a portable bundle id");
+            continue;
+        }
+        let pin;
+        if (raw.pin !== undefined) {
+            const parsed = parsePin(raw.pin);
+            if (parsed === null) {
+                // A YAML scalar such as 1234567 or 3e45678 arrives as a number, so the hint says to quote.
+                reject(alias, "DEP_PIN", "pin must be a quoted commit (7-40 lower-case hex) or sha256:<64 lower-case hex>");
+                continue;
+            }
+            pin = parsed;
+        }
+        if (options.selfBundleId !== undefined && bundleId === options.selfBundleId) {
+            reject(alias, "DEP_SELF", `bundle_id '${bundleId}' is this bundle`);
+            continue;
+        }
+        const earlier = aliasByBundle.get(bundleId);
+        if (earlier !== undefined) {
+            reject(alias, "DEP_DUPLICATE_BUNDLE", `bundle_id '${bundleId}' is already declared as '${earlier}'`);
+            continue;
+        }
+        const entry = { alias, bundle_id: bundleId };
+        if (raw.source !== undefined) {
+            if (typeof raw.source === "string" && raw.source.trim() !== "")
+                entry.source = raw.source;
+            else
+                problems.push({ code: "DEP_SHAPE", alias, detail: "source must be a non-empty string" });
+        }
+        if (pin)
+            entry.pin = pin;
+        if (raw.path !== undefined) {
+            if (typeof raw.path !== "string" || raw.path.trim() === "") {
+                problems.push({ code: "DEP_SHAPE", alias, detail: "path must be a non-empty string" });
+            }
+            else if (isNonPortableDependencyPath(raw.path)) {
+                problems.push({ code: "DEP_PATH_ABSOLUTE", alias, detail: "path must be relative to this bundle's root, with '/' separators" });
+            }
+            else {
+                entry.path = raw.path;
+            }
+        }
+        for (const key of Object.keys(raw)) {
+            if (KNOWN_KEYS.has(key))
+                continue;
+            if (RESERVED_KEYS.has(key)) {
+                problems.push({ code: "DEP_RESERVED_KEY", alias, detail: `'${key}' is reserved for recipe dependencies` });
+            }
+            else {
+                problems.push({ code: "DEP_UNKNOWN_KEY", alias, detail: `unknown key '${key}'` });
+            }
+        }
+        aliasByBundle.set(bundleId, alias);
+        dependencies.set(alias, entry);
+    }
+    return result();
+}
+//# sourceMappingURL=dependencies.js.map

package/dist/dependencies.js.map

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

package/dist/engine.d.ts

@@ -36,6 +36,13 @@ export declare function readDoc(backend: StorageBackend, id: ConceptId): Promise
 export declare function existsDoc(backend: StorageBackend, id: ConceptId): Promise<boolean>;
 export declare function docVersions(backend: StorageBackend, id: ConceptId): Promise<VersionInfo[]>;
 export declare function deleteDoc(backend: StorageBackend, id: ConceptId, options?: DeleteOptions): Promise<boolean>;
+/**
+ * Delete-tolerant batch read: one `readMany`, falling back to per-id reads only when the batch
+ * fails because an id vanished (or, with `onMalformed`, because one document is malformed).
+ * Absent ids are simply missing from the result. Shared by the scan path and the cross-bundle
+ * resolver, which issues one call per bound alias.
+ */
+export declare function readManyExisting(backend: StorageBackend, ids: ConceptId[], onMalformed?: (skip: SkippedDoc) => void): Promise<ReadResult[]>;
 export declare function query(backend: StorageBackend, filter?: QueryFilter, options?: QueryOptions): Promise<OkfDocument[]>;
 export declare const list: typeof query;
 export declare function queryHeads(backend: StorageBackend, filter?: QueryFilter, options?: QueryOptions): Promise<HeadResult[]>;