@undefineds.co/drizzle-solid 0.2.11 → 0.2.13

package/README.md

@@ -1,563 +1,379 @@
-# Drizzle Solid
+# drizzle-solid
 
-一个为Solid Pod设计的类型安全ORM，基于Drizzle ORM构建，让您能够像操作传统数据库一样操作Solid Pod中的RDF数据。
+`drizzle-solid` is a Drizzle-aligned adapter for application-owned data in Solid Pods.
 
-## ✨ 特性
+It helps you define typed models, map them to RDF resources/documents/IRIs, and read or write them with a familiar query builder — without pretending Solid is a relational database.
 
-- 🔒 **类型安全**: 完整的 TypeScript 支持与严格模式提示
-- 🧭 **Drizzle 对齐**: 沿用 Drizzle ORM 的查询构建器与错误形态，降低迁移成本
-- 🌐 **Solid 实测**: CSS 集成测试覆盖 CRUD、条件组合、聚合与联结场景
-- 🔁 **智能回退**: SQL 查询自动转换为 SPARQL；当 CSS/Comunica 无法处理过滤器或聚合时由方言拉取数据并在内存中回放
-- 🔧 **灵活映射**: 自定义命名空间、谓词和列类型（字符串、数字、布尔、时间、JSON/Object）
+The library is intentionally **document-first**, **IRI-native**, **Pod-aware**, and **SPARQL-native**.
 
-## 🔋 服务器支持
+## What it helps with
 
-drizzle-solid 支持两种 Solid 服务器：
+- Defining typed application data for Solid Pods
+- Mapping fields to RDF predicates and resource layouts
+- Using a Drizzle-style CRUD/query builder over Pod data
+- Performing exact entity operations through full IRIs
+- Building discovery, federation, and notification flows on top of Solid-native storage
 
-### 能力对比
+## Design principles
 
-| 能力 | 原生 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% |
+- **Document-first**: model around Solid resources and document boundaries
+- **IRI-native**: treat IRIs as first-class identity, not as an afterthought over local IDs
+- **Pod-aware**: keep resource layout, links, network, and access constraints explicit
+- **Drizzle-aligned**: stay close to Drizzle's builder surface and ergonomics where it makes sense
+- **SPARQL-native**: the native query model is SPARQL/Solid, not SQL emulation
 
-### 原生 Community Solid Server (CSS)
+## What it is
 
-原生 CSS **不支持 SPARQL SELECT**，drizzle-solid 通过 **Comunica 客户端**读取文件到内存后执行查询：
-- ✅ 基本的 CRUD 操作（LDP）
-- ⚠️ 写入仅支持 BGP（Basic Graph Pattern）
-- ⚠️ 所有查询由 Comunica 客户端在内存中执行
+- A typed persistence layer for application-owned data in Solid Pods
+- A Drizzle-style API surface over RDF resources and documents
+- A practical bridge for teams migrating Drizzle mental models into Solid-native data flows
 
-### xpod - 扩展的 CSS (推荐)
+## What it isn't
 
-**xpod** 使用 **QuintStore**（五元组存储，GSPOV）替代文件存储，通过 6 组索引实现查询下推：
+- Not a general-purpose SQL ORM
+- Not a universal abstraction over arbitrary RDF on the open web
+- Not a graph database or SPARQL engine replacement
+- Not a black box that hides Pod boundaries, permissions, or network behavior
+- Not a promise that every SQL/driver-specific Drizzle feature maps cleanly to Solid
 
-- ✅ **SPARQL SELECT 服务端执行**：查询下推到 QuintStore 索引
-- ✅ **Sidecar API**：`/-/sparql` 端点，权限继承自资源路径
-- ✅ **混合存储**：RDF → QuintStore 索引，非 RDF → 文件系统
-- ⚠️ **联邦查询**：跨 Pod 查询仍需 Comunica 内存处理
-- ⚠️ **SPARQL 覆盖**：约 90% W3C SPARQL 1.1 测试通过
+## Core concepts
 
-**仓库**：https://github.com/undefinedsco/xpod | **详细对比**：[xpod 特性文档](./docs/xpod-features.md)
+### Resource
 
-## 🚀 快速开始
+A resource is the persisted unit in a Pod, usually a Turtle or JSON-LD document addressed by URL.
 
-### 安装
+### Document
 
-```bash
-yarn add drizzle-solid
-```
+A document may contain one entity or many entities. Document layout is part of application design, not an implementation detail.
 
-### 基本用法
+### Entity
 
-```typescript
-import { drizzle } from 'drizzle-solid';
-import { podTable, string, int } from 'drizzle-solid';
-import { Session } from '@inrupt/solid-client-authn-node';
+An entity is a typed RDF subject stored in a document. It is closer to a linked-data subject than to a relational row.
 
-// 定义表结构
-const profileTable = podTable('profile', {
-  name: string('name'),
-  email: string('email'),
-  age: int('age')
-}, {
-  // 相对 Pod 根的容器/资源路径，不需要 idp:// 前缀
-  base: '/profiles/',
-  type: 'https://schema.org/Person'
-});
+### IRI
 
-// 自定义 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'
-});
+IRIs are native identity. `drizzle-solid` keeps the full subject IRI available and provides explicit IRI APIs for exact operations.
 
-// 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);
+### Link
 
-// 初始化需要使用的表（创建容器、资源并注册 TypeIndex）
-await db.init([profileTable]);
+Links between entities are represented as IRIs and may cross documents or Pods.
 
-// 查询数据
-const profiles = await db.select().from(profileTable);
+### Model
 
-// 插入数据
-await db.insert(profileTable).values({
-  name: 'Alice',
-  email: 'alice@example.com',
-  age: 30
-});
+`drizzle-solid` supports two modeling styles:
 
-// 使用 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' });
+- `podTable(...)`: schema plus concrete storage location
+- `solidSchema(...)` + `db.createTable(...)`: reusable schema separated from where data is stored
 
-### SPARQL Endpoint 模式兼容性说明 (重要!)
+### Pod client
 
-当 `podTable` 配置 `sparqlEndpoint` 时，Drizzle Solid 会直接使用该端点执行所有 CRUD 操作。理解其行为模式对于数据一致性至关重要：
+`drizzle(session)` creates the database client bound to an authenticated Solid session.
 
-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 中。
+## Modeling vs persistence
 
-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 作为聚合查询工具。
+A Solid application usually needs to answer two different questions:
 
+1. **What is the shape of my data?**
+2. **Where does that data live in Pods?**
 
-```
+`drizzle-solid` keeps those concerns explicit.
 
-## 📚 示例教程
+- Use `podTable(...)` when your app owns the storage location and you want one place to define shape + location.
+- Use `solidSchema(...)` when the same schema should be reused across different Pod locations, profiles, or discovered data sources.
+- Use `db.createTable(schema, { base, ... })` when you want to bind a reusable schema to a concrete place at runtime.
 
-我们提供了完整的示例来帮助您快速上手：
+This keeps Solid's persistence model visible instead of flattening everything into table-only abstractions.
 
-### 🏗️ 示例1: 快速开始
+## Why document-first
 
-```bash
-yarn example:quick
-```
+Solid stores data in resources, not in tables.
 
-这个示例展示：
-- 如何连接到 Solid Pod 并定义表结构
-- 使用 Drizzle 风格 API 执行插入、查询、更新、删除
+That means application design starts with questions like:
 
-### 📖 示例2: 关系查询
+- which entities belong in the same document
+- which entities should be split into separate resources
+- which resources should be public, private, or shared
+- how links should work across documents and Pods
 
-```bash
-yarn example:query
-```
+`drizzle-solid` follows that reality. It provides a structured API, but keeps resource identity and document layout as part of the model.
 
-这个示例展示：
-- 如何定义表之间的关系
-- 使用 `with` 进行关联查询
-- 嵌套数据的加载方式
+## Quick start
 
-### 🛠️ 示例3: 零配置数据发现
+### Install
 
 ```bash
-yarn example:discovery
+yarn add @undefineds.co/drizzle-solid
+# or
+npm install @undefineds.co/drizzle-solid
 ```
 
-这个示例展示：
-- 如何使用 TypeIndex 自动发现数据位置
-- SAI (Solid Application Interoperability) 数据授权
-- 无需硬编码路径的数据访问
+> In this repository, the examples import `drizzle-solid` through a local TypeScript path alias. In external applications, import the published package name: `@undefineds.co/drizzle-solid`.
 
-## 📖 详细文档
+### Define a model and run CRUD
 
-### 表定义
-
-```typescript
-import { podTable, string, int, boolean, date, uri, eq, gte, and } from 'drizzle-solid';
-
-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()
+```ts
+import {
+  drizzle,
+  podTable,
+  string,
+  datetime,
+  eq,
+} 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'),
 }, {
-  // 目标 Turtle 资源，必填，可以是相对 Pod 路径或绝对 URL
-  base: 'data/users.ttl',
-  // 主体类型
-  type: 'https://schema.org/Person',
-  // 可选：注册 TypeIndex（仅在提供 typeIndex 时才会尝试）
-  typeIndex: 'private' // 'public' | 'private' | undefined
+  base: 'https://alice.example/data/posts/',
+  subjectTemplate: '{id}.ttl',
+  type: 'http://schema.org/CreativeWork',
 });
 
-// 初始化：在 CRUD 前确保容器/资源存在（会按 base 自动创建）
-await db.init([userTable]);
-```
-
-- 使用 `.inverse()` 可以把列映射为 `<object> predicate <subject>` 方向，适合例如 `<org> schema:member <person>` 这样的反向边；查询/写入都会自动交换 RDF 三元组的主体和宾语。
-
-### Drizzle 风格查询：`db.query` + `findByIRI`
-
-将 schema 传入 `drizzle(session, { schema })` 后，可通过 Drizzle 对齐的查询助手调用：
+const db = drizzle(session);
+await db.init([posts]);
 
-```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 预加载关联行
-  }
+await db.insert(posts).values({
+  id: 'post-1',
+  title: 'Hello Solid',
+  content: 'Stored as RDF in a Pod document.',
+  createdAt: new Date(),
 });
 
-// 通过 IRI 查找单条记录（推荐使用 db.findByIri）
-const alice = await db.findByIri(schema.users, 'https://pod.example/data/users.ttl#alice');
-```
+const rows = await db.select()
+  .from(posts)
+  .where(eq(posts.id, 'post-1'));
 
-- `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') // 对象类型 (扩展)
-```
+await db.update(posts)
+  .set({ title: 'Updated title' })
+  .where(eq(posts.id, 'post-1'));
 
-### 查询操作
-
-```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();
+await db.delete(posts)
+  .where(eq(posts.id, 'post-1'));
 ```
 
-### 聚合查询
+### Reusable schema + runtime binding
 
-```typescript
-import { count, max } from 'drizzle-solid';
+```ts
+import {
+  drizzle,
+  solidSchema,
+  id,
+  string,
+} from '@undefineds.co/drizzle-solid';
+
+const profileSchema = solidSchema({
+  id: id(),
+  name: string('name').predicate('http://xmlns.com/foaf/0.1/name'),
+  bio: string('bio').predicate('http://schema.org/description'),
+}, {
+  type: 'http://xmlns.com/foaf/0.1/Person',
+});
 
-const stats = await db
-  .select({
-    totalUsers: count(),
-    oldestAge: max(userTable.age)
-  })
-  .from(userTable)
-  .where(gte(userTable.age, 18));
+const db = drizzle(session);
 
-console.log(stats[0]);
-// { totalUsers: 42, oldestAge: 63 }
+const profileTable = db.createTable(profileSchema, {
+  base: 'https://alice.example/profile/card',
+});
 ```
 
-> 当前聚合支持 `count/sum/avg/min/max`，由客户端在内存中计算，选择列表需全部为聚合字段；`JOIN` 与 `GROUP BY` 亦已通过客户端回放实现（在 CSS 升级至最新 Comunica 前仍保留此策略）。
-
-### 插入数据
+## Exact IRI operations
 
-```typescript
-// 插入单条记录
-await db.insert(userTable).values({
-  name: 'Bob',
-  email: 'bob@example.com',
-  age: 25
-});
-
-// 批量插入
-await db.insert(userTable).values([
-  { name: 'Alice', email: 'alice@example.com', age: 30 },
-  { name: 'Charlie', email: 'charlie@example.com', age: 35 }
-]);
-```
+For detail-page flows, remote links, shared resources, or exact mutation targets, use the IRI APIs:
 
-### 更新数据
+- `db.findByIri(table, iri)`
+- `db.updateByIri(table, iri, data)`
+- `db.deleteByIri(table, iri)`
+- `db.subscribeByIri(table, iri, options)`
 
-```typescript
-await db.update(userTable)
-  .set({ age: 26 })
-  .where(eq(userTable.name, 'Bob'));
-```
+```ts
+const agent = await db.findByIri(agentTable, 'https://alice.example/data/agents.ttl#assistant');
 
-### 删除数据
+await db.updateByIri(
+  agentTable,
+  'https://alice.example/data/agents.ttl#assistant',
+  { description: 'Updated through explicit IRI' },
+);
 
-```typescript
-await db.delete(userTable)
-  .where(eq(userTable.name, 'Bob'));
+await db.deleteByIri(
+  agentTable,
+  'https://alice.example/data/agents.ttl#assistant',
+);
 ```
 
-## 🔍 数据发现与零配置访问 (Data Discovery & Interoperability)
+## Subject templates and identity
 
-Drizzle Solid 实现了 Solid 的 **TypeIndex** 和 **SAI (Application Interoperability)** 规范，这意味着您**不需要**硬编码数据的具体路径（`base`）。只要定义好 RDF 类型，Drizzle 就会自动帮您找到数据，无论它是在您自己的 Pod 里，还是别人通过 SAI 授权给您的。
+`subjectTemplate` controls how record identity maps to Pod resources.
 
-### 核心概念
+Common patterns:
 
-- **TypeIndex**: 您的“个人数据索引”，记录了“我的笔记在哪里”、“我的联系人在哪里”。适合单用户场景。
-- **SAI Discovery**: 一种更高级的发现机制，用于发现**跨 Pod** 共享的数据（例如 Alice 分享给 Bob 的聊天室）。适合社交、协作场景。
+- `#{id}`: fragment mode, many entities in one RDF file
+- `{id}.ttl`: document mode, one file per entity
+- `{id}.ttl#it`: document mode with stable in-document fragment
+- `{chatId}/{yyyy}/{MM}/{dd}/messages.ttl#{id}`: multi-variable, date-partitioned layouts
 
-### 如何启用自动发现？
+Example:
 
-只需在定义表时，移除 `base` 属性，并设置 `typeIndex: 'private'`（或 `'public'`）：
-
-```typescript
-const messageTable = podTable('message', {
-  id: id(),
+```ts
+const Message = podTable('Message', {
+  id: string('id').primaryKey(),
+  chatId: string('chatId').predicate('http://example.org/chatId'),
   content: string('content').predicate('http://schema.org/text'),
+  timestamp: datetime('timestamp').predicate('http://schema.org/dateCreated'),
 }, {
+  base: 'https://alice.example/data/chats/',
+  subjectTemplate: '{chatId}/messages.ttl#{id}',
   type: 'http://schema.org/Message',
-  typeIndex: 'private' // ✨ 开启自动发现魔法
 });
-
-// 当您执行查询时，Drizzle 会自动：
-// 1. 查您的 Private TypeIndex
-// 2. 如果没找到，查 SAI Agent Registry (查看是否有授权给您的数据)
-// 3. 找到数据位置后，自动定向查询
-const messages = await db.select().from(messageTable);
 ```
 
-### 跨 Pod 聊天应用示例 (SAI Chat)
-
-这是一个展示如何利用 SAI 发现机制构建“零配置”聊天应用的完整示例。Bob 不需要知道 Alice 的聊天室 URL，只要 Alice 授权了，Bob 的应用就能自动发现并加入聊天。
-
-> 查看完整可运行代码：[`examples/04-sai-chat.ts`](examples/04-sai-chat.ts)
-
-```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
-});
+For reads, the library can often work from:
 
-// 2. Alice (房主) 初始化聊天室
-// Alice 需要明确指定存储位置 (base)
-const aliceChatTable = podTable('message', { ...messageTable.columns }, {
-    ...messageTable.config,
-    base: 'https://alice.pod/data/chat/room.ttl',
-    subjectTemplate: '#{id}' // 强制单文件存储模式
-});
-await db.insert(aliceChatTable).values({ ... });
+- a full IRI
+- all template variables
+- a narrower partial condition that scans a smaller bounded area
 
-// ... (Alice 通过 SAI 授权给 Bob，此处省略 SAI 注册代码) ...
+Read-path and write-path semantics are intentionally different:
 
-// 3. Bob (访客) 发现并回复
-// Bob 初始化 Drizzle 时，完全不需要知道 room.ttl 的地址
-const bobDb = drizzle(bobSession);
+- **Read queries** (`select`, `db.query.*`) may use partial template information for list/filter flows when the resolver can keep the scan bounded.
+- **Mutations** (`update`, `delete`) require deterministic targets by default. If `where()` cannot uniquely resolve the subject from the template, the dialect throws and tells you to use `updateByIri()` / `deleteByIri()` (or to provide the missing template variables).
+- **No implicit scan-based `updateMany/deleteMany` fallback** is performed on backends that do not natively support set-based mutation.
+- **Capability-based enhancement**: if a backend explicitly supports filter-based multi-row mutation in the future (for example, an xpod capability), `drizzle-solid` can expose that path there without pretending every Solid server supports it.
 
-// 读取：自动发现 Alice 分享的数据
-const messages = await bobDb.select().from(messageTable);
-console.log(messages); // 包含 Alice 的消息
+## Server support
 
-// 写入：自动向发现的地址写入回复
-await bobDb.insert(messageTable).values({
-    content: 'Hi Alice! I found your chat room!',
-    author: bobSession.info.webId
-});
-```
+### Capability matrix
 
-### Discovery 策略
+| Capability | Community Solid Server | xpod |
+| --- | --- | --- |
+| Basic CRUD | ✅ LDP mode | ✅ LDP mode |
+| SPARQL SELECT pushdown | ❌ Client-side / resolver-driven | ✅ `/-/sparql` sidecar |
+| SPARQL UPDATE | ⚠️ Limited / write path stays LDP-oriented | ✅ Better server-side support |
+| Filter / aggregation pushdown | ❌ Fallbacks and client execution | ✅ Single-Pod pushdown |
+| Federated queries | ⚠️ Client-side federation | ⚠️ Client-side federation |
+| Notifications | ✅ | ✅ |
+| In-process test runtime | ⚠️ External CSS setup | ✅ via `@undefineds.co/xpod` |
 
-Drizzle Solid 使用组合策略 (`CompositeDiscovery`)：
-1.  **TypeIndex 优先**：检查用户的 `privateTypeIndex.ttl` 和 `publicTypeIndex.ttl`。
-2.  **SAI 后备**：如果 TypeIndex 未命中，检查用户的 Profile -> RegistrySet -> Agent Registry，寻找匹配当前 ClientID 的 Data Grant。
+### Community Solid Server (CSS)
 
-这种设计确保了既能兼容旧的 Solid 应用（基于 TypeIndex），又能支持未来的互操作性规范（SAI）。
+On plain CSS, `drizzle-solid` keeps working, but many queries are resolved through client-side execution and Solid-aware fallbacks. This is the compatibility baseline.
 
-架构说明见 `docs/guides/architecture.md`。
+### xpod
 
-## ✅ 当前 SQL 支持范围
+`xpod` adds a Solid-compatible SPARQL sidecar and is the recommended development/runtime target when you want stronger query pushdown and a lower-friction local setup.
 
-- 已实现：`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 或拆分查询。
+See `docs/xpod-features.md` for more detail.
 
-## 🗺️ Roadmap
+## Verified examples
 
-- **`rightJoin`/`fullJoin` 支持**: 待评估 xpod SPARQL 能力后实现，详见[设计方案](docs/guides/right-full-join-sparql-design.md)。
+The canonical examples in `examples/` are verified in the test suite.
 
-## 🔧 配置
+- `examples/01-quick-start.ts` — CRUD quick start
+- `examples/02-relational-query.ts` — relational query API surface
+- `examples/03-zero-config-discovery.ts` — zero-config discovery flow
+- `examples/04-notifications.ts` — Solid notifications
+- `examples/05-data-discovery.ts` — discovery API
+- `examples/06-federated-query.ts` — federated query across Pods
+- `examples/07-hooks-and-profile.ts` — hooks and profile management
+- `examples/08-iri-based-operations.ts` — explicit IRI operations
+- `examples/08-schema-inheritance.ts` — schema inheritance
+- `examples/09-multi-variable-templates.ts` — multi-variable subject templates
 
-### 自定义命名空间
+The example manifest lives at `examples/manifest.json`, and the integration verification lives at `tests/integration/css/examples-verification.test.ts`.
 
-Drizzle Solid 不再内置 vocab 常量，请从 RDF vocab 库（例如 `@inrupt/vocab-common-rdf`）导入需要的术语；若需要扩展缺失字段，可使用 `extendNamespace`：
+## Query surface and SQL scope
 
-```typescript
-import { podTable, string, extendNamespace } from 'drizzle-solid';
-import { SCHEMA_INRUPT as SCHEMA } from '@inrupt/vocab-common-rdf';
+`drizzle-solid` aims to stay close to Drizzle's public builder surface where that maps cleanly to Solid.
 
-const LINQ = extendNamespace(
-  { prefix: 'linq', uri: 'https://linq.dev/ns/' },
-  { favorite: 'profile#favorite' },
-  { namespace: 'https://linq.dev/ns/' }
-);
+Current supported surface includes:
 
-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
-});
-```
+- CRUD builders: `select`, `insert`, `update`, `delete`
+- Read-oriented query facade: `db.query.*.findMany`, `findFirst`, `findById`, `findByIRI`, `count`
+- Conditions: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `inArray`, `exists`, `and`, `or`, `not`
+- Query features: joins, ordering, limits, offsets, distinct
+- Aggregations: `count`, `sum`, `avg`, `min`, `max`
+- Batch and `returning()` support where implemented by the dialect
+- Raw **SPARQL** workflows where you need explicit graph-native control
 
-### 认证配置
+Not the mainline contract:
 
-```typescript
-import { Session } from '@inrupt/solid-client-authn-node';
+- raw SQL as the primary abstraction
+- transaction semantics identical to SQL databases
+- implicit scan-based `updateMany/deleteMany` on backends that do not support set-based mutation
+- driver-specific DDL, auto-increment, foreign keys, or SQL engine behaviors
 
-const session = new Session();
-await session.login({
-  oidcIssuer: 'https://solidcommunity.net',
-  redirectUrl: 'http://localhost:3000/callback',
-  clientName: 'My Solid App'
-});
+The migration goal is API familiarity with low migration cost, but the execution model remains Solid/SPARQL-native rather than semantics-faking SQL emulation.
 
-const db = drizzle(session);
-```
+## Discovery, interoperability, and federation
 
-### `base` / `@id` / `id` 与 Pod 根的关系
+The library also includes higher-level Solid workflows:
 
-- `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`。
+- data discovery and interop metadata
+- TypeIndex-driven location discovery
+- shape-aware table generation
+- federated queries across discovered Pod locations
+- notifications for resource/entity updates
 
-## 🏗️ 架构
+Useful starting points:
 
-Drizzle Solid基于以下组件构建：
+- `docs/guides/data-discovery.md`
+- `docs/guides/notifications.md`
+- `docs/guides/css-notifications.md`
+- `docs/federated-queries.md`
+- `docs/guides/multi-variable-templates.md`
 
-- **PodDialect**: Solid Pod的Drizzle方言实现
-- **SPARQL转换器**: 将Drizzle查询转换为SPARQL
-- **Comunica执行器**: 执行SPARQL查询
-- **类型系统**: 完整的TypeScript类型支持
+## Documentation map
 
-### Comunica CRUD 流程
+- `examples/README.md` — curated walkthroughs and runnable examples
+- `docs/quick-start-local.md` — local setup guide
+- `docs/guides/data-discovery.md` — discovery workflows
+- `docs/guides/issue-handling.md` — issue reproduction and regression workflow
+- `docs/guides/testing.md` — test conventions and coverage strategy
+- `ACTION-PLAN.md` — current parity and implementation plan
 
-- 查询会经过 AST → SPARQL 转换；若 Comunica 无法执行带过滤器/聚合的 `UPDATE`/`DELETE`，方言会先通过 `SELECT` 拉取命中的 subject，再以 PATCH 方式回写，实现与 SQL 行级操作一致的语义。
-- `PodDialect` 会自动推导目标容器与 `.ttl` 资源文件路径，必要时发送 `HEAD`/`PUT` 请求确保容器和资源已经存在，再交由 Comunica 处理数据修改。
-- 插入会预先读取现有资源以检测重复 subject，避免重复写入；删除或更新只针对匹配的 subject 生成最小化补丁。
-- 对于 `JOIN`、`GROUP BY` 与聚合，选取的数据仍由 SPARQL 拉取，但结果会在内存中组合或聚合，直到 CSS 升级到支持完整 SPARQL 1.1 为止。
+## Planned scope
 
-## 🤝 贡献
+### Current direction
 
-欢迎贡献代码！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解测试要求、提交流程与验证内容。
+The current focus is:
 
-在提交 PR 之前，请同步运行完整的 CSS 集成测试（覆盖 CRUD、TypeIndex 等场景）：
+- typed models for application-owned Pod data
+- explicit document and subject placement
+- Drizzle-aligned query ergonomics
+- practical CRUD, discovery, federation, and notification flows
 
-```bash
-SOLID_ENABLE_REAL_TESTS=true npx vitest run tests/integration/css --runInBand
-```
+### Likely next steps
 
-> `SOLID_ENABLE_REAL_TESTS=true` 会启用真实 Pod，`--runInBand` 保证所有 suite 共用一个会话并顺序执行，避免对 OIDC 服务造成并发压力。
+- better modeling ergonomics around reusable schemas and links
+- clearer guidance around multi-resource layouts and identity strategies
+- continued Drizzle parity on Solid-relevant behaviors
+- stronger documentation around Solid-native tradeoffs and migration paths
 
-## 📄 许可证
+### Out of scope
 
-MIT License - 查看[LICENSE](LICENSE)文件了解详情。
+- hiding Solid behind a fake SQL database mental model
+- universal querying over arbitrary open-world RDF as the primary goal
+- promising full relational/database feature parity where Solid semantics differ
 
-## 🔗 相关链接
+## Contributing
 
-- [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)
+Before contributing:
 
+```bash
+yarn build
+yarn lint
+SOLID_ENABLE_REAL_TESTS=true SOLID_SERIAL_TESTS=true yarn vitest --run --silent
+```
 
-## 📞 支持
+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