Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jon Chery
|
79b6749211 | ||
|
Jon Chery
|
c7f46bc0cc | ||
|
Jon Chery
|
7fdd143d03 | ||
|
Jon Chery
|
9f5ed4b5cd |
@@ -1,15 +1,15 @@
|
||||
{
|
||||
"phase": 2,
|
||||
"phase": 4,
|
||||
"stage": "complete",
|
||||
"milestone": "v0.4",
|
||||
"phase_role": "execution",
|
||||
"project": "atelier",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-05T06:30:00Z",
|
||||
"updated_at": "2026-08-05T07:00:00Z",
|
||||
"milestone_complete": false,
|
||||
"milestone_branch": "milestone/v0.4-edge-quantum-langs",
|
||||
"phase_branch": "phase/02-messaging",
|
||||
"phase_branch": "phase/04-matrix-review-manifest",
|
||||
"tag_base": "v0.3",
|
||||
"phase_tag": "v0.3.2",
|
||||
"release_id": 483
|
||||
"phase_tag": "v0.3.4",
|
||||
"release_id": 486
|
||||
}
|
||||
@@ -16,8 +16,18 @@ atelier/
|
||||
│ ├── gitops-operators/ # v0.3: GitOps + Operators (argocd, flux, operators, progressive-delivery)
|
||||
│ ├── ai-ml/ # v0.3: ML engineering (data-versioning, model-evaluation, serving, monitoring-drift)
|
||||
│ ├── i18n/ # v0.3: internationalization (locale-resources, formatting, rtl-bidi, testing-i18n)
|
||||
│ └── compliance/ # v0.3: compliance/audit (audit-logs, data-retention, policy-as-code, evidence)
|
||||
│ ├── compliance/ # v0.3: compliance/audit (audit-logs, data-retention, policy-as-code, evidence)
|
||||
│ ├── edge/ # v0.4: edge computing (cdn, offline-first, iot, sync)
|
||||
│ └── messaging/ # v0.4: cross-process messaging (queues, pubsub, streams, delivery-semantics)
|
||||
├── languages/ # Language-specific application of domains
|
||||
│ ├── typescript.md # v0.1 first-principles stub
|
||||
│ ├── python.md # v0.1 first-principles stub
|
||||
│ ├── go.md # v0.1 first-principles stub
|
||||
│ ├── rust.md # v0.1 first-principles stub
|
||||
│ ├── ts-*.md # v0.4: 4 derived docs (ts-types, ts-tooling, ts-async, ts-testing)
|
||||
│ ├── py-*.md # v0.4: 4 derived docs (py-types, py-tooling, py-async, py-testing)
|
||||
│ ├── go-*.md # v0.4: 4 derived docs (go-types, go-tooling, go-concurrency, go-testing)
|
||||
│ └── rs-*.md # v0.4: 4 derived docs (rs-ownership, rs-tooling, rs-async, rs-testing)
|
||||
├── review/ # Evaluation checklists and anti-patterns
|
||||
├── matrix/ # Cross-reference: domain ↔ core
|
||||
└── examples/ # Worked examples (good + bad)
|
||||
@@ -106,4 +116,28 @@ From the v0.3 ideation stage (IDEATE-17..30), the following architectural refine
|
||||
- **Core Principle Coverage table (IDEATE-19 → ATELIER-81):** `matrix/domain-coverage.md` contains two tables — the per-domain row schema table (covered by v0.2 IDEATE-03) AND the "Core Principle Coverage" table mapping C1–C8 → domains. Both must be extended for the 4 new domains; the C-rule counts shift (e.g., C4 Locality adds i18n + gitops; C5 Reversibility adds ai-ml + compliance + gitops + i18n).
|
||||
- **Cross-link type unchanged:** v0.3 introduces no new cross-link type. All cross-links remain one-directional outward from new domains to existing (D-033). No back-link edits to v0.1/v0.2 content.
|
||||
|
||||
See `.ciagent/atelier/RESEARCH.md` "v0.3 Research" for the full prior-art survey and principle inventory rationale, and `.ciagent/atelier/PERSONAS.md` for the v0.3 persona roster (5 active: lead-developer, tech-writer, domain-expert + 2 phase-specific platform-engineer, ml-engineer; 3 default personas deactivated).
|
||||
See `.ciagent/atelier/RESEARCH.md` "v0.3 Research" for the full prior-art survey and principle inventory rationale, and `.ciagent/atelier/PERSONAS.md` for the v0.3 persona roster (5 active: lead-developer, tech-writer, domain-expert + 2 phase-specific platform-engineer, ml-engineer; 3 default personas deactivated).
|
||||
|
||||
## v0.4 Domain Additions
|
||||
|
||||
Two new top-level domains and a language-derived extension expand the tree under the same hierarchy rules. All follow the v0.1/v0.2/v0.3 contract: docs-only markdown with illustrative code fences (no runtime/deployable artifacts per D-020). Total matrix grows from 170 → 190 domain principles across 17 → 19 domains.
|
||||
|
||||
- **`edge/`** — edge computing domain. Owns the proximity/location/constraint angle (D-061): compute near the user or data source, offline as a first-class state, constrained resources declared, sync conflicts bounded, partition-survivable telemetry. Boundary vs `performance/` (generic measurement/optimization), `observability/` (generic structured telemetry), and `concurrency/` (in-process primitives): edge owns only the proximity/location/disconnection concerns that arise at the network edge — performance's locality is algorithmic, edge's locality is geographic (C4). 10 P-rules, broad derivation (7 C-rules: C1, C3, C4, C5, C6, C7, C8). Depends on `core/`. Cross-links are one-directional outward (D-026 extended): `performance/frontend` (P6 geographic cache invalidation vs generic caching), `performance/P4` (P3 constrained-device vs generic resource bounds), `observability/metrics` + `observability/logging` (P10 local-first telemetry), `concurrency/patterns` (P5 offline write-queue analog), `security/secrets` (P9 device identity), `security/input-validation` (P6 cache poisoning), `data/migrations` (P4 schema migration under sync). Edge↔messaging intra-v0.4 cross-links resolve bidirectionally in P5 (ATELIER-114, IDEATE-40): `edge/iot.md` → `messaging/queues` (MQTT QoS parallels to delivery semantics). Derived docs: `cdn.md`, `offline-first.md`, `iot.md`, `sync.md`.
|
||||
|
||||
- **`messaging/`** — cross-process messaging domain. Owns the cross-process/network-failure-model angle (D-062): messages as contracts, explicit delivery semantics, idempotent consumers, bounded backpressure, observable lag. Boundary vs `concurrency/` (in-process/crash-failure-model): messaging's queue fails by network partition/broker restart/consumer crash-and-retry; concurrency's queue fails by OOM or thread crash. The discriminator is the failure model (D-062). 10 P-rules, broad derivation (7 C-rules: C1, C2, C4, C5, C6, C7, C8). Depends on `core/`. Cross-links are one-directional outward (D-026 extended): `concurrency/patterns` (P6 broker-backed bounded queue vs in-process Pattern 5; P3 cross-process idempotent retry vs in-process retry), `observability/metrics` + `observability/tracing` (P10 broker signals), `data/schema-design` (P1/P9 message schema evolution), `errors/patterns` (P5 errors as data for poison messages), `edge/iot` (P4 — bidirectional resolution of the MQTT QoS cross-link per IDEATE-40). Derived docs: `queues.md`, `pubsub.md`, `streams.md`, `delivery-semantics.md`.
|
||||
|
||||
### v0.4 Language-Derived Extension
|
||||
|
||||
The `languages/` tree extends from a first-principles-only stub (v0.1) to a full derived-doc tree (v0.4). Each of the 4 v0.1 stubs (`typescript.md`, `python.md`, `go.md`, `rust.md`) is extended with a pointer to its 4 derived docs (16 total). Language-derived docs **apply, not derive** domain principles (D-063): they introduce **no new P-rules** and **no new matrix rows** (D-066). Every section header names the traced core C-rule(s) AND the traced domain P-rule(s) inline (e.g., `## Nominal vs Structural Typing (C1 Correctness, Data P7 Type Fidelity, API P1 Contract Fidelity)`). The first-principles stubs retain their existing section structure — **no P1–P10 numbering** is added to languages (D-063); languages are an application lens, not a principle source, preserving the `core > domains > languages` ordering ("conflicts go UP, never sideways").
|
||||
|
||||
The `matrix/principles-matrix.md` gains **no language rows** — it stays at 190 P-rules / 19 domains (D-066). Language-derived-doc traceability is captured in a new `## Languages Coverage` sub-table in `matrix/domain-coverage.md` (exactly 16 rows, one per derived doc) — the verifiable aggregate; inline section-headers are the per-doc detail. Every derived doc traces to ≥1 domain P-rule (D-066, no orphans).
|
||||
|
||||
Derived docs by language:
|
||||
- **TypeScript** — `ts-types.md`, `ts-tooling.md`, `ts-async.md`, `ts-testing.md`
|
||||
- **Python** — `py-types.md`, `py-tooling.md`, `py-async.md`, `py-testing.md`
|
||||
- **Go** — `go-types.md`, `go-tooling.md`, `go-concurrency.md`, `go-testing.md`
|
||||
- **Rust** — `rs-ownership.md`, `rs-tooling.md`, `rs-async.md`, `rs-testing.md`
|
||||
|
||||
The manifest (`MANIFEST.md`) is extended with a new `## Languages` section (D-065) listing the 4 v0.1 stubs (closing pre-existing drift parallel to the v0.2 ESC-002 / ATELIER-91 precedent) and the 16 new v0.4 derived docs. The `review/` docs (agent-checklist, peer-review-checklist, anti-patterns) gain edge, messaging, and language-derived trigger sections. Examples (P5) are illustrative markdown with fenced code only — no standalone `.ts`/`.py`/`.go`/`.rs` runtime artifacts (D-020 docs-only contract, extended in v0.4 to language-derived-doc artifact types).
|
||||
|
||||
See `.ciagent/atelier/RESEARCH-v0.4.md` for the full prior-art survey (Akamai/Cloudflare, Kafka/RabbitMQ/NATS, Jepsen, Reactive Streams, CloudEvents, CRDTs, PouchDB, MQTT/CoAP) and `.ciagent/atelier/PERSONAS.md` for the v0.4 persona roster (5 active: lead-developer, tech-writer, domain-expert + 2 phase-specific edge-engineer, languages-engineer).
|
||||
@@ -133,8 +133,8 @@ NFR milestone: no separate minor tag. The final patch (v0.2.6) IS the v0.3 deliv
|
||||
| 0 | Pre-Execution | docs | complete | Spec, clarify, research, ideate, plan, PERSONAS.md (adds edge-engineer + languages-engineer phase-specific personas) — shipped v0.3.0 |
|
||||
| 1 | Edge Domain | docs | complete | domains/edge/{first-principles, cdn, offline-first, iot, sync}.md — shipped v0.3.1 |
|
||||
| 2 | Messaging Domain | docs | complete | domains/messaging/{first-principles, queues, pubsub, streams, delivery-semantics}.md — shipped v0.3.2 |
|
||||
| 3 | Language-Derived Extension | docs | pending | languages/ × 4 → first-principles + 4 derived docs each (16 derived docs) |
|
||||
| 4 | Matrix + Review Integration | docs | pending | matrix/principles-matrix.md (+20 mappings, 170→190), matrix/domain-coverage.md (+ languages/ sub-table), review/{agent-checklist, peer-review-checklist, anti-patterns}.md, MANIFEST.md (languages/ section) |
|
||||
| 3 | Language-Derived Extension | docs | complete | languages/ × 4 → first-principles + 4 derived docs each (16 derived docs) — shipped v0.3.3 |
|
||||
| 4 | Matrix + Review Integration | docs | complete | matrix/principles-matrix.md (+20 mappings, 170→190), matrix/domain-coverage.md (+ languages/ sub-table), review/{agent-checklist, peer-review-checklist, anti-patterns}.md, MANIFEST.md (languages/ section), ARCHITECTURE.md — shipped v0.3.4 |
|
||||
| 5 | Examples + Cross-Links | docs | pending | examples/good + examples/bad for 2 domains, cross-links to devops/observability/data/concurrency/kubernetes/infrastructure-as-code + language→domain links |
|
||||
| 6 | Final Review + Ship | docs | pending | Review passed, audit clean, milestone merged to main, tag v0.3.6 |
|
||||
|
||||
|
||||
+20
-5
@@ -40,6 +40,21 @@
|
||||
| AI / ML | ✓ | data-versioning, model-evaluation, serving, monitoring-drift |
|
||||
| i18n | ✓ | locale-resources, formatting, rtl-bidi, testing-i18n |
|
||||
| Compliance | ✓ | audit-logs, data-retention, policy-as-code, evidence |
|
||||
| Edge | ✓ | cdn, offline-first, iot, sync |
|
||||
| Messaging | ✓ | queues, pubsub, streams, delivery-semantics |
|
||||
|
||||
## Languages
|
||||
|
||||
> Language docs apply (not derive) domain principles. They introduce
|
||||
> no new P-rules and no new matrix rows (D-063, D-066). First-
|
||||
> principles stubs from v0.1; derived docs added in v0.4.
|
||||
|
||||
| Language | First Principles | Derived Documents |
|
||||
|----------|------------------|-------------------|
|
||||
| TypeScript | ✓ (v0.1 stub) | ts-types, ts-tooling, ts-async, ts-testing |
|
||||
| Python | ✓ (v0.1 stub) | py-types, py-tooling, py-async, py-testing |
|
||||
| Go | ✓ (v0.1 stub) | go-types, go-tooling, go-concurrency, go-testing |
|
||||
| Rust | ✓ (v0.1 stub) | rs-ownership, rs-tooling, rs-async, rs-testing |
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -71,8 +86,8 @@
|
||||
|
||||
| Document | Purpose |
|
||||
|-----------------------------------|----------------------------------|
|
||||
| `matrix/principles-matrix.md` | Maps domain → core principles (17 domains, 170 P-rules post-v0.3) |
|
||||
| `matrix/domain-coverage.md` | Maps core → domains; per-domain coverage (incl. v0.3 Core Principle Coverage) |
|
||||
| `review/agent-checklist.md` | Pre-completion agent checklist (incl. IaC + k8s + gitops + ai-ml + i18n + compliance triggers) |
|
||||
| `review/peer-review-checklist.md` | Human peer-review checklist (incl. IaC + k8s + gitops + ai-ml + i18n + compliance sections) |
|
||||
| `review/anti-patterns.md` | Catalog of violations (incl. IaC + k8s + gitops + ai-ml + i18n + compliance + v0.3 chaos anti-patterns) |
|
||||
| `matrix/principles-matrix.md` | Maps domain → core principles (19 domains, 190 P-rules post-v0.4) |
|
||||
| `matrix/domain-coverage.md` | Maps core → domains; per-domain coverage (incl. v0.4 Core Principle Coverage + Languages Coverage sub-table) |
|
||||
| `review/agent-checklist.md` | Pre-completion agent checklist (incl. edge + messaging + language-derived triggers) |
|
||||
| `review/peer-review-checklist.md` | Human peer-review checklist (incl. edge + messaging + language-derived sections) |
|
||||
| `review/anti-patterns.md` | Catalog of violations (incl. edge + messaging + language-derived + v0.4 chaos anti-patterns + .ts/.py/.go/.rs artifact types) |
|
||||
@@ -0,0 +1,158 @@
|
||||
# Bad Example: Edge Sync Loop (Livelock)
|
||||
|
||||
> A two-node sync that oscillates divergent state forever. This is
|
||||
> the pre-specified `edge-sync-loop` chaos anti-pattern (ATELIER-110).
|
||||
> **Single-breach per D-068:** the principle breached is **Edge P4
|
||||
> (Sync Conflicts are Bounded, Not Infinite)**. The prose explains
|
||||
> why this is a livelock, not eventual consistency.
|
||||
|
||||
## The Code
|
||||
|
||||
```typescript
|
||||
// Two edge nodes (a tablet and a dispatcher workstation) sync a
|
||||
// work-order status. The merge uses wall-clock timestamps with no
|
||||
// vector clock and no deterministic tiebreak. A clock skew flips
|
||||
// the winner on every merge pass; the state oscillates forever.
|
||||
|
||||
interface WorkOrderState {
|
||||
orderId: string;
|
||||
status: string;
|
||||
wallClock: number; // P4 VIOLATION: wall time, not monotonic
|
||||
nodeId: string;
|
||||
}
|
||||
|
||||
// P4 VIOLATION: the merge picks the later wall-clock write as the
|
||||
// winner. Wall time skews across nodes; a skew of even a few
|
||||
// milliseconds flips the winner. With no vector clock, concurrent
|
||||
// writes are not detected; with no deterministic tiebreak, equal
|
||||
// timestamps are resolved by whichever node's clock is ahead.
|
||||
function mergeBad(local: WorkOrderState, remote: WorkOrderState): WorkOrderState {
|
||||
// No vector clock. No monotonic logical clock. No deterministic
|
||||
// tiebreak by nodeId. This is wall-clock-only LWW on durable
|
||||
// state — the row in the CRDT-vs-LWW decision matrix that is a
|
||||
// P4 violation for anything but ephemeral state.
|
||||
if (local.wallClock >= remote.wallClock) return local;
|
||||
return remote;
|
||||
}
|
||||
|
||||
// The sync loop: each node merges the other's state, writes the
|
||||
// result, and the next sync pass flips it back. The loop never
|
||||
// terminates.
|
||||
async function syncLoop(node: "tablet" | "dispatcher", peer: WorkOrderState) {
|
||||
let local = store.get(peer.orderId);
|
||||
while (true) {
|
||||
const merged = mergeBad(local, peer);
|
||||
store.set(merged.orderId, merged);
|
||||
await pushToPeer(merged); // peer receives, merges, pushes back
|
||||
peer = await pullFromPeer(); // peer's clock is now ahead — flips winner
|
||||
local = store.get(peer.orderId); // local re-merges; flips again
|
||||
// The loop runs forever. Convergence is never reached. This is
|
||||
// a livelock: the system is making progress (each pass writes)
|
||||
// but the state never converges.
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The tablet sets `status: "completed"` at wall time `10:00:00.500`.
|
||||
The dispatcher's clock is 50ms ahead; it sets `status: "reassigned"`
|
||||
at wall time `10:00:00.550`. The first merge: dispatcher wins
|
||||
(`10:00:00.550 > 10:00:00.500`). The tablet receives `reassigned`,
|
||||
but its clock drifts ahead by 100ms during the next sync pass; it
|
||||
writes `completed` at `10:00:00.650`. The second merge: tablet
|
||||
wins. The dispatcher's clock drifts ahead again; it writes
|
||||
`reassigned` at `10:00:00.750`. The third merge: dispatcher wins.
|
||||
The state flips between `completed` and `reassigned` on every sync
|
||||
pass. The loop runs forever.
|
||||
|
||||
## Why It Violates
|
||||
|
||||
### Sync Conflicts are Bounded, Not Infinite (Edge P4, C1, C5)
|
||||
|
||||
- **The breach:** the merge has no convergence bound. The CRDT-vs-
|
||||
LWW decision matrix in `domains/edge/sync.md` is explicit:
|
||||
wall-clock-only LWW on durable state carries an **unbounded
|
||||
failure mode** — clock skew = oscillation — and is a P4
|
||||
violation for anything but ephemeral state. This code is the
|
||||
matrix's failure column made real.
|
||||
- **Why it is a livelock, not eventual consistency:** eventual
|
||||
consistency guarantees that, in the absence of new writes, all
|
||||
replicas eventually converge. This system never converges even
|
||||
with no new writes: the clock skew alone drives the oscillation.
|
||||
Each sync pass writes (so the system is "busy"), but the state
|
||||
never settles — the definition of a livelock. The P4 contract is
|
||||
that the merge terminates and converges; this merge does neither.
|
||||
- The missing pieces, per the decision matrix:
|
||||
- **No monotonic logical clock** (a hybrid logical clock or
|
||||
vector clock) — wall time skews, and the skew is unbounded.
|
||||
- **No vector clock** — concurrent writes are not detected, so
|
||||
the conflict is invisible; the merge silently flips instead of
|
||||
surfacing.
|
||||
- **No deterministic tiebreak** (e.g., `nodeId`) on equal
|
||||
timestamps — equal wall times are resolved by whichever node's
|
||||
clock is ahead, which is not a stable property.
|
||||
- The P4 bound requires that the merge function be associative,
|
||||
commutative, and idempotent, terminating in one pass. A
|
||||
wall-clock merge with clock skew satisfies none of these: it is
|
||||
not associative (order of merges flips the winner), not
|
||||
idempotent (a re-merge after a clock drift flips the result),
|
||||
and not terminating (the loop runs forever).
|
||||
|
||||
## The Fix
|
||||
|
||||
```typescript
|
||||
// Fix: replace wall-clock LWW with a CRDT register (state-based
|
||||
// CvRDT) using a monotonic logical clock and a deterministic
|
||||
// tiebreak by nodeId. The merge is now a total order — no
|
||||
// oscillation (P4 bounded). See the CRDT-vs-LWW decision matrix:
|
||||
// for a register on an unreliable network, a state-based CRDT is
|
||||
// the correct row.
|
||||
|
||||
interface LWWRegister<T> {
|
||||
value: T;
|
||||
timestamp: number; // monotonic logical clock (HLC), not wall time
|
||||
nodeId: string; // deterministic tiebreak
|
||||
}
|
||||
|
||||
function mergeLWWRegister<T>(
|
||||
local: LWWRegister<T>,
|
||||
remote: LWWRegister<T>,
|
||||
): LWWRegister<T> {
|
||||
// Associative, commutative, idempotent (P4 bound, P5 idempotent).
|
||||
// (timestamp, nodeId) is a total order — convergence in one pass.
|
||||
if (local.timestamp > remote.timestamp) return local;
|
||||
if (local.timestamp < remote.timestamp) return remote;
|
||||
return local.nodeId > remote.nodeId ? local : remote;
|
||||
}
|
||||
|
||||
// The sync is now one pass: merge, write, done. No loop, no
|
||||
// oscillation. A re-merge of the same two replicas yields the same
|
||||
// result (P5 idempotent), so a retried sync is safe.
|
||||
async function syncOnce(local: LWWRegister<unknown>, remote: LWWRegister<unknown>) {
|
||||
const converged = mergeLWWRegister(local, remote);
|
||||
store.set(converged);
|
||||
await pushToPeer(converged);
|
||||
// Done. No while(true). The merge terminates.
|
||||
}
|
||||
```
|
||||
|
||||
The fix selects the CRDT row of the decision matrix (a register on
|
||||
an unreliable network): a monotonic logical clock (HLC) eliminates
|
||||
clock skew; a deterministic tiebreak by `nodeId` eliminates the
|
||||
equal-timestamp flip. The merge is now a total order that converges
|
||||
in one pass — the P4 bound. See `examples/good/edge-offline-sync.md`
|
||||
for the full good-example version of this pattern.
|
||||
|
||||
## Cross-Domain Links
|
||||
|
||||
- `domains/edge/sync.md` — the CRDT-vs-LWW decision matrix; the
|
||||
wall-clock-only LWW row is the failure mode this example
|
||||
instantiates; the CRDT row is the fix.
|
||||
- `domains/edge/first-principles.md` — P4 (Sync Conflicts are
|
||||
Bounded, Not Infinite) is the principle breached.
|
||||
- `review/anti-patterns.md` — the `edge-sync-loop` chaos
|
||||
anti-pattern (edge P4, C1, C5 — infinite oscillation is a
|
||||
correctness failure, not eventual consistency; the sync is a
|
||||
livelock).
|
||||
- `examples/good/edge-offline-sync.md` — the good-example version
|
||||
of this pattern: a CRDT register merge that converges in one
|
||||
pass.
|
||||
@@ -0,0 +1,188 @@
|
||||
# Bad Example: Messaging Shared Subscription
|
||||
|
||||
> Two consumers share one subscription; the broker dispatches each
|
||||
> message to an arbitrary consumer. Per-consumer ordering breaks;
|
||||
> per-consumer dedup is wrong. This is the pre-specified
|
||||
> `messaging-shared-subscription` chaos anti-pattern (ATELIER-110).
|
||||
> **Single-breach per D-068:** the primary principle breached is
|
||||
> **Messaging P2 (Ordering is a Property, Not an Assumption)**. P3
|
||||
> (Consumers are Idempotent) is noted as the compounding
|
||||
> consequence — the example remains single-breach in its named
|
||||
> violation.
|
||||
|
||||
## The Code
|
||||
|
||||
```python
|
||||
# Two email workers share ONE subscription on the "users" topic.
|
||||
# The broker round-robins: worker A gets msg 1, msg 3; worker B
|
||||
# gets msg 2, msg 4. Per-consumer order is broken (P2 breach).
|
||||
# Each worker has its OWN dedup store — a redelivery to the other
|
||||
# worker re-processes (P3 compounding).
|
||||
|
||||
import json
|
||||
|
||||
def shared_subscription_bad(broker, send_email, worker_id: str):
|
||||
# P2 VIOLATION: both workers call subscribe with the SAME
|
||||
# subscription name. The broker dispatches each message to an
|
||||
# arbitrary worker in the shared group. Worker A sees msg 3
|
||||
# before worker B sees msg 1; per-worker order is broken.
|
||||
sub = broker.subscribe(topic="users", subscription="welcome-shared")
|
||||
|
||||
# P3 compounding: per-worker dedup. A redelivered message may
|
||||
# land on the OTHER worker, which has not seen it, so the
|
||||
# per-worker dedup store does not catch it — the message is
|
||||
# processed twice across the two workers.
|
||||
local_dedup = DedupStore(backend=redis_for(worker_id))
|
||||
|
||||
for message in sub.receive():
|
||||
payload = json.loads(message["body"])
|
||||
if local_dedup.seen(payload["idempotencyKey"]):
|
||||
sub.ack(message); continue
|
||||
send_email(payload["email"], "Welcome!")
|
||||
local_dedup.mark(payload["idempotencyKey"])
|
||||
sub.ack(message)
|
||||
```
|
||||
|
||||
```python
|
||||
# The two workers are launched with the same subscription name.
|
||||
# Worker A and Worker B both call subscribe("users", "welcome-shared").
|
||||
# The broker sees one shared subscription; it round-robins.
|
||||
|
||||
def start_workers(broker):
|
||||
# Worker A
|
||||
spawn(shared_subscription_bad, broker, send_email, worker_id="A")
|
||||
# Worker B — same subscription name, same topic
|
||||
spawn(shared_subscription_bad, broker, send_email, worker_id="B")
|
||||
# The broker dispatches: A gets msg 1, B gets msg 2, A gets msg 3,
|
||||
# B gets msg 4. If worker A is slow, B may get msg 2 and msg 4
|
||||
# before A acks msg 1. Per-worker order is broken (P2).
|
||||
```
|
||||
|
||||
The scenario: a user signs up, then immediately updates their
|
||||
email preference (two messages in topic order: `user.signed-up.v1`,
|
||||
`user.preference-updated.v1`). The broker dispatches `signed-up` to
|
||||
worker A and `preference-updated` to worker B. Worker B sends the
|
||||
preference email before worker A sends the welcome email — the
|
||||
user sees the preference confirmation before the welcome. Then the
|
||||
broker redelivers `signed-up` (worker A's ack was slow); this time
|
||||
it dispatches to worker B. Worker B's local dedup store has never
|
||||
seen `signed-up` (it was processed by A), so B sends the welcome
|
||||
email again. The user receives two welcome emails. Per-consumer
|
||||
ordering broke (P2); per-consumer dedup did not catch the
|
||||
cross-worker redelivery (P3 compounding).
|
||||
|
||||
## Why It Violates
|
||||
|
||||
### Ordering is a Property, Not an Assumption (Messaging P2, C1, C2)
|
||||
|
||||
- **The breach (primary):** the two workers share one subscription,
|
||||
and the broker dispatches each message to an arbitrary worker in
|
||||
the shared group. Per-consumer ordering is broken: worker A sees
|
||||
`preference-updated` (msg 2) before it sees `signed-up` (msg 1)
|
||||
if the broker round-robins them to different workers. The
|
||||
workers' code assumes topic order, but the shared subscription
|
||||
provides no per-consumer order guarantee — the broker's dispatch
|
||||
is arbitrary. P2 requires that the ordering property be explicit
|
||||
and documented; here it is assumed (topic order) but not provided
|
||||
(arbitrary dispatch). The assumption is wrong.
|
||||
- The P2 contract is that "it's FIFO" is a claim backed by the
|
||||
broker's partitioning contract, not an assumption the consumer
|
||||
makes. A shared subscription's contract is "no per-consumer
|
||||
order"; the workers' code assumes the opposite. See
|
||||
`domains/messaging/pubsub.md` (Shared vs Independent
|
||||
Subscriptions) and `domains/messaging/first-principles.md` P2.
|
||||
|
||||
### Consumers are Idempotent — compounding consequence (Messaging P3, C1)
|
||||
|
||||
- **The compounding consequence (not the named breach):** each
|
||||
worker has its OWN dedup store. A redelivered message that lands
|
||||
on the *other* worker is not in that worker's dedup store, so it
|
||||
is processed again. The dedup is per-worker, but the subscription
|
||||
is shared — the dedup must be shared across workers to be
|
||||
correct under a shared subscription. The per-worker dedup store
|
||||
is wrong for a shared subscription; a shared dedup store (a
|
||||
shared Redis, a shared DB) is required.
|
||||
- Per D-068, the example remains single-breach in its named
|
||||
violation: P2 is the primary breach (the shared subscription
|
||||
breaks ordering); P3 is the compounding consequence (the
|
||||
per-worker dedup is wrong *because* the subscription is shared).
|
||||
If the subscription were independent, per-worker dedup would be
|
||||
correct. The shared subscription is the root cause; P3 is the
|
||||
downstream effect.
|
||||
|
||||
## The Fix
|
||||
|
||||
```python
|
||||
# Fix 1 (default): independent subscriptions. Each consumer gets
|
||||
# its own durable cursor; per-consumer order holds (P2); per-
|
||||
# consumer dedup is correct (P3). This is the default per
|
||||
# domains/messaging/pubsub.md.
|
||||
|
||||
def independent_subscriptions_good(broker, send_email, worker_id: str):
|
||||
# Each worker has its OWN subscription name. The broker
|
||||
# delivers every message to every subscription in topic order.
|
||||
sub = broker.subscribe(
|
||||
topic="users",
|
||||
subscription=f"welcome-{worker_id}", # per-consumer
|
||||
)
|
||||
# Per-consumer dedup is now correct: a redelivery to THIS
|
||||
# worker is caught by THIS worker's dedup store.
|
||||
dedup = DedupStore(backend=redis_for(worker_id))
|
||||
for message in sub.receive():
|
||||
payload = json.loads(message["body"])
|
||||
if dedup.seen(payload["idempotencyKey"]):
|
||||
sub.ack(message); continue
|
||||
send_email(payload["email"], "Welcome!")
|
||||
dedup.mark(payload["idempotencyKey"])
|
||||
sub.ack(message)
|
||||
```
|
||||
|
||||
```python
|
||||
# Fix 2 (if a shared subscription is genuinely required): the
|
||||
# consumers must be stateless, the processing order-independent,
|
||||
# AND the dedup store must be SHARED across workers. Document the
|
||||
# ordering property as "none across consumers" (P2 — the property
|
||||
# is explicit, not assumed) and use a shared dedup backend (P3).
|
||||
|
||||
def shared_subscription_stateless(broker, send_email):
|
||||
# P2: document the ordering property. A shared subscription
|
||||
# provides NO per-consumer order; processing must be order-
|
||||
# independent. Do not assume topic order.
|
||||
sub = broker.subscribe(topic="users", subscription="welcome-shared")
|
||||
# P3: SHARED dedup. A redelivery to any worker is caught by the
|
||||
# shared store.
|
||||
shared_dedup = DedupStore(backend=shared_redis)
|
||||
for message in sub.receive():
|
||||
payload = json.loads(message["body"])
|
||||
if shared_dedup.seen(payload["idempotencyKey"]):
|
||||
sub.ack(message); continue
|
||||
send_email(payload["email"], "Welcome!") # order-independent
|
||||
shared_dedup.mark(payload["idempotencyKey"])
|
||||
sub.ack(message)
|
||||
```
|
||||
|
||||
The default is Fix 1 (independent subscriptions): per-consumer
|
||||
ordering holds, per-consumer dedup is correct, and the code is
|
||||
simpler. Fix 2 is the narrow opt-in for genuinely stateless,
|
||||
order-independent processing — and even then, the dedup must be
|
||||
shared. See `domains/messaging/pubsub.md` for the full
|
||||
shared-vs-independent discussion.
|
||||
|
||||
## Cross-Domain Links
|
||||
|
||||
- `domains/messaging/pubsub.md` — the shared-vs-independent
|
||||
subscriptions section; the `messaging-shared-subscription`
|
||||
anti-pattern lives here (pre-specified in P4 ATELIER-110).
|
||||
- `domains/messaging/first-principles.md` — P2 (Ordering is a
|
||||
Property, Not an Assumption) is the primary breach; P3
|
||||
(Consumers are Idempotent) is the compounding consequence.
|
||||
- `domains/messaging/delivery-semantics.md` — the idempotency-key
|
||||
dedup store; the per-subscription dedup key scoping
|
||||
(`(subscription, idempotencyKey)`) that prevents one
|
||||
subscription's dedup from masking another's redelivery.
|
||||
- `review/anti-patterns.md` — the `messaging-shared-subscription`
|
||||
chaos anti-pattern (messaging P2, P3, C1 — shared subscription
|
||||
breaks ordering and dedup).
|
||||
- `examples/good/messaging-idempotent-consumer.md` — the good-
|
||||
example version of the consumer pattern: an independent consumer
|
||||
with a dedup store and a DLQ routing rule.
|
||||
@@ -0,0 +1,223 @@
|
||||
# Good Example: Edge Offline-First + Sync Reconcile
|
||||
|
||||
> A field-service tablet app that operates through a 90-minute network
|
||||
> partition, queues writes locally, and reconciles on reconnect using
|
||||
> the CRDT-vs-LWW decision matrix from `domains/edge/sync.md`. Each
|
||||
> aspect cites the edge principle it satisfies.
|
||||
|
||||
## The Code
|
||||
|
||||
```typescript
|
||||
// The local store: an offline-first write queue + a CRDT register
|
||||
// per record. The tablet keeps working through the partition; the
|
||||
// queue drains on reconnect; the merge converges (P4 bounded).
|
||||
|
||||
interface LWWRegister<T> {
|
||||
value: T;
|
||||
timestamp: number; // monotonic logical clock (HLC), NOT wall time
|
||||
nodeId: string; // tablet id — deterministic tiebreak (P4)
|
||||
}
|
||||
|
||||
interface QueuedWrite {
|
||||
idempotencyKey: string; // P5: retried syncs are safe
|
||||
collection: string;
|
||||
recordId: string;
|
||||
register: LWWRegister<unknown>;
|
||||
queuedAt: number;
|
||||
}
|
||||
|
||||
class OfflineStore {
|
||||
private queue: QueuedWrite[] = [];
|
||||
private state: Map<string, LWWRegister<unknown>> = new Map();
|
||||
private telemetryBuffer: TelemetryRecord[] = []; // P10 local-first
|
||||
|
||||
// P2: write succeeds offline. The queue is the durable record of
|
||||
// intent; sync is deferred, not blocked.
|
||||
write(collection: string, recordId: string, value: unknown, key: string): void {
|
||||
const register: LWWRegister<unknown> = {
|
||||
value,
|
||||
timestamp: this.hlc.now(), // monotonic; no wall-clock skew
|
||||
nodeId: this.nodeId,
|
||||
};
|
||||
this.state.set(`${collection}:${recordId}`, register);
|
||||
this.queue.push({
|
||||
idempotencyKey: key, // P5: idempotent sync
|
||||
collection, recordId, register,
|
||||
queuedAt: this.hlc.now(),
|
||||
});
|
||||
// P10: buffer the write event locally; forwarded on reconnect.
|
||||
this.telemetryBuffer.push({ event: "local.write", at: Date.now(), key });
|
||||
}
|
||||
|
||||
// P2: read from local state offline. The UI never blocks on the
|
||||
// network.
|
||||
read(collection: string, recordId: string): unknown {
|
||||
return this.state.get(`${collection}:${recordId}`)?.value;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// The CRDT register merge — a state-based CvRDT (convergent). Per the
|
||||
// CRDT-vs-LWW decision matrix in domains/edge/sync.md, a state-based
|
||||
// CRDT is the choice when the data model fits a register and the
|
||||
// network is unreliable (full-state merge tolerates dropped ops).
|
||||
|
||||
function mergeLWWRegister<T>(
|
||||
local: LWWRegister<T>,
|
||||
remote: LWWRegister<T>,
|
||||
): LWWRegister<T> {
|
||||
// Associative, commutative, idempotent (P4 bound, P5 idempotent).
|
||||
// (timestamp, nodeId) is a total order — no oscillation.
|
||||
if (local.timestamp > remote.timestamp) return local;
|
||||
if (local.timestamp < remote.timestamp) return remote;
|
||||
return local.nodeId > remote.nodeId ? local : remote; // deterministic tie
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// The reconnect reconcile: drain the offline queue, pull remote
|
||||
// state, three-way merge (CRDT registers), push converged state.
|
||||
// Idempotent keys make a retried reconcile safe (P5).
|
||||
|
||||
async function reconcile(store: OfflineStore, server: SyncServer): Promise<ReconcileReport> {
|
||||
// P5: the reconcile is idempotent. The idempotency key on each
|
||||
// queued write means a retry (network flapped mid-reconcile) does
|
||||
// not double-apply.
|
||||
const queued = store.drainQueue();
|
||||
let pushed = 0, merged = 0, conflicts = 0;
|
||||
|
||||
// 1. Push local writes. The server dedups by idempotencyKey (P5).
|
||||
for (const w of queued) {
|
||||
await server.applyWrite(w.idempotencyKey, w.collection, w.recordId, w.register);
|
||||
pushed++;
|
||||
}
|
||||
|
||||
// 2. Pull remote state for every record we touched + every record
|
||||
// the server changed since our last sync cursor. Merge via CRDT.
|
||||
const remoteRecords = await server.fetchChanged(store.syncCursor());
|
||||
for (const [key, remoteReg] of remoteRecords) {
|
||||
const localReg = store.localRegister(key);
|
||||
if (localReg) {
|
||||
// P4: CRDT merge converges. The merge is a pure function of
|
||||
// two inputs; the total order (timestamp, nodeId) guarantees
|
||||
// no oscillation.
|
||||
const converged = mergeLWWRegister(localReg, remoteReg);
|
||||
if (converged !== localReg) { conflicts++; }
|
||||
store.setLocal(key, converged);
|
||||
merged++;
|
||||
} else {
|
||||
store.setLocal(key, remoteReg); // remote-only record
|
||||
merged++;
|
||||
}
|
||||
}
|
||||
|
||||
// 3. P10: flush the buffered telemetry. The partition did not blind
|
||||
// the operator — the events survived on-node.
|
||||
store.flushTelemetry();
|
||||
|
||||
return { pushed, merged, conflicts, converged: true };
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// P10: local-first telemetry. Events are buffered on-node and
|
||||
// forwarded on reconnect. A fire-and-forget pipeline loses data when
|
||||
// the link drops; a local-first buffer survives.
|
||||
|
||||
interface TelemetryRecord { event: string; at: number; key: string; }
|
||||
|
||||
class TelemetryBuffer {
|
||||
private buffer: TelemetryRecord[] = [];
|
||||
|
||||
push(rec: TelemetryRecord): void { this.buffer.push(rec); }
|
||||
|
||||
// Called from reconcile() on reconnect. The buffer is the P10
|
||||
// guarantee: the operator sees the partition-window activity,
|
||||
// not a gap.
|
||||
async flush(sink: TelemetrySink): Promise<void> {
|
||||
for (const rec of this.buffer) { await sink.emit(rec); }
|
||||
this.buffer = [];
|
||||
}
|
||||
|
||||
depth(): number { return this.buffer.length; }
|
||||
}
|
||||
```
|
||||
|
||||
## The Scenario
|
||||
|
||||
A field-service tablet is dispatched to a basement site with no
|
||||
cellular coverage. The technician updates the work-order status
|
||||
(`started`, `parts-ordered`, `completed`) five times over 90
|
||||
minutes. Each write lands in the local store immediately — the UI
|
||||
never blocks on the network. The writes are queued with an
|
||||
idempotency key (the work-order id + a monotonic sequence).
|
||||
|
||||
When the tablet reconnects, the reconcile drains the queue: the
|
||||
server dedups by idempotency key (a retry mid-reconcile does not
|
||||
double-apply). The server also returns a remote update — the
|
||||
dispatcher re-assigned the work order to a different technician at
|
||||
minute 45, then reverted at minute 60. The CRDT merge converges:
|
||||
the register with the later logical timestamp wins; the tiebreak by
|
||||
node id is deterministic. The merge terminates in one pass (P4
|
||||
bounded); it does not oscillate between the dispatcher's revert and
|
||||
the technician's status updates. The buffered telemetry flushes,
|
||||
and the operator sees the full partition-window activity — no gap.
|
||||
|
||||
## Principles Demonstrated
|
||||
|
||||
### Offline is a First-Class State (Edge P2, C1, C5)
|
||||
- The tablet writes and reads through the partition. The UI never
|
||||
blocks on the network; the offline write queue is the durable
|
||||
record of intent. Partition is the norm, not the exception;
|
||||
reconciliation happens on reconnect. An app that crashes on
|
||||
disconnect has no offline state; this app engineers it.
|
||||
- See `domains/edge/offline-first.md` (offline write-queue) and
|
||||
`domains/edge/first-principles.md` P2.
|
||||
|
||||
### Sync Conflicts are Bounded, Not Infinite (Edge P4, C1, C5)
|
||||
- The CRDT register merge is associative, commutative, and
|
||||
idempotent. The total order `(timestamp, nodeId)` guarantees
|
||||
convergence in one pass — no oscillation, no infinite loop. This
|
||||
is the P4 bound: the merge terminates. The CRDT-vs-LWW decision
|
||||
matrix in `domains/edge/sync.md` selected a state-based CRDT
|
||||
because the data model fits a register and the network is
|
||||
unreliable (full-state merge tolerates dropped ops).
|
||||
- See `domains/edge/sync.md` (CRDT-vs-LWW decision matrix, merge
|
||||
semantics) and `domains/edge/first-principles.md` P4.
|
||||
|
||||
### Edge Operations are Idempotent (Edge P5, C1)
|
||||
- Every queued write carries an idempotency key; the server dedups
|
||||
by key. A reconcile retried mid-flap does not double-apply. The
|
||||
merge function is idempotent (`merge(a, a) === a`) — a retried
|
||||
merge of the same two replicas yields the same result. Sync, the
|
||||
retried-by-nature operation, is safe.
|
||||
- See `domains/edge/sync.md` (Merge Semantics, P5) and
|
||||
`domains/edge/first-principles.md` P5.
|
||||
|
||||
### Edge Observability Survives Partition (Edge P10, C7, C5)
|
||||
- Telemetry is buffered on-node (`telemetryBuffer`) and flushed on
|
||||
reconnect. The partition did not blind the operator — the
|
||||
partition-window activity is forwarded, not lost. A
|
||||
fire-and-forget pipeline would have a 90-minute gap; the
|
||||
local-first buffer survives.
|
||||
- See `domains/edge/offline-first.md` (local-first logging) and
|
||||
`domains/edge/first-principles.md` P10.
|
||||
|
||||
## Cross-Domain Links
|
||||
|
||||
- `domains/edge/offline-first.md` — the offline write-queue pattern
|
||||
this app instantiates; the partition-as-norm discipline.
|
||||
- `domains/edge/sync.md` — the CRDT-vs-LWW decision matrix exercised
|
||||
here (state-based CvRDT chosen for register + unreliable network);
|
||||
the merge-semantics properties (associative, commutative,
|
||||
idempotent).
|
||||
- `domains/edge/first-principles.md` — P2, P4, P5, P10 are the
|
||||
principles demonstrated.
|
||||
- `domains/concurrency/patterns` — the in-process immutability
|
||||
analog (`concurrency/P1 Immutability by Default`) that makes the
|
||||
merge a pure function of two inputs.
|
||||
- `domains/observability/metrics` — the generic SLI/SLO discipline
|
||||
the local-first telemetry buffer builds on.
|
||||
- `review/anti-patterns.md` — the `edge-sync-loop` chaos
|
||||
anti-pattern is the inverse of this example's bounded CRDT merge.
|
||||
@@ -0,0 +1,226 @@
|
||||
# Good Example: Idempotent Consumer with Dedup + DLQ
|
||||
|
||||
> An orders-consumer that achieves exactly-once-via-idempotency:
|
||||
> at-least-once delivery plus a TTL-bounded dedup store and a DLQ
|
||||
> routing rule. Each aspect cites the messaging principle it
|
||||
> satisfies. Exercises the idempotency + DLQ guidance in
|
||||
> `domains/messaging/delivery-semantics.md`.
|
||||
|
||||
## The Code
|
||||
|
||||
```python
|
||||
# The idempotency-key dedup store (P3). TTL-bounded (P6): a dedup
|
||||
# store with no TTL is a memory leak. The TTL exceeds the broker's
|
||||
# max-redelivery window; beyond it, the key is expired (the broker
|
||||
# has given up).
|
||||
|
||||
import time, json
|
||||
|
||||
DEDUP_TTL_SECONDS = 24 * 3600 # > broker max-redelivery window
|
||||
|
||||
class DedupStore:
|
||||
"""P3 (idempotent), P6 (TTL-bounded). seen() before process;
|
||||
mark() after process; the order gives at-least-once + dedup."""
|
||||
|
||||
def __init__(self, backend):
|
||||
# backend is Redis or a shared DB. MUST be shared across
|
||||
# consumer instances (see messaging/pubsub.md on shared vs
|
||||
# independent subscriptions).
|
||||
self.backend = backend
|
||||
|
||||
def seen(self, key: str) -> bool:
|
||||
ts = self.backend.get(key)
|
||||
if ts is None:
|
||||
return False
|
||||
if time.time() - ts > DEDUP_TTL_SECONDS:
|
||||
self.backend.delete(key) # P6: expired; not a redelivery
|
||||
return False
|
||||
return True
|
||||
|
||||
def mark(self, key: str):
|
||||
self.backend.set(key, time.time(), ttl=DEDUP_TTL_SECONDS)
|
||||
```
|
||||
|
||||
```python
|
||||
# The idempotent consumer. Order: dedup BEFORE process, mark AFTER
|
||||
# process, ack AFTER mark. A crash before mark re-processes (the
|
||||
# dedup store lacks the key); a crash before ack redelivers and the
|
||||
# dedup store makes the redelivery a no-op (P3). For a
|
||||
# non-idempotent process (a payment that must not double-charge),
|
||||
# process+mark are one DB transaction — exactly-once via
|
||||
# idempotency (P4).
|
||||
|
||||
def consume_orders(broker, dedup: DedupStore, process_order):
|
||||
for message in broker.receive():
|
||||
payload = json.loads(message["body"])
|
||||
|
||||
# P3: dedup BEFORE process. A redelivered message is a
|
||||
# no-op, not a double-apply.
|
||||
if dedup.seen(payload["idempotencyKey"]):
|
||||
broker.ack(message) # already processed; skip
|
||||
continue
|
||||
|
||||
try:
|
||||
# P4: the declared semantic is at-least-once + idempotent
|
||||
# dedup = exactly-once-via-idempotency. For a payment,
|
||||
# process_order + dedup.mark run in one DB transaction
|
||||
# so the mark commits iff the process commits.
|
||||
process_order(payload)
|
||||
dedup.mark(payload["idempotencyKey"])
|
||||
broker.ack(message)
|
||||
|
||||
except TransientError as exc:
|
||||
# P6: bounded retry with backoff. Nack for redelivery;
|
||||
# the broker redelivers after exponential backoff.
|
||||
broker.nack(message, delay=backoff(payload.get("attempt", 0)))
|
||||
|
||||
except (ValueError, SchemaError) as exc:
|
||||
# P5: poison message — unparseable. Route immediately,
|
||||
# do NOT retry (no retry will fix a bad schema).
|
||||
route_to_dlq(broker, message, exc, kind="poison")
|
||||
broker.ack(message)
|
||||
|
||||
except PermanentError as exc:
|
||||
# P5: permanent failure (e.g., not-found dependency).
|
||||
# Retry will not fix it — DLQ now.
|
||||
route_to_dlq(broker, message, exc, kind="dlq")
|
||||
broker.ack(message)
|
||||
```
|
||||
|
||||
```python
|
||||
# The DLQ routing rule (P5 dead-letter handling, P10 DLQ depth
|
||||
# alert). Distinguishes poison (unparseable; never retried) from
|
||||
# DLQ (exhausted retry budget on a transient). Both carry audit
|
||||
# metadata; both emit a depth metric.
|
||||
|
||||
DLQ = "orders-dlq"
|
||||
POISON = "orders-poison"
|
||||
MAX_RETRY_TTL_SECONDS = 30 * 60 # 30 min retry window
|
||||
|
||||
def route_to_dlq(broker, message, reason, kind: str):
|
||||
target = POISON if kind == "poison" else DLQ
|
||||
broker.send(target, body=json.dumps({
|
||||
"original": message["body"],
|
||||
"reason": str(reason),
|
||||
"kind": kind, # poison vs dlq
|
||||
"deadLetteredAt": now_iso(),
|
||||
"redeliveryCount": message.get("attempt", 0),
|
||||
}))
|
||||
# P10: emit a metric so DLQ depth alerts fire. A DLQ that grows
|
||||
# with no alert is a silent correctness defect (P5/P10).
|
||||
metrics.increment(f"{kind}.depth", tags={"queue": "orders"})
|
||||
|
||||
|
||||
def consume_with_retry_budget(broker, dedup, process_order):
|
||||
# Combines TTL-with-backoff for transient failures (P6) with
|
||||
# poison-queue + DLQ + alert (P5/P10).
|
||||
for message in broker.receive():
|
||||
payload = json.loads(message["body"])
|
||||
if dedup.seen(payload["idempotencyKey"]):
|
||||
broker.ack(message); continue
|
||||
|
||||
first_attempt_ts = payload.get("firstAttemptTs", time.time())
|
||||
attempt = payload.get("attempt", 0)
|
||||
|
||||
try:
|
||||
process_order(payload)
|
||||
dedup.mark(payload["idempotencyKey"])
|
||||
broker.ack(message)
|
||||
|
||||
except TransientError as exc:
|
||||
# P6: if the retry window is exhausted, route to DLQ;
|
||||
# otherwise redeliver with exponential backoff.
|
||||
if time.time() - first_attempt_ts > MAX_RETRY_TTL_SECONDS:
|
||||
route_to_dlq(broker, message, exc, kind="dlq") # P5
|
||||
broker.ack(message)
|
||||
else:
|
||||
broker.nack(message, delay=backoff(attempt))
|
||||
```
|
||||
|
||||
## The Scenario
|
||||
|
||||
An orders queue delivers `order.created` events to the consumer at
|
||||
**at-least-once** (the declared semantic, P4). The broker redelivers
|
||||
on consumer crash or ack-timeout. Three things happen:
|
||||
|
||||
1. **Normal delivery** — the consumer dedups by `idempotencyKey`,
|
||||
processes, marks, acks.
|
||||
2. **Redelivery after a crash before ack** — the consumer crashed
|
||||
after `mark` but before `ack`. The broker redelivers; `seen()`
|
||||
returns true; the consumer acks without re-processing (P3).
|
||||
3. **Poison message** — a malformed JSON body. The consumer routes
|
||||
it to the poison queue immediately (no retry will fix a parse
|
||||
error), acks the origin, and emits a `poison.depth` metric. The
|
||||
operator is paged on poison-queue growth (P10).
|
||||
|
||||
A transient downstream failure (the payments API is briefly 503)
|
||||
retries with exponential backoff for 30 minutes (P6); if it exceeds
|
||||
the budget, the message routes to the DLQ with `reason`,
|
||||
`redeliveryCount`, and `deadLetteredAt` — auditable, drainable,
|
||||
observable (P5). The DLQ depth metric alerts the operator; the DLQ
|
||||
entry's audit metadata lets the operator replay after the bug is
|
||||
fixed (P5 reversibility).
|
||||
|
||||
## Principles Demonstrated
|
||||
|
||||
### Consumers are Idempotent (Messaging P3, C1)
|
||||
- The consumer dedups by idempotency key before processing. A
|
||||
redelivered message is a no-op, not a double-apply. The
|
||||
`process → mark → ack` order gives at-least-once + idempotent
|
||||
dedup; for a non-idempotent process, `process + mark` are one DB
|
||||
transaction (exactly-once via idempotency, P4).
|
||||
- See `domains/messaging/delivery-semantics.md` (idempotency-key
|
||||
dedup store) and `domains/messaging/first-principles.md` P3.
|
||||
|
||||
### Delivery Semantics are Explicit (Messaging P4, C1, C2)
|
||||
- The channel is declared **at-least-once + idempotent consumer** —
|
||||
the engineering practice that collapses to exactly-once under
|
||||
correct dedup (P3). The semantic is not emergent; it is the
|
||||
declared choice per channel. The tradeoff (dedup-store cost,
|
||||
transactional-process complexity) is conscious and documented.
|
||||
- See `domains/messaging/queues.md` (the three-semantics comparison
|
||||
table) and `domains/messaging/delivery-semantics.md` (exactly-
|
||||
once via idempotency).
|
||||
|
||||
### Dead-Letter Handling is Defined (Messaging P5, C1, C5)
|
||||
- Poison messages (unparseable) route immediately to the poison
|
||||
queue — no retry will fix them. Transient failures retry with
|
||||
backoff until the TTL, then route to the DLQ. Both carry audit
|
||||
metadata (`reason`, `redeliveryCount`, `deadLetteredAt`); both are
|
||||
drainable and observable. The DLQ is the reversibility mechanism
|
||||
— a dead-lettered message can be reprocessed after the bug is
|
||||
fixed.
|
||||
- See `domains/messaging/delivery-semantics.md` (dead-letter
|
||||
strategy comparison table, DLQ routing rule) and
|
||||
`domains/messaging/first-principles.md` P5.
|
||||
|
||||
### Messaging is Observable (Messaging P10, C7, C1)
|
||||
- DLQ depth and poison-queue depth are emitted as metrics and wired
|
||||
to alerts. A DLQ that grows silently is a correctness defect;
|
||||
the alert makes it visible. Silent backlog is a bug, not a
|
||||
feature — the operator is paged on growth, not on a customer
|
||||
report.
|
||||
- See `domains/messaging/delivery-semantics.md` (DLQ depth as an
|
||||
alert) and `domains/messaging/first-principles.md` P10.
|
||||
|
||||
## Cross-Domain Links
|
||||
|
||||
- `domains/messaging/delivery-semantics.md` — the idempotency-key
|
||||
dedup-store pattern and the dead-letter strategy comparison table
|
||||
exercised here (TTL-with-backoff + poison-queue + DLQ + alert).
|
||||
- `domains/messaging/queues.md` — the three-semantics comparison
|
||||
table; the ack/nack/redelivery model this consumer uses.
|
||||
- `domains/messaging/first-principles.md` — P3, P4, P5, P10 are the
|
||||
principles demonstrated.
|
||||
- `domains/concurrency/patterns` — the in-process retry/backoff
|
||||
analog (Pattern 6, Timeout on Every Block); messaging owns the
|
||||
broker-backed instance where redelivery comes across a network.
|
||||
- `domains/errors/patterns` — errors as data: a DLQ entry is the
|
||||
async-messaging instance of an error log (observable, auditable,
|
||||
drainable).
|
||||
- `domains/observability/metrics` — the generic SLI/SLO discipline
|
||||
the DLQ-depth alert builds on.
|
||||
- `review/anti-patterns.md` — the `messaging-unbounded-retry` and
|
||||
`messaging-shared-subscription` chaos anti-patterns are the
|
||||
inverse of this example's bounded retry + independent-consumer
|
||||
discipline.
|
||||
@@ -6,14 +6,14 @@
|
||||
|
||||
| Core Principle | Domains that derive from it | Count |
|
||||
|----------------|---------------------------|-------|
|
||||
| C1 Correctness | All 17 (v0.1: 11; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance) | Universal |
|
||||
| C2 Clarity | v0.1: uiux, api, data, testing, observability, errors, documentation, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance | 14 |
|
||||
| C3 Simplicity | v0.1: security, data, testing, performance, documentation, concurrency, devops; v0.2: infrastructure-as-code; v0.3: gitops-operators, i18n, compliance | 11 |
|
||||
| C4 Locality | v0.1: testing, concurrency; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, i18n | 6 |
|
||||
| C5 Reversibility | v0.1: api, data, uiux, concurrency, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance | 11 |
|
||||
| C6 Composability | v0.1: api, security, observability, errors, documentation, concurrency; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance | 12 |
|
||||
| C7 Observability | v0.1: api, data, testing, performance, observability, errors, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance | 13 |
|
||||
| C8 Economy | v0.1: security, testing, performance, observability, concurrency; v0.2: kubernetes; v0.3: gitops-operators, i18n, compliance | 9 |
|
||||
| C1 Correctness | All 19 (v0.1: 11; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: edge, messaging) | Universal |
|
||||
| C2 Clarity | v0.1: uiux, api, data, testing, observability, errors, documentation, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: messaging | 16 |
|
||||
| C3 Simplicity | v0.1: security, data, testing, performance, documentation, concurrency, devops; v0.2: infrastructure-as-code; v0.3: gitops-operators, i18n, compliance; v0.4: edge | 12 |
|
||||
| C4 Locality | v0.1: testing, concurrency; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, i18n; v0.4: edge, messaging | 8 |
|
||||
| C5 Reversibility | v0.1: api, data, uiux, concurrency, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: edge, messaging | 13 |
|
||||
| C6 Composability | v0.1: api, security, observability, errors, documentation, concurrency; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: edge, messaging | 14 |
|
||||
| C7 Observability | v0.1: api, data, testing, performance, observability, errors, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: edge, messaging | 15 |
|
||||
| C8 Economy | v0.1: security, testing, performance, observability, concurrency; v0.2: kubernetes; v0.3: gitops-operators, i18n, compliance; v0.4: edge, messaging | 11 |
|
||||
|
||||
## Interpretation
|
||||
|
||||
@@ -43,6 +43,8 @@
|
||||
| AI / ML | C1, C2, C5, C6, C7 | Reproducibility + lineage + serving observability |
|
||||
| i18n | C1, C2, C3, C4, C5, C6, C7, C8 | Locale + formatting + direction + reversibility; broadest derivation (8 C-rules) |
|
||||
| Compliance | C1, C2, C3, C5, C6, C7, C8 | Audit + policy-as-code + retention + posture |
|
||||
| Edge | C1, C3, C4, C5, C6, C7, C8 | Proximity + offline + constraint; broad derivation (7 C-rules) |
|
||||
| Messaging | C1, C2, C4, C5, C6, C7, C8 | Cross-process delivery + ordering + idempotency; broad derivation (7 C-rules) |
|
||||
|
||||
## v0.2 Domain Coverage (per IDEATE-03 schema)
|
||||
|
||||
@@ -60,6 +62,39 @@
|
||||
| i18n | 10 | 4 (locale-resources, formatting, rtl-bidi, testing-i18n) | ✓ | complete |
|
||||
| Compliance | 10 | 4 (audit-logs, data-retention, policy-as-code, evidence) | ✓ | complete |
|
||||
|
||||
## v0.4 Domain Coverage (per IDEATE-03 schema)
|
||||
|
||||
| Domain | P-count | Derived-doc-count | Manifest-listed | Status |
|
||||
|--------|---------|-------------------|-----------------|--------|
|
||||
| Edge | 10 | 4 (cdn, offline-first, iot, sync) | ✓ | complete |
|
||||
| Messaging | 10 | 4 (queues, pubsub, streams, delivery-semantics) | ✓ | complete |
|
||||
|
||||
## Languages Coverage (v0.4, per D-066)
|
||||
|
||||
> Language-derived docs apply existing domain P-rules. They introduce
|
||||
> no new matrix rows (D-063, D-066). The sub-table is the verifiable
|
||||
> aggregate; inline section-headers are the per-doc detail. Every
|
||||
> derived doc traces to ≥1 domain P-rule (D-066, no orphans).
|
||||
|
||||
| Language | Derived Doc | Traced Domain P-rules | Traced Core C-rules |
|
||||
|----------|-------------|------------------------|---------------------|
|
||||
| TypeScript | ts-types.md | Data P7, API P1, Errors P1 | C1, C5, C6 |
|
||||
| TypeScript | ts-tooling.md | DevOps P2, DevOps P1, Documentation P1, DevOps P9 | C1, C2, C6, C8 |
|
||||
| TypeScript | ts-async.md | Concurrency P7, Concurrency P8, Concurrency P9, Errors P5, Errors P1 | C1, C2, C5 |
|
||||
| TypeScript | ts-testing.md | Testing P1, Testing P2, Testing P3, Testing P7, Testing P9, Data P7 | C1, C2 |
|
||||
| Python | py-types.md | Data P7, API P1, Errors P1 | C1, C2, C6 |
|
||||
| Python | py-tooling.md | DevOps P2, DevOps P1, Documentation P1, DevOps P9 | C1, C2, C3, C8 |
|
||||
| Python | py-async.md | Concurrency P1, Concurrency P7, Concurrency P8, Concurrency P9, Errors P5, Errors P1 | C1, C2, C5, C6 |
|
||||
| Python | py-testing.md | Testing P1, Testing P2, Testing P3, Testing P7, Testing P9, Concurrency P10 | C1, C2 |
|
||||
| Go | go-types.md | Data P7, API P1, Errors P1, Errors P3 | C1, C2, C6 |
|
||||
| Go | go-tooling.md | DevOps P2, DevOps P1, Concurrency P6, Documentation P1, DevOps P9 | C1, C2, C3, C7, C8 |
|
||||
| Go | go-concurrency.md | Concurrency P1, Concurrency P3, Concurrency P5, Concurrency P6, Concurrency P7, Concurrency P8, Concurrency P9 | C1, C3, C4, C5, C6, C8 |
|
||||
| Go | go-testing.md | Testing P1, Testing P2, Testing P3, Testing P7, Testing P9, Concurrency P6, Concurrency P10, API P1 | C1, C2 |
|
||||
| Rust | rs-ownership.md | Concurrency P1, Concurrency P3, Concurrency P5, Data P7 | C1, C3, C4 |
|
||||
| Rust | rs-tooling.md | DevOps P2, DevOps P1, Documentation P1, DevOps P9 | C1, C2, C3, C5, C8 |
|
||||
| Rust | rs-async.md | Concurrency P5, Concurrency P7, Concurrency P8, Concurrency P9 | C1, C3, C5, C6, C8 |
|
||||
| Rust | rs-testing.md | Testing P1, Testing P2, Testing P3, Testing P7, Testing P9, Concurrency P10, Documentation P1 | C1, C2 |
|
||||
|
||||
## Gaps and Notes
|
||||
|
||||
- No domain derives from only one C-rule. The minimum is 4 (UI/UX: C1, C2, C3, C5, C7 — actually 5). Every domain is multi-rooted.
|
||||
@@ -68,4 +103,6 @@
|
||||
- **UI/UX** and **API** are the most user-facing; they emphasize C2 (Clarity) heavily.
|
||||
- **Security** is the only domain with explicit non-tradeable declarations; this promotes 8 of its rules to C1-equivalent per `core/conflict-resolution.md` §6.
|
||||
- **v0.2 expansion:** C4 (Locality) grew from 2 to 4 domains (added infrastructure-as-code state locality, kubernetes namespace blast-radius). C6 (Composability) grew from 6 to 8. The two new domains are broad-derivation domains (7 C-rules each), consistent with Concurrency's breadth.
|
||||
- **v0.3 expansion:** C3 (Simplicity) grew from 7 to 11 (added gitops-operators declarative simplicity, i18n flexible layout, compliance structural redaction). C4 (Locality) grew from 4 to 6 (added gitops-operators pull-credential locality, i18n resource/text-direction locality). C5 (Reversibility) grew from 7 to 11 (added all four v0.3 domains — gitops history, ai-ml reproducibility, i18n translation versioning, compliance append-only/retention). C6 (Composability) grew from 8 to 12. C7 (Observability) grew from 9 to 13 (added all four v0.3 domains — reconciliation, drift detection, format correctness, posture). C2 (Clarity) grew from 10 to 14. The v0.3 expansion broadens every non-universal C-rule's coverage, confirming the four new domains are cross-cutting and well-rooted.
|
||||
- **v0.3 expansion:** C3 (Simplicity) grew from 7 to 11 (added gitops-operators declarative simplicity, i18n flexible layout, compliance structural redaction). C4 (Locality) grew from 4 to 6 (added gitops-operators pull-credential locality, i18n resource/text-direction locality). C5 (Reversibility) grew from 7 to 11 (added all four v0.3 domains — gitops history, ai-ml reproducibility, i18n translation versioning, compliance append-only/retention). C6 (Composability) grew from 8 to 12. C7 (Observability) grew from 9 to 13 (added all four v0.3 domains — reconciliation, drift detection, format correctness, posture). C2 (Clarity) grew from 10 to 14. The v0.3 expansion broadens every non-universal C-rule's coverage, confirming the four new domains are cross-cutting and well-rooted.
|
||||
- **v0.4 expansion:** C2 (Clarity) grew from 14 to 16 (added messaging P1/P2/P4 — contract clarity). C4 (Locality) grew from 6 to 8 (added edge P1/P8 geographic locality, messaging P7 partition locality). C5 (Reversibility) grew from 11 to 13 (added edge P2/P4/P7/P10 reconciliation + degradation, messaging P5/P8/P9 replay + evolution). C6 (Composability) grew from 12 to 14 (added edge P8 fleet composition, messaging P7/P9 partition + version composition). C7 (Observability) grew from 13 to 15 (added edge P10 partition-survivable telemetry, messaging P8/P10 durable-log + lag). C8 (Economy) grew from 9 to 11 (added edge P3/P9 constrained resources + trust, messaging P6 bounded backpressure). C3 (Simplicity) grew from 11 to 12 (added edge P6 explicit invalidation simplicity). Both v0.4 domains are broad-derivation (7 C-rules each), consistent with the v0.2/v0.3 precedent.
|
||||
- **Languages Coverage (v0.4, D-066):** The 16 language-derived docs (4 languages × 4 docs) apply existing domain P-rules; they introduce no new matrix rows (D-063, D-066). The sub-table above is the verifiable aggregate — every derived doc traces to ≥1 domain P-rule (no orphans). Languages are an application lens, not a principle source.
|
||||
@@ -265,8 +265,39 @@ C5=Reversibility · C6=Composability · C7=Observability · C8=Economy
|
||||
| P9 Secrets and Sensitive Data are Redacted in Audit | C1, C3 | Correctness via security; simplicity of structural redaction |
|
||||
| P10 Compliance Posture is Observable | C7, C1 | Observability of compliance; correctness of posture |
|
||||
|
||||
## Coverage Summary (post-v0.3)
|
||||
## Edge
|
||||
|
||||
- 17 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes; 4 v0.3: gitops-operators, ai-ml, i18n, compliance)
|
||||
- 170 domain principles total (110 v0.1 + 20 v0.2 + 40 v0.3)
|
||||
- Every domain P-rule traces to ≥1 core C-rule (C1–C8). No orphans.
|
||||
| Edge Principle | Core | Why |
|
||||
|-------------------------------------------------------|-------|--------------------------------------------------|
|
||||
| P1 Proximity is the Design Driver | C4, C1 | Locality of compute near user/data; correctness via latency |
|
||||
| P2 Offline is a First-Class State | C1, C5 | Correctness under partition; reversibility of reconciliation |
|
||||
| P3 Resources are Constrained and Declared | C8, C1 | Economy of constrained nodes; correctness of declared bounds |
|
||||
| P4 Sync Conflicts are Bounded, Not Infinite | C1, C5 | Correctness of convergence; reversibility of divergent state |
|
||||
| P5 Edge Operations are Idempotent | C1 | Correctness under retry |
|
||||
| P6 Cache Invalidation is Explicit | C1, C3 | Correctness of cached state; simplicity of defined invalidation |
|
||||
| P7 Partial Degradation is Engineered | C1, C5 | Correctness of degraded modes; reversibility of recovery |
|
||||
| P8 Geographic Distribution is a First-Class Constraint | C4, C6 | Locality of placement; composability of the fleet |
|
||||
| P9 Identity is Constrained at the Edge | C1, C8 | Correctness via security; economy of trust |
|
||||
| P10 Edge Observability Survives Partition | C7, C5 | Observability of the fleet; reversibility of buffered telemetry |
|
||||
|
||||
## Messaging
|
||||
|
||||
| Messaging Principle | Core | Why |
|
||||
|--------------------------------------------------|-------|--------------------------------------------------|
|
||||
| P1 Messages are Contracts | C1, C2 | Correctness of the exchange; clarity of the schema boundary |
|
||||
| P2 Ordering is a Property, Not an Assumption | C1, C2 | Correctness of order; clarity of the guarantee |
|
||||
| P3 Consumers are Idempotent | C1 | Correctness under redelivery |
|
||||
| P4 Delivery Semantics are Explicit | C1, C2 | Correctness of the chosen semantic; clarity of the tradeoff |
|
||||
| P5 Dead-Letter Handling is Defined | C1, C5 | Correctness of poison-message routing; reversibility of reprocessing |
|
||||
| P6 Backpressure is Bounded | C1, C8 | Correctness of bounded backlog; economy of broker memory |
|
||||
| P7 Partitioning is Intentional | C4, C6 | Locality of order; composability of parallelism |
|
||||
| P8 Replay and Retention are Configured | C5, C7 | Reversibility of replay; observability of the durable log |
|
||||
| P9 Schemas Evolve Compatibly | C5, C6 | Reversibility of schema changes; composability of versions |
|
||||
| P10 Messaging is Observable | C7, C1 | Observability of lag/DLQ; correctness of backlog detection |
|
||||
|
||||
## Coverage Summary (post-v0.4)
|
||||
|
||||
- 19 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes; 4 v0.3: gitops-operators, ai-ml, i18n, compliance; 2 v0.4: edge, messaging)
|
||||
- 190 domain principles total (110 v0.1 + 20 v0.2 + 40 v0.3 + 20 v0.4)
|
||||
- Every domain P-rule traces to ≥1 core C-rule (C1–C8). No orphans.
|
||||
- Language-derived docs (16) apply existing domain P-rules; they introduce no new matrix rows (D-063, D-066). See `matrix/domain-coverage.md` `## Languages Coverage` sub-table.
|
||||
@@ -197,6 +197,37 @@ If the task touches a domain, run that domain's checklist:
|
||||
- [ ] Audit logs do not leak secrets; redaction is structural, not opportunistic (P9)
|
||||
- [ ] System reports its own compliance state (drift from policy, open violations, retention status) (P10)
|
||||
|
||||
### If Edge (see `domains/edge/`)
|
||||
- [ ] Compute is placed near the user/data source; latency is treated as a correctness constraint, not a perf preference (P1)
|
||||
- [ ] The system continues to operate offline; partition is the norm, not the exception; reconciliation happens on reconnect (P2)
|
||||
- [ ] Edge-node resource constraints (CPU/memory/power/bandwidth) are declared per node class, not assumed infinite (P3)
|
||||
- [ ] Sync conflicts converge; no oscillation or infinite sync loops (P4)
|
||||
- [ ] Sync, cache-fill, and device commands are idempotent — retries are safe (P5)
|
||||
- [ ] Edge caches have an explicit TTL or invalidation strategy; no TTL-less caches under partition (P6)
|
||||
- [ ] Partial degradation is a designed state with a defined contract, not a crash (P7)
|
||||
- [ ] Routing, fan-out, and data placement are location-aware decisions, not accidents of deployment (P8)
|
||||
- [ ] Edge-device credentials are scoped and per-device; no edge node is a cluster-admin-equivalent (P9)
|
||||
- [ ] Telemetry is local-first: buffered on-node and forwarded on reconnect; partition does not blind the operator (P10)
|
||||
|
||||
### If Messaging (see `domains/messaging/`)
|
||||
- [ ] Messages have an explicit, versioned schema; producer and consumer agree on shape before exchange (P1)
|
||||
- [ ] Ordering guarantees (per-partition, global, none) are explicit and documented; "FIFO" is backed by the broker contract (P2)
|
||||
- [ ] Consumers are idempotent — redelivery is deduped via idempotency keys or deterministic processing (P3)
|
||||
- [ ] Delivery semantics (at-least-once/at-most-once/exactly-once) are a declared choice per channel (P4)
|
||||
- [ ] Poison messages route to a dead-letter queue; the DLQ is observable and drainable (P5)
|
||||
- [ ] Backpressure is bounded — consumer lag visible, max-unacked bounded, retry budget capped (P6)
|
||||
- [ ] Partition key choice is a documented design decision (ordering vs parallelism vs hotspots) (P7)
|
||||
- [ ] Retention windows and replay-from-offset are explicit; the broker is a durable log, not a pipe (P8)
|
||||
- [ ] Schema changes are backward/forward-compatible; breaking changes are versioned migrations, not silent shape edits (P9)
|
||||
- [ ] Consumer lag, DLQ depth, throughput, and consumer-group health are observed; silent backlog is a bug (P10)
|
||||
|
||||
### If Language-Derived Docs (see `languages/`)
|
||||
- [ ] Scope check: no new P-rules introduced — every section traces to an existing domain P-rule (D-063, D-066)
|
||||
- [ ] Every section header names ≥1 traced domain P-rule AND the core C-rule(s) inline (e.g., `## Nominal vs Structural Typing (C1 Correctness, Data P7 Type Fidelity, API P1 Contract Fidelity)`)
|
||||
- [ ] Fenced code examples are in-language and illustrative only — no standalone `.ts`/`.py`/`.go`/`.rs` runtime artifacts (D-020)
|
||||
- [ ] The first-principles stub retains its section structure — no P1–P10 numbering added to languages (D-063)
|
||||
- [ ] Cross-links to traced domain docs are present (≥1 outbound per derived doc, ATELIER-114)
|
||||
|
||||
## Final Gate
|
||||
|
||||
- [ ] Have I read the relevant domain's first-principles?
|
||||
|
||||
@@ -188,6 +188,72 @@ The following standalone file types are forbidden under `examples/` and elsewher
|
||||
| Signed manifests as standalone files (`.sig`, `.att`, `.intoto.jsonl`) | fenced code in `examples/*.md` | Runtime attestation artifact; violates docs-only contract |
|
||||
| Standalone `.yaml` / `.tf` / `.sh` | fenced code in `examples/*.md` | (Carried forward from v0.2) Runtime deployable artifact |
|
||||
|
||||
## v0.4 Chaos Anti-Patterns (from IDEATE-36, IDEATE-37, D-068, ATELIER-110)
|
||||
|
||||
These are named, cross-cutting violations specific to the v0.4 domains. Single-breach per D-068. Reject on sight.
|
||||
|
||||
| Anti-Pattern | Breaches | Why |
|
||||
|--------------|----------|-----|
|
||||
| Edge sync conflict loop (two nodes oscillate divergent state forever; no convergence) | edge P4 Sync Conflicts are Bounded, Not Infinite; C1, C5 | Infinite oscillation is a correctness failure, not eventual consistency; the sync is a livelock |
|
||||
| Edge TTL-less cache (edge cache with no TTL and no explicit invalidation; stale forever under partition) | edge P6 Cache Invalidation is Explicit; C1, C3 | Stale-forever under partition is a silent correctness defect |
|
||||
| Edge blocking call on constrained device (a synchronous blocking I/O call on a low-power IoT device with no timeout) | edge P3 Resources are Constrained, P5 (retry safety); C8, C1 | Blocks the constrained node; no timeout = hang; retry is unsafe without idempotency |
|
||||
| Messaging shared subscription (two consumers share one subscription; each message processed by an arbitrary consumer, breaking per-consumer ordering and idempotency) | messaging P2 Ordering, P3 Idempotency; C1 | Shared subscription breaks ordering and dedup; the `messaging-shared-subscription` bad example lives here |
|
||||
| Messaging blocking consumer (a consumer blocks on a slow downstream call with no timeout; the broker re-delivers to the same stuck consumer) | messaging P6 Backpressure is Bounded; C1, C8 | Blocks the partition; lag grows; no backpressure escape |
|
||||
| Messaging unbounded retry / no DLQ (a poison message is retried forever with no dead-letter queue; the consumer never makes progress) | messaging P5 Dead-Letter Handling is Defined; C1, C5 | Infinite retry is a livelock; poison messages must DLQ |
|
||||
|
||||
### v0.4 Deployable Artifact Types (IDEATE-36, D-020)
|
||||
|
||||
The following standalone file types are forbidden under `languages/` and elsewhere in the framework (carried forward from v0.2/v0.3 and extended for language-derived docs). All examples and derived-doc code are `.md` files with fenced code only.
|
||||
|
||||
| Forbidden standalone artifact | Belongs in | Why |
|
||||
|-------------------------------|-----------|-----|
|
||||
| Standalone `.ts` file | fenced code in `languages/*.md` (or `examples/*.md`) | Runtime TypeScript artifact; violates docs-only contract (v0.4 extension) |
|
||||
| Standalone `.py` file | fenced code in `languages/*.md` (or `examples/*.md`) | Runtime Python artifact; violates docs-only contract (v0.4 extension) |
|
||||
| Standalone `.go` file | fenced code in `languages/*.md` (or `examples/*.md`) | Runtime Go artifact; violates docs-only contract (v0.4 extension) |
|
||||
| Standalone `.rs` file | fenced code in `languages/*.md` (or `examples/*.md`) | Runtime Rust artifact; violates docs-only contract (v0.4 extension) |
|
||||
| Standalone `.yaml` / `.tf` / `.sh` | fenced code in `examples/*.md` | (Carried forward from v0.2/v0.3) Runtime deployable artifact |
|
||||
|
||||
### v0.4 Language-Derived-Doc Anti-Patterns
|
||||
|
||||
| Anti-Pattern | Breaches | Why |
|
||||
|--------------|----------|-----|
|
||||
| Language-derived doc introducing a new P-rule (e.g., "TS P1", "Python P2") | D-063, ARCHITECTURE.md hierarchy, matrix row-count invariant | Languages apply, not derive; breaks the hierarchy (`core > domains > languages`) and the 190-row invariant |
|
||||
| Language-derived doc with no domain P-rule trace (orphan section — header names no domain P-rule) | D-066, matrix completeness | No trace = no traceability; the doc is not connected to the framework |
|
||||
| Language-derived doc with runtime artifact (standalone `.ts`/`.py`/`.go`/`.rs` file) | D-020, PROJECT.md no-runtime-code | Violates the docs-only contract; must be fenced code in `.md` |
|
||||
| Language first-principles stub gaining P1–P10 numbering | D-063 | Languages are not domains; no P-rules to number; breaks the apply-don't-derive scope |
|
||||
|
||||
## v0.4 Domain-Specific Anti-Patterns
|
||||
|
||||
### Edge
|
||||
|
||||
| Anti-Pattern | Breaches | Why |
|
||||
|--------------|----------|-----|
|
||||
| Central-region-only deployment for a latency-bound workload | P1 Proximity is the Design Driver | Violates the proximity constraint; latency is a correctness defect |
|
||||
| App that crashes on disconnect (no offline state) | P2 Offline is a First-Class State | Partition is the norm; crash-on-disconnect is unengineered |
|
||||
| Undeclared edge-node resource budget (assumes infinite CPU/memory) | P3 Resources are Constrained and Declared | Unbounded = OOM on constrained nodes |
|
||||
| Sync loop that oscillates forever (CRDT without merge-semantics, LWW without monotonic clock) | P4 Sync Conflicts are Bounded | Livelock; convergence is never reached |
|
||||
| Non-idempotent edge write (cache-fill or device command retried with side effects) | P5 Edge Operations are Idempotent | Retry doubles the side effect |
|
||||
| TTL-less edge cache under partition | P6 Cache Invalidation is Explicit | Stale-forever; silent staleness |
|
||||
| Crash-on-node-failure (no partial-degradation contract) | P7 Partial Degradation is Engineered | Whole-system crash on one node's failure |
|
||||
| Random geographic placement (no location-aware routing) | P8 Geographic Distribution is a First-Class Constraint | Latency and data-residency uncontrolled |
|
||||
| Shared edge-device credential (one key for the whole fleet) | P9 Identity is Constrained at the Edge | One compromise = fleet compromise |
|
||||
| Fire-and-forget telemetry (no on-node buffer; data lost on partition) | P10 Edge Observability Survives Partition | Partition blinds the operator |
|
||||
|
||||
### Messaging
|
||||
|
||||
| Anti-Pattern | Breaches | Why |
|
||||
|--------------|----------|-----|
|
||||
| Schemaless message (no versioned contract; consumer parses by guess) | P1 Messages are Contracts | No boundary; consumer breaks silently on shape change |
|
||||
| "It's FIFO" with no documented partition contract | P2 Ordering is a Property, Not an Assumption | Undocumented ordering = assumed ordering = wrong ordering |
|
||||
| Non-idempotent consumer under at-least-once delivery | P3 Consumers are Idempotent | Redelivery doubles the effect |
|
||||
| Unstated delivery semantic (at-least-once vs exactly-once guessed) | P4 Delivery Semantics are Explicit | The tradeoff is made blindly |
|
||||
| No dead-letter queue (poison message retried forever or dropped) | P5 Dead-Letter Handling is Defined | Livelock or silent loss |
|
||||
| Unbounded retry budget (no cap; slow consumer stalls the partition) | P6 Backpressure is Bounded | Lag grows without bound |
|
||||
| Default partition key (no rationale; hotspot or wrong-order) | P7 Partitioning is Intentional | Hotspot or ordering violation |
|
||||
| Ephemeral broker (no retention; no replay) | P8 Replay and Retention are Configured | Not a durable log; replay impossible |
|
||||
| Silent schema change (producer breaks consumers with no version bump) | P9 Schemas Evolve Compatibly | Breaking change without migration |
|
||||
| Silent backlog (no lag metric; consumer falls behind invisibly) | P10 Messaging is Observable | Cannot fix what you cannot see |
|
||||
|
||||
## v0.3 Domain-Specific Anti-Patterns
|
||||
|
||||
### GitOps + Operators
|
||||
|
||||
@@ -129,6 +129,39 @@ Run the relevant domain section from `agent-checklist.md` (UI/UX, API, Security,
|
||||
- [ ] Do audit logs avoid leaking secrets (redaction is structural, not opportunistic)?
|
||||
- [ ] Does the system report its own compliance state (drift from policy, open violations, retention status)?
|
||||
|
||||
### If Edge
|
||||
- [ ] Scope check: is this the proximity/location/constraint angle, NOT generic perf or in-process concurrency? (D-061 — reject generic-performance or in-process-concurrency content as out-of-scope)
|
||||
- [ ] Is compute placed near the user/data source, with latency treated as a correctness constraint (not a perf preference)? (P1)
|
||||
- [ ] Does the system continue to operate offline; is partition the norm, not the exception? (P2)
|
||||
- [ ] Are edge-node resource constraints (CPU/memory/power/bandwidth) declared per node class, not assumed infinite? (P3)
|
||||
- [ ] Do sync conflicts converge; is there no oscillation or infinite sync loop? (P4)
|
||||
- [ ] Are sync, cache-fill, and device commands idempotent (retries safe)? (P5)
|
||||
- [ ] Do edge caches have an explicit TTL or invalidation strategy (no TTL-less caches under partition)? (P6)
|
||||
- [ ] Is partial degradation a designed state with a defined contract (not a crash)? (P7)
|
||||
- [ ] Are routing, fan-out, and data placement location-aware decisions? (P8)
|
||||
- [ ] Are edge-device credentials scoped and per-device (no edge cluster-admin)? (P9)
|
||||
- [ ] Is telemetry local-first (buffered on-node, forwarded on reconnect; partition does not blind the operator)? (P10)
|
||||
|
||||
### If Messaging
|
||||
- [ ] Scope check: is this cross-process/network-failure-model, NOT in-process concurrency? (D-062 — reject in-process-concurrency content as out-of-scope)
|
||||
- [ ] Do messages have an explicit, versioned schema (producer and consumer agree on shape)? (P1)
|
||||
- [ ] Are ordering guarantees (per-partition, global, none) explicit and documented? (P2)
|
||||
- [ ] Are consumers idempotent (redelivery deduped via idempotency keys or deterministic processing)? (P3)
|
||||
- [ ] Are delivery semantics (at-least-once/at-most-once/exactly-once) a declared choice per channel? (P4)
|
||||
- [ ] Do poison messages route to a dead-letter queue (DLQ observable and drainable)? (P5)
|
||||
- [ ] Is backpressure bounded (consumer lag visible, max-unacked bounded, retry budget capped)? (P6)
|
||||
- [ ] Is partition key choice a documented design decision (ordering vs parallelism vs hotspots)? (P7)
|
||||
- [ ] Are retention windows and replay-from-offset explicit (durable log, not pipe)? (P8)
|
||||
- [ ] Are schema changes backward/forward-compatible (breaking changes are versioned migrations)? (P9)
|
||||
- [ ] Are consumer lag, DLQ depth, throughput, and consumer-group health observed (silent backlog is a bug)? (P10)
|
||||
|
||||
### If Language-Derived Docs
|
||||
- [ ] Scope check: apply, don't derive — no new P-rules, no new matrix rows (D-063, D-066 — reject any "TS P1"/"Python P2" etc. new-P-rule content)
|
||||
- [ ] Does every section header name ≥1 traced domain P-rule AND the core C-rule(s) inline?
|
||||
- [ ] Are fenced code examples in-language and illustrative only (no standalone `.ts`/`.py`/`.go`/`.rs` runtime artifacts)? (D-020)
|
||||
- [ ] Does the first-principles stub retain its section structure (no P1–P10 numbering added to languages)? (D-063)
|
||||
- [ ] Are cross-links to traced domain docs present (≥1 outbound per derived doc)? (ATELIER-114)
|
||||
|
||||
## Review Etiquette
|
||||
|
||||
- **Comment, don't command.** "This could be X" not "Change this to X."
|
||||
|
||||
Reference in New Issue
Block a user