@undefineds.co/xpod 0.4.11 → 0.4.12

package/node_modules/@undefineds.co/models/dist/schema.d.ts

@@ -321,6 +321,7 @@ export declare const solidResources: {
         id: import("@undefineds.co/drizzle-solid/dist/core/schema").PodStringColumn<false, false>;
         provider: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"uri", null, false, false>;
         authMode: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, true>;
+        offeringId: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, false>;
         service: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, true, true>;
         status: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, true, true>;
         apiKey: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, false>;
@@ -352,6 +353,7 @@ export declare const solidResources: {
         oauthExpiresAt: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"datetime", null, false, false>;
         projectId: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, false>;
         organizationId: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, false>;
+        metadata: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"json", null, false, false>;
     }>>;
     aiProviderResource: import("@undefineds.co/drizzle-solid/dist/core/schema").PodTableWithColumns<import("@undefineds.co/drizzle-solid/dist/core/schema").ResolvedColumns<{
         id: import("@undefineds.co/drizzle-solid/dist/core/schema").PodStringColumn<false, false>;
@@ -1049,6 +1051,7 @@ export declare const solidSchema: {
         id: import("@undefineds.co/drizzle-solid/dist/core/schema").PodStringColumn<false, false>;
         provider: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"uri", null, false, false>;
         authMode: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, true>;
+        offeringId: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, false>;
         service: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, true, true>;
         status: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, true, true>;
         apiKey: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, false>;
@@ -1080,6 +1083,7 @@ export declare const solidSchema: {
         oauthExpiresAt: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"datetime", null, false, false>;
         projectId: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, false>;
         organizationId: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"string", null, false, false>;
+        metadata: import("@undefineds.co/drizzle-solid/dist/core/schema").ColumnBuilder<"json", null, false, false>;
     }>>;
     aiProviderTable: import("@undefineds.co/drizzle-solid/dist/core/schema").PodTableWithColumns<import("@undefineds.co/drizzle-solid/dist/core/schema").ResolvedColumns<{
         id: import("@undefineds.co/drizzle-solid/dist/core/schema").PodStringColumn<false, false>;

package/node_modules/@undefineds.co/models/dist/session/index.d.ts

@@ -1 +1 @@
-export { sessionResource, sessionTable, buildRuntimeSessionIri, extractSessionIdFromSessionRef, extractRuntimeSessionId, type SessionStatus, type SessionRow, type SessionInsert, type SessionUpdate, } from './session.schema';
+export { sessionResource, sessionTable, buildRuntimeSessionIri, extractSessionIdFromSessionRef, extractRuntimeSessionId, type SessionStatus, type SessionRow, type SessionInsert, type SessionUpdate, } from './session.schema.js';

package/node_modules/@undefineds.co/models/dist/settings/index.d.ts

@@ -1 +1 @@
-export { settingsResource, settingsTable, SETTING_KEYS, type SettingKey, type SettingsRow, type SettingsInsert, type SettingsUpdate } from "./settings.schema";
+export { settingsResource, settingsTable, SETTING_KEYS, type SettingKey, type SettingsRow, type SettingsInsert, type SettingsUpdate } from "./settings.schema.js";

package/node_modules/@undefineds.co/models/dist/sidecar/persistence-mapping.d.ts

@@ -1,8 +1,8 @@
-import type { ApprovalInsert, ApprovalUpdate } from '../approval.schema';
-import type { AuditInsert } from '../audit.schema';
-import type { GrantInsert } from '../grant.schema';
-import type { InboxNotificationInsert } from '../inbox-notification.schema';
-import type { ToolCallEvent, InboxApprovalEvent, SessionStateEvent } from './sidecar-events';
+import type { ApprovalInsert, ApprovalUpdate } from '../approval.schema.js';
+import type { AuditInsert } from '../audit.schema.js';
+import type { GrantInsert } from '../grant.schema.js';
+import type { InboxNotificationInsert } from '../inbox-notification.schema.js';
+import type { ToolCallEvent, InboxApprovalEvent, SessionStateEvent } from './sidecar-events.js';
 export type ChatSessionProjection = {
     chat: string;
     sessionStatus: 'active' | 'paused' | 'completed' | 'error';

package/node_modules/@undefineds.co/models/dist/thread.repository.d.ts

@@ -1,5 +1,5 @@
-import { definePodRepository } from './repository';
-import { threadResource, type ThreadRow, type ThreadInsert, type ThreadUpdate } from './thread.schema';
+import { definePodRepository } from './repository.js';
+import { threadResource, type ThreadRow, type ThreadInsert, type ThreadUpdate } from './thread.schema.js';
 export interface ChatThreadTarget extends Record<string, unknown> {
     parent: string;
     id?: string;

package/node_modules/@undefineds.co/models/dist/types/message-block.d.ts

@@ -1,4 +1,4 @@
-import type { ToolApprovalStatus, ToolCallStatus, TaskProgressStepStatus } from './collaboration-blocks';
+import type { ToolApprovalStatus, ToolCallStatus, TaskProgressStepStatus } from './collaboration-blocks.js';
 /**
  * Message Block Types - 基于 Cherry Studio 的 block-based 消息系统
  *

package/node_modules/@undefineds.co/models/dist/vocab/_namespaces.d.ts

@@ -1 +1 @@
-export * from '../namespaces';
+export * from '../namespaces.js';

package/node_modules/@undefineds.co/models/dist/vocab/index.d.ts

@@ -1,10 +1,10 @@
-export * from './_namespaces';
-export * from './chat.vocab';
-export * from './message.vocab';
-export * from './contact.vocab';
-export * from './thread.vocab';
-export * from './session.vocab';
-export * from './workflow.vocab';
-export * from './capture.vocab';
-export * from './sidecar.vocab';
-export * from './reader-materialization.vocab';
+export * from './_namespaces.js';
+export * from './chat.vocab.js';
+export * from './message.vocab.js';
+export * from './contact.vocab.js';
+export * from './thread.vocab.js';
+export * from './session.vocab.js';
+export * from './workflow.vocab.js';
+export * from './capture.vocab.js';
+export * from './sidecar.vocab.js';
+export * from './reader-materialization.vocab.js';

package/node_modules/@undefineds.co/models/dist/vocab/sidecar.vocab.d.ts

@@ -82,6 +82,7 @@ export declare const GrantVocab: {
     readonly onBehalfOf: string;
     readonly createdAt: string;
     readonly revokedAt: string;
+    readonly disabledAt: string;
 };
 /**
  * Legacy predicates written by @undefineds.co/models <= 0.2.33.

package/node_modules/@undefineds.co/models/dist/vocab/sidecar.vocab.js

@@ -83,6 +83,7 @@ export const GrantVocab = {
     onBehalfOf: UDFS.onBehalfOf,
     createdAt: DCTerms.created,
     revokedAt: UDFS.revokedAt,
+    disabledAt: UDFS.disabledAt,
 };
 /**
  * Legacy predicates written by @undefineds.co/models <= 0.2.33.

package/node_modules/@undefineds.co/models/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@undefineds.co/models",
-  "version": "0.2.55",
+  "version": "0.2.59",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -95,7 +95,9 @@
     "skills:pack": "yarn skills:check && node scripts/pack-skills.mjs",
     "sync:discovery:vercel": "node --experimental-strip-types scripts/sync-discovery-vercel.ts",
     "test": "vitest run",
-    "test:ci": "vitest run tests/ai-config.test.ts tests/ai-runtime-repository.test.ts tests/ai-runtime-schema.test.ts tests/ai-gateway-schema.test.ts tests/chat-project.test.ts tests/client.test.ts tests/contracts-chat-contact.contract.test.ts tests/discovery-vercel.test.ts tests/discovery.test.ts tests/issue-schema.test.ts tests/message-repository.test.ts tests/profile.test.ts tests/protocol-metadata.test.ts tests/repository.test.ts tests/resource-utils.test.ts tests/session-schema.test.ts tests/sidecar-events.contract.test.ts tests/resource-schema.test.ts tests/resource-id-defaults.test.ts tests/pod-storage-descriptor.test.ts tests/capture-schema.test.ts tests/udfs-cli.test.ts",
+    "test:types": "tsc -p tsconfig.types.json",
+    "test:dist-types": "node scripts/check-dist-types.mjs",
+    "test:ci": "tsc -p tsconfig.types.json && node scripts/check-dist-types.mjs && vitest run tests/ai-config.test.ts tests/ai-runtime-repository.test.ts tests/ai-runtime-schema.test.ts tests/ai-gateway-schema.test.ts tests/chat-project.test.ts tests/client.test.ts tests/contracts-chat-contact.contract.test.ts tests/discovery-vercel.test.ts tests/discovery.test.ts tests/issue-schema.test.ts tests/message-repository.test.ts tests/profile.test.ts tests/protocol-metadata.test.ts tests/repository.test.ts tests/resource-utils.test.ts tests/session-schema.test.ts tests/sidecar-events.contract.test.ts tests/resource-schema.test.ts tests/resource-id-defaults.test.ts tests/pod-storage-descriptor.test.ts tests/pod-storage-descriptor.types.test.ts tests/capture-schema.test.ts tests/udfs-cli.test.ts",
     "test:pod": "dotenv -e ../linx-models/.env -- vitest run tests/pod.integration.test.ts"
   },
   "dependencies": {

package/node_modules/@undefineds.co/pod-collections/README.md

@@ -0,0 +1,71 @@
+# @undefineds.co/pod-collections
+
+声明式 **Pod 表集合** adapter：一个 Pod 表（同一 RDF 文档内的一类主语）用一条声明描述，
+消费方拿到的是活数据 —— 按 key 增量更新、带乐观写入与回滚。
+
+设计权威：[`docs/pod-collections.md`](../../docs/pod-collections.md)（§2 声明、§3 同步算法、
+§4 乐观契约、§8 分期）。本包是那份设计的 P1 落地。
+
+```ts
+import { credentialDescriptor, credentialResource } from '@undefineds.co/models';
+import { definePodCollection } from '@undefineds.co/pod-collections';
+
+const credentials = definePodCollection(credentialDescriptor, {
+  table: credentialResource,
+  database,
+  podUrl,
+  feed: solidNotifications, // 宿主注入的脏信号能力（结构上满足 PodDocumentFeed）
+});
+
+credentials.tableDocument; // `${podUrl}settings/credentials.ttl`（由 storage.base 推导）
+await credentials.preload();
+const row = credentials.get('openai-1'); // RowOf<typeof credentialDescriptor>
+await credentials.update('openai-1', (draft) => { draft.label = 'Renamed'; }).isPersisted.promise;
+```
+
+## 定位（做什么）
+
+- **schema 只来自 models 的 descriptor**：`storage.base` / `resourceIdPattern` 推导文档（topic），
+  `fields[*].predicate` 决定字段落在哪一列，`class` 决定行准入。本包不写表清单、不写字段映射表、
+  不写布局常量（守卫测试 `test/guards.test.ts` 会失败）。
+- **读**：`conditionalDocumentRead()` 是唯一读原语，走 drizzle-solid 的 `select()`；脏信号驱动
+  合并窗口（默认 75ms）后的重读 + 投影 diff，只写真正变化的行（`begin/write/commit`），
+  未变的行不产生新对象，组件身份与乐观状态都不被整表替换动摇。
+- **写**：`onInsert` / `onUpdate` / `onDelete` → `insert().values()` / `updateById()` / `deleteById()`；
+  `array: true` + `type: 'uri'` 字段走一次认证过的 SPARQL PATCH（单一入口 `writeField()`），
+  不进 ORM。
+- **乐观**：写入后立刻重读确认，确认条件满足前 handler 不 resolve；服务端拒绝或读不到意图 →
+  抛错，由 TanStack DB 自动回滚；外部冲突 server wins + `conflicts` 标记 + `onConflict` 回调。
+  确认只承诺**读得回来**的东西：只写字段（`secret: true`，不进投影）不参与比对，也不会
+  因为它们判冲突 —— 它们的证据是写入调用本身成功；可读字段一个都不放宽（`§9-7`）。
+- **不轮询**：没有 feed 就只读一次，之后只能显式 `refresh()`，同步状态为 `unavailable`；
+  源码里没有 `setInterval`（守卫测试断言）。
+
+## 边界（不做什么）
+
+- **不做 schema 副本**：字段、谓词、布局、日期分桶、exact id 规则都以 `@undefineds.co/models`
+  为权威；发现 descriptor 与 drizzle 表漂移时本包**报错**而不是就地补一份映射。
+  `@undefineds.co/models@0.2.57` 起 `credentialDescriptor.fields` 与 credential 表的
+  36 个列**逐谓词完全对齐**（0.2.56 曾缺 18 个 by-predicate 表列、多一个无承载列的
+  `secretType`），`uniqueBy` 也改成真实列 `['id']` —— 见 `test/guards.test.ts` 里锁定的
+  双向空集与精确计数（任何未来的漂移都会让那组断言失败）。
+- **不做传输**：`PodDocumentFeed` 只有 `watch(topic, listener)`，是宿主能力的窄端口，
+  不实现 websocket / 订阅生命周期。
+- **不做行级文档表**（`base = '/.data/'` + `{id}`，一行一文档，如 gateway access key）：
+  topic 语义是容器订阅，不在本期（§1.2）。
+- **不做 `loadSubset` 谓词下推**（§8.1 的 P5）。
+- **P1 未覆盖**：宿主能力接线与 pilot 页面（`ui/src/**`、`packages/extension-sdk`、
+  `packages/ai-connections`）属于下一期；`./react` 入口只保证签名与编译。
+
+## 文档 ETag 的结论（P1 第一件事）
+
+drizzle-solid 0.3.24 的读路径**拿不到文档 ETag**，因此 `conditionalDocumentRead()` 恒返回
+`etag: undefined`，同步按设计文档 §8.7-2 的出口降级（每个合并窗口全量读 + 投影 diff，
+零轮询），`metadata.collection` 不写任何伪造的 ETag。证据与请求实测见 `src/read.ts` 文件头
+与 `.test-data/etag-probe/probe.ts`。
+
+## 脚本
+
+- `bun run test`：`vitest run test --config ../../vitest.packages.config.mts`
+- `bun run typecheck`：`tsc --noEmit -p tsconfig.test.json`（含测试与 `RowOf` 的类型级断言）
+- `bun run build`：`tsc -p tsconfig.json` → `dist/`（ESM + 类型声明）

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

@@ -0,0 +1,85 @@
+/**
+ * 投影哈希与三向 diff（§3.2、§3.3）。
+ *
+ * 两个设计点：
+ *
+ * 1. **`metadata.row` 存的是投影哈希，不是 per-row ETag**：一个 Solid 文档只有一个
+ *    ETag，文档内的主语没有独立 validator（§3.2）。哈希按谓词排序的字段顺序计算
+ *    （`mapping.projectionFieldOrder()`），与字段声明顺序无关。
+ * 2. **update 的判定用「上次服务端投影哈希」，insert/delete 的判定用「集合当前呈现
+ *    的行」**，且带未确认写的 key 不参与 insert/delete 判定。理由：乐观写期间
+ *    `collection.state` 里那一行已经是写入后的值，若用呈现行做 update 判定，自回声
+ *    会被判成 0 次写，服务端行永远进不了 syncedData，乐观层一撤就回退到旧值
+ *    （实测 `@tanstack/db@0.9.0` 的 `CollectionStateManager.get()` = 乐观覆盖层 ??
+ *    syncedData；事务完成时乐观层被丢弃）。用 `metadata.row` 的哈希判定 update，
+ *    服务端行会写进 syncedData，而库自己的冗余抑制
+ *    （`dist/esm/collection/state.js:885-905` 的 `isRedundantSync`）保证呈现值不变时
+ *    不产生事件 —— 这才是「无闪烁」的机制。
+ */
+export interface PodProjectionEntry<R extends object> {
+    key: string;
+    row: R;
+}
+export interface PodDocumentDiff<R extends object> {
+    inserts: PodProjectionEntry<R>[];
+    updates: PodProjectionEntry<R>[];
+    deletes: PodProjectionEntry<R>[];
+}
+/**
+ * 去掉 TanStack 的虚属性（`$synced` / `$origin` / `$key` / `$collectionId`）。
+ * 按约定前缀 `$` 判定：`@tanstack/db@0.9.0` 的 `virtual-props.d.ts` 明确「用户 schema
+ * 不应含 `$` 前缀字段，保留给虚属性」，且 `VIRTUAL_PROP_NAMES` 没有从包入口导出。
+ */
+export declare function stripVirtualProps<R extends object>(row: R): R;
+/**
+ * 行的投影哈希：只包含行标识 `id` 与 descriptor 声明的字段（按谓词顺序）、
+ * 递归排序对象键、`undefined` 不参与。
+ *
+ * 两点取舍：
+ * - **不含 `@id`**：主语 IRI 由 `id` + 文档推导（`subjectIriForRow`），带上它只会让
+ *   写入意图（applet 给的行常常没有 `@id`）与服务端投影不可比；身份已经由 `id` 表达。
+ * - **不含 descriptor 之外的键**：集合的行就是 descriptor 投影，多出来的键既不会
+ *   出现在服务端读里，也不该让「未变」被误判成「变了」。
+ */
+export declare function projectionHash<R extends object>(row: R, fieldOrder: readonly string[]): string;
+/**
+ * 服务端投影是否覆盖了写入意图：意图里**每个可读字段**（`@id` 与只写字段除外）都相等。
+ *
+ * 逐字段而不是整行哈希：插入意图通常只带一部分字段，其余由列默认值补齐；
+ * 服务端行也可能带读取侧才有的字段（`@id`）。
+ *
+ * ## 只写字段（`secret: true`）为什么不参与比对
+ *
+ * 确认协议必须只承诺能读回来的东西。`secret: true` 的字段按 §2.1 被排除在投影之外
+ * （`mapping.writeOnlyFields()` 是那条规则的唯一来源），**任何读取路径都不可能返回它们**，
+ * 所以「服务端行里等于意图值」这个条件对它们永远不可能成立：
+ *
+ * - 把它们算进比对 ⇒ 带 secret 的意图永远无法确认（旧缺陷：随后落进
+ *   `hashOf(server) !== beforeHash` 分支，被误判成 `write_conflict`）；
+ * - 反过来把「读不到」当成冲突同样是错的：它不是「服务端值和我们写的不一样」，
+ *   而是「这一层看不见」。
+ *
+ * 选定规则：**只写字段被排除在确认比对之外；它们的唯一证据是写入调用本身成功**
+ * （`mutations.createMutationHandlers()` 只在 `insert/updateById` 或 `array+uri` 的
+ * PATCH resolve 之后才进入确认循环；写入抛错会直接回滚，根本不走到这里），
+ * 集合行则始终是投影行 —— 不假装把 secret 读了回来。
+ *
+ * 措辞边界：这不削弱**可读**字段的确认。意图里出现的每个非 secret 字段（包括
+ * descriptor 声明了、但当前没有承载列因而读不回来的字段，§2.7 的漂移面）仍然逐字段
+ * 比对；任何一个对不上，`reconcilePendingWrites()` 依旧判 `write_conflict`。
+ */
+export declare function projectionCovers<R extends object>(row: R | undefined, intent: R, writeOnly?: ReadonlySet<string>): boolean;
+export interface PodDocumentDiffInput<R extends object> {
+    /** 服务端（文档）当前投影，按行键。 */
+    next: ReadonlyMap<string, R>;
+    /** 集合当前呈现的行键（含乐观覆盖层）。 */
+    presentKeys: Iterable<string>;
+    /** 有未确认本地写的 key：不参与 insert/delete 判定（§3.4、§4.4）。 */
+    pendingKeys: ReadonlySet<string>;
+    /** 上一次服务端投影哈希（`metadata.row`）。 */
+    knownHash: (key: string) => string | undefined;
+    hashOf: (row: R) => string;
+    /** 已从文档消失的行的原值，供 `write({type:'delete', value})` 使用。 */
+    presentRow?: (key: string) => R | undefined;
+}
+export declare function computeDocumentDiff<R extends object>(input: PodDocumentDiffInput<R>): PodDocumentDiff<R>;

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

@@ -0,0 +1,166 @@
+/**
+ * 投影哈希与三向 diff（§3.2、§3.3）。
+ *
+ * 两个设计点：
+ *
+ * 1. **`metadata.row` 存的是投影哈希，不是 per-row ETag**：一个 Solid 文档只有一个
+ *    ETag，文档内的主语没有独立 validator（§3.2）。哈希按谓词排序的字段顺序计算
+ *    （`mapping.projectionFieldOrder()`），与字段声明顺序无关。
+ * 2. **update 的判定用「上次服务端投影哈希」，insert/delete 的判定用「集合当前呈现
+ *    的行」**，且带未确认写的 key 不参与 insert/delete 判定。理由：乐观写期间
+ *    `collection.state` 里那一行已经是写入后的值，若用呈现行做 update 判定，自回声
+ *    会被判成 0 次写，服务端行永远进不了 syncedData，乐观层一撤就回退到旧值
+ *    （实测 `@tanstack/db@0.9.0` 的 `CollectionStateManager.get()` = 乐观覆盖层 ??
+ *    syncedData；事务完成时乐观层被丢弃）。用 `metadata.row` 的哈希判定 update，
+ *    服务端行会写进 syncedData，而库自己的冗余抑制
+ *    （`dist/esm/collection/state.js:885-905` 的 `isRedundantSync`）保证呈现值不变时
+ *    不产生事件 —— 这才是「无闪烁」的机制。
+ */
+/** 默认「没有只写字段」：不传 `writeOnly` 的调用方语义与改动前一致。 */
+const EMPTY_FIELDS = new Set();
+/**
+ * 去掉 TanStack 的虚属性（`$synced` / `$origin` / `$key` / `$collectionId`）。
+ * 按约定前缀 `$` 判定：`@tanstack/db@0.9.0` 的 `virtual-props.d.ts` 明确「用户 schema
+ * 不应含 `$` 前缀字段，保留给虚属性」，且 `VIRTUAL_PROP_NAMES` 没有从包入口导出。
+ */
+export function stripVirtualProps(row) {
+    const source = row;
+    const stripped = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (key.startsWith('$'))
+            continue;
+        stripped[key] = value;
+    }
+    return stripped;
+}
+function canonicalValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map((item) => canonicalValue(item));
+    if (value && typeof value === 'object') {
+        if (value instanceof Set)
+            return [...value].map((item) => canonicalValue(item));
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        return Object.fromEntries(entries.map(([key, item]) => [key, canonicalValue(item)]));
+    }
+    return value;
+}
+/**
+ * 行的投影哈希：只包含行标识 `id` 与 descriptor 声明的字段（按谓词顺序）、
+ * 递归排序对象键、`undefined` 不参与。
+ *
+ * 两点取舍：
+ * - **不含 `@id`**：主语 IRI 由 `id` + 文档推导（`subjectIriForRow`），带上它只会让
+ *   写入意图（applet 给的行常常没有 `@id`）与服务端投影不可比；身份已经由 `id` 表达。
+ * - **不含 descriptor 之外的键**：集合的行就是 descriptor 投影，多出来的键既不会
+ *   出现在服务端读里，也不该让「未变」被误判成「变了」。
+ */
+export function projectionHash(row, fieldOrder) {
+    const source = stripVirtualProps(row);
+    const ordered = {};
+    if (source.id !== undefined)
+        ordered.id = canonicalValue(source.id);
+    for (const field of fieldOrder) {
+        if (source[field] !== undefined)
+            ordered[field] = canonicalValue(source[field]);
+    }
+    return JSON.stringify(ordered);
+}
+function canonicalEquals(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return JSON.stringify(canonicalValue(left)) === JSON.stringify(canonicalValue(right));
+}
+/**
+ * 服务端投影是否覆盖了写入意图：意图里**每个可读字段**（`@id` 与只写字段除外）都相等。
+ *
+ * 逐字段而不是整行哈希：插入意图通常只带一部分字段，其余由列默认值补齐；
+ * 服务端行也可能带读取侧才有的字段（`@id`）。
+ *
+ * ## 只写字段（`secret: true`）为什么不参与比对
+ *
+ * 确认协议必须只承诺能读回来的东西。`secret: true` 的字段按 §2.1 被排除在投影之外
+ * （`mapping.writeOnlyFields()` 是那条规则的唯一来源），**任何读取路径都不可能返回它们**，
+ * 所以「服务端行里等于意图值」这个条件对它们永远不可能成立：
+ *
+ * - 把它们算进比对 ⇒ 带 secret 的意图永远无法确认（旧缺陷：随后落进
+ *   `hashOf(server) !== beforeHash` 分支，被误判成 `write_conflict`）；
+ * - 反过来把「读不到」当成冲突同样是错的：它不是「服务端值和我们写的不一样」，
+ *   而是「这一层看不见」。
+ *
+ * 选定规则：**只写字段被排除在确认比对之外；它们的唯一证据是写入调用本身成功**
+ * （`mutations.createMutationHandlers()` 只在 `insert/updateById` 或 `array+uri` 的
+ * PATCH resolve 之后才进入确认循环；写入抛错会直接回滚，根本不走到这里），
+ * 集合行则始终是投影行 —— 不假装把 secret 读了回来。
+ *
+ * 措辞边界：这不削弱**可读**字段的确认。意图里出现的每个非 secret 字段（包括
+ * descriptor 声明了、但当前没有承载列因而读不回来的字段，§2.7 的漂移面）仍然逐字段
+ * 比对；任何一个对不上，`reconcilePendingWrites()` 依旧判 `write_conflict`。
+ */
+export function projectionCovers(row, intent, writeOnly = EMPTY_FIELDS) {
+    if (row === undefined)
+        return false;
+    const source = stripVirtualProps(row);
+    const target = stripVirtualProps(intent);
+    for (const [key, value] of Object.entries(target)) {
+        if (key === '@id' || value === undefined)
+            continue;
+        if (writeOnly.has(key))
+            continue;
+        if (!canonicalEquals(source[key], value))
+            return false;
+    }
+    return true;
+}
+export function computeDocumentDiff(input) {
+    const present = new Set(input.presentKeys);
+    const inserts = [];
+    const updates = [];
+    const deletes = [];
+    /**
+     * The projection the collection should already hold for `key`.
+     *
+     * Row metadata is the fast path, but a store/library combination without it
+     * would otherwise answer `undefined` for every key and make every sync pass
+     * rewrite every present row - our own echo would replace rows that did not
+     * change. Falling back to the row we last applied answers the same question
+     * ("did this projection change?") from data we always have.
+     */
+    const baselineHash = (key) => {
+        const known = input.knownHash(key);
+        if (known !== undefined)
+            return known;
+        const held = input.presentRow?.(key);
+        return held === undefined ? undefined : input.hashOf(held);
+    };
+    for (const [key, row] of input.next) {
+        if (input.pendingKeys.has(key)) {
+            // 未确认的本地写：服务端行仍要进 syncedData（否则乐观层撤不掉），
+            // 但不能据此判定 insert（那会在乐观行还在时插入同一 key）。
+            if (present.has(key) && baselineHash(key) !== input.hashOf(row)) {
+                updates.push({ key, row });
+            }
+            continue;
+        }
+        if (!present.has(key)) {
+            inserts.push({ key, row });
+            continue;
+        }
+        if (baselineHash(key) !== input.hashOf(row))
+            updates.push({ key, row });
+    }
+    for (const key of present) {
+        if (input.next.has(key))
+            continue;
+        if (input.pendingKeys.has(key))
+            continue;
+        const row = input.presentRow?.(key);
+        if (row === undefined)
+            continue;
+        deletes.push({ key, row });
+    }
+    return { inserts, updates, deletes };
+}

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

@@ -0,0 +1,17 @@
+import type { PodDocumentFeed } from './types.js';
+/**
+ * 变更 feed 端口与无 feed 时的降级（§2.2、§1.5 N1）。
+ *
+ * 传输层不在本包：`PodDocumentFeed` 只是宿主注入的**脏信号**端口，结构上由
+ * `SolidNotificationsCapability` 满足。没有 feed 时**不装任何轮询**：只读一次，
+ * 之后只能显式 `refresh()`，同步状态显式为 `unavailable`。
+ */
+export interface PodFeedSubscription {
+    /** feed 是否真的建立（无 feed / watch 抛错时为 false）。 */
+    readonly available: boolean;
+    unsubscribe(): void;
+}
+/** 订阅文档脏信号；无 feed 或订阅失败时返回不可用订阅，调用方据此标注状态。 */
+export declare function subscribeDocumentFeed(feed: PodDocumentFeed | undefined, topicUrl: string, listener: (signal: {
+    topic: string;
+}) => void): PodFeedSubscription;

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

@@ -0,0 +1,27 @@
+const NOOP_SUBSCRIPTION = {
+    available: false,
+    unsubscribe: () => { },
+};
+/** 订阅文档脏信号；无 feed 或订阅失败时返回不可用订阅，调用方据此标注状态。 */
+export function subscribeDocumentFeed(feed, topicUrl, listener) {
+    if (!feed || typeof feed.watch !== 'function')
+        return NOOP_SUBSCRIPTION;
+    try {
+        const unsubscribe = feed.watch(topicUrl, listener);
+        if (typeof unsubscribe !== 'function')
+            return NOOP_SUBSCRIPTION;
+        let active = true;
+        return {
+            available: true,
+            unsubscribe: () => {
+                if (!active)
+                    return;
+                active = false;
+                unsubscribe();
+            },
+        };
+    }
+    catch {
+        return NOOP_SUBSCRIPTION;
+    }
+}