Canary Go — Cadence Ladder

Governing thesis. The cadence ladder is the how-and-why of Canary Go's endpoint strategy. The three-axis model in the Endpoint Library (Adapter / Resource / Agent) answers who the endpoint serves and where it sits. The cadence ladder adds the orthogonal dimension: what cadence it runs at. Every endpoint occupies one cell of a 3×5 grid. The tier dictates protocol, SLA, alerting, recovery, and agent contract — and gets baked in at four layers (config, agent contract, runtime behavior, surface). Without the tier dimension, "endpoint" is too coarse a unit; freshness budgets, replay-vs-resync, alert routing, and agent-readiness all collapse into binary green/red instead of the five-tier health model that real multi-store operators actually need.

Provenance

The cadence ladder is synthesized from a national specialty retailer's ~2011 multi-tier RTI (Real-Time Integration) architecture for store↔hub data flow — an enterprise-scale precedent the founder authored and still finds operationally correct fifteen years later. Key extractions: the Service Pulse heartbeat as canonical stream-tier liveness proof, the DDS message-queue polling pattern as change-feed, the Windows-Event-Log + CA-UNICENTER integration as tier-aware alert routing, and the Interface Groups taxonomy (5 groups by cadence) as the prior-art classification of feeds. Raw intakes preserved in Brain/raw/inbox/technical_design_* — never the named source in synthesis.

The five-tier ladder

Each tier has a different protocol fit (stream → WebSocket/SSE/MSMQ; change-feed → REST polling or webhooks; daily batch → cron-driven export; bulk window → scheduled file drop or large GraphQL/REST page; reference → cached lookup with TTL), a different failure metric, and a different recovery operation. Mixing tiers in one endpoint is the fastest way to make health unmonitorable — you can't write a single alert that catches both "stream stalled for 10 seconds" and "weekly file didn't land."

The 3×5 grid (axis × tier)

The endpoint library's three axes (Adapter Substrate / Resource APIs / Agent Surface) cross with the five tiers to produce 15 endpoint archetypes. Every endpoint Canary exposes occupies exactly one cell.

Worked examples

Inventory across the grid:

Alerts across the grid:

The same domain (inventory, alerts) shows up in every tier. That's the point. Tier completeness is the right unit of capability, not endpoint count.

The four-layer baking model

Tier metadata isn't a comment in the docs — it's load-bearing in four places.

Layer 1 — Config schema

Every feed declaration carries tier: as a required field. Tier drives required companions:

feed: counterpoint.transactions
tier: change-feed              # required
sla:
  freshness_budget: 15m        # required for change-feed
  max_lag: 30m                 # required for change-feed
recovery:
  mode: catch-up-from-watermark  # tier-determined
retention: 90d
alert_pattern: lag-exceeded     # tier-determined

Config validation rejects tier: stream without a freshness_budget in seconds. It rejects tier: bulk-window without a schedule. The schema is the first checkpoint where tier mismatches die loudly instead of degrading silently.

Layer 2 — Agent contract

Every Canary agent declares which tiers it consumes and what freshness it needs. From agent-card-format:

consumes:
  - feed: alerts.events
    tier: stream
    freshness_budget: 5s
  - feed: items.master
    tier: reference
    freshness_budget: 1d

At agent-boot time, the runtime cross-references each declared dependency against the feed config. Tier mismatch is a hard error, not a runtime warning — an agent that wants stream-tier alerts but the feed is configured as daily-batch fails to boot. This is the contract the Ross RTI architecture got right: agents that misjudge cadence cause the silent 2 a.m. drift that forensic teams find weeks later.

Layer 3 — Runtime behavior

Tier parameterizes everything operational:

The runtime doesn't carry tier-specific code paths for each feed — it carries five tier-specific code paths, parameterized by feed config. Adding a new feed means writing config, not code.

Layer 4 — Surface (Bases / dashboards / docs)

The Brain wiki has a Bases view that groups feeds by tier, not by domain. There are five separate per-tier health rollups, not one binary "all green." The CRB Endpoint Library renders the Tier column on every endpoint table. The Ops Dashboard SSE channel surfaces five health indicators, not one.

This sounds cosmetic. It is not. Tiering the surface forces tiering everywhere upstream. A flat "all systems green" rollup tolerates silent change-feed lag because it's not visible. A five-tier rollup makes change-feed lag a visible amber light next to a green stream.

Adapter substrate as tier expression

The current Endpoint Library lists three adapter patterns (webhook / polling / edge-agent) without naming them as tier expressions. Naming clarifies and surfaces a missing pattern:

The bulk-import pattern is required and the current library does not list it. Catalog refreshes, store-list updates, weekly assortment imports, and reference-master synchronization all need a bulk-window-tier inbound channel. The shape: scheduled file drop → SFTP or signed S3 URL → POST /imports returns a job ID → status polling endpoint → completion event. The Ross RTI architecture handled this as DDS-staged file transfers over HTTPS streams with explicit landing-window monitoring; Canary's variant is a cloud-native SFTP-or-bucket landing zone with the same lifecycle semantics.

Action item: Axis A in the Endpoint Library now lists four patterns, not three.

Moat-service tier mapping

The accountability rails — Canary's patent-protected differentiators — must be tiered explicitly because they are exactly the services where tier mismatches would be catastrophic.

Do not break this mapping. A future engineer arguing blockchain-anchor should be stream-tier is making an architectural mistake — L2 settlement economics enforce the tier, not preference. Same for the others.

How this composes with the three-axis model

Axes answer who consumes the endpoint (Adapter for POSes inbound, Resource for external systems, Agent for AI). Tiers answer what cadence it runs at. Both compose. An endpoint is fully specified only when both are declared:

GET /alerts/sse        → Axis B (Resource), Tier: Stream
POST /webhooks/square  → Axis A (Adapter), Tier: Stream
canary-compliance.lookup_zone()  → Axis C (Agent), Tier: Reference
POST /exports/inventory-positions  → Axis B (Resource), Tier: Bulk window

This is what gets stamped on every row in the Endpoint Library: axis + tier. A coverage matrix that looks like (axes × tiers × domains) is the actual measure of "is this API surface complete."

What this changes in the existing wiki

Three downstream edits land in the same commit set as this card:

1. canary-go-endpoint-library — add Tier column to every endpoint table; audit all 11 documented services and assign tiers; for each of the 21 undocumented services, propose a tier-shaped endpoint family (not a single generic endpoint); add the bulk-import pattern to Axis A; add a Tier classification section linking back here.
2. canary-go-vs-gk-pos-gap-analysis — add a "Gap as tier coverage, not endpoint count" section; reframe the 9-namespace GK comparison with the tier lens (GK's Pos namespace is stream + reference; their Service API spans daily batch + bulk window; the gap analysis is now multi-dimensional).
3. The dispatch GRO-717 closes on the commit landing.

What this enables downstream

Tier weights are the load-bearing input to the satoshi cost model — the platform's commercial mechanism. A stream-tier consumer costs ~50× a reference-tier consumer at the same event volume; the cadence ladder names the asymmetry, the satoshi cost model prices it. Every event metered carries the tier weight from this card directly into per-merchant accumulation. Without the cadence ladder, the cost model has no defensible weighting basis. With it, every line item on every usage statement traces to a tier defined here.

What this is not

• Not a replacement for the three-axis model. The Adapter / Resource / Agent split stays. This adds a column.
• Not a code change. Wiki + spec only. Config schema, agent contract, runtime parameterization all follow in a feed-tier-contract SDD (separate dispatch).
• Not volatile data. Specific freshness budgets, queue depth thresholds, current feed counts, SLA numbers — those live in code/config, not in this card. The card defines the structure; numbers live in deploy/ and internal/config/.

References

• Source intakes (provenance, abstract in synthesis): Brain/raw/inbox/technical_design_ross_* (7 files, 2011 RTI architecture)
• canary-go-endpoint-library — where tiers stamp every endpoint
• canary-go-vs-gk-pos-gap-analysis — where tier coverage replaces endpoint count as the unit
• canary-go-portal — project portal
• agent-card-format — where agent tier consumption gets declared
• Memory: project_canary_canonical_positioning, project_engine_map_and_main_street_archetype, feedback_no_volatile_data_in_wiki, feedback_extract_working_solution, feedback_no_hand_rolling_outside_core_ip