@tinkerlandai/indiana-sdk 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Release facts and artifact evidence: [SDK release ledger](../../docs/sdk-releases.md). Earlier personal-package versions are preserved in [@houzhen888/groove-grow history](../../docs/sdk-changelog-groove-grow.md). The two packages have independent version histories.
 
+## 0.2.0 — 2026-10-16
+
+- Breaking: server Funnel starts and decisions use `customer: { type: "id" | "externalUserId", value }`; optional `customerData` is creation-only and requires an external user reference. Remove start-body `customerToken` and decision `customerId`; no legacy compatibility. Customer-credential starts name no Customer.
+- Export `createFunnelCampaignClient` from `/server` for explicit campaign decisions and starts with durable suppression. Validate returned Funnel and Customer identity before accepting a Run.
+- Use `X-Indiana-Web-View` and `X-Indiana-Telemetry-Subject` response headers. Include current renderer, native shell and Paywall recovery/lifecycle fixes.
+- Route native receipt recovery through independent `subscriptions/native/restore`, including read-only recovery. This package release does not certify or publish Apple/Google store integrations; real store acceptance remains deferred.
+
+## 0.1.0 — 2026-10-16
+
+- Web Beta with current Indiana factories, Customer two-table identity, current Funnel runtime, Feature generation, Offering hierarchy and independent Paywall sessions. No legacy API or data compatibility.
+- Converge current request/response contracts and regenerate native shell assets. Include canonical Stripe payment setup, subscription administration and License client contracts. Server availability is documented in README; unfinished billing authorization, batch/conflict, Reward Product and native execution remain outside accepted scope.
+- Keep one npm package with browser, server, popup, OpenRouter and native-shell entries. Swift/Kotlin store acceptance and publication are deferred.
+
+- Move Local/Remote evaluation policy to each Funnel. New Funnels default to Local; Owner/Admin manage it in Funnel settings. API keys only authenticate and authorize calls; one key can call different modes. Remove `remoteEval`: `configuration()` reads the Funnel mode and the server enforces rule downloads and API decisions.
+- Add `configuration()` with public Funnel topology and versioned resource references. Remote payloads omit rules and commercial parameters; Local payloads include pure evaluation configuration.
+- Keep business actions server-authoritative. Existing Funnels migrate explicitly to Remote; one API key can call both Local and Remote Funnels.
+
 ## 0.0.1 — 2026-10-13
 
 - First organizational Beta under `@tinkerlandai/indiana-sdk`, replacing personal-package imports. Publish with the `beta` tag and pin `0.0.1` when installing.

package/README.md

@@ -1,307 +1,95 @@
 # @tinkerlandai/indiana-sdk
 
-Indiana 的框架无关 Web / TypeScript SDK。组织包首版为 `0.0.1`，以 `beta` 标签分发；升级前确认服务端与数据库迁移匹配。不提供旧接口或数据格式兼容，变更见 [Changelog](CHANGELOG.md)。
+Indiana 的 JavaScript／TypeScript SDK，包含浏览器、Node.js、屏幕渲染与可选 AI 用量集成。`0.2.0` 以 `beta` 标签分发；服务端和数据库必须使用匹配的当前协议。本版本有破坏性变更，不提供旧名称、旧输入或旧数据模型的兼容层。
 
 ```sh
-npm install @tinkerlandai/indiana-sdk@0.0.1
+npm install @tinkerlandai/indiana-sdk@0.2.0
 ```
 
-安装请固定 `0.0.1`。新组织包与旧个人包 `@houzhen888/groove-grow` 的版本空间独立，不能按版本号大小判断升级关系。完整发布记录与核对时间见 [发布总账](../../docs/sdk-releases.md)，本版范围与验收边界见本文末尾。
+## 一个 npm 包，五个入口
 
-服务端 Key、Customer Token 与控制台登录的区别、逐请求查库校验、权限及撤销轮换，见 [服务端鉴权](../../docs/server-authentication.md)。安装与发布状态见 [自助接入](../../docs/sdk-selfserve.md)。
+| 导入入口                                 | 用途                                                        |
+| ---------------------------------------- | ----------------------------------------------------------- |
+| `@tinkerlandai/indiana-sdk`              | 浏览器 Customer、Funnel、Feature 与独立 Paywall 客户端      |
+| `@tinkerlandai/indiana-sdk/server`       | 可信 Node.js 后端、Customer Session、业务写入和 Funnel 决策 |
+| `@tinkerlandai/indiana-sdk/popup`        | 独立屏幕渲染、清洗和预览                                    |
+| `@tinkerlandai/indiana-sdk/openrouter`   | 可选 OpenRouter 用量集成，需要安装对应 peer dependency      |
+| `@tinkerlandai/indiana-sdk/native-shell` | 原生 WebView 的静态 Funnel shell 资源；不代表商店购买验收   |
 
-一个包提供浏览器、可信后端与渲染入口，不依赖 React、Next.js 或 Supabase 客户端。内部 contracts 在打包时内联，接入方不需要安装私有工作区包。
+JavaScript 与 TypeScript 共用本包，声明文件随包提供。内部 `@indiana/contracts` 在构建时内联，接入方无需安装私有包。Swift 和 Kotlin 使用各自的包管理生态，不在本次 npm 发布范围内。
 
-| 入口                                     | 用途                                                           |
-| ---------------------------------------- | -------------------------------------------------------------- |
-| `@tinkerlandai/indiana-sdk`              | 当前客户读取、Funnel 控制器与统一展示宿主                      |
-| `@tinkerlandai/indiana-sdk/server`       | 客户管理、Session 签发、账本写入与可信 Funnel 启动             |
-| `@tinkerlandai/indiana-sdk/openrouter`   | 可选 OpenRouter 用量集成，宿主需安装对应 peer dependency       |
-| `@tinkerlandai/indiana-sdk/popup`        | 纯屏幕渲染、清洗和编辑预览                                     |
-| `@tinkerlandai/indiana-sdk/native-shell` | 供 Grow 托管的原生 Funnel 壳生成纯设计资源，不含客户或运行凭据 |
-
-## 可信后端与客户身份
+## 从可信后端创建 Customer Session
 
 ```ts
-import { createGrooveServer } from "@tinkerlandai/indiana-sdk/server";
-const groove = createGrooveServer({
-  baseUrl: process.env.GROOVE_BASE_URL!,
-  apiKey: process.env.GROOVE_SECRET_KEY!,
-  scope: { projectId: process.env.GROOVE_PROJECT_ID!, environment: "sandbox" },
+import { createIndianaServer } from "@tinkerlandai/indiana-sdk/server";
+
+const indiana = createIndianaServer({
+  baseUrl: process.env.INDIANA_BASE_URL!,
+  apiKey: process.env.INDIANA_SECRET_KEY!,
+  scope: {
+    projectId: process.env.INDIANA_PROJECT_ID!,
+    environment: "sandbox",
+  },
 });
 const user = await requireSignedInUser(request);
-const { customer } = await groove.getOrCreateCustomer({
+const { customer } = await indiana.getOrCreateCustomer({
   externalUserId: user.id,
 });
-const { customerToken } = await groove.createCustomerSession(customer.id);
+const { customerToken } = await indiana.createCustomerSession(customer.id);
 ```
 
-Secret Key 只放在可信后端。浏览器提供的客户 ID 不能作为登录证明；客户 Token 仅交给该已登录用户，SDK 只在内存持有。每个 App／环境单独配置权限与允许来源。切换账号时关闭并销毁旧运行，丢弃旧客户凭据；迟到响应不能更新新身份。
-
-## 统一 Funnel
+Secret Key 仅保存在可信后端。浏览器传入的 Customer ID 不能作为登录证明；将 Customer Token 交给对应的已登录用户。App、Sandbox／Live、Customer、权限和允许来源分别校验。SDK 在内存中持有客户凭据；退出或切换身份时销毁旧视图并清理凭据。
 
 ```ts
-import { createFunnelStartClient } from "@tinkerlandai/indiana-sdk/server";
-const funnels = createFunnelStartClient({
-  baseUrl: process.env.GROOVE_BASE_URL!,
-  apiKey: process.env.GROOVE_SECRET_KEY!,
-  scope: { projectId: process.env.GROOVE_PROJECT_ID!, environment: "sandbox" },
-});
-// 宿主在首次调用前持久保存整个 start 输入；响应丢失后原样重试。
-const result = await funnels.start({ ...retainedStartInput, customerToken });
-```
+import { createIndiana } from "@tinkerlandai/indiana-sdk";
 
-`retainedStartInput` 包含 `source`、`requestId`，以及明确的 `commerce`、`locale`、`parameters`。`source` 选择 `funnel/id`、`paywall/id` 或已发布的 `trigger/key`。服务端 Key 需要 `sessions:create` 与 `funnels:run`。每个运行都属于一个客户：已登录用户用 `createCustomerSession` 的 `customerToken`；未登录访客先 `createGuestCustomer`，再用 `resumeGuestSession` 取得游客 `customerToken`。浏览器只接收这一运行的 `runToken`。独立 Paywall 使用系统维护的 Funnel。
-
-```ts
-import {
-  createFunnelRunController,
-  showFunnelRun,
-} from "@tinkerlandai/indiana-sdk";
-const client = createFunnelRunController({
+const indiana = createIndiana({
   baseUrl,
   scope: { projectId, environment: "sandbox" },
-  runToken,
-});
-const handle = await showFunnelRun(container, {
-  client,
-  onAuthenticate: async () => obtainCurrentUserCustomerToken(),
-  onCheckout: ({ url }) => window.location.assign(url),
-  onOpenUrl: ({ url }) => window.location.assign(url),
-  onError: reportError,
 });
+indiana.identify(customerToken);
+const { holdings } = await indiana.readHoldings();
+// 退出账号时：
+indiana.reset();
 ```
 
-宿主实现登录与 Token 获取；取消认证返回 `null`。付款回跳后展示同一运行，服务端读取验证后的支付事实。点击、导航和宿主回调不能确认付款。
+Customer 使用原始业务字段；资料更新是部分 patch，没有 Customer revision。Guest 登录到已有 Customer 时返回 `switched: true`，资源和历史保留原归属，接入方应为目标 Customer 创建新 Session／Funnel；不合并旧 Guest 的财务事实。
 
-控制器提供 `get`、`submit`、`retry`、`resume`、`identify`、`link`、`subscribe` 和 `reset`。变更命令包含当前 `nodeId`、`revision` 与稳定 `requestId`。超时保留 `pendingCommand`，先 `retry` 原命令；服务端已经持有中断命令时使用其 `pendingRequest.requestId` 恢复。原命令回执不能倒退新的观测状态。
+## Funnel、Feature 与独立 Paywall
 
-每个屏幕分别选择弹窗、面板、全屏或嵌入。屏幕按钮只产生出口，认证、领券、收费和会员变更由相应节点执行。账户、积分、会员和账单是屏幕中的客户组件；刷新、分页、过滤及预览只读。`destroy` 清理界面，`close` 才提交关闭命令。
+可信后端通过 `createFunnelStartClient().start()` 提交 `funnelId`、持久保留的 `requestId`、`customer`、`locale` 和 `parameters`。`customer` 为 `{ type: "id", value: customerId }` 或 `{ type: "externalUserId", value: verifiedUser.id }`。后者可以同时提供仅用于新建的 `customerData`，需要 `customers:write` 权限；已有 Customer 不因此更新。服务端响应返回 `customerId`，后端再为它签发 Customer Session。旧的 start-body `customerToken` 和 decision `customerId` 明确拒绝。
 
-## JSON 决策与 Feature（当前源码）
+`createFunnelClient({ customerToken, ...options })` 用于已持有 Customer 凭据的客户端；其 `start()` 不指定 `customer` 或 `customerData`，始终以凭据所属 Customer 运行。响应丢失时保留原编号和输入重试，商业参数放在 `parameters.commerce`。运行有独立的 Run Token，不能据此切换 Customer。
 
-本版的通用 JSON 决策需要匹配的数据库迁移和 Workflow 部署。旧个人包 `@houzhen888/groove-grow@0.0.7` 使用发布时的旧契约；发布事实见 [发布总账](../../docs/sdk-releases.md)。
+`createFunnelDecisionClient` 的 `submit/decide` 与 `/server` 的 `createFunnelCampaignClient` 同样使用明确的 `customer` 引用。Campaign 客户端提供显式 `decide/start`；受频率或进行中运行限制时，`start` 返回 `suppressed` 和重试时间，不伪造 Run 凭据。Run 实际展示后才提交 `shown`，不能用页面关闭或本地存储代替持久的展示事实。
 
-```ts
-import { createFunnelDecisionClient } from "@tinkerlandai/indiana-sdk/server";
-const decisions = createFunnelDecisionClient({
-  baseUrl,
-  scope,
-  apiKey,
-  funnelId,
-});
-const decision = await decisions.decide({
-  requestId: retainedRequestId,
-  customerId,
-  attributes: {
-    tags: ["ad"],
-    isNeverPaid: true,
-    country: "US",
-    channel: "ads",
-  },
-});
-```
-
-可信后端提交完整 `attributes` JSON，业务可以自行提供付费历史、渠道等属性。结果的 `value` 是规则输出的任意 JSON；首次成功提交的结果（包括 null、false、0 或零优惠对象）固定在当前 allocationScopeId，后续属性变化不会重新计算。`state` 分别表示 active、expired 或 inactive；它随有效期和活动状态变化，value 保持不变。新的分配活动须显式更换 allocationScopeId。parameters、answers、results 是 Funnel 保留的上下文命名空间。
+浏览器使用 `createFunnelRunController` 与 `showFunnelRun`。控制器负责当前协议的命令、读取、重试、恢复和订阅；展示句柄提供 `refresh()` 和 `destroy()`。业务操作按当前发布节点委派给服务端，客户端声明或重定向不构成付款证明。
 
-每个新 requestId 保存查询日志，重试保留原 ID。查询不发券、不执行支付。采用后可选调用 `reportUsed({ eventId, decisionId, occurredAt, reference })`；它只记录调用方报告。超时后的 `FunnelDecisionTimeoutError` 保留 decisionId，可通过 read 继续读取。
-
-```ts
-const features = decisions.features({
-  attributes: { id: customerId, country: "US" },
-});
-await features.init(); // 下载当前 App/环境/Funnel 的配置
-const value = features.getFeatureValue("discount", { starter: 0 }); // 同步、本地判断
-features.setAttributes({ id: customerId, country: "JP" }); // 完整替换属性
-await features.refresh(); // 显式获取新的资源配置
-```
+Local／Remote 求值策略由每个 Funnel 决定。`createFunnelDecisionClient` 支持当前 `configuration()`、`features()`、提交和结果读取；`createFeatureClient` 以 `generation` 标识配置。Local 下载的规则对客户端可见；敏感决策应使用 Remote 和可信业务事实。
 
-`createFeatureClient` 在浏览器与服务端入口均可用，自行提供 load 可复用安全下发的配置。Secret Key 仅用于后端。init/refresh 后，每次 evalFeature/getFeatureValue 不联网；expiresAt 到达时间表边界后必须刷新。实验曝光和 Feature 使用由可选回调报告；持久化粘性分桶需提供对应存储回调和初始分配，后端 Funnel 使用原子数据库存储。
+Offering 固定 Product Version 的范围与层级。Paywall 固定已发布 Offering Version，并独立选择显示的 Product 子集、分组、顺序和默认项。`createPaywallStartClient`、`createPaywallSession`、`showPaywall` 使用独立 Paywall Session，不创建占位 Funnel。付款完成后重新查询权益，业务后端仍须重新鉴权并幂等扣减用量。
 
-需要异步接收时调用 `submit(input)`，它返回已持久接受的当前状态，不等待求值或轮询。`submit`／`decide` 首次提交的响应丢失、网络错误或服务暂时不可用时，会抛出 `DECISION_ACCEPTANCE_UNKNOWN`，其 `requestId` 是原逻辑请求编号；沿用原编号与原输入重试。请求已接受后，HTTP 结果等待最多八秒，读取卡住或暂时失败仍返回原 requestId／decisionId 的 pending 状态，不取消后台执行。
+## Web 商业能力与当前服务边界
 
-交互运行的 `runExpiresAt` 和 `credentialExpiresAt` 分别表示业务期限和凭证期限。可信后端使用 `renewFunnelRun` 续签同一已识别客户的运行，业务期限不变。等待指令和客户端须使用同一当前协议。
+当前服务端实现了 Customer／Guest、Entitlement 检查、持有与账本读取、用量和余额、Coupon／推荐码、Offering／独立 Paywall，以及配置后的 Stripe Sandbox attach、支付方式收集、订阅验证／更新／退款／Trial 和 License 分配路径。每个操作仍受已配置的支付账号、执行模式、Product／Price 条款和当前实现范围约束；接口存在不表示任意组合已验收。
 
-## Funnel 服务端回执
+Stripe 环境的 `autumn` 模式由 Indiana 执行；`record_only` 返回交给商户后端执行的指令。两种模式都从验证后的 Stripe 事实写入财务与权益。支付方式收集本身不产生扣款、Invoice 或额外权益。报价／确认／读取使用各自持久操作 ID；同一请求编号不能更换输入。
 
-`createFunnelOrchestrationClient` 来自 `/server` 入口，使用 App/环境的 Secret Key。`signal({ runId, nodeId, eventName, eventId, data })` 为已声明的自定义等待节点提交回执，重试沿用同一事件 ID 与数据；`readResults(runId)` 读取已完成任务和已消费回执的结果。浏览器不能发送这些回执，自定义事件不能代替验证付款事实。
-
-回执可以早于等待节点抵达，但收到确认不代表已经消费。条件和后续任务以 `nodeId.field` 引用声明结果。仅查询优惠的调用方可以继续使用上面的查询接口，不需要增加回执等待。
-
-本版包含 `createFunnelOrchestrationClient` 的 `signal` / `readResults` 接口。外部任务可复用已启用的 Sandbox 通知端点，提供签名请求、冻结输入和持久重试预算。接收器必须按 Action Receipt ID 去重；网络调用允许至少一次投递。配置、协议、数据库变更与验收边界见[编排说明](../../docs/funnel-orchestration-2026-10-10.md)。接口存在不代表宿主通知已经配置或验收。
-
-## 当前持有与账本
-
-### 原生订单恢复
-
-Swift／Kotlin 宿主的 `recoverNativeOrders` 通过应用自有 HTTPS 后端提交当前客户会话及受保护的订单绑定。后端使用 `createNativeReceiptClient`，服务器密钥始终留在后端：
-
-```ts
-import { createNativeReceiptClient } from "@tinkerlandai/indiana-sdk/server";
-const receipts = createNativeReceiptClient({
-  baseUrl: process.env.GROOVE_BASE_URL!,
-  apiKey: process.env.GROOVE_SECRET_KEY!,
-  scope: { projectId: process.env.GROOVE_PROJECT_ID!, environment: "sandbox" },
-});
-// 先校验应用自身登录会话及当前客户身份；重试保留原 requestId 和输入。
-const result = await receipts.recover(retainedCurrentReceiptInput);
-```
-
-该操作为 `/api/v1/funnels` 的 `native_receipt`，需要 `billing:write` 与 `funnels:run` 以及当前 `gg_ct_` 客户会话。它不依赖 run token，不复活或推进已结束、关闭或过期流程。Apple 只 finish 返回的 `nativeCompletion.transactionIds`；Google 的 acknowledge/consume 在服务端持久交付后完成。完整输入、宿主 relay、固定 SKU 席位及商店优惠边界见[当前原生接入](../../docs/native-commercial-current.md)。
-
-```ts
-import { createGroove } from "@tinkerlandai/indiana-sdk";
-const grow = createGroove({
-  baseUrl,
-  scope: { projectId, environment: "sandbox" },
-});
-grow.identify(customerToken);
-const { holdings } = await grow.readHoldings();
-const { ledger } = await grow.readLedger({
-  type: null,
-  from: null,
-  to: null,
-  after: null,
-  limit: 50,
-});
-const { quote } = await grow.quoteBalance({
-  operation: "quote",
-  entitlementId,
-  quantity: "1",
-  properties: {},
-});
-```
+本 Beta **不认证完整商业功能或生产运行**。当前仍未接通的服务包括：
 
-浏览器请求不传客户 ID。持有需要 `entitlements:read`，账本和报价需要 `credits:read`。账本过滤作用于全部历史，之后分页；下一页原样传回 `nextCursor`，保留微秒、记录 ID 与类型。数量、余额和计价保留十进制字符串；报价不扣款。
+- 订阅批处理。冲突查询／重试已有对应服务，但仍需匹配部署及业务前置条件。
+- Postpaid Billing Authorization、Billing Coupon 列表和账单调整确认。当前 AutoTopup consent 的准备／确认／撤销已有服务，不能据此推定其他授权类型可用。
+- `claimRewardProduct` 的完整交付。
+- Apple／Google 真实商店验收。当前独立购买／恢复的协议及部分服务实现不代表商店已验收；`createNativeReceiptClient().recover()` 使用 `subscriptions/native/restore`，不再发送旧 Funnel 原生恢复命令。
 
-```ts
-const { receipt } = await groove.mutateBalance({
-  customerId: verifiedCustomer.id,
-  command: {
-    operation: "consume",
-    entitlementId,
-    quantity: "1",
-    properties: {},
-    idempotencyKey: `job:${job.id}`,
-  },
-});
-```
-
-后端使用 `consume`、`reserve`、`confirm`、`release`、`refund`。每次重试保留原输入和幂等键，确认、释放与退款引用原操作 ID。写入需要 `credits:consume`；退款另外需要 `credits:manage`。当前余额执行仅开放明确的 Sandbox 范围。
-
-## 积分、用量与计费
-
-以下接口需要与 SDK 协议匹配的 Grow 部署。SDK 包验证与发布不会自动升级既有宿主；数据库、Stripe、原生商店和部署各自的验收结果以对应回执为准。
-
-### 周期积分、消费分析与批量用量
-
-接口与验收边界见 [积分能力补齐](../../docs/credit-expansion.md)。在可信服务端使用：
-
-```ts
-const { entity } = await grow.manageUsageEntity({
-  customerId,
-  command: { action: "upsert", externalId: "workspace-a", name: "Workspace A" },
-});
-const requestId = crypto.randomUUID(); // 保存这个逻辑批次的身份，重试时复用
-const { batchId } = await grow.submitUsageBatch({
-  requestId,
-  items: [
-    {
-      customerId,
-      command: {
-        operation: "consume",
-        entitlementId,
-        entityId: entity.id,
-        quantity: "1",
-        properties: { model: "alpha" },
-        idempotencyKey: "generation-001",
-      },
-    },
-  ],
-});
-const { batch } = await grow.readUsageBatch({ batchId, after: -1, limit: 100 });
-// queued 只表示等待执行；逐条检查 accepted / rejected / failed 及 receipt。
-// 后续页使用 batch.nextAfter；整个批次没有跨功能事务语义。
-const { analytics } = await grow.readCreditAnalytics({
-  customerId,
-  query: {
-    range: {
-      kind: "absolute",
-      from: "2026-10-01T00:00:00Z",
-      to: "2026-10-08T00:00:00Z",
-    },
-    timezone: "UTC",
-    filterBy: [],
-    interval: "day",
-    groupBy: "properties.model",
-    entitlementId: null,
-    after: null,
-    limit: 100,
-  },
-});
-```
-
-`manageUsageEntity` 需要 `credits:manage`；批量提交需要 `credits:consume`，读取和分析需要 `credits:read`。批次最多 1,000 条，入队后返回 HTTP 202，每条事件保留独立消费凭据。相同 `requestId` 的重试必须保留完整输入；修改内容会冲突。分析保留 `entitlementId` 与 `resourceId`，不同计量单位不能直接相加，`charged` 等字段是积分数量。
-
-批量消费可指定 `command.occurredAt`；只允许当前 UTC 月内且不晚于服务器当前时间的事件。该时间用于事件归属，不回溯重算已结算账期或过去套餐的额度与费率。相对分析范围可用 `last_days` 或客户的 `billing_cycles`；读取后续页时，将 `range` 固定为返回的 `analytics.from` / `analytics.to`（`kind: "absolute"`），并传入 `analytics.nextCursor`，避免相对日期窗口在分页时移动。小时分桶使用 UTC，其余分桶使用查询的 IANA 时区。
-
-服务端 AI SDK v7 的自动 Token 采集用 `createAiUsageMiddleware`，必须提供每次上游调用的持久幂等键与 usage/quote 存储回调。生成和流式最终用量均使用原报价一次扣减；失败恢复直接重放扣款，避免重跑模型。`readBillingInvoice`、`readCreditStatement` 提供分页逐项账单和精确来源／退款明细。接入代码、时间范围与当前边界见 [积分接入](../../docs/credits-integration.md)。后续协议扩展须单独发布并匹配服务端部署。
-
-### 余额规则、状态同步与 AI 配置
-
-Server SDK 的 `readBalanceSource` / `adjustBalance` 在读取精确可用余额后以 `expectedAvailable` 增减或 `set_remaining`；保留预扣、已消费及付款依据。独立 `manageBalanceGrant` 的创建／更新使用当前 `rollover`、`nextResetAt` 字段，`amount: null` 表示无限额度，不能与结转组合。没有旧输入兼容。
-
-非消耗型的实际状态也通过当前客户的 `readHoldings()` 返回（`entitlements:read`）：每行必含可空 `usage`；非消耗型的 `usage` 含实际占用、总容量、带符号剩余量及修订号，其他类型为 null。无限容量的 capacity / remaining 为 null，超容量的 remaining 为负；available 始终非负。指定 Entity 只计算其独立非消耗型容量。
-
-非消耗型 metered 权益使用绝对状态同步，读取需要 `credits:read`，设置需要 `credits:manage`：
-
-```ts
-const { usage } = await grow.readUsage({
-  customerId,
-  query: { entitlementId, entityId: null },
-});
-await grow.setUsage({
-  customerId,
-  command: {
-    entitlementId,
-    entityId: null,
-    quantity: "12",
-    expectedRevision: usage.revision,
-    idempotencyKey: durableSyncId,
-    properties: {},
-  },
-});
-```
-
-`createConfiguredAiPricing(grow, { entitlementId })` 从已发布权益读取控制台 AI 模型／加价配置，入口为 `@tinkerlandai/indiana-sdk/server`。支持负加价和显式免费价格，免费调用保留真实 Token 的零金额事件。`createOpenRouterUsageClient` 从独立入口 `@tinkerlandai/indiana-sdk/openrouter` 导入，包装当前 `@openrouter/sdk` 的 `chat.send`，自动捕获生成／流式 Token，先持久保存 usage／原报价，再原子扣款；需要宿主提供 `context`、`persist` 和明确的推理计价方式。只有使用该入口的应用需要安装可选 peer dependency `@openrouter/sdk`；普通服务端入口的类型不引用它。示例及缺失价格、取消流、并发冲突和恢复语义见 [当前接入](../../docs/credits-integration.md)。
-
-### 新购订阅选择优惠券
-
-先通过 `redeemCoupon` 或发放获得持券，再用 `listOffers` 查询；将所选持券的 `id` 传入 `previewAttach.offerId`，不是 Coupon 定义 ID。仅新购 Stripe Checkout 支持此输入，首次结账最多一张券；已有订阅使用现有订阅优惠操作。
-
-```ts
-const { quote } = await groove.previewAttach({
-  requestId: crypto.randomUUID(),
-  plans: [{ productVersionId }],
-  provider: "stripe",
-  currency: "USD",
-  offerId: selectedOffer.id,
-});
-// 向客户展示 quote.discount 的条款、amountMinor 和逐套餐 allocations。
-// quote.catalogAmountMinor 是原价，自动税额在原生 Checkout 中确认。
-const { operation } = await groove.attach({ operationId: quote.operationId });
-```
+Live 商业执行仍有显式服务端门禁。其他 Product／Price、Entity、订阅追加和数量组合，以匹配服务端的实际能力为准；不自动回退到旧实现。
 
-报价固定客户、环境、商品版本、币种和持券；修改选择必须使用新的 requestId 重新报价。接受时重新核对资格及持券占用，重复确认恢复原订单。只有原生支付验证才能产生核销和付费权益。
+## AI 用量
 
-## 0.0.1 范围与验收边界
+`/server` 提供 AI SDK 用量中间件；`/openrouter` 提供 OpenRouter 包装器。宿主必须提供每次调用的持久幂等键、usage／quote 存储及恢复回调。恢复时重放原报价的扣款，不重新运行模型。密钥始终留在可信后端。
 
-本版包含下列 Web／TypeScript 接口及行为。原生配套包、数据库与服务部署按各自回执判断：
+## 发布与验收
 
-- 宿主句柄也支持 `handle.resume(originalRequestId)`，可在原命令已经完成后回读同一回执；无参数时恢复当前服务端待处理请求。`close()` 等待正在提交的命令完成，再持久化关闭，提交失败会继续向宿主抛出错误。 旧个人包 `0.0.7` 不代表具备相同语义。
-- 本版包含独立商店路径的 Web 契约；Swift／Kotlin 配套包另行发布：`previewAttach`／`previewUpdate` 固定订阅操作后，Swift／Kotlin 的 `purchaseSubscription`／`switchSubscription` 获取实际商店报价并购买；`restorePurchases` 扫描当前购买，通过 `POST /api/v1/subscriptions/native/restore` 恢复，不要求本地保留原订单绑定。后端仍须校验当前客户会话；商店购买链与账户关联决定归属，客户端的意图或客户 ID 不能转移购买。独立恢复要求 `billing:write`，已知 Funnel 订单的回执恢复仍使用上面的协议。候选迁移、本地替身验证与真实验收边界见[第八批记录](../../docs/subscription-core-phase8.md)。
-- 本版的预付 Feature 数量接口：`previewAttach` 的每个 plan 可传 `featureQuantities: { [entitlementVersionId]: quantity }`；`previewUpdate` 使用 `change: { type: "quantity", entitlementVersionId, quantity }`，再通过同一 `update` 确认。Swift／Kotlin 对应 `previewQuantityUpdate`。增加数量可立即付款生效，减少数量使用 `renewal`；重试保留原 requestId。服务端根据不可变套餐条款和实际计费项交付额度。此项支持 Stripe，Apple／Google 仍使用固定已发布 SKU，不能传可变数量替换商店价格。详见[第九批记录](../../docs/subscription-core-phase9.md)。
-- 本版客户资料使用 `attributes`，属性删除使用 `removeAttributes`，标签增减使用 `tagChanges`；旧个人包 `0.0.7` 保留原 `metadata` / `tags` 契约，不能向旧包传入当前新字段。
-- 本版浏览器和服务端提供 `createFeatureClient` 与 Feature 评估契约，见[实施记录](../../docs/experiments-growthbook-port-plan-2026-10-11.md)。该导出不在旧个人包 `0.0.7` 的类型入口中。
+npm 发布不部署 Web 服务、不应用数据库迁移，也不发布 Swift／Kotlin 包。安装消费、类型、离线单元和构建检查，与真实 Auth／RLS、Stripe、原生商店、浏览器和线上部署分别记录；局部通过不代表整套产品验收。
 
-发布产物和检查结果见 [发布总账](../../docs/sdk-releases.md)。本次按用户要求跳过浏览器验证；真实 Auth/RLS、Stripe、原生商店与部署验收未执行，npm 发布不代表这些验收已通过。
+版本、冻结产物哈希和 registry 回读见 [发布总账](../../docs/sdk-releases.md)；当前架构与实现边界见 [开发状态](../../docs/development-status.md)。