client: `environments.delete` still documents a one-call cascade delete and has no `purge` option — once the hosted cloud enforces ADR-0014's two-step delete, SDK users can archive but never purge

[hotlong]

现象

packages/client/src/index.ts（origin/main）的 environments.delete：

/**
 * Cascade-delete an environment: cleans up credential/member/package_installation
 * rows, releases the physical database via the provisioning adapter, and
 * removes the `sys_environment` row. Default environments require `force: true`.
 */
delete: async (id: string, opts?: { force?: boolean }) => {
  const qs = opts?.force ? '?force=1' : '';

为什么现在要改

托管云的 DELETE /api/v1/cloud/environments/:id 正在改为遵守 ADR-0014 的两步删除（objectstack-ai/cloud#2187，PR objectstack-ai/cloud#2188）：

• 活跃环境 → 归档（响应 archived: true，保留期内可恢复）
• 已归档环境 + ?purge=1 → 才真正拆除
• ?force=1 只是「确认这是生产环境」，永远不等于 purge
• DELETE /cloud/organizations/:id 在组织名下仍有任何环境时返回 409

该 PR 合并后，这个客户端方法会出现三处与线上不一致：

1. JSDoc 说谎：写的是「级联删除、释放物理库、删除行」，实际对活跃环境只归档
2. 缺 purge 选项 ⇒ SDK 用户完全无法 purge：opts 只有 force，而服务端明确拒绝把 force 当 purge（重试一次 ?force=1 就毁掉环境，正是两步删除要防的事故）
3. 返回类型不完整：缺 archived、purgeDeferred、retentionDays

验收

1. opts 增加 purge?: boolean → ?purge=1；force 与 purge 可同时传（生产环境拆除需要两者）
2. JSDoc 按两步语义重写：活跃环境归档、purge 仅对已归档环境生效、force 是生产确认而非 purge
3. 返回类型声明 archived、purgeDeferred、retentionDays（以服务端实际响应为准，勿凭文档臆造字段——见同文件注释里记录过的 credential 教训）
4. 若客户端文档站有该方法的页面，同步更新

顺序

等 objectstack-ai/cloud#2188 合并后再开工，以服务端实际响应形状为准。

[hotlong]

Claim: maintainer direct dispatch (cloud ops session, incident follow-up)
Session: c5c0ce54-bb9c-478c-9e5b-cf44b80d4569
Time: 2026-09-11T06:54Z
Branch: claude/issue-17636-client-environments-delete-purge
Worktree: ~/Documents/GitHub/objectstack-issue-17636
Domain: domain:cloud
File surface: packages/client/src/index.ts (environments.delete: purge option, JSDoc, return type) + its tests; client docs page if one exists
Unblocked by: objectstack-ai/cloud#2188 merged at eeac7b22b — the server response shape is now fixed on cloud main.
No overlap with the in-flight #17634 seat (service-messaging only).
Clause-②: no — additive optional client parameter + doc/type correction; no packages/spec/src/** surface expected (path limb re-checked on the actual diff at review)

[hotlong]

os-dev-report
{
"issue": 17636,
"status": "done",
"branch": "claude/issue-17636-client-environments-delete-purge",
"pr": "#17642",
"premise_still_valid": true,
"summary": "environments.delete in packages/client/src/index.ts gains opts.purge (sent as ?purge=1, independent of and combinable with force), its JSDoc now describes the ADR-0014 archive-then-purge semantics instead of a one-call cascade, and its return type is the discriminated union of the route's two 200 answers as read from cloud origin/main eeac7b22b (archive: environmentId, deleted false, archived true, purgeDeferred, retentionDays, warnings, message; teardown: environmentId, deleted true, purged true, warnings). organizations.delete's JSDoc claimed organization-plugin hooks tear down environments; no such hook exists in either repo, so that sentence is replaced (JSDoc only, no behaviour change). The card's premise holds against cloud origin/main, with one divergence recorded under deviations: organizations.delete calls better-auth POST /api/v1/auth/organization/delete, not cloud DELETE /api/v1/cloud/organizations/:id (the route that answers 409). Changeset graded minor; assignee was already set at dispatch and was not touched.",
"tests": "All runs at HEAD 0dc8666, equal to the pushed tip. os-verify-lock ran in DECLARED UNLOCKED MODE (macOS, no flock; disclosed in the PR body). (1) pnpm exec turbo run build --filter=@objectstack/client --concurrency=2 gave 'Tasks: 33 successful, 33 total', VERDICT command-exit 0. (2) pnpm --filter @objectstack/client test gave 'Test Files 42 passed (42)', 'Tests 506 passed (506)', VERDICT command-exit 0. (3) pnpm --filter @objectstack/client typecheck gave 'check:test-typecheck: OK', 0 file(s) / 0 error(s), VERDICT command-exit 0; tsc -p tsconfig.test.json --noEmit --listFiles exited 0 and listed the new test file once. (4) vitest run --reporter=verbose src/environments-delete-two-step.test.ts gave 'Tests 14 passed (14)': 8 option combinations, id encoding, archive relay, deferred-purge relay, teardown relay, refusal rejects with code and httpStatus, anti-vacuity. (5) Ablation from the committed state, restored with git checkout HEAD on the absolute path and proven by hash match with the HEAD blob a2631376 plus git diff HEAD exit 0: runtime leg (the purge line removed) gave 'Tests 4 failed | 10 passed (14)'; type leg (retentionDays removed from the archive member) gave tsc exit 2 with TS2339 at environments-delete-two-step.test.ts(55,42) and (170,23). (6) node scripts/pm/dispatch-gates.mjs --commands derived 60 families; all run and recorded with exit codes; --ran gave '60 derived famil(ies) accounted for, 58 run, 2 NOT-MEASURED'. Named gates: pnpm check:nul-bytes OK; pnpm check:adr-0087-registration 'this PR adds no declared-breaking changeset (1 non-breaking changeset(s) seen)'; node scripts/check-changeset-no-major.mjs 'no major bump', level axis not applicable locally; pnpm --filter @objectstack/spec run check:skill-examples, after building client-react, '258 prose examples type-check across 3 surface(s)'. NOT MEASURED: pnpm check:dual-build-cjs-loads and pnpm check:type-check-debt, both PREREQUISITE NOT MET exit 3, each needing a whole-workspace build the dispatch excludes. (7) Narrowed eslint --no-inline-config --format json on the 2 changed TS files: exit 0, 2 files, 0 errors, 0 warnings; eslint.config.mjs enables no type-aware linting, so untouched files cannot move.",
"mcp_calls": "0 (all GitHub reads and writes went through git and the gh CLI)",
"open_questions": [],
"out_of_scope_findings": [
"reported for PM to file (cloud repo, contract text quoted): cloud packages/service-cloud/src/environment-deletion-policy.ts says an archived environment deleted again without purge is 'a repeat delete is an idempotent no-op', but environment-lifecycle.ts re-runs the archive branch (:1785-1840) for it, re-stamping metadata.archived_at (restarting the retention clock) and writing another audit row. Never destructive.",
"noted, not filed: cloud packages/service-cloud/src/cloud-route-ledger.ts:185 says the SDK sends force only and cannot purge; stale once PR 17642 lands and cloud pins past it. Carrier: that cloud pin bump.",
"noted, not filed: the SDK has no archive or restore method (cloud ledger rows for those routes are gap). Carrier: none."
],
"server_response_branches": [
"route: packages/service-cloud/src/routes/environment-lifecycle.ts:1930-1945 at cloud eeac7b22b; flags read by isDeleteFlagSet (:1711-1712, accepts true, 1, 'true', '1') from req.query.force and req.query.purge (:1940-1941)",
"401 no caller: routes/types.ts:200, reached from :1931",
"400 empty id: :1933",
"404 unknown id: :1935",
"gate assertEnvAdminOrCreator (:1312): 409 environment has no organization_id :1326; 503 no control driver :1329; 404 caller not a member of the environment's organization :1338; 403 member who is not owner/admin/creator :1347",
"409 system environment: :1769-1771",
"409 production environment without force: :1773-1778 (classifyEnvironmentType, plan-entitlements.ts:767: explicit environment_type, else legacy is_default)",
"mode: decideEnvironmentDeletionMode, environment-deletion-policy.ts:44 (failed tears down :49; archived tears down only with purge :53; anything else archives :57)",
"archive path, metadata CAS failure: 503, 500, 404 or 409 at :1799 (from :639, :656, :660, :666)",
"200 archive: :1822-1839 { environmentId, deleted: false, archived: true, purgeDeferred (equals purge, :1818), retentionDays (ENV_RETENTION_DAYS, 30, environment-deletion-policy.ts:32), warnings: [], message }",
"503 teardown path, provisioning service unavailable: :1843-1844",
"200 teardown: :1886 { environmentId, deleted: true, purged: true, warnings }",
"teardown throws: 409 if the message names a system or default environment, else 500, :1887-1891",
"envelopes: ok() is { success: true, data } at cloud-artifact-helpers.ts:107; fail() is { success: false, error: { code, message, httpStatus } } at cloud-artifact-helpers.ts:141",
"cloud's own route pins agree: test/environment-delete-route-two-step.test.ts lines 325, 343, 355, 384, 397, 403, 416, 429, 444"
],
"acceptance": [
"1 purge sends ?purge=1 and combines with force: 8 option combinations plus id encoding pinned (tests 4); runtime ablation reds 4 of 14 (tests 5)",
"2 JSDoc rewritten: archive (recoverable within retentionDays), purge only on an archived environment (deferred on a live one), force is the production confirmation and never a purge, failed torn down in one call, refusals reject",
"3 return type is exactly the two 200 bodies: typed-local and ts-expect-error pins, compiled (listFiles), type ablation reds with TS2339",
"4 docs: no page documents environments.delete; grep over content/, apps/docs/, skills/, packages/client/README.md gives 0 hits; content/docs/api/client-sdk.mdx names the namespace only at lines 18 and 158; nothing to sync",
"5 organizations.delete: JSDoc claimed hook-driven environment teardown; plugin-auth organizationHooks (packages/plugins/plugin-auth/src/auth-manager.ts:2951) declares no delete hook and git grep for beforeDeleteOrganization or afterDeleteOrganization finds 0 hits in objectstack packages//src and cloud packages/*/src; sentence replaced, no other method touched"
],
"spec_touched": "no: the diff is .changeset/client-environments-delete-purge.md, packages/client/src/index.ts and packages/client/src/environments-delete-two-step.test.ts; no packages/spec/src/ path and no contract accept/reject behaviour change, so the claim's Clause-2 no holds on the actual diff",
"deviations": [
"PR body first line is 'Fixes #17636' (the os-dev.md form) rather than the dispatch's 'Closes #17636'; the closing effect is identical and os-dev.md governs where the two conflict; check-closing-keyword-parity --body binds only 17636",
"premise divergence on acceptance 5: the dispatch took organizations.delete to be the cloud 409 route; it calls better-auth instead, and its JSDoc was corrected for its own false claim",
"commit trailers are the model-free pair AGENTS.md requires, not a model-named Co-Authored-By",
"os-verify-lock ran in declared unlocked mode on this macOS host; disclosed in the PR body",
"changeset graded minor (WHICH LEVEL: additive widening of a published method), not patch; non-breaking, so no ADR-0087 marker"
]
}

---

Generated by Claude Code

[hotlong]

PM 收尾（Session c5c0ce54）：已落地

• PR feat(client): environments.delete gains purge and documents the two-step delete #17642 于 2026-09-11T08:17:28Z 合并，merge commit 1c4270fa7。
• 落地核对：merge commit 的文件集与 PR 的 3 个文件逐一相同，没有丢失补推。
• 客户端 SDK 的变化：
  • environments.delete(id, { force, purge }) 可以传 purge；
  • 返回类型分成「归档」和「拆除」两种，字段与服务端的两种响应体一致；
  • organizations.delete 的 JSDoc 改为如实描述：要先逐个删除环境。

消费端：cloud 在下一次 bump 框架 pin 时拿到这一变化，届时要顺带改的一处已记在 cloud 的对应卡上。