@superbee/core 0.2.0-pre.15 → 0.2.0-pre.17

package/dist/blob-contract.js

@@ -0,0 +1,131 @@
+/** Pure ordinary-file intent and result grammar. No transport or authority is carried here. */
+import { assertSafeBlobKey } from "./paths.js";
+import { isContentVersion } from "./version-transport.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const onlyKeys = (value, allowed) => Object.keys(value).every(key => allowed.includes(key));
+const count = (value) => Number.isSafeInteger(value) && value >= 1;
+export const BLOB_OPERATION_IDS = Object.freeze(["blobs.create.v1", "blobs.replace.v1", "blobs.delete.v1"]);
+const BLOB_ERROR_CODES = ["version_conflict", "insufficient_scope", "bundle_not_found", "concurrent_change", "backend_unavailable", "request_capacity", "deletions_held", "write_outcome_unknown"];
+const BLOB_ERROR_KEYS = ["code", "message", "retryable", "writeState", "expected", "actual", "expectedContentType", "actualContentType", "scope", "resetAt", "deletions", "baseline"];
+const BLOB_CONFLICT_KEYS = ["expected", "actual", "expectedContentType", "actualContentType"];
+export function isBlobContentType(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 1024 && /^[\x20-\x7e]+$/.test(value) && value.trim() === value;
+}
+export function isSafeBlobKey(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        assertSafeBlobKey(value);
+        const bytes = new TextEncoder().encode(value);
+        return bytes.length <= 512 && new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes) === value;
+    }
+    catch {
+        return false;
+    }
+}
+export function isBlobWriteExpected(expected) {
+    if (!isRecord(expected) || !BLOB_OPERATION_IDS.includes(expected.operationId) || !isSafeBlobKey(expected.key))
+        return false;
+    if (expected.operationId === "blobs.create.v1") {
+        if (expected.expectedVersion !== null || expected.expectedContentType !== null)
+            return false;
+    }
+    else if (!isContentVersion(expected.expectedVersion) || !isBlobContentType(expected.expectedContentType))
+        return false;
+    if (expected.operationId === "blobs.delete.v1")
+        return !("version" in expected) && !("contentType" in expected);
+    return isContentVersion(expected.version) && isBlobContentType(expected.contentType);
+}
+/** A blob result answers every version and MIME pin retained in the original intent. Success
+ * names a replacement head, or a delete's removed head; it never invents a tombstone. */
+export function decodeBlobWriteResult(raw, expected) {
+    const refuse = () => new TypeError("the blob write result does not answer the retained intent");
+    if (!isBlobWriteExpected(expected) || !isRecord(raw) || !onlyKeys(raw, ["ok", "operationId", "data", "error"]) || raw.operationId !== expected.operationId)
+        throw refuse();
+    const operationId = expected.operationId;
+    if (raw.ok === true) {
+        const data = raw.data;
+        const deletion = operationId === "blobs.delete.v1";
+        if (raw.error !== undefined || !isRecord(data) || !onlyKeys(data, deletion ? ["key", "version", "contentType", "deleted"] : ["key", "version", "contentType", "changed"]) || data.key !== expected.key || !isContentVersion(data.version) || !isBlobContentType(data.contentType))
+            throw refuse();
+        if (expected.operationId === "blobs.delete.v1") {
+            if (data.deleted !== true || data.version !== expected.expectedVersion || data.contentType !== expected.expectedContentType)
+                throw refuse();
+            return { ok: true, operationId: expected.operationId, data: { key: expected.key, version: data.version, contentType: data.contentType, deleted: true } };
+        }
+        if (data.version !== expected.version || data.contentType !== expected.contentType || typeof data.changed !== "boolean" ||
+            (expected.operationId === "blobs.create.v1" && !data.changed) ||
+            (expected.operationId === "blobs.replace.v1" && data.changed !== (expected.version !== expected.expectedVersion || expected.contentType !== expected.expectedContentType)))
+            throw refuse();
+        return { ok: true, operationId: expected.operationId, data: { key: expected.key, version: data.version, contentType: data.contentType, changed: data.changed } };
+    }
+    const error = raw.error;
+    if (raw.ok !== false || raw.data !== undefined || !isRecord(error) || !onlyKeys(error, BLOB_ERROR_KEYS) || !BLOB_ERROR_CODES.includes(error.code) || typeof error.message !== "string" || error.retryable !== false ||
+        (error.writeState !== "not_applied" && error.writeState !== "unknown") ||
+        (error.code === "write_outcome_unknown" ? error.writeState !== "unknown" : error.writeState !== "not_applied"))
+        throw refuse();
+    if (error.code === "version_conflict") {
+        if (error.expected !== expected.expectedVersion || error.expectedContentType !== expected.expectedContentType ||
+            !(error.actual === null || isContentVersion(error.actual)) || !(error.actualContentType === null || isBlobContentType(error.actualContentType)) ||
+            ((error.actual === null) !== (error.actualContentType === null)) ||
+            (expected.operationId === "blobs.create.v1" && error.actual === null) ||
+            (error.actual === expected.expectedVersion && error.actualContentType === expected.expectedContentType))
+            throw refuse();
+    }
+    else if (BLOB_CONFLICT_KEYS.some(key => error[key] !== undefined))
+        throw refuse();
+    if (error.code === "request_capacity") {
+        if ((error.scope !== "principal" && error.scope !== "bundle") || (error.resetAt !== undefined && (typeof error.resetAt !== "string" || !Number.isFinite(Date.parse(error.resetAt)))))
+            throw refuse();
+    }
+    else if (error.scope !== undefined || error.resetAt !== undefined)
+        throw refuse();
+    if (error.code === "deletions_held") {
+        if (operationId !== "blobs.delete.v1" || !count(error.deletions) || !count(error.baseline))
+            throw refuse();
+    }
+    else if (error.deletions !== undefined || error.baseline !== undefined)
+        throw refuse();
+    return { ok: false, operationId, error: { ...error } };
+}
+export function assertBlobKey(key) {
+    try {
+        assertSafeBlobKey(key);
+    }
+    catch {
+        throw new TypeError("unsafe blob key");
+    }
+    const bytes = new TextEncoder().encode(key);
+    if (bytes.length > 512 || new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes) !== key)
+        throw new TypeError("unrepresentable blob key");
+}
+export function captureBlobHead(value) {
+    if (!isRecord(value) || !onlyKeys(value, ["key", "version", "contentType"]) || typeof value.key !== "string" || !isContentVersion(value.version) || !isBlobContentType(value.contentType))
+        throw new TypeError("malformed blob head");
+    assertBlobKey(value.key);
+    return Object.freeze({ key: value.key, version: value.version, contentType: value.contentType });
+}
+export function encodeBlobKey(key) {
+    assertBlobKey(key);
+    let binary = "";
+    for (const byte of new TextEncoder().encode(key))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/** Snapshot the strict retained payload before any asynchronous admission. */
+export function captureBlobWriteExpected(intent) {
+    if (!isRecord(intent))
+        throw new TypeError("blob intent and identity must be objects");
+    const copied = { ...intent };
+    const deletion = copied.operationId === "blobs.delete.v1";
+    if (!["blobs.create.v1", "blobs.replace.v1", "blobs.delete.v1"].includes(copied.operationId) ||
+        !onlyKeys(copied, deletion ? ["operationId", "key", "expectedVersion", "expectedContentType"] : ["operationId", "key", "expectedVersion", "expectedContentType", "version", "contentType"]))
+        throw new TypeError("unsupported blob intent");
+    assertBlobKey(copied.key);
+    if (copied.operationId === "blobs.create.v1" ? copied.expectedVersion !== null || copied.expectedContentType !== null : !isContentVersion(copied.expectedVersion) || !isBlobContentType(copied.expectedContentType))
+        throw new TypeError("blob preconditions are required");
+    if (copied.operationId !== "blobs.delete.v1" && (!isContentVersion(copied.version) || !isBlobContentType(copied.contentType)))
+        throw new TypeError("blob replacement pins are required");
+    return Object.freeze(copied);
+}
+//# sourceMappingURL=blob-contract.js.map

package/dist/blob-contract.js.map

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

package/dist/blob-journal.d.ts

@@ -0,0 +1,117 @@
+/** File-journal optional ordinary-file admission. Frozen payloads are data, never authority:
+ * a dispatcher must compare their scope with its current trusted context before delivery. */
+import { type BlobWriteExpected, type BlobWriteResult, type BlobHead } from "./blob-contract.js";
+import { type MetaExpectation, type MetaRecord } from "./journaled-backend.js";
+import type { OperationState } from "./uncertain-write.js";
+export { isWriteRequestId } from "./write-identity.js";
+export declare const BLOB_JOURNAL_BOUNDS: Readonly<{
+    rawBytes: number;
+    preparedBytes: number;
+    /** The file codec checks the actual tagged encoding, not an estimate of JSON text. */
+    terminalReceiptBytes: number;
+    settlementStructureBytes: number;
+    /** Aggregate encoded metadata growth ordinarily needed for the settled byte+MIME baseline. */
+    baselineBytes: number;
+}>;
+export interface BlobTargetScope {
+    origin: string;
+    prefix: string;
+    bundleId: string;
+    workspaceSlug: string | null;
+}
+export interface BlobPreparedInput {
+    scope: BlobTargetScope;
+    intent: BlobWriteExpected;
+    identity: {
+        requestId: string;
+        binding: string;
+        via?: string;
+    };
+    createdAt: string;
+}
+export interface PreparedBlobIntent extends BlobPreparedInput {
+    schemaVersion: 1;
+    bytesBase64?: string;
+}
+export type BlobReceipt = {
+    scope: BlobTargetScope;
+    result: Extract<BlobWriteResult, {
+        ok: true;
+    }>;
+    head: BlobHead | null;
+    removed?: BlobHead;
+} | {
+    scope: BlobTargetScope;
+    result: Extract<BlobWriteResult, {
+        ok: false;
+    }>;
+};
+export interface BlobDeletionHold {
+    deletions: number;
+    baseline: number;
+}
+/** Bounded diagnostics, never acceptance or a terminal receipt. */
+export declare function captureBlobDeletionHold(value: BlobDeletionHold): BlobDeletionHold;
+export interface BlobIntentRecord {
+    recordFamily: "blob";
+    requestId: string;
+    target: string;
+    /** The ONE canonical frozen payload, including raw bytes when this is a create/replace. */
+    prepared: string;
+    sequence: number;
+    attempts: number;
+    state: OperationState;
+    updatedAt: string;
+    receipt?: BlobReceipt;
+    /** Proven non-execution for every attempt through this count; omitted means zero. */
+    notAppliedThrough?: number;
+    deletionHold?: BlobDeletionHold;
+}
+export interface BlobJournalGuard {
+    key: string;
+    intents: BlobIntentRecord[];
+    meta: {
+        key: string;
+        expected: MetaExpectation;
+    }[];
+}
+export interface BlobJournalRead {
+    key: string;
+    intents: BlobIntentRecord[];
+    meta: Map<string, unknown>;
+    guard: BlobJournalGuard;
+}
+export interface BlobJournalMutationOptions {
+    guard: BlobJournalGuard;
+    meta?: MetaRecord[];
+    removeMeta?: string[];
+}
+export interface BlobIntentPatch {
+    state?: OperationState;
+    attempts?: number;
+    receipt?: BlobReceipt;
+    notAppliedThrough?: number;
+    deletionHold?: BlobDeletionHold;
+}
+export interface BlobJournaledBackend {
+    /** Optional file-only atomic metadata mutation under the complete same-key/named-meta guard. */
+    writeBlobMeta?(key: string, changes: Pick<BlobJournalMutationOptions, "meta" | "removeMeta">, options: {
+        guard: BlobJournalGuard;
+    }): Promise<void>;
+    readBlobWithJournal(key: string, options?: {
+        meta?: readonly string[];
+    }): Promise<BlobJournalRead>;
+    admitPreparedBlob(prepared: string, options: BlobJournalMutationOptions): Promise<BlobIntentRecord>;
+    listBlobIntents(state?: OperationState | readonly OperationState[]): Promise<BlobIntentRecord[]>;
+    readBlobIntent(requestId: string): Promise<BlobIntentRecord | undefined>;
+    updateBlobIntent(requestId: string, expectedState: OperationState, patch: BlobIntentPatch, options: BlobJournalMutationOptions): Promise<BlobIntentRecord>;
+    retireBlobIntents(key: string, requestIds: readonly string[], options: BlobJournalMutationOptions): Promise<void>;
+}
+export declare function prepareBlobIntent(input: BlobPreparedInput, bytes?: Uint8Array): string;
+export declare function decodePreparedBlobIntent(payload: string): PreparedBlobIntent;
+export declare function blobReceipt(prepared: string, raw: unknown): BlobReceipt;
+export declare function captureBlobIntentRecord(value: BlobIntentRecord): BlobIntentRecord;
+export declare function captureBlobJournalGuard(value: BlobJournalGuard): BlobJournalGuard;
+export declare function assertBlobJournalGuard(expected: BlobJournalGuard, actual: BlobJournalGuard): void;
+export declare function captureBlobMutationOptions(options: BlobJournalMutationOptions): BlobJournalMutationOptions;
+//# sourceMappingURL=blob-journal.d.ts.map

package/dist/blob-journal.d.ts.map

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

package/dist/blob-journal.js

@@ -0,0 +1,168 @@
+/** File-journal optional ordinary-file admission. Frozen payloads are data, never authority:
+ * a dispatcher must compare their scope with its current trusted context before delivery. */
+import { captureBlobWriteExpected, decodeBlobWriteResult, assertBlobKey } from "./blob-contract.js";
+import { isHostedBundleId } from "./dependencies.js";
+import { isAgentLabelVia, isWriteBinding, isWriteRequestId } from "./write-identity.js";
+import { sha256HexOfBytes } from "./sha256.js";
+import { captureJournalValue, equalJournalValue, assertMetaExpectation, JournalGuardConflict } from "./journaled-backend.js";
+export { isWriteRequestId } from "./write-identity.js";
+export const BLOB_JOURNAL_BOUNDS = Object.freeze({ rawBytes: 16 * 1024 * 1024, preparedBytes: 24 * 1024 * 1024,
+    /** The file codec checks the actual tagged encoding, not an estimate of JSON text. */
+    terminalReceiptBytes: 128 * 1024,
+    settlementStructureBytes: 4 * 1024,
+    /** Aggregate encoded metadata growth ordinarily needed for the settled byte+MIME baseline. */
+    baselineBytes: 16 * 1024,
+});
+/** Bounded diagnostics, never acceptance or a terminal receipt. */
+export function captureBlobDeletionHold(value) {
+    const hold = captureJournalValue(value);
+    if (!object(hold) || !only(hold, ["deletions", "baseline"]) || ![hold.deletions, hold.baseline].every(n => Number.isSafeInteger(n) && n >= 1))
+        throw new TypeError("invalid blob deletion hold");
+    return hold;
+}
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const only = (v, keys) => Object.keys(v).every(key => keys.includes(key));
+const timestamp = (v) => typeof v === "string" && v.length <= 64 && /^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(v) && Number.isFinite(Date.parse(v));
+function captureInput(value) {
+    const v = captureJournalValue(value);
+    if (!object(v) || !only(v, ["scope", "intent", "identity", "createdAt"]) || !timestamp(v.createdAt) || !object(v.scope) || !only(v.scope, ["origin", "prefix", "bundleId", "workspaceSlug"]) || !object(v.identity) || !only(v.identity, ["requestId", "binding", "via"]))
+        throw new TypeError("invalid prepared blob input");
+    const { scope, identity } = v;
+    if (typeof scope.origin !== "string" || scope.origin.length > 2048 || typeof scope.prefix !== "string" || scope.prefix.length > 512 || !/^\/(?:[a-zA-Z0-9._~-]+\/)*[a-zA-Z0-9._~-]+$/.test(scope.prefix) || scope.prefix.split("/").some(part => part === "." || part === "..") || typeof scope.bundleId !== "string" || !isHostedBundleId(scope.bundleId) || !(scope.workspaceSlug === null || typeof scope.workspaceSlug === "string" && /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(scope.workspaceSlug)))
+        throw new TypeError("invalid blob target scope");
+    let origin;
+    try {
+        origin = new URL(scope.origin);
+    }
+    catch {
+        throw new TypeError("invalid blob target origin");
+    }
+    if (!['http:', 'https:'].includes(origin.protocol) || origin.origin !== scope.origin)
+        throw new TypeError("invalid blob target origin");
+    if (typeof identity.requestId !== "string" || !isWriteRequestId(identity.requestId) || typeof identity.binding !== "string" || !isWriteBinding(identity.binding) || identity.via !== undefined && !isAgentLabelVia(identity.via))
+        throw new TypeError("invalid blob prepared identity");
+    const original = captureBlobWriteExpected(v.intent);
+    const pins = { operationId: original.operationId, key: original.key, expectedVersion: original.expectedVersion, expectedContentType: original.expectedContentType };
+    const intent = (original.operationId === "blobs.delete.v1" ? pins : { ...pins, version: original.version, contentType: original.contentType });
+    return { scope: { origin: scope.origin, prefix: scope.prefix, bundleId: scope.bundleId, workspaceSlug: scope.workspaceSlug }, intent, identity: { requestId: identity.requestId, binding: identity.binding, ...(identity.via === undefined ? {} : { via: identity.via }) }, createdAt: v.createdAt };
+}
+function base64(bytes) {
+    let binary = "";
+    for (let at = 0; at < bytes.length; at += 8192)
+        binary += String.fromCharCode(...bytes.subarray(at, at + 8192));
+    return btoa(binary);
+}
+function checkedPayload(input, bytes) {
+    const captured = captureInput(input);
+    const deletion = captured.intent.operationId === "blobs.delete.v1";
+    if (deletion ? bytes !== undefined : !(bytes instanceof Uint8Array) || bytes.byteLength > BLOB_JOURNAL_BOUNDS.rawBytes)
+        throw new TypeError("invalid prepared blob bytes");
+    if (captured.intent.operationId !== "blobs.delete.v1" && `sha256:${sha256HexOfBytes(bytes)}` !== captured.intent.version)
+        throw new TypeError("prepared blob digest does not match bytes");
+    return { schemaVersion: 1, ...captured, ...(deletion ? {} : { bytesBase64: base64(bytes) }) };
+}
+export function prepareBlobIntent(input, bytes) {
+    const payload = JSON.stringify(checkedPayload(input, bytes === undefined ? undefined : new Uint8Array(bytes)));
+    if (new TextEncoder().encode(payload).byteLength > BLOB_JOURNAL_BOUNDS.preparedBytes)
+        throw new RangeError("prepared blob exceeds its byte bound");
+    return payload;
+}
+export function decodePreparedBlobIntent(payload) {
+    if (typeof payload !== "string" || payload.length > BLOB_JOURNAL_BOUNDS.preparedBytes || new TextEncoder().encode(payload).byteLength > BLOB_JOURNAL_BOUNDS.preparedBytes)
+        throw new TypeError("invalid prepared blob payload");
+    const value = JSON.parse(payload);
+    if (!object(value) || !only(value, ["schemaVersion", "scope", "intent", "identity", "createdAt", "bytesBase64"]) || value.schemaVersion !== 1)
+        throw new TypeError("invalid prepared blob schema");
+    const { schemaVersion: _schema, bytesBase64, ...input } = value;
+    let bytes;
+    if (bytesBase64 !== undefined) {
+        if (typeof bytesBase64 !== "string" || bytesBase64.length > Math.ceil(BLOB_JOURNAL_BOUNDS.rawBytes / 3) * 4)
+            throw new TypeError("invalid prepared blob base64");
+        bytes = Uint8Array.from(atob(bytesBase64), c => c.charCodeAt(0));
+        if (base64(bytes) !== bytesBase64)
+            throw new TypeError("noncanonical prepared blob base64");
+    }
+    const checked = checkedPayload(input, bytes);
+    if (JSON.stringify(checked) !== payload)
+        throw new TypeError("noncanonical prepared blob payload");
+    return captureJournalValue(checked);
+}
+export function blobReceipt(prepared, raw) {
+    const original = decodePreparedBlobIntent(prepared);
+    const result = decodeBlobWriteResult(raw, original.intent);
+    if (!result.ok) {
+        if (result.error.writeState !== "not_applied")
+            throw new TypeError("uncertain blob result is not a terminal receipt");
+        return { scope: original.scope, result };
+    }
+    const head = { key: result.data.key, version: result.data.version, contentType: result.data.contentType };
+    return result.operationId === "blobs.delete.v1" ? { scope: original.scope, result, head: null, removed: head } : { scope: original.scope, result, head };
+}
+export function captureBlobIntentRecord(value) {
+    const row = captureJournalValue(value);
+    if (!object(row) || !only(row, ["recordFamily", "requestId", "target", "prepared", "sequence", "attempts", "state", "updatedAt", "receipt", "notAppliedThrough", "deletionHold"]) || row.recordFamily !== "blob" || !Number.isSafeInteger(row.sequence) || row.sequence < 1 || !Number.isSafeInteger(row.attempts) || row.attempts < 0 || !timestamp(row.updatedAt) || !["pending", "in_flight", "acknowledged", "conflict", "refused", "unknown"].includes(row.state))
+        throw new TypeError("invalid blob intent record");
+    const prepared = decodePreparedBlobIntent(row.prepared);
+    if (row.requestId !== prepared.identity.requestId || row.target !== prepared.intent.key)
+        throw new TypeError("blob record index does not match payload");
+    const prefix = row.notAppliedThrough === undefined ? 0 : row.notAppliedThrough;
+    if (!Number.isSafeInteger(prefix) || prefix < 0 || prefix > row.attempts)
+        throw new TypeError("invalid blob non-execution prefix");
+    if (row.deletionHold !== undefined) {
+        captureBlobDeletionHold(row.deletionHold);
+        if (prefix === 0 || prepared.intent.operationId !== "blobs.delete.v1")
+            throw new TypeError("blob hold requires its proven deletion prefix");
+    }
+    if (prefix > 0 && row.deletionHold === undefined)
+        throw new TypeError("blob non-execution prefix requires hold diagnostics");
+    const terminal = row.state === "acknowledged" || row.state === "conflict" || row.state === "refused";
+    if (terminal !== (row.receipt !== undefined))
+        throw new TypeError("blob terminal state requires its receipt");
+    if (row.receipt !== undefined) {
+        const receipt = blobReceipt(row.prepared, row.receipt.result);
+        if (!equalJournalValue(receipt, row.receipt) || (row.state === "acknowledged") !== receipt.result.ok || (!receipt.result.ok && (row.state === "conflict") !== (receipt.result.error.code === "version_conflict")))
+            throw new TypeError("blob receipt does not match state");
+    }
+    return row;
+}
+export function captureBlobJournalGuard(value) {
+    const guard = captureJournalValue(value);
+    if (!object(guard) || !only(guard, ["key", "intents", "meta"]) || !Array.isArray(guard.intents) || !Array.isArray(guard.meta))
+        throw new JournalGuardConflict("blob");
+    assertBlobKey(guard.key);
+    const ids = new Set(), sequences = new Set(), keys = new Set();
+    for (const row of guard.intents) {
+        captureBlobIntentRecord(row);
+        if (row.target !== guard.key || ids.has(row.requestId) || sequences.has(row.sequence))
+            throw new JournalGuardConflict(guard.key);
+        ids.add(row.requestId);
+        sequences.add(row.sequence);
+    }
+    for (const row of guard.meta) {
+        if (!object(row) || !only(row, ["key", "expected"]) || typeof row.key !== "string" || keys.has(row.key))
+            throw new JournalGuardConflict(guard.key);
+        keys.add(row.key);
+        assertMetaExpectation(row.expected);
+    }
+    return guard;
+}
+export function assertBlobJournalGuard(expected, actual) {
+    const a = captureBlobJournalGuard(expected), b = captureBlobJournalGuard(actual);
+    for (const guard of [a, b]) {
+        guard.intents.sort((x, y) => x.sequence - y.sequence);
+        guard.meta.sort((x, y) => x.key.localeCompare(y.key));
+    }
+    if (!equalJournalValue(a, b))
+        throw new JournalGuardConflict(a.key);
+}
+export function captureBlobMutationOptions(options) {
+    const captured = captureJournalValue(options);
+    if (!object(captured) || !only(captured, ["guard", "meta", "removeMeta"]))
+        throw new JournalGuardConflict("blob");
+    captured.guard = captureBlobJournalGuard(captured.guard);
+    const puts = captured.meta ?? [], removals = captured.removeMeta ?? [];
+    if (!Array.isArray(puts) || !Array.isArray(removals) || puts.some(row => !object(row) || !only(row, ["key", "value"]) || typeof row.key !== "string") || new Set(puts.map(row => row.key)).size !== puts.length || new Set(removals).size !== removals.length || [...puts.map(row => row.key), ...removals].some(key => typeof key !== "string" || !captured.guard.meta.some(row => row.key === key)) || removals.some(key => puts.some(row => row.key === key)))
+        throw new JournalGuardConflict(captured.guard.key);
+    return captured;
+}
+//# sourceMappingURL=blob-journal.js.map

package/dist/blob-journal.js.map

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

package/dist/bundle-health/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@superbee/core/bundle-health`: the health report behind `superbee status`, computed from a core
+ * `Bundle` on any backend. The caller resolves what lives outside the bundle (bound copies of its
+ * dependencies, the clock, a fallback bundle id) and presents the report; the `superbee` CLI is one
+ * such caller. It also holds `bundleKindFindings`, the one rule for the Kind problems a strict host
+ * write would refuse, which publish preview and hosted bundle creation run. Storage-neutral: no Node
+ * globals or builtins.
+ */
+export { bundleHealth } from "./report.js";
+export type { BindDependencies, BundleHealthOptions, BundleHealthReport, CrossBundleHealth, CrossLinkTypeViolationRow, CrossUnresolvedRow, DanglingEntryRow, DependencyProblemRow, DependencyRow, DocTypeRow, FieldValueRow, InvalidRegistrationRow, KindLintRow, LegacyNamingFindings, LinkTypeViolationRow, MalformedRow, MissingExpectedRow, OkfUpgradeFinding, StaleRow, StatusFieldRow, UnresolvedLinkRow, ValueRow, ViewSurfaceHealth, } from "./report.js";
+export { bundleKindFindings, bundleKindRegistry, documentKindFinding, isRegistryConvention } from "./kind-findings.js";
+export type { BundleKindFindings, KindFinding, KindWriteIdentity } from "./kind-findings.js";
+export { LEGACY_PAGE_TYPE_NAME, isLegacyPageDoc } from "./legacy-page.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/bundle-health/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundle-health/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,UAAU,EACV,aAAa,EACb,sBAAsB,EACtB,WAAW,EACX,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACvH,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/bundle-health/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@superbee/core/bundle-health`: the health report behind `superbee status`, computed from a core
+ * `Bundle` on any backend. The caller resolves what lives outside the bundle (bound copies of its
+ * dependencies, the clock, a fallback bundle id) and presents the report; the `superbee` CLI is one
+ * such caller. It also holds `bundleKindFindings`, the one rule for the Kind problems a strict host
+ * write would refuse, which publish preview and hosted bundle creation run. Storage-neutral: no Node
+ * globals or builtins.
+ */
+export { bundleHealth } from "./report.js";
+export { bundleKindFindings, bundleKindRegistry, documentKindFinding, isRegistryConvention } from "./kind-findings.js";
+export { LEGACY_PAGE_TYPE_NAME, isLegacyPageDoc } from "./legacy-page.js";
+//# sourceMappingURL=index.js.map

package/dist/bundle-health/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bundle-health/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0B3C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEvH,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/bundle-health/kind-findings.d.ts

@@ -0,0 +1,44 @@
+import { type KindRegistry } from "../kinds.js";
+import type { OkfDocument } from "../types.js";
+import type { ValidationWarning } from "../validation.js";
+/**
+ * Who the checked first edit is attributed to. `producer` defaults to `actor`, as a write's does.
+ * On OKF v0.2 a `person:` actor cannot be a producer, so a v0.2 call with a `person:` actor must
+ * pass a `process:` (or `<producer>/<version>`) producer, or the check throws `OkfActorError`.
+ */
+export interface KindWriteIdentity {
+    actor: string;
+    producer?: string;
+}
+export interface KindFinding {
+    readonly id: string;
+    readonly governs: string;
+    readonly violations: readonly ValidationWarning[];
+    /** Core's own sentence: `'<id>' does not satisfy the '<Kind>' kind: …`. */
+    readonly message: string;
+}
+export interface BundleKindFindings {
+    /** Registry warnings: every strict write to the bundle refuses while any is present. */
+    readonly conventions: readonly ValidationWarning[];
+    /** Documents whose first strict edit would refuse for their Kind. */
+    readonly documents: readonly KindFinding[];
+}
+/** Whether `loadKinds` builds the Kind registry from this document: a `Convention` under `conventions/`. */
+export declare function isRegistryConvention(doc: OkfDocument): boolean;
+/** The Kind registry a bundle holding `documents` loads, built with `loadKinds`' own filter and builder. */
+export declare function bundleKindRegistry(documents: readonly OkfDocument[], okfVersion: "0.1" | "0.2"): KindRegistry;
+/**
+ * The Kind problem a strict write would refuse the first edit of one stored document over, or
+ * null. The document is prepared as its first edit: the stored document as the existing one and a
+ * body one line longer as the candidate, so unchanged values keep the leniency an edit gives them.
+ * An edit refused for another reason (a malformed standard field it changes) is not a Kind problem.
+ */
+export declare function documentKindFinding(doc: OkfDocument, registry: KindRegistry, okfVersion: "0.1" | "0.2", write: KindWriteIdentity): KindFinding | null;
+/**
+ * The Kind problems in `documents` (as stored) that strict writes would refuse over: the warnings
+ * of the registry their conventions build, and each document's own finding against it, in input
+ * order. Each document is checked on its own, so a bundle checked in parts against the same
+ * registry finds exactly this.
+ */
+export declare function bundleKindFindings(documents: readonly OkfDocument[], okfVersion: "0.1" | "0.2", write: KindWriteIdentity): BundleKindFindings;
+//# sourceMappingURL=kind-findings.d.ts.map

package/dist/bundle-health/kind-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind-findings.d.ts","sourceRoot":"","sources":["../../src/bundle-health/kind-findings.ts"],"names":[],"mappings":"AAaA,OAAO,EAA0D,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAExG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAC;CAC5C;AAED,4GAA4G;AAC5G,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAE9D;AAED,4GAA4G;AAC5G,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,GAAG,YAAY,CAE7G;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,KAAK,GAAG,KAAK,EACzB,KAAK,EAAE,iBAAiB,GACvB,WAAW,GAAG,IAAI,CAuBpB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,UAAU,EAAE,KAAK,GAAG,KAAK,EACzB,KAAK,EAAE,iBAAiB,GACvB,kBAAkB,CAQpB"}

package/dist/bundle-health/kind-findings.js

@@ -0,0 +1,68 @@
+/**
+ * The Kind problems a strict host write would refuse a bundle over, before the bundle exists. A
+ * strict write refuses while the Kind registry has any warning, and it prepares and validates its
+ * candidate with `prepareDocumentMutationCandidate`, which supplies the timestamp, actor and v0.2
+ * metadata a write adds. This is the one rule for "what would the host refuse": the CLI's publish
+ * preview runs it, and a host's bundle creation runs it with its own producer.
+ *
+ * It asks a different question from the health report's Kind lint (`kindLint`,
+ * `conformanceDebt`), which reports what is wrong with each stored document as advice. Both run
+ * core's one validator, `validateAgainstKind`.
+ */
+import { KindConformanceError, prepareDocumentMutationCandidate } from "../document-mutation.js";
+import { InvalidInputError, OkfActorError } from "../errors.js";
+import { buildKindRegistry, CONVENTION_TYPE, CONVENTIONS_PREFIX } from "../kinds.js";
+import { matchesFilter } from "../query-filter.js";
+/** Whether `loadKinds` builds the Kind registry from this document: a `Convention` under `conventions/`. */
+export function isRegistryConvention(doc) {
+    return matchesFilter(doc, { prefix: CONVENTIONS_PREFIX, type: CONVENTION_TYPE });
+}
+/** The Kind registry a bundle holding `documents` loads, built with `loadKinds`' own filter and builder. */
+export function bundleKindRegistry(documents, okfVersion) {
+    return buildKindRegistry(documents.filter(isRegistryConvention), [], { okfVersion });
+}
+/**
+ * The Kind problem a strict write would refuse the first edit of one stored document over, or
+ * null. The document is prepared as its first edit: the stored document as the existing one and a
+ * body one line longer as the candidate, so unchanged values keep the leniency an edit gives them.
+ * An edit refused for another reason (a malformed standard field it changes) is not a Kind problem.
+ */
+export function documentKindFinding(doc, registry, okfVersion, write) {
+    try {
+        prepareDocumentMutationCandidate(doc, { frontmatter: doc.frontmatter, body: `${doc.body ?? ""}\n` }, {
+            strict: true,
+            persistActor: true,
+            ...(write.producer === undefined ? {} : { producer: write.producer }),
+            id: doc.id,
+            registry,
+            okfVersion,
+            actor: write.actor,
+        });
+    }
+    catch (error) {
+        if (error instanceof KindConformanceError) {
+            return { id: doc.id, governs: error.governs, violations: error.violations, message: error.message };
+        }
+        if (error instanceof InvalidInputError && !(error instanceof OkfActorError))
+            return null;
+        throw error;
+    }
+    return null;
+}
+/**
+ * The Kind problems in `documents` (as stored) that strict writes would refuse over: the warnings
+ * of the registry their conventions build, and each document's own finding against it, in input
+ * order. Each document is checked on its own, so a bundle checked in parts against the same
+ * registry finds exactly this.
+ */
+export function bundleKindFindings(documents, okfVersion, write) {
+    const registry = bundleKindRegistry(documents, okfVersion);
+    const found = [];
+    for (const doc of documents) {
+        const finding = documentKindFinding(doc, registry, okfVersion, write);
+        if (finding)
+            found.push(finding);
+    }
+    return { conventions: registry.warnings, documents: found };
+}
+//# sourceMappingURL=kind-findings.js.map