@undefineds.co/xpod 0.4.11 → 0.4.12

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

@@ -0,0 +1,287 @@
+import { PodCollectionError } from './types.js';
+import { rowKeyOf, rowKeyVariable } from './layout.js';
+/**
+ * RDF ↔ 行映射（`docs/pod-collections.md` §2.4）。
+ *
+ * 映射的唯一来源是 **descriptor 的字段声明**：`fields[*].predicate` 决定哪个表列
+ * 承载该字段（列名由 drizzle 表的 mapping 给出，不由字段名猜）。两个 0.2.57 实测的
+ * 证据：`createdAt` 经 `dcterms:created` 落到 `createdAt` 列（谓词不在 `ns#` 下），
+ * 而行标识字段 `id` 的谓词是 `ns#id`、**不**落到表里那个同名的 `id` 列上（那是 `@id`
+ * 虚列）—— 所以按名绑定会在第二个例子上直接错。字段类型只由 `fields[*].type` 决定，
+ * **不从 term 类型反推**（§2.4 边界 1：以 `http(s)://` 开头的 `string` 会被写成
+ * named node）。
+ *
+ * 字面量 datatype 按 drizzle-solid 的 SPARQL helper 规则
+ * （`node_modules/@undefineds.co/drizzle-solid/dist/esm/core/sparql/helpers.js`
+ * 的 `buildLiteralTerm`）：整数 `xsd:integer`、非整数 `xsd:decimal`、`xsd:boolean`、
+ * `xsd:dateTime`。注意同一文件的 `formatValue()`（写路径）对整数发的是**无 datatype**
+ * 的字面量，两者并不一致；本层按 §2.4 表格取 `buildLiteralTerm` 的规则，写路径仍完全
+ * 交给 drizzle-solid 自己格式化。
+ */
+const XSD = 'http://www.w3.org/2001/XMLSchema#';
+/** 表列 → 谓词（跳过 `@id` 虚列）。 */
+export function tableColumnPredicates(table) {
+    const mapping = table.getMapping();
+    const predicates = new Map();
+    for (const [column, entry] of Object.entries(mapping.columns)) {
+        if (entry.predicate === '@id')
+            continue;
+        predicates.set(column, entry.predicate);
+    }
+    return predicates;
+}
+/** descriptor 字段 → 承载它的表列（按谓词，不按字段名）。 */
+export function fieldBindings(descriptor, table) {
+    const byPredicate = new Map();
+    for (const [column, predicate] of tableColumnPredicates(table)) {
+        byPredicate.set(predicate, column);
+    }
+    const bindings = new Map();
+    for (const [field, fieldDescriptor] of Object.entries(descriptor.fields)) {
+        bindings.set(field, { field, descriptor: fieldDescriptor, column: byPredicate.get(fieldDescriptor.predicate) });
+    }
+    return bindings;
+}
+/**
+ * 行标识字段：`resourceIdPattern` 的 `{…}` 键 slot 名（`#{id}` → `id`）。
+ * 它由 drizzle-solid 的虚列 `id` / `@id` 承载，不落在任何谓词列上。
+ */
+export function identityFieldOf(descriptor) {
+    return rowKeyVariable(descriptor.storage.resourceIdPattern);
+}
+/**
+ * descriptor 声明了、但表里找不到对应谓词的字段（§2.7 的漂移面）。
+ * 行标识字段不算：它由行本身承载（`mapSubjectRows` 用行键填它）。
+ */
+export function descriptorFieldsWithoutColumn(descriptor, table) {
+    const identity = identityFieldOf(descriptor);
+    return [...fieldBindings(descriptor, table).values()]
+        .filter((binding) => binding.column === undefined && binding.field !== identity)
+        .map((binding) => binding.field)
+        .sort();
+}
+/** 表里有、但 descriptor 没声明的列（§2.7 的漂移面）。 */
+export function tableColumnsWithoutDescriptorField(descriptor, table) {
+    const declaredPredicates = new Set(Object.values(descriptor.fields).map((field) => field.predicate));
+    return [...tableColumnPredicates(table)]
+        .filter(([, predicate]) => !declaredPredicates.has(predicate))
+        .map(([column]) => column)
+        .sort();
+}
+/**
+ * 类过滤的显式化（§2.4 边界 2）：行准入以 descriptor 的 `class` 为准，而 drizzle 的
+ * 读把它编译成 `?subject rdf:type <class>`（表 options 的 `type`）。两者必须同源，
+ * 否则读回来的行与 descriptor 不是一套 schema —— 抛错而不是静默接受。
+ */
+export function assertDescriptorTableAlignment(descriptor, table) {
+    const tableClass = table.getType();
+    if (descriptor.class !== tableClass) {
+        throw new PodCollectionError('mapping_class_mismatch', `descriptor ${descriptor.uri} declares class ${descriptor.class} but table ${table.config.name} reads ${tableClass}`);
+    }
+}
+/**
+ * 只写字段（`secret: true`）：**写入可以带、读取永远读不回**。
+ *
+ * §2.1 把投影定义为「descriptor 的非 secret 字段」，所以这些字段既不在
+ * `mapSubjectRows()` 的行里，也不可能出现在服务端投影里。这个集合是那条规则的
+ * 唯一来源：读写两侧（`mapSubjectRows()` 与 §4.2 的确认协议）都从它取，避免
+ * 「哪边算 secret」出现第二份判断。
+ *
+ * 特别注意它与「descriptor 声明了但表里没有列」的字段（§2.7 的漂移面）不是一回事：
+ * 后者是**可读**字段，只是当前不可投影，语义上仍要求出现在服务端行里。
+ */
+export function writeOnlyFields(descriptor) {
+    return new Set(Object.entries(descriptor.fields)
+        .filter(([, field]) => field.secret === true)
+        .map(([name]) => name));
+}
+/**
+ * 投影后的字段顺序：按谓词排序（§3.2 的投影哈希要求确定性，与字段声明顺序无关）。
+ */
+export function projectionFieldOrder(descriptor) {
+    // The projection is the *readable* row: `secret: true` fields never come back
+    // from a read (see `writeOnlyFields`), so counting them would make the row the
+    // store completed differ from the row we wrote and turn our own echo into a
+    // spurious update.
+    const writeOnly = writeOnlyFields(descriptor);
+    return Object.entries(descriptor.fields)
+        .filter(([field]) => !writeOnly.has(field))
+        .sort(([, left], [, right]) => (left.predicate < right.predicate ? -1 : left.predicate > right.predicate ? 1 : 0))
+        .map(([field]) => field);
+}
+function isRdfTerm(value) {
+    return typeof value === 'object' && value !== null
+        && typeof value.termType === 'string'
+        && typeof value.value === 'string';
+}
+function termDatatypeOf(value) {
+    const datatype = value.datatype;
+    if (!datatype)
+        return undefined;
+    return typeof datatype === 'string' ? datatype : datatype.value;
+}
+function coerceScalar(field, input) {
+    if (input === null || input === undefined || input === '')
+        return undefined;
+    const term = isRdfTerm(input) ? input : undefined;
+    const raw = term ? term.value : input;
+    const datatype = term ? termDatatypeOf(term) : undefined;
+    switch (field.type) {
+        case 'uri':
+            return term && term.termType !== 'NamedNode' ? String(raw) : String(raw);
+        case 'string':
+        case 'text':
+            return typeof raw === 'boolean' || typeof raw === 'number' ? String(raw) : String(raw);
+        case 'number': {
+            if (typeof raw === 'number')
+                return raw;
+            const parsed = Number(raw);
+            return Number.isFinite(parsed) ? parsed : undefined;
+        }
+        case 'boolean':
+            if (typeof raw === 'boolean')
+                return raw;
+            if (raw === 'true')
+                return true;
+            if (raw === 'false')
+                return false;
+            return Boolean(raw);
+        case 'timestamp': {
+            const date = raw instanceof Date ? raw : new Date(String(raw));
+            return Number.isNaN(date.getTime()) ? undefined : date;
+        }
+        case 'json': {
+            // JSON 的序列化细节属于 drizzle-solid（§2.4）：非 term 输入（ORM 已解码的值）
+            // 原样透传；term 输入（本层 valueToTerm 的产物）解析回值，解析不了就当字符串。
+            if (!term)
+                return input;
+            if (datatype && !/#json(Array)?$/u.test(datatype) && raw === '')
+                return undefined;
+            try {
+                return JSON.parse(String(raw));
+            }
+            catch {
+                return raw;
+            }
+        }
+        default:
+            return raw;
+    }
+}
+/** 值 → 行字段值；同时接受 drizzle-solid 已解码的值与 RDF term（§2.4）。 */
+export function coerceFieldValue(field, input) {
+    if (field.array) {
+        if (input === undefined || input === null)
+            return undefined;
+        const list = Array.isArray(input) ? input : [input];
+        const values = list
+            .map((item) => coerceScalar(field, item))
+            .filter((item) => item !== undefined);
+        return values.length > 0 ? values : undefined;
+    }
+    return coerceScalar(field, input);
+}
+/** 值 → RDF term（§2.4；datatype 规则见文件头）。 */
+export function valueToTerm(field, value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (field.type === 'uri')
+        return { termType: 'NamedNode', value: String(value) };
+    if (field.type === 'number') {
+        const numeric = typeof value === 'number' ? value : Number(value);
+        if (!Number.isFinite(numeric))
+            return undefined;
+        return {
+            termType: 'Literal',
+            value: String(numeric),
+            datatype: Number.isInteger(numeric) ? `${XSD}integer` : `${XSD}decimal`,
+        };
+    }
+    if (field.type === 'boolean') {
+        return { termType: 'Literal', value: value ? 'true' : 'false', datatype: `${XSD}boolean` };
+    }
+    if (field.type === 'timestamp') {
+        const date = value instanceof Date ? value : new Date(String(value));
+        if (Number.isNaN(date.getTime()))
+            return undefined;
+        return { termType: 'Literal', value: date.toISOString(), datatype: `${XSD}dateTime` };
+    }
+    if (field.type === 'json') {
+        return { termType: 'Literal', value: typeof value === 'string' ? value : JSON.stringify(value) };
+    }
+    const text = String(value);
+    // §2.4 边界 1：`string` 字段的值以 http(s):// 开头时会被写成 named node。
+    if (/^https?:\/\//u.test(text))
+        return { termType: 'NamedNode', value: text };
+    return { termType: 'Literal', value: text };
+}
+/** array 字段：每个元素一个 term（每元素一条三元组，§2.4）。 */
+export function valuesToTerms(field, value) {
+    const list = Array.isArray(value) ? value : [value];
+    return list
+        .map((item) => valueToTerm(field, item))
+        .filter((term) => term !== undefined);
+}
+/**
+ * 主语行 → 集合行（`RowOf<D>`）：只投影 descriptor 的非 `secret` 字段，
+ * `secret: true` 的字段默认不出现在行里（§2.1）。文档归属由读原语（`read.ts`）
+ * 决定，这里只做投影与键提取。
+ */
+export function mapSubjectRows(descriptor, table, subjects) {
+    const bindings = fieldBindings(descriptor, table);
+    const identityField = identityFieldOf(descriptor);
+    const writeOnly = writeOnlyFields(descriptor);
+    const rows = [];
+    for (const subject of subjects) {
+        const key = rowKeyOf(descriptor, subject);
+        if (key === undefined)
+            continue;
+        const row = { id: key };
+        if (identityField !== 'id')
+            row[identityField] = key;
+        const subjectIri = subject['@id'] ?? subject.uri ?? subject.subject;
+        if (typeof subjectIri === 'string')
+            row['@id'] = subjectIri;
+        for (const binding of bindings.values()) {
+            if (writeOnly.has(binding.field))
+                continue;
+            if (binding.column === undefined)
+                continue;
+            const value = coerceFieldValue(binding.descriptor, subject[binding.column]);
+            if (value !== undefined)
+                row[binding.field] = value;
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+/**
+ * 集合行 → drizzle 写负载（列名 → 值），供 `insert().values()` / `updateById()`。
+ * `array + uri` 字段由调用方走 `writeField()` 的 PATCH 旁路，不进 ORM（§4.1）。
+ * 返回的负载总是包含行标识列 `id`（表列 `id` 是 base-relative resource id）。
+ */
+export function descriptorRowToColumnValues(descriptor, table, row, options) {
+    const bindings = fieldBindings(descriptor, table);
+    const values = { id: options.resourceId };
+    for (const [field, value] of Object.entries(row)) {
+        if (field === 'id' || field === '@id')
+            continue;
+        const binding = bindings.get(field);
+        if (!binding || binding.column === undefined)
+            continue;
+        if (options.includeField && !options.includeField(field))
+            continue;
+        values[binding.column] = value;
+    }
+    return values;
+}
+/** 该字段是否走 §4.1 的 PATCH 旁路：`array: true` + `type: 'uri'`。 */
+export function isUriArrayField(field) {
+    return field.array === true && field.type === 'uri';
+}
+/** descriptor 里所有走 PATCH 旁路的字段。 */
+export function uriArrayFields(descriptor) {
+    return Object.entries(descriptor.fields)
+        .filter(([, field]) => isUriArrayField(field))
+        .map(([name]) => name);
+}

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

@@ -0,0 +1,83 @@
+import type { AnyPodTable, SolidDatabase } from '@undefineds.co/drizzle-solid';
+import type { PodModelDescriptor } from '@undefineds.co/models';
+import type { InsertMutationFn, UpdateMutationFn, DeleteMutationFn } from '@tanstack/db';
+import type { PodRowConflict, RowOf } from './types.js';
+/**
+ * 未确认的本地写。`sync` 每轮读回文档后调用 `reconcilePendingWrites()`：
+ * 读回意图 → 确认；读回第三方值 → 冲突（server wins + 标记）；仍未见意图 → 继续等。
+ */
+export interface PodPendingWrite<R extends object> {
+    key: string;
+    /** 写入意图；删除时为 `undefined`。 */
+    intent: R | undefined;
+    /** 本地认为的行（删除时为删除前的行），仅用于冲突呈现。 */
+    localRow: R | undefined;
+    /** 写前的服务端投影哈希；`undefined` = 该行此前不在文档里。 */
+    beforeHash: string | undefined;
+    settled: boolean;
+    error: Error | undefined;
+    settledPromise: Promise<void>;
+    resolveSettled: () => void;
+}
+export interface RegisterPendingWriteInput<R extends object> {
+    key: string;
+    intent: R | undefined;
+    localRow: R | undefined;
+    beforeHash: string | undefined;
+}
+export interface PodPendingWrites<R extends object> {
+    /** 有未确认写的 key（同一个 Set 直接暴露给 `PodCollection.pendingKeys`）。 */
+    readonly keys: ReadonlySet<string>;
+    readonly entries: ReadonlyMap<string, PodPendingWrite<R>>;
+    readonly conflicts: readonly PodRowConflict<R>[];
+    register(input: RegisterPendingWriteInput<R>): PodPendingWrite<R>;
+    clear(key: string): void;
+    /** 该 key 的写是否已确认（意图已出现在服务端投影里）。 */
+    isConfirmed(key: string): boolean;
+    /** @internal 记录一次冲突（server wins + 标记 + 事务失败）。 */
+    recordConflict(conflict: PodRowConflict<R>): void;
+    /** @internal 结束一个未确认写：`error` 为空表示确认。 */
+    settle(entry: PodPendingWrite<R>, error?: Error): void;
+}
+export declare function createPendingWrites<R extends object>(onConflict?: (conflict: PodRowConflict<R>) => void): PodPendingWrites<R>;
+/** 冲突标记：记录 + 回调 + 让写事务失败（§4.5）。 */
+export declare function markConflict<R extends object>(pending: PodPendingWrites<R>, entry: PodPendingWrite<R>, server: R): void;
+/**
+ * 每轮读回文档后调和未确认写（§4.2、§4.4、§4.5）。
+ * - 服务端投影覆盖了意图的**可读**字段：确认（handler 可以 resolve，乐观层被同值服务端行替换）。
+ * - 服务端投影 ∉ {意图, 写前值}：外部冲突，server wins + 标记 + 事务失败。
+ * - 服务端还没有该行：继续等下一轮（写可能还在索引后面）。
+ *
+ * `writeOnly` 是 `mapping.writeOnlyFields(descriptor)`：`secret: true` 的字段读不回来，
+ * 因此**不参与**「覆盖」判定，也不会因为它们而判冲突 —— 规则与理由见
+ * `diff.projectionCovers()`。可读字段的比对一字未松：意图里任何一个非 secret 字段
+ * 在服务端行里对不上，仍然走冲突分支。
+ */
+export declare function reconcilePendingWrites<R extends object>(pending: PodPendingWrites<R>, next: ReadonlyMap<string, R>, hashOf: (row: R) => string, writeOnly?: ReadonlySet<string>): void;
+export interface PodMutationContext<D extends PodModelDescriptor> {
+    descriptor: D;
+    table: AnyPodTable;
+    database: SolidDatabase;
+    podUrl: string;
+    document: string;
+    pending: PodPendingWrites<RowOf<D>>;
+    /** §4.2 的确认协议；由 sync 提供（立刻重读 + 至多 N 次合并窗口重试）。 */
+    confirm: (key: string) => Promise<void>;
+    /** PATCH 用的认证 fetch；缺省时从 database 的 session 取（见 `sessionFetchOf`）。 */
+    authenticatedFetch?: typeof fetch;
+}
+/**
+ * `array: true` + `type: 'uri'` 字段的唯一写入口（§4.1）：一次 SPARQL PATCH，
+ * 先删旧值再插新值。`array + uri` 之外字段不允许走这里。
+ */
+export declare function writeField<D extends PodModelDescriptor>(context: PodMutationContext<D>, fieldName: string, options: {
+    subjectIri: string;
+    previous: unknown;
+    next: unknown;
+}): Promise<void>;
+export interface PodMutationHandlers<D extends PodModelDescriptor> {
+    onInsert: InsertMutationFn<RowOf<D>, string>;
+    onUpdate: UpdateMutationFn<RowOf<D>, string>;
+    onDelete: DeleteMutationFn<RowOf<D>, string>;
+}
+export declare function createMutationHandlers<D extends PodModelDescriptor>(context: PodMutationContext<D>): PodMutationHandlers<D>;

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

@@ -0,0 +1,273 @@
+import { PodCollectionError } from './types.js';
+import { descriptorRowToColumnValues, fieldBindings, isUriArrayField, projectionFieldOrder, } from './mapping.js';
+import { documentOfIri, resourceIdForRow, subjectIriForRow } from './layout.js';
+import { sessionFetchOf } from './read.js';
+import { projectionCovers, projectionHash } from './diff.js';
+function createDeferred() {
+    let resolve;
+    const promise = new Promise((settle) => {
+        resolve = () => settle();
+    });
+    return { promise, resolve };
+}
+export function createPendingWrites(onConflict) {
+    const keys = new Set();
+    const entries = new Map();
+    const conflicts = [];
+    const clear = (key) => {
+        keys.delete(key);
+        entries.delete(key);
+    };
+    const settle = (entry, error) => {
+        if (entry.settled)
+            return;
+        entry.error = error;
+        entry.settled = true;
+        entry.resolveSettled();
+    };
+    const register = (input) => {
+        // 同一 key 上只允许一个未确认写（库的乐观层也只展示最后一个）；后者取代前者。
+        clear(input.key);
+        const deferred = createDeferred();
+        const entry = {
+            ...input,
+            settled: false,
+            error: undefined,
+            settledPromise: deferred.promise,
+            resolveSettled: deferred.resolve,
+        };
+        entries.set(input.key, entry);
+        keys.add(input.key);
+        return entry;
+    };
+    return {
+        keys,
+        entries,
+        conflicts,
+        register,
+        clear,
+        settle,
+        isConfirmed: (key) => entries.get(key)?.settled === true && entries.get(key)?.error === undefined,
+        recordConflict: (conflict) => {
+            conflicts.push(conflict);
+            onConflict?.(conflict);
+        },
+    };
+}
+/** 冲突标记：记录 + 回调 + 让写事务失败（§4.5）。 */
+export function markConflict(pending, entry, server) {
+    pending.recordConflict({
+        key: entry.key,
+        server,
+        local: (entry.localRow ?? entry.intent ?? server),
+        at: Date.now(),
+    });
+    pending.settle(entry, new PodCollectionError('write_conflict', `row ${entry.key} was changed by someone else; server wins`));
+}
+/**
+ * 每轮读回文档后调和未确认写（§4.2、§4.4、§4.5）。
+ * - 服务端投影覆盖了意图的**可读**字段：确认（handler 可以 resolve，乐观层被同值服务端行替换）。
+ * - 服务端投影 ∉ {意图, 写前值}：外部冲突，server wins + 标记 + 事务失败。
+ * - 服务端还没有该行：继续等下一轮（写可能还在索引后面）。
+ *
+ * `writeOnly` 是 `mapping.writeOnlyFields(descriptor)`：`secret: true` 的字段读不回来，
+ * 因此**不参与**「覆盖」判定，也不会因为它们而判冲突 —— 规则与理由见
+ * `diff.projectionCovers()`。可读字段的比对一字未松：意图里任何一个非 secret 字段
+ * 在服务端行里对不上，仍然走冲突分支。
+ */
+export function reconcilePendingWrites(pending, next, hashOf, writeOnly = EMPTY_WRITE_ONLY) {
+    for (const entry of pending.entries.values()) {
+        if (entry.settled)
+            continue;
+        const server = next.get(entry.key);
+        if (entry.intent === undefined) {
+            // 删除意图：行不在了就是确认。
+            if (server === undefined) {
+                pending.settle(entry);
+                continue;
+            }
+            if (entry.beforeHash !== undefined && hashOf(server) !== entry.beforeHash) {
+                markConflict(pending, entry, server);
+            }
+            continue;
+        }
+        if (projectionCovers(server, entry.intent, writeOnly)) {
+            // 意图的可读字段都在服务端行里（插入意图可能只带一部分字段；带 secret 的意图
+            // 只按可读部分确认，secret 的证据是写调用已经成功）。
+            pending.settle(entry);
+            continue;
+        }
+        if (server !== undefined && hashOf(server) !== entry.beforeHash) {
+            markConflict(pending, entry, server);
+            continue;
+        }
+        if (server === undefined && entry.beforeHash !== undefined) {
+            // 我们想改的行已经不在文档里：外部删除，服务端状态已是「不存在」。
+            pending.settle(entry, new PodCollectionError('write_conflict', `row ${entry.key} disappeared before the write was confirmed; server wins`));
+        }
+    }
+}
+/** 默认「没有只写字段」，与 `projectionCovers()` 的默认值同义。 */
+const EMPTY_WRITE_ONLY = new Set();
+function absoluteUri(value, base) {
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    if (/^[a-z][a-z0-9+.-]*:/iu.test(value))
+        return value;
+    return new URL(value, base).toString();
+}
+/**
+ * `array: true` + `type: 'uri'` 字段的唯一写入口（§4.1）：一次 SPARQL PATCH，
+ * 先删旧值再插新值。`array + uri` 之外字段不允许走这里。
+ */
+export async function writeField(context, fieldName, options) {
+    const field = context.descriptor.fields[fieldName];
+    if (!field || !isUriArrayField(field)) {
+        throw new PodCollectionError('write_field_not_uri_array', `field ${fieldName} is not array+uri; it must go through the ORM`);
+    }
+    const documentUrl = documentOfIri(context.document);
+    const previous = (Array.isArray(options.previous) ? options.previous : [options.previous])
+        .map((value) => absoluteUri(value, documentUrl))
+        .filter((value) => value !== undefined);
+    const next = (Array.isArray(options.next) ? options.next : [options.next])
+        .map((value) => absoluteUri(value, documentUrl))
+        .filter((value) => value !== undefined);
+    const triples = (iris) => iris
+        .map((iri) => `<${options.subjectIri}> <${field.predicate}> <${iri}> .`)
+        .join('\n');
+    const operations = [
+        previous.length > 0 ? `DELETE DATA { ${triples(previous)} }` : undefined,
+        next.length > 0 ? `INSERT DATA { ${triples(next)} }` : undefined,
+    ].filter((operation) => operation !== undefined);
+    if (operations.length === 0)
+        return;
+    const fetchFn = context.authenticatedFetch ?? sessionFetchOf(context.database);
+    if (!fetchFn) {
+        throw new PodCollectionError('write_field_no_fetch', 'array+uri fields need an authenticated fetch (SolidAuthSession.fetch); none available');
+    }
+    const response = await fetchFn(documentUrl, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/sparql-update' },
+        body: operations.join(';\n'),
+    });
+    if (!response.ok) {
+        throw new PodCollectionError('write_field_rejected', `SPARQL PATCH for ${fieldName} failed with HTTP ${response.status}`);
+    }
+}
+export function createMutationHandlers(context) {
+    const { descriptor, table, pending } = context;
+    const fieldOrder = projectionFieldOrder(descriptor);
+    const hashOf = (row) => projectionHash(row, fieldOrder);
+    const uriArrayFieldNames = new Set(Object.entries(descriptor.fields)
+        .filter(([, field]) => isUriArrayField(field))
+        .map(([name]) => name));
+    const columnBindings = fieldBindings(descriptor, table);
+    const columnOf = (field) => columnBindings.get(field)?.column;
+    const runWrite = async (key, write) => {
+        try {
+            await write();
+        }
+        catch (error) {
+            pending.clear(key);
+            throw error instanceof Error
+                ? error
+                : new PodCollectionError('write_failed', String(error), { cause: error });
+        }
+        try {
+            await context.confirm(key);
+        }
+        finally {
+            pending.clear(key);
+        }
+    };
+    return {
+        onInsert: async ({ transaction }) => {
+            for (const mutation of transaction.mutations) {
+                const row = mutation.modified;
+                const key = String(mutation.key);
+                const resourceId = resourceIdForRow(descriptor, context.document, context.podUrl, key);
+                const subjectIri = subjectIriForRow(descriptor, context.document, key);
+                pending.register({
+                    key,
+                    intent: row,
+                    localRow: row,
+                    beforeHash: undefined,
+                });
+                await runWrite(key, async () => {
+                    const values = descriptorRowToColumnValues(descriptor, table, row, {
+                        resourceId,
+                        includeField: (field) => !uriArrayFieldNames.has(field),
+                    });
+                    await context.database.insert(table).values(values).execute();
+                    await writeUriArrayFields(context, row, subjectIri, undefined, row);
+                });
+            }
+        },
+        onUpdate: async ({ transaction }) => {
+            for (const mutation of transaction.mutations) {
+                const key = String(mutation.key);
+                const original = mutation.original;
+                const modified = mutation.modified;
+                const changes = mutation.changes;
+                const resourceId = resourceIdForRow(descriptor, context.document, context.podUrl, key);
+                const subjectIri = subjectIriForRow(descriptor, context.document, key);
+                const beforeHash = original && Object.keys(original).length > 0 ? hashOf(original) : undefined;
+                pending.register({
+                    key,
+                    intent: modified,
+                    localRow: modified,
+                    beforeHash,
+                });
+                await runWrite(key, async () => {
+                    const columnChanges = {};
+                    for (const [field, value] of Object.entries(changes)) {
+                        if (uriArrayFieldNames.has(field))
+                            continue;
+                        const column = columnOf(field);
+                        if (column === undefined)
+                            continue;
+                        columnChanges[column] = value;
+                    }
+                    if (Object.keys(columnChanges).length > 0) {
+                        const updated = await context.database.updateById(table, resourceId, columnChanges);
+                        if (!updated) {
+                            throw new PodCollectionError('write_rejected', `drizzle-solid did not update ${resourceId}`);
+                        }
+                    }
+                    await writeUriArrayFields(context, changes, subjectIri, original, modified);
+                });
+            }
+        },
+        onDelete: async ({ transaction }) => {
+            for (const mutation of transaction.mutations) {
+                const key = String(mutation.key);
+                const original = mutation.original;
+                const resourceId = resourceIdForRow(descriptor, context.document, context.podUrl, key);
+                pending.register({
+                    key,
+                    intent: undefined,
+                    localRow: original,
+                    beforeHash: original && Object.keys(original).length > 0 ? hashOf(original) : undefined,
+                });
+                await runWrite(key, async () => {
+                    // 返回 false = 该行本来就不在：意图（行不存在）已经满足，交给确认协议判定。
+                    await context.database.deleteById(table, resourceId);
+                });
+            }
+        },
+    };
+}
+/** 遍历本次写涉及的 `array + uri` 字段，逐个走 §4.1 的 PATCH 旁路。 */
+async function writeUriArrayFields(context, changed, subjectIri, previousRow, nextRow) {
+    for (const [field, fieldDescriptor] of Object.entries(context.descriptor.fields)) {
+        if (!isUriArrayField(fieldDescriptor))
+            continue;
+        if (!(field in changed))
+            continue;
+        await writeField(context, field, {
+            subjectIri,
+            previous: previousRow?.[field],
+            next: nextRow?.[field],
+        });
+    }
+}

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

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