@superbee/core 0.1.6 → 0.2.0-pre.10

package/dist/uncertain-write.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The shared uncertain-write primitive: durable request identity, unknown-outcome handling, and
+ * acknowledgement reconciliation for a write whose delivery to a shared authority may be lost.
+ *
+ * A network write has three answers, not two: the authority applied it, refused it, or the
+ * client cannot tell (a dropped response, a timeout, a transport error). Retrying a write in the
+ * third case is only safe when the authority can recognize the retry as the same request, so
+ * every write carries a {@link OperationIntent.requestId} minted once when the intent is first
+ * recorded and never reminted, and every transport offers {@link OperationTransport.lookup} to
+ * fetch the authority's recorded outcome for that id.
+ *
+ * This module is owned by core so the browser-local sync component and bounded CLI remote
+ * operations consume one primitive rather than each defining unknown-outcome handling. It
+ * imports no Node builtin and bundles for the browser. The only injected time source is the
+ * `sleep` used for the submission deadline and the delay between lookups; there is no
+ * injectable clock, and a transport's own latency is real.
+ */
+import type { Version } from "./types.js";
+/**
+ * The operation an intent performs: a whole-document write, or `document.delete` (the document
+ * leaves at exactly the intent's base). The union is open.
+ */
+export type OperationKind = "document.write" | "document.delete" | (string & {});
+/**
+ * The journal states of an intent. `unknown` is the primitive's own classification of an
+ * exhausted attempt: the authority may or may not hold the write, and a later attempt begins
+ * with a lookup rather than a submission.
+ */
+export type OperationState = "pending" | "in_flight" | "acknowledged" | "conflict" | "refused" | "unknown";
+/** A recorded local write awaiting a shared outcome. */
+export interface OperationIntent {
+    /** Durable request identity: minted once at record time, reused verbatim on every retry. */
+    requestId: string;
+    kind: OperationKind;
+    /** The target the operation applies to; a concept id for `document.write`. */
+    target: string;
+    /**
+     * The tombstone a create acknowledges it re-creates: the id's latest deletion, as the
+     * authority named it. Set only by an explicit decision to re-create a deleted document (the
+     * caller's own observed delete, or `keep` on a "deleted remotely" conflict), and only on a
+     * create recorded after that decision; never inferred by a transport. An authority whose latest
+     * deletion of the id is another one refuses the create, and the refusal comes back as a
+     * conflict.
+     */
+    recreates?: Version;
+    /** The shared version the local edit was made against, or `null` for a create. */
+    base: Version | null;
+    /** The content-addressed version of `content`. */
+    local: Version;
+    /** The serialized document: the comparison content reconciliation needs later. */
+    content: string;
+    createdAt: string;
+    /**
+     * Submissions made or durably claimed so far. A non-zero count means the authority may already
+     * hold the write, so delivery begins with a lookup rather than a submission; a journal records
+     * the count before a submission leaves, never only after its outcome is known.
+     */
+    attempts: number;
+    state: OperationState;
+}
+/** The authority's answer for one request identity. */
+export type Outcome = {
+    kind: "committed";
+    version: Version;
+}
+/**
+ * The shared head moved. `actual` is the version the authority serves now, or `null` when it
+ * serves none ("deleted remotely"). With `actual: null`, `tombstone` names the deletion the
+ * authority reported, when it reported one: the acknowledgement a deliberate re-create sends.
+ * It is never a version any read serves, so it is never a base or a remote version.
+ */
+ | {
+    kind: "conflict";
+    actual: Version | null;
+    tombstone?: Version;
+} | {
+    kind: "refused";
+    code: string;
+    message: string;
+} | {
+    kind: "unknown";
+};
+/** A transport to a shared authority that records outcomes by request identity. */
+export interface OperationTransport {
+    /** Deliver the intent once; a repeated `requestId` must return the recorded outcome unchanged. */
+    submit(intent: OperationIntent, options?: {
+        signal?: AbortSignal;
+    }): Promise<Outcome>;
+    /** The recorded outcome for `requestId`, or `null` when the authority never recorded it. */
+    lookup(requestId: string): Promise<Outcome | null>;
+}
+/** Wait `ms`, resolving early and harmlessly when `signal` aborts. Injected by tests. */
+export type Sleep = (ms: number, signal?: AbortSignal) => Promise<void>;
+export interface UncertainWriteOptions {
+    /** Exact-content writes may settle matching conflicts; governed writes require recorded evidence. */
+    settlement?: "exact-content" | "recorded-only";
+    /** How long one submission may take before its outcome is treated as unknown. */
+    deadlineMs?: number;
+    /** Lookups attempted after an unknown submission before giving up (default 3). */
+    maxLookups?: number;
+    /** Delay between lookups (default 250 ms; the injected `sleep` decides what that means). */
+    lookupDelayMs?: number;
+    /** Submissions permitted in one call, counting the first (default 2). */
+    maxSubmissions?: number;
+    /** Timer; defaults to a `setTimeout` sleep. */
+    sleep?: Sleep;
+}
+export interface UncertainWriteResult {
+    /** The intent with `attempts` and `state` advanced to reflect this call. */
+    intent: OperationIntent;
+    outcome: Outcome;
+    /** How many times `lookup` was called in this call. */
+    lookups: number;
+}
+/**
+ * Refusal codes that pause shared operations rather than say the content is wrong: the caller's
+ * authorization is gone, or a hosted sync quota (`REQUEST_CAPACITY_*`, one per scope the host
+ * names) is spent. Nothing is lost; the refused intents are requeued when the store resumes.
+ */
+export declare const AUTHORIZATION_REFUSAL_CODES: ReadonlySet<string>;
+/** True when a refusal reports lost permission, which pauses further shared operations. */
+export declare function isAuthorizationRefusal(outcome: Outcome): boolean;
+/** The journal state an outcome settles an intent into. */
+export declare function stateForOutcome(outcome: Outcome): OperationState;
+/** The longest request identity the wire accepts as `Idempotency-Key`. */
+export declare const REQUEST_ID_MAX_LENGTH = 128;
+/**
+ * True when `value` is a request identity the wire accepts: 1 to {@link REQUEST_ID_MAX_LENGTH}
+ * printable ASCII characters with no space, and neither `.` nor `..`, which URL normalization
+ * folds away so the lookup route could never name them. One rule, checked by the client before
+ * a header is built and by the reference router before a key is claimed, so the two sides cannot
+ * disagree about which keys identify a write. A minted UUID always satisfies it.
+ */
+export declare function isRequestIdentity(value: string): boolean;
+/** A fresh request identity. UUIDs come from the platform's `crypto` in both Node and browsers. */
+export declare function mintRequestId(): string;
+/**
+ * The outcome as it applies to `intent`. A conflict whose `actual` is the intent's own `local`
+ * version means the shared head already holds exactly this content, so the write is committed
+ * at that version. This is the wire's post-expiry compare-and-swap property: a committed write
+ * whose acknowledgement was lost and whose recorded outcome expired from the authority's
+ * retention window is resubmitted with its original `base`, which no longer matches, and the
+ * authority answers a conflict against the version the client itself committed. If the head
+ * has meanwhile returned to `base` exactly, the premise matches and the resubmission is applied
+ * again instead (see {@link performUncertainWrite}). The mapping depends only on the outcome and
+ * the intent, so the primitive owns it and every consumer settles such a write as acknowledged
+ * rather than presenting it as a concurrent edit. Every other conflict, including one against
+ * an absent head (`actual: null`), is returned unchanged.
+ */
+export declare function settleAgainstIntent(outcome: Outcome, intent: OperationIntent): Outcome;
+/**
+ * Deliver `intent` and settle it against the authority's recorded outcome.
+ *
+ * Flow: when the intent has never been submitted, submit it; when it has (`attempts > 0`), or
+ * when a submission's outcome is unknown, look the request identity up. A positive lookup
+ * settles the intent. A `null` lookup is taken as proof that the authority never recorded the
+ * request, so a resubmission with the same `requestId` is the first delivery and is allowed, up
+ * to `maxSubmissions`. A lookup that fails leaves the outcome unknown and the intent for a later
+ * call.
+ *
+ * No resubmission happens without a `null` lookup because a blind retry after an unknown
+ * outcome is unsound: on an authority without request identity the retry applies the write
+ * twice, and even on one with it the retry can only ever learn what the lookup already knew.
+ * The lookup is what turns "unknown" into a fact before any second delivery.
+ *
+ * That fact is only as good as the transport's `null`. An authority that has expired or lost a
+ * record answers as if it never recorded it, and the reference wire transport returns `null`
+ * then. The resubmission is guarded only by its `base`, and versions are content hashes: if the
+ * write had landed and a third party has since restored `base` exactly, the premise matches, the
+ * write is applied a second time over that revert, and the outcome is `committed`. The hosted
+ * transport never answers `null` for an absent record once the intent is older than the host's
+ * stated retention window, less a skew margin, so it does not resubmit there.
+ *
+ * By default every outcome passes through {@link settleAgainstIntent}, so a conflict naming the
+ * intent's own version is committed. `recorded-only` preserves the recorded outcome instead.
+ */
+export declare function performUncertainWrite(transport: OperationTransport, intent: OperationIntent, options?: UncertainWriteOptions): Promise<UncertainWriteResult>;
+//# sourceMappingURL=uncertain-write.d.ts.map

package/dist/uncertain-write.d.ts.map

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

package/dist/uncertain-write.js

@@ -0,0 +1,198 @@
+/**
+ * The shared uncertain-write primitive: durable request identity, unknown-outcome handling, and
+ * acknowledgement reconciliation for a write whose delivery to a shared authority may be lost.
+ *
+ * A network write has three answers, not two: the authority applied it, refused it, or the
+ * client cannot tell (a dropped response, a timeout, a transport error). Retrying a write in the
+ * third case is only safe when the authority can recognize the retry as the same request, so
+ * every write carries a {@link OperationIntent.requestId} minted once when the intent is first
+ * recorded and never reminted, and every transport offers {@link OperationTransport.lookup} to
+ * fetch the authority's recorded outcome for that id.
+ *
+ * This module is owned by core so the browser-local sync component and bounded CLI remote
+ * operations consume one primitive rather than each defining unknown-outcome handling. It
+ * imports no Node builtin and bundles for the browser. The only injected time source is the
+ * `sleep` used for the submission deadline and the delay between lookups; there is no
+ * injectable clock, and a transport's own latency is real.
+ */
+/**
+ * Refusal codes that pause shared operations rather than say the content is wrong: the caller's
+ * authorization is gone, or a hosted sync quota (`REQUEST_CAPACITY_*`, one per scope the host
+ * names) is spent. Nothing is lost; the refused intents are requeued when the store resumes.
+ */
+export const AUTHORIZATION_REFUSAL_CODES = new Set([
+    "AUTH_REQUIRED",
+    "FORBIDDEN",
+    "UNAUTHORIZED",
+    "PERMISSION_DENIED",
+    "REQUEST_CAPACITY_PRINCIPAL",
+    "REQUEST_CAPACITY_BUNDLE",
+]);
+/** True when a refusal reports lost permission, which pauses further shared operations. */
+export function isAuthorizationRefusal(outcome) {
+    return outcome.kind === "refused" && AUTHORIZATION_REFUSAL_CODES.has(outcome.code);
+}
+/** The journal state an outcome settles an intent into. */
+export function stateForOutcome(outcome) {
+    switch (outcome.kind) {
+        case "committed":
+            return "acknowledged";
+        case "conflict":
+            return "conflict";
+        case "refused":
+            return "refused";
+        case "unknown":
+            return "unknown";
+    }
+}
+/** The longest request identity the wire accepts as `Idempotency-Key`. */
+export const REQUEST_ID_MAX_LENGTH = 128;
+/**
+ * True when `value` is a request identity the wire accepts: 1 to {@link REQUEST_ID_MAX_LENGTH}
+ * printable ASCII characters with no space, and neither `.` nor `..`, which URL normalization
+ * folds away so the lookup route could never name them. One rule, checked by the client before
+ * a header is built and by the reference router before a key is claimed, so the two sides cannot
+ * disagree about which keys identify a write. A minted UUID always satisfies it.
+ */
+export function isRequestIdentity(value) {
+    if (value === "." || value === "..")
+        return false;
+    return value.length >= 1 && value.length <= REQUEST_ID_MAX_LENGTH && /^[!-~]+$/.test(value);
+}
+/** A fresh request identity. UUIDs come from the platform's `crypto` in both Node and browsers. */
+export function mintRequestId() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi && typeof cryptoApi.randomUUID === "function")
+        return cryptoApi.randomUUID();
+    throw new Error("mintRequestId requires crypto.randomUUID in this host.");
+}
+const defaultSleep = (ms, signal) => new Promise((resolve) => {
+    if (signal?.aborted) {
+        resolve();
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    function onAbort() {
+        clearTimeout(timer);
+        resolve();
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+const UNKNOWN = { kind: "unknown" };
+/**
+ * The outcome as it applies to `intent`. A conflict whose `actual` is the intent's own `local`
+ * version means the shared head already holds exactly this content, so the write is committed
+ * at that version. This is the wire's post-expiry compare-and-swap property: a committed write
+ * whose acknowledgement was lost and whose recorded outcome expired from the authority's
+ * retention window is resubmitted with its original `base`, which no longer matches, and the
+ * authority answers a conflict against the version the client itself committed. If the head
+ * has meanwhile returned to `base` exactly, the premise matches and the resubmission is applied
+ * again instead (see {@link performUncertainWrite}). The mapping depends only on the outcome and
+ * the intent, so the primitive owns it and every consumer settles such a write as acknowledged
+ * rather than presenting it as a concurrent edit. Every other conflict, including one against
+ * an absent head (`actual: null`), is returned unchanged.
+ */
+export function settleAgainstIntent(outcome, intent) {
+    if (outcome.kind === "conflict" && outcome.actual !== null && outcome.actual === intent.local) {
+        return { kind: "committed", version: outcome.actual };
+    }
+    return outcome;
+}
+/**
+ * One submission under a deadline. A transport rejection or a deadline overrun both yield
+ * `unknown`: the request may have reached the authority, so nothing here decides otherwise.
+ */
+async function submitOnce(transport, intent, deadlineMs, sleep) {
+    const controller = new AbortController();
+    const attempt = transport.submit(intent, { signal: controller.signal }).then((outcome) => ({ settled: true, outcome }), () => ({ settled: true, outcome: UNKNOWN }));
+    if (deadlineMs === undefined)
+        return (await attempt).outcome;
+    const timerControl = new AbortController();
+    const deadline = sleep(deadlineMs, timerControl.signal).then(() => ({ settled: false }));
+    const first = await Promise.race([attempt, deadline]);
+    if (first.settled) {
+        timerControl.abort();
+        return first.outcome;
+    }
+    controller.abort();
+    return UNKNOWN;
+}
+/**
+ * Deliver `intent` and settle it against the authority's recorded outcome.
+ *
+ * Flow: when the intent has never been submitted, submit it; when it has (`attempts > 0`), or
+ * when a submission's outcome is unknown, look the request identity up. A positive lookup
+ * settles the intent. A `null` lookup is taken as proof that the authority never recorded the
+ * request, so a resubmission with the same `requestId` is the first delivery and is allowed, up
+ * to `maxSubmissions`. A lookup that fails leaves the outcome unknown and the intent for a later
+ * call.
+ *
+ * No resubmission happens without a `null` lookup because a blind retry after an unknown
+ * outcome is unsound: on an authority without request identity the retry applies the write
+ * twice, and even on one with it the retry can only ever learn what the lookup already knew.
+ * The lookup is what turns "unknown" into a fact before any second delivery.
+ *
+ * That fact is only as good as the transport's `null`. An authority that has expired or lost a
+ * record answers as if it never recorded it, and the reference wire transport returns `null`
+ * then. The resubmission is guarded only by its `base`, and versions are content hashes: if the
+ * write had landed and a third party has since restored `base` exactly, the premise matches, the
+ * write is applied a second time over that revert, and the outcome is `committed`. The hosted
+ * transport never answers `null` for an absent record once the intent is older than the host's
+ * stated retention window, less a skew margin, so it does not resubmit there.
+ *
+ * By default every outcome passes through {@link settleAgainstIntent}, so a conflict naming the
+ * intent's own version is committed. `recorded-only` preserves the recorded outcome instead.
+ */
+export async function performUncertainWrite(transport, intent, options = {}) {
+    if (options.settlement !== undefined && options.settlement !== "exact-content" && options.settlement !== "recorded-only") {
+        throw new Error("Unknown uncertain-write settlement mode.");
+    }
+    const sleep = options.sleep ?? defaultSleep;
+    const maxLookups = Math.max(1, options.maxLookups ?? 3);
+    const maxSubmissions = Math.max(1, options.maxSubmissions ?? 2);
+    const lookupDelayMs = options.lookupDelayMs ?? 250;
+    let attempts = intent.attempts;
+    let submissions = 0;
+    let lookups = 0;
+    const finish = (raw) => {
+        const outcome = options.settlement === "recorded-only" ? raw : settleAgainstIntent(raw, intent);
+        return { intent: { ...intent, attempts, state: stateForOutcome(outcome) }, outcome, lookups };
+    };
+    // A previously submitted intent starts at the lookup, never at a submission.
+    let needSubmission = attempts === 0;
+    for (;;) {
+        if (needSubmission) {
+            if (submissions >= maxSubmissions)
+                return finish(UNKNOWN);
+            submissions += 1;
+            attempts += 1;
+            const outcome = await submitOnce(transport, { ...intent, attempts, state: "in_flight" }, options.deadlineMs, sleep);
+            if (outcome.kind !== "unknown")
+                return finish(outcome);
+        }
+        needSubmission = false;
+        let recorded;
+        for (let round = 0; round < maxLookups; round++) {
+            if (round > 0)
+                await sleep(lookupDelayMs);
+            lookups += 1;
+            try {
+                recorded = await transport.lookup(intent.requestId);
+            }
+            catch {
+                recorded = undefined;
+                continue;
+            }
+            break;
+        }
+        if (recorded === undefined)
+            return finish(UNKNOWN);
+        if (recorded !== null)
+            return finish(recorded);
+        needSubmission = true;
+    }
+}
+//# sourceMappingURL=uncertain-write.js.map

package/dist/uncertain-write.js.map

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

package/dist/version-transport.d.ts

@@ -1,5 +1,12 @@
 /** Runtime-neutral version transport primitives shared by storage adapters and HTTP clients. */
 import type { Version } from "./types.js";
+/**
+ * True only for a content-addressed {@link Version} token as every conforming backend mints it:
+ * `sha256:` followed by 64 lowercase hex characters. One rule, shared by the reference router
+ * (an identified delete's premise) and the View registry (an entry pin), so no adapter carries
+ * its own reading of what a version looks like.
+ */
+export declare function isContentVersion(value: unknown): value is Version;
 /** Recover a bare version token from a quoted or weak HTTP ETag. */
 export declare function stripETagWrapper(raw: string): string;
 /** Typed optimistic-concurrency rejection raised by every conforming backend. */

package/dist/version-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version-transport.d.ts","sourceRoot":"","sources":["../src/version-transport.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAEhG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpD;AAED,iFAAiF;AACjF,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAqB;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;gBAEpB,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;CASzE"}
+{"version":3,"file":"version-transport.d.ts","sourceRoot":"","sources":["../src/version-transport.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAEhG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAEjE;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpD;AAED,iFAAiF;AACjF,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAqB;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;gBAEpB,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;CASzE"}

package/dist/version-transport.js

@@ -1,4 +1,13 @@
 /** Runtime-neutral version transport primitives shared by storage adapters and HTTP clients. */
+/**
+ * True only for a content-addressed {@link Version} token as every conforming backend mints it:
+ * `sha256:` followed by 64 lowercase hex characters. One rule, shared by the reference router
+ * (an identified delete's premise) and the View registry (an entry pin), so no adapter carries
+ * its own reading of what a version looks like.
+ */
+export function isContentVersion(value) {
+    return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
+}
 /** Recover a bare version token from a quoted or weak HTTP ETag. */
 export function stripETagWrapper(raw) {
     let value = raw.trim();

package/dist/version-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"version-transport.js","sourceRoot":"","sources":["../src/version-transport.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAIhG,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACvB,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iFAAiF;AACjF,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACtB,IAAI,GAAG,iBAAiB,CAAC;IAClC,EAAE,CAAS;IACX,QAAQ,CAAiB;IACzB,MAAM,CAAiB;IAEhC,YAAY,EAAU,EAAE,QAAwB,EAAE,MAAsB;QACtE,KAAK,CACH,wBAAwB,EAAE,eAAe,QAAQ,IAAI,QAAQ,WAAW,MAAM,IAAI,MAAM,GAAG;YACzF,8DAA8D,CACjE,CAAC;QACF,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"version-transport.js","sourceRoot":"","sources":["../src/version-transport.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAIhG;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1E,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACvB,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iFAAiF;AACjF,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACtB,IAAI,GAAG,iBAAiB,CAAC;IAClC,EAAE,CAAS;IACX,QAAQ,CAAiB;IACzB,MAAM,CAAiB;IAEhC,YAAY,EAAU,EAAE,QAAwB,EAAE,MAAsB;QACtE,KAAK,CACH,wBAAwB,EAAE,eAAe,QAAQ,IAAI,QAAQ,WAAW,MAAM,IAAI,MAAM,GAAG;YACzF,8DAA8D,CACjE,CAAC;QACF,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/versioning.d.ts

@@ -4,10 +4,15 @@
  * These make the seam's "hardest case" (content-addressed versions, compare-and-swap
  * writes, actor attribution) implementable uniformly across adapters:
  *   - {@link contentVersion} defines the opaque {@link Version} token as a SHA-256 over
- *     the canonically serialized document, so identical content yields the same token
- *     REGARDLESS of backend. The filesystem adapter hashes the on-disk bytes; the
- *     in-memory adapter hashes the same serialization — an engine-written document
- *     therefore carries the same version token in either store.
+ *     the canonically serialized document. A version token is a property of a backend,
+ *     not of the content: the filesystem adapter hashes the on-disk bytes exactly as
+ *     written, so a hand-authored file keeps its bytes and its token; the in-memory and
+ *     wire adapters hash a re-serialization, which folds long strings, expands flow
+ *     sequences and normalizes timestamps, so content Superbee did not author may carry a
+ *     different token there. An engine-written document carries the same token in either
+ *     store, because the engine wrote the canonical bytes. Bytes are the promise that
+ *     travels between backends (decision of 2026-09-17, "bytes win"); no promise rests on
+ *     cross-backend token equality.
  *   - {@link blobVersion} is the SAME idea for opaque blob bytes, but hashes the raw
  *     `Uint8Array` directly with no string/UTF-8 step — a doc-shaped hash would corrupt
  *     binary content, so blobs get their own primitive rather than reusing `contentVersion`
@@ -17,10 +22,12 @@
  *     the caller's `expectedVersion` no longer matches the backend's current version.
  *
  * Nothing here touches the filesystem — hashing and attribution are backend-neutral,
- * which is precisely why the memory adapter can reuse them.
+ * which is precisely why the memory adapter can reuse them. The digest itself lives in
+ * `sha256.ts`, a pure implementation with no `node:*` import, so this module and the memory
+ * adapter bundle for the browser and mint the same tokens there.
  */
 import type { OkfDocument, Version } from "./types.js";
-export { VersionConflict, stripETagWrapper } from "./version-transport.js";
+export { VersionConflict, isContentVersion, stripETagWrapper } from "./version-transport.js";
 /** Lowercase hex SHA-256 of a UTF-8 string. The version tokens' underlying digest. */
 export declare function sha256Hex(input: string): string;
 /**
@@ -43,6 +50,10 @@ export declare function versionOfBytes(raw: string): Version;
  * of adapter, exactly as {@link contentVersion} is for documents.
  */
 export declare function blobVersion(bytes: Uint8Array): Version;
-/** A local identity for unattributed writes: `$USER`/`$USERNAME`/`$LOGNAME`, else `"local"`. */
+/**
+ * A local identity for unattributed writes: `$USER`/`$USERNAME`/`$LOGNAME`, else `"local"`.
+ * A browser host has no `process` global, so the environment lookup is guarded and such a
+ * host attributes to `"local"`.
+ */
 export declare function defaultActor(): string;
 //# sourceMappingURL=versioning.d.ts.map

package/dist/versioning.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE3E,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAExD;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAEtD;AAED,gGAAgG;AAChG,wBAAgB,YAAY,IAAI,MAAM,CAOrC"}
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE7F,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAExD;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAGrC"}

package/dist/versioning.js

@@ -4,10 +4,15 @@
  * These make the seam's "hardest case" (content-addressed versions, compare-and-swap
  * writes, actor attribution) implementable uniformly across adapters:
  *   - {@link contentVersion} defines the opaque {@link Version} token as a SHA-256 over
- *     the canonically serialized document, so identical content yields the same token
- *     REGARDLESS of backend. The filesystem adapter hashes the on-disk bytes; the
- *     in-memory adapter hashes the same serialization — an engine-written document
- *     therefore carries the same version token in either store.
+ *     the canonically serialized document. A version token is a property of a backend,
+ *     not of the content: the filesystem adapter hashes the on-disk bytes exactly as
+ *     written, so a hand-authored file keeps its bytes and its token; the in-memory and
+ *     wire adapters hash a re-serialization, which folds long strings, expands flow
+ *     sequences and normalizes timestamps, so content Superbee did not author may carry a
+ *     different token there. An engine-written document carries the same token in either
+ *     store, because the engine wrote the canonical bytes. Bytes are the promise that
+ *     travels between backends (decision of 2026-09-17, "bytes win"); no promise rests on
+ *     cross-backend token equality.
  *   - {@link blobVersion} is the SAME idea for opaque blob bytes, but hashes the raw
  *     `Uint8Array` directly with no string/UTF-8 step — a doc-shaped hash would corrupt
  *     binary content, so blobs get their own primitive rather than reusing `contentVersion`
@@ -17,14 +22,16 @@
  *     the caller's `expectedVersion` no longer matches the backend's current version.
  *
  * Nothing here touches the filesystem — hashing and attribution are backend-neutral,
- * which is precisely why the memory adapter can reuse them.
+ * which is precisely why the memory adapter can reuse them. The digest itself lives in
+ * `sha256.ts`, a pure implementation with no `node:*` import, so this module and the memory
+ * adapter bundle for the browser and mint the same tokens there.
  */
-import { createHash } from "node:crypto";
 import { stringifyDoc } from "./frontmatter.js";
-export { VersionConflict, stripETagWrapper } from "./version-transport.js";
+import { sha256HexOfBytes, sha256HexOfUtf8 } from "./sha256.js";
+export { VersionConflict, isContentVersion, stripETagWrapper } from "./version-transport.js";
 /** Lowercase hex SHA-256 of a UTF-8 string. The version tokens' underlying digest. */
 export function sha256Hex(input) {
-    return createHash("sha256").update(input, "utf8").digest("hex");
+    return sha256HexOfUtf8(input);
 }
 /**
  * The content-addressed {@link Version} of a concept document: the SHA-256 of its
@@ -50,13 +57,15 @@ export function versionOfBytes(raw) {
  * of adapter, exactly as {@link contentVersion} is for documents.
  */
 export function blobVersion(bytes) {
-    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    return `sha256:${sha256HexOfBytes(bytes)}`;
 }
-/** A local identity for unattributed writes: `$USER`/`$USERNAME`/`$LOGNAME`, else `"local"`. */
+/**
+ * A local identity for unattributed writes: `$USER`/`$USERNAME`/`$LOGNAME`, else `"local"`.
+ * A browser host has no `process` global, so the environment lookup is guarded and such a
+ * host attributes to `"local"`.
+ */
 export function defaultActor() {
-    return (process.env.USER?.trim() ||
-        process.env.USERNAME?.trim() ||
-        process.env.LOGNAME?.trim() ||
-        "local");
+    const env = typeof process !== "undefined" ? process.env : undefined;
+    return env?.USER?.trim() || env?.USERNAME?.trim() || env?.LOGNAME?.trim() || "local";
 }
 //# sourceMappingURL=versioning.js.map

package/dist/versioning.js.map

@@ -1 +1 @@
-{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE3E,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAgB;IAC7C,OAAO,UAAU,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,UAAU,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,YAAY;IAC1B,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE;QACxB,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE;QAC5B,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE;QAC3B,OAAO,CACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE7F,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAgB;IAC7C,OAAO,UAAU,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,UAAU,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,UAAU,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,OAAO,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC;AACvF,CAAC"}