@undefineds.co/drizzle-solid 0.2.11 → 0.3.0

package/README.md

@@ -1,563 +1,270 @@
-# Drizzle Solid
+# drizzle-solid
 
-一个为Solid Pod设计的类型安全ORM，基于Drizzle ORM构建，让您能够像操作传统数据库一样操作Solid Pod中的RDF数据。
+`drizzle-solid` is a Drizzle-aligned data layer for application-owned data in Solid Pods.
 
-## ✨ 特性
+这次变化的重点不是强迫你把构造函数名字从 `drizzle()` 换成别的东西，而是把语义讲清楚：
 
-- 🔒 **类型安全**: 完整的 TypeScript 支持与严格模式提示
-- 🧭 **Drizzle 对齐**: 沿用 Drizzle ORM 的查询构建器与错误形态，降低迁移成本
-- 🌐 **Solid 实测**: CSS 集成测试覆盖 CRUD、条件组合、聚合与联结场景
-- 🔁 **智能回退**: SQL 查询自动转换为 SPARQL；当 CSS/Comunica 无法处理过滤器或聚合时由方言拉取数据并在内存中回放
-- 🔧 **灵活映射**: 自定义命名空间、谓词和列类型（字符串、数字、布尔、时间、JSON/Object）
+- `table` 更接近 **resource layout / collection definition**
+- `link` 字段更接近 **RDF link / IRI link**
+- 实体最终身份更接近 **IRI / @id**，而不只是本地主键
+- 读取和写入不再默认共享 SQL 式语义
 
-## 🔋 服务器支持
+## Scope
 
-drizzle-solid 支持两种 Solid 服务器：
+Current v1 solves one problem well:
 
-### 能力对比
+- persist application-owned data into Solid Pods with typed schemas
+- keep Pod layout explicit through `base` and `subjectTemplate`
+- make full IRIs part of the public API instead of hiding them behind local-only IDs
+- give Drizzle users a migration-friendly surface without pretending Solid is a SQL database
+- support adjacent Solid flows such as discovery, notifications, and federation where they fit the Pod model
 
-| 能力 | 原生 CSS | xpod |
-|------|----------|------|
-| **基础 CRUD** | ✅ LDP 模式 | ✅ LDP 模式 |
-| **SPARQL SELECT** | ❌ 不支持（Comunica 客户端执行） | ✅ 服务端索引下推 |
-| **SPARQL UPDATE** | ⚠️ 仅 BGP 写入 | ✅ 完整支持 |
-| **条件查询** (where) | Comunica 读文件到内存 | 索引下推（单 Pod） |
-| **聚合函数** (count/sum/avg) | Comunica 读文件到内存 | 索引下推（单 Pod） |
-| **GROUP BY / JOIN** | Comunica 读文件到内存 | 索引下推（单 Pod） |
-| **联邦查询** (跨 Pod) | Comunica 内存处理 | Comunica 内存处理 |
-| **SPARQL 端点** | ❌ 不支持 | ✅ `/-/sparql` Sidecar |
-| **SPARQL 1.1 覆盖率** | - | ~90% |
+Not in v1:
 
-### 原生 Community Solid Server (CSS)
+- full SQL/database feature parity
+- raw SQL as the primary abstraction
+- hiding Pod boundaries, permissions, or network behavior
+- implicit scan-based `updateMany/deleteMany` on backends that do not support set-based mutation
+- universal querying over arbitrary open-world RDF as the main goal
 
-原生 CSS **不支持 SPARQL SELECT**，drizzle-solid 通过 **Comunica 客户端**读取文件到内存后执行查询：
-- ✅ 基本的 CRUD 操作（LDP）
-- ⚠️ 写入仅支持 BGP（Basic Graph Pattern）
-- ⚠️ 所有查询由 Comunica 客户端在内存中执行
+## Constructor Choice
 
-### xpod - 扩展的 CSS (推荐)
+仓库文档与 examples 默认先用 `pod(session, config?)` 讲主线语义：
 
-**xpod** 使用 **QuintStore**（五元组存储，GSPOV）替代文件存储，通过 6 组索引实现查询下推：
+- `pod(session, config?)`
+- `drizzle(session, config?)`
 
-- ✅ **SPARQL SELECT 服务端执行**：查询下推到 QuintStore 索引
-- ✅ **Sidecar API**：`/-/sparql` 端点，权限继承自资源路径
-- ✅ **混合存储**：RDF → QuintStore 索引，非 RDF → 文件系统
-- ⚠️ **联邦查询**：跨 Pod 查询仍需 Comunica 内存处理
-- ⚠️ **SPARQL 覆盖**：约 90% W3C SPARQL 1.1 测试通过
+建议这样理解：
 
-**仓库**：https://github.com/undefinedsco/xpod | **详细对比**：[xpod 特性文档](./docs/xpod-features.md)
+- `pod()` 是语义优先的正式入口，方便把 API 组织成 `collection()` / `entity()` / `bind()`
+- `drizzle()` 是同一运行时上的 Drizzle-aligned 入口，适合迁移或保留 builder/query 代码形状
+- 重要的不是“入口名”，而是下面这些语义：`base`、`subjectTemplate`、`IRI`、exact-target mutation
 
-## 🚀 快速开始
+## Public Surface
 
-### 安装
+当前公开表面可以分成两层：
 
-```bash
-yarn add drizzle-solid
-```
-
-### 基本用法
-
-```typescript
-import { drizzle } from 'drizzle-solid';
-import { podTable, string, int } from 'drizzle-solid';
-import { Session } from '@inrupt/solid-client-authn-node';
-
-// 定义表结构
-const profileTable = podTable('profile', {
-  name: string('name'),
-  email: string('email'),
-  age: int('age')
-}, {
-  // 相对 Pod 根的容器/资源路径，不需要 idp:// 前缀
-  base: '/profiles/',
-  type: 'https://schema.org/Person'
-});
-
-// 自定义 subject 模板示例：按年月目录、文件名是 id，仍指向单独文件
-const logsTable = podTable('logs', {
-  id: string('id').primaryKey(),
-  message: string('message')
-}, {
-  type: 'https://schema.org/DigitalDocument',
-  base: '/logs/',
-  subjectTemplate: '{yyyy}/{MM}/{dd}/{id}.ttl'
-});
-
-// subjectTemplate（选填）：
-// - 作用：控制每条记录主体 URI 的形态，支持占位符 {yyyy}/{MM}/{dd}/{HH}/{mm}/{ss}/{id}。
-// - 推断：未指定时按 base 判断：base 是容器（以 / 结尾且包含表名）→ document 模式；base 是具体文件 → fragment 模式。模板含 #（如 '#{id}'）也强制 fragment；其他模板按 document 处理，可用 {yyyy}/{MM}/{dd}/{id}.ttl 等。
-// - document 模式：每条记录独立文件，URI 形如 .../users/{id}.ttl，SELECT/UPDATE/DELETE 由 Comunica dereference 目标文件后本地求值；适合记录级隔离/按目录分片。
-// - fragment 模式：多条记录共享同一文件，主体是片段（.../file.ttl#{id}），SELECT 同样由 Comunica 拉取该文件求值；适合小表或聚合存放的数据。
-// - 示例：subjectTemplate: '{yyyy}/{MM}/{dd}/{id}.ttl'（document 分日期分片）；subjectTemplate: '#{id}'（fragment，共享文件）。
-
-// 创建数据库连接
-const session = new Session(); // 已认证的session
-const db = drizzle(session);
-
-// 初始化需要使用的表（创建容器、资源并注册 TypeIndex）
-await db.init([profileTable]);
-
-// 查询数据
-const profiles = await db.select().from(profileTable);
-
-// 插入数据
-await db.insert(profileTable).values({
-  name: 'Alice',
-  email: 'alice@example.com',
-  age: 30
-});
-
-// 使用 SPARQL 端点（适用于 xpod）
-const sparqlTable = podTable('posts', {
-  id: string('id').primaryKey(),
-  title: string('title'),
-}, {
-  type: 'https://schema.org/CreativeWork',
-  base: '/data/posts.ttl',                      // 资源路径
-  sparqlEndpoint: '/data/posts.ttl/-/sparql'    // xpod Sidecar 模式端点
-  // 💡 xpod 使用 Sidecar 模式：在资源路径后添加 /-/sparql 后缀
-  //    - 文件资源: /data/posts.ttl/-/sparql
-  //    - 容器: /data/users/-/sparql
-});
-await db.init([sparqlTable]); // 不会创建容器，直接使用端点执行 SPARQL UPDATE/SELECT
-await db.insert(sparqlTable).values({ id: 'post-1', title: 'Hello SPARQL' });
-
-### SPARQL Endpoint 模式兼容性说明 (重要!)
+### Semantic-first surface
 
-当 `podTable` 配置 `sparqlEndpoint` 时，Drizzle Solid 会直接使用该端点执行所有 CRUD 操作。理解其行为模式对于数据一致性至关重要：
+- `pod(session, config?)`
+- `client.bind(schema, options)`
+- `client.collection(table)`
+- `client.entity(table, iri)`
+- `client.sparql(query)`
 
-1.  **Fragment Mode (聚合 Named Graph)**:
-    *   **定义**: 当表的 `base` 指向一个具体资源 URL (例如 `/data/posts.ttl`)，或者 `subjectTemplate` 使用片段 (例如 `'#{id}'`) 时，Drizzle Solid 会将所有数据操作集中在 `base` 对应的单一 Named Graph (`GRAPH <base_url>`) 中。
-    *   **行为**: 在此模式下，LDP 读写与 SPARQL 读写**完全兼容且互操作**。LDP 对 `base` 资源的 PATCH/GET 操作，与 SPARQL 对 `GRAPH <base_url>` 的 DML/SELECT 操作，都作用于相同的数据集，并能互相可见。**这是 SPARQL Endpoint 模式下的推荐用法**。
-    *   **示例**: `base: '/data/posts.ttl'`, `subjectTemplate: '#{id}'`。所有 posts 都存储在 `posts.ttl` 文件对应的 Named Graph 中。
+### Drizzle-aligned surface
 
-2.  **Document Mode (聚合视图，写操作不兼容)**:
-    *   **定义**: 当表的 `base` 指向一个容器 URL (例如 `/data/users/`)，且 `subjectTemplate` 生成文件路径 (例如 `'{id}.ttl'`) 时。
-    *   **读操作 (SELECT)**: SPARQL SELECT 查询指向容器的 `/sparql` 端点时，Community Solid Server (CSS) 会**聚合该容器内所有 LDP 子文件**的数据，形成一个统一的视图。因此，通过 LDP PUT 写入的子文件 (例如 `alice.ttl`)，**可以被 SPARQL SELECT 查询到**。
-    *   **写操作 (DML)**: SPARQL INSERT/UPDATE/DELETE 操作是针对**容器的聚合 Named Graph** (`GRAPH <container_url>`)。这些操作**不会**直接创建、修改或删除 LDP 子文件。
-        *   例如，通过 SPARQL INSERT 写入 `bob`，数据会存在容器 Graph 中，但**不会**创建 `bob.ttl` 文件 (LDP GET `/data/users/bob.ttl` 将返回 404)。
-        *   通过 SPARQL UPDATE `alice`，只会修改容器 Graph 中的 `alice` 数据（SPARQL 视图），而**不会**更新 `alice.ttl` 文件本身 (LDP GET `/data/users/alice.ttl` 将显示旧数据)。
-    *   **结论**: 在 Document Mode 下，SPARQL 读操作可以兼容 LDP 资源（因为聚合），但 **写操作与 LDP 资源的物理文件视图不兼容**。这意味着 LDP 客户端可能无法看到 SPARQL DML 操作的影响，反之亦然。**不建议混合使用 LDP Document Mode 和 SPARQL DML 操作**，除非您明确理解其数据存储的视图差异，并仅利用 SPARQL 作为聚合查询工具。
+- `drizzle(session, config?)`
+- `podTable(name, columns, config)`
+- `solidSchema(...)`
+- `select / insert / update / delete`
+- `db.query.*` read facade
 
-
-```
-
-## 📚 示例教程
-
-我们提供了完整的示例来帮助您快速上手：
-
-### 🏗️ 示例1: 快速开始
+## Install
 
 ```bash
-yarn example:quick
+yarn add @undefineds.co/drizzle-solid drizzle-orm
+# optional, when your app wants the default SPARQL client engine
+yarn add @comunica/query-sparql-solid
 ```
 
-这个示例展示：
-- 如何连接到 Solid Pod 并定义表结构
-- 使用 Drizzle 风格 API 执行插入、查询、更新、删除
-
-### 📖 示例2: 关系查询
-
-```bash
-yarn example:query
-```
-
-这个示例展示：
-- 如何定义表之间的关系
-- 使用 `with` 进行关联查询
-- 嵌套数据的加载方式
-
-### 🛠️ 示例3: 零配置数据发现
-
 ```bash
-yarn example:discovery
+npm install @undefineds.co/drizzle-solid drizzle-orm
+npm install @comunica/query-sparql-solid
 ```
 
-这个示例展示：
-- 如何使用 TypeIndex 自动发现数据位置
-- SAI (Solid Application Interoperability) 数据授权
-- 无需硬编码路径的数据访问
-
-## 📖 详细文档
+`@comunica/query-sparql-solid` is an optional peer dependency.
 
-### 表定义
+Install it in the consuming app when you need built-in SPARQL query execution, LDP-backed query fallback, or direct SPARQL workflows.
 
-```typescript
-import { podTable, string, int, boolean, date, uri, eq, gte, and } from 'drizzle-solid';
+Current public compatibility stance:
 
-const userTable = podTable('users', {
-  name: string('name'),           // foaf:name
-  email: string('email'),         // foaf:mbox
-  age: int('age'),               // foaf:age
-  verified: boolean('verified'),     // 自定义谓词
-  createdAt: date('createdAt'),   // dcterms:created
-  organization: uri('organization')
-    .predicate('https://schema.org/member') // <org> schema:member <person>
-    .inverse()
-}, {
-  // 目标 Turtle 资源，必填，可以是相对 Pod 路径或绝对 URL
-  base: 'data/users.ttl',
-  // 主体类型
-  type: 'https://schema.org/Person',
-  // 可选：注册 TypeIndex（仅在提供 typeIndex 时才会尝试）
-  typeIndex: 'private' // 'public' | 'private' | undefined
-});
+- officially supported: `@comunica/query-sparql-solid` `4.x`
+- not currently in the supported matrix: `3.x`
 
-// 初始化：在 CRUD 前确保容器/资源存在（会按 base 自动创建）
-await db.init([userTable]);
-```
+If another in-process runtime already carries Comunica (for example `xpod`), inject that engine instead of forcing a second copy. See `docs/api/README.md` and `docs/guides/installation.md`.
 
-- 使用 `.inverse()` 可以把列映射为 `<object> predicate <subject>` 方向，适合例如 `<org> schema:member <person>` 这样的反向边；查询/写入都会自动交换 RDF 三元组的主体和宾语。
+## Quick start
 
-### Drizzle 风格查询：`db.query` + `findByIRI`
+仓库里的主线 quick start 默认使用 `pod(session)`，因为它会把 `collection()` / `entity()` / `bind()` 语义直接写在代码里。
 
-将 schema 传入 `drizzle(session, { schema })` 后，可通过 Drizzle 对齐的查询助手调用：
+如果你已有大量 Drizzle 风格代码，`drizzle(session)` 仍然是正式可用入口。
 
 ```ts
-import * as schema from './schema';
-const db = drizzle(session, { schema });
-
-const users = await db.query.users.findMany({
-  where: { verified: true },
-  orderBy: [{ column: schema.users.name, direction: 'asc' }],
-  with: {
-    posts: true // 根据子表 referenceTarget + @id 预加载关联行
-  }
+import {
+  pod,
+  podTable,
+  string,
+  datetime,
+} from '@undefineds.co/drizzle-solid';
+
+const posts = podTable('posts', {
+  id: string('id').primaryKey(),
+  title: string('title').predicate('http://schema.org/headline'),
+  content: string('content').predicate('http://schema.org/text'),
+  createdAt: datetime('createdAt').predicate('http://schema.org/dateCreated'),
+}, {
+  base: 'https://alice.example/data/posts/',
+  subjectTemplate: '{id}.ttl',
+  type: 'http://schema.org/CreativeWork',
 });
 
-// 通过 IRI 查找单条记录（推荐使用 db.findByIri）
-const alice = await db.findByIri(schema.users, 'https://pod.example/data/users.ttl#alice');
-```
-
-- `findMany/findFirst/findById/count` 与 Drizzle ORM 行为一致，复用现有 `select` 管道。
-- `with` 支持基于 `reference(target)` 的引用外键（通过 `@id` 关联），结果会嵌套数组挂在相应键上。
-- `db.findByIri(table, iri)` 可直接接受绝对 IRI 或 fragment（无协议时按 `id` 匹配），推荐使用此方法。
-- TypeIndex 注册策略：仅当表配置了 `typeIndex: 'private' | 'public'` 时才会尝试写入 TypeIndex；未配置则跳过。
-
-### 支持的列类型
-
-Drizzle Solid 完全兼容所有 Drizzle ORM 数据库方言的列类型：
-
-#### 基础类型
-```typescript
-// 字符串类型
-string('name')     // 通用字符串
-text('content')    // 文本内容
-varchar('title')   // 可变长度字符串
-char('code')       // 固定长度字符串
-
-// 数字类型
-int('count')       // MySQL 风格整数
-integer('id')      // PostgreSQL 风格整数
-bigint('large')    // 大整数
-smallint('small')  // 小整数
-tinyint('tiny')    // 微整数 (MySQL)
-mediumint('medium') // 中等整数 (MySQL)
-serial('auto')     // 自增序列
-
-// 浮点数类型（内部映射为 xsd:decimal）
-real('price')      // 实数
-decimal('amount')  // 十进制数
-numeric('value')   // 数值
-float('ratio')     // 单精度浮点
-double('precise')  // 双精度浮点
-
-// 布尔类型
-boolean('active')  // 布尔值
-
-// 日期时间类型
-date('birthday')   // 日期
-datetime('event')  // 日期时间
-timestamp('created') // 时间戳
-
-// JSON 类型
-json('data')       // JSON 数据
-jsonb('config')    // 二进制 JSON (PostgreSQL)
-object('metadata') // 对象类型 (扩展)
-```
-
-### 查询操作
-
-```typescript
-// 查询所有记录
-const users = await db.select().from(userTable);
-
-// 条件查询
-const adults = await db.select()
-  .from(userTable)
-  .where(gte(userTable.age, 18));
-
-// 选择特定字段
-const names = await db.select({ name: userTable.name })
-  .from(userTable);
-
-// 使用条件构建器
-const verifiedAdults = await db.select()
-  .from(userTable)
-  .where(and(gte(userTable.age, 18), eq(userTable.verified, true)));
-
-// 排序、分页查询
-const recentUsers = await db.select()
-  .from(userTable)
-  .orderBy(userTable.createdAt, 'desc') // 默认升序，可显式指定 'desc'
-  .limit(10)  // 取前 10 条
-  .offset(10); // 跳过前 10 条，实现分页
-
-// DISTINCT 查询，去重后返回唯一记录
-const uniqueEmails = await db.select({ email: userTable.email })
-  .from(userTable)
-  .distinct();
-```
-
-### 聚合查询
-
-```typescript
-import { count, max } from 'drizzle-solid';
-
-const stats = await db
-  .select({
-    totalUsers: count(),
-    oldestAge: max(userTable.age)
-  })
-  .from(userTable)
-  .where(gte(userTable.age, 18));
-
-console.log(stats[0]);
-// { totalUsers: 42, oldestAge: 63 }
-```
-
-> 当前聚合支持 `count/sum/avg/min/max`，由客户端在内存中计算，选择列表需全部为聚合字段；`JOIN` 与 `GROUP BY` 亦已通过客户端回放实现（在 CSS 升级至最新 Comunica 前仍保留此策略）。
+const client = pod(session);
+await client.init(posts);
 
-### 插入数据
+const postsCollection = client.collection(posts);
 
-```typescript
-// 插入单条记录
-await db.insert(userTable).values({
-  name: 'Bob',
-  email: 'bob@example.com',
-  age: 25
+const created = await postsCollection.create({
+  id: 'post-1',
+  title: 'Hello Solid',
+  content: 'Stored as RDF in a Pod document.',
+  createdAt: new Date(),
 });
 
-// 批量插入
-await db.insert(userTable).values([
-  { name: 'Alice', email: 'alice@example.com', age: 30 },
-  { name: 'Charlie', email: 'charlie@example.com', age: 35 }
-]);
-```
-
-### 更新数据
-
-```typescript
-await db.update(userTable)
-  .set({ age: 26 })
-  .where(eq(userTable.name, 'Bob'));
-```
-
-### 删除数据
-
-```typescript
-await db.delete(userTable)
-  .where(eq(userTable.name, 'Bob'));
-```
-
-## 🔍 数据发现与零配置访问 (Data Discovery & Interoperability)
-
-Drizzle Solid 实现了 Solid 的 **TypeIndex** 和 **SAI (Application Interoperability)** 规范，这意味着您**不需要**硬编码数据的具体路径（`base`）。只要定义好 RDF 类型，Drizzle 就会自动帮您找到数据，无论它是在您自己的 Pod 里，还是别人通过 SAI 授权给您的。
-
-### 核心概念
-
-- **TypeIndex**: 您的“个人数据索引”，记录了“我的笔记在哪里”、“我的联系人在哪里”。适合单用户场景。
-- **SAI Discovery**: 一种更高级的发现机制，用于发现**跨 Pod** 共享的数据（例如 Alice 分享给 Bob 的聊天室）。适合社交、协作场景。
-
-### 如何启用自动发现？
-
-只需在定义表时，移除 `base` 属性，并设置 `typeIndex: 'private'`（或 `'public'`）：
+const first = await postsCollection.first({
+  where: { id: 'post-1' },
+});
 
-```typescript
-const messageTable = podTable('message', {
-  id: id(),
-  content: string('content').predicate('http://schema.org/text'),
-}, {
-  type: 'http://schema.org/Message',
-  typeIndex: 'private' // ✨ 开启自动发现魔法
+const postIri = created?.['@id'] ?? postsCollection.iriFor({
+  id: 'post-1',
+  title: 'Hello Solid',
+  content: 'Stored as RDF in a Pod document.',
+  createdAt: new Date(),
 });
 
-// 当您执行查询时，Drizzle 会自动：
-// 1. 查您的 Private TypeIndex
-// 2. 如果没找到，查 SAI Agent Registry (查看是否有授权给您的数据)
-// 3. 找到数据位置后，自动定向查询
-const messages = await db.select().from(messageTable);
+const post = client.entity(posts, postIri);
+await post.update({ title: 'Updated title' });
+await post.delete();
 ```
 
-### 跨 Pod 聊天应用示例 (SAI Chat)
+> 如果你保持 `drizzle(session)` 作为入口，语义并不会变：`base`、`subjectTemplate`、`IRI`、精确写目标这些约束仍然完全成立。
 
-这是一个展示如何利用 SAI 发现机制构建“零配置”聊天应用的完整示例。Bob 不需要知道 Alice 的聊天室 URL，只要 Alice 授权了，Bob 的应用就能自动发现并加入聊天。
+## Reusable schema + runtime binding
 
-> 查看完整可运行代码：[`examples/04-sai-chat.ts`](examples/04-sai-chat.ts)
+Use `solidSchema(...)` when you want to separate the reusable data shape from where that data lives in a Pod.
 
-```typescript
-// 1. 定义通用的消息表（不绑定具体路径）
-const messageTable = podTable('message', {
-  id: id(),
-  content: string('content').predicate('http://schema.org/text'),
-  author: uri('author').predicate('http://schema.org/author'),
-  createdAt: datetime('createdAt').predicate('http://schema.org/dateCreated')
-}, {
-  type: 'http://schema.org/Message',
-  typeIndex: 'private', // 启用发现
-  autoRegister: false   // 对于访客 Bob，不仅不需要注册，而且不能注册到自己的 TypeIndex
-});
+如果你使用 `pod()` façade：
 
-// 2. Alice (房主) 初始化聊天室
-// Alice 需要明确指定存储位置 (base)
-const aliceChatTable = podTable('message', { ...messageTable.columns }, {
-    ...messageTable.config,
-    base: 'https://alice.pod/data/chat/room.ttl',
-    subjectTemplate: '#{id}' // 强制单文件存储模式
+```ts
+const client = pod(session);
+const profileTable = client.bind(profileSchema, {
+  base: 'https://alice.example/profile/card',
 });
-await db.insert(aliceChatTable).values({ ... });
-
-// ... (Alice 通过 SAI 授权给 Bob，此处省略 SAI 注册代码) ...
-
-// 3. Bob (访客) 发现并回复
-// Bob 初始化 Drizzle 时，完全不需要知道 room.ttl 的地址
-const bobDb = drizzle(bobSession);
+```
 
-// 读取：自动发现 Alice 分享的数据
-const messages = await bobDb.select().from(messageTable);
-console.log(messages); // 包含 Alice 的消息
+如果你保持 `drizzle()` 入口：
 
-// 写入：自动向发现的地址写入回复
-await bobDb.insert(messageTable).values({
-    content: 'Hi Alice! I found your chat room!',
-    author: bobSession.info.webId
+```ts
+const db = drizzle(session);
+const profileTable = db.createTable(profileSchema, {
+  base: 'https://alice.example/profile/card',
 });
 ```
 
-### Discovery 策略
+## Identity and placement
 
-Drizzle Solid 使用组合策略 (`CompositeDiscovery`)：
-1.  **TypeIndex 优先**：检查用户的 `privateTypeIndex.ttl` 和 `publicTypeIndex.ttl`。
-2.  **SAI 后备**：如果 TypeIndex 未命中，检查用户的 Profile -> RegistrySet -> Agent Registry，寻找匹配当前 ClientID 的 Data Grant。
+`subjectTemplate` defines how application identity maps onto Pod resources.
 
-这种设计确保了既能兼容旧的 Solid 应用（基于 TypeIndex），又能支持未来的互操作性规范（SAI）。
+Common patterns:
 
-架构说明见 `docs/guides/architecture.md`。
+- `#{id}`: many entities inside one document
+- `{id}.ttl`: one document per entity
+- `{id}.ttl#it`: one document per entity with stable in-document fragment
+- `{chatId}/messages.ttl#{id}`: multi-variable layouts and partitioned resources
 
-## ✅ 当前 SQL 支持范围
+这不是命名细节，而是持久化语义本身。
 
-- 已实现：`select/insert/update/delete`、Drizzle 风格的 `where` 条件构建器（`eq/ne/lt/gte/like/inArray/not` 等）、`orderBy`、`limit/offset`、`distinct`、嵌套布尔组合，以及 `count/sum/avg/min/max` 聚合、`leftJoin/innerJoin` 和 `GROUP BY`。
-- 运行策略：
-  - **xpod + 单 Pod**：查询下推到 QuintStore 索引执行
-  - **原生 CSS / 联邦查询**：Comunica 将数据读入内存后执行
-- 未实现：`rightJoin`/`fullJoin`（待评估 xpod 支持情况）
-- 未覆盖：`HAVING`、窗口函数、`UNION/UNION ALL`、子查询与跨容器联结；如需这些能力，请暂时改用手写 SPARQL 或拆分查询。
+## Exact-target mutation semantics
 
-## 🗺️ Roadmap
+Reads and writes do not intentionally behave the same way.
 
-- **`rightJoin`/`fullJoin` 支持**: 待评估 xpod SPARQL 能力后实现，详见[设计方案](docs/guides/right-full-join-sparql-design.md)。
+- list / filter reads can stay collection-oriented
+- writes should prefer exact-target semantics
+- incomplete `where(...)` information should not silently degrade into scan + mutate
+- if a subject can only be resolved by multiple template variables, mutation should use an explicit IRI or provide all required variables
 
-## 🔧 配置
+所以最重要的变化不是“要不要换成 `pod()`”，而是：
 
-### 自定义命名空间
+- 什么时候你只是在做集合读取
+- 什么时候你已经需要一个确定的实体目标
 
-Drizzle Solid 不再内置 vocab 常量，请从 RDF vocab 库（例如 `@inrupt/vocab-common-rdf`）导入需要的术语；若需要扩展缺失字段，可使用 `extendNamespace`：
+## Server support
 
-```typescript
-import { podTable, string, extendNamespace } from 'drizzle-solid';
-import { SCHEMA_INRUPT as SCHEMA } from '@inrupt/vocab-common-rdf';
+### Capability matrix
 
-const LINQ = extendNamespace(
-  { prefix: 'linq', uri: 'https://linq.dev/ns/' },
-  { favorite: 'profile#favorite' },
-  { namespace: 'https://linq.dev/ns/' }
-);
+| Capability | Community Solid Server | xpod |
+| --- | --- | --- |
+| Basic CRUD | ✅ | ✅ |
+| Document notifications | ✅ | ✅ |
+| Drizzle-style read facade | ✅ | ✅ |
+| SPARQL pushdown | ⚠️ Limited / often client-assisted | ✅ Better in-process support |
+| Filter / aggregation pushdown | ❌ Mostly fallback execution | ✅ Better server-side support |
+| Federated queries | ⚠️ Client-side federation | ⚠️ Client-side federation |
+| In-process local runtime | ⚠️ External setup | ✅ via `@undefineds.co/xpod` |
 
-const customTable = podTable('custom', {
-  title: string('title').predicate(`${SCHEMA.NAMESPACE}title`),
-  favorite: string('favorite').predicate(LINQ.favorite)
-}, {
-  base: 'idp:///custom/index.ttl', // 目标资源
-  type: `${SCHEMA.NAMESPACE}CreativeWork`,
-  namespace: LINQ
-});
-```
+If `xpod` already ships its own Comunica stack, `drizzle-solid` can reuse that copy instead of requiring another app-level install.
 
-### 认证配置
+## Verified examples
 
-```typescript
-import { Session } from '@inrupt/solid-client-authn-node';
+The canonical examples in `examples/` are part of the real integration verification flow:
 
-const session = new Session();
-await session.login({
-  oidcIssuer: 'https://solidcommunity.net',
-  redirectUrl: 'http://localhost:3000/callback',
-  clientName: 'My Solid App'
-});
+- `examples/01-quick-start.ts`
+- `examples/02-relational-query.ts`
+- `examples/03-zero-config-discovery.ts`
+- `examples/04-notifications.ts`
+- `examples/05-data-discovery.ts`
+- `examples/06-federated-query.ts`
+- `examples/07-hooks-and-profile.ts`
+- `examples/08-iri-based-operations.ts`
+- `examples/08-schema-inheritance.ts`
+- `examples/09-multi-variable-templates.ts`
 
-const db = drizzle(session);
-```
+See `examples/manifest.json` and `tests/integration/css/examples-verification.test.ts`.
 
-### `base` / `@id` / `id` 与 Pod 根的关系
+## Migration
 
-- `podUrl`（Pod 根）由 WebID 推导，所有相对路径都基于它解析。
-- `base` 是表的目标 Turtle 资源（必填），可为相对路径或绝对 URL。示例：`base: '/data/contacts.ttl'` → `https://pod.example/data/contacts.ttl`。
-- 写入：
-  - 提供 `@id` 则直接作为 subject；
-  - 提供 `id`（或库自动生成）则 subject 形如 `base#<id>`（或按表的 subject 模板选择 `#`/`/`）。
-- 查询：
-  - `where({ '@id': 'https://…#foo' })` 精确匹配该 subject；
-  - `where({ id: 'foo' })` 匹配 fragment 为 `foo` 且落在该表 `base` 下的 subject。
-- `base` 同时决定存储地址（PUT/PATCH 目标）和 subject 生成；`podUrl` 只负责解析相对的 `base`。
+If you already know `drizzle-orm`, start here:
 
-## 🏗️ 架构
+- `docs/guides/migrating-from-drizzle-orm.md`
 
-Drizzle Solid基于以下组件构建：
+那份指南重点解释的是：
 
-- **PodDialect**: Solid Pod的Drizzle方言实现
-- **SPARQL转换器**: 将Drizzle查询转换为SPARQL
-- **Comunica执行器**: 执行SPARQL查询
-- **类型系统**: 完整的TypeScript类型支持
+- `table/row` → `resource/document/entity/IRI`
+- `link` / relation fields → RDF link / IRI link
+- `where`-style mutation → exact-target mutation
+- `toSQL()` / raw SQL 主心智 → `toSPARQL()` / SPARQL 主心智
 
-### Comunica CRUD 流程
+而不是要求你第一步先改掉构造函数名。
 
-- 查询会经过 AST → SPARQL 转换；若 Comunica 无法执行带过滤器/聚合的 `UPDATE`/`DELETE`，方言会先通过 `SELECT` 拉取命中的 subject，再以 PATCH 方式回写，实现与 SQL 行级操作一致的语义。
-- `PodDialect` 会自动推导目标容器与 `.ttl` 资源文件路径，必要时发送 `HEAD`/`PUT` 请求确保容器和资源已经存在，再交由 Comunica 处理数据修改。
-- 插入会预先读取现有资源以检测重复 subject，避免重复写入；删除或更新只针对匹配的 subject 生成最小化补丁。
-- 对于 `JOIN`、`GROUP BY` 与聚合，选取的数据仍由 SPARQL 拉取，但结果会在内存中组合或聚合，直到 CSS 升级到支持完整 SPARQL 1.1 为止。
+## Documentation map
 
-## 🤝 贡献
+- `docs/api/README.md` — current public API and constructor positioning
+- `docs/guides/installation.md` — installation and SPARQL engine setup
+- `docs/guides/migrating-from-drizzle-orm.md` — migration guide for Drizzle users
+- `examples/README.md` — curated runnable examples
+- `docs/guides/data-discovery.md` — discovery workflows
+- `docs/guides/notifications.md` — notification flows
+- `docs/xpod-features.md` — xpod runtime notes
+- `ACTION-PLAN.md` — parity and implementation plan
 
-欢迎贡献代码！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解测试要求、提交流程与验证内容。
+## Contributing
 
-在提交 PR 之前，请同步运行完整的 CSS 集成测试（覆盖 CRUD、TypeIndex 等场景）：
+Before pushing:
 
 ```bash
-SOLID_ENABLE_REAL_TESTS=true npx vitest run tests/integration/css --runInBand
+yarn build
+yarn lint
+SOLID_ENABLE_REAL_TESTS=true SOLID_SERIAL_TESTS=true yarn vitest --run --silent
 ```
 
-> `SOLID_ENABLE_REAL_TESTS=true` 会启用真实 Pod，`--runInBand` 保证所有 suite 共用一个会话并顺序执行，避免对 OIDC 服务造成并发压力。
-
-## 📄 许可证
-
-MIT License - 查看[LICENSE](LICENSE)文件了解详情。
-
-## 🔗 相关链接
-
-- [Drizzle ORM](https://orm.drizzle.team/)
-- [Solid Project](https://solidproject.org/)
-- [Community Solid Server](https://github.com/CommunitySolidServer/CommunitySolidServer)
-- [Inrupt Solid Client](https://github.com/inrupt/solid-client-js)
-
-
-## 📞 支持
+Examples must remain runnable and verified.
 
-如果遇到问题，可先查阅：
+## License
 
-1. `docs/quick-start-local.md` 获取本地 CSS 启动与疑难解答
-2. `examples/README.md` 了解脚本入口与运行方式
-3. [Issue 列表](https://github.com/undefinedsco/drizzle-solid/issues) 提交复现步骤与日志
+MIT
 
----
+## Related links
 
-**开始您的 Solid 数据之旅！** 🚀
+- GitHub: https://github.com/undefinedsco/drizzle-solid
+- npm: https://www.npmjs.com/package/@undefineds.co/drizzle-solid
+- xpod: https://github.com/undefinedsco/xpod