UI
CCA-UI-001
MUST
Use CCA UI Profile v2
New public services MUST use CCA UI Profile v2: pinned GOV.UK Frontend 6.4.0 CSS and ES module plus fonts from govuk.prodcdn.com; palette #1d70b8, #003078, #00703c, #d4351c, #f47738, #ffdd00, #0b0c0c, #505a5f, #b1b4b6, and #f3f2f1; stable v6 header, footer, container and grid; GDS Transport; responsive behavior at 641/640/768 boundaries; visible focus; skip links; semantic landmarks; reduced motion; and aria-hidden decorative SVG. A page MUST NOT mix GOV.UK Frontend and NYC Core.
Automatable · Reference 1
CCA-UI-002
MUST
Deliver accessible no-JavaScript content
Core public content MUST be server-rendered and usable without JavaScript. Pages MUST include semantic landmarks, a skip link, visible keyboard focus, labeled controls, accessible error summaries linked to field errors, status or live regions for meaningful asynchronous changes, useful loading, empty, and error states, and layouts usable at narrow widths and high zoom. Custom dialogs MUST trap focus, restore it on close, support Escape where safe, and MUST NOT fall back to alert, confirm, or prompt.
Design review · Reference 1
CCA-UI-003
MUST
Load executable assets only from approved hosts
Executable CSS, JavaScript, fonts, and related frontend assets MUST be self-hosted, hosted on cdn.coopalliance.org, or hosted on a subdomain ending .prodcdn.com. The apex prodcdn.com host is not allowed. Asset versions MUST be pinned.
Automatable
CCA-UI-004
MUST
Migrate legacy fleet pages without mixing frameworks
NYC Core 1.0 with the legacy #004CBE shell is Legacy UI Profile v1 and MAY remain only during migration. New services MUST NOT introduce Profile v1. Migration maps the legacy container, grid, cards, tables, badges, header, footer, skip link, and controls to their GOV.UK Frontend v6 equivalents in one release; pages MUST never load both frameworks.
Automatable · Reference 1
Service Bindings
CCA-BIND-003
MUST
Never silently fall back from a binding to public HTTPS
A missing or failed service binding MUST produce an explicit failure or documented independent degradation. Internal calls MUST NOT silently fall back to the public HTTPS hostname. Service-binding and RPC callees MUST authenticate and authorize independently.
Design review · Reference 1
CCA-BIND-001
SHOULD
Document service bindings safely
Services supporting Cloudflare service bindings SHOULD document the public-safe contract, request envelope, authentication responsibility, compatibility expectations, and local-test strategy without publishing account IDs, private hostnames, credentials, or secret binding configuration.
Design review · Reference 1
CCA-BIND-002
MUST
Keep service enrichments independent
Service-binding enrichments MUST degrade independently so one unavailable enrichment does not corrupt the owned core record. Enrichment responses MUST retain their source ownership and MUST NOT be persisted or republished as data owned by the calling service.
Design review
OpenAPI
CCA-OAS-001
MUST
Publish a complete OpenAPI 3.1 contract
Every public API MUST publish an OpenAPI 3.1 document with title, version, description, canonical HTTPS servers, contact, license, tags, stable globally unique operationId values, parameter and request schemas, every success and error response schema, and realistic examples.
Automatable · Reference 1
CCA-OAS-002
MUST
Prevent specification and runtime drift
CI MUST validate OpenAPI syntax and fleet rules. Contract tests SHOULD exercise documented routes, status codes, content types, and representative schemas against the runtime so undeclared or stale behavior fails review.
Automatable · Reference 1
Data Semantics
CCA-DATA-001
SHOULD
Use the fleet response envelope
Successful collection and lookup responses SHOULD use the existing fleet envelope consistently, with data plus meta fields for provenance, freshness, cache state, request or trace identity when safe, and upstream status. meta.sources MUST list the sources that actually contributed to that response, never a static superset. Status or source-query failures MUST remain explicit errors or unknown states and MUST NOT be converted to a zero count. Do not report stale or partial upstream data as unqualified success.
Design review
CCA-DATA-002
MUST
Describe provenance and freshness
Every data-bearing response or linked metadata resource MUST identify its source, observed or released timestamp where known, refresh cadence, and whether the result is live, cached, stale, partial, or unavailable.
Design review
CCA-DATA-003
MUST
Preserve immutable evidence and independent quality dimensions
Evidence-bearing systems MUST preserve immutable captures and hashes plus support and contradiction relationships, exact quotes or spans or pages, and source authority. Confidence, verification state, and publication state MUST remain orthogonal. Publication eligibility MUST be continuously derived from current evidence and policy, not stored as an unexamined permanent flag.
Design review
CCA-DATA-004
MUST
Version and reconcile projections
Derived projections MUST expose their source revision and freshness. Rebuilders MUST track dirty generations, compare the generation before clearing dirty state, and leave newer work pending when concurrent changes arrive.
Design review
CCA-DATA-005
MUST
Publish source use restrictions
Source registries and provenance manifests MUST record license, redistribution rights, solicitation restrictions, and other use constraints and surface applicable restrictions in APIs and public UI. Classification labels are descriptive metadata and MUST NOT be presented as legal determinations.
Design review
Pipeline
CCA-PIPE-011
MUST
Use durable execution for required work
ExecutionContext.waitUntil is best effort and MUST be used only for disposable post-response work. Required, retryable, or state-changing background work MUST use Queues or Workflows with explicit retry policy, dead-letter handling, idempotency, and reconciliation.
Design review · Reference 1 · Reference 2
CCA-PIPE-001
MUST
Archive immutable source bytes before indexing
External data pipelines MUST archive verified immutable source bytes in R2 before parsing or indexing. Pipeline Workers MUST use scoped Worker administration APIs and service bindings and MUST NOT hold direct D1 or R2 account credentials.
Design review · Reference 1
CCA-PIPE-002
MUST
Download and discover sources defensively
Downloads MUST use a temporary .part path, incremental SHA, declared and actual size checks, response framing and magic-byte validation, bot or challenge detection, and atomic rename only after verification. Discovery MUST fail closed and MUST NOT guess source URLs. Download caps and multipart sizes are source-specific implementation values, not fleet constants.
Design review
CCA-PIPE-003
MUST
Verify immutable object publication
Multipart completion MUST verify the remote SHA and size. An existing immutable key with conflicting bytes MUST stop the pipeline and MUST never be overwritten. Archive extraction MUST reject path traversal, absolute paths, symlinks, duplicate names, excessive expansion or compression ratio, encrypted entries, truncation, CRC failures, and unsafe ZIP64 structures.
Automatable
CCA-PIPE-004
MUST
Normalize deterministically
Source adapters MUST separate discovery metadata from bounded record iteration. Shared normalizers MUST be centralized and versioned. Canonical JSON, stable ordering, and deterministic duplicate-winner rules MUST make equivalent inputs produce byte-identical artifacts and shard assignments.
Automatable
CCA-PIPE-005
MUST
Bound and partition durable pipeline work
D1-facing writes MUST default to batches of no more than 500 rows unless a documented load test supports another bound. Durable state MUST partition work by release, source, shard, and batch. Queue and Workflow messages MUST contain immutable pointers and identity metadata only, never large mutable payloads. Lease durations are implementation-specific, not universal constants.
Design review · Reference 1 · Reference 2
CCA-PIPE-006
MUST
Reconcile exactly before promotion
Promotion MUST require exact expected shard and record-count reconciliation. Ledger, checkpoint, lease, and compare-and-swap state MUST make replay idempotent and reject stale ownership tokens. Pipelines MUST reject zero-result releases, modeled corpus mismatches, unsafe object paths, and ambiguous corrections rather than promoting partial data.
Automatable
CCA-PIPE-007
MUST
Bind releases to complete provenance manifests
Every promotable release MUST have a canonical provenance manifest binding discovered URLs, validators, content length, source SHA, schema and normalization versions, shards, expected and actual counts, and immutable object keys. Secret configuration SHOULD support NAME_FILE indirection, and logs MUST redact secret values and sensitive source parameters.
Automatable
CCA-PIPE-008
MUST
Test pipeline faults, replay, and promotion
End-to-end tests MUST cover interrupted and malformed downloads, archive attacks, multipart retries and conflicts, duplicate deliveries, lease expiry and stale tokens, checkpoint replay, count or shard mismatch, failed promotion, and successful atomic promotion from archived source through serving indexes.
Design review
CCA-PIPE-010
MUST
Allocate production-scale ingest test memory explicitly
Test and rehearsal processes that exercise production-scale or full-corpus ingestion MUST run in a documented runner profile with more than 28 GB of memory allocated and MUST record the profile in CI or the runbook. This requirement is not applicable to bounded unit, contract, and small deterministic fixture tests.
Design review
CCA-PIPE-009
MUST
Coordinate cross-resource writes with sagas
Workflows spanning D1, R2, queues, or append-only audit stores MUST use a saga or transactional outbox with durable commit markers, deterministic work IDs, content-addressed staging, a D1 delivery ledger, enqueue-after-staging, leases with owner tokens, conditional terminal writes, dead-letter handling, reconciliation, and idempotent replay.
Design review
HTTP
CCA-HTTP-001
MUST
Implement HTTP caching correctly
Cacheable GET and HEAD resources MUST publish explicit Cache-Control and a validator such as ETag or Last-Modified, honor conditional requests, and use Vary when representation selection changes the response. Unsafe or private responses MUST NOT be publicly cached.
Automatable · Reference 1
CCA-HTTP-002
MUST
Define CORS intentionally
Public machine-readable metadata and openly reusable APIs SHOULD allow wildcard read CORS. Credentialed, private, administrative, or browser-sensitive endpoints MUST use an explicit Origin policy and MUST validate Origin independently of CORS headers.
Automatable · Reference 1
CCA-HTTP-003
MUST
Expose rate-limit state
Rate-limited APIs MUST document their quota model and return actionable limit, remaining, reset or retry information using current standard fields where practical. A 429 response MUST include Retry-After when the retry time is known.
Design review · Reference 1
Security
CCA-AUTH-001
MUST
Separate public, authenticated, and administrative surfaces
Public read routes, user-authenticated routes, ingestion routes, and administrative routes MUST be separate and documented with explicit security schemes. Administrative endpoints and internal hostnames MUST NOT appear in the public service catalog.
Automatable
CCA-AUTH-002
MUST
Enforce trust boundaries at every Worker
High-risk services MUST separate public, administrative, audit, PII, and immutable-evidence responsibilities into explicit Worker and resource trust boundaries. Every service-binding callee MUST authorize the request itself because Cloudflare Access identity and policy context do not automatically propagate through service bindings.
Design review · Reference 1
CCA-AUTH-003
MUST
Use least-privilege entrypoints
Browser and administrative routes MUST be protected by Cloudflare Access plus application RBAC. Read and mutation entrypoints SHOULD use separate least-privilege bindings or RPC capabilities. Caller-supplied identity headers are untrusted audit labels and MUST NOT authorize a request.
Design review · Reference 1
Agents
CCA-AGENT-001
SHOULD
Publish agent-readable documentation
Public services SHOULD provide concise llms.txt discovery and clean Markdown documentation linked to the authoritative OpenAPI and status resources. Agent-facing claims MUST not exceed actual schema, example, freshness, or operation coverage.
Automatable · Reference 1
CCA-AGENT-002
SHOULD
Describe multi-service workflows with Arazzo
Common repeatable workflows that call one or more public APIs SHOULD be published as Arazzo documents using stable operation references and explicit inputs, success criteria, outputs, and failure handling.
Automatable · Reference 1
CCA-AGENT-003
SHOULD
Use overlays for non-breaking enrichment
Agent-facing descriptions, examples, classifications, and corrections SHOULD be distributed as OpenAPI Overlay documents when upstream specifications cannot be changed immediately. Overlays MUST identify their target and MUST NOT conceal runtime drift.
Automatable · Reference 1
Database Safety
CCA-D1-001
MUST
Keep D1 bounded and rebuildable
D1 MUST contain only bounded, rebuildable metadata, identity records, pointers, and indexes. Immutable raw bytes, large fact tables, documents, and unbounded history MUST live in R2. R2 SQL or any other beta feature MUST NOT be required for public request correctness.
Design review · Reference 1 · Reference 2
CCA-D1-002
MUST
Design deterministic D1 sharding before ingest
Every D1-backed design MUST choose and document a deterministic shard key before ingest, maintain a versioned shard map, and prove that every shard can be rebuilt from immutable R2 manifests. CI and design review MUST reject an unsharded schema whose modeled corpus plus index growth can exceed the 7.5 GB admission ceiling.
Design review · Reference 1
CCA-D1-003
MUST
Enforce D1 capacity gates
Each D1 shard MUST begin rollover and provision its successor by 7.0 GB, stop write admission when projected post-write or peak usage could exceed 7.5 GB, and target 5.0 GB or less after rebalancing. Systems MUST reserve at least 2.5 GB under the non-increasable 10 GB hard cap. Batches, index builds, copy or rebuild migrations, VACUUM, and rollback reserve MUST be included in the peak estimate and MUST NOT run when projected peak usage exceeds 7.5 GB.
Automatable · Reference 1
CCA-D1-004
MUST
Fail closed before D1 capacity exhaustion
Ingest MUST estimate projected post-write and peak bytes before writes, enforce documented row, batch, and transaction bounds, checkpoint progress, and stop or queue work when admission would cross the 7.5 GB gate. It MUST reject earlier when migration, index, VACUUM, or rollback reserve requires space and fail closed rather than relying on the platform to reject an oversized database.
Automatable · Reference 1
CCA-D1-005
MUST
Observe every D1 shard
Status and telemetry MUST expose each shard's platform-reported databaseSizeBytes, percentage of the 10 GB cap, recent growth rate, projected exhaustion date, threshold state, and last verified timestamp. Alerting MUST trigger before 7.0 GB. Account-wide storage and Worker binding limits MUST be reported separately and MUST NOT be treated as increasing the 10 GB per-database hard cap or changing D1's single-threaded execution model.
Automatable · Reference 1 · Reference 2
Identity
CCA-ID-001
MUST
Encode only immutable namespaces in stable IDs
Stable identifiers MAY encode only a prefix registered in the fleet namespace registry that denotes an immutable namespace or record kind. They MUST NOT encode a mutable classification, status, ownership role, geography, or lifecycle value. Prefix allocation MUST be reviewed for collision before use.
Automatable
CCA-ID-002
MUST
Model legal-entity classifications and relations temporally
Legal entities MUST use the neutral ecgc namespace with canonical syntax ecgc-[0-9a-z]{12}. corp, npo, fund, sub, and gov prefixes are prohibited for legal-entity identity because corporation, nonprofit, fund, and government are temporal provenanced classifications, while subsidiary_of is a temporal relationship rather than an entity type.
Automatable
CCA-ID-003
MUST
Make identity edges auditable
Identity and relationship edges MUST use surrogate edge IDs, enforce uniqueness for active equivalent edges, retain audited reassignment history, and normalize identifiers by scheme-specific rules rather than generic separator stripping. Alias resolution MUST return ambiguity explicitly and MUST NOT select an unordered first match. Redirect and alias tables MUST be explicit, cycle-checked, tombstone-aware, and immutable in audit history.
Design review
CCA-ID-005
MUST
Govern canonical legal-entity minting
cca-entities is the sole minting authority for ecgc-[0-9a-z]{12} legal-entity IDs unless one atomic global allocator is designated. IDs MUST use Web Crypto with a lowercase base36 custom alphabet, be immutable and non-reusable, and mint by retrying actual INSERT uniqueness conflicts rather than SELECT-then-INSERT. Consumers MUST validate syntax only and otherwise treat IDs as opaque. Legacy e###-*, noncanonical ecgc-*, enty-*, and entm-* identifiers MUST migrate through audited aliases and immutable cycle-checked redirects.
Design review
CCA-ID-004
MUST
Preserve identity through organizational change
Mergers and acquisitions MUST retain both stable IDs and add effective-dated predecessor and successor relationships. Spin-offs MUST receive new IDs. Identifiers MUST NOT transfer or redirect implicitly; every reassignment or alias requires explicit provenance, effective dates, and immutable audit.
Design review
History
CCA-HIST-001
MUST
Serve snapshot history from indexed metadata
Snapshot and release history MUST be served from bounded indexed metadata. Public request paths MUST NOT enumerate R2 with LIST to reconstruct history at request time.
Design review · Reference 1
