@braidlabs/data 0.1.1

package/src/lib/indexeddb-driver.js

@@ -0,0 +1,160 @@
+const PARTITION_INDEX = 'by-partition-seq';
+/**
+ * IndexedDB, as the source of truth.
+ *
+ * Why this rather than a KV shim over the same database: every operation below is **one
+ * transaction over one record**. There is no read-modify-write anywhere, so two realms or two tabs
+ * writing concurrently cannot lose each other's work — which a `get`-then-`set` shim absolutely can,
+ * whatever storage sits underneath it.
+ *
+ * The `[partition, seq]` compound index is what makes `list` a range scan rather than a full read
+ * plus filter, and it is why partitions stay cheap as the store grows.
+ */
+export function indexedDbRecordDriver(options) {
+    const databaseName = options.database ?? 'skew-data';
+    const factory = options.indexedDB ?? globalThis.indexedDB;
+    const collections = [...options.collections];
+    const ranges = options.keyRange ?? globalThis.IDBKeyRange;
+    let open = null;
+    function database() {
+        open ??= connect();
+        return open;
+    }
+    /**
+     * Opens the database, upgrading only if a declared collection is actually missing.
+     *
+     * **The version is discovered, never derived.** An earlier draft opened at
+     * `collections.length + 1`, which works perfectly for one application and breaks the moment two
+     * share an origin — which is exactly what this library is for. Two independently deployed apps
+     * rarely declare the same number of collections, so each would demand its own version: the one
+     * with the shorter list ends up requesting a version *lower* than the database already has, and
+     * IndexedDB answers that with a `VersionError` forever. Not a race, not intermittent — that app
+     * simply never opens its storage again.
+     *
+     * Discovering it instead means the two converge. Each opens at whatever version exists, adds only
+     * the stores it is missing, and the version climbs monotonically as fragments arrive.
+     */
+    async function connect() {
+        if (!factory)
+            throw new Error('skew-data: no IndexedDB in this environment');
+        let db = await openDatabase();
+        const missing = collections.filter((collection) => !db.objectStoreNames.contains(collection));
+        if (missing.length > 0) {
+            // A connection has to be closed before it can be upgraded, including our own.
+            db.close();
+            db = await openDatabase(db.version + 1);
+        }
+        /**
+         * Stand aside when another context needs to upgrade.
+         *
+         * This is the other half of sharing a database, and the half that hangs rather than throws when
+         * it is missing: a sibling fragment declaring a collection we do not have must upgrade, and an
+         * upgrade cannot start while anyone holds the database open. Closing here lets it proceed; the
+         * next operation reopens at the new version, by which point its store exists.
+         */
+        db.onversionchange = () => {
+            db.close();
+            open = null;
+        };
+        return db;
+    }
+    function openDatabase(version) {
+        return new Promise((resolve, reject) => {
+            const request = version === undefined ? factory.open(databaseName) : factory.open(databaseName, version);
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                for (const collection of collections) {
+                    if (db.objectStoreNames.contains(collection))
+                        continue;
+                    const store = db.createObjectStore(collection, { keyPath: 'id' });
+                    store.createIndex(PARTITION_INDEX, ['partition', 'seq']);
+                }
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error ?? new Error('skew-data: could not open the database'));
+            // Someone is holding the database open at an older version and did not stand aside. Every
+            // connection this driver makes closes itself on `versionchange`, so the holder is something
+            // else — an old build, another library, or a devtools inspection. Reported rather than left
+            // to hang, because a promise that never settles is the least debuggable failure there is.
+            request.onblocked = () => reject(new Error(`skew-data: another connection is holding "${databaseName}" open at an older version, ` +
+                `so it cannot be upgraded to add ${collections.join(', ')}. Close other tabs of this ` +
+                `application, or reload them.`));
+        });
+    }
+    /**
+     * Object stores can only be created during a version upgrade, so a collection that was not
+     * declared cannot be created on demand — and IndexedDB reports that as a bare `NotFoundError`
+     * naming neither the collection nor the fix. Checking first turns an opaque failure into an
+     * actionable one, which is worth the branch.
+     */
+    function assertDeclared(db, collection) {
+        if (db.objectStoreNames.contains(collection))
+            return;
+        throw new Error(`skew-data: collection "${collection}" is not in this database. IndexedDB can only create ` +
+            `object stores during a version upgrade, so every collection must be declared up front — ` +
+            `add it to \`collections\` where the driver is created (currently: ${collections.join(', ') || 'none'}).`);
+    }
+    async function transaction(collection, mode, run) {
+        const db = await database();
+        assertDeclared(db, collection);
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(collection, mode);
+            const request = run(tx.objectStore(collection));
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error ?? new Error(`skew-data: ${collection} operation failed`));
+        });
+    }
+    return {
+        async put(collection, record) {
+            await transaction(collection, 'readwrite', (store) => store.put(record));
+        },
+        async get(collection, id) {
+            return (await transaction(collection, 'readonly', (store) => store.get(id))) ?? null;
+        },
+        async delete(collection, id) {
+            await transaction(collection, 'readwrite', (store) => store.delete(id));
+        },
+        async list(collection, partition) {
+            // Range scan over [partition, seq] — already ordered, so no sort and no full read.
+            const range = ranges.bound([partition, -Infinity], [partition, Infinity]);
+            return transaction(collection, 'readonly', (store) => store.index(PARTITION_INDEX).getAll(range));
+        },
+        async clearPartition(collection, partition) {
+            const db = await database();
+            assertDeclared(db, collection);
+            return new Promise((resolve, reject) => {
+                const tx = db.transaction(collection, 'readwrite');
+                const store = tx.objectStore(collection);
+                const range = ranges.bound([partition, -Infinity], [partition, Infinity]);
+                const cursor = store.index(PARTITION_INDEX).openCursor(range);
+                cursor.onsuccess = () => {
+                    const position = cursor.result;
+                    if (!position)
+                        return;
+                    position.delete();
+                    position.continue();
+                };
+                // Resolved on the transaction, not the cursor: deleting through a cursor is only durable
+                // once the transaction commits, and a sign-out purge that reported success before that
+                // could leave a partition half-deleted.
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => reject(tx.error ?? new Error('skew-data: purge failed'));
+                tx.onabort = () => reject(tx.error ?? new Error('skew-data: purge aborted'));
+            });
+        },
+        async highestSeq(collection) {
+            const db = await database();
+            assertDeclared(db, collection);
+            return new Promise((resolve, reject) => {
+                const tx = db.transaction(collection, 'readonly');
+                const cursor = tx.objectStore(collection).index(PARTITION_INDEX).openCursor(null, 'prev');
+                cursor.onsuccess = () => {
+                    const record = cursor.result?.value;
+                    resolve(record?.seq ?? 0);
+                };
+                cursor.onerror = () => reject(cursor.error ?? new Error('skew-data: could not read the sequence'));
+            });
+        },
+    };
+}
+//# sourceMappingURL=indexeddb-driver.js.map

package/src/lib/indexeddb-driver.js.map

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

package/src/lib/intents.d.ts

@@ -0,0 +1,83 @@
+import type { VersionedSchema } from '@braidlabs/skew';
+/**
+ * Intents: "somebody handle this", and deciding who.
+ *
+ * The FDC3 shape, with the resolution question answered honestly. FDC3's answer is a resolver UI,
+ * which is *one* policy — and the wrong one for most internal software, where two candidates usually
+ * means one is a newer deployment of the other and nobody wants to be asked.
+ *
+ * The part that is ours rather than FDC3's: **a handler that cannot read the payload is not a
+ * candidate.** Version eligibility is decided before resolution, not discovered during it, so a user
+ * is never offered a handler that will fail — and an automatic policy never picks one.
+ */
+export interface IntentHandlerOptions<T = unknown> {
+    /** The contract version this handler accepts. It is excluded if the payload cannot reach it. */
+    as?: number;
+    /** Ranks candidates for the `'first'` policy and for a resolver. Higher wins; defaults to 0. */
+    priority?: number;
+    signal?: AbortSignal;
+    /** For diagnostics and for a chooser UI. Defaults to the bus's consumer name. */
+    label?: string;
+    handler: (payload: T) => unknown | Promise<unknown>;
+}
+export interface IntentCandidate {
+    intent: string;
+    /** Which application registered it. */
+    consumer: string;
+    label: string;
+    priority: number;
+    /** The contract version it reads the payload at. */
+    as?: number;
+}
+/**
+ * How to choose between handlers.
+ *
+ * `'first'` is the default because it is deterministic and it is what an internal deployment wants;
+ * `'ask'` is FDC3's behaviour and needs the host to render something, so it arrives as a callback the
+ * shell supplies rather than as UI this package owns.
+ */
+export type ResolvePolicy = 'first' | 'all' | 'ask' | ((candidates: readonly IntentCandidate[], payload: unknown) => IntentCandidate | Promise<IntentCandidate>);
+export interface RaiseOptions {
+    resolve?: ResolvePolicy;
+    /** Required when `resolve` is `'ask'`: the shell's chooser. */
+    chooser?: (candidates: readonly IntentCandidate[], payload: unknown) => Promise<IntentCandidate>;
+}
+export interface IntentResult<R = unknown> {
+    /** Every handler that ran, in the order it ran. */
+    handled: {
+        candidate: IntentCandidate;
+        result: R;
+    }[];
+    /** Candidates excluded because they could not read the payload at their declared version. */
+    ineligible: {
+        candidate: IntentCandidate;
+        reason: string;
+    }[];
+}
+export declare class NoIntentHandlerError extends Error {
+    readonly intent: string;
+    readonly ineligible: readonly {
+        candidate: IntentCandidate;
+        reason: string;
+    }[];
+    constructor(intent: string, ineligible: readonly {
+        candidate: IntentCandidate;
+        reason: string;
+    }[]);
+}
+export interface IntentRegistry {
+    addIntentListener<T>(intent: string, options: IntentHandlerOptions<T>): () => void;
+    raiseIntent<R = unknown>(intent: string, payload: unknown, options?: RaiseOptions): Promise<IntentResult<R>>;
+    /** Who could handle this intent right now, for a launcher or a chooser. */
+    candidates(intent: string, payload?: unknown): {
+        eligible: IntentCandidate[];
+        ineligible: IntentCandidate[];
+    };
+}
+export interface IntentRegistryOptions {
+    consumer: string;
+    /** Resolves the contract for an intent's payload, so eligibility can be decided. */
+    schemaFor: (intent: string) => VersionedSchema<unknown> | undefined;
+    onEventError?: (message: string, detail?: unknown) => void;
+}
+export declare function createIntentRegistry(options: IntentRegistryOptions): IntentRegistry;

package/src/lib/intents.js

@@ -0,0 +1,136 @@
+export class NoIntentHandlerError extends Error {
+    intent;
+    ineligible;
+    constructor(intent, ineligible) {
+        const excluded = ineligible.length
+            ? ` ${ineligible.length} handler(s) were excluded: ${ineligible.map((entry) => `${entry.candidate.consumer} (${entry.reason})`).join(', ')}`
+            : '';
+        super(`[skew/data] nothing can handle the intent "${intent}".${excluded}`);
+        this.intent = intent;
+        this.ineligible = ineligible;
+        this.name = 'NoIntentHandlerError';
+    }
+}
+export function createIntentRegistry(options) {
+    const registrations = new Map();
+    /**
+     * Whether a handler can be handed this payload.
+     *
+     * Decided from the declared chain rather than by attempting the projection, so the answer does not
+     * depend on a payload being present — `candidates()` has to work for a launcher with nothing in
+     * hand.
+     */
+    function eligibility(registration) {
+        const schema = options.schemaFor(registration.intent);
+        if (!schema || registration.as === undefined || registration.as === schema.version)
+            return { ok: true };
+        if (registration.as > schema.version) {
+            return { ok: false, reason: `reads v${registration.as}, the payload is v${schema.version}` };
+        }
+        const missing = schema.steps
+            .filter((step) => step.to > registration.as && step.to <= schema.version && !step.down)
+            .map((step) => `v${step.to}`);
+        return missing.length === 0
+            ? { ok: true }
+            : { ok: false, reason: `v${registration.as} is unreachable — ${missing.join(', ')} declare no down migration` };
+    }
+    function project(intent, payload, as) {
+        const schema = options.schemaFor(intent);
+        if (!schema || as === undefined || as === schema.version)
+            return payload;
+        return schema.write(payload, { as }).payload;
+    }
+    return {
+        addIntentListener(intent, handlerOptions) {
+            let forIntent = registrations.get(intent);
+            if (!forIntent) {
+                forIntent = new Set();
+                registrations.set(intent, forIntent);
+            }
+            const registration = {
+                intent,
+                consumer: options.consumer,
+                label: handlerOptions.label ?? options.consumer,
+                priority: handlerOptions.priority ?? 0,
+                ...(handlerOptions.as === undefined ? {} : { as: handlerOptions.as }),
+                run: handlerOptions.handler,
+            };
+            forIntent.add(registration);
+            const unsubscribe = () => void forIntent.delete(registration);
+            handlerOptions.signal?.addEventListener('abort', unsubscribe, { once: true });
+            return unsubscribe;
+        },
+        candidates(intent) {
+            const eligible = [];
+            const ineligible = [];
+            for (const registration of registrations.get(intent) ?? []) {
+                (eligibility(registration).ok ? eligible : ineligible).push(strip(registration));
+            }
+            // Ranked here so every policy — and every chooser the host renders — sees one order.
+            eligible.sort((a, b) => b.priority - a.priority);
+            return { eligible, ineligible };
+        },
+        async raiseIntent(intent, payload, raiseOptions) {
+            const policy = raiseOptions?.resolve ?? 'first';
+            const all = [...(registrations.get(intent) ?? [])];
+            const eligible = [];
+            const ineligible = [];
+            for (const registration of all) {
+                const verdict = eligibility(registration);
+                if (verdict.ok)
+                    eligible.push(registration);
+                else
+                    ineligible.push({ candidate: strip(registration), reason: verdict.reason });
+            }
+            eligible.sort((a, b) => b.priority - a.priority);
+            if (eligible.length === 0)
+                throw new NoIntentHandlerError(intent, ineligible);
+            const run = async (registration) => ({
+                candidate: strip(registration),
+                result: (await registration.run(project(intent, payload, registration.as))),
+            });
+            if (policy === 'all') {
+                // Sequential, so handlers that touch the same records do so in a defined order — the same
+                // reason the outbox drains one at a time.
+                const handled = [];
+                for (const registration of eligible)
+                    handled.push(await run(registration));
+                return { handled, ineligible };
+            }
+            let chosen;
+            if (policy === 'first') {
+                chosen = eligible[0];
+            }
+            else if (policy === 'ask') {
+                if (!raiseOptions?.chooser) {
+                    throw new TypeError("[skew/data] resolve: 'ask' needs a `chooser` — which handler a user picks is a question " +
+                        'for the shell that can render it, not for this package.');
+                }
+                const picked = await raiseOptions.chooser(eligible.map(strip), payload);
+                chosen = eligible.find((candidate) => matches(candidate, picked));
+            }
+            else {
+                const picked = await policy(eligible.map(strip), payload);
+                chosen = eligible.find((candidate) => matches(candidate, picked));
+            }
+            if (!chosen) {
+                // A resolver that returns something not in the list is a bug in the resolver, and guessing
+                // would run a handler nobody selected.
+                throw new Error(`[skew/data] the resolver for "${intent}" returned a candidate that is not eligible`);
+            }
+            return { handled: [await run(chosen)], ineligible };
+        },
+    };
+}
+const strip = (registration) => ({
+    intent: registration.intent,
+    consumer: registration.consumer,
+    label: registration.label,
+    priority: registration.priority,
+    ...(registration.as === undefined ? {} : { as: registration.as }),
+});
+const matches = (registration, candidate) => registration.consumer === candidate.consumer &&
+    registration.label === candidate.label &&
+    registration.priority === candidate.priority &&
+    registration.as === candidate.as;
+//# sourceMappingURL=intents.js.map

package/src/lib/intents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intents.js","sourceRoot":"","sources":["../../../../../libs/data/src/lib/intents.ts"],"names":[],"mappings":"AA6DA,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAElC;IACA;IAFX,YACW,MAAc,EACd,UAAqE;QAE9E,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM;YAChC,CAAC,CAAC,IAAI,UAAU,CAAC,MAAM,8BAA8B,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,QAAQ,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAC5I,CAAC,CAAC,EAAE,CAAC;QACP,KAAK,CAAC,8CAA8C,MAAM,KAAK,QAAQ,EAAE,CAAC,CAAC;QANlE,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAA2D;QAM9E,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAoBD,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,MAAM,aAAa,GAAG,IAAI,GAAG,EAA6B,CAAC;IAE3D;;;;;;OAMG;IACH,SAAS,WAAW,CAAC,YAA0B;QAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,EAAE,KAAK,SAAS,IAAI,YAAY,CAAC,EAAE,KAAK,MAAM,CAAC,OAAO;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QAExG,IAAI,YAAY,CAAC,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACrC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,YAAY,CAAC,EAAE,qBAAqB,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/F,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK;aACzB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,YAAY,CAAC,EAAG,IAAI,IAAI,CAAC,EAAE,IAAI,MAAM,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;aACvF,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAEhC,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC;YACzB,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE;YACd,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,YAAY,CAAC,EAAE,qBAAqB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B,EAAE,CAAC;IACpH,CAAC;IAED,SAAS,OAAO,CAAC,MAAc,EAAE,OAAgB,EAAE,EAAsB;QACvE,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,MAAM,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC;QACzE,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,iBAAiB,CAAI,MAAc,EAAE,cAAuC;YAC1E,IAAI,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;gBACtB,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACvC,CAAC;YAED,MAAM,YAAY,GAAiB;gBACjC,MAAM;gBACN,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,KAAK,EAAE,cAAc,CAAC,KAAK,IAAI,OAAO,CAAC,QAAQ;gBAC/C,QAAQ,EAAE,cAAc,CAAC,QAAQ,IAAI,CAAC;gBACtC,GAAG,CAAC,cAAc,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC;gBACrE,GAAG,EAAE,cAAc,CAAC,OAAwC;aAC7D,CAAC;YACF,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAE5B,MAAM,WAAW,GAAG,GAAG,EAAE,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC9D,cAAc,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9E,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,UAAU,CAAC,MAAc;YACvB,MAAM,QAAQ,GAAsB,EAAE,CAAC;YACvC,MAAM,UAAU,GAAsB,EAAE,CAAC;YAEzC,KAAK,MAAM,YAAY,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC3D,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;YACnF,CAAC;YAED,qFAAqF;YACrF,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;YACjD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;QAClC,CAAC;QAED,KAAK,CAAC,WAAW,CAAI,MAAc,EAAE,OAAgB,EAAE,YAA2B;YAChF,MAAM,MAAM,GAAG,YAAY,EAAE,OAAO,IAAI,OAAO,CAAC;YAChD,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAEnD,MAAM,QAAQ,GAAmB,EAAE,CAAC;YACpC,MAAM,UAAU,GAAqD,EAAE,CAAC;YAExE,KAAK,MAAM,YAAY,IAAI,GAAG,EAAE,CAAC;gBAC/B,MAAM,OAAO,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;gBAC1C,IAAI,OAAO,CAAC,EAAE;oBAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;;oBACvC,UAAU,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YACnF,CAAC;YAED,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;YAEjD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAE9E,MAAM,GAAG,GAAG,KAAK,EAAE,YAA0B,EAAE,EAAE,CAAC,CAAC;gBACjD,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;gBAC9B,MAAM,EAAE,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CAAM;aACjF,CAAC,CAAC;YAEH,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBACrB,0FAA0F;gBAC1F,0CAA0C;gBAC1C,MAAM,OAAO,GAAgD,EAAE,CAAC;gBAChE,KAAK,MAAM,YAAY,IAAI,QAAQ;oBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;gBAC3E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;YACjC,CAAC;YAED,IAAI,MAAgC,CAAC;YAErC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBACvB,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACvB,CAAC;iBAAM,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBAC5B,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,CAAC;oBAC3B,MAAM,IAAI,SAAS,CACjB,0FAA0F;wBACxF,yDAAyD,CAC5D,CAAC;gBACJ,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;gBACxE,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;YACpE,CAAC;iBAAM,CAAC;gBACN,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;gBAC1D,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;YACpE,CAAC;YAED,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,2FAA2F;gBAC3F,uCAAuC;gBACvC,MAAM,IAAI,KAAK,CAAC,iCAAiC,MAAM,6CAA6C,CAAC,CAAC;YACxG,CAAC;YAED,OAAO,EAAE,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;QACtD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,YAA0B,EAAmB,EAAE,CAAC,CAAC;IAC9D,MAAM,EAAE,YAAY,CAAC,MAAM;IAC3B,QAAQ,EAAE,YAAY,CAAC,QAAQ;IAC/B,KAAK,EAAE,YAAY,CAAC,KAAK;IACzB,QAAQ,EAAE,YAAY,CAAC,QAAQ;IAC/B,GAAG,CAAC,YAAY,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,EAAE,EAAE,CAAC;CAClE,CAAC,CAAC;AAEH,MAAM,OAAO,GAAG,CAAC,YAA0B,EAAE,SAA0B,EAAW,EAAE,CAClF,YAAY,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ;IAC5C,YAAY,CAAC,KAAK,KAAK,SAAS,CAAC,KAAK;IACtC,YAAY,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ;IAC5C,YAAY,CAAC,EAAE,KAAK,SAAS,CAAC,EAAE,CAAC"}

package/src/lib/invalidation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Tag invalidation, across every app on the page and — when asked — every tab.
+ *
+ * Tags rather than TTLs, because a time-to-live is a guess about when data went stale whereas a
+ * mutation *knows*. `character#1` and `characters` are claims about what a query depends on;
+ * invalidating a tag re-runs exactly the queries that said they cared.
+ *
+ * The reach is the part that is new. A per-application registry gives each app its own private
+ * answer, so a mutation in one leaves the other four stale — and staleness is invisible, which is
+ * the worst property a bug can have.
+ */
+export interface InvalidationOptions {
+    /**
+     * Partition the signals belong to. Tags never cross one, so invalidating `characters` cannot
+     * reach another tenant's queries.
+     */
+    partition: string;
+    /**
+     * Whether invalidation reaches other **JavaScript contexts** — other tabs, and other realms on
+     * this page.
+     *
+     * Named for contexts rather than tabs because the two cases are the same mechanism and people
+     * only think of the first one. A Braid realm is a separate context: two fragments composed onto
+     * one page are as isolated from each other, in memory, as two tabs are. Leave this off on a
+     * composed page and one fragment's invalidation silently never reaches another.
+     *
+     * Off by default, and that is a real choice rather than caution: refreshing a list in another tab
+     * is sometimes exactly right and sometimes a refetch storm across five of them.
+     */
+    crossContext?: boolean;
+    /** Injectable for tests. */
+    channel?: BroadcastChannelLike;
+}
+/** The slice of `BroadcastChannel` this uses, so a test can supply a pair without a DOM. */
+export interface BroadcastChannelLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    close(): void;
+}
+export interface Invalidator {
+    /** Marks tags stale. Every subscriber that owns a matching tag is notified. */
+    invalidate(...tags: string[]): void;
+    /**
+     * Registers interest. `getTags` is re-read on every invalidation, so a query whose tags depend on
+     * a changing input stays correct without re-subscribing.
+     */
+    subscribe(getTags: () => readonly string[], notify: () => void, options?: {
+        signal?: AbortSignal;
+    }): () => void;
+    close(): void;
+}
+/**
+ * The invalidator for a partition, shared with anyone else who asks for the same one.
+ *
+ * Reference-counted: the underlying channel closes when the last holder closes, so a short-lived
+ * client cannot take the page's invalidation down with it.
+ */
+export declare function sharedInvalidator(options: InvalidationOptions): Invalidator;
+/** Exposed for tests. */
+export declare function resetSharedInvalidators(): void;
+export declare function createInvalidator(options: InvalidationOptions): Invalidator;

package/src/lib/invalidation.js

@@ -0,0 +1,136 @@
+/**
+ * Tag invalidation, across every app on the page and — when asked — every tab.
+ *
+ * Tags rather than TTLs, because a time-to-live is a guess about when data went stale whereas a
+ * mutation *knows*. `character#1` and `characters` are claims about what a query depends on;
+ * invalidating a tag re-runs exactly the queries that said they cared.
+ *
+ * The reach is the part that is new. A per-application registry gives each app its own private
+ * answer, so a mutation in one leaves the other four stale — and staleness is invisible, which is
+ * the worst property a bug can have.
+ */
+const CHANNEL_NAME = 'skew:data:invalidation';
+/**
+ * Invalidators, shared per partition within a JavaScript context.
+ *
+ * Two applications on one page each building a private invalidator is the same defect the outbox
+ * had: a page-wide fact with a per-app answer. A mutation in one would leave the other stale, and
+ * staleness is invisible — the worst property a bug can have.
+ *
+ * Cross-*realm* and cross-tab reach is `BroadcastChannel`'s job; this map covers the case the
+ * channel cannot, which is two clients in one context (a channel does not deliver to its own
+ * sender).
+ */
+const sharedInvalidators = new Map();
+/**
+ * The invalidator for a partition, shared with anyone else who asks for the same one.
+ *
+ * Reference-counted: the underlying channel closes when the last holder closes, so a short-lived
+ * client cannot take the page's invalidation down with it.
+ */
+export function sharedInvalidator(options) {
+    const existing = sharedInvalidators.get(options.partition);
+    if (existing) {
+        existing.refs += 1;
+        return wrapRelease(options.partition, existing.invalidator);
+    }
+    const entry = { invalidator: createInvalidator(options), refs: 1 };
+    sharedInvalidators.set(options.partition, entry);
+    return wrapRelease(options.partition, entry.invalidator);
+}
+function wrapRelease(partition, invalidator) {
+    let released = false;
+    return {
+        invalidate: (...tags) => invalidator.invalidate(...tags),
+        subscribe: (getTags, notify, options) => invalidator.subscribe(getTags, notify, options),
+        close() {
+            if (released)
+                return;
+            released = true;
+            const entry = sharedInvalidators.get(partition);
+            if (!entry)
+                return;
+            entry.refs -= 1;
+            if (entry.refs > 0)
+                return;
+            sharedInvalidators.delete(partition);
+            entry.invalidator.close();
+        },
+    };
+}
+/** Exposed for tests. */
+export function resetSharedInvalidators() {
+    for (const entry of sharedInvalidators.values())
+        entry.invalidator.close();
+    sharedInvalidators.clear();
+}
+export function createInvalidator(options) {
+    const subscribers = new Map();
+    const channel = options.channel ??
+        (options.crossContext && typeof BroadcastChannel !== 'undefined'
+            ? new BroadcastChannel(CHANNEL_NAME)
+            : undefined);
+    // A BroadcastChannel does not deliver to the context that posted, which is the semantics wanted
+    // here: local subscribers are notified directly, remote ones over the channel, and neither path
+    // double-fires.
+    channel?.addEventListener('message', (event) => {
+        const signal = event.data;
+        if (signal?.partition !== options.partition)
+            return;
+        notifyLocal(signal.tags);
+    });
+    function notifyLocal(tags) {
+        if (tags.length === 0)
+            return;
+        for (const subscriber of [...subscribers.values()]) {
+            let interested = false;
+            try {
+                interested = subscriber.getTags().some((owned) => tags.some((tag) => tagsMatch(owned, tag)));
+            }
+            catch {
+                // A tag getter that throws — a signal read outside its context, say — must not take down
+                // invalidation for everyone else.
+                interested = false;
+            }
+            if (!interested)
+                continue;
+            try {
+                subscriber.notify();
+            }
+            catch {
+                // A refresh that throws is that query's problem, not this loop's.
+            }
+        }
+    }
+    return {
+        invalidate(...tags) {
+            notifyLocal(tags);
+            channel?.postMessage({ partition: options.partition, tags });
+        },
+        subscribe(getTags, notify, subscribeOptions) {
+            const token = Symbol('skew-invalidation-subscriber');
+            subscribers.set(token, { getTags, notify });
+            const unsubscribe = () => void subscribers.delete(token);
+            subscribeOptions?.signal?.addEventListener('abort', unsubscribe, { once: true });
+            return unsubscribe;
+        },
+        close() {
+            subscribers.clear();
+            channel?.close();
+        },
+    };
+}
+/**
+ * Wildcards in one direction: invalidating `character#*` reaches every `character#…` subscriber, and
+ * a subscriber may register the wildcard itself to hear about any change to that type.
+ */
+function tagsMatch(owned, invalidated) {
+    if (owned === invalidated)
+        return true;
+    if (invalidated.endsWith('*'))
+        return owned.startsWith(invalidated.slice(0, -1));
+    if (owned.endsWith('*'))
+        return invalidated.startsWith(owned.slice(0, -1));
+    return false;
+}
+//# sourceMappingURL=invalidation.js.map

package/src/lib/invalidation.js.map

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

package/src/lib/locks.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Cross-context mutual exclusion, for work that must happen once across every tab and realm.
+ *
+ * The motivating case is flushing the outbox. Storage is shared per origin, so without this every
+ * open tab drains the same queue on reconnect — replaying the same mutations several times, against
+ * a server that is by definition just coming back. No storage layer helps: IndexedDB makes each
+ * *write* atomic, and says nothing about who should be doing the writing.
+ *
+ * `navigator.locks` is the only primitive that spans realms and tabs. Where it is missing — Node,
+ * a non-secure context, an older browser — this degrades to an in-process lock, which is honest
+ * about what it can offer: exclusion within one JavaScript context, which is what existed before
+ * this and is still better than nothing.
+ */
+export type LockResult<T> = {
+    acquired: true;
+    value: T;
+} | {
+    acquired: false;
+};
+export interface LockOptions {
+    /**
+     * When true (the default), a lock already held elsewhere is **not waited for** — the call returns
+     * `{ acquired: false }` immediately.
+     *
+     * Waiting is the wrong default for this. A flush that queued behind another tab's flush would run
+     * against a queue that tab had just drained, so the work is redundant by the time it starts;
+     * skipping says "someone is on it" and lets the caller move on.
+     */
+    ifAvailable?: boolean;
+    signal?: AbortSignal;
+}
+/** True when this context has real cross-tab locks rather than the in-process fallback. */
+export declare function hasCrossContextLocks(): boolean;
+export declare function withLock<T>(name: string, run: () => Promise<T>, options?: LockOptions): Promise<LockResult<T>>;
+/**
+ * The lock name for flushing one owner's queue.
+ *
+ * Per **owner**, not one global lock. Two different applications flush disjoint entries, so making
+ * them queue behind each other would serialize work that has no reason to be serialized. The
+ * conflict this prevents is the same application open in two tabs, both replaying the same
+ * mutations.
+ */
+export declare function outboxFlushLock(owner: string): string;