ADR-0130 D4:产物 schema 增加可选 packages[] 列表,两种形态都读,分段加载键位结构性预留

[os-sam]

实现 ADR-0130(docs/adr/0130-release-artifact-as-co-ownership-boundary.md)D4,epic #14122 实现面第 1 行——本卡是全链的先行卡,行 2/3/4 均依赖它。

要求(单源在 ADR-0130 D4,此处只列判据)

1. ObjectStackDefinitionSchema(packages/spec/src/stack.zod.ts:240 一带)新增可选 packages: [...] 键;manifest(单数)保留。
2. 读取语义:有 packages 则遍历;无则把 manifest 当单元素列表——schema 形状本身就是兼容机制,⛔ 不是替换。
3. 分段加载键位结构性预留:packages[] 元素恒为对象,永不是拍平内联的 manifest 体——未来 {ref, integrity} 外部分段是加键不是改形。⛔ 不实现分段本体(ADR-0130 Non-goals)。
4. 前向兼容走既有 manifest.engines.protocol(ADR-0025),⛔ 不引入新版本协商机制。
5. os compile/os build 写出侧(packages/cli/src/commands/compile.ts:271 解析、:596 写出)对齐 schema;编译产物默认行为不变(单包工程照旧写 manifest)。

Clause-②

packages/spec/src/** 命中路径肢;公共面扩宽(新增可选键)属实 ⇒ 自报 yes,挂 needs:contract-review,PR 恒 draft 待复审。

验收

• 存量单 manifest 产物 parse 结果逐位不变;
• 新增键为可选,现有产物与调用方零改动通过全部既有测试;
• 换档:minor(扩宽零收窄,无 BREAKING 横幅)。

[os-sam]

Claim

• Session: session_015adLit3ZYASJiXwxKG78Wi (dispatching PM / director seat)
• Branch: claude/issue-14161-artifact-packages-schema
• Scope: ADR-0130 D4 schema half only — optional packages[] on ObjectStackDefinitionSchema + os compile write-side alignment. Load-path iteration (ADR-0130 D5+D7:装载路径按拓扑序注册物内 N 包(复用 resolvePluginOrder)+ 存量产物逐位相同测试 #14162) and the installPackage gate (ADR-0130 D1+D3:installPackage 命名空间闸认同物共同所有者 + 安装期对象名唯一性检查(同 PR 机器不可拆) #14163) are out of scope here.

Starting now in a dedicated worktree. Assignee left as set by the PM.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

os-dev-report

{
 "issue": 14161,
 "status": "done",
 "branch": "claude/issue-14161-artifact-packages-schema",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/14191",
 "premise_still_valid": true,
 "summary": "ObjectStackDefinitionSchema gains an optional `packages` key (ADR-0130 D4); `manifest` is retained and both shapes are readable. Each entry is a strict WRAPPER object carrying its manifest under `manifest:`, never a flattened manifest body — the reservation that keeps a future `{ref, integrity}` segment an additive key instead of a reshape. Segmented loading, the D5 load-path iteration (#14162) and the installPackage gate (#14163) are untouched. `os compile`/`os build` needed NO source change: normalize, lower and write each shallow-clone the top level and validation parses with this schema — measured by compiling real projects and reading the artifact off disk, not argued from source. Two mechanical consequences a new top-level key carries were handled in the same change: a `COMPOSE_KEY_DISPOSITIONS` entry (`packages: 'concat'` — the table is total, so it will not compile otherwise) and a declared `NON_COLLECTION_ARRAY_KEYS` exception in scripts/check-stack-collection-maps.mjs, whose extractor would otherwise have counted `packages` as a metadata collection and manufactured eight simultaneous deviations. PR is DRAFT with needs:contract-review attached (Clause-2 YES: packages/spec/src path limb + public-surface widening).",
 "tests": "All readings on the FINAL commit a16839529, tree clean, exit codes captured before any pipe. (1) EVERY runnable step of lint.yml's `Lint & Repo Gates` job, harvested from the workflow itself — 132 steps, setup excluded — ALL GREEN. This harvest earned its keep: it caught `check:spec-parsed-alias` (ADR-0122) which the path derivation did NOT name — `ArtifactPackageEntry` needed a paired `ArtifactPackageEntryParsed` because ManifestSchema applies defaults, so z.input and z.infer genuinely differ; fixed in the second commit and the step is green. (2) dispatch-gates --repo objectstack-ai/objectstack --commands: all 56 derived commands, 55 green + 1 NOT MEASURED (`check-test-completeness` exits 3 by design with no CI test-run log to parse; its own text says 'It is not a red'). Four more first reported exit 3 / PREREQUISITE NOT MET against a partially built tree and all re-ran GREEN after `turbo run build --filter=./packages/* --filter=./packages/*/*`: check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt, check:type-check-coverage. (3) packages/spec full suite 449 files / 12072 passed / 1 skipped; `pnpm --filter @objectstack/spec typecheck` (src + scripts + tsconfig.test.json) green. (4) packages/cli: the new e2e plus three sibling compile-path suites, 4 files / 25 passed; `pnpm --filter @objectstack/cli typecheck` 0 errors — an earlier reading of 66 errors was entirely TS7016/TS7006 cascade from declarations my own OS_SKIP_DTS=1 closure build had skipped, ZERO naming any file in this diff. (5) check-governed-merges --test over the FINAL 7-path file list: NOT governed, 0 of 7 hit the register. (6) check:generated green after regenerating api-surface/ and export-origins/ from a full dts build (+1 line each). ABLATION — mutated `packages: z.array(ArtifactPackageEntrySchema)` to `z.array(ManifestSchema)`, the flattened shape D4 forbids. Rebuild status: NONE REQUIRED AND NONE DONE, stated deliberately — the subject test imports './stack.zod', a package-relative path resolving to SOURCE rather than through exports to dist, so a stale dist cannot make this ablation falsely green. Mutation confirmed ON DISK before any reading, both directions counted: wrapper form remaining 0 (expected 0), flattened form present 1 (expected 1), plus a non-empty `git diff --stat`. Result exit 1, 6 failed / 11 passed of 17 — red included the reservation pin, the no-manifest pin, and the future-segment pin. Restore leg proved by BYTES not by exit code: `git checkout HEAD -- ABSOLUTE-PATH` (naming HEAD, never a bare --), then `git diff HEAD` empty and `git hash-object` equal to the HEAD blob, both 374e92fb5cd0c8db349af2084e9e2cba567c5461; the script carried `trap ... EXIT INT TERM`. The ablation also produced an unplanned finding: under the flattened shape `{ref, integrity}` parses GREEN with both keys silently dropped, because ManifestSchema is not strict — which is a second, independent argument for the wrapper, and the thread that led to the finding filed below.",
 "mcp_calls": "6 — issue_read(get), issue_read(get_comments), add_issue_comment(claim), create_pull_request, search_issues(one targeted dedup query), issue_write(create #14192). This report comment is the 7th. Bulk reads went through git and the local checkout; the label write went through the additive REST POST endpoint (probed first: repo-scoped REST read returned 200), with a compare read-back confirming `needs:contract-review` survived beside the size-labeler's `size/l`.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #14192: `ManifestSchema` strips unknown keys silently — a `namesapce` typo inside `manifest:` parses green, is dropped, and `manifest.namespace` comes out `undefined`; the strictness ledger covers kernel/manifest.zod.ts with a directory-level `wire — code-to-code` verdict that manifest: outgrew, the same shape as the expired-verdict finding the ledger's own api/ row records. Searched first (one targeted search_issues; no open duplicate, and the query returned relevant domain:spec strictness hits so it was not a dead read). Unassigned, unlabelled for PM triage."
 ]
}

Notes not belonging in the JSON:

• ADR-0130 D4's anchors were all re-verified against the branch base 682d03ba7 and all held exactly — stack.zod.ts:240, compile.ts:271 (parse) and :596/:597 (write), build.ts as a subclass of Compile. Nothing needed correcting, so §7 of the ADR gains no new row from this card.
• The PR body carries a duplicated signature footer: the platform appends its own session-URL footer on create. It is left as-is deliberately, because a PATCH to remove it demotes the session-URL form to the bare form and costs the durable attribution.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

契约复审(总监席,会话 session_015adLit3ZYASJiXwxKG78Wi;保险丝:本场 get_session 机读 = claude-fable-5 = CONTRACT_REVIEW_TIER)

VERDICT: PASS
REVIEWED-HEAD: a16839529 (PR #14191)
CLAUSE-2-PATH: yes — packages/spec/src/stack.zod.ts +107(源),api-surface/export-origins 各 +3(再生成)
CLAUSE-2-CONTENT: yes — 纯扩宽零收窄:新导出 ArtifactPackageEntrySchema + ArtifactPackageEntry/…Parsed(ADR-0122 配对齐全);ObjectStackDefinitionSchema 新增可选 packages 键;COMPOSE_KEY_DISPOSITIONS += packages:'concat'(表全量性所需,语义正确)
FINDINGS: 无阻断。
- 与 ADR-0130 D4 逐条吻合:wrapper 元素(manifest 居于 manifest: 键下,strictObject 拒绝拍平形态并在 history 里给出改写指引)、packages 可选且无 .default([])(「不物化新顶层键」有专门 pin,compile 输出逐字节不动)、manifest 保留、前向兼容引 engines.protocol ⛔ 无新机制、分段加载只留结构预留。
- 范围纪律:D5 装载(#14162)与 D1/D3 闸(#14163)零触碰;composeStacks preserve 明确注记留给 #14164;CLI 侧实测零源码改动(spread 透传,e2e 证实)。
- 消融证据超预期:拍平形态下 {ref,integrity} 会被 ManifestSchema 静默吞掉——wrapper 的第二条独立论证;顺带产出 finding #14192(ManifestSchema 非 strict 的账面缺口),已按只记录规则立案。
- 换档核对:spec minor 无 BREAKING 横幅,正确(可选键扩宽,与 ADR-0044 落 returned 同形)。

清标即落地:PR 侧 needs:contract-review 同笔摘除(读-改-写单标);CI 全绿后转 ready 入队,合并即解锁 #14162/#14164 接续派发。

---

Generated by Claude Code