@undefineds.co/xpod 0.4.10 → 0.4.12

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

@@ -0,0 +1,37 @@
+import type { PodModelDescriptor } from '@undefineds.co/models';
+import type { PodCollection, PodCollectionOptions, PodRowConflict, PodSyncState, RowOf } from './types.js';
+export type { PodCollection, PodCollectionOptions, PodDocumentFeed, PodRowConflict, PodSyncState, PodSubjectRow, PodFieldValue, RowOf, } from './types.js';
+export type { PodLayoutInput, PodLayoutScope } from './layout.js';
+export type { PodRdfTerm } from './mapping.js';
+export { PodCollectionError } from './types.js';
+export type { PodFieldBinding } from './mapping.js';
+export { DEFAULT_COALESCE_MS, DEFAULT_CONFIRM_RETRIES } from './sync.js';
+/**
+ * 声明一个 Pod 表集合（§2）。
+ *
+ * 表是一个**文档**，行是文档里的**主语**：schema 全部来自 models 的 descriptor
+ * （`storage.base` / `resourceIdPattern` / `fields` / `class`），消费方不手写 topic、
+ * 不手写字段映射、不手写 refetch。集合定义本身就是「开启订阅」的声明（D3），
+ * 所以这里 `startSync: true`：配置了 feed 就是活表，没有 feed 就退化为
+ * 「读一次 + 显式 `refresh()`」，永不轮询（N1）。
+ */
+export declare function definePodCollection<D extends PodModelDescriptor>(descriptor: D, options: PodCollectionOptions<D>): PodCollection<RowOf<D>>;
+/** 行键冲突类型再导出，便于 applet 写 `onConflict` 回调签名。 */
+export type PodConflict<R extends object> = PodRowConflict<R>;
+export { conditionalDocumentRead, sessionFetchOf } from './read.js';
+export { resolveTableDocument, rowKeyOf, subjectIriForRow, resourceIdForRow } from './layout.js';
+export { coerceFieldValue, descriptorFieldsWithoutColumn, fieldBindings, mapSubjectRows, projectionFieldOrder, tableColumnsWithoutDescriptorField, valueToTerm, writeOnlyFields, } from './mapping.js';
+export { computeDocumentDiff, projectionHash, stripVirtualProps } from './diff.js';
+/**
+ * 内部观测面（不在 `PodCollection` 接口里）：宿主能力用它读取同步状态，
+ * 测试用它驱动库的 `truncate()`。类型上显式标注，避免 applet 依赖。
+ */
+export interface PodCollectionInternals {
+    syncState(): PodSyncState;
+    dispose(): void;
+    /** @internal 仅测试：调用库的 `truncate()`（清空 syncedData 与 row metadata）。 */
+    truncateForTest(): void;
+}
+export declare function podCollectionInternals<R extends {
+    id: string;
+}>(collection: PodCollection<R>): PodCollectionInternals;

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

@@ -0,0 +1,89 @@
+import { createCollection } from '@tanstack/db';
+import { resolveTableDocument } from './layout.js';
+import { assertDescriptorTableAlignment } from './mapping.js';
+import { createMutationHandlers, createPendingWrites } from './mutations.js';
+import { createPodSync } from './sync.js';
+import { PodCollectionError } from './types.js';
+export { PodCollectionError } from './types.js';
+export { DEFAULT_COALESCE_MS, DEFAULT_CONFIRM_RETRIES } from './sync.js';
+/**
+ * 声明一个 Pod 表集合（§2）。
+ *
+ * 表是一个**文档**，行是文档里的**主语**：schema 全部来自 models 的 descriptor
+ * （`storage.base` / `resourceIdPattern` / `fields` / `class`），消费方不手写 topic、
+ * 不手写字段映射、不手写 refetch。集合定义本身就是「开启订阅」的声明（D3），
+ * 所以这里 `startSync: true`：配置了 feed 就是活表，没有 feed 就退化为
+ * 「读一次 + 显式 `refresh()`」，永不轮询（N1）。
+ */
+export function definePodCollection(descriptor, options) {
+    assertDescriptorTableAlignment(descriptor, options.table);
+    const document = resolveTableDocument(descriptor, {
+        podUrl: options.podUrl,
+        document: options.document,
+        scope: options.scope,
+    });
+    const pending = createPendingWrites(options.onConflict);
+    let collection;
+    const engine = createPodSync({
+        descriptor,
+        table: options.table,
+        database: options.database,
+        podUrl: options.podUrl,
+        document,
+        feed: options.feed,
+        coalesceMs: options.coalesceMs,
+        confirmRetries: options.confirmRetries,
+        pending,
+        collection: () => collection,
+    });
+    const handlers = createMutationHandlers({
+        descriptor,
+        table: options.table,
+        database: options.database,
+        podUrl: options.podUrl,
+        document,
+        pending,
+        confirm: (key) => engine.confirmPending(key),
+    });
+    const created = createCollection({
+        // 集合 id 由 descriptor 与文档决定：一个表一个文档就是一个集合。
+        id: `pod-collection:${descriptor.uri}:${document}`,
+        // §2.7：键取行标识（`resourceIdPattern` 的键 slot），不取 `uniqueBy` ——
+        // 后者是语义唯一键，与存储布局的键 slot 不保证同形（`aiModelDescriptor`：
+        // `uniqueBy: ['id']` 但键 slot 是 `key`）。
+        getKey: (row) => row.id,
+        // §3.2：diff 的产物是整行投影，`partial` 表达不了「谓词被移除」。
+        sync: { sync: engine.sync, rowUpdateMode: 'full' },
+        startSync: true,
+        onInsert: handlers.onInsert,
+        onUpdate: handlers.onUpdate,
+        onDelete: handlers.onDelete,
+    });
+    collection = created;
+    return Object.assign(created, {
+        tableDocument: document,
+        pendingKeys: pending.keys,
+        conflicts: pending.conflicts,
+        refresh: () => engine.refresh(),
+        /**
+         * @internal 同步状态（§1.5 N1 的 `unavailable` / §3.4 的降级）。
+         * 不进 `PodCollection` 接口：宿主能力的接线在下一期（§6.4）。
+         */
+        syncState: () => engine.state(),
+        /** @internal 释放订阅与定时器（宿主 capability 的 `dispose()`，§6.4-6）。 */
+        dispose: () => engine.dispose(),
+        /** @internal 测试钩子：库的 `truncate()`。 */
+        truncateForTest: () => engine.truncate(),
+    });
+}
+export { conditionalDocumentRead, sessionFetchOf } from './read.js';
+export { resolveTableDocument, rowKeyOf, subjectIriForRow, resourceIdForRow } from './layout.js';
+export { coerceFieldValue, descriptorFieldsWithoutColumn, fieldBindings, mapSubjectRows, projectionFieldOrder, tableColumnsWithoutDescriptorField, valueToTerm, writeOnlyFields, } from './mapping.js';
+export { computeDocumentDiff, projectionHash, stripVirtualProps } from './diff.js';
+export function podCollectionInternals(collection) {
+    const internals = collection;
+    if (typeof internals.syncState !== 'function' || typeof internals.dispose !== 'function') {
+        throw new PodCollectionError('collection_not_from_define', 'collection was not created by definePodCollection()');
+    }
+    return internals;
+}

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

@@ -0,0 +1,75 @@
+import type { PodModelDescriptor } from '@undefineds.co/models';
+import type { PodSubjectRow } from './types.js';
+/**
+ * topic 推导与行 IRI ↔ 键（`docs/pod-collections.md` §2.3、§2.7）。
+ *
+ * 只读 descriptor 的 `storage.base` / `storage.resourceIdPattern`：本文件里没有
+ * 任何表清单、字段映射表或布局常量（N2）。三种形状：
+ *
+ * | `storage.base`             | `resourceIdPattern`        | 文档（topic）                      |
+ * |----------------------------|----------------------------|------------------------------------|
+ * | 文档（`…/credentials.ttl`） | `#{id}`                    | base 本身                          |
+ * | 容器（`…/providers/`）      | `{key}.ttl`                | `base + key + '.ttl'`              |
+ * | 容器（`…/providers/`）      | `{isProvidedBy.doc}#{key}` | 行所属 provider 的文档（scope 决定） |
+ *
+ * 第四种形状（`base = '/.data/'` + `{id}`，一行一文档）不在本期范围（§1.2）。
+ */
+export interface PodLayoutScope {
+    provider?: string;
+    instanceId?: string;
+}
+export interface PodLayoutInput {
+    podUrl: string;
+    /** 显式文档（绝对 URL 或相对 podUrl 的路径）。给了就不再推导。 */
+    document?: string;
+    scope?: PodLayoutScope;
+}
+/** 绝对 URL 直接用；否则按 podUrl 解析（相对路径不要求前导 `/`）。 */
+export declare function resolvePodUrl(podUrl: string, value: string): string;
+export declare function templateVariables(pattern: string): string[];
+/** 行键 slot（模式里最后一个模板变量）的名字。 */
+export declare function rowKeyVariable(pattern: string): string;
+/** `storage.base` 本身就是一个文档（最后一段带扩展名），而不是容器。 */
+export declare function isDocumentBase(base: string): boolean;
+/**
+ * 文档（topic）解析。三种形状见文件头；无法机械推导时抛
+ * `layout_document_required`，不猜布局。
+ */
+export declare function resolveTableDocument(descriptor: PodModelDescriptor, input: PodLayoutInput): string;
+/** 文档 URL 相对 podUrl 的 resource id（例如 `settings/credentials.ttl`）。 */
+export declare function documentResourceId(documentUrl: string, podUrl: string): string;
+/** 文档在表 base 下的相对 id（表列 `id` 的文档段），例如 `credentials.ttl`。 */
+export declare function documentKeyOf(descriptor: PodModelDescriptor, documentUrl: string, podUrl: string): string;
+/**
+ * 表列 `id`（base-relative resource id）的值：
+ * `settings/credentials.ttl` + base `/settings/` + `#{id}` → `credentials.ttl#{key}`。
+ * ORM 的 `updateById` / `deleteById` 收的就是这个值。
+ */
+export declare function resourceIdForRow(descriptor: PodModelDescriptor, documentUrl: string, podUrl: string, key: string): string;
+/** 行主语 IRI：文档 + fragment slot（行就是文档时等于文档 URL）。 */
+export declare function subjectIriForRow(descriptor: PodModelDescriptor, documentUrl: string, key: string): string;
+/** 行所属文档（去掉 fragment）。 */
+export declare function documentOfIri(iri: string): string;
+/** 行主语 IRI：drizzle-solid 行上的 `@id` / `uri` / `subject`。 */
+export declare function rowSubjectIriOf(row: PodSubjectRow): string | undefined;
+/** 行 resource id（drizzle-solid 的虚列 `id`）。 */
+export declare function rowResourceIdOf(row: PodSubjectRow): string | undefined;
+/**
+ * 从行上取行键：把 `resourceIdPattern` 编译成正则，最后一个模板变量就是键。
+ * `#{id}` → fragment；`{key}.ttl` → 文件名；`{isProvidedBy.doc}#{key}` → fragment；
+ * `{yyyy}/{MM}/{dd}.ttl#{id}` → fragment。
+ * 与 §2.7 一致：键只取行标识 slot，**不取 `uniqueBy`**。0.2.57 起 credential 的
+ * `uniqueBy` 是真实列 `['id']`（旧值 `['service','providerId','secretType']` 引用了
+ * 不存在的列且不唯一），但两者语义不同：`uniqueBy` 是语义唯一键，键 slot 是存储布局。
+ * 官方 descriptor 已经出现不同形的情形 —— `aiModelDescriptor` 的 `uniqueBy` 也是
+ * `['id']`，而它的键 slot 叫 `key`（`{isProvidedBy.doc}#{key}`），且 `id` 并不是一个
+ * 有谓词列的字段。所以键只能从 `resourceIdPattern` 取。
+ */
+export declare function rowKeyOf(descriptor: PodModelDescriptor, row: PodSubjectRow): string | undefined;
+/**
+ * 模板 → 正则：字面量先切出来再转义，模板变量替换成捕获组（最后一个变量是键）。
+ * 不能「先整体转义再替换变量」—— 那会把变量前的转义反斜杠留在原处，生成非法正则。
+ */
+export declare function compileRowKeyPattern(pattern: string): RegExp;
+/** 行是否属于该文档（一个表 = 一个文档；§2.3、§3.4）。 */
+export declare function rowBelongsToDocument(descriptor: PodModelDescriptor, documentUrl: string, podUrl: string, row: PodSubjectRow): boolean;

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

@@ -0,0 +1,173 @@
+import { PodCollectionError } from './types.js';
+const TEMPLATE_VARIABLE = /\{([^{}]+)\}/gu;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+function normalizePodUrl(podUrl) {
+    return podUrl.endsWith('/') ? podUrl : `${podUrl}/`;
+}
+/** 绝对 URL 直接用；否则按 podUrl 解析（相对路径不要求前导 `/`）。 */
+export function resolvePodUrl(podUrl, value) {
+    if (/^[a-z][a-z0-9+.-]*:/iu.test(value))
+        return value;
+    return new URL(value.replace(/^\/+/u, ''), normalizePodUrl(podUrl)).toString();
+}
+export function templateVariables(pattern) {
+    return [...pattern.matchAll(TEMPLATE_VARIABLE)].map((match) => match[1]);
+}
+/** 行键 slot（模式里最后一个模板变量）的名字。 */
+export function rowKeyVariable(pattern) {
+    const last = templateVariables(pattern).at(-1);
+    if (!last) {
+        throw new PodCollectionError('layout_pattern_without_key', `resourceIdPattern "${pattern}" has no {…} key slot`);
+    }
+    return last;
+}
+function splitOnKeySlot(pattern) {
+    const slot = `{${rowKeyVariable(pattern)}}`;
+    const index = pattern.lastIndexOf(slot);
+    return { head: pattern.slice(0, index), tail: pattern.slice(index + slot.length), slot };
+}
+/** `storage.base` 本身就是一个文档（最后一段带扩展名），而不是容器。 */
+export function isDocumentBase(base) {
+    const lastSegment = base.replace(/\/+$/u, '').split('/').pop() ?? '';
+    return lastSegment.includes('.');
+}
+function baseDirectory(base) {
+    if (base.endsWith('/'))
+        return base;
+    const slash = base.lastIndexOf('/');
+    return slash < 0 ? '/' : base.slice(0, slash + 1);
+}
+/**
+ * 文档（topic）解析。三种形状见文件头；无法机械推导时抛
+ * `layout_document_required`，不猜布局。
+ */
+export function resolveTableDocument(descriptor, input) {
+    const podUrl = normalizePodUrl(input.podUrl);
+    if (input.document)
+        return resolvePodUrl(podUrl, input.document);
+    const base = descriptor.storage.base;
+    const pattern = descriptor.storage.resourceIdPattern;
+    if (!base || !pattern) {
+        throw new PodCollectionError('layout_missing_storage', `descriptor ${descriptor.uri} has no storage.base / resourceIdPattern`);
+    }
+    // 形状 1：base 本身是文档，行是文档里的主语。
+    if (isDocumentBase(base))
+        return resolvePodUrl(podUrl, base);
+    // 形状 2：base 是容器，行键就是文档名（`{key}.ttl`，键 slot 前只有字面量）。
+    const { head, tail } = splitOnKeySlot(pattern);
+    if (!pattern.includes('#') && templateVariables(head).length === 0) {
+        const key = input.scope?.instanceId ?? input.scope?.provider;
+        if (!key) {
+            throw new PodCollectionError('layout_document_required', `descriptor ${descriptor.uri} stores one document per row key (${pattern}); pass document or scope`);
+        }
+        return resolvePodUrl(podUrl, `${base}${head}${key}${tail}`);
+    }
+    // 形状 3：文档由另一个模板变量（如 `{isProvidedBy.doc}`）决定，descriptor 推不出来。
+    throw new PodCollectionError('layout_document_required', `descriptor ${descriptor.uri} stores rows across documents (${base}${pattern}); pass document explicitly`);
+}
+/** 文档 URL 相对 podUrl 的 resource id（例如 `settings/credentials.ttl`）。 */
+export function documentResourceId(documentUrl, podUrl) {
+    const root = normalizePodUrl(podUrl);
+    if (documentUrl.startsWith(root))
+        return documentUrl.slice(root.length);
+    return documentUrl.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/iu, '').replace(/^\/+/u, '');
+}
+/** 文档在表 base 下的相对 id（表列 `id` 的文档段），例如 `credentials.ttl`。 */
+export function documentKeyOf(descriptor, documentUrl, podUrl) {
+    const relative = documentResourceId(documentUrl, podUrl);
+    const baseDir = baseDirectory(descriptor.storage.base).replace(/^\/+/u, '');
+    const key = relative.startsWith(baseDir) ? relative.slice(baseDir.length) : relative;
+    if (!key) {
+        throw new PodCollectionError('layout_document_outside_base', `document ${documentUrl} is not under ${descriptor.storage.base}`);
+    }
+    return key;
+}
+/**
+ * 表列 `id`（base-relative resource id）的值：
+ * `settings/credentials.ttl` + base `/settings/` + `#{id}` → `credentials.ttl#{key}`。
+ * ORM 的 `updateById` / `deleteById` 收的就是这个值。
+ */
+export function resourceIdForRow(descriptor, documentUrl, podUrl, key) {
+    const pattern = descriptor.storage.resourceIdPattern;
+    const documentKey = documentKeyOf(descriptor, documentUrl, podUrl);
+    const { head, tail, slot } = splitOnKeySlot(pattern);
+    if (templateVariables(pattern).length > 1) {
+        throw new PodCollectionError('layout_document_required', `resourceIdPattern "${pattern}" has template variables this layer cannot fill`);
+    }
+    if (pattern.startsWith('#'))
+        return `${documentKey}${pattern.replace(slot, key)}`;
+    return `${head}${key}${tail}`;
+}
+/** 行主语 IRI：文档 + fragment slot（行就是文档时等于文档 URL）。 */
+export function subjectIriForRow(descriptor, documentUrl, key) {
+    return descriptor.storage.resourceIdPattern.includes('#') ? `${documentUrl}#${key}` : documentUrl;
+}
+/** 行所属文档（去掉 fragment）。 */
+export function documentOfIri(iri) {
+    const hash = iri.indexOf('#');
+    return hash < 0 ? iri : iri.slice(0, hash);
+}
+/** 行主语 IRI：drizzle-solid 行上的 `@id` / `uri` / `subject`。 */
+export function rowSubjectIriOf(row) {
+    for (const candidate of [row['@id'], row.uri, row.subject]) {
+        if (typeof candidate === 'string' && candidate.length > 0)
+            return candidate;
+    }
+    return undefined;
+}
+/** 行 resource id（drizzle-solid 的虚列 `id`）。 */
+export function rowResourceIdOf(row) {
+    return typeof row.id === 'string' && row.id.length > 0 ? row.id : undefined;
+}
+/**
+ * 从行上取行键：把 `resourceIdPattern` 编译成正则，最后一个模板变量就是键。
+ * `#{id}` → fragment；`{key}.ttl` → 文件名；`{isProvidedBy.doc}#{key}` → fragment；
+ * `{yyyy}/{MM}/{dd}.ttl#{id}` → fragment。
+ * 与 §2.7 一致：键只取行标识 slot，**不取 `uniqueBy`**。0.2.57 起 credential 的
+ * `uniqueBy` 是真实列 `['id']`（旧值 `['service','providerId','secretType']` 引用了
+ * 不存在的列且不唯一），但两者语义不同：`uniqueBy` 是语义唯一键，键 slot 是存储布局。
+ * 官方 descriptor 已经出现不同形的情形 —— `aiModelDescriptor` 的 `uniqueBy` 也是
+ * `['id']`，而它的键 slot 叫 `key`（`{isProvidedBy.doc}#{key}`），且 `id` 并不是一个
+ * 有谓词列的字段。所以键只能从 `resourceIdPattern` 取。
+ */
+export function rowKeyOf(descriptor, row) {
+    const resourceId = rowResourceIdOf(row);
+    if (!resourceId)
+        return undefined;
+    return compileRowKeyPattern(descriptor.storage.resourceIdPattern).exec(resourceId)?.[1];
+}
+/**
+ * 模板 → 正则：字面量先切出来再转义，模板变量替换成捕获组（最后一个变量是键）。
+ * 不能「先整体转义再替换变量」—— 那会把变量前的转义反斜杠留在原处，生成非法正则。
+ */
+export function compileRowKeyPattern(pattern) {
+    const matches = [...pattern.matchAll(TEMPLATE_VARIABLE)];
+    const last = matches.at(-1);
+    if (!last) {
+        throw new PodCollectionError('layout_pattern_without_key', `resourceIdPattern "${pattern}" has no {…} key slot`);
+    }
+    let source = '^[\\s\\S]*?';
+    let cursor = 0;
+    for (const match of matches) {
+        const index = match.index ?? 0;
+        source += escapeRegExp(pattern.slice(cursor, index));
+        source += match === last ? '([\\s\\S]+)' : '[\\s\\S]*?';
+        cursor = index + match[0].length;
+    }
+    source += `${escapeRegExp(pattern.slice(cursor))}$`;
+    return new RegExp(source, 'u');
+}
+/** 行是否属于该文档（一个表 = 一个文档；§2.3、§3.4）。 */
+export function rowBelongsToDocument(descriptor, documentUrl, podUrl, row) {
+    const document = documentOfIri(documentUrl);
+    const subject = rowSubjectIriOf(row);
+    if (subject)
+        return documentOfIri(subject) === document;
+    const resourceId = rowResourceIdOf(row);
+    if (!resourceId)
+        return false;
+    const documentKey = documentKeyOf(descriptor, documentUrl, podUrl);
+    return documentOfIri(resourceId).endsWith(documentKey);
+}

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

@@ -0,0 +1,78 @@
+import type { AnyPodTable } from '@undefineds.co/drizzle-solid';
+import type { PodModelDescriptor, PodModelFieldDescriptor } from '@undefineds.co/models';
+import type { PodSubjectRow, RowOf } from './types.js';
+/** RDF term（只覆盖本层会产生的两种）。 */
+export interface PodRdfTerm {
+    termType: 'NamedNode' | 'Literal';
+    value: string;
+    datatype?: string;
+}
+export interface PodFieldBinding {
+    field: string;
+    descriptor: PodModelFieldDescriptor;
+    /** 承载该字段的表列；descriptor 声明了但表里没有对应谓词时为 undefined。 */
+    column: string | undefined;
+}
+/** 表列 → 谓词（跳过 `@id` 虚列）。 */
+export declare function tableColumnPredicates(table: AnyPodTable): Map<string, string>;
+/** descriptor 字段 → 承载它的表列（按谓词，不按字段名）。 */
+export declare function fieldBindings(descriptor: PodModelDescriptor, table: AnyPodTable): Map<string, PodFieldBinding>;
+/**
+ * 行标识字段：`resourceIdPattern` 的 `{…}` 键 slot 名（`#{id}` → `id`）。
+ * 它由 drizzle-solid 的虚列 `id` / `@id` 承载，不落在任何谓词列上。
+ */
+export declare function identityFieldOf(descriptor: PodModelDescriptor): string;
+/**
+ * descriptor 声明了、但表里找不到对应谓词的字段（§2.7 的漂移面）。
+ * 行标识字段不算：它由行本身承载（`mapSubjectRows` 用行键填它）。
+ */
+export declare function descriptorFieldsWithoutColumn(descriptor: PodModelDescriptor, table: AnyPodTable): string[];
+/** 表里有、但 descriptor 没声明的列（§2.7 的漂移面）。 */
+export declare function tableColumnsWithoutDescriptorField(descriptor: PodModelDescriptor, table: AnyPodTable): string[];
+/**
+ * 类过滤的显式化（§2.4 边界 2）：行准入以 descriptor 的 `class` 为准，而 drizzle 的
+ * 读把它编译成 `?subject rdf:type <class>`（表 options 的 `type`）。两者必须同源，
+ * 否则读回来的行与 descriptor 不是一套 schema —— 抛错而不是静默接受。
+ */
+export declare function assertDescriptorTableAlignment(descriptor: PodModelDescriptor, table: AnyPodTable): void;
+/**
+ * 只写字段（`secret: true`）：**写入可以带、读取永远读不回**。
+ *
+ * §2.1 把投影定义为「descriptor 的非 secret 字段」，所以这些字段既不在
+ * `mapSubjectRows()` 的行里，也不可能出现在服务端投影里。这个集合是那条规则的
+ * 唯一来源：读写两侧（`mapSubjectRows()` 与 §4.2 的确认协议）都从它取，避免
+ * 「哪边算 secret」出现第二份判断。
+ *
+ * 特别注意它与「descriptor 声明了但表里没有列」的字段（§2.7 的漂移面）不是一回事：
+ * 后者是**可读**字段，只是当前不可投影，语义上仍要求出现在服务端行里。
+ */
+export declare function writeOnlyFields(descriptor: PodModelDescriptor): ReadonlySet<string>;
+/**
+ * 投影后的字段顺序：按谓词排序（§3.2 的投影哈希要求确定性，与字段声明顺序无关）。
+ */
+export declare function projectionFieldOrder(descriptor: PodModelDescriptor): string[];
+/** 值 → 行字段值；同时接受 drizzle-solid 已解码的值与 RDF term（§2.4）。 */
+export declare function coerceFieldValue(field: PodModelFieldDescriptor, input: unknown): unknown;
+/** 值 → RDF term（§2.4；datatype 规则见文件头）。 */
+export declare function valueToTerm(field: PodModelFieldDescriptor, value: unknown): PodRdfTerm | undefined;
+/** array 字段：每个元素一个 term（每元素一条三元组，§2.4）。 */
+export declare function valuesToTerms(field: PodModelFieldDescriptor, value: unknown): PodRdfTerm[];
+/**
+ * 主语行 → 集合行（`RowOf<D>`）：只投影 descriptor 的非 `secret` 字段，
+ * `secret: true` 的字段默认不出现在行里（§2.1）。文档归属由读原语（`read.ts`）
+ * 决定，这里只做投影与键提取。
+ */
+export declare function mapSubjectRows<D extends PodModelDescriptor>(descriptor: D, table: AnyPodTable, subjects: readonly PodSubjectRow[]): RowOf<D>[];
+/**
+ * 集合行 → drizzle 写负载（列名 → 值），供 `insert().values()` / `updateById()`。
+ * `array + uri` 字段由调用方走 `writeField()` 的 PATCH 旁路，不进 ORM（§4.1）。
+ * 返回的负载总是包含行标识列 `id`（表列 `id` 是 base-relative resource id）。
+ */
+export declare function descriptorRowToColumnValues(descriptor: PodModelDescriptor, table: AnyPodTable, row: Record<string, unknown>, options: {
+    resourceId: string;
+    includeField?: (field: string) => boolean;
+}): Record<string, unknown>;
+/** 该字段是否走 §4.1 的 PATCH 旁路：`array: true` + `type: 'uri'`。 */
+export declare function isUriArrayField(field: PodModelFieldDescriptor): boolean;
+/** descriptor 里所有走 PATCH 旁路的字段。 */
+export declare function uriArrayFields(descriptor: PodModelDescriptor): string[];