@superbee/core 0.1.0

package/dist/memory-backend.js

@@ -0,0 +1,214 @@
+/**
+ * In-memory {@link StorageBackend} — the PROOF that the seam's hard contract is
+ * implementable, and that the engine leaks no filesystem assumptions.
+ *
+ * Where {@link FilesystemBackend} is the degenerate adapter (single-version history,
+ * cross-process filesystem compare-and-swap), this adapter implements the historical hard case:
+ *   - a genuine per-document VERSION CHAIN (`versions()` returns the full history,
+ *     newest-first);
+ *   - ENFORCED compare-and-swap: a `write` whose `expectedVersion` no longer matches
+ *     the current head throws {@link VersionConflict}, atomically against the in-process
+ *     map (no check-then-write window);
+ *   - per-write ACTOR attribution recorded on every revision;
+ *   - a real batch {@link MemoryBackend.readMany}.
+ *
+ * It touches NO filesystem and NO markdown serialization for storage — documents are
+ * held as parsed {@link OkfDocument} objects, keyed by concept id — so running the
+ * core operations over it exercises exactly the parts of the engine that must be
+ * backend-neutral. Version tokens are still content-addressed via {@link contentVersion},
+ * so an engine-written document carries the SAME token here as on disk.
+ *
+ * Id/dir safety mirrors {@link FilesystemBackend} exactly: an unsafe concept id (a `..`
+ * segment, an absolute id) or an unsafe reserved-file `dir` is harmless against a plain
+ * `Map` key, but this adapter rejects it via the SAME `assertSafeConceptId` /
+ * `assertSafeReservedDir` guards anyway — the two adapters must agree on rejecting it, or
+ * the dual-backend / wire-protocol contract tests diverge.
+ */
+import { resolveContentType } from "./content-type.js";
+import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, toPosix } from "./paths.js";
+import { blobVersion, contentVersion, defaultActor, VersionConflict, versionOfBytes } from "./versioning.js";
+/** Deep copy so stored state never aliases a caller's object (and vice-versa). */
+function snapshot(value) {
+    return structuredClone(value);
+}
+/** An ENOENT-shaped rejection so missing-document handling matches {@link FilesystemBackend}. */
+function notFound(id) {
+    const err = new Error(`no concept document '${id}'`);
+    err.code = "ENOENT";
+    return err;
+}
+/** Bundle-relative key for a reserved file (`""` = bundle root), mirroring the fs adapter's layout. */
+function reservedKey(dir, name) {
+    const d = toPosix(dir).replace(/^\.?\//, "").replace(/\/$/, "");
+    return d === "" ? name : `${d}/${name}`;
+}
+/**
+ * A fully in-memory OKF store implementing the {@link StorageBackend} contract for
+ * the hard, multi-writer case. Not persistent — its purpose is to prove the seam and
+ * to back tests, not to be a shipping store.
+ */
+export class MemoryBackend {
+    /** Concept id → revision chain, newest-first (index 0 is the head). */
+    chains = new Map();
+    /** Reserved-file path → raw content. */
+    reserved = new Map();
+    /** Blob key → current state. Separate from `chains` — a different namespace, no history. */
+    blobs = new Map();
+    async read(id) {
+        // An unsafe id is harmless against a plain Map key, but the two adapters must AGREE
+        // on rejecting it — otherwise the dual-backend/wire contract tests diverge.
+        assertSafeConceptId(id);
+        const head = this.chains.get(id)?.[0];
+        if (!head)
+            throw notFound(id);
+        return { doc: snapshot(head.doc), version: head.version };
+    }
+    async readMany(ids) {
+        // Validate every id up front (same contract as FilesystemBackend.readMany), then a
+        // real multi-get: one pass over the in-memory index, results in input order.
+        for (const id of ids)
+            assertSafeConceptId(id);
+        return Promise.all(ids.map((id) => this.read(id)));
+    }
+    async write(id, doc, options = {}) {
+        assertSafeConceptId(id);
+        const chain = this.chains.get(id);
+        const current = chain?.[0]?.version ?? null;
+        // Enforced compare-and-swap, atomic against the in-process map.
+        if (options.expectedVersion !== undefined && options.expectedVersion !== current) {
+            throw new VersionConflict(id, options.expectedVersion, current);
+        }
+        // The seam's `id` argument owns identity. Filesystem and wire adapters reconstruct/attach
+        // that route id on reads because document bytes do not serialize `doc.id`; mirror them here
+        // instead of retaining a mismatched caller-supplied `doc.id` in the in-memory snapshot.
+        const storedDoc = { ...doc, id };
+        const version = contentVersion(storedDoc);
+        // Idempotent: re-writing byte-identical content is a no-op that does not grow the
+        // chain (the content address is unchanged). A genuine content change appends a revision.
+        if (current === version)
+            return version;
+        const revision = {
+            version,
+            actor: options.actor?.trim() || defaultActor(),
+            timestamp: new Date().toISOString(),
+            // Unlike `actor`, an unattested agent is simply absent — no default is applied.
+            agent: options.agent?.trim() || undefined,
+            doc: snapshot(storedDoc),
+        };
+        this.chains.set(id, chain ? [revision, ...chain] : [revision]);
+        return version;
+    }
+    async delete(id, options = {}) {
+        assertSafeConceptId(id);
+        const chain = this.chains.get(id);
+        const current = chain?.[0]?.version ?? null;
+        if (current === null)
+            return false; // absent ⇒ idempotent no-op, EVEN under CAS
+        // Enforced compare-and-swap, atomic against the in-process map (no check-then-write
+        // window — synchronous with no `await` between the check above and the mutation below).
+        if (options.expectedVersion !== undefined && current !== options.expectedVersion) {
+            throw new VersionConflict(id, options.expectedVersion, current);
+        }
+        // D5: the whole chain is purged, not just the head — `versions(id)` reports `[]`
+        // afterward, matching a never-written concept (a delete's history is unobservable).
+        this.chains.delete(id);
+        return true;
+    }
+    async exists(id) {
+        assertSafeConceptId(id);
+        return this.chains.has(id);
+    }
+    async list(prefix) {
+        const ids = [...this.chains.keys()].filter((id) => !prefix || id.startsWith(prefix));
+        ids.sort((a, b) => a.localeCompare(b));
+        return ids;
+    }
+    async versions(id) {
+        assertSafeConceptId(id);
+        const chain = this.chains.get(id) ?? [];
+        // Strip the stored doc snapshot; expose only the history metadata (newest-first).
+        // `agent` is omitted (not merely `undefined`-valued) when the revision was never
+        // agent-attested, so a never-agent'd revision serializes clean over the wire.
+        return chain.map(({ version, actor, timestamp, agent }) => agent === undefined ? { version, actor, timestamp } : { version, actor, timestamp, agent });
+    }
+    async readReserved(dir, name) {
+        assertSafeReservedDir(dir);
+        const content = this.reserved.get(reservedKey(dir, name));
+        if (content === undefined)
+            return null;
+        // Content-addressed, so the token matches the filesystem adapter's for identical bytes.
+        return { content, version: versionOfBytes(content) };
+    }
+    async writeReserved(dir, name, content, options = {}) {
+        assertSafeReservedDir(dir);
+        const key = reservedKey(dir, name);
+        const existing = this.reserved.get(key);
+        const current = existing === undefined ? null : versionOfBytes(existing);
+        // Enforced compare-and-swap, atomic against the in-process map (no check-then-write window).
+        if (options.expectedVersion !== undefined && options.expectedVersion !== current) {
+            throw new VersionConflict(key, options.expectedVersion, current);
+        }
+        this.reserved.set(key, content);
+        return versionOfBytes(content);
+    }
+    // ── blobs: opaque bytes + a content-type ──────────────────────────────────
+    async readBlob(key) {
+        assertSafeBlobKey(key);
+        const entry = this.blobs.get(key);
+        if (!entry)
+            return null;
+        // `new Uint8Array(entry.bytes)`, NOT `entry.bytes.slice()`: a `Buffer` (the shape
+        // every real caller's bytes actually are — `fs.readFile`, the CLI's `promote`)
+        // OVERRIDES `.slice()` to return a VIEW onto the SAME underlying ArrayBuffer, not a
+        // copy — a caller mutating its own buffer after the fact would silently mutate the
+        // "stored" blob too. The constructor form always copies element-by-element into a
+        // fresh buffer, regardless of the input's concrete TypedArray subclass.
+        return { bytes: new Uint8Array(entry.bytes), contentType: entry.contentType, version: entry.version };
+    }
+    async writeBlob(key, bytes, contentType, options = {}) {
+        assertSafeBlobKey(key);
+        const existing = this.blobs.get(key);
+        const current = existing?.version ?? null;
+        // Enforced compare-and-swap, atomic against the in-process map (no check-then-write window).
+        if (options.expectedVersion !== undefined && options.expectedVersion !== current) {
+            throw new VersionConflict(key, options.expectedVersion, current);
+        }
+        const version = blobVersion(bytes);
+        // Unlike FilesystemBackend, this adapter KEEPS STATE, so an explicit content-type
+        // override is persisted (not merely inferred-on-read) — the documented divergence
+        // the tri-adapter contentType parity test pins (B5).
+        const resolvedType = resolveContentType(key, contentType);
+        // Idempotent: a byte-identical AND content-type-identical re-write is a true
+        // same-version no-op (I7) — mirrors write()'s content-address idempotency.
+        if (existing && existing.version === version && existing.contentType === resolvedType) {
+            return version;
+        }
+        // See readBlob's comment: `new Uint8Array(bytes)`, never `bytes.slice()` (a Buffer's
+        // `.slice()` returns a shared VIEW, not a copy) — the caller's own buffer must not
+        // alias what gets stored.
+        this.blobs.set(key, { bytes: new Uint8Array(bytes), contentType: resolvedType, version });
+        return version;
+    }
+    async deleteBlob(key, options = {}) {
+        assertSafeBlobKey(key);
+        const existing = this.blobs.get(key);
+        const current = existing?.version ?? null;
+        if (current === null)
+            return false; // absent ⇒ idempotent no-op, EVEN under CAS
+        if (options.expectedVersion !== undefined && current !== options.expectedVersion) {
+            throw new VersionConflict(key, options.expectedVersion, current);
+        }
+        this.blobs.delete(key);
+        return true;
+    }
+    async existsBlob(key) {
+        assertSafeBlobKey(key);
+        return this.blobs.has(key);
+    }
+    async listBlobs(prefix) {
+        const keys = [...this.blobs.keys()].filter((k) => !prefix || k.startsWith(prefix));
+        keys.sort((a, b) => a.localeCompare(b));
+        return keys;
+    }
+}
+//# sourceMappingURL=memory-backend.js.map

package/dist/memory-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-backend.js","sourceRoot":"","sources":["../src/memory-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACpG,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA2B7G,kFAAkF;AAClF,SAAS,QAAQ,CAAI,KAAQ;IAC3B,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAeD,iGAAiG;AACjG,SAAS,QAAQ,CAAC,EAAa;IAC7B,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,wBAAwB,EAAE,GAAG,CAA0B,CAAC;IAC9E,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC;IACpB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uGAAuG;AACvG,SAAS,WAAW,CAAC,GAAW,EAAE,IAAsB;IACtD,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAChE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACxB,uEAAuE;IACtD,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC3D,wCAAwC;IACvB,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtD,4FAA4F;IAC3E,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEvD,KAAK,CAAC,IAAI,CAAC,EAAa;QACtB,oFAAoF;QACpF,4EAA4E;QAC5E,mBAAmB,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI;YAAE,MAAM,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC9B,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,GAAgB;QAC7B,mFAAmF;QACnF,6EAA6E;QAC7E,KAAK,MAAM,EAAE,IAAI,GAAG;YAAE,mBAAmB,CAAC,EAAE,CAAC,CAAC;QAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,EAAa,EAAE,GAAgB,EAAE,UAAwB,EAAE;QACrE,mBAAmB,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;QAC5C,gEAAgE;QAChE,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS,IAAI,OAAO,CAAC,eAAe,KAAK,OAAO,EAAE,CAAC;YACjF,MAAM,IAAI,eAAe,CAAC,EAAE,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAClE,CAAC;QACD,0FAA0F;QAC1F,4FAA4F;QAC5F,wFAAwF;QACxF,MAAM,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;QAC1C,kFAAkF;QAClF,yFAAyF;QACzF,IAAI,OAAO,KAAK,OAAO;YAAE,OAAO,OAAO,CAAC;QACxC,MAAM,QAAQ,GAAa;YACzB,OAAO;YACP,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,YAAY,EAAE;YAC9C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,gFAAgF;YAChF,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,SAAS;YACzC,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC;SACzB,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/D,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAa,EAAE,UAAyB,EAAE;QACrD,mBAAmB,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;QAC5C,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,CAAC,4CAA4C;QAChF,oFAAoF;QACpF,wFAAwF;QACxF,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS,IAAI,OAAO,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC;YACjF,MAAM,IAAI,eAAe,CAAC,EAAE,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAClE,CAAC;QACD,iFAAiF;QACjF,oFAAoF;QACpF,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAa;QACxB,mBAAmB,CAAC,EAAE,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAe;QACxB,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACrF,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,EAAa;QAC1B,mBAAmB,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QACxC,kFAAkF;QAClF,iFAAiF;QACjF,8EAA8E;QAC9E,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,CACxD,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAC3F,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,GAAW,EAAE,IAAsB;QACpD,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1D,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACvC,wFAAwF;QACxF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,GAAW,EACX,IAAsB,EACtB,OAAe,EACf,UAAwB,EAAE;QAE1B,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QACzE,6FAA6F;QAC7F,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS,IAAI,OAAO,CAAC,eAAe,KAAK,OAAO,EAAE,CAAC;YACjF,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAChC,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,6EAA6E;IAE7E,KAAK,CAAC,QAAQ,CAAC,GAAY;QACzB,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,kFAAkF;QAClF,+EAA+E;QAC/E,oFAAoF;QACpF,mFAAmF;QACnF,kFAAkF;QAClF,wEAAwE;QACxE,OAAO,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;IACxG,CAAC;IAED,KAAK,CAAC,SAAS,CACb,GAAY,EACZ,KAAiB,EACjB,WAAoB,EACpB,UAAwB,EAAE;QAE1B,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,QAAQ,EAAE,OAAO,IAAI,IAAI,CAAC;QAC1C,6FAA6F;QAC7F,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS,IAAI,OAAO,CAAC,eAAe,KAAK,OAAO,EAAE,CAAC;YACjF,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACnC,kFAAkF;QAClF,kFAAkF;QAClF,qDAAqD;QACrD,MAAM,YAAY,GAAG,kBAAkB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QAC1D,6EAA6E;QAC7E,2EAA2E;QAC3E,IAAI,QAAQ,IAAI,QAAQ,CAAC,OAAO,KAAK,OAAO,IAAI,QAAQ,CAAC,WAAW,KAAK,YAAY,EAAE,CAAC;YACtF,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,qFAAqF;QACrF,mFAAmF;QACnF,0BAA0B;QAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1F,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAAY,EAAE,UAAyB,EAAE;QACxD,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,QAAQ,EAAE,OAAO,IAAI,IAAI,CAAC;QAC1C,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,CAAC,4CAA4C;QAChF,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS,IAAI,OAAO,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC;YACjF,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAAY;QAC3B,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAe;QAC7B,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/mutation-attribution.d.ts

@@ -0,0 +1,19 @@
+import type { Frontmatter } from "./types.js";
+/** Producer-qualified portable projection of the actor behind the latest Superbee mutation. */
+export declare const SUPERBEE_UPDATED_BY_FIELD = "superbee_updated_by";
+/**
+ * Resolve advisory mutation attribution from document bytes.
+ *
+ * The producer-qualified v0.2 extension wins. The remaining spellings preserve permissive
+ * consumption of documents written before the extension existed.
+ */
+export declare function mutationActorFromFrontmatter(frontmatter: Readonly<Record<string, unknown>>): string | undefined;
+export interface PersistMutationActorOptions {
+    actor: string | undefined;
+    okfVersion: "0.1" | "0.2";
+    /** A v0.2 Kind may independently require the legacy-named `actor` field. */
+    kindRequiresActor: boolean;
+}
+/** Apply the edition-appropriate portable mutation-attribution coordinate. */
+export declare function persistMutationActor(frontmatter: Frontmatter, options: PersistMutationActorOptions): Frontmatter;
+//# sourceMappingURL=mutation-attribution.d.ts.map

package/dist/mutation-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-attribution.d.ts","sourceRoot":"","sources":["../src/mutation-attribution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,+FAA+F;AAC/F,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAM/D;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC7C,MAAM,GAAG,SAAS,CAIpB;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,UAAU,EAAE,KAAK,GAAG,KAAK,CAAC;IAC1B,4EAA4E;IAC5E,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,2BAA2B,GACnC,WAAW,CAcb"}

package/dist/mutation-attribution.js

@@ -0,0 +1,34 @@
+/** Producer-qualified portable projection of the actor behind the latest Superbee mutation. */
+export const SUPERBEE_UPDATED_BY_FIELD = "superbee_updated_by";
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+/**
+ * Resolve advisory mutation attribution from document bytes.
+ *
+ * The producer-qualified v0.2 extension wins. The remaining spellings preserve permissive
+ * consumption of documents written before the extension existed.
+ */
+export function mutationActorFromFrontmatter(frontmatter) {
+    return nonEmptyString(frontmatter[SUPERBEE_UPDATED_BY_FIELD])
+        ?? nonEmptyString(frontmatter.updated_by)
+        ?? nonEmptyString(frontmatter.actor);
+}
+/** Apply the edition-appropriate portable mutation-attribution coordinate. */
+export function persistMutationActor(frontmatter, options) {
+    if (options.actor === undefined) {
+        if (options.okfVersion === "0.1" || !(SUPERBEE_UPDATED_BY_FIELD in frontmatter)) {
+            return frontmatter;
+        }
+        const { [SUPERBEE_UPDATED_BY_FIELD]: _previousActor, ...rest } = frontmatter;
+        return rest;
+    }
+    if (options.okfVersion === "0.1")
+        return { ...frontmatter, actor: options.actor };
+    return {
+        ...frontmatter,
+        [SUPERBEE_UPDATED_BY_FIELD]: options.actor,
+        ...(options.kindRequiresActor ? { actor: options.actor } : {}),
+    };
+}
+//# sourceMappingURL=mutation-attribution.js.map

package/dist/mutation-attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-attribution.js","sourceRoot":"","sources":["../src/mutation-attribution.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;AAE/D,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACrF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAC1C,WAA8C;IAE9C,OAAO,cAAc,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAC;WACxD,cAAc,CAAC,WAAW,CAAC,UAAU,CAAC;WACtC,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AASD,8EAA8E;AAC9E,MAAM,UAAU,oBAAoB,CAClC,WAAwB,EACxB,OAAoC;IAEpC,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,OAAO,CAAC,UAAU,KAAK,KAAK,IAAI,CAAC,CAAC,yBAAyB,IAAI,WAAW,CAAC,EAAE,CAAC;YAChF,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,MAAM,EAAE,CAAC,yBAAyB,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,WAAW,CAAC;QAC7E,OAAO,IAAmB,CAAC;IAC7B,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,KAAK,KAAK;QAAE,OAAO,EAAE,GAAG,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;IAClF,OAAO;QACL,GAAG,WAAW;QACd,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC,KAAK;QAC1C,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC"}

package/dist/mutation.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The ONE versioned-mutation boundary: every read-modify-write over this engine's
+ * compare-and-swap seam for one independently retryable document/link mutation reduces to
+ * the SAME shape — a fresh versioned
+ * read, a domain decision over exactly that read, and a CAS write bounded-retried on
+ * conflict. This module is that shape, extracted once so the retry loop cannot drift
+ * between the prior hand-rolled document overwrite/patch and `link add` copies — see
+ * the single-authority contract: ONE
+ * implementation, consumed everywhere, not a schema fork.
+ *
+ * The structural property that kills the "stale decision paired with a fresher CAS token"
+ * bug class: {@link VersionedMutationOptions.decide} is handed ONLY the state a fresh
+ * {@link VersionedMutationOptions.read} just produced — never a version token, never a
+ * previous attempt's state — and {@link VersionedMutationOptions.write} CASes with THAT
+ * SAME read's version. A caller cannot compute a decision once and merely retry the WRITE
+ * with a newer token; each attempt re-derives its decision from its own fresh read.
+ *
+ * What this guarantees is VERSION-safety (a decision is always paired with the read that
+ * produced it), NOT domain-invariant-safety. `decide` receiving a fresh `state` every attempt
+ * means stale BYTES are structurally impossible to act on — it does NOT mean a consumer's
+ * decision logic automatically re-checks whatever assumption it made about that state BEFORE
+ * the retry loop started. A `decide` that only re-derives PART of its decision from `state`
+ * (e.g. re-splicing a field list while silently trusting an invariant — "this doc still
+ * governs kind X" — that was true when the caller looked the doc up, but is not re-verified
+ * against THIS attempt's fresh read) can still commit a change that is well-formed CAS-wise
+ * and wrong domain-wise. Every consumer's `decide` MUST derive its ENTIRE decision — including
+ * re-checking any mutable invariant it depends on — from the `state` it was just handed, not
+ * from anything captured before the loop began; the primitive cannot enforce this for a
+ * caller. For example, `kind.ts`'s `buildCandidate` re-verifies `governs` on every attempt; merely
+ * re-splicing field lists would not prove that the convention still governs the kind being edited.
+ */
+import type { Version } from "./types.js";
+/**
+ * What {@link VersionedMutationOptions.decide} resolves a single attempt to: either commit
+ * `next` (CAS write against this attempt's read version) or converge with no write at all
+ * (`done` — e.g. an idempotent no-op, or a retry that discovers a competing writer already
+ * made the same change).
+ */
+export type MutationDecision<S, R> = {
+    action: "write";
+    next: S;
+    result: R;
+} | {
+    action: "done";
+    result: R;
+};
+/** Inputs to a {@link versionedMutation} call, parameterized over the mutated state `S` and the caller's result shape `R`. */
+export interface VersionedMutationOptions<S, R> {
+    /** A FRESH versioned read, called once per attempt. `version: null` means the state is absent (an expect-absent CAS basis). */
+    read: () => Promise<{
+        state: S | undefined;
+        version: Version | null;
+    }>;
+    /**
+     * Re-run against EVERY attempt's fresh `state` — never a previous attempt's decision, never a
+     * version token (decisions are made over domain state only; CAS pairing is this module's job,
+     * not the caller's). Safe to call more than once; may throw a terminal domain error, which
+     * propagates out of {@link versionedMutation} unchanged (not retried).
+     */
+    decide: (state: S | undefined, attempt: number) => MutationDecision<S, R> | Promise<MutationDecision<S, R>>;
+    /** CAS-write `next`, conditional on THIS attempt's read version (`null` = expect-absent create). Returns the new version. */
+    write: (next: S, expectedVersion: Version | null) => Promise<Version>;
+    /** Bounded retry budget. Default 5. `1` makes a conflict terminal (hard single-shot CAS, no retry). */
+    maxAttempts?: number;
+}
+/** The result of a {@link versionedMutation} call. */
+export interface VersionedMutationOutcome<R> {
+    /** The winning attempt's decision result. */
+    result: R;
+    /** The version current after this call: the write's new version, or (a `done` convergence) the read's version. */
+    version: Version | null;
+    /** `true` if a write actually happened; `false` for a `done` convergence. */
+    wrote: boolean;
+}
+/**
+ * Run one versioned read-decide-write cycle, retrying on a {@link VersionConflict} up to
+ * `maxAttempts` (default 5). Each attempt: (1) one fresh `read`; (2) `decide` against THAT
+ * state only; (3) `done` returns immediately with no write; (4) `write` CASes with THAT
+ * attempt's own version; (5) a `VersionConflict` retries (fresh read, fresh decide) while
+ * budget remains, else the final `VersionConflict` is RETHROWN unchanged — callers map it
+ * to their own conflict shape (e.g. `STALE_HEAD`, exit 5); (6) a `ConcurrentReplacementError`
+ * from `read` or `write` (the filesystem adapter could not bind the attempt to one safe entry) is
+ * the same contention in filesystem clothing and retries the COMPLETE fresh read/decide/CAS cycle
+ * on the SAME attempt budget, so
+ * `maxAttempts: 1` makes it terminal too; (7) any other thrown error is terminal and propagates
+ * unchanged.
+ */
+export declare function versionedMutation<S, R>(opts: VersionedMutationOptions<S, R>): Promise<VersionedMutationOutcome<R>>;
+//# sourceMappingURL=mutation.d.ts.map

package/dist/mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation.d.ts","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAe1C;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,CAAC,IAC7B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC;AAElC,8HAA8H;AAC9H,MAAM,WAAW,wBAAwB,CAAC,CAAC,EAAE,CAAC;IAC5C,+HAA+H;IAC/H,IAAI,EAAE,MAAM,OAAO,CAAC;QAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5G,6HAA6H;IAC7H,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,eAAe,EAAE,OAAO,GAAG,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,uGAAuG;IACvG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sDAAsD;AACtD,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,6CAA6C;IAC7C,MAAM,EAAE,CAAC,CAAC;IACV,kHAAkH;IAClH,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAC1C,IAAI,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GACnC,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CA8BtC"}

package/dist/mutation.js

@@ -0,0 +1,94 @@
+/**
+ * The ONE versioned-mutation boundary: every read-modify-write over this engine's
+ * compare-and-swap seam for one independently retryable document/link mutation reduces to
+ * the SAME shape — a fresh versioned
+ * read, a domain decision over exactly that read, and a CAS write bounded-retried on
+ * conflict. This module is that shape, extracted once so the retry loop cannot drift
+ * between the prior hand-rolled document overwrite/patch and `link add` copies — see
+ * the single-authority contract: ONE
+ * implementation, consumed everywhere, not a schema fork.
+ *
+ * The structural property that kills the "stale decision paired with a fresher CAS token"
+ * bug class: {@link VersionedMutationOptions.decide} is handed ONLY the state a fresh
+ * {@link VersionedMutationOptions.read} just produced — never a version token, never a
+ * previous attempt's state — and {@link VersionedMutationOptions.write} CASes with THAT
+ * SAME read's version. A caller cannot compute a decision once and merely retry the WRITE
+ * with a newer token; each attempt re-derives its decision from its own fresh read.
+ *
+ * What this guarantees is VERSION-safety (a decision is always paired with the read that
+ * produced it), NOT domain-invariant-safety. `decide` receiving a fresh `state` every attempt
+ * means stale BYTES are structurally impossible to act on — it does NOT mean a consumer's
+ * decision logic automatically re-checks whatever assumption it made about that state BEFORE
+ * the retry loop started. A `decide` that only re-derives PART of its decision from `state`
+ * (e.g. re-splicing a field list while silently trusting an invariant — "this doc still
+ * governs kind X" — that was true when the caller looked the doc up, but is not re-verified
+ * against THIS attempt's fresh read) can still commit a change that is well-formed CAS-wise
+ * and wrong domain-wise. Every consumer's `decide` MUST derive its ENTIRE decision — including
+ * re-checking any mutable invariant it depends on — from the `state` it was just handed, not
+ * from anything captured before the loop began; the primitive cannot enforce this for a
+ * caller. For example, `kind.ts`'s `buildCandidate` re-verifies `governs` on every attempt; merely
+ * re-splicing field lists would not prove that the convention still governs the kind being edited.
+ */
+import { setTimeout as delay } from "node:timers/promises";
+import { ConcurrentReplacementError } from "./errors.js";
+import { VersionConflict } from "./versioning.js";
+/** Bounded compare-and-swap retry budget for a {@link versionedMutation} call, unless overridden. */
+const CAS_MAX_ATTEMPTS = 5;
+/**
+ * Honor a host-provided transient-contention hint between complete attempts. The attempt-indexed
+ * growth restores useful Windows sharing-violation tolerance without ever retrying the unsafe
+ * rename itself; ordinary observation replacement has no delay hint and retries immediately.
+ */
+async function waitForFreshAttempt(error, attempt) {
+    if (error.retryAfterMs <= 0)
+        return;
+    await delay(error.retryAfterMs * (4 ** attempt));
+}
+/**
+ * Run one versioned read-decide-write cycle, retrying on a {@link VersionConflict} up to
+ * `maxAttempts` (default 5). Each attempt: (1) one fresh `read`; (2) `decide` against THAT
+ * state only; (3) `done` returns immediately with no write; (4) `write` CASes with THAT
+ * attempt's own version; (5) a `VersionConflict` retries (fresh read, fresh decide) while
+ * budget remains, else the final `VersionConflict` is RETHROWN unchanged — callers map it
+ * to their own conflict shape (e.g. `STALE_HEAD`, exit 5); (6) a `ConcurrentReplacementError`
+ * from `read` or `write` (the filesystem adapter could not bind the attempt to one safe entry) is
+ * the same contention in filesystem clothing and retries the COMPLETE fresh read/decide/CAS cycle
+ * on the SAME attempt budget, so
+ * `maxAttempts: 1` makes it terminal too; (7) any other thrown error is terminal and propagates
+ * unchanged.
+ */
+export async function versionedMutation(opts) {
+    const maxAttempts = opts.maxAttempts ?? CAS_MAX_ATTEMPTS;
+    for (let attempt = 0;; attempt++) {
+        let fresh;
+        try {
+            fresh = await opts.read();
+        }
+        catch (err) {
+            if (err instanceof ConcurrentReplacementError && attempt < maxAttempts - 1) {
+                await waitForFreshAttempt(err, attempt);
+                continue;
+            }
+            throw err;
+        }
+        const { state, version } = fresh;
+        const decision = await opts.decide(state, attempt);
+        if (decision.action === "done") {
+            return { result: decision.result, version, wrote: false };
+        }
+        try {
+            const newVersion = await opts.write(decision.next, version);
+            return { result: decision.result, version: newVersion, wrote: true };
+        }
+        catch (err) {
+            if (err instanceof VersionConflict && attempt < maxAttempts - 1)
+                continue;
+            if (err instanceof ConcurrentReplacementError && attempt < maxAttempts - 1) {
+                await waitForFreshAttempt(err, attempt);
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=mutation.js.map

package/dist/mutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation.js","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,qGAAqG;AACrG,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;GAIG;AACH,KAAK,UAAU,mBAAmB,CAAC,KAAiC,EAAE,OAAe;IACnF,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC;QAAE,OAAO;IACpC,MAAM,KAAK,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC;AACnD,CAAC;AAuCD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAoC;IAEpC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,gBAAgB,CAAC;IACzD,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,KAAwD,CAAC;QAC7D,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,0BAA0B,IAAI,OAAO,GAAG,WAAW,GAAG,CAAC,EAAE,CAAC;gBAC3E,MAAM,mBAAmB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBACxC,SAAS;YACX,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;QACjC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC/B,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC5D,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACvE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,eAAe,IAAI,OAAO,GAAG,WAAW,GAAG,CAAC;gBAAE,SAAS;YAC1E,IAAI,GAAG,YAAY,0BAA0B,IAAI,OAAO,GAAG,WAAW,GAAG,CAAC,EAAE,CAAC;gBAC3E,MAAM,mBAAmB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBACxC,SAAS;YACX,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/page.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure View registry/entry path grammar shared by every producer and consumer.
+ *
+ * `View` is the ONLY accepted kind name: the legacy `Page` spelling is no longer read
+ * (the repo's `migrate-legacy-view-names` script renames legacy content in place). Registry ids
+ * are concept ids under `views-registry/` (legacy `pages-registry/` LOCATIONS stay recognized;
+ * relocation is a separate open decision); entries are opaque blob keys under
+ * `views/` (legacy `pages/`). Both retain exact, case-preserving nested paths while
+ * rejecting spellings that discovery or storage cannot safely round-trip. ONE segment
+ * grammar, parameterized by prefix — never a parallel module per name.
+ */
+/** Legacy registry-id prefix — the LOCATION stays recognized (only the legacy kind NAME is retired). */
+export declare const PAGE_REGISTRY_PREFIX = "pages-registry/";
+/** Legacy blob-key prefix for View entries — the LOCATION stays recognized. */
+export declare const PAGE_ENTRY_PREFIX = "pages/";
+/** Current registry-id prefix for `type: View` docs. */
+export declare const VIEW_REGISTRY_PREFIX = "views-registry/";
+/** Current blob-key prefix for View entries. */
+export declare const VIEW_ENTRY_PREFIX = "views/";
+/**
+ * The kind names the launcher/registry surfaces accept: exactly `View`. Exact, case-sensitive
+ * match. The legacy `Page` name is deliberately NOT here — a Page-typed doc no longer registers
+ * anywhere (the CLI's `status` legacy_naming finding is the loud diagnostic for leftover stock,
+ * and `migrate-legacy-view-names` is the remedy).
+ */
+export declare const PAGE_TYPE_NAMES: readonly ["View"];
+export type PageTypeName = (typeof PAGE_TYPE_NAMES)[number];
+/**
+ * The shell-enforced capability requested by a registered View. `bundle-propose` includes the
+ * read surface but grants no direct write authority: it may only propose a narrow action for the
+ * trusted shell and human to confirm. Unknown values fail closed to `none`.
+ */
+export type BridgeCapability = "none" | "bundle-read" | "bundle-propose";
+/** One capability resolver shared by registry parsing and the loopback server's security gates. */
+export declare function resolveBridgeCapability(value: unknown): BridgeCapability;
+/**
+ * THE one reader of the registry-doc capability FIELD: `access`, and ONLY `access`. The legacy
+ * `bridge` spelling is no longer read — a doc declaring only `bridge` resolves to `undefined`
+ * here and fails closed to `none` downstream (the `migrate-legacy-view-names` script renames
+ * existing stock in place; the CLI's `status` legacy_naming finding flags leftover `bridge`
+ * fields loudly).
+ */
+export declare function declaredAccessValue(frontmatter: Record<string, unknown>): unknown;
+/** Resolve a registry doc's declared capability: {@link declaredAccessValue} through the fail-closed {@link resolveBridgeCapability} — an absent or unrecognized `access` yields `none`. */
+export declare function resolveDeclaredAccess(frontmatter: Record<string, unknown>): BridgeCapability;
+/** True iff `value` is exactly the accepted kind name (`View`). The legacy `Page` name is rejected. */
+export declare function isPageTypeName(value: unknown): value is PageTypeName;
+/** Strict concept-id grammar for registry documents at the legacy LOCATION (`pages-registry/…`). Nested ids and ordinary dots are valid. */
+export declare function isPageRegistryId(id: unknown): id is string;
+/** Strict concept-id grammar for View registry documents (`views-registry/…`) — the SAME segment rules as {@link isPageRegistryId}. */
+export declare function isViewRegistryId(id: unknown): id is string;
+/** True iff `id` is a valid registry id under EITHER accepted prefix (`views-registry/` or legacy `pages-registry/`). */
+export declare function isAnyRegistryId(id: unknown): id is string;
+/** Strict blob-key grammar for executable View entries at the legacy LOCATION (`pages/…`). */
+export declare function isPageEntryKey(entry: unknown): entry is string;
+/** Strict blob-key grammar for executable View entries (`views/…`) — the SAME segment rules as {@link isPageEntryKey}. */
+export declare function isViewEntryKey(entry: unknown): entry is string;
+/** True iff `entry` is a valid entry key under EITHER accepted prefix (`views/` or legacy `pages/`). */
+export declare function isAnyEntryKey(entry: unknown): entry is string;
+/** True only for the content-addressed version tokens allowed to pin executable View bytes. */
+export declare function isViewEntryVersion(value: unknown): value is string;
+/** A complete, valid View registration — one identity, entry, and optional exact-byte pin. */
+export interface PageRegistration {
+    /** The registry doc's concept id (under an accepted registry prefix). */
+    id: string;
+    /** The accepted kind name the doc declares — exactly `View`. */
+    type: PageTypeName;
+    /** The declared executable entry blob key (under an accepted entry prefix). */
+    entry: string;
+    /** Optional exact blob-version pin. When present, every host must refuse other bytes. */
+    entryVersion?: string;
+}
+/**
+ * THE one registration predicate: a doc is a usable View registration iff its id satisfies
+ * an accepted registry-id grammar ({@link isAnyRegistryId}), its `type` is exactly an accepted
+ * kind name ({@link isPageTypeName}), AND its `entry` satisfies an accepted entry-key grammar
+ * ({@link isAnyEntryKey}). An explicitly declared `entry_version` must be a canonical
+ * content-addressed token. Returns the validated registration, or `null`.
+ *
+ * This is a SECURITY boundary shared by every surface that decides what counts as a registered
+ * page — the launcher/`open-page` parse (ui `parseRegisteredPage`), the `ui` command's
+ * nonce-mint allowlist, and its serve-time re-verification. All of them MUST consume this one
+ * function: a doc any surface rejects must be un-mintable and un-servable everywhere, never
+ * "rejected by the launcher but still served by the nonce route".
+ */
+export declare function parseRegistration(id: unknown, frontmatter: Record<string, unknown>): PageRegistration | null;
+//# sourceMappingURL=page.d.ts.map

package/dist/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,wGAAwG;AACxG,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AACtD,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAC1C,wDAAwD;AACxD,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AACtD,gDAAgD;AAChD,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,mBAAoB,CAAC;AACjD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEzE,mGAAmG;AACnG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAIjF;AAED,4LAA4L;AAC5L,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAE5F;AAED,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AA4CD,4IAA4I;AAC5I,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAE1D;AAED,uIAAuI;AACvI,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAE1D;AAED,yHAAyH;AACzH,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAEzD;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED,0HAA0H;AAC1H,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE7D;AAED,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAElE;AAED,8FAA8F;AAC9F,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,IAAI,EAAE,YAAY,CAAC;IACnB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,GAAG,IAAI,CAiB5G"}