@doubling/types 0.3.0 → 0.4.0

package/README.md

@@ -18,6 +18,13 @@ The duplication was load-bearing for shipping (web and sync run in different env
 
 ## Layout
 
+- `src/crdt-store.ts`: `UpdateRecord`, `Snapshot`, `UpdateStore`, and
+  `updateStoreConformance`. The CRDT update-store contract plus the behavioural
+  cases both `web/` and `sync/` run against their own backends. It lives here
+  because it is the only dependency-free part of the CRDT stack — types over
+  `Uint8Array` and `string`, since a store treats updates as opaque bytes — and
+  because a package with shared runtime deps cannot be shared at all under this
+  repo's nested install strategy (DOU-379).
 - `src/firestore.ts`: `FileEntity`, `FolderEntity`, `Entity`, `OrgMembership`, `OrgMember`, `Team`, `TeamMember`, `UserProfile`, `Scope`.
 - `src/mime.ts`: `EXT_TO_MIME`, `mimeTypeFromExt`, `isTextMimeType`.
 - `src/paths.ts`: `extFromPath`, `storagePathFor`.

package/dist/crdt-store.d.ts

@@ -0,0 +1,86 @@
+/** One stored update: the opaque CRDT bytes plus its ordering id. */
+export interface UpdateRecord {
+    id: string;
+    update: Uint8Array;
+}
+/** A folded snapshot plus the highest update id it covers. */
+export interface Snapshot {
+    state: Uint8Array;
+    /** null means "no known baseline" — replay the whole log. */
+    baselineId: string | null;
+}
+/**
+ * The storage seam between a CRDT provider and any concrete backend.
+ *
+ * Identity contract:
+ *
+ *  - Every `UpdateRecord` has a unique, monotonically-ordered `id`.
+ *    Backends choose the encoding (server timestamp + doc id, a counter,
+ *    a ULID) but iterating in id order must replay in append order.
+ *  - `baselineId` is the highest id covered by the current snapshot.
+ *    `loadUpdatesAfter(baselineId)` returns strictly newer records.
+ *  - Ids exist only on records **read back** from the store.
+ *    `appendUpdate` returns void: the backend assigns the id (a server
+ *    timestamp, in Firestore's case), so resolving it at append time
+ *    costs a round trip for a value no caller uses (DOU-377).
+ *
+ * Deliberately absent: any method that folds or deletes. Compaction is
+ * destructive and only safe when the reader, the snapshot writer and the
+ * deleter are one actor in one consistent view, which a client cannot be
+ * while others append. It is the `compactYjsDoc` callable, and
+ * `firestore.rules` denies clients `delete` on `yupdates` and writes on
+ * `yjs/state` so this is enforced rather than conventional (DOU-409).
+ *
+ * This is a deliberate narrowing of what the two local interfaces
+ * declared before DOU-379. Both carried an optional
+ * `saveSnapshotAndCompact?(...)`, present so the in-memory stores could
+ * exercise fold semantics while the Firestore stores omitted it. Nothing
+ * ever called it *through the interface* — the tests that seed snapshots
+ * hold a concrete `MemoryUpdateStore` — so it was optional surface on a
+ * contract that no longer describes a store's job. The in-memory stores
+ * keep the method for those tests; it is simply not part of the contract.
+ */
+export interface UpdateStore {
+    loadSnapshot(): Promise<Snapshot | null>;
+    loadUpdatesAfter(baselineId: string | null): Promise<UpdateRecord[]>;
+    appendUpdate(update: Uint8Array): Promise<void>;
+    /** Stream records as they are appended.
+     *
+     * `baselineId` filters the stream exactly as `loadUpdatesAfter` does,
+     * and the provider passes what it already loaded. Without it every
+     * client re-received the document's whole history on attach --
+     * history it had just loaded itself -- and again on every reconnect.
+     * DOU-388 measured the shape: one append reaches every subscribed
+     * client, so at 200 collaborators a reconnect storm meant 200 clients
+     * each re-reading everything (DOU-395).
+     *
+     * Implementations must honour it, including in-memory ones, so tests
+     * exercise the same contract production does. */
+    subscribeUpdates(onUpdate: (record: UpdateRecord) => void, baselineId?: string | null): () => void;
+}
+/** Minimal assertion surface, so this module stays dependency-free and
+ * can be driven by `node:assert`, vitest, or anything else. */
+export interface ConformanceAsserts {
+    equal(actual: unknown, expected: unknown, message?: string): void;
+    deepEqual(actual: unknown, expected: unknown, message?: string): void;
+    ok(value: unknown, message?: string): void;
+}
+export interface ConformanceCase {
+    name: string;
+    run(store: UpdateStore, a: ConformanceAsserts): Promise<void>;
+}
+/**
+ * Behavioural cases every `UpdateStore` must satisfy, expressed against
+ * the interface alone so one list can drive every backend.
+ *
+ * Each case gets a *fresh* store from the caller's factory — several
+ * assert on the empty state, and a shared store would make them
+ * order-dependent.
+ *
+ * Scope note: these cover the store contract, not Yjs semantics. Updates
+ * are arbitrary bytes here on purpose — a store that only works for
+ * well-formed Yjs payloads is a store that inspects payloads it should be
+ * treating as opaque. Convergence is covered separately.
+ */
+export declare const updateStoreConformance: ConformanceCase[];
+//# sourceMappingURL=crdt-store.d.ts.map

package/dist/crdt-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crdt-store.d.ts","sourceRoot":"","sources":["../src/crdt-store.ts"],"names":[],"mappings":"AA6BA,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACzC,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACrE,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD;;;;;;;;;;;qDAWiD;IACjD,gBAAgB,CACd,QAAQ,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,EACxC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,MAAM,IAAI,CAAC;CACf;AAID;+DAC+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAaD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAAe,EAgGnD,CAAC"}

package/dist/crdt-store.js

@@ -0,0 +1,140 @@
+// The CRDT update-store contract, shared by web/ and sync/.
+//
+// WHY THIS LIVES IN @doubling/types
+//
+// The Yjs provider and its store backends exist twice — once in
+// `web/src/yjs/`, once in `sync/`. That duplication is not carelessness:
+// the root `.npmrc` sets `install-strategy=nested` on purpose, because
+// `desktop/scripts/after-pack.cjs` needs `sync/node_modules/firebase` to
+// be a real directory when it copies the daemon into the .app bundle,
+// `functions/` deploys with its own `node_modules`, and
+// `@doubling/compound-sync` publishes standalone. So a shared workspace
+// package that imported `yjs` or `firebase` would resolve its *own*
+// nested copies of them, and two instances of either is worse than the
+// duplication: two `yjs` copies break Yjs' client-id identity, two
+// `firebase` copies break the SDK's runtime type checks on
+// `collection()` / `doc()` inputs (DOU-379).
+//
+// This file is the part that *can* be shared, because it has no runtime
+// dependencies at all. It is types and plain functions over `Uint8Array`
+// and `string` — the store treats updates as opaque bytes, so nothing
+// here needs to know what Yjs is.
+//
+// The payoff is compile-time: both `FirestoreUpdateStore`s and both
+// `MemoryUpdateStore`s declare `implements UpdateStore` against *this*
+// interface, so a signature drifting on one side is a type error rather
+// than something a reader has to notice. That is what actually failed
+// before — the divergences found in this subsystem were all found by
+// reading, never by a check.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function bytes(s) {
+    return encoder.encode(s);
+}
+function text(b) {
+    return decoder.decode(b);
+}
+/**
+ * Behavioural cases every `UpdateStore` must satisfy, expressed against
+ * the interface alone so one list can drive every backend.
+ *
+ * Each case gets a *fresh* store from the caller's factory — several
+ * assert on the empty state, and a shared store would make them
+ * order-dependent.
+ *
+ * Scope note: these cover the store contract, not Yjs semantics. Updates
+ * are arbitrary bytes here on purpose — a store that only works for
+ * well-formed Yjs payloads is a store that inspects payloads it should be
+ * treating as opaque. Convergence is covered separately.
+ */
+export const updateStoreConformance = [
+    {
+        name: 'loadSnapshot returns null before anything is written',
+        async run(store, a) {
+            a.equal(await store.loadSnapshot(), null);
+        },
+    },
+    {
+        name: 'loadUpdatesAfter(null) is empty on a fresh store',
+        async run(store, a) {
+            a.deepEqual(await store.loadUpdatesAfter(null), []);
+        },
+    },
+    {
+        name: 'appended updates read back in append order',
+        async run(store, a) {
+            await store.appendUpdate(bytes('one'));
+            await store.appendUpdate(bytes('two'));
+            await store.appendUpdate(bytes('three'));
+            const all = await store.loadUpdatesAfter(null);
+            a.deepEqual(all.map((r) => text(r.update)), ['one', 'two', 'three']);
+        },
+    },
+    {
+        name: 'ids sort in the same order records were appended',
+        async run(store, a) {
+            await store.appendUpdate(bytes('a'));
+            await store.appendUpdate(bytes('b'));
+            await store.appendUpdate(bytes('c'));
+            const ids = (await store.loadUpdatesAfter(null)).map((r) => r.id);
+            const sorted = [...ids].sort();
+            a.deepEqual(ids, sorted, 'iterating in id order must replay in append order — the ordering contract');
+        },
+    },
+    {
+        name: 'loadUpdatesAfter(baselineId) excludes the baseline itself',
+        async run(store, a) {
+            await store.appendUpdate(bytes('first'));
+            await store.appendUpdate(bytes('second'));
+            const all = await store.loadUpdatesAfter(null);
+            a.equal(all.length, 2);
+            const after = await store.loadUpdatesAfter(all[0].id);
+            a.deepEqual(after.map((r) => text(r.update)), ['second']);
+        },
+    },
+    {
+        name: 'the newest id yields an empty tail',
+        async run(store, a) {
+            await store.appendUpdate(bytes('only'));
+            const all = await store.loadUpdatesAfter(null);
+            a.deepEqual(await store.loadUpdatesAfter(all[all.length - 1].id), []);
+        },
+    },
+    {
+        name: 'an empty update round-trips as empty, not as absent',
+        async run(store, a) {
+            // Conflating "zero bytes" with "no record" is the shape of bug this
+            // subsystem keeps producing: DOU-404 (blob read failure faked as
+            // empty content) and the DOU-378 drain() bug (wrote '' over real
+            // content) were both that mistake. A store must keep them distinct.
+            await store.appendUpdate(new Uint8Array(0));
+            const all = await store.loadUpdatesAfter(null);
+            a.equal(all.length, 1, 'an empty update is still a record');
+            a.equal(all[0].update.length, 0);
+        },
+    },
+    {
+        name: 'subscribeUpdates delivers records appended after subscribing',
+        async run(store, a) {
+            const seen = [];
+            const unsubscribe = store.subscribeUpdates((r) => seen.push(text(r.update)));
+            await store.appendUpdate(bytes('live'));
+            // Backends deliver asynchronously; give the listener a turn.
+            await new Promise((r) => setTimeout(r, 50));
+            a.ok(seen.includes('live'), `expected delivery, saw ${JSON.stringify(seen)}`);
+            unsubscribe();
+        },
+    },
+    {
+        name: 'unsubscribe stops delivery',
+        async run(store, a) {
+            const seen = [];
+            const unsubscribe = store.subscribeUpdates((r) => seen.push(text(r.update)));
+            unsubscribe();
+            await store.appendUpdate(bytes('after-unsubscribe'));
+            await new Promise((r) => setTimeout(r, 50));
+            a.ok(!seen.includes('after-unsubscribe'), `listener fired after unsubscribe: ${JSON.stringify(seen)}`);
+        },
+    },
+];
+//# sourceMappingURL=crdt-store.js.map

package/dist/crdt-store.js.map

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

package/dist/crdt-testing.d.ts

@@ -0,0 +1,34 @@
+/** The slice of `Y.Text` the generators need. `Y.Text` satisfies this
+ * structurally, which is what keeps this module dependency-free. */
+export interface TextLike {
+    readonly length: number;
+    insert(index: number, content: string): void;
+    delete(index: number, length: number): void;
+}
+/** mulberry32. Small, fast, adequate for shuffling and picking offsets;
+ * not cryptographic and does not need to be. */
+export declare function makeRng(seed: number): () => number;
+export declare function pick<T>(rng: () => number, xs: readonly T[]): T;
+export declare function shuffled<T>(rng: () => number, xs: readonly T[]): T[];
+/** Fixed seeds, named rather than a range so a failing one can be pinned
+ * in isolation while debugging. */
+export declare const SEEDS: readonly [1, 7, 42, 1337, 90210, 555555];
+/** Deliberately includes a newline, a non-ASCII letter and an astral-plane
+ * emoji: CRDT text indices are UTF-16 code units, so a surrogate pair is
+ * where off-by-one position handling shows up. */
+export declare const WORDS: readonly ["alpha", "beta ", "gamma", " delta", "eps", "\n", "ζ", "🙂"];
+export type Edit = {
+    kind: 'insert';
+    index: number;
+    text: string;
+} | {
+    kind: 'delete';
+    index: number;
+    length: number;
+};
+/** Generate an edit valid against a text of the given length. Positions and
+ * lengths are clamped so generated edits are always applicable — the
+ * property under test is convergence, not the CRDT's bounds checking. */
+export declare function generateEdit(rng: () => number, currentLength: number): Edit;
+export declare function applyEdit(text: TextLike, edit: Edit): void;
+//# sourceMappingURL=crdt-testing.d.ts.map

package/dist/crdt-testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crdt-testing.d.ts","sourceRoot":"","sources":["../src/crdt-testing.ts"],"names":[],"mappings":"AAwBA;oEACoE;AACpE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED;gDACgD;AAChD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CASlD;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAE9D;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAOpE;AAED;mCACmC;AACnC,eAAO,MAAM,KAAK,0CAA4C,CAAC;AAE/D;;kDAEkD;AAClD,eAAO,MAAM,KAAK,wEAAyE,CAAC;AAE5F,MAAM,MAAM,IAAI,GACZ;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD;;yEAEyE;AACzE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAW3E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAQ1D"}

package/dist/crdt-testing.js

@@ -0,0 +1,79 @@
+// Deterministic edit generators for CRDT convergence testing.
+//
+// WHY THESE ARE SHARED
+//
+// The provider and its stores exist twice (web/src/yjs/ and sync/) and
+// cannot be collapsed into one package — see the header of ./crdt-store.ts
+// for why. That makes it easy for the two sides' *tests* to drift as well
+// as their implementations, and a shared implementation with two different
+// generators would still let them disagree about what "an edit" is.
+//
+// These live here for the same reason the contract does: they have no
+// runtime dependencies. `applyEdit` takes a structural `TextLike` rather
+// than a `Y.Text`, which `Y.Text` satisfies without this module importing
+// yjs — so it stays shareable under the repo's nested install strategy,
+// where a shared package with runtime deps would resolve its own copies.
+//
+// DETERMINISM
+//
+// Seeded, never Math.random. A property test whose failures cannot be
+// replayed is a flake generator: the seed appears in every assertion
+// message so a failure reproduces exactly. The seed list is fixed rather
+// than time-derived so CI runs the same cases every time — widening
+// coverage is a deliberate edit to SEEDS, not a side effect of the clock.
+/** mulberry32. Small, fast, adequate for shuffling and picking offsets;
+ * not cryptographic and does not need to be. */
+export function makeRng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function pick(rng, xs) {
+    return xs[Math.floor(rng() * xs.length)];
+}
+export function shuffled(rng, xs) {
+    const out = xs.slice();
+    for (let i = out.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(rng() * (i + 1));
+        [out[i], out[j]] = [out[j], out[i]];
+    }
+    return out;
+}
+/** Fixed seeds, named rather than a range so a failing one can be pinned
+ * in isolation while debugging. */
+export const SEEDS = [1, 7, 42, 1337, 90210, 555_555];
+/** Deliberately includes a newline, a non-ASCII letter and an astral-plane
+ * emoji: CRDT text indices are UTF-16 code units, so a surrogate pair is
+ * where off-by-one position handling shows up. */
+export const WORDS = ['alpha', 'beta ', 'gamma', ' delta', 'eps', '\n', 'ζ', '🙂'];
+/** Generate an edit valid against a text of the given length. Positions and
+ * lengths are clamped so generated edits are always applicable — the
+ * property under test is convergence, not the CRDT's bounds checking. */
+export function generateEdit(rng, currentLength) {
+    if (currentLength > 0 && rng() < 0.3) {
+        const index = Math.floor(rng() * currentLength);
+        const length = Math.max(1, Math.floor(rng() * Math.min(5, currentLength - index)));
+        return { kind: 'delete', index, length };
+    }
+    return {
+        kind: 'insert',
+        index: Math.floor(rng() * (currentLength + 1)),
+        text: pick(rng, WORDS),
+    };
+}
+export function applyEdit(text, edit) {
+    if (edit.kind === 'insert') {
+        text.insert(Math.min(edit.index, text.length), edit.text);
+        return;
+    }
+    const index = Math.min(edit.index, text.length);
+    const length = Math.min(edit.length, text.length - index);
+    if (length > 0)
+        text.delete(index, length);
+}
+//# sourceMappingURL=crdt-testing.js.map

package/dist/crdt-testing.js.map

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

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export * from './crdt-store.js';
+export * from './crdt-testing.js';
 export * from './firestore.js';
 export * from './mime.js';
 export * from './paths.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -4,6 +4,8 @@
 // relative imports in TypeScript source, even though the actual file
 // on disk is `.ts`. tsc and Node's ESM loader rewrite to the
 // compiled `.js` at build / runtime.
+export * from './crdt-store.js';
+export * from './crdt-testing.js';
 export * from './firestore.js';
 export * from './mime.js';
 export * from './paths.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,EAAE;AACF,6DAA6D;AAC7D,qEAAqE;AACrE,6DAA6D;AAC7D,qCAAqC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,EAAE;AACF,6DAA6D;AAC7D,qEAAqE;AACrE,6DAA6D;AAC7D,qCAAqC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubling/types",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared Firestore document interfaces and MIME / path helpers consumed by web/ and sync/. Single source of truth so the two consumers can never drift on a document shape (DOU-182, TS Phase 2 of the monorepo TypeScript migration).",
   "type": "module",
   "main": "./dist/index.js",