fix: line-aware manifest diagnostics and token-collision detection

[devanchohan]

What this changes

Follow-up hardening for contextfence generate after a self-review pass. (The matrix expansion and generate command themselves already landed on main via #9; this PR carries the remaining iteration on top.)

1. Line-aware manifest diagnostics — generate's validation errors previously reported 1:1 for every finding. Diagnostics now resolve their YAML node position through the same path-walking lookup the boundary-contract parser uses, so an invalid allow entry reports its actual line and column.
2. Credential-placeholder collision detection — identity ids are slugified into env placeholders, so finance-analyst and finance.analyst both derived CONTEXTFENCE_FINANCE_ANALYST_TOKEN and would silently share one credential — invalidating the very boundary the generated grid is supposed to test. This now fails closed with DUPLICATE_TOKEN_ENV.
3. Architecture doc — documents the matrix-expansion and access-manifest-generator seams (loader-side, adapter-agnostic, generated contracts earn no trust and pass through the full validator on every run).

Evidence

All data is synthetic. A manifest with an undefined allow identity now reports its exact position instead of 1:1:

manifest.yaml:7:9 $.sources[0].allow[0]: allow references an identity that is not defined. [UNKNOWN_IDENTITY]

A manifest with finance-analyst and finance.analyst fails with DUPLICATE_TOKEN_ENV naming both ids and the shared placeholder CONTEXTFENCE_FINANCE_ANALYST_TOKEN.

Verification

• pnpm lint
• pnpm typecheck
• pnpm test (67 tests; regression tests added for both fixes, including asserting the diagnostic line is > 10)
• pnpm build
• I added or updated a regression test where behavior changed.
• I tested both the violating and remediated path where applicable (full release-check preflight green).

Safety and compatibility

• No credentials, confidential prompts, customer data, or sensitive report artifacts are included.
• Logs and reports minimize or redact sensitive evidence (diagnostics report positions and paths, never values).
• Contract/schema compatibility impact is documented, or there is none — no contract-schema change; DUPLICATE_TOKEN_ENV only rejects manifests that were previously generating broken suites.
• The change keeps vendor-specific behavior behind an adapter, or is vendor-neutral.
• User-facing and release-facing changes are included in CHANGELOG.md (covered by the existing Unreleased generate entry).

Screenshots or artifacts

Reproduce locally: node dist/package/cli.js generate <manifest> with an undefined allow identity or colliding identity ids.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UxYFd1KhMHh7ZLytLz4Yg8

[Copilot]

Pull request overview

Adds a scalable authorization “matrix” abstraction to boundary contracts and a companion contextfence generate CLI command to produce matrix contracts from connector-neutral access manifests, while preserving the existing v1 probe runner and reporting semantics.

Changes:

• Extend the contract schema/loader to accept an optional matrix block and deterministically expand it into deny/allow probes with stable YAML locations.
• Add contextfence generate to convert an access manifest into a matrix contract with env placeholders for credentials and line-aware diagnostics.
• Add new examples/docs and wire matrix fixtures + generator into release preflight.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/contract/schema.ts	Adds matrix validation + expansion into generated probes and tracks per-probe YAML paths.
src/contract/parser.ts	Uses probePaths to map generated probes back to matrix-source YAML locations.
src/contract/matrix.test.ts	Adds tests for matrix expansion semantics and location mapping.
src/contract/index.ts	Exports the new contract generator API.
src/contract/generate.ts	Implements access-manifest parsing/validation and deterministic matrix contract codegen.
src/contract/generate.test.ts	Adds generator tests (round-trip validation, derived keys/canaries, diagnostics).
src/cli/main.ts	Adds generate command execution path and help routing.
src/cli/args.ts	Adds generate command parsing and help text.
src/cli/args.test.ts	Adds CLI parsing tests for generate.
scripts/release-check.mjs	Runs matrix fixtures and generator in release preflight.
README.md	Documents matrix usage and the generate command.
package.json	Ensures examples/manifests is published.
examples/README.md	Adds example guidance for matrix expansion and generator usage.
examples/manifests/northstar-access.yaml	Adds a sample access manifest input for generation.
examples/contracts/matrix.boundary.yaml	Adds a live-template matrix contract example.
examples/contracts/matrix-leak.boundary.yaml	Adds a failing matrix “leak” fixture to demonstrate detection.
docs/architecture.md	Documents loader-owned matrix expansion and generator behavior.
CHANGELOG.md	Records new matrix block and contextfence generate additions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.