@superbee/core 0.1.0

package/dist/index-projection.js

@@ -0,0 +1,245 @@
+/**
+ * Portable `index.md` projection policy.
+ *
+ * Concept heads are authoritative. Index files are deterministic, replaceable views over
+ * one observed head set. Planning is pure; preparation reads and classifies EVERY target
+ * before a write; application uses those exact versions with single-shot CAS. A conflict
+ * stops the batch instead of silently re-deciding one file outside the global preflight.
+ */
+import { backendFor } from "./bundle.js";
+import { InvalidInputError } from "./errors.js";
+import { parseMarkdown, stringifyWithData } from "./frontmatter.js";
+import { GENERATED_INDEX_MARKER } from "./index-marker.js";
+import { assertSafeConceptId, toPosix } from "./paths.js";
+export { GENERATED_INDEX_MARKER } from "./index-marker.js";
+/** A terminal per-file failure after zero or more earlier targets completed. */
+export class IndexProjectionWriteError extends Error {
+    name = "IndexProjectionWriteError";
+    failed;
+    completed;
+    pending;
+    constructor(failed, completed, pending, cause) {
+        super(`index projection write failed at '${displayDir(failed)}'`, { cause });
+        this.failed = failed;
+        this.completed = completed;
+        this.pending = pending;
+    }
+}
+function displayDir(dir) {
+    return dir === "" ? "index.md" : `${dir}/index.md`;
+}
+/** Collapse frontmatter display text to one Markdown line. */
+function inlineText(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const collapsed = value.replace(/\s+/g, " ").trim();
+    return collapsed === "" ? undefined : collapsed;
+}
+function escapeLabel(value) {
+    return value.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+}
+/** URL-encode each path segment while preserving hierarchy and the `.md` suffix. */
+function hrefSegment(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function ensureDirectory(map, dir) {
+    const existing = map.get(dir);
+    if (existing)
+        return existing;
+    const created = { direct: [], children: new Set() };
+    map.set(dir, created);
+    return created;
+}
+function depth(dir) {
+    return dir === "" ? 0 : dir.split("/").length;
+}
+/** Locale-independent code-unit ordering keeps projection bytes portable across hosts. */
+function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Plan root + every ancestor directory from ONE complete `queryHeads`-shaped set.
+ * The caller supplies the root display name; core never derives it from a local path or URL.
+ */
+export function planIndexProjection(displayName, heads) {
+    const directories = new Map();
+    ensureDirectory(directories, "");
+    for (const head of heads) {
+        assertSafeConceptId(head.id);
+        const normalized = toPosix(head.id).replace(/^\.\//, "");
+        const segments = normalized.split("/");
+        const conceptName = segments.pop();
+        let parent = "";
+        for (const child of segments) {
+            const next = parent === "" ? child : `${parent}/${child}`;
+            ensureDirectory(directories, parent).children.add(child);
+            ensureDirectory(directories, next);
+            parent = next;
+        }
+        ensureDirectory(directories, parent).direct.push({ ...head, id: parent === "" ? conceptName : `${parent}/${conceptName}` });
+    }
+    const rootTitle = inlineText(displayName) ?? "bundle";
+    const targets = [...directories.entries()]
+        .sort(([a], [b]) => compareText(a, b))
+        .map(([dir, projection]) => {
+        const groups = new Map();
+        const prefix = dir === "" ? "" : `${dir}/`;
+        for (const head of projection.direct) {
+            const fileName = head.id.slice(prefix.length);
+            const type = inlineText(head.frontmatter.type) ?? "Concept";
+            const title = inlineText(head.frontmatter.title) ?? fileName;
+            const description = inlineText(head.frontmatter.description);
+            const href = `${hrefSegment(fileName)}.md`;
+            const bullet = `* [${escapeLabel(title)}](${href})${description ? ` - ${description}` : ""}`;
+            const group = groups.get(type) ?? [];
+            group.push(bullet);
+            groups.set(type, group);
+        }
+        const sections = [];
+        for (const type of [...groups.keys()].sort()) {
+            sections.push(`# ${type}\n\n${groups.get(type).sort().join("\n")}\n`);
+        }
+        if (projection.children.size > 0) {
+            const bullets = [...projection.children]
+                .sort()
+                .map((child) => `* [${escapeLabel(child)}](${hrefSegment(child)}/index.md)`);
+            sections.push(`# Subdirectories\n\n${bullets.join("\n")}\n`);
+        }
+        const title = dir === "" ? rootTitle : inlineText(dir.split("/").pop()) ?? "directory";
+        const body = `${GENERATED_INDEX_MARKER}\n# ${title}\n\n${sections.join("\n")}`.trimEnd() + "\n";
+        return { dir, body };
+    });
+    return { targets };
+}
+function markerOwnership(body) {
+    const lines = body.split("\n");
+    const exact = lines.filter((line) => line === GENERATED_INDEX_MARKER).length;
+    const markerLike = lines.filter((line) => /^\s*<!--\s*agentstate-lite:generated-index(?::[^>]*)?\s*-->\s*$/.test(line)).length;
+    if (exact > 1)
+        return { owned: false, reason: "duplicate-marker" };
+    if (exact === 1 && markerLike === 1 && lines[0] === GENERATED_INDEX_MARKER)
+        return { owned: true };
+    if (markerLike > 0)
+        return { owned: false, reason: "malformed-marker" };
+    return { owned: false, reason: "unmarked" };
+}
+function inspectExisting(dir, content) {
+    if (dir === "") {
+        try {
+            const { frontmatter, body } = parseMarkdown(content, "index.md");
+            const keys = Object.keys(frontmatter);
+            if (keys.length !== 1 || keys[0] !== "okf_version" || typeof frontmatter.okf_version !== "string") {
+                return { owned: false, body, reason: "malformed-root" };
+            }
+            return {
+                ...markerOwnership(body),
+                body,
+                okfVersion: frontmatter.okf_version,
+            };
+        }
+        catch {
+            return { owned: false, body: content, reason: "malformed-root" };
+        }
+    }
+    try {
+        const { frontmatter, body } = parseMarkdown(content, `${dir}/index.md`);
+        if (Object.keys(frontmatter).length > 0) {
+            return { owned: false, body, reason: "nested-frontmatter" };
+        }
+        return { ...markerOwnership(body), body };
+    }
+    catch {
+        return { owned: false, body: content, reason: "nested-frontmatter" };
+    }
+}
+function desiredContent(dir, body, okfVersion) {
+    return dir === "" ? stringifyWithData({ okf_version: okfVersion ?? "0.1" }, body) : body;
+}
+/**
+ * Read and classify every planned target before any write. A single refusal blocks the
+ * whole preparation; `force` makes each unmarked/malformed target an explicit adoption.
+ */
+export async function prepareIndexProjection(bundle, plan, options = {}) {
+    const backend = backendFor(bundle);
+    const targets = [];
+    for (const planned of plan.targets) {
+        const current = await backend.readReserved(planned.dir, "index.md");
+        if (current === null) {
+            targets.push({
+                dir: planned.dir,
+                content: desiredContent(planned.dir, planned.body),
+                expectedVersion: null,
+                disposition: "missing",
+            });
+            continue;
+        }
+        const ownership = inspectExisting(planned.dir, current.content);
+        const content = desiredContent(planned.dir, planned.body, ownership.okfVersion);
+        if (ownership.owned) {
+            targets.push({
+                dir: planned.dir,
+                content,
+                expectedVersion: current.version,
+                disposition: current.content === content ? "unchanged" : "generated",
+            });
+        }
+        else if (options.force) {
+            targets.push({
+                dir: planned.dir,
+                content,
+                expectedVersion: current.version,
+                disposition: "adopted",
+                ...(ownership.reason ? { reason: ownership.reason } : {}),
+            });
+        }
+        else {
+            targets.push({
+                dir: planned.dir,
+                content,
+                expectedVersion: current.version,
+                disposition: "refused",
+                ...(ownership.reason ? { reason: ownership.reason } : {}),
+            });
+        }
+    }
+    const refused = targets.filter((target) => target.disposition === "refused");
+    return refused.length > 0
+        ? { ready: false, targets, refused }
+        : { ready: true, targets, refused: [] };
+}
+function writableDisposition(disposition) {
+    return disposition === "missing" || disposition === "generated" || disposition === "adopted";
+}
+/**
+ * Apply a ready preparation deepest-first and root-last. Each target gets ONE CAS attempt
+ * against the version captured during global preparation; a conflict is terminal and reports
+ * completed/pending paths so a full re-prepare can resume idempotently.
+ */
+export async function applyIndexProjection(bundle, prepared, options = {}) {
+    if (!prepared.ready) {
+        throw new InvalidInputError("Cannot apply a refused index projection; re-prepare with explicit force to adopt it.");
+    }
+    const backend = backendFor(bundle);
+    const unchanged = prepared.targets
+        .filter((target) => target.disposition === "unchanged")
+        .map((target) => target.dir);
+    const writable = prepared.targets
+        .filter((target) => writableDisposition(target.disposition))
+        .sort((a, b) => depth(b.dir) - depth(a.dir) || compareText(a.dir, b.dir));
+    const completed = [];
+    for (let index = 0; index < writable.length; index++) {
+        const target = writable[index];
+        try {
+            const version = await backend.writeReserved(target.dir, "index.md", target.content, {
+                expectedVersion: target.expectedVersion,
+                ...(options.actor !== undefined ? { actor: options.actor } : {}),
+            });
+            completed.push({ dir: target.dir, disposition: target.disposition, version });
+        }
+        catch (cause) {
+            throw new IndexProjectionWriteError(target.dir, completed, writable.slice(index + 1).map((pending) => pending.dir), cause);
+        }
+    }
+    return { completed, unchanged, pending: [] };
+}
+//# sourceMappingURL=index-projection.js.map

package/dist/index-projection.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `@superbee/core` — the OKF store engine.
+ *
+ * An **Open Knowledge Format (OKF v0.1 or v0.2)** *Knowledge Bundle* is a
+ * directory tree of UTF-8 markdown files, each carrying a YAML frontmatter block
+ * (delimited by `---` lines) plus a markdown body. Every non-reserved `.md` file
+ * is a *Concept*; its *Concept ID* is the file path minus `.md`
+ * (e.g. `tables/users.md` -> `tables/users`).
+ *
+ * The FILESYSTEM is the source of truth by default, but storage is routed through
+ * a pluggable {@link StorageBackend} (default: {@link FilesystemBackend}). This
+ * module implements bundle I/O, standard-markdown cross-links (never wikilinks),
+ * derived backlinks, freshness derived from the edition's meaningful-change clock, and reserved-file
+ * (`index.md`/`log.md`) handling. Human-facing bundle Pages consume this engine through the
+ * reference server's narrow browser bridge (read-only v0 plus shell-confirmed local proposals).
+ *
+ * The public function signatures below are contract-stable; everything past the
+ * "extensions" line is additive (pure helpers, reserved-file accessors, and the
+ * ported content_type utilities).
+ *
+ * @see OKF spec — GoogleCloudPlatform/knowledge-catalog, `okf/SPEC.md`
+ * @packageDocumentation
+ */
+export type { ConceptId, Frontmatter, OkfDocument, Bundle, InitBundleOptions, QueryFilter, Link, EdgeFilter, FreshnessVerdict, FreshnessOptions, FreshnessResult, ReservedFilename, StorageBackend, StorageCapabilities, Version, ReadResult, ReservedReadResult, VersionInfo, WriteOptions, DeleteOptions, } from "./types.js";
+export { initBundle, readBundleOkfVersion, resolveOkfAuthoringVersion, DEFAULT_OKF_AUTHORING_VERSION, SUPPORTED_OKF_AUTHORING_VERSIONS, writeDoc, readDoc, existsDoc, query, parseLinks, backlinks, queryEdges, } from "./bundle.js";
+export { writeDocVersioned, readDocVersioned, docVersions } from "./bundle.js";
+export type { WriteResult } from "./bundle.js";
+export { deleteDoc, deleteBlob } from "./bundle.js";
+export { readBlob, writeBlob, existsBlob, listBlobs } from "./bundle.js";
+export type { BlobKey, ReadBlobResult } from "./types.js";
+export { freshness } from "./freshness.js";
+export { FilesystemBackend } from "./backend.js";
+export { MemoryBackend } from "./memory-backend.js";
+export { withFilesystemMutationLock, FilesystemMutationLockError, filesystemMutationLockPath, } from "./filesystem-lock.js";
+export type { FilesystemMutationLockOptions, FilesystemMutationLockOwner, } from "./filesystem-lock.js";
+export { RemoteBackend, RemoteError } from "./remote-backend.js";
+export type { FetchLike, RemoteBackendOptions } from "./remote-backend.js";
+export { contentVersion, versionOfBytes, blobVersion, defaultActor, VersionConflict, stripETagWrapper, } from "./versioning.js";
+export { versionedMutation } from "./mutation.js";
+export type { MutationDecision, VersionedMutationOptions, VersionedMutationOutcome } from "./mutation.js";
+export { mutateDocument, DocumentNotFoundError, KindConformanceError, } from "./document-mutation.js";
+export type { DocumentMutationCandidate, DocumentMutationContext, DocumentMutationMode, DocumentMutationResult, MutateDocumentOptions, } from "./document-mutation.js";
+export { PreconditionFailed, assertFieldPreconditions } from "./document-precondition.js";
+export type { FieldExpectation, FieldPrecondition } from "./document-precondition.js";
+export { list } from "./bundle.js";
+export type { QueryOptions, SkippedDoc } from "./bundle.js";
+export { queryHeads } from "./bundle.js";
+export { matchesFilter } from "./query-filter.js";
+export { applyQuerySelectionFilters } from "./query-selection.js";
+export type { QuerySelectionParams } from "./query-selection.js";
+export type { HeadResult } from "./types.js";
+export { GENERATED_INDEX_MARKER, IndexProjectionWriteError, planIndexProjection, prepareIndexProjection, applyIndexProjection, } from "./index-projection.js";
+export type { PlannedIndex, IndexProjectionPlan, IndexProjectionDisposition, PreparedIndexTarget, ReadyIndexProjection, RefusedIndexProjection, IndexProjectionPreparation, AppliedIndexTarget, IndexProjectionApplyResult, } from "./index-projection.js";
+export { RESERVED_FILENAMES, isReservedFile, conceptIdFromPath, pathFromConceptId, assertSafeConceptId, assertSafeReservedDir, assertSafeBlobKey, toPosix, } from "./paths.js";
+export { extractMarkdownLinks, resolveConceptId, relativeHref, parseLinksFromDoc, isExternalHref, } from "./links.js";
+export type { RawLink } from "./links.js";
+export { parseTimestamp } from "./freshness.js";
+export { SUPERBEE_UPDATED_BY_FIELD, mutationActorFromFrontmatter, persistMutationActor, } from "./mutation-attribution.js";
+export type { PersistMutationActorOptions } from "./mutation-attribution.js";
+export { parseMarkdown, stringifyDoc, stringifyWithData, normalizeDocumentBodyForStorage, isUsableTimestamp, MalformedDocumentError, } from "./frontmatter.js";
+export { InvalidInputError, FilesystemIdentityAliasError, ConcurrentReplacementError } from "./errors.js";
+export { applyV02MutationMetadata } from "./document-write-policy.js";
+export { CONVENTIONS_PREFIX, CONVENTION_TYPE, PROGRESS_STATUS_FIELD, SUPERBEE_PROGRESS_STATUS_FIELD, RESERVED_KIND_FIELD_NAMES, progressStatusStorageField, progressStatusCoordinate, resolveKindFieldCoordinate, claimCoordinates, kindInputFieldNames, readKindField, projectLogicalKindFields, projectKindForAuthoring, projectKindValidationWarnings, validateAgainstKind, isPresent, defaultTimestampAndValidateAgainstRegistry, freshnessHorizonMs, kindConventionDoc, parseConventionDoc, buildKindRegistry, splitSections, isTerminal, } from "./kinds.js";
+export { loadKinds } from "./kinds-load.js";
+export type { KindClaimCoordinates, KindClaimPolicy, KindConvention, KindFieldCoordinate, KindFields, KindRegistry, RegistryValidationResult, } from "./kinds.js";
+export { EXTENSION_CONTENT_TYPES, extensionOfDocKey, inferContentTypeFromDocKey, inferContentTypeForNewBlob, resolveContentType, DEFAULT_BLOB_CONTENT_TYPE, } from "./content-type.js";
+export type { ContentTypeInference, ValidationWarning } from "./content-type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,WAAW,EACX,IAAI,EACJ,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,6BAA6B,EAC7B,gCAAgC,EAChC,QAAQ,EACR,OAAO,EACP,SAAS,EACT,KAAK,EACL,UAAU,EACV,SAAS,EACT,UAAU,GACX,MAAM,aAAa,CAAC;AAMrB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO/C,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAOpD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAM3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKpD,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACjE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAM3E,OAAO,EACL,cAAc,EACd,cAAc,EACd,WAAW,EACX,YAAY,EACZ,eAAe,EACf,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAI1G,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC1F,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAKtF,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM5D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,OAAO,GACR,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAE7E,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAC1G,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAMtE,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,8BAA8B,EAC9B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,EAC7B,mBAAmB,EACnB,SAAS,EACT,0CAA0C,EAC1C,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,0BAA0B,EAC1B,0BAA0B,EAC1B,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,110 @@
+/**
+ * `@superbee/core` — the OKF store engine.
+ *
+ * An **Open Knowledge Format (OKF v0.1 or v0.2)** *Knowledge Bundle* is a
+ * directory tree of UTF-8 markdown files, each carrying a YAML frontmatter block
+ * (delimited by `---` lines) plus a markdown body. Every non-reserved `.md` file
+ * is a *Concept*; its *Concept ID* is the file path minus `.md`
+ * (e.g. `tables/users.md` -> `tables/users`).
+ *
+ * The FILESYSTEM is the source of truth by default, but storage is routed through
+ * a pluggable {@link StorageBackend} (default: {@link FilesystemBackend}). This
+ * module implements bundle I/O, standard-markdown cross-links (never wikilinks),
+ * derived backlinks, freshness derived from the edition's meaningful-change clock, and reserved-file
+ * (`index.md`/`log.md`) handling. Human-facing bundle Pages consume this engine through the
+ * reference server's narrow browser bridge (read-only v0 plus shell-confirmed local proposals).
+ *
+ * The public function signatures below are contract-stable; everything past the
+ * "extensions" line is additive (pure helpers, reserved-file accessors, and the
+ * ported content_type utilities).
+ *
+ * @see OKF spec — GoogleCloudPlatform/knowledge-catalog, `okf/SPEC.md`
+ * @packageDocumentation
+ */
+// ── Contract functions ────────────────────────────────────────────────────────
+export { initBundle, readBundleOkfVersion, resolveOkfAuthoringVersion, DEFAULT_OKF_AUTHORING_VERSION, SUPPORTED_OKF_AUTHORING_VERSIONS, writeDoc, readDoc, existsDoc, query, parseLinks, backlinks, queryEdges, } from "./bundle.js";
+// Version-surfacing engine API (additive; the seam's hard-case capabilities threaded
+// through the engine): `writeDocVersioned` returns the write's version token; `readDocVersioned`
+// returns a document with its version; `docVersions` exposes attributed history. The plain
+// `writeDoc`/`readDoc` above keep their historical `OkfDocument` returns unchanged.
+export { writeDocVersioned, readDocVersioned, docVersions } from "./bundle.js";
+// Delete (additive; the DELETE-operation pass): hard-delete, non-cascading, reserved files
+// stay non-deletable (guarded at the SAME engine layer writeDocVersioned's reserved-file
+// check lives at), idempotent (absent -> false, never an error). `deleteDoc` carries the
+// engine's id-safety/reserved-file guard; `deleteBlob` is a pure pass-through, mirroring
+// the blob wrappers above.
+export { deleteDoc, deleteBlob } from "./bundle.js";
+// Blob storage engine wrappers: opaque bytes + a
+// content-type, addressed by a bundle-relative key DISJOINT from the concept-document
+// namespace, versioned by a raw-byte content hash, CAS-able, actor-attributed — reusing
+// the doc seam's version/CAS/actor machinery. Future consumers (the CLI's `promote`/
+// `pull`) route through ONLY these, never a backend directly.
+export { readBlob, writeBlob, existsBlob, listBlobs } from "./bundle.js";
+export { freshness } from "./freshness.js";
+// Pluggable storage: the seam is `StorageBackend` (types.ts). `FilesystemBackend` is
+// the DEGENERATE default adapter (the engine falls back to it for a `{ root }` bundle);
+// `MemoryBackend` implements the SAME contract for the hard case (real version chain,
+// enforced compare-and-swap, per-write actor) and proves the engine is backend-neutral.
+export { FilesystemBackend } from "./backend.js";
+export { MemoryBackend } from "./memory-backend.js";
+// Internal-workspace filesystem arbitration authority. CLI create-only policy reuses this
+// external same-user lock rather than defining a second lock protocol or writing claims into a
+// portable bundle tree.
+export { withFilesystemMutationLock, FilesystemMutationLockError, filesystemMutationLockPath, } from "./filesystem-lock.js";
+// `RemoteBackend` is the CLIENT half of the wire-protocol v0 seam-over-HTTP contract
+// (docs/WIRE-PROTOCOL.md) — a FUTURE plug-in adapter, proven here against the
+// in-repo reference server (`@superbee/server`) by the tri-backend contract
+// tests. No CF/D1/production deployment is implied by its presence.
+export { RemoteBackend, RemoteError } from "./remote-backend.js";
+// Versioning / attribution primitives shared by every adapter: the content-addressed
+// version token, a default actor, and the typed compare-and-swap conflict error.
+// `blobVersion` is the raw-bytes sibling of `contentVersion`/`versionOfBytes` (blobs
+// are hashed directly, never routed through a string/UTF-8 step).
+export { contentVersion, versionOfBytes, blobVersion, defaultActor, VersionConflict, stripETagWrapper, } from "./versioning.js";
+// The ONE versioned-mutation boundary: a shared read-decide-CAS-retry
+// primitive consumed by document, link, and index mutation policies instead of
+// independently hand-rolled loops.
+export { versionedMutation } from "./mutation.js";
+// Shared document mutation policy below any transport or presentation boundary. CLI and
+// future trusted consumers reuse create/overwrite/patch semantics without importing CLI code.
+export { mutateDocument, DocumentNotFoundError, KindConformanceError, } from "./document-mutation.js";
+// Field preconditions: the domain-invariant guard `mutateDocument` evaluates against each
+// attempt's fresh read, inside the same decision the CAS write is paired with. `PreconditionFailed`
+// is terminal — consumers branch on the type and map it to their own conflict shape.
+export { PreconditionFailed, assertFieldPreconditions } from "./document-precondition.js";
+// ── Extensions (additive; do not break the contract) ──────────────────────────
+// `list` is an alias of `query` (the `list/query` API surface).
+export { list } from "./bundle.js";
+// Head-projection scan + its canonical filter predicate — contracts documented at the
+// definition sites (bundle.ts/types.ts). The delete-tolerant batch read they share
+// (`readManyExisting`) is internal: its one-time export for the reference router was
+// withdrawn when the router switched to consuming `queryHeads` wholesale.
+export { queryHeads } from "./bundle.js";
+export { matchesFilter } from "./query-filter.js";
+export { applyQuerySelectionFilters } from "./query-selection.js";
+// Portable, ownership-governed `index.md` projection. Raw reserved-file interop stays on the backend seam.
+export { GENERATED_INDEX_MARKER, IndexProjectionWriteError, planIndexProjection, prepareIndexProjection, applyIndexProjection, } from "./index-projection.js";
+// Pure, unit-testable path / link / note / freshness helpers.
+export { RESERVED_FILENAMES, isReservedFile, conceptIdFromPath, pathFromConceptId, assertSafeConceptId, assertSafeReservedDir, assertSafeBlobKey, toPosix, } from "./paths.js";
+export { extractMarkdownLinks, resolveConceptId, relativeHref, parseLinksFromDoc, isExternalHref, } from "./links.js";
+export { parseTimestamp } from "./freshness.js";
+export { SUPERBEE_UPDATED_BY_FIELD, mutationActorFromFrontmatter, persistMutationActor, } from "./mutation-attribution.js";
+export { parseMarkdown, stringifyDoc, stringifyWithData, normalizeDocumentBodyForStorage, isUsableTimestamp, MalformedDocumentError, } from "./frontmatter.js";
+// Typed input-validation rejection — consumer boundaries branch on the TYPE (CLI: USAGE/exit 2),
+// never on message prose. `FilesystemIdentityAliasError` is the alias verdict of the filesystem
+// adapter (a subclass, so it maps through the same branch); `ConcurrentReplacementError` is its
+// bounded-retry runtime condition.
+export { InvalidInputError, FilesystemIdentityAliasError, ConcurrentReplacementError } from "./errors.js";
+export { applyV02MutationMetadata } from "./document-write-policy.js";
+// Kind conventions: a bundle-declared, opt-in document-kind
+// registry — validation + per-kind freshness horizons, read from `Convention` docs under
+// `conventions/`. THE mechanism is core (one implementation, consumed by CLI/server/future
+// MCP); usage is opt-in per bundle. A conventions-free bundle is byte-for-byte unaffected.
+export { CONVENTIONS_PREFIX, CONVENTION_TYPE, PROGRESS_STATUS_FIELD, SUPERBEE_PROGRESS_STATUS_FIELD, RESERVED_KIND_FIELD_NAMES, progressStatusStorageField, progressStatusCoordinate, resolveKindFieldCoordinate, claimCoordinates, kindInputFieldNames, readKindField, projectLogicalKindFields, projectKindForAuthoring, projectKindValidationWarnings, validateAgainstKind, isPresent, defaultTimestampAndValidateAgainstRegistry, freshnessHorizonMs, kindConventionDoc, parseConventionDoc, buildKindRegistry, splitSections, isTerminal, } from "./kinds.js";
+export { loadKinds } from "./kinds-load.js";
+// Ported MIME utilities (holaxis-agentstate `packages/schemas/src/content-type.ts`).
+// `resolveContentType` is the ONE place a blob's content-type is resolved (explicit
+// override > inferred from key extension > `DEFAULT_BLOB_CONTENT_TYPE`) — every
+// backend's blob methods route through it.
+export { EXTENSION_CONTENT_TYPES, extensionOfDocKey, inferContentTypeFromDocKey, inferContentTypeForNewBlob, resolveContentType, DEFAULT_BLOB_CONTENT_TYPE, } from "./content-type.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/kinds-load.d.ts

@@ -0,0 +1,13 @@
+import type { KindRegistry } from "./kinds.js";
+import type { Bundle } from "./types.js";
+/**
+ * Build the {@link KindRegistry} for `bundle`: every `Convention` doc under
+ * {@link CONVENTIONS_PREFIX}, keyed by the `type` it governs. A Convention doc OUTSIDE
+ * the prefix is NOT discovered — that is the documented contract (CONTRIBUTING.md, "Kind conventions"),
+ * not a bug. Malformed docs are skipped with a collected warning (never thrown); a
+ * duplicate `governs` keeps the first-by-id declaration (query's results are
+ * id-sorted) and warns about the shadowed one. Callers build this ONCE per invocation
+ * and pass it down — no engine path calls this on its own.
+ */
+export declare function loadKinds(bundle: Bundle): Promise<KindRegistry>;
+//# sourceMappingURL=kinds-load.d.ts.map

package/dist/kinds-load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds-load.d.ts","sourceRoot":"","sources":["../src/kinds-load.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiBrE"}

package/dist/kinds-load.js

@@ -0,0 +1,34 @@
+/**
+ * The backend-touching half of the kind-convention registry: {@link loadKinds}
+ * queries a bundle's `conventions/` prefix and builds the registry out of `kinds.ts`'s pure
+ * parsing/derivation. Split from `kinds.ts` ONLY by dependency weight — `kinds.ts` is the
+ * browser-safe `@superbee/core/kinds` subpath (zero value imports), while this module may
+ * pull the engine (`query` -> backends -> node built-ins). One registry, two entry weights.
+ */
+import { query } from "./bundle.js";
+import { CONVENTIONS_PREFIX, CONVENTION_TYPE, buildKindRegistry, } from "./kinds.js";
+/**
+ * Build the {@link KindRegistry} for `bundle`: every `Convention` doc under
+ * {@link CONVENTIONS_PREFIX}, keyed by the `type` it governs. A Convention doc OUTSIDE
+ * the prefix is NOT discovered — that is the documented contract (CONTRIBUTING.md, "Kind conventions"),
+ * not a bug. Malformed docs are skipped with a collected warning (never thrown); a
+ * duplicate `governs` keeps the first-by-id declaration (query's results are
+ * id-sorted) and warns about the shadowed one. Callers build this ONCE per invocation
+ * and pass it down — no engine path calls this on its own.
+ */
+export async function loadKinds(bundle) {
+    const warnings = [];
+    // A convention doc whose YAML frontmatter is itself corrupt must not crash the WHOLE registry
+    // load (which every `kinds`/`status`/`new`/`doc write` invocation runs) — it is reported as a
+    // registry warning, exactly like a semantically-malformed convention, and the rest still load.
+    const docs = await query(bundle, { prefix: CONVENTIONS_PREFIX, type: CONVENTION_TYPE }, {
+        onSkip: ({ id, reason }) => warnings.push({
+            code: "KIND_CONVENTION_MALFORMED",
+            message: `skipped kind convention '${id}' with unparseable frontmatter: ${reason}`,
+            field: id,
+            severity: "warning",
+        }),
+    });
+    return buildKindRegistry(docs, warnings);
+}
+//# sourceMappingURL=kinds-load.js.map

package/dist/kinds-load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds-load.js","sourceRoot":"","sources":["../src/kinds-load.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAc;IAC5C,MAAM,QAAQ,GAAwB,EAAE,CAAC;IAEzC,8FAA8F;IAC9F,8FAA8F;IAC9F,+FAA+F;IAC/F,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE;QACtF,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CACzB,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,2BAA2B;YACjC,OAAO,EAAE,4BAA4B,EAAE,mCAAmC,MAAM,EAAE;YAClF,KAAK,EAAE,EAAE;YACT,QAAQ,EAAE,SAAS;SACpB,CAAC;KACL,CAAC,CAAC;IAEH,OAAO,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC3C,CAAC"}