docs(qa): qa-scratch-authz declares the qa namespace its object names carry - #26875

Requested by Warren · project thread
Fixes #26791

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:areas/attachments-storage.json 的配方 qa-scratch-authz 第 1 步安装清单声明 namespace: "qa";用到该配方的三个条目 revision 各升一级(7、9、9)并加一行 history。
• 为什么改:实测照原文重放,安装把命名空间推成 attachments,第 2–4 步建对象全部 422 NAMESPACE_PREFIX,三个条目的鉴权子句只能记 blocked(fixture)。
• 风险与回滚:只改 QA 台账一个 JSON 文件,不动产品代码;对象名不变,其余步骤与条目子句一字未动;回滚即 revert 本 PR。
• 先看:docs/qa/platform-checklist/areas/attachments-storage.json 顶部配方的 step 1 与 provenance,再看三个条目 history 的最新一行。
• 两分钟验证:node scripts/check-platform-checklist.mjs,预期 OK。
• 需要你做的:无,席位落地。

What changes

• qa-scratch-authz step 1 (POST /api/v1/packages) now declares manifest.namespace: "qa". Its expect says why the namespace is declared and that it must be unique on the boot; its source cites the namespace derivation and the prefix judge.
• The recipe's provenance records the replay below.
• The three items that opt into the recipe each take a revision and a history row citing qa(checklist): the attachments-storage qa-scratch-authz recipe authors un-prefixed objects, which a package save now refuses with 422 NAMESPACE_PREFIX #26791: download-authz-both-sides (6 → 7), read-inherits-parent-rls (8 → 9) and attach-requires-parent-edit (8 → 9). No step or clause sentence changed in any of them.

Why

Read on main 8eef9a8. Every object a package defines must be named NS_SHORT; the direct save asks objectNamespacePrefixViolation (ADR-0129 D2) against the namespace the package declares. A manifest that declares none gets one derived from its id's last segment at install (protocol-package-install.ts, deriveNamespaceFromPackageId), so com.objectstack.qa.attachments became attachments, and qa_vault / qa_shared / qa_nofiles were refused.

The card allowed two fixes: rename the three objects, or declare a namespace their names already carry. Declaring qa changes one line. A rename would touch about 40 mentions across the recipe, step 6's three permission-set bodies and the three items, so the declared namespace was chosen.

Tests

No code changed. The recipe was replayed REST only on two fresh stock showcase boots built from 8eef9a8 (pnpm dev -- --fresh -p PORT, no env posture), with the recipe JSON read from the file and sent literally.

step 1 POST /api/v1/packages -> 201   manifest.namespace "attachments" (derived)
step 2 PUT /api/v1/meta/object/qa_vault?package=com.objectstack.qa.attachments -> 422
   {"error":"Object 'qa_vault' is missing the package namespace prefix. Rename it to 'attachments_qa_vault' (namespace = 'attachments').","code":"NAMESPACE_PREFIX"}
step 3 PUT /api/v1/meta/object/qa_shared?package=... -> 422 NAMESPACE_PREFIX (attachments_qa_shared)
step 4 PUT /api/v1/meta/object/qa_nofiles?package=... -> 422 NAMESPACE_PREFIX (attachments_qa_nofiles)
GET /api/v1/meta/object/qa_vault | qa_shared | qa_nofiles -> 404 each

step 1 POST /api/v1/packages -> 201   manifest.namespace "qa"
step 2 PUT /api/v1/meta/object/qa_vault?package=com.objectstack.qa.attachments -> 200   state active
step 3 PUT /api/v1/meta/object/qa_shared?package=... -> 200   state active
step 4 PUT /api/v1/meta/object/qa_nofiles?package=... -> 200   state active
step 6 PUT /api/v1/meta/permission/qa_att_reader|qa_att_baseline|qa_att_editor?package=... -> 200 each
   (reader and editor carry the security-private-no-readscope advisory the step expects)
GET /api/v1/meta/object/qa_vault | qa_shared | qa_nofiles -> 200 each
teardown DELETE /api/v1/packages/com.objectstack.qa.attachments -> 200   deletedCount 6 (three objects, three sets)

Acceptance notes

• The same refusal hits two sibling recipes this card does not own, measured on the same boot: qa-media-constraints in this file (qa_media under com.objectstack.qa.media, derived namespace media) and qa-feeds-disabled in areas/records-forms.json (qa_nofeeds under com.objectstack.qa.feeds, derived feeds). Both answer 422 NAMESPACE_PREFIX at their object save. They are reported to the seat, not fixed here. Their fix must not declare qa too, or installing both on one boot answers NAMESPACE_CONFLICT.

Verification

Local gates on head 1845844 (main e9e344a merged in), derived by node scripts/pm/dispatch-gates.mjs --commands: 16 families, all exit 0; --ran reconciles 16 derived, 16 run, 0 NOT-MEASURED, 0 UNRUN. check:platform-checklist prints OK — 16 areas, 329 items … provisioning: 8 area recipes, 13 item references resolved … 8/8 recipes referenced. Its first run on 41f0d71 exited 1 on an anchor this PR wrote at a call site (protocol-package-install.ts#deriveNamespaceFromPackageId); 1845844 cites the declaring file instead.

node scripts/check-adr-links.mjs :: exit 0
node scripts/check-adr-links.mjs --self-test :: exit 0
node scripts/check-closing-keyword-parity.mjs :: exit 0
node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0
pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0
pnpm check:ci-filter-parity :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:doc-authoring :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:platform-checklist :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:watch-hint-literal :: exit 0

CI families outside the derived list are left to the PR's check-runs.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic. (not touched)
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes. (no linted file touched)
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. (publishes nothing: skip-changeset)
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (not touched)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.
• The Before Submitting list in CONTRIBUTING.md is done.

Generated by Claude Code