@tinkerlandai/indiana-sdk 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.3.1 — 2026-10-17
+
+- Make English the default package README and include a separately linked Simplified Chinese translation.
+- Update the package and SDK request version identifiers to 0.3.1; wire protocol 0.3 and business behavior are unchanged from the immutable 0.3.0 release.
+
+## 0.3.0
+
+- 0.3.0 uses wire protocol 0.3 for published screen render references. Obsolete 0.2 and its fixed headerless identity are explicitly refused before business execution; no pre-1.0 compatibility adapter is provided. Existing 0.2.0 publication evidence remains immutable.
+- Add `ScreenPreviewHandle.resizeViewport(height)` to resize previews while preserving their active document and interaction state.
+- Keep Funnel background reads separate from the command lock, so polling cannot swallow a screen action. Unchanged GET/shown data preserves the mounted form and selection.
+- Clear a lost-command error when an external `controller.retry()` settles that exact command. A GET before settlement retains the error; unrelated renderer failures remain visible.
+
+- Expose error recovery, retryability, registered business reasons and Retry-After timing on IndianaError. Distinguish unavailable capabilities from missing configuration. Retain HTTP status and request references for non-JSON failures; unknown results, timeouts and lost responses require original-operation recovery and never trigger automatic retries.
+
+- Pause renderer startup deadlines while the host document is hidden, preserving the five-second visible-time budget and cancellation on ready/disposal.
+- Identify the wire protocol and package version with `X-Indiana-Protocol` / `X-Indiana-SDK-Version`; verify advertised successful-response protocols. These changes are not in the immutable published 0.2.0 tarball.
+- Add the stable-major compatibility policy, at least 12 calendar months of predecessor support and 180 days of public notice, with a pinned published-old-SDK/current-server regression gate. Current 0.x still rejects obsolete protocols. See [support policy](../../docs/sdk-versioning-and-support.md).
+
 ## 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.

package/README.md

@@ -1,24 +1,35 @@
 # @tinkerlandai/indiana-sdk
 
-Indiana 的 JavaScript／TypeScript SDK，包含浏览器、Node.js、屏幕渲染与可选 AI 用量集成。`0.2.0` 以 `beta` 标签分发；服务端和数据库必须使用匹配的当前协议。本版本有破坏性变更，不提供旧名称、旧输入或旧数据模型的兼容层。
+[简体中文](./README.zh-CN.md)
+
+Indiana's JavaScript and TypeScript SDK for browsers, Node.js, screen rendering, and optional AI usage integrations. Version `0.3.1` uses protocol `0.3` and requires a matching Indiana server and database deployment.
+
+Protocol `0.3` includes standalone Feature delivery, screen render references, and protocol header validation. Historical `0.2` clients, including requests without a protocol header, are rejected before business operations run.
 
 ```sh
-npm install @tinkerlandai/indiana-sdk@0.2.0
+npm install @tinkerlandai/indiana-sdk@0.3.1
 ```
 
-## 一个 npm 包，五个入口
+## Version compatibility and support
+
+During `0.x`, only the current protocol is supported. Starting with `1.0`, compatibility is preserved within each stable major version. Once the next stable major is published, the preceding stable major remains supported for at least 12 calendar months, with at least 180 days' public notice before retirement. The later deadline applies. See the [support policy](https://tinker.cash/docs/release-notes#support-policy).
 
-| 导入入口                                 | 用途                                                        |
-| ---------------------------------------- | ----------------------------------------------------------- |
-| `@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 资源；不代表商店购买验收   |
+Version `0.3.1` sends protocol and SDK version headers and validates the protocol declared by successful responses. Headerless historical clients retain the fixed identity `0.2`; they do not follow the current protocol automatically. Updating source code does not change an existing npm artifact or deploy a server.
 
-JavaScript 与 TypeScript 共用本包，声明文件随包提供。内部 `@indiana/contracts` 在构建时内联，接入方无需安装私有包。Swift 和 Kotlin 使用各自的包管理生态，不在本次 npm 发布范围内。
+## One package, six entry points
 
-## 从可信后端创建 Customer Session
+| Import | Purpose |
+| --- | --- |
+| `@tinkerlandai/indiana-sdk` | Browser Customer, Funnel, Feature, and standalone Paywall clients |
+| `@tinkerlandai/indiana-sdk/server` | Trusted Node.js backend, Customer Sessions, business writes, and Funnel decisions |
+| `@tinkerlandai/indiana-sdk/popup` | Standalone screen rendering, sanitization, and previews |
+| `@tinkerlandai/indiana-sdk/openrouter` | Optional OpenRouter usage integration; requires its peer dependency |
+| `@tinkerlandai/indiana-sdk/native-shell` | Static Funnel shell assets for native WebViews |
+| `@tinkerlandai/indiana-sdk/page` | Anonymous website URL experiments using a public App environment ID |
+
+The same package supports JavaScript and TypeScript and includes type declarations. Internal `@indiana/contracts` code is bundled; consumers do not install private workspace packages. Swift and Kotlin use their own package ecosystems and are released separately.
+
+## Create a Customer Session from a trusted backend
 
 ```ts
 import { createIndianaServer } from "@tinkerlandai/indiana-sdk/server";
@@ -38,7 +49,7 @@ const { customer } = await indiana.getOrCreateCustomer({
 const { customerToken } = await indiana.createCustomerSession(customer.id);
 ```
 
-Secret Key 仅保存在可信后端。浏览器传入的 Customer ID 不能作为登录证明；将 Customer Token 交给对应的已登录用户。App、Sandbox／Live、Customer、权限和允许来源分别校验。SDK 在内存中持有客户凭据；退出或切换身份时销毁旧视图并清理凭据。
+Keep the Secret Key on your trusted backend. A Customer ID supplied by a browser is not proof of login. Give each Customer Token only to the corresponding authenticated user. App, Sandbox/Live environment, Customer identity, permissions, and allowed origins are checked independently. The SDK holds Customer credentials in memory; destroy the previous view and clear credentials when signing out or changing accounts.
 
 ```ts
 import { createIndiana } from "@tinkerlandai/indiana-sdk";
@@ -49,47 +60,89 @@ const indiana = createIndiana({
 });
 indiana.identify(customerToken);
 const { holdings } = await indiana.readHoldings();
-// 退出账号时：
+// On sign-out:
 indiana.reset();
 ```
 
-Customer 使用原始业务字段；资料更新是部分 patch，没有 Customer revision。Guest 登录到已有 Customer 时返回 `switched: true`，资源和历史保留原归属，接入方应为目标 Customer 创建新 Session／Funnel；不合并旧 Guest 的财务事实。
+Customer updates are partial patches and do not use a Customer revision. When a Guest signs in to an existing Customer, the response reports `switched: true`. Resources and history keep their original owner; create a new Session/Funnel for the target Customer. Guest financial facts are not merged.
+
+## Optional stable fingerprint
 
-## Funnel、Feature 与独立 Paywall
+`fingerprint` is a host-supplied stable deduplication signal, such as an installation identifier. Initialize and retain it before the first Guest/Customer request, independently of login and credentials. Reuse it across Guest identification, account changes and session renewal. The SDK does not collect or generate it.
 
-可信后端通过 `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` 明确拒绝。
+```ts
+// Trusted backend: retain installationSignal independently of login.
+// verifiedUser.id comes from your application's authenticated session.
+const { customer } = await indiana.getOrCreateCustomer({
+  externalUserId: verifiedUser.id,
+  fingerprint: installationSignal,
+});
+// Reuse the signal on Guest creation. Retain guestToken separately for retries.
+await indiana.createGuestCustomer({
+  guestToken: retainedGuestToken,
+  fingerprint: installationSignal,
+});
+```
 
-`createFunnelClient({ customerToken, ...options })` 用于已持有 Customer 凭据的客户端；其 `start()` 不指定 `customer` 或 `customerData`，始终以凭据所属 Customer 运行。响应丢失时保留原编号和输入重试，商业参数放在 `parameters.commerce`。运行有独立的 Run Token，不能据此切换 Customer。
+Indiana keeps the first supplied signal as an environment-scoped hash; later values do not replace it. Missing input is valid and retains per-Customer trial deduplication. `unique_fingerprint` additionally deduplicates the configured Product trial across Customers sharing the signal. Business user IDs do not identify an installation; Customer/Guest/session tokens and request IDs have their own lifecycles and should not be fingerprints.
 
-`createFunnelDecisionClient` 的 `submit/decide` 与 `/server` 的 `createFunnelCampaignClient` 同样使用明确的 `customer` 引用。Campaign 客户端提供显式 `decide/start`；受频率或进行中运行限制时，`start` 返回 `suppressed` 和重试时间，不伪造 Run 凭据。Run 实际展示后才提交 `shown`，不能用页面关闭或本地存储代替持久的展示事实。
+On Web, an independent first-party installation cookie can retain the signal. Clearing it or changing browser storage can produce a new value; sign-out need not reset it. Native hosts persist a random installation signal and define reinstall, restore and reset behavior. This signal is separate from device attestation and authentication. See the [identity guide](https://tinker.cash/docs/identity#fingerprint) for HTTP host examples. Trial conflicts remain generic to clients; retain `X-Request-Id` for server-side diagnosis.
 
-浏览器使用 `createFunnelRunController` 与 `showFunnelRun`。控制器负责当前协议的命令、读取、重试、恢复和订阅；展示句柄提供 `refresh()` 和 `destroy()`。业务操作按当前发布节点委派给服务端，客户端声明或重定向不构成付款证明。
+## Funnel, Feature, and standalone Paywall
+
+A trusted backend calls `createFunnelStartClient().start()` with `funnelId`, a retained `requestId`, `customer`, `locale`, and `parameters`. The Customer reference is `{ type: "id", value: customerId }` or `{ type: "externalUserId", value: verifiedUser.id }`. The latter supports creation-only `customerData` and requires `customers:write`; an existing Customer is not updated. The response includes `customerId`, which your backend can use to issue a Customer Session. Historical start-body `customerToken` and decision-body `customerId` inputs are rejected.
+
+`createFunnelClient({ customerToken, ...options })` is for clients that already hold a Customer credential. Its `start()` omits `customer` and `customerData` and runs as the credential's Customer. After response loss, retry with the same request ID and input. Put commercial parameters in `parameters.commerce`. Each Run has its own Run Token, which cannot switch Customer identity.
+
+`createFunnelDecisionClient.submit/decide` and the server entry's `createFunnelCampaignClient` use the same explicit Customer reference. Campaign `decide/start` operations report durable frequency or active-Run suppression as `suppressed` with a retry time. Report `shown` only after the Run is actually displayed; page closure or local storage cannot replace a durable presentation fact.
+
+In a browser, use `createFunnelRunController` and `showFunnelRun`. The controller handles current-protocol commands, reads, retries, recovery, and subscriptions. Presentation handles provide `refresh()` and `destroy()`. Published nodes delegate business operations to the server. A client assertion or redirect is not payment evidence.
+
+Each Funnel chooses local or remote evaluation. `createFunnelDecisionClient` supports `configuration()`, `features()`, submission, and result reads. `createFeatureClient` identifies configuration by `generation`. Downloaded local rules are visible to clients; use remote evaluation and verified business facts for sensitive decisions.
+
+### Standalone Feature delivery
+
+Explicitly grant a backend Key `features:read` / `events:write` and issue existing Customer/Guest Sessions to browser clients.
+
+```ts
+const flags = await indiana.features({ attributes: { country: "CA" } });
+const enabled = flags.getFeatureValue("new-checkout", false);
+const unsubscribe = flags.subscribe(() =>
+  updateView(flags.isOn("new-checkout")),
+);
+flags.setAttributes({ country: "US" });
+indiana.track("Checkout Viewed", { source: "pricing" });
+await indiana.flush();
+// On page teardown:
+unsubscribe();
+flags.destroy();
+```
 
-Local／Remote 求值策略由每个 Funnel 决定。`createFunnelDecisionClient` 支持当前 `configuration()`、`features()`、提交和结果读取；`createFeatureClient` 以 `generation` 标识配置。Local 下载的规则对客户端可见；敏感决策应使用 Remote 和可信业务事实。
+Flags default to local evaluation; Owner/Admin can switch each flag to server evaluation. Server-evaluated flags deliver only keys and results, using the caller's fallback until the first result arrives. Attribute changes immediately discard old results. List hashes are not a secrecy boundary. Local Funnels cannot depend on server-evaluated flags; mode switches also check active historical Runs. `identify` / `reset` release the previous identity's Feature instances and event queue.
 
-Offering 固定 Product Version 的范围与层级。Paywall 固定已发布 Offering Version，并独立选择显示的 Product 子集、分组、顺序和默认项。`createPaywallStartClient`、`createPaywallSession`、`showPaywall` 使用独立 Paywall Session，不创建占位 Funnel。付款完成后重新查询权益，业务后端仍须重新鉴权并幂等扣减用量。
+Offering pins the Product Version scope and hierarchy. Paywall pins a published Offering Version and independently chooses its displayed Product subset, groups, ordering, and default selection. `createPaywallStartClient`, `createPaywallSession`, and `showPaywall` use a standalone Paywall Session. After payment, read Entitlements again. Your backend still authorizes requests and consumes usage idempotently.
 
-## Web 商业能力与当前服务边界
+## Commercial capabilities and current service boundaries
 
-当前服务端实现了 Customer／Guest、Entitlement 检查、持有与账本读取、用量和余额、Coupon／推荐码、Offering／独立 Paywall，以及配置后的 Stripe Sandbox attach、支付方式收集、订阅验证／更新／退款／Trial 和 License 分配路径。每个操作仍受已配置的支付账号、执行模式、Product／Price 条款和当前实现范围约束；接口存在不表示任意组合已验收。
+The server implements Customer/Guest identity, Entitlement checks, holdings and ledger reads, usage and balances, Coupons/referral codes, Offering/standalone Paywall, and configured Stripe Sandbox attach, payment-method collection, subscription validation/updates/refunds/Trial, and License allocation. Each operation depends on configured payment accounts, execution mode, Product/Price terms, and its implemented scope. An API's presence does not certify every combination.
 
-Stripe 环境的 `autumn` 模式由 Indiana 执行；`record_only` 返回交给商户后端执行的指令。两种模式都从验证后的 Stripe 事实写入财务与权益。支付方式收集本身不产生扣款、Invoice 或额外权益。报价／确认／读取使用各自持久操作 ID；同一请求编号不能更换输入。
+In Stripe environments, Indiana executes `autumn` mode; `record_only` returns instructions for the merchant backend to execute. Both record financial and Entitlement facts from verified Stripe evidence. Collecting a payment method does not itself charge, create an Invoice, or grant extra Entitlements. Quotes, confirmations, and reads retain their durable operation IDs; a request ID cannot be reused with different input.
 
-本 Beta **不认证完整商业功能或生产运行**。当前仍未接通的服务包括：
+This beta does not certify complete commercial or production operation. Remaining service gaps include:
 
-- 订阅批处理。冲突查询／重试已有对应服务，但仍需匹配部署及业务前置条件。
-- Postpaid Billing Authorization、Billing Coupon 列表和账单调整确认。当前 AutoTopup consent 的准备／确认／撤销已有服务，不能据此推定其他授权类型可用。
-- `claimRewardProduct` 的完整交付。
-- Apple／Google 真实商店验收。当前独立购买／恢复的协议及部分服务实现不代表商店已验收；`createNativeReceiptClient().recover()` 使用 `subscriptions/native/restore`，不再发送旧 Funnel 原生恢复命令。
+- Subscription batch processing. Conflict queries and retries have services but still require a matching deployment and business prerequisites.
+- Postpaid Billing Authorization, Billing Coupon lists, and billing-adjustment confirmation. AutoTopup consent preparation/confirmation/revocation is implemented independently.
+- Complete delivery for `claimRewardProduct`.
+- Real Apple/Google store acceptance. Independent purchase/restore contracts and partial services do not certify store acceptance. `createNativeReceiptClient().recover()` uses `subscriptions/native/restore`.
 
-Live 商业执行仍有显式服务端门禁。其他 Product／Price、Entity、订阅追加和数量组合，以匹配服务端的实际能力为准；不自动回退到旧实现。
+Live commercial execution remains subject to explicit server gates. Other Product/Price, Entity, subscription-addition, and quantity combinations depend on the matching server's actual capabilities.
 
-## AI 用量
+## AI usage
 
-`/server` 提供 AI SDK 用量中间件；`/openrouter` 提供 OpenRouter 包装器。宿主必须提供每次调用的持久幂等键、usage／quote 存储及恢复回调。恢复时重放原报价的扣款，不重新运行模型。密钥始终留在可信后端。
+The server entry provides AI SDK usage middleware; the OpenRouter entry provides a wrapper. Your host supplies a persistent idempotency key per invocation, usage/quote storage, and recovery callbacks. Recovery replays the original quoted charge without running the model again. Keep provider keys on your trusted backend.
 
-## 发布与验收
+## Publication and verification
 
-npm 发布不部署 Web 服务、不应用数据库迁移，也不发布 Swift／Kotlin 包。安装消费、类型、离线单元和构建检查，与真实 Auth／RLS、Stripe、原生商店、浏览器和线上部署分别记录；局部通过不代表整套产品验收。
+Publishing to npm does not deploy Web services, apply database migrations, or release Swift/Kotlin packages. Package installation, types, offline unit tests, and builds are recorded separately from real Auth/RLS, Stripe, native stores, browser checks, and hosted deployment acceptance.
 
-版本、冻结产物哈希和 registry 回读见 [发布总账](../../docs/sdk-releases.md)；当前架构与实现边界见 [开发状态](../../docs/development-status.md)。
+See the [SDK release ledger](https://github.com/tinkerlandai/Indiana/blob/main/docs/sdk-releases.md) for versions and immutable publication evidence, and the [developer documentation](https://tinker.cash/docs?lang=en) for integration guides.

package/README.zh-CN.md

@@ -0,0 +1,149 @@
+[English](./README.md)
+
+# @tinkerlandai/indiana-sdk
+
+Indiana 的 JavaScript／TypeScript SDK，包含浏览器、Node.js、屏幕渲染与可选 AI 用量集成。本包版本为 `0.3.1`，使用协议 `0.3`；服务端和数据库必须使用匹配的当前协议。本版本有破坏性变更，不提供旧名称、旧输入或旧数据模型的兼容层。
+
+**0.3.1 / 协议 0.3** 包含独立 Feature 下发、屏幕 render reference 与当前请求头校验。历史 0.2.0 包不能连接使用协议 0.3 的 HTTP handlers；显式或无版本头的旧 0.2 请求都在业务执行前被拒绝。
+
+```sh
+npm install @tinkerlandai/indiana-sdk@0.3.1
+```
+
+## 版本兼容与支持
+
+当前 0.x 仅支持当前协议；1.0 起同一主版本内保持兼容。新稳定主版本发布后，旧稳定主版本至少继续支持 12 个日历月，停止支持提前至少 180 天公开通知，实际日期取两者中较晚者。详见 [版本与支持政策](../../docs/sdk-versioning-and-support.md) 和公开开发文档 `/docs/release-notes#support-policy`。
+
+0.3.0 发送协议及 SDK 版本请求头，并校验成功响应的协议声明。历史 0.2.0 不发送这些请求头；服务端将无版本头的请求固定识别为 0.2，不自动跟随新协议。源码更新不会修改已有 npm 包，也不会自动部署服务端。
+
+## 一个 npm 包，六个入口
+
+| 导入入口                                 | 用途                                                        |
+| ---------------------------------------- | ----------------------------------------------------------- |
+| `@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 资源；不代表商店购买验收   |
+| `@tinkerlandai/indiana-sdk/page`         | 匿名商户页面的网址实验；使用公开的 App environment ID       |
+
+JavaScript 与 TypeScript 共用本包，声明文件随包提供。内部 `@indiana/contracts` 在构建时内联，接入方无需安装私有包。Swift 和 Kotlin 使用各自的包管理生态，不在本次 npm 发布范围内。
+
+## 从可信后端创建 Customer Session
+
+```ts
+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 indiana.getOrCreateCustomer({
+  externalUserId: user.id,
+});
+const { customerToken } = await indiana.createCustomerSession(customer.id);
+```
+
+Secret Key 仅保存在可信后端。浏览器传入的 Customer ID 不能作为登录证明；将 Customer Token 交给对应的已登录用户。App、Sandbox／Live、Customer、权限和允许来源分别校验。SDK 在内存中持有客户凭据；退出或切换身份时销毁旧视图并清理凭据。
+
+```ts
+import { createIndiana } from "@tinkerlandai/indiana-sdk";
+
+const indiana = createIndiana({
+  baseUrl,
+  scope: { projectId, environment: "sandbox" },
+});
+indiana.identify(customerToken);
+const { holdings } = await indiana.readHoldings();
+// 退出账号时：
+indiana.reset();
+```
+
+Customer 使用原始业务字段；资料更新是部分 patch，没有 Customer revision。Guest 登录到已有 Customer 时返回 `switched: true`，资源和历史保留原归属，接入方应为目标 Customer 创建新 Session／Funnel；不合并旧 Guest 的财务事实。
+
+## Optional stable fingerprint
+
+`fingerprint` is a host-supplied stable deduplication signal, such as an installation identifier. Initialize and retain it before the first Guest/Customer request, independently of login and credentials. Reuse it across Guest identification, account changes and session renewal. The SDK does not collect or generate it.
+
+```ts
+// Trusted backend fragment: installationSignal is retained by the host;
+// verifiedUser.id comes from the host's authenticated login.
+const { customer } = await indiana.getOrCreateCustomer({
+  externalUserId: verifiedUser.id,
+  fingerprint: installationSignal,
+});
+// On Guest creation, use that same installationSignal and separately
+// retain/reuse guestToken for creation retries.
+await indiana.createGuestCustomer({
+  guestToken: retainedGuestToken,
+  fingerprint: installationSignal,
+});
+```
+
+Indiana keeps the first supplied signal as an environment-scoped hash; later values do not replace it. Missing input is valid and retains per-Customer trial deduplication. `unique_fingerprint` additionally deduplicates the configured Product trial across Customers sharing the signal. Business user IDs do not identify an installation; Customer/Guest/session tokens and request IDs have their own lifecycles and should not be fingerprints.
+
+On Web, an independent first-party installation cookie can retain the signal. Clearing it or changing browser storage can produce a new value; sign-out need not reset it. Native hosts persist a random installation signal and define reinstall, restore and reset behavior. This signal is separate from device attestation and authentication. See the Web developer documentation's `/docs/identity#fingerprint` guide for executable HTTP host examples. Trial conflicts remain generic to clients; retain `X-Request-Id` for server-side diagnosis.
+
+## Funnel、Feature 与独立 Paywall
+
+可信后端通过 `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` 明确拒绝。
+
+`createFunnelClient({ customerToken, ...options })` 用于已持有 Customer 凭据的客户端；其 `start()` 不指定 `customer` 或 `customerData`，始终以凭据所属 Customer 运行。响应丢失时保留原编号和输入重试，商业参数放在 `parameters.commerce`。运行有独立的 Run Token，不能据此切换 Customer。
+
+`createFunnelDecisionClient` 的 `submit/decide` 与 `/server` 的 `createFunnelCampaignClient` 同样使用明确的 `customer` 引用。Campaign 客户端提供显式 `decide/start`；受频率或进行中运行限制时，`start` 返回 `suppressed` 和重试时间，不伪造 Run 凭据。Run 实际展示后才提交 `shown`，不能用页面关闭或本地存储代替持久的展示事实。
+
+浏览器使用 `createFunnelRunController` 与 `showFunnelRun`。控制器负责当前协议的命令、读取、重试、恢复和订阅；展示句柄提供 `refresh()` 和 `destroy()`。业务操作按当前发布节点委派给服务端，客户端声明或重定向不构成付款证明。
+
+Local／Remote 求值策略由每个 Funnel 决定。`createFunnelDecisionClient` 支持当前 `configuration()`、`features()`、提交和结果读取；`createFeatureClient` 以 `generation` 标识配置。Local 下载的规则对客户端可见；敏感决策应使用 Remote 和可信业务事实。
+
+### 独立 Feature
+
+后端 Key 显式授予 `features:read` / `events:write`，通过现有 Customer/Guest Session 交给浏览器，不使用新的凭证种类。
+
+```ts
+const flags = await indiana.features({ attributes: { country: "CA" } });
+const enabled = flags.getFeatureValue("new-checkout", false);
+const unsubscribe = flags.subscribe(() =>
+  updateView(flags.isOn("new-checkout")),
+);
+flags.setAttributes({ country: "US" });
+indiana.track("Checkout Viewed", { source: "pricing" });
+await indiana.flush();
+// 页面卸载时：
+unsubscribe();
+flags.destroy();
+```
+
+每个 flag 默认本地计算，Owner/Admin 可切换为服务器计算。服务器 flag 只下发键与结果，首次结果到达前使用调用方默认值；属性变化立即丢弃旧结果。名单哈希不等于保密，敏感规则应使用服务器计算。本地 Funnel 不得依赖服务器 flag，切换时也会校验仍在运行的历史版本。`identify` / `reset` 会释放旧身份的功能实例和事件队列。
+
+Offering 固定 Product Version 的范围与层级。Paywall 固定已发布 Offering Version，并独立选择显示的 Product 子集、分组、顺序和默认项。`createPaywallStartClient`、`createPaywallSession`、`showPaywall` 使用独立 Paywall Session，不创建占位 Funnel。付款完成后重新查询权益，业务后端仍须重新鉴权并幂等扣减用量。
+
+## Web 商业能力与当前服务边界
+
+当前服务端实现了 Customer／Guest、Entitlement 检查、持有与账本读取、用量和余额、Coupon／推荐码、Offering／独立 Paywall，以及配置后的 Stripe Sandbox attach、支付方式收集、订阅验证／更新／退款／Trial 和 License 分配路径。每个操作仍受已配置的支付账号、执行模式、Product／Price 条款和当前实现范围约束；接口存在不表示任意组合已验收。
+
+Stripe 环境的 `autumn` 模式由 Indiana 执行；`record_only` 返回交给商户后端执行的指令。两种模式都从验证后的 Stripe 事实写入财务与权益。支付方式收集本身不产生扣款、Invoice 或额外权益。报价／确认／读取使用各自持久操作 ID；同一请求编号不能更换输入。
+
+本 Beta **不认证完整商业功能或生产运行**。当前仍未接通的服务包括：
+
+- 订阅批处理。冲突查询／重试已有对应服务，但仍需匹配部署及业务前置条件。
+- Postpaid Billing Authorization、Billing Coupon 列表和账单调整确认。当前 AutoTopup consent 的准备／确认／撤销已有服务，不能据此推定其他授权类型可用。
+- `claimRewardProduct` 的完整交付。
+- Apple／Google 真实商店验收。当前独立购买／恢复的协议及部分服务实现不代表商店已验收；`createNativeReceiptClient().recover()` 使用 `subscriptions/native/restore`，不再发送旧 Funnel 原生恢复命令。
+
+Live 商业执行仍有显式服务端门禁。其他 Product／Price、Entity、订阅追加和数量组合，以匹配服务端的实际能力为准；不自动回退到旧实现。
+
+## AI 用量
+
+`/server` 提供 AI SDK 用量中间件；`/openrouter` 提供 OpenRouter 包装器。宿主必须提供每次调用的持久幂等键、usage／quote 存储及恢复回调。恢复时重放原报价的扣款，不重新运行模型。密钥始终留在可信后端。
+
+## 发布与验收
+
+npm 发布不部署 Web 服务、不应用数据库迁移，也不发布 Swift／Kotlin 包。安装消费、类型、离线单元和构建检查，与真实 Auth／RLS、Stripe、原生商店、浏览器和线上部署分别记录；局部通过不代表整套产品验收。
+
+版本、冻结产物哈希和 registry 回读见 [发布总账](../../docs/sdk-releases.md)；当前架构与实现边界见 [开发状态](../../docs/development-status.md)。

package/THIRD_PARTY_NOTICES.md

@@ -17,3 +17,30 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+# @noble/hashes 2.4.0
+
+SHA-256 for hashed saved-group membership is bundled from `@noble/hashes` 2.4.0.
+Source: https://github.com/paulmillr/noble-hashes
+
+The MIT License (MIT)
+
+Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.