@undefineds.co/xpod 0.4.10 → 0.4.12

package/node_modules/@undefineds.co/pod-collections/dist/react.js

@@ -0,0 +1,22 @@
+import { useLiveQuery } from '@tanstack/react-db';
+/**
+ * `./react` 入口（§6.2）：只有这里 import `@tanstack/react-db`，主入口保持无 React。
+ *
+ * P1 只保证这一层的签名与编译（§8.2 的测试清单里没有 React 用例）；真实渲染、
+ * live query 与乐观层的交互验收在 P3 的 pilot 页面上做（§8.6）。
+ */
+export { useLiveQuery };
+/**
+ * 便捷 hook：把一个集合当单表读出来。
+ * `rows` 已含乐观行（库的 `state` 语义），`status` 直接来自 live query。
+ */
+export function usePodCollection(collection) {
+    const { data, status, isLoading } = useLiveQuery({
+        query: (q) => q.from({ row: collection }),
+    });
+    return {
+        rows: data,
+        status,
+        isLoading,
+    };
+}

package/node_modules/@undefineds.co/pod-collections/dist/read.d.ts

@@ -0,0 +1,65 @@
+import type { AnyPodTable, SolidDatabase } from '@undefineds.co/drizzle-solid';
+import type { PodModelDescriptor } from '@undefineds.co/models';
+import type { PodDocumentRead } from './types.js';
+/**
+ * 唯一的读原语（§8.2）：`conditionalDocumentRead(document, { ifNoneMatch })`
+ * → `{ etag, subjects }`。
+ *
+ * ## 文档 ETag：P1 第一件事的结论（§8.7-2 / §9-6）
+ *
+ * **drizzle-solid 0.3.24 的读路径拿不到文档 ETag**，所以本原语恒返回
+ * `etag: undefined`，同步按 §8.7-2 的出口降级为「每个合并窗口全量读 + 投影 diff，
+ * 只写真正变化的行」，仍然零轮询（N1）。证据：
+ *
+ * 1. 类型面上没有任何 ETag 载体：`QueryResourceHelper.findMany/findFirst/find/findById`
+ *    返回 `Promise<T[]>`（`node_modules/@undefineds.co/drizzle-solid/dist/core/pod-database.d.ts`
+ *    的 `QueryResourceHelper`）、`ExecutionStrategy.executeSelect` 返回 `unknown[]`
+ *    （`dist/core/execution/types.d.ts`）、`ComunicaSPARQLExecutor.executeSelect` 同样
+ *    （`dist/core/sparql-executor.d.ts:22`）。
+ * 2. 实现面上只有写路径读 ETag：整个 `dist/`（CJS 与 ESM 两份）里只有
+ *    `core/sparql-executor.js:301` / `:344` 两处 `headers.get('ETag')`，都在
+ *    `executeUpdate()` 里为 PATCH 组装 `If-Match`，从不返回给调用方；
+ *    `executeDirectSparqlQuery()`（同文件 `:704-745`）只取 `payload.results.bindings`。
+ * 3. 读并不落在文档上：`credentialResource` 声明了 `sparqlEndpoint: '/settings/-/sparql'`
+ *    （`@undefineds.co/models@0.2.57` 的 `dist/credential.schema.js:74`，与 0.2.56 同行同值 ——
+ *    该版本改动的是 `credentialDescriptor.fields` / `uniqueBy`，没有动表的 endpoint），
+ *    `SparqlStrategy.executeSelect()`（`dist/core/execution/sparql-strategy.js:66-82`）
+ *    把查询发给该 endpoint，`resolveTargetGraph(table, true)`（`forSelect`）对 document
+ *    模式返回 `undefined`，实测生成的查询没有 `GRAPH`/`FROM` 子句：
+ *    `SELECT ?subject … WHERE { ?subject rdf:type <…/ns#Credential>. … }`。
+ *    `.test-data/etag-probe/probe.ts` 的记录显示这次读期间**文档本身没有被请求**
+ *    （只打到 `/settings/-/sparql?query=…`），所以文档 ETag 不是这次读的 validator：
+ *    即便能拿到它，也无法用来判定「这次读的结果是否变了」。
+ * 4. 唯一能拿到 ETag 的路径是绕过读 API：`database.getDialect().config.session.fetch`
+ *    是注入的认证 fetch（实测 `HEAD <document>` → `200 ETag: "v1"`，带 `If-None-Match`
+ *    的条件 GET → `304`）。它属于 drizzle-solid 的内部接线（`PodDialect.config.session`），
+ *    与 §3.2 想要的「条件**读**」不是同一个资源（见第 3 点），因此本层不依赖它，
+ *    也不据此伪造 `metadata.collection.etag`。
+ *
+ * `ifNoneMatch` 因此只是签名上的兼容位：本实现无法用它短路读，读者应把
+ * `etag === undefined` 当作「条件读不可用」的信号（§8.7-2、§9-6）。
+ */
+export interface PodDocumentReadSource<D extends PodModelDescriptor> {
+    descriptor: D;
+    table: AnyPodTable;
+    database: SolidDatabase;
+    /** 表所在文档的绝对 URL（`resolveTableDocument()` 的结果）。 */
+    document: string;
+    podUrl: string;
+}
+export interface PodDocumentReadRequest {
+    /** 上一次读到的文档 ETag。当前读路径无法使用它（见文件头）。 */
+    ifNoneMatch?: string;
+}
+/**
+ * 读一个文档的全部主语行。行由 drizzle-solid 的读给出（它已经按表的 `type`
+ * 施加类过滤：查询里带 `?subject rdf:type <descriptor.class>`），这里再按文档收敛，
+ * 因为该读不是文档作用域的（见文件头第 3 点）。
+ */
+export declare function conditionalDocumentRead<D extends PodModelDescriptor>(source: PodDocumentReadSource<D>, _request?: PodDocumentReadRequest): Promise<PodDocumentRead>;
+/**
+ * 认证 fetch：drizzle-solid 没有公开的 session fetch 访问器，`PodDialect.config.session`
+ * 是唯一可达路径，且就是它自己用的那个 fetch（`sparql-executor.js:296/:319` 的 HEAD/PATCH）。
+ * 仅 §4.1 的 `array + uri` PATCH 旁路需要它；拿不到时抛明确错误而不是静默跳过写。
+ */
+export declare function sessionFetchOf(database: SolidDatabase): typeof fetch | undefined;

package/node_modules/@undefineds.co/pod-collections/dist/read.js

@@ -0,0 +1,31 @@
+import { rowBelongsToDocument } from './layout.js';
+/** drizzle-solid `select().from(table).execute()`；首次读前确保表已 init。 */
+async function selectSubjectRows(table, database) {
+    const initialized = typeof table.isInitialized === 'function' ? table.isInitialized() : true;
+    if (!initialized)
+        await database.init?.(table);
+    const rows = await database.select().from(table).execute();
+    return rows;
+}
+/**
+ * 读一个文档的全部主语行。行由 drizzle-solid 的读给出（它已经按表的 `type`
+ * 施加类过滤：查询里带 `?subject rdf:type <descriptor.class>`），这里再按文档收敛，
+ * 因为该读不是文档作用域的（见文件头第 3 点）。
+ */
+export async function conditionalDocumentRead(source, _request = {}) {
+    const subjects = await selectSubjectRows(source.table, source.database);
+    return {
+        etag: undefined,
+        subjects: subjects.filter((subject) => rowBelongsToDocument(source.descriptor, source.document, source.podUrl, subject)),
+    };
+}
+/**
+ * 认证 fetch：drizzle-solid 没有公开的 session fetch 访问器，`PodDialect.config.session`
+ * 是唯一可达路径，且就是它自己用的那个 fetch（`sparql-executor.js:296/:319` 的 HEAD/PATCH）。
+ * 仅 §4.1 的 `array + uri` PATCH 旁路需要它；拿不到时抛明确错误而不是静默跳过写。
+ */
+export function sessionFetchOf(database) {
+    const dialect = database.getDialect?.();
+    const candidate = dialect?.config?.session?.fetch;
+    return typeof candidate === 'function' ? candidate : undefined;
+}

package/node_modules/@undefineds.co/pod-collections/dist/sync.d.ts

@@ -0,0 +1,66 @@
+import type { Collection, SyncConfig } from '@tanstack/db';
+import type { AnyPodTable, SolidDatabase } from '@undefineds.co/drizzle-solid';
+import type { PodModelDescriptor } from '@undefineds.co/models';
+import type { PodPendingWrites } from './mutations.js';
+import type { PodDocumentFeed, PodSyncState, RowOf } from './types.js';
+/**
+ * TanStack sync 实现（§3）。
+ *
+ * 时序不可换（§3.1）：
+ *
+ * ```
+ * feed.watch(document) ──► 首次整表读（一次 drizzle-solid select）
+ *        │                        │
+ *        │  读期间到达的脏信号 → 缓冲
+ *        ▼                        ▼
+ *   投递脏信号 ◄──────────── markReady()
+ *        │
+ *        ▼
+ *   合并窗口（75ms）──► 重读 ──► diff ──► begin/write/commit 增量
+ * ```
+ *
+ * 与 §3.2 伪代码的三处**实测修正**（@tanstack/db@0.9.0）：
+ *
+ * 1. `metadata.row.set()` 必须在事务**打开期间**调用：
+ *    `dist/esm/collection/sync.js:272-280` 的 `getActivePendingSyncTransaction()` 在
+ *    没有未提交事务时抛 `NoPendingSyncTransactionWriteError`，所以伪代码里 `commit()`
+ *    之后再 `set` 会直接抛错。这里改成 `write → metadata.row.set → commit`。
+ * 2. `commit()` 返回 `true | Promise<void>`（同步可见性收据），必须 `await`：
+ *    存在 persisting 的用户事务时，普通 sync 事务会被排队
+ *    （`dist/esm/collection/state.js:593` 的 `!hasPersistingTransaction || …`），
+ *    等待收据就会一直挂住。因此本实现统一用 `begin({ immediate: true })`
+ *    —— 这正是库为「需要立刻写入 syncedData 的写操作」提供的开关。
+ * 3. `metadata.collection` 的 ETag 无法获得（见 `read.ts` 的结论），
+ *    所以每个脏信号都是「读 + 投影 diff」，未变的行 0 次 `write()`（§8.7-2 的出口）。
+ */
+/** 变更合并窗口，沿用现网 `TABLE_CHANGE_COALESCE_MS`（§3.2）。 */
+export declare const DEFAULT_COALESCE_MS = 75;
+/** §4.2：确认未满足时再等一个合并窗口重试，默认 2 次后抛错。 */
+export declare const DEFAULT_CONFIRM_RETRIES = 2;
+export interface PodSyncOptions<D extends PodModelDescriptor> {
+    descriptor: D;
+    table: AnyPodTable;
+    database: SolidDatabase;
+    podUrl: string;
+    document: string;
+    feed?: PodDocumentFeed;
+    coalesceMs?: number;
+    confirmRetries?: number;
+    pending: PodPendingWrites<RowOf<D>>;
+    /** 创建后回填的集合引用（`refresh()` 在 sync 启动前被调用时用它拉起 preload）。 */
+    collection: () => Collection<RowOf<D>, string> | undefined;
+}
+export interface PodSyncEngine<R extends object> {
+    /** 交给 `createCollection({ sync: { sync } })` 的函数。 */
+    sync: SyncConfig<R, string>['sync'];
+    /** 显式重读（`PodCollection.refresh()`）。 */
+    refresh(): Promise<void>;
+    /** §4.2 的确认协议：写后立刻重读，未满足则等一个合并窗口重试。 */
+    confirmPending(key: string): Promise<void>;
+    state(): PodSyncState;
+    /** 释放订阅与定时器（页面卸载/登出；宿主 capability 的 `dispose()`）。 */
+    dispose(): void;
+    /** @internal 测试钩子：调用库的 `truncate()`（清空 syncedData 与 row metadata）。 */
+    truncate(): void;
+}
+export declare function createPodSync<D extends PodModelDescriptor>(options: PodSyncOptions<D>): PodSyncEngine<RowOf<D>>;

package/node_modules/@undefineds.co/pod-collections/dist/sync.js

@@ -0,0 +1,260 @@
+import { conditionalDocumentRead } from './read.js';
+import { mapSubjectRows, projectionFieldOrder, writeOnlyFields } from './mapping.js';
+import { computeDocumentDiff, projectionHash, stripVirtualProps } from './diff.js';
+import { subscribeDocumentFeed } from './feed.js';
+import { reconcilePendingWrites } from './mutations.js';
+import { PodCollectionError } from './types.js';
+/**
+ * TanStack sync 实现（§3）。
+ *
+ * 时序不可换（§3.1）：
+ *
+ * ```
+ * feed.watch(document) ──► 首次整表读（一次 drizzle-solid select）
+ *        │                        │
+ *        │  读期间到达的脏信号 → 缓冲
+ *        ▼                        ▼
+ *   投递脏信号 ◄──────────── markReady()
+ *        │
+ *        ▼
+ *   合并窗口（75ms）──► 重读 ──► diff ──► begin/write/commit 增量
+ * ```
+ *
+ * 与 §3.2 伪代码的三处**实测修正**（@tanstack/db@0.9.0）：
+ *
+ * 1. `metadata.row.set()` 必须在事务**打开期间**调用：
+ *    `dist/esm/collection/sync.js:272-280` 的 `getActivePendingSyncTransaction()` 在
+ *    没有未提交事务时抛 `NoPendingSyncTransactionWriteError`，所以伪代码里 `commit()`
+ *    之后再 `set` 会直接抛错。这里改成 `write → metadata.row.set → commit`。
+ * 2. `commit()` 返回 `true | Promise<void>`（同步可见性收据），必须 `await`：
+ *    存在 persisting 的用户事务时，普通 sync 事务会被排队
+ *    （`dist/esm/collection/state.js:593` 的 `!hasPersistingTransaction || …`），
+ *    等待收据就会一直挂住。因此本实现统一用 `begin({ immediate: true })`
+ *    —— 这正是库为「需要立刻写入 syncedData 的写操作」提供的开关。
+ * 3. `metadata.collection` 的 ETag 无法获得（见 `read.ts` 的结论），
+ *    所以每个脏信号都是「读 + 投影 diff」，未变的行 0 次 `write()`（§8.7-2 的出口）。
+ */
+/** 变更合并窗口，沿用现网 `TABLE_CHANGE_COALESCE_MS`（§3.2）。 */
+export const DEFAULT_COALESCE_MS = 75;
+/** §4.2：确认未满足时再等一个合并窗口重试，默认 2 次后抛错。 */
+export const DEFAULT_CONFIRM_RETRIES = 2;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function createPodSync(options) {
+    const { descriptor, table, database, document, podUrl, pending } = options;
+    const coalesceMs = options.coalesceMs ?? DEFAULT_COALESCE_MS;
+    const confirmRetries = options.confirmRetries ?? DEFAULT_CONFIRM_RETRIES;
+    const fieldOrder = projectionFieldOrder(descriptor);
+    // `secret: true` 的字段读不回来，确认协议要按这条规则把它们排除在比对之外（§4.2、§9-7）。
+    const writeOnly = writeOnlyFields(descriptor);
+    const hashOf = (row) => projectionHash(row, fieldOrder);
+    let params;
+    let subscription;
+    let feedAvailable = false;
+    let ready = false;
+    let failureReported = false;
+    let syncState = 'initializing';
+    let timer;
+    let bufferedSignals = [];
+    let running;
+    let rerunRequested = false;
+    let disposed = false;
+    let lastEtag;
+    async function ensureParams() {
+        if (params)
+            return params;
+        const collection = options.collection();
+        if (!collection) {
+            throw new PodCollectionError('sync_not_started', 'collection has not started syncing yet');
+        }
+        await collection.preload();
+        if (!params) {
+            throw new PodCollectionError('sync_not_started', 'collection sync did not start');
+        }
+        return params;
+    }
+    function schedulePass() {
+        if (disposed || timer !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void runPass().catch(() => {
+                // 脏信号驱动的读失败：保持现有行，状态标降级（§3.4），等下一次信号或显式 refresh()。
+                syncState = 'degraded';
+            });
+        }, coalesceMs);
+    }
+    /**
+     * 串行化的「读 + diff + 写」：正在跑的一轮会吸收新请求（合并成一轮重跑），
+     * 空闲时立刻开一轮。sync 事务一律用 `immediate` 开始（见文件头修正 2）。
+     *
+     * `running` 必须在**本轮循环结束时同步清掉**（内层 `finally`），不能挂在返回
+     * promise 的 `.finally()` 上：后者要等一个额外的微任务，那段时间里 `running`
+     * 仍是已完成的旧 promise，调用方会拿到「什么都没做」的旧 promise
+     * （实测：首读失败后紧接着 refresh() 不会产生新读）。
+     */
+    function runPass() {
+        if (running) {
+            rerunRequested = true;
+            return running;
+        }
+        const task = (async () => {
+            try {
+                do {
+                    rerunRequested = false;
+                    await passOnce();
+                } while (rerunRequested && !disposed);
+            }
+            finally {
+                running = undefined;
+            }
+        })();
+        running = task;
+        return task;
+    }
+    async function passOnce() {
+        const sync = await ensureParams();
+        if (disposed)
+            return;
+        let read;
+        try {
+            read = await conditionalDocumentRead({ descriptor, table, database, document, podUrl }, { ifNoneMatch: lastEtag });
+        }
+        catch (error) {
+            // 读失败 → 不动集合，只标降级（§3.4）；首读失败必须给库一个结论，否则 live query 永不
+            // resolve，所以报一次 markError。之后成功的读会把它带回 ready（库允许 error → ready），
+            // 因此这里**不**把 `ready` 置真。
+            syncState = 'degraded';
+            if (!ready && !failureReported) {
+                failureReported = true;
+                sync.markError(error);
+            }
+            return;
+        }
+        if (read.etag !== undefined)
+            lastEtag = read.etag;
+        const rows = mapSubjectRows(descriptor, table, read.subjects);
+        const next = new Map(rows.map((row) => [String(row.id), row]));
+        const presentKeys = [...sync.collection.keys()].map((key) => String(key));
+        const knownHash = (key) => {
+            const entry = sync.metadata?.row.get(key);
+            return entry?.hash;
+        };
+        const diff = computeDocumentDiff({
+            next,
+            presentKeys,
+            pendingKeys: pending.keys,
+            knownHash,
+            hashOf,
+            presentRow: (key) => sync.collection.get(key),
+        });
+        if (diff.inserts.length + diff.updates.length + diff.deletes.length > 0) {
+            // immediate：库在存在 persisting 用户事务时会把普通 sync 事务排队，
+            // 那会让 §4.4 的自回声与 §4.2 的确认永远等不到应用（见文件头修正 2）。
+            sync.begin({ immediate: true });
+            for (const entry of diff.inserts) {
+                sync.write({ type: 'insert', value: stripVirtualProps(entry.row) });
+            }
+            for (const entry of diff.updates) {
+                // `rowUpdateMode: 'full'`：整行替换，键由库用 `getKey(value)` 取（行里有 id）。
+                sync.write({ type: 'update', value: stripVirtualProps(entry.row) });
+            }
+            for (const entry of diff.deletes) {
+                // §3.2 要求 delete 带上前一行；0.9.0 的 `ChangeMessageOrDeleteKeyMessage` 联合类型
+                // 不允许 delete 携带 value（运行时允许且不使用），因此在这里做一次局部放宽。
+                sync.write({
+                    type: 'delete',
+                    key: entry.key,
+                    value: stripVirtualProps(entry.row),
+                });
+            }
+            for (const entry of [...diff.inserts, ...diff.updates]) {
+                // 投影哈希写进 row metadata（delete 的 row metadata 由库自动删除，§3.2）。
+                sync.metadata?.row.set(entry.key, { hash: hashOf(entry.row) });
+            }
+            await sync.commit();
+        }
+        if (!ready) {
+            ready = true;
+            failureReported = false;
+            sync.markReady();
+        }
+        reconcilePendingWrites(pending, next, hashOf, writeOnly);
+        syncState = feedAvailable ? 'live' : 'unavailable';
+    }
+    async function confirmPending(key) {
+        const entry = pending.entries.get(key);
+        if (!entry)
+            return;
+        for (let attempt = 0;; attempt += 1) {
+            await runPass();
+            if (entry.settled) {
+                if (entry.error)
+                    throw entry.error;
+                return;
+            }
+            if (attempt >= confirmRetries) {
+                throw new PodCollectionError('write_unconfirmed', `write to ${key} was not visible in the document after ${confirmRetries + 1} reads`);
+            }
+            await sleep(coalesceMs);
+        }
+    }
+    const sync = (syncParams) => {
+        if (disposed)
+            return () => { };
+        params = syncParams;
+        subscription = subscribeDocumentFeed(options.feed, document, () => {
+            if (!ready) {
+                bufferedSignals.push({ topic: document });
+                return;
+            }
+            schedulePass();
+        });
+        feedAvailable = subscription.available;
+        void runPass()
+            .then(() => {
+            if (disposed)
+                return;
+            // 状态由 passOnce 写（成功 = live/unavailable，失败 = degraded），这里只重放缓冲信号。
+            const replay = bufferedSignals;
+            bufferedSignals = [];
+            if (replay.length > 0)
+                schedulePass();
+        })
+            .catch(() => {
+            syncState = 'degraded';
+        });
+        return () => {
+            dispose();
+        };
+    };
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        subscription?.unsubscribe();
+        subscription = undefined;
+        bufferedSignals = [];
+    }
+    return {
+        sync,
+        refresh: () => runPass(),
+        confirmPending,
+        state: () => syncState,
+        dispose,
+        truncate: () => {
+            if (!params || disposed)
+                return;
+            params.begin({ immediate: true });
+            params.truncate();
+            void Promise.resolve(params.commit()).catch(() => { });
+        },
+    };
+}

package/node_modules/@undefineds.co/pod-collections/dist/types.d.ts

@@ -0,0 +1,155 @@
+import type { Collection, InsertConfig, Transaction } from '@tanstack/db';
+import type { AnyPodTable, SolidDatabase } from '@undefineds.co/drizzle-solid';
+import type { PodModelDescriptor, PodModelFieldDescriptor, PodModelFieldType } from '@undefineds.co/models';
+/**
+ * descriptor 字段类型 → TS 类型（`docs/pod-collections.md` §2.1）。
+ * `array: true` 必须先于标量判断。
+ *
+ * 与 §2.1 代码块的唯一差别是最后两行：`@undefineds.co/models@0.2.57` 仍然把 descriptor
+ * 声明成 `PodModelDescriptor`（`fields: Record<string, PodModelFieldDescriptor>`，
+ * 见 `dist/pod-storage-descriptor.d.ts:13-34` / `:95`），字段字面量类型没有随包导出，
+ * 所以官方 descriptor 的 `{ type: ... }` 是**联合类型**而不是单个字面量 —— 0.2.57 补的是
+ * credential 的字段（19 个），没有把字段类型变精确。此时若沿用 §2.1 的 `: string` 兜底，
+ * `RowOf<typeof credentialDescriptor>` 会把 `expiresAt` / `createdAt` 等 `timestamp` 字段
+ * 也标成 `string`，而运行时它们是 `Date` —— 类型说谎。这里对「类型未被收窄」的情形返回
+ * `unknown`：字面量 descriptor（测试与将来的 models 发版）仍得到 §2.1 的精确类型，
+ * 官方 descriptor 得到诚实的 `unknown`，绝不静默收窄或放宽成表列类型。
+ *
+ * 附带后果：`keyof Record<string, …>` 是 `string | number`，所以 `RowOf<官方 descriptor>`
+ * 带索引签名，字段名不会被静态校验 —— 这正是 `test/guards.test.ts` 用运行时清单
+ * （36 字段 / 36 列 / `uniqueBy`）而不是类型来守漂移的原因。
+ */
+export type PodFieldValue<F extends PodModelFieldDescriptor> = F extends {
+    array: true;
+} ? PodFieldValue<Omit<F, 'array'>>[] : F extends {
+    type: 'number';
+} ? number : F extends {
+    type: 'boolean';
+} ? boolean : F extends {
+    type: 'timestamp';
+} ? Date : F extends {
+    type: 'json';
+} ? unknown : F extends {
+    type: 'string' | 'text' | 'uri';
+} ? string : F extends {
+    type: PodModelFieldType;
+} ? unknown : string;
+/**
+ * 行 = descriptor 的 fields 投影 + 行标识（§2.1）。
+ *
+ * 行标识只有 `id`（`resourceIdPattern` 的 `{id}` slot，§2.7 的键取法）与 `@id`
+ * （主语 IRI）。**不从 drizzle 表列推导行类型**：表列与 descriptor 不一致时由
+ * `test/guards.test.ts` 报错，而不是悄悄把行类型放宽到表列。
+ */
+export type RowOf<D extends PodModelDescriptor> = {
+    [K in keyof D['fields']]: PodFieldValue<D['fields'][K]>;
+} & {
+    id: string;
+    '@id'?: string;
+};
+/**
+ * drizzle-solid `select()` 返回的「主语行」：列名 → 已解码值，外加虚列
+ * `id`（base-relative resource id）、`@id` / `uri` / `subject`（主语 IRI）。
+ * 形状由 `packages/pod-collections/.test-data` 探针实测，
+ * 见 `read.ts` 的 ETag 说明。
+ */
+export type PodSubjectRow = Record<string, unknown>;
+/**
+ * 一次文档读的结果（§8.2 的 `conditionalDocumentRead`）。
+ *
+ * `etag` 只有在读路径能拿到文档 validator 时才有值；drizzle-solid 0.3.24 的读
+ * 路径拿不到（证据见 `read.ts`），所以实际实现恒为 `undefined`，同步退化为
+ * 「每个合并窗口全量读 + 投影 diff」（§8.7-2 的出口）。字段保留是为了将来读原语
+ * 能给出 ETag 时不必改签名。
+ */
+export interface PodDocumentRead {
+    etag: string | undefined;
+    subjects: PodSubjectRow[];
+}
+/**
+ * 变更 feed 端口（§2.2）：只声明集合层用到的那一面，结构上由
+ * `SolidNotificationsCapability` 满足。集合层不实现任何传输。
+ */
+export interface PodDocumentFeed {
+    watch(topicUrl: string, listener: (signal: {
+        topic: string;
+    }) => void): () => void;
+}
+/** 该 key 上未确认的本地写与服务端行的冲突（§4.5，server wins + 标记）。 */
+export interface PodRowConflict<R extends object> {
+    key: string;
+    /** 服务端当前行（已生效）。 */
+    server: R;
+    /** 本地未确认写入的意图。 */
+    local: R;
+    at: number;
+}
+/** 同步状态：`live` = feed 可用；`unavailable` = 只读一次 + 显式 `refresh()`（N1）。 */
+export type PodSyncState = 'initializing' | 'live' | 'unavailable' | 'degraded';
+/**
+ * TanStack 的 Collection + 我们加的观测面（§2.2）。
+ * TanStack 的类型不出现在 applet 签名里，换引擎时改动面锁在包内。
+ */
+export interface PodCollection<R extends {
+    id: string;
+} = Record<string, unknown> & {
+    id: string;
+}> extends Collection<R, string> {
+    /**
+     * 写入负载收窄成「descriptor 字段的一部分 + 行标识」。
+     *
+     * 为什么不能直接用 `RowOf<D>` 当插入输入：`secret: true` 的字段不从行里投影出去
+     * （§2.1），所以行类型拿不到、也读不回这些字段，而写入必须能提供它们。缺的字段
+     * 由 drizzle-solid 的列默认值补齐；确认协议按「意图里**可读**的字段」逐字段比对，
+     * 不用整行相等（否则带默认值的服务端行永远无法与部分意图相等）。
+     *
+     * 只写字段（`secret: true`）写得到、读不回，因此**不参与**确认比对，也不会因为
+     * 它们被判冲突：它们的证据是写入调用本身成功。规则与理由见 `diff.projectionCovers()`
+     * 与 `docs/pod-collections.md` §9-7。
+     */
+    insert: (data: (Partial<R> & {
+        id: string;
+    }) | Array<Partial<R> & {
+        id: string;
+    }>, config?: InsertConfig) => Transaction<Record<string, unknown>>;
+    /** 表所在文档的绝对 URL（§2.3 的 topic 推导结果）。 */
+    readonly tableDocument: string;
+    /** 有未确认本地写的 key。sync 不会用服务端行覆盖它们的 insert/delete 判定（§3、§4.4）。 */
+    readonly pendingKeys: ReadonlySet<string>;
+    /** 记录到的外部冲突（最近优先）。 */
+    readonly conflicts: readonly PodRowConflict<R>[];
+    /** 显式条件重读；mutation handler 的确认协议内部也用它（§4.2）。 */
+    refresh(): Promise<void>;
+}
+export interface PodCollectionOptions<D extends PodModelDescriptor> {
+    /** drizzle-solid 表：I/O 走它。 */
+    table: AnyPodTable;
+    database: SolidDatabase;
+    podUrl: string;
+    /** 变更 feed（脏信号）。缺省 = 无 live：只读一次，之后只能显式 refresh()（N1）。 */
+    feed?: PodDocumentFeed;
+    /**
+     * 表所在文档。单文档表可由 `storage.base` 推导（缺省）；
+     * 跨文档表（模型行按 provider 分文档）必须给，或用 scope 选一个文档。
+     */
+    document?: string;
+    scope?: {
+        provider?: string;
+        instanceId?: string;
+    };
+    /** 变更合并窗口，沿用现网 75ms。 */
+    coalesceMs?: number;
+    onConflict?: (conflict: PodRowConflict<RowOf<D>>) => void;
+    /** 确认协议的重试次数（写入后未读回意图时再等一个合并窗口），默认 2（§4.2）。 */
+    confirmRetries?: number;
+}
+/** 集合层错误：都带稳定 code，调用方按 code 分派，不解析 message。 */
+export declare class PodCollectionError extends Error {
+    readonly code: string;
+    /** 原始错误（`Error.cause` 是 ES2022；本包 target ES2020，自己挂字段）。 */
+    readonly cause?: unknown;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export type { PodModelDescriptor, PodModelFieldDescriptor };

package/node_modules/@undefineds.co/pod-collections/dist/types.js

@@ -0,0 +1,9 @@
+/** 集合层错误：都带稳定 code，调用方按 code 分派，不解析 message。 */
+export class PodCollectionError extends Error {
+    constructor(code, message, options) {
+        super(message);
+        this.name = 'PodCollectionError';
+        this.code = code;
+        this.cause = options?.cause;
+    }
+}

package/node_modules/@undefineds.co/pod-collections/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@undefineds.co/pod-collections",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && bun ../../scripts/fix-dist-js-imports.mjs dist && bun build src/index.ts --target=node --format=cjs --packages=external --outfile=dist/index.cjs",
+    "test": "vitest run test --config ../../vitest.packages.config.mts",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "@tanstack/db": "0.9.0",
+    "@tanstack/react-db": "0.3.8",
+    "@undefineds.co/models": "0.2.59"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/node_modules/@undefineds.co/shared-ui/dist/index.d.ts

@@ -17,7 +17,6 @@ export { LocalReachabilitySummary, } from './login/LocalReachabilitySummary';
 export { getProviderActionLabel, getProviderDisplayLabel, getProviderInfoText, getProviderSourceLabel, getProviderStatusBadge, getProviderSubtitle, type ProviderStatusBadge, } from './login/presentation';
 export { isLocalLoginProvider, isLocalLoginProviderSource, resolveLoginProviderSource, } from './login/provider-model';
 export type { AuthWindowStatus, ConnectingProviderInfo, LocalLoginProviderSource, LocalLoginStatus, LocalOnboardingCapabilities, LocalOnboardingConnectivity, LocalOnboardingProgress, LocalOnboardingRouteKind, LocalOnboardingRouteProbe, LocalOnboardingSnapshot, LocalOnboardingState, LocalOnboardingTunnel, LocalPodRuntime, LocalSpaceKind, LoginEndpoint, LoginEndpointKind, LoginModalProps, LoginProviderOption, LoginProviderSource, LoginState, ProviderOption, StorageConflict, StoredAccount, } from './login/types';
-export * from './oidc-consent';
 export * from './scroll-area';
 export * from './separator';
 export * from './skeleton';