ADR-204 · ILLUSTRATIVE SPECIMEN STATUS: ILLUSTRATIVE PROPOSAL · REGION: ap-southeast-1

Swiss Atelier v1.1.0 · Living design system

Distributed State & Read-Path Engineering

01. A Proposed Snapshot Ring Read Path

This fictional storage-engine example explores a ring-buffer read path with quorum fallback. The proposed design targets replication lag below 1,800ms and expires a lease after 2,000ms. Its numbers illustrate presentation; no workload measurements or production verification are supplied.

Metric provenance: synthetic design values, not observations; period, sample size, and uncertainty are unspecified. p99 is a read-latency percentile in ms; hit ratio is hits/all reads; contention is blocked reads/all reads. The 87% change compares synthetic 1.84ms with 14.2ms. Only hit ratio uses a bar, with width equal to that percentage on a 0–100% scale.

Synthetic p99 Latency -87%

1.84 ms

Synthetic comparator: 14.2ms

Synthetic Hit Ratio SYNTHETIC

94.6%

Hits / reads · linear scale 0–100%

Example Lease Limit BOUNDED

2,000 ms

Lease age, not replication lag

Synthetic Contention ZERO-LOCK

0.00%

Synthetic blocked reads / all reads

Module 02 · Editorial Readability

02. Long-Form Technical Prose, Margin Sidenotes & Callouts

Literata 440 · 65ch Measure

In this illustrative design, engineers compare a local snapshot read with a quorum fallback. The intended reader is a storage engineer deciding which read path is eligible. The example does not establish a general latency or consistency guarantee for distributed storage.

The example proposes read-your-own-writes monotonicity paired with a deterministic upper bound on staleness^[S1]. If a client mutates a permission graph in Singapore, any subsequent read carrying a session vector greater than or equal to hlc_epoch: 109482910 must satisfy that session watermark before returning a local result, whereas unauthenticated public reads may attempt a read from an in-memory ring buffer within a 2,000ms lease window.

Why This Example Separates Reads from Updates

The synthetic comparison assumes a sharded LRU protected by a lock. Its illustrative contention values are design inputs, not measurements^[S2]. By replacing mutable linked lists with a pre-allocated ring of immutable snapshot slots, readers acquire data via a single Acquire atomic load in the proposed local read path; correctness and concurrency testing are outside this presentation example.

[S1] SIDENOTE · HLC EPOCHS

Here HLC means hybrid logical clock. The example carries a session watermark; a concrete clock encoding and clock-skew guarantees are unspecified.

[S2] SYNTHETIC BENCHMARK EXAMPLE

Synthetic L3 cache-miss fractions: 18.4% for the comparator and 1.9% for the proposed path at an assumed 100k requests/s. Source: fictional specimen inputs; period, sample size, and uncertainty unknown.

Semantic Callout & Guardrail Taxonomy

Focal Rule · Lease Expiration

If an edge node fails to renew its WAL heartbeat within 2,000ms, it must immediately evict local ring slots and route reads to the regional quorum.

Proposed Rule · Session Watermark

A client presenting client_hlc > slot_hlc bypasses the ring buffer and triggers an asynchronous fast-forward barrier.

Operational Note · Memory Budget

The example configuration assigns 512 MB per worker to a 64-slot ring. Allocation overhead and fragmentation have not been measured.

ILLUSTRATIVE RECOMMENDATION Wait-Free Read

Load the active slot index via Ordering::Acquire and clone the immutable Arc<SnapshotPage> reference before deserializing fields.

ANTI-PATTERN · AVOID Mutex Serialization

Never hold a write guard across network I/O or WAL decompression; a single slow packet will stall all 64 reader threads on the socket.

Module 03 · 4px Grid & Orthogonal Routing

03. Editorial SVG Diagram Suite

Choose topology for structure, sequence for ordered messages, state for legal transitions, and a table for exact comparison. These are illustrative views, not production evidence. Each scrollable diagram has an independent text equivalent. Read the diagram method for scope, notation, omissions, and reader checks.

FIG 3.1 — MULTI-TIER READ-THROUGH CACHE & QUORUM STORAGE TOPOLOGY 4 ENTITIES · CONCEPTUAL PROPOSAL

Illustrative proposal, conceptual scope. Four boxes are the Edge SDK session, epoch-classifier router, snapshot ring buffer, and regional quorum/WAL ledger.

SDK → router: sends a read request with its session HLC token over the illustrated mTLS ingress.
Router → ring: attempts the focal read when the lease and session watermark permit it.
Router → quorum: dashed cold-path fallback when the ring cannot satisfy the read.
Quorum/WAL → ring: streams updates into snapshot slots.

Orange identifies the focal ring path; teal identifies the proposed ingress/update roles, with no verification claim. Solid arrows show requests or replication; the dashed arrow is fallback. Box size fits labels; the well is decorative, not a trust or deployment boundary. Responses, replication failure, and internals are omitted. Takeaway: the router chooses the ring or quorum; this is not a deployed-system inventory.

Module 04 · Semantic Syntax Highlighting

04. Syntax-Highlighted Code & Invariant Callouts

Illustrative parameters, not measured guarantees. Lease age means elapsed time since renewal: age >1,500ms starts soft hedging; age >2,000ms expires the lease (at exactly 2,000ms it has not expired). Replication lag is a separate quantity: the SQL acceptance target is <1,800ms, not a lease duration. The Rust excerpt checks lease validity and the session watermark; it does not implement the complete lag/hedge policy. These fragments are incomplete teaching examples, not a tested storage engine.

              
              crates/edge-cache/src/ring_buffer.rs
            
Rust 1.82 · Wait-Free Atomic Path
01// Acquire the latest committed snapshot slot without locking the WAL writer thread
02#[inline(always)]
03pub fn read_monotonic(&self, min_hlc: HlcTimestamp) -> Result<Arc<SnapshotPage>, ReadFallback> {
04    let head_idx = self.active_epoch.load(Ordering::Acquire) & RING_MASK; // FOCAL: Zero-lock atomic load
05    let slot = unsafe { self.slots.get_unchecked(head_idx) }.load();
06    if slot.lease_valid_until() >= Instant::now() && slot.hlc_watermark >= min_hlc { // Proposed lease and session checks
07        return Ok(Arc::clone(&slot.page));
08    }
09    Err(ReadFallback::RouteToQuorum { region: "ap-southeast-1", observed_hlc: slot.hlc_watermark })
10}

Syntax Token Palette:

keyword (#B91C1C) Type/Struct (#0F766E) function() (#1D4ED8) CONSTANT/42 (#B45309) "string" (#15803D) #[attribute] (#6D28D9) // comment (--ink-code #57534E)

Module 05 · Decision Analysis

05. Quantitative Trade-Off Matrix & Decision Log

Synthetic read-strategy comparison. Latencies are ms; RPS means requests/s. Source: fictional specimen inputs. Observation period, sample sizes, and uncertainty unknown; statuses describe the illustrative proposal.
Architecture Strategy	p50 / p99 Latency	Max Throughput	Consistency Guarantee	Status
Atomic Ring Buffer + HLC Lease	0.4 ms / 1.84 ms	450,000 RPS	Session watermark + lease check	ADOPTED PRIMARY
Client SDK Immutable Memoization	0.1 ms / 0.35 ms	Local Memory	Content-Addressed Static Assets	ADOPTED L0
Cross-Region Raft Quorum Read	6.8 ms / 14.20 ms	42,000 RPS	Strict Linearizable	REJECTED (LATENCY)
Sharded RwLock In-Memory LRU	1.1 ms / 9.60 ms	115,000 RPS	TTL Eventual (Unbounded Skew)	REJECTED (LOCK STALL)

Expandable Decision Record Clauses (Click to toggle)

This illustrative proposal chooses a 2,000ms lease age limit independently from its <1,800ms replication-lag target. No session telemetry, observation period, or evidence of perceptual acceptability is supplied. The synthetic 94.6% hit fraction is an input for demonstrating a component, not evidence for this limit.

Module 06 · Spatial & Temporal Models

06. Rollout Timeline & 2x2 Trade-Off Quadrant

Illustrative 3-Stage Cutover Proposal

01

Shadow Ring Verification PROPOSED CHECK

Mirror 10% of production reads to the L1 ring buffer asynchronously and log any HLC watermark divergence without serving ring responses.

02

Canary POP Cutover (sin-01, nrt-01) PROPOSED CANARY

Enable wait-free L1 serving for read-heavy endpoints with automatic fallback on lease_age > 2000ms.

03

Global Fleet Rollout (12 POPs) ILLUSTRATIVE NEXT STAGE

Decommission legacy sharded RwLock LRU instances and evaluate any change in edge compute use; savings are unknown.

Qualitative 2x2 Approach Map

Synthetic qualitative map: client cache is placed in faster/local serving, sharded LRU in slower/local serving, ring with quorum fallback in faster/coordinated serving, and Raft quorum in slower/coordinated serving. Points identify approaches; orange marks the focal proposal and teal the client-cache role, not verification. Positions are categorical illustration; distances and speed are unmeasured, with no time scale or ranked consistency guarantees. Frame and dashed quadrant lines organize categories and assert no security boundary. Takeaway: compare exact values and consistency categories in the table above; this map supplies no further quantitative evidence.

Module 07 · Optical Scale

07. Typography & Hierarchy Scale Specimen

Fraunces + Literata 440 + Geist

Display H1

Fraunces · 500 · 40px

Architectural Clarity Through Disciplined Hierarchy

Section H2

Fraunces · 500 · 28px

1. Bounded Staleness & Monotonic Read Guarantees

Paragraph Body

Literata · 440 · 15.7px (0.98rem)

Literata at weight 440, 0.98rem, and line-height 1.68 is the Swiss prose default. Adapt size and measure for the audience and surface, and verify loaded and fallback fonts; these settings are brand calibration, not a universal readability result.

UI & Table Cell

Geist Sans · 400/600 · 13px

Ring Buffer + Lease — synthetic 450,000 requests/s across 12 regional edge POPs.

Technical Mono

Geist Mono · 500 · 12px

let epoch = Ordering::Acquire; // synthetic_p99_latency_ms = 1.84

Module 08 · Production Token Spec

08. Surface, Signal & Syntax Color Tokens

Click any swatch to copy hex

Module 09 · Machine-Readable Agent & CDN Hub

09. Agent Skill, Repository Guides & Cross-Site Imports

View Raw SKILL.md View Raw AGENTS.md View llms.txt

This living design system serves both human engineers and AI coding agents. All assets, token manifests, and agent skill instructions are bundled inside the repository and exposed directly as static HTTP endpoints.

1. SHARED CSS / JS dist/

Cross-Page Asset Links

Import dist/atelier.css and dist/atelier.js via GitHub Pages, jsDelivr CDN, or Google Cloud Storage.

./dist/atelier.css ./dist/atelier.js

2. AGENT SKILL skills/swiss-atelier/

Reusable SKILL.md

Invoke explicitly with $swiss-atelier or “use Swiss Atelier.” Your requested format governs delivery; HTML requires an HTML or web-page request. Optional companions preserve Swiss identity.

./skills/swiss-atelier/SKILL.md

3. AGENT DISCOVERY Root Manifests

AGENTS.md & llms.txt

Point any agent at your hosted root URL or repo; llms.txt and AGENTS.md index every asset.

./AGENTS.md ./llms.txt Starter HTML

<!-- Current-main recipe: use guidance and assets from the same deployed build -->
<link rel="stylesheet" href="https://jeonkwan.github.io/swiss-atelier-design-system/dist/atelier.css" />
<script src="https://jeonkwan.github.io/swiss-atelier-design-system/dist/atelier.js" defer></script>

Install the complete Swiss Atelier skill directory, including agents/openai.yaml and references/.
https://jeonkwan.github.io/swiss-atelier-design-system/skills/swiss-atelier/SKILL.md

Invoke explicitly with $swiss-atelier or “use Swiss Atelier.” Installation does not activate it.
Preserve the requested output format; create HTML only for an HTML/web-page request.
Establish audience, task, evidence, and unknowns before styling.
Choose a representation and define arrow/boundary semantics before drawing.
Keep Swiss typography, surfaces, and contextual text colors.
Use matching CSS, JS, tokens, templates, and guidance from one source.
Check reader understanding, text equivalents, and rendered delivery.

Use Swiss Atelier to create an HTML page.
1. Read the agent skill and token rules from: https://jeonkwan.github.io/swiss-atelier-design-system/skills/swiss-atelier/SKILL.md (or ./skills/swiss-atelier/SKILL.md)
2. Import the shared stylesheet and auto-highlighter runtime in <head>:
   <link rel="stylesheet" href="https://jeonkwan.github.io/swiss-atelier-design-system/dist/atelier.css" />
   <script src="https://jeonkwan.github.io/swiss-atelier-design-system/dist/atelier.js" defer></script>
3. Reuse supplied audience/task/evidence; keep unknowns visible. Read the linked authoring and diagram methods. Follow the 1px Quiet Hairline architecture, Fraunces 500 + Literata 440 + Geist typography, 4px orthogonal SVG diagram rules, and [data-atelier-code] syntax highlighting.