feat(architecture): align package roles across catalog and policy

[kang-heewon]

Summary

Public packages now have one canonical role in docs/package-catalog.json: Kernel, Contracts, Plugins, Application, Profiles, or Tooling. Subtype, domain, runtime claims, maturity, certification, and spine membership remain separate. Historical inventory groups retain their certification scope.

README role tables, the extension matrix, repository architecture policy, and the role map shipped with generated applications use that source. Missing or contradictory role metadata and generated-map drift fail repository checks. Kernel/Contracts cannot import concrete Plugins; generated Plugins can compose other Plugins. The desktop contract's stricter browser and manifest restrictions remain effective.

tx-drizzle is Plugins/provider and telemetry-api is Contracts/observability. Architecture and generated agent guidance preserve the separate Host, Transport, and Build Target responsibilities.

Closes #2157

Validation

Elevated profile for metadata shared by documentation, dependency policy, and generated applications.

• Canonical metadata, catalog drift, generated role-map drift, and policy regressions pass. A negative control rejects missing role metadata only with the fix.
• All 120 public package classifications match the generated map. Actual policy-engine fixtures preserve desktop source/manifest restrictions and reject Contracts importing concrete Plugins.
• Full build, typecheck, and tests each pass 243/243 tasks. Normal pre-push full tests and guarded typecheck also pass 243/243 with repository-default test settings. Earlier isolated runs resolved resource contention and cross-worktree fixture collisions without source or timeout workarounds.
• Review companion: PASS for architecture policy, generated applications, public API snapshots, and repository policy. pnpm check: 27 passed, one not applicable.
• Generated-app matrix: 21/21 passed. The execution session ended after 17 cases; the four incomplete cases resumed on the same unchanged head, preserving the earlier results.
• Independent code review and verification review: PASS, including final release-evidence registration and its verified digest.
• Browser verification: three documentation routes at 1440×1000 and 390×844; no console/page errors or document overflow. Matrix overflow is confined to its scrollable table.

Evidence identity

Head: c86abc2e75502ae9d29f09213c03aa2eb916b4ee.
Validated base: 98fcaed613d648bde489686c5f1ae622f59070cd.

Runtime metadata records existing compatibility claims; an explicit empty list means unclaimed support. This change does not introduce new runtime support.

Current assessed base: 1d120139878fa362578d665d213d0e93558addcd. Cumulative drift is non-interacting with canonical roles and generated architecture policy. The initial provider changes and separate inventory entry received independent review; later billing retry and workflow execution fixes retain package identities, role metadata, and dependency directions. The workflow registry change adds only recovery metadata. No rebase was required.

CI validated merge candidate fdb553e465388e66eaeb97def6df9d421f973142 with base c2a26539a965065486813fda9462a0bae6d82212 and the unchanged head. Its tree is 57c6f63cdd09dce6914ed40152db0e68feb500f3. Downloaded core evidence proves inventory, catalog, architecture policy, and runtime policy pass on that exact candidate; publish-profile evidence has 34 passing checks and one not applicable. Subsequent base changes do not invalidate those role-contract assumptions.

CI

All required checks pass: validate, benchmark-gate, docs-sync-check, and repository-contracts. Impact-selected companion, core verification, generated apps, package artifacts, coverage/security, Windows scaffold, split-validation shadow, documentation build and links also pass.

Runs: CI, review companion, benchmark.

GitHub reports a clean, conflict-free PR. No requested changes, review requests, unresolved threads, or blocking issue comments remain. All ten uploaded screenshots were verified rendering in the published PR.

Visual evidence

Final documentation build. Pure copy and table changes; no interaction flow changed.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Warning

Review limit reached

Next included review available in 48 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ba42a904-531c-43db-bae2-3b73f81b29ce

📥 Commits

Reviewing files that changed from the base of the PR and between c2a2653 and c86abc2.

📒 Files selected for processing (26)

• .changeset/canonical-package-roles.md
• AGENTS.md
• README.md
• croco.arch.json
• docs/architecture-policy.md
• docs/architecture/dataloader-design.md
• docs/package-catalog.json
• docs/package-docs-report.md
• packages/create-croco-app/src/data/package-roles.json
• packages/create-croco-app/src/generator.ts
• packages/create-croco-app/src/tests/e2e-generation.spec.ts
• packages/create-croco-app/templates/addons/agent-rules/.agent/rules/000-core-architecture.mdc
• packages/create-croco-app/templates/addons/agent-rules/.cursor/rules/000-core-architecture.mdc
• packages/create-croco-app/templates/addons/agent-rules/AGENTS.md
• packages/docs/src/content/docs/en/guides/architecture.mdx
• packages/docs/src/content/docs/en/reference/adapter-ecosystem.md
• packages/docs/src/content/docs/en/reference/extension-matrix.md
• scripts/architecture-policy-check.mts
• scripts/package-docs-check.mts
• scripts/package-roles.mts
• scripts/release-gate-maintenance.mts
• scripts/tests/architecture-policy-check.spec.ts
• scripts/tests/package-docs-check.spec.ts
• scripts/tests/package-roles.spec.ts
• scripts/tests/verification-manifest.spec.ts
• test-inventory.json

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-08T05:53:34.635360Z	c86abc2	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

📊 Benchmark Results

✅ All benchmarks passed

Benchmark	p75	Threshold	Baseline	vs Baseline	Status	Notes
CrocoApp constructor	36.1μs	30.0ms	8.2μs	+341.0%	❌	-
CrocoApp lambdaHandler (10 controllers)	1.5ms	50.0ms	258.4μs	+475.5%	❌	-
Lambda cold-start simulation	1.2ms	80.0ms	418.1μs	+192.7%	❌	-
Lambda cold-start with headers	1.2ms	80.0ms	369.7μs	+214.3%	❌	-
Lambda cold-start with binary body	1.2ms	80.0ms	339.1μs	+239.8%	❌	-
Lambda cold-start with query params	1.1ms	80.0ms	301.3μs	+276.1%	❌	-
Lambda cold-start with authorizer context	1.1ms	80.0ms	299.8μs	+269.1%	❌	-
Lambda cold-start realistic scenario	1.1ms	80.0ms	299.2μs	+272.2%	❌	-
EventBusConfig.start (10 handlers)	1.5μs	10.0ms	1.4μs	+3.5%	✅	-
EventPublisher.publishNow single event	1.6μs	2.0ms	1.7μs	-4.2%	✅	-
DefaultHandlerResolver.resolve × 10	0.1μs	5.0ms	0.1μs	-12.5%	✅	-
Container.get singleton (cold)	51.2μs	5.0ms	70.3μs	-27.2%	✅	-
Container.register × 50 components	2.6ms	10.0ms	3.2ms	-18.7%	✅	-
Container.validate (50 components)	3.0ms	20.0ms	3.4ms	-10.8%	✅	-
Container.get singleton (warm)	1.1μs	500.0μs	1.6μs	-33.7%	✅	-
TelemetryRuntime.init (lambda preset)	9.7μs	200.0ms	1.1ms	-99.1%	✅	-
lambdaPreset config creation	1.1μs	2.0ms	1.4μs	-21.8%	✅	-

_{Updated: 2026-09-08T05:53:48.811Z · Commit: c86abc2}