Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/specs/2026-08-31-docs-workflow-code-test-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ Do not infer ownership merely from the top-level directory: `content/**` is norm
| Publication diagnostics, exact owned targets, and retired-manifest governance (`packages/docs-tooling/src/publication/diagnostics*`, `packages/docs-tooling/src/publication/retiredManifests*`) | `pnpm vitest run packages/docs-tooling/src/publication/diagnostics.test.ts packages/docs-tooling/src/publication/retiredManifests.test.ts`; cover identity hashing, every separately replaced path, and the finalized deprecated/non-evidence dispositions that keep retired manifests out of publication and provenance inputs | `pnpm test:replay:fetch` | `pnpm test:workflow-policy` + `git diff --check` |
| Evidence equivalence groups (`packages/docs-tooling/src/publication/evidenceGroups*`, matrix entries `evidence-fetch-publication`/`evidence-rest-derivation`/`evidence-translation-publication`, `scripts/docs-workflow/evidence-groups-contract.test.js`) | `pnpm vitest run packages/docs-tooling/src/publication/evidenceGroups.test.ts` and `node --test scripts/docs-workflow/evidence-groups-contract.test.js`; the three matrix group entries must mirror the derived path sets, and every on-disk group path must stay mapped | — | `pnpm test:workflow-matrix` + `git diff --check` |
| Translation fast-path precheck (`scripts/translation/fastpath-precheck*`, `.claude/specs/2026-09-03-translation-fastpath-design.md`) | `node --test scripts/translation/fastpath-precheck.test.js`; cover the evidence-group locale scope (ja Reference and zh Guides allowed, zh REST rejected), inventory restore, manifest regeneration, export-group derivation check, command failures, drift, and stable status codes | — | `pnpm test:workflow-matrix` + `pnpm test:workflow-policy` + `git diff --check` |
| REST OpenAPI fragments, generator, lifecycle evidence, fragment migration inventory, and the zh title table (`packages/docs-tooling/src/reference/rest/meta/openapi/**`, `packages/docs-tooling/src/reference/rest/meta/lifecycle-evidence/**`, `fragment-migration.json`, `titles.json`, `descriptions.json` (the per-category REST intro copy, looked up by the generated category slug `toSlug(tag.name)`, so renaming a tag must rename its entry in the same change), `refGen.js`, `refGen.route-scope.test.js`, `refGen.plane.test.js`, `refGen.lang-filter.test.js`, `includeSpans.js` (shared build-side resolver for `<include>/<exclude target>` prose spans; `refGen.__filter_content` delegates to it), `milvusTargetHygiene.test.js` (projects the real fragment set onto the milvus target — with the wrapper-style primary-tag cascade — and fails on zilliz-only vocabulary: Zilliz Cloud, on-demand compute, serving/Dedicated cluster, serverless, BDU, Public Preview; "usage tracking" is deliberately allowed as a Milvus kernel concept), `specLoader*` (merge + `$ref` resolution; a self-referencing component expands once and stays a `$ref` leaf where it re-enters its own branch), `lifecycle*` (release-track projection: `applyLifecycleForTrack` resolves combinator-branch `required` names against the enclosing object scope, so anyOf/oneOf alternatives may name parent-level properties while lifecycle-omitted names still shrink), `index.js`, `integratedSpecBuilder*` (the exported primary-tag cascade is shared with `milvusTargetHygiene.test.js` and fails closed on undeclared primary tags), `restDerivationManifest*`) | `integratedSpecBuilder`, `integratedSpecArtifacts`, `fragmentCollection`, integrated-spec CLI, completeness-receipt, and REST derivation-manifest tests, plus the refGen route-scope test (flat `/restful/<slug>` uniqueness stays fail-closed for zdoc sites while milvus keys on the physical page path, and the fetch CLI must fail before the derivation manifest or S3 upload on a conflict; it runs inside `pnpm test:rest-publication-contract`, so required CI executes it on every PR), the lifecycle track-projection test (branch-required scope resolution, parent-omission shrinking, dangling names stay fail-closed), and the milvus-target hygiene guard (v1+v2 latest projections, `x-admonition`-entry/property `x-include-target` mechanics, include-span semantics). Fragment and builder edits also run the release-track projection drift gate (`scripts/rest-upstream/assert-track-projection.test.js` pins the 2.6.x/3.0.x published path counts and reconciles the operation accounting against the merged fragment set); it also runs inside `pnpm test:rest-publication-contract`, so required CI executes it on every PR. Fragment edits also pull the conformance inventory-drift gate into the focused set (`conformance/inventory/inventory.test.mjs`: the committed `schema-inventory.json` must regenerate byte-identically from the fragments via `inventory/generate-inventory.mjs`, alongside the `refresh-lifecycle-inventory.js` hash refresh) — without this mapping the gate only ran when the inventory file itself changed, which is how the committed inventory silently trailed the #1256/#1258 fragment refreshes until the 2026-11-16 `Eventually` enum fix surfaced it. The lifecycle-evidence verifier pins a SHA-256 inventory over the referenced fragments, so any fragment byte change must refresh `fragmentInventorySha256` in the same change; its target-survival gate fails any evidence pointer the milvus publication filter removes (retiring a node from the milvus target means removing its fragment stamps AND its evidence rows together), and `dualTargetStructure.contract.test.js` enforces the same-endpoint dual-implementation modeling rules of CUSTOM_ATTRIBUTES §1.2 (sibling fields never carry disjoint publication targets, and explicitly scoped subtrees never contain foreign-target nodes). The two plain-script refGen pins also run inside `pnpm test:rest-publication-contract`: `refGen.plane.test.js` pins plane classification plus the List Cloud Roles `roleType`/`projectId` parameter descriptions, and `refGen.lang-filter.test.js` pins the explicit `x-include-langs` inventory (the zh-CN sidebar exceptions) against the live fragment set, so a fragment edit that adds, drops, or re-scopes a language-restricted operation or that parameter must update the pin in the same change — neither test was previously wired into any CI command, which is how both drifted silently until milvus-io/web-content's wholesale sync of this directory surfaced them (zdoc#1039). The refresh land step writes `titles.json` alongside fragment changes, and `descriptions.json` must follow any tag rename for the same reason, so both stay mapped here | `pnpm test:rest-publication-contract` | `pnpm test:workflow-matrix` + `git diff --check` |
| REST OpenAPI fragments, generator, lifecycle evidence, fragment migration inventory, and the zh title table (`packages/docs-tooling/src/reference/rest/meta/openapi/**`, `packages/docs-tooling/src/reference/rest/meta/lifecycle-evidence/**`, `fragment-migration.json`, `titles.json`, `descriptions.json` (the per-category REST intro copy, looked up by the generated category slug `toSlug(tag.name)`, so renaming a tag must rename its entry in the same change), `refGen.js`, `refGen.route-scope.test.js`, `refGen.plane.test.js`, `refGen.lang-filter.test.js`, `includeSpans.js` (shared build-side resolver for `<include>/<exclude target>` prose spans; `refGen.__filter_content` delegates to it), `milvusTargetHygiene.test.js` (projects the real fragment set onto the milvus target — with the wrapper-style primary-tag cascade — and fails on zilliz-only vocabulary: Zilliz Cloud, on-demand compute, serving/Dedicated cluster, serverless, BDU, Public Preview; "usage tracking" is deliberately allowed as a Milvus kernel concept), `specLoader*` (merge + `$ref` resolution; a self-referencing component expands once and stays a `$ref` leaf where it re-enters its own branch), `lifecycle*` (release-track projection: `applyLifecycleForTrack` resolves combinator-branch `required` names against the enclosing object scope, so anyOf/oneOf alternatives may name parent-level properties while lifecycle-omitted names still shrink), `index.js`, `integratedSpecBuilder*` (the exported primary-tag cascade is shared with `milvusTargetHygiene.test.js` and fails closed on undeclared primary tags), `restDerivationManifest*`) | `integratedSpecBuilder`, `integratedSpecArtifacts`, `fragmentCollection`, integrated-spec CLI, completeness-receipt, and REST derivation-manifest tests, plus the refGen route-scope test (flat `/restful/<slug>` uniqueness stays fail-closed for zdoc sites while milvus keys on the physical page path, and the fetch CLI must fail before the derivation manifest or S3 upload on a conflict; it runs inside `pnpm test:rest-publication-contract`, so required CI executes it on every PR), the lifecycle track-projection test (branch-required scope resolution, parent-omission shrinking, dangling names stay fail-closed), and the milvus-target hygiene guard (v1+v2 latest projections, `x-admonition`-entry/property `x-include-target` mechanics, include-span semantics). Fragment and builder edits also run the release-track projection drift gate (`scripts/rest-upstream/assert-track-projection.test.js` pins the 2.6.x/3.0.x published path counts and reconciles the operation accounting against the merged fragment set); it also runs inside `pnpm test:rest-publication-contract`, so required CI executes it on every PR. Fragment edits also pull the conformance inventory-drift gate into the focused set (`conformance/inventory/inventory.test.mjs`: the committed `schema-inventory.json` must regenerate byte-identically from the fragments via `inventory/generate-inventory.mjs`, alongside the `refresh-lifecycle-inventory.js` hash refresh; the refresh land step spawns the same generator into the refresh commit, because an inventory stranded outside it fails exactly this gate and keeps the refresh PR from ever opening) — without this mapping the gate only ran when the inventory file itself changed, which is how the committed inventory silently trailed the #1256/#1258 fragment refreshes until the 2026-11-16 `Eventually` enum fix surfaced it. The lifecycle-evidence verifier pins a SHA-256 inventory over the referenced fragments, so any fragment byte change must refresh `fragmentInventorySha256` in the same change; its target-survival gate fails any evidence pointer the milvus publication filter removes (retiring a node from the milvus target means removing its fragment stamps AND its evidence rows together), and `dualTargetStructure.contract.test.js` enforces the same-endpoint dual-implementation modeling rules of CUSTOM_ATTRIBUTES §1.2 (sibling fields never carry disjoint publication targets, and explicitly scoped subtrees never contain foreign-target nodes). The two plain-script refGen pins also run inside `pnpm test:rest-publication-contract`: `refGen.plane.test.js` pins plane classification plus the List Cloud Roles `roleType`/`projectId` parameter descriptions, and `refGen.lang-filter.test.js` pins the explicit `x-include-langs` inventory (the zh-CN sidebar exceptions) against the live fragment set, so a fragment edit that adds, drops, or re-scopes a language-restricted operation or that parameter must update the pin in the same change — neither test was previously wired into any CI command, which is how both drifted silently until milvus-io/web-content's wholesale sync of this directory surfaced them (zdoc#1039). The refresh land step writes `titles.json` alongside fragment changes, and `descriptions.json` must follow any tag rename for the same reason, so both stay mapped here | `pnpm test:rest-publication-contract` | `pnpm test:workflow-matrix` + `git diff --check` |
| Staged REST sidebar language inventory (`packages/docs-tooling/src/reference/restSidebarDerivation*`) | `pnpm vitest run packages/docs-tooling/src/reference/restSidebarDerivation.test.ts`; the English and Chinese generated inventories stay aligned except for operations deliberately excluded from Chinese through `x-include-langs`, and the focused test pins that exception list | — | `pnpm test:rest-publication-contract` + `git diff --check` |
| rest-upstream pipeline: lock/ledger/change-set contracts, canonical fragment formatter, OAS 3.1→3.0 downgrade, branch-aware upstream diff, deterministic applier, and CLI (`packages/docs-tooling/src/reference/rest/upstreamDiff/**`, `packages/docs-tooling/src/reference/rest/meta/upstream/**`, `packages/docs-tooling/src/reference/rest/contracts/rest-upstream-*.schema.json`) | `pnpm test:rest-upstream`; every committed fragment must satisfy the canonical byte round-trip (`JSON.stringify(…, null, 2)` + newline, raw UTF-8), scenario oneOf/anyOf branches are never flattened or extended by the diff (upstream merged objects are the union of branch fields; uncovered fields become `unattributed`), change sets must be digest-bound to one diff output and may only write prose/constraint/lifecycle leaves, and the structural skeleton must be unchanged after apply. The decisions-first pipeline adds `rest-upstream-candidates` and `rest-upstream-assemble`: decision stances (adopt/skip/ledger) never carry loci or values, and the assembler derives every change-set byte from the diff and the fragment copies. The refresh workflow's `Run the change-scoped test union` step executes every command the change-scoped selector returns (the selector itself only prints the union), so any focused test registered on these paths is enforced inside the refresh run. The workflow also carries a dedicated `Assert release-track projections (drift gate)` step — pinned in `select-tests-for-changes.test.js` so it cannot be removed by matrix edits — that projects the committed fragments onto both managed release tracks and pins the published path counts; the track projections have no production consumer of their own (their audience is milvus.io via web-content), so that step is what keeps a cascade/lifecycle/fragment regression from breaking the track path silently again, and a deliberate surface change updates the pinned counts in `scripts/rest-upstream/assert-track-projection.test.js` in the same change. Design: `.claude/specs/2026-10-28-rest-upstream-pipeline-design.md` and `.claude/specs/2026-10-29-rest-upstream-decisions-pipeline-design.md` | `pnpm test:rest-publication-contract` | `pnpm test:workflow-matrix` + `git diff --check` |
| REST reference live-verification rounds (`packages/docs-tooling/src/reference/rest/conformance/**`; per-round evidence lives in `reports/<date>/` — `reports/2026-11-01` archives the first round: 130 param-level cases built from the PR #1005 fragments pin `5f7e112`, executed against Milvus v2.6.26 standalone on milvus-cell, plus v2.6.26/v3.0.5 route skeletons extracted from upstream `internal/distributed/proxy/httpserver`; `reports/2026-11-04` holds the second round: four suites — milvus-2.6.26, milvus-3.0.5, uat-dataplane (219 cases each), uat-controlplane (36 cases, 108/108 cloud ops) — with frozen accepted-response goldens, per-suite verify reports, `diff/schema-verify` fragment-vs-evidence corroboration reports, and the M/Z + cross-track diffs) | the seven hermetic commands in the machine matrix (`reports/2026-11-01/archive.test.js`, `inventory/inventory.test.mjs`, `suites/cases-integrity.test.mjs`, `diff/diff.test.mjs`, `lib/case-runner.test.mjs`, `suites/goldens-integrity.test.mjs`, `diff/schema-verify.test.mjs`); both rounds' archives are frozen evidence — verdict counts and goldens may only change when a new round is deliberately re-recorded, never to turn a red round green; goldens hold accepted responses only, and fragment fixes follow human adjudication while goldens follow environment drift | — | `pnpm test:workflow-matrix` + `git diff --check` |
Expand Down
29 changes: 25 additions & 4 deletions .github/workflows/rest-upstream-refresh.yml
Original file line number Diff line number Diff line change
Expand Up @@ -358,9 +358,10 @@ jobs:
# Gate 9a: land the verified outputs on the refresh branch. Only files
# the applier changed move; unaddressed diff entries ride the PR body.
# Design §3.1/§5: adoption is atomic — the same commit lands the fragment
# and titles deltas AND bumps the lock pin, so the watchdog goes quiet
# exactly when the refresh PR merges (no hand-edited lock follow-up).
- name: Land applied fragments, titles, and the lock pin bump on the refresh branch
# and titles deltas, both fragment-derived inventories, AND bumps the
# lock pin, so the watchdog goes quiet exactly when the refresh PR
# merges (no hand-edited lock follow-up).
- name: Land applied fragments, titles, inventories, and the lock pin bump on the refresh branch
env:
SOURCE: ${{ inputs.source }}
UPSTREAM_COMMIT: ${{ steps.upstream.outputs.commit }}
Expand All @@ -374,6 +375,25 @@ jobs:
for (const file of applied.changedFiles) {
fs.copyFileSync(path.join(process.env.RUNNER_TEMP, process.env.APPLIED, file), path.join(restMeta, 'openapi', file))
}
// The schema-attribution inventory (conformance/inventory/schema-
// inventory.json) derives from the fragment bytes — its sha256 table
// pins every fragment — and the change-scoped union below runs its
// hermetic drift gate, which demands the committed file equal a
// byte-identical regeneration. Regenerate with the very command the
// gate runs so a fragment refresh can never strand the inventory
// outside the atomic commit (the 11-17/11-19 dispatches failed
// exactly there: fragments moved, inventory trailed, PR never
// opened). Fragment bytes always move the table (per-fragment
// sha256), so a zero-diff regeneration is impossible here.
if (applied.changedFiles.length > 0) {
const {status, stderr} = require('node:child_process').spawnSync(
process.execPath,
['packages/docs-tooling/src/reference/rest/conformance/inventory/generate-inventory.mjs'],
{encoding: 'utf8'},
)
if (status !== 0) throw new Error(`schema-inventory regeneration failed: ${stderr}`)
console.log('schema-attribution inventory regenerated from the landed fragments')
}
if (applied.titleLog.length > 0) {
fs.copyFileSync(path.join(process.env.RUNNER_TEMP, process.env.APPLIED, 'titles.json'), path.join(restMeta, 'titles.json'))
// The zh-build title assertion (refGen get_slug) cannot run on a
Expand Down Expand Up @@ -454,7 +474,8 @@ jobs:
}
console.log(`landed ${applied.changedFiles.length} fragment(s); ${applied.titleLog.length} title entr(ies); ${applied.overrides.length} override(s); ${applied.ledgerDrafts.length} ledger draft(s); ${(applied.inheritedLifecycle ?? []).length} inherited lifecycle triple(s); pin -> ${process.env.UPSTREAM_COMMIT}`)
NODE
git add packages/docs-tooling/src/reference/rest/meta
git add packages/docs-tooling/src/reference/rest/meta \
packages/docs-tooling/src/reference/rest/conformance/inventory/schema-inventory.json
test -n "$(git status --porcelain -- packages/docs-tooling/src/reference/rest/meta)" || {
echo 'The change set produced no fragment, titles, or lock delta on this base; nothing to refresh' >&2
exit 1
Expand Down
Loading