[CLI] META-244 — consume published @workspacejson/spec declarations, remove ambient shadow - #2
Merged
Conversation
…244)
types/ambient.d.ts carried a handwritten `declare module '@workspacejson/spec'`
restating that package's type surface. Ambient module declarations win over
node_modules typings, so the stub shadowed the real published declarations even
though the dependency is a registry-backed pin — and it silently hid the entire
v0.4 contract from this repository's compiler:
WorkspaceJsonV4 absent from the stub
validateV4 absent from the stub
CoChangeEntry absent from the stub
FragilityEntry absent from the stub
validate() narrowed to `data is WorkspaceJsonV3`; the real declaration
is `data is WorkspaceJsonV3 | WorkspaceJsonV4`
version typed `string`; the real declaration is the literal "0.4.4"
workspacejson/standard owns that contract. This removes the second editable copy
and compiles both packages against the real declarations.
This is a type-visibility correction only. No producer behavior change, no
emission change, no schema change, nothing renamed, nothing published. It
implies nothing about the durable architecture of this repository — the
migrated package layout remains a migration baseline pending META-236.
Added: packages/agents-audit/src/spec-contract-visibility.test.ts. Every symbol
it imports exists only in the real package, so reintroducing the shadow breaks
it at compile time rather than at runtime. Verified by deliberately restoring a
V3-only stub and observing TS2305/TS2724 on validateV4, CoChangeEntry,
FragilityEntry and WorkspaceJsonV4.
Added: a `shadowed-standard-types` guard in check-architecture.mjs rejecting any
ambient re-declaration of a @workspacejson/* package, with two red tests (spec
and rules). The guard strips comments first, so the note explaining the removal
can quote the syntax it forbids.
Inventory recorded on META-244: 22 ambient module declarations plus one global.
Exactly one was a standard-owned contract shadow. No @workspacejson/rules shadow
exists. Six declarations (fast-glob, simple-git, remark, remark-parse, ajv,
ajv/dist/2020.js) are dead here — they served packages/spec and packages/rules,
which left for workspacejson/standard — and are deliberately NOT removed in this
change, which stays scoped to the contract-ownership defect.
Verification
- typecheck 2/2, build 2/2
- tests 68 (was 63; +5 from the new visibility suite) + 6 shim tests
- architecture guard red tests 15/15 (was 13)
- packed file inventory identical to published agents-audit@0.4.4
- packed manifest identical to the merged META-240 candidate
- META-240 producer parity harness 29/29
- META-240 DataHub shim parity harness 35/35
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Removes the handwritten
@workspacejson/specambient declarations so the CLI packages compile against the real published contract.Linear: META-244. Follow-up to META-240, which migrated this file byte-identical because parity required preserving behavior, and recorded the shadow as a known follow-up.
Scope discipline: this is a type-visibility correction only. It implies nothing about the durable architecture of this repository. The migrated package layout (
packages/agents-audit/,packages/cli/) remains a migration baseline and compatibility capsule pending the META-236 target-architecture ratification — per ADR-002, historical repository and package names are migration inputs and compatibility constraints, not the target architecture.The defect
types/ambient.d.tscontaineddeclare module '@workspacejson/spec' { … }restating that package's type surface. Ambient module declarations win overnode_modulestypings, so the stub shadowed the real published declarations even though the dependency is a registry-backed pin (0.4.4).It was not merely redundant — it was stale, and hid the entire v0.4 contract:
WorkspaceJsonV4(specVersion: '0.4',coChange,fragility, health extensions)validateV4()CoChangeEntryFragilityEntryvalidate()data is WorkspaceJsonV3; realdata is WorkspaceJsonV3 | WorkspaceJsonV4versionstring; real literal"0.4.4"WorkspaceJsonV3,FileIndexEntry,FrameworkEntryandWorkspaceJsonwere shape-identical, which is why nothing failed loudly — the repository simply could not see the newer half of the contract it depends on.Full ambient inventory (22 module declarations + 1 global)
@workspacejson/specnode:fs,node:fs/promises,node:path,node:url,node:module,node:readline@types/nodeadded in META-240node:child_processcommander,ora,picocolors,cli-table3,boxen,terminal-link,dedent,vitestfast-glob,simple-git,remark,remark-parse,ajv,ajv/dist/2020.jspackages/spec/packages/rules, which leftdeclare const process@types/node@workspacejson/rulesshadow: does not exist.@workspacejson/specwas the only@workspacejson/*ambient declaration. No other first-party contract is duplicated here.The six dead declarations are deliberately not removed — they are a separate, evidence-backed cleanup, and bundling them would blur a contract-ownership fix into unrelated tidying.
The deliberate test
packages/agents-audit/src/spec-contract-visibility.test.ts(5 cases) importsvalidateV4,WorkspaceJsonV4,CoChangeEntryandFragilityEntry— every one of which exists only in the real published package and was absent from the removed stub. Its primary assertion is that it compiles at all.Proven by perturbation — restoring a V3-only stub and re-running typecheck:
That is the acceptance criterion "a changed published type is visible to the CLI compiler", demonstrated rather than asserted.
The suite also checks the opposite failure: v0.3 artifacts must still validate and must still be rejected by
validateV4, so consuming real types did not widen or break the contract the producer emits today.Regression guard
New
shadowed-standard-typescheck inscripts/check-architecture.mjsrejects any ambient re-declaration of a@workspacejson/*package, with two red tests (specandrules). Guard red tests: 13 → 15, all passing, including the baseline case proving an unmodified repository is still accepted.The guard strips comments before matching — the note left in
ambient.d.tsexplaining the removal necessarily quotes the syntax it forbids. I hit that false positive during development and fixed the guard rather than reword the explanation, since the rule is about what the compiler sees.Verification
No runtime behavior changed — the packed artifact is byte-identical to the merged META-240 candidate, which is the strongest available evidence that a types-only change stayed types-only.
Not in scope
@workspacejson/cliremainsprivate: trueand absent from the registry.packages/agents-auditas the durable home of anything.