客户端

客户端是每个应用、自动化与远程函数用于读取、写入与调用的类型化界面。它从 $bolt/client 导入，由 bolt sync 生成，因此每次调用都会对照你的集合进行类型检查。

一个客户端，每个关注点一个界面

客户端暴露工作区能做的所有事情：

界面	用途
client.db	读取——实时 findMany/findFirst 前缀，以及一次性的 count/findGrouped/findNearest
client.collection	写入——声明的 create/createMany/update/updateMany/delete/deleteMany，各自返回乐观行与结算句柄（accepted、rebased、rejected 或 quarantined）
client.collection_history	历史——一条记录的全部修订，或指定修订、时刻、审批请求之前的记录取值
client.approvals	审批决定——处理请求（APPROVED、REJECTED、REQUEST_FOR_CHANGE、SUPERSEDED）或撤回
client.records	公共系统集合——用 records.findMany(collectionName, query) 读取类型化租户注册表之外的表
client.collections	只读目录——每个集合声明的字段与关系，用于构建通用界面
client.invoke	远程函数——从 src/functions/ 发现的带类型查询与命令处理器
client.automations	——后台启动已声明的自动化并观察其持久运行
client.device	设备——定位、分享、复制、触感与在线状态，各自返回一个值或类型化的 DeviceRefusal，从不抛异常

客户端实战

同一个客户端驱动所有应用——读取、写入与调用都经由它：

import { client } from '$bolt/client';
import { Effect } from 'effect';

// Live read — registered with the server; its current answer is held in memory
// and commits that change the answer arrive as SSE apply frames
const sites = client.db.sites.findMany({
  where: { status: { eq: 'active' } },
  orderBy: { name: 'asc' },
  limit: 25
});

// Collection write — queued in this tab's memory and pushed to the authority;
// the server allocates the id
const write = await client.collection.site_visits.create({
  site_id: siteId,
  visited_at: new Date()
});
write.row; // optimistic row projected immediately
await write.settlement.settled; // accepted, rebased, rejected, or quarantined

// History — every revision of one record, one-shot, never live.
// A create's authoritative id arrives with the live read; the optimistic row carries none.
const revisions = await client.collection_history.site_visits.revisions(visitId);

// Remote function — typed query or command handler
const forecast = await client.invoke.holiday_feed({ year: 2026 });

// Device — the platform seam for location, share, copy, and haptics;
// every call answers a value or a typed DeviceRefusal, never throws
const fix = await Effect.runPromise(client.device.location({ highAccuracy: true }));

实时数据

读取是 实时查询 ，在服务器注册并由服务器应答；浏览器写入使用 client.collection.<name> 下每个集合声明的操作，返回持久性为 memory 的乐观结果与结算句柄。读取与写入是两个独立界面：client.db 从不写入。

AI

模型访问经由 ai 设施 ——宿主绑定提供商，租户代码永远看不到凭据。

边界

• 客户端从不接触服务器端缓存 API。
• 应用无法访问私有运行时设施。
• 生成的客户端是进入工作区的唯一合规数据路径。