← all branches

exp/core-dossiers

needs attention
8ff8773 · incrementalPR #270reviewed 2026-07-27 17:46 UTC1H · 3M · 2L · 3I
The branch
Purpose
Stand up a canonical-reference system and capability-dossier layer for the frontend/API surface — covering what the backend ontology/FCIS docs never touched
Goal
Nine audited core-domain dossiers + non-running reference implementations for every core entity, with a capability registry that makes write-sets derivable across coordinators
Sub-goals
  • SG-1–SG-14: device integration manifests, catalog seeds, ARN seed, CDK paths, migration scripts, 1M granularity, coverage clamp, brand consolidation, estate validation, Loop C remediation
  • Dossier layer: capability-dossier rule, /dossier skill, 9 audited entities
  • Canonical-reference: third contract kind, capability registry with deriveWriteMap(), 5 new entity contracts + types
The changes (whole branch)
What
Auth service contract (3rd kind), GET /me/session moved profile→auth, signup write-edge registered, 5 new canonical entities (invitation, api-key, secret-config, user-preferences, cross-domain integration-credential), capability registry with deriveWriteMap()
Why
Establishes the derivability mechanism (registry, not folder) and three new patterns: NO-EVENT telemetry writes, ONE-TIME secret reveal, service contracts with registered write-edges
Areas
canonical-reference/registry+231−0canonical-reference/apps/platform/src/api/contracts+370−20canonical-reference/domains/core/src+420−15canonical-reference/_migration+100−0.claude/skills/dossier + rules+1400−0
Blast
32 files incremental, ~100 files cumulative. All docs under canonical-reference/ (non-running reference) — zero runtime surface changed.
docs-only non-running-reference no-migration no-test-change
➖ci· CI checks not accessible via PAT➖coderabbit· No .coderabbit.yaml in repo

Findings · 9

correctness4

high

api-key revoke route absent from ENTITIES entityRoutes — deriveWriteMap() misses it

canonical-reference/registry/capability-registry.ts

apiKeyContract defines POST .../revoke and revokeApiKeyShell is in shells[], but no entity route entry exists. deriveWriteMap() iterates entityRoutes, so this write is invisible — contradicting the registry's stated guarantee.

medium

FLOWS['create-integration-credential'].writes only lists core entity — metrics IntegrationSecret absent

canonical-reference/registry/capability-registry.ts

Shell header and TODO.md say this is a cross-domain flow writing TWO domains. Registry writes[] only declares secret-configuration. Add a placeholder comment for the metrics entity.

medium

PUT /credentials/cfe mapped as op:'create' — semantically incorrect for an idempotent upsert

canonical-reference/registry/capability-registry.ts

PUT is create-or-replace (idempotent). op:'create' causes deriveWriteMap to miss the update case. Consider adding 'upsert' to WriteOp or using 'update' with a comment.

low

accept-invitation flow references decision.value.invitationPublicId while decide step is still commented

canonical-reference/domains/core/src/flows/accept-invitation.flow.ts

The decide call is commented out — decision is presumably declared in the unseen upper function body. Add a placeholder comment to make data flow legible.

conventions3

medium

UserPreferences publicId prefix prf_ clashes with Profile's ontology prefix

canonical-reference/domains/core/src/user-preferences/user-preferences.type.ts

prf_ reads as profile. If Profile uses prf_, log traces are ambiguous. Use a distinct prefix (ups_ or upf_).

low

invitation.contract.ts uses HTTP DELETE with a body for revoke

canonical-reference/apps/platform/src/api/contracts/invitation.contract.ts

DELETE with a request body is non-standard; some proxies drop it. Align with existing POST /...​/revoke + OCC body pattern.

info

withAuthErrors import implies a live export — note it's part of the same rollout

canonical-reference/ROUTE-FORMS.md

Reference contracts import withAuthErrors from @batu/api/responses. Both are NON-RUNNING — clarify the rollout dependency.

tests1

info

Enforcement Layer 3 (flow-registry.check.mjs) not yet wired to CI

canonical-reference/enforcement/flow-registry.check.mjs

Layer 3 would prevent registry drift structurally. Create a follow-up issue or add a TODO in the registry header.

improvement1

info

TODO.md sections 1 and 3 should become Linear issues

canonical-reference/TODO.md

Admin-completeness audit and contract completeness sweep are well-scoped cross-cutting items that will be forgotten without tracking.

History · 7 commits

  1. 8ff8773needs attentionincremental1H · 3M · 2L2026-07-27 17:46current
  2. 7640070needs attentionincremental10H · 18M · 14L2026-07-18 02:11
  3. a516a9dneeds attentionincremental4H · 5M · 4L2026-07-17 04:38
  4. 910fc6aneeds attentionincremental1H · 9M · 6L2026-07-10 23:48
  5. 0b75850safeincremental0H · 0M · 0L2026-07-10 23:17
  6. 380a931safeincremental0H · 0M · 0L2026-07-09 19:17
  7. 5a9ac90blockedfull5H · 8M · 5L2026-07-07 22:07