Vocabulary note. This document predates the depot ruling and says realm where standalone Deck now says depot — the URL slot holding a live tree, a store, and a prefix. Where a sentence is genuinely about the Boxel construct, it means that. See deck-depot-and-realm-backport.md.
Status: for design exploration. The protocol, server, and CLI are built and tested (151 tests); every endpoint, field, and state referenced here is real and reachable today. What is not settled is the product: this document fixes the requirements and the invariants, and deliberately leaves information architecture and interaction patterns open, with directions to explore.
Collaboration vocabulary update (2026-08-20).
deck-fork-merge-pr-ux.mdsupersedes this document's instruction to avoid branch, pull request, and merge in product UI. The familiar names are now deliberate. Internally, a branch and an external fork use the same isolated fork primitive: same owner/repository is presented as a branch; a different owner is presented as a fork. A fork remains private until a pull request is opened. A Repository may contain one or many independently addressable member packages; a multi-package Repository is simply a monorepo. Seedeck-collaboration-protocol.md.
Branch and fork are one lineage affordance in Browse. Mutable packages get a compact branch selector whose New… menu contains Branch here and Fork to my scope. Imported packages are read-only and expose Fork only. The full Review surface becomes prominent only after work exists.
Read §1–§6 as constraints. Read §7–§8 as an invitation. Use §9 to check any design against all four workloads in about twenty minutes.
Companion: deck-use-cases.md — the four workloads in full, and why they break on git and npm.
Deck develops, versions, publishes, and shares packages of ES modules and JSON without npm, GitHub, a build step, or a deploy.
A realm is a directory. Its layout IS its URL space:
<root>/site/acme/palette/palette.js on disk
/site/acme/palette/palette.js live — every save, immediately
/site/acme/palette@1.1.0/palette.js sealed — immutable forever
/site/_history/<changeId>/… any state it was ever in
Four ideas carry the product:
- The URL is the path.
lsshows the latest of everything;@<version>reads the same path out of a seal. - Every save is captured. A settled edit auto-publishes an immutable
prerelease (
1.0.0-dev.7, taggeddev) and is sealed — including states never published. - Identity is content. A tree's
treeHashis its name. Publishing the same content twice writes no bytes; releasing is a pointer move. - A fork is a proposal. It records its base, so a daemon keeps every proposal merged against upstream, and any proposal can be run by changing a URL.
Vocabulary — use consistently; do not introduce branch, commit, merge request, checkout, or staging.
| Term | Means |
|---|---|
| realm | a directory served at /<realm>/; the unit of history |
| publisher | the scope segment; also the fork boundary |
| deck | a package: a directory with an importmap.json |
| live | the bytes on disk right now; no version in the URL |
| dev | dist-tag on the freshest auto-published prerelease |
| sealed / version | an immutable published state, @<version> |
| seal | one point in realm history (changeId), published or not |
| decklist | a deck's declared dependency ranges |
| lock | those ranges resolved to exact pins |
| offer | a fork that records its base — a proposal |
| trial | running something with dependencies swapped (?with=) |
From the use-case pass. These are not personas; they are shapes of work, and a design that serves all four is the product.
| W1 Swarm tool | W2 Codelists | W3 Adapters | W4 Skills | |
|---|---|---|---|---|
| What | 8 agents build one dashboard | shared reference data | Zapier-style long tail | prompt + tools bundles |
| Unit | component deck | a JSON list | four strata: adapter / bespoke pattern / generic pattern / instance | one skill |
| Decks in play | ~8, all changing | 1–20, many editors | 100s, mostly static | 10s, one hot |
| Content | ES modules | JSON only | small modules + schema | markdown + JSON |
| Edit cadence | continuous, parallel | bursty amendments | rare per deck, constant across catalog | 200 edits/hour on one |
| "Is it good?" | the assembled app runs | consumers still render | the automation fires | the agent behaves |
| Contribution | internal, trusted | many, shallow | long tail, unknown | fork-and-house-style |
| Privacy | internal | public | mixed within one workload | often private |
| Failure today | branches don't compose | JSON conflicts + stale forks | contribution costs 100× the change | iterations are lost |
Each workload wants a different object at the center, and any hierarchy that privileges one will fight the others:
- W1 → composition. The interesting object is the assembled app right now and the volatility of each part. Realtime matters. Eight decks, one answer.
- W2 → the data itself. There is no app to run; the "preview" is the list rendered as a table. Diffs are semantic (which keys moved), and the notable event is two additions that did not conflict.
- W3 → the catalog and the queue. Hundreds of siblings. Discovery, search, and triage dominate; any individual deck is small and boring.
- W4 → the timeline. Versions barely matter; iterations do. The core act is comparing two moments and going back to one.
A useful way to hold this without four products: the same deck, read through different lenses (code / data / running / timeline). Whether "lens" is the right construct is a design question — see §7.
From deck-use-cases.md §5. Every deck sits somewhere on three correlated axes, and its position determines what the user needs from it:
- Velocity — per-keystroke to per-quarter.
- Width — one consumer to thousands.
- Privacy — full of my specifics, or free of them.
Fast things are private and have one consumer; wide things are slow and public. W3 is the workload that contains the whole spectrum inside itself:
| Stratum | Velocity | Width | Private | Wants |
|---|---|---|---|---|
adapter (hub/slack) |
monthly | thousands | no | pinned semver, trust |
bespoke pattern (me/ship-notes) |
hourly, then never | one | yes | zero ceremony, restore |
generic pattern (team/message-to-doc) |
weekly | many | no | a contract + a config schema |
| instance (my binding) | occasional | one | maximally | to be data, and to hold secret references |
Two consequences the design has to carry:
- Position on the axes is a property worth showing. "Frozen and widely used" and "moving and mine" should not look the same, even though both are decks. This is the same information as volatility, read at the level of a whole deck rather than a single dependency.
- The promotion path is a product moment. Bespoke → generic is a fork plus an extraction of specifics into a config schema, with the private original untouched. It is the transition Zapier cannot do at all, and it deserves to feel like an event.
- Something is live and something is frozen, and the user constantly chooses which they are looking at.
- The URL is the handle for everything, including proposals and trials.
- Going back must be cheap and safe, or people won't move fast.
- Somebody else's version of this is a first-class, ever-present state — not an edge case.
| Tension | W1/W4 want | W2/W3 want |
|---|---|---|
| Density | one thing, deeply, live | hundreds of things, scannably |
| Time | the timeline is primary | the timeline is audit trail |
| Preview | run the app | render the data / fire the automation |
| Contribution | internal, implicit | external, queued, at volume |
| Diff | line-level code | key-level data |
Each requirement names the workloads that demand it. A design may satisfy a requirement any way it likes.
R1 — Volatility is always answerable and always changeable. At any moment the user can tell whether they are seeing live, a sealed version, or a trial, and can switch in one action. (all four)
R2 — Nothing implies mutability the protocol lacks. A sealed version is
immutable; never offer to edit 1.1.0. (all four)
R3 — Every view exposes its canonical URL, copyable. The URL is the product's central idea and the unit of sharing — a review, a trial, a bug report, and a dependency pin are all URLs. (all four; W3 most)
R4 — Provenance is one hop away. version → its seal; fork → its base; vendored module → its origin; pin → the deck it points at. (W2, W3, W4)
R5 — Review is running, not reading. Getting from "someone proposed something" to "I am running it" is one action, with no checkout or build. (W3 primary, W4 strongly)
R6 — The exceptional few must be legible among the healthy many. 3 conflicted among 200 fine; 1 misbehaving agent among 8. (W1, W3)
R7 — Actions state their true cost at the moment of action. Releasing copies zero bytes; restoring is undoable; pruning frees bytes only when nothing points at them; adopting copies nothing. (all four)
R8 — Live means live. The UI updates without refresh when the filesystem changes; sealed views never change under the user. (W1 primary)
R9 — Degraded capability is stated, never faked. No jj → say Versions only and how to enable every-save History; a backend that cannot enumerate → say so, never show an empty tree. (all four)
R10 — Data decks are first-class, not code decks with JSON in them. A deck whose content is data needs a data reading, a key-level diff, and a "these two additions merged cleanly" story. (W2; also W4's schemas) (new — this is the largest gap in the previous draft)
R11 — Many-deck views must scale before they are pretty. Hundreds of sibling decks, thousands of versions, 200 open proposals. (W3) (new)
R12 — Iteration is the unit for some workloads. Where 200 edits produce one release, the timeline is the primary object and versions are secondary. (W4) (new)
R13 — Simultaneous authorship is visible. When several agents edit at once, the user can see what is moving and what is standing still. (W1) (new)
R14 — A deck that declares a config schema is configurable, for free. The schema generates a form; an instance is a JSON document validated against it. The "configure an integration in a UI" product and the "read a data deck" product are the same product. (W3 strata S2b/S3; W2 and W4 schemas) (new)
R15 — A fork is private until it is offered. Forking to hack something for yourself must not enqueue a proposal against a maintainer who never asked. Proposing is a separate, deliberate act. (W3 bespoke stratum; W4 house-style forks) (new — the current implementation conflates these; see §13.8)
R16 — Secrets are references, never values, and the UI must make that visible. Immutability is hostile to secrets: a key sealed into a pack is content-addressed forever and cannot be recalled. A config deck names a secret; the host resolves it at runtime. Show the name, never a value, and make an unresolved reference a legible state rather than a blank. (W3 instances; anything with auth) (new)
Not a code editor (file contents are read-only; editing happens in the user's editor or by an agent). Not a discussion system. Not a permissions surface — identity arrives with the realm server.
Five primitives. The names and forms below are placeholders — inventing better ones is part of the work. What matters is that each concept is expressible and unambiguous.
- Volatility — live / dev / a version. Three genuinely different
promises, never blurred.
latestis a dist-tag on a stable release and is not live. - Identity —
treeHash. Two versions with one hash are the same bytes; that is what makes releases free. Sameness should be visible, not inferred. - Provenance — where this came from: a seal, a base, a CDN, a fork.
- Immutability — sealed is forever; live changes under you; a trial is temporary and must never be mistaken for either.
- Proposal state — current / rebased / conflicted / unresolvable. Only one of the four wants attention.
Atomic intents, replacing a screen list. A design can distribute these however it likes; §9's rubric checks that they are all reachable.
Orient
- J1 What exists here? (all)
- J2 What is changing right now? (W1, W4)
- J3 What does this deck contain, at the volatility I choose? (all)
Iterate
- J4 Is my thing running, and did my last save land? (W1, W4)
- J5 What changed between these two moments? (W2, W4)
- J6 Go back to how it was. (W4, W1)
- J7 Freeze this state as a real version. (all)
Depend
- J8 What am I depending on, and how exposed am I? (W1, W2)
- J9 Move a dependency forward, deliberately. (W2, W1)
- J10 Freeze one dependency while everything else keeps moving. (W1)
Contribute
- J11 Take someone's thing and start changing it. (W3, W4, W2)
- J12 Show someone what I did — running. (W3, W4)
- J13 What is proposed against me, and what needs me? (W3)
- J14 Take it. (W3)
Trust
- J15 Where did this come from? (W2, W3, W4)
- J16 Is this exactly what was published? (all)
C1 — The server is read-only. GET/HEAD only; everything else 405.
Mutation needs a channel; see §10.
C2 — Version-less means live. Three distinct things: live, @dev,
@latest.
C3 — Ranges never match prereleases. Opting into churn is explicit.
C4 — A realm's machinery is not content. .deck/ and .jj/ are never
listed or served; they appear only as facts about a realm.
C5 — Trials are no-store and must be visually unmistakable.
Five organizing principles, each real, each with a cost. None is recommended. The interesting work is probably a hybrid, or a sixth idea.
Realm → Publisher → Deck, and inside a deck, modes for files / versions /
history / dependencies / preview.
Favors: W1, W4 (deep single-object work). Fights: W3 (a catalog of 300 is
three clicks deep and unsearchable), W2 (data buried under a file tree).
Question: can search and a strong locator rescue the catalog case?
The app is the home object; its dependency graph is the navigation; each node carries a volatility control. Favors: W1 decisively — composition is the screen. Fights: W2 (no app to run), W3 (adapters have no single app). Question: is "the running thing" generalizable — could a codelist's "app" be its rendered table, and an adapter's be its harness?
Separate top-level spaces: Build, Data, Proposals, History. Each optimized for one center of gravity. Favors: all four, individually. Fights: coherence — the same deck appears in several places, and users must learn which space to be in. Question: are these genuinely different activities, or one activity with different content?
Minimal chrome. A command bar accepts any Deck URL, spec, or name and resolves it; the body renders whatever was addressed. Deep links are the primary navigation, and the UI is a viewer for the address space. Favors: the protocol's own logic, W3 (paste an adapter URL), sharing. Fights: discovery and orientation — you must know what to ask for. Question: is this a mode inside another direction rather than a whole one?
An activity river: saves, publishes, seals, proposals, adoptions. Objects are reached through their events. Favors: W4 (iteration is the object), W1 (watch the swarm). Fights: W2, W3 (stable things vanish from a feed). Question: does a feed work as a secondary spine everywhere?
One deck, several readings: code (tree + text), data (table + key-diff), running (iframe/harness), timeline (iterations). The lens persists as you navigate. Attraction: dissolves the four centers of gravity without four products, and makes W2 and W4 first-class rather than special cases. Risk: lens-switching becomes a hidden mode; the wrong default makes the tool feel wrong for a whole workload. Question: is the lens chosen by the user, or inferred from content and overridable?
Eight recurring problems. Each states what must be true, then sketches possibilities without picking one.
P1 — Expressing volatility (R1, all workloads). Must convey: three kinds of promise; that live changes under you; that pinned does not. Possibilities: a segmented live/dev/version control; one dropdown listing everything; a temperature or risk metaphor (hot/warm/frozen); a slider from "every save" to "pinned forever". Test it against W1's per-dependency mixture — some hot, some frozen, in one view.
P2 — Making zero-copy legible (R7, invariant 2). Must convey: two versions can be the same bytes; a release copied nothing. Possibilities: alias lines linking timeline entries; identicon/color-hash for treeHash; explicit "same content as 1.0.0-dev.4" text. Watch for: a hash-as-decoration that carries no meaning.
P3 — Trial mode (R5, C5). Must convey: this is not the real state; what is swapped; how to leave; how to share. Possibilities: a persistent banner; distinct frame chrome; side-by-side real vs trial; a "tray" of override chips that composes several at once (a slate). Test with W3's review flow and W4's A/B of two skills.
P4 — Triage at 200 (R6, R11). Must convey: the few that need a person, without hiding the many that don't. Possibilities: conflicted-first list with a single collapsed "197 merging cleanly"; kanban by proposal state; inbox-zero; a heat strip over the catalog. Test: can a maintainer find and act on 3 conflicts in under a minute?
P5 — Reading data decks (R10). Must convey: a JSON deck as data, and a key-level diff. Possibilities: a table with added/changed/removed keys; a schema-aware form view; a merge view that shows "you added 3 keys, they added 2, none collided". This is currently unserved and is W2's whole experience.
P6 — Scrubbing iterations (R12). Must convey: hundreds of unnamed states, findable by time and by what changed. Possibilities: a video-style scrubber; bisect (better/worse) that narrows a range; pinning two points for comparison; sparklines of what files moved. Test with W4: "the version 40 minutes ago was better."
P7 — Simultaneous authorship (R8, R13). Must convey: what is moving, who or what is moving it, and what is deliberately standing still. Possibilities: per-deck heartbeat/pulse; presence chips; an activity river; a "frozen" badge that reads as a choice rather than as staleness. Test with W1's eight agents, including the quarantine move.
P8 — Consequential moments (R7). Restore, adopt, release, prune. Must convey the true cost — usually reassuring, occasionally not. Possibilities: inline confirmation stating the fact ("0 bytes copied", "the state you are leaving is sealed first"); post-action undo affordance; a receipt. Avoid generic "Are you sure?" — the whole point is that these actions are cheaper than they look.
Everything below is drop-in. Fixtures are real shapes from live runs.
Each card: the situation, what the person wants, and what must be visible for them to decide. Design against the cards; they are the acceptance test.
W1 — Swarm tool
- C1.1 Eight agents editing; the dashboard is open. Wants: to see it assemble live. Must see: which parts moved in the last minute; that the app is composed of eight decks.
- C1.2 Chart 3 has gone wrong. Wants: to stop just that. Must see: chart 3's current volatility, its last good version, and the effect of freezing it on everything else (none).
- C1.3 The filter bar looks right. Wants: to freeze it as
1.2.0. Must see: which sealed state is being named, and that it copies nothing. - C1.4 Something broke twenty minutes ago. Wants: to find and restore. Must see: the states between publishes, what changed in each, and that restoring is undoable.
W2 — Codelists
- C2.1 Adding three currency codes. Wants: confidence it will not conflict. Must see: the list as data, their additions as keys, that nobody else touched those keys.
- C2.2 Two people amended simultaneously. Wants: to know both landed. Must see: a merge that reads as combination, not as a resolved conflict.
- C2.3 Consuming the list at
^1.0.0; a1.4.0exists. Wants: to know what changed before moving. Must see: a key-level diff, and what moving the pin would change. - C2.4 Maintaining a fork with three internal codes. Wants: to stay current without losing the patch. Must see: that upstream amendments are being absorbed automatically, and when they collide.
W3 — Adapters
- C3.1 300 adapters in the catalog. Wants: the one for Shopify. Must see: search, and enough per-item signal to choose.
- C3.2 An adapter is broken. Wants: to fix it now. Must see: how to fork it into their own scope and have it running immediately.
- C3.3 Maintainer, 200 open proposals. Wants: the ones needing them. Must see: conflicted first; the rest as a single reassuring line.
- C3.4 Reviewing one proposal. Wants: to see it work. Must see: one action that runs the real harness with this adapter substituted.
- C3.5 It works. Wants: to take it. Must see: what version is being created, and that it copies zero bytes.
- C3.6 Vibe-coding a one-off: their Slack rule, hardcoded, for themselves. Wants: speed, and no publishing decision. Must see: that it is captured anyway — addressable, versioned, restorable — without having asked for any of that, and that it is not proposed to anyone.
- C3.7 Four colleagues want that one-off. Wants: to generalize it. Must see: the promotion path — fork to a new name, extract the hardcoded specifics into a config schema, publish — with the private original still running, untouched.
- C3.8 Configuring the generic pattern for a new team. Wants: to fill in a form, not read code. Must see: a form generated from the schema, and their instance saved as data.
- C3.9 An instance needs a Slack token. Wants: it to work without the token ending up anywhere permanent. Must see: a named secret reference, never a value, and a clear state when it is unresolved.
- C3.10 Their pattern depends on a moving thing and a frozen thing.
Wants: to reason about exposure. Must see: per-dependency
volatility in one view —
hub/slackpinned,me/formatlive.
W4 — Skills
- C4.1 200 iterations in an hour. Wants: not to think about saving. Must see: ambient confirmation that everything is kept.
- C4.2 Version from 40 minutes ago was better. Wants: to find it. Must see: a scrubbable history with enough signal to recognize it.
- C4.3 Comparing two variants. Wants: A/B them. Must see: two addressable runs, side by side or in two tabs.
- C4.4 Their fork of a community skill. Wants: upstream's improvements without losing house style. Must see: what was absorbed, and when a collision needs them.
Realm site, tier-2 history (jj). Paste into mocks.
W1
tool/charts/revenue live · dev 2.1.0-dev.14 · latest 2.0.0 ← moving
tool/charts/funnel live · dev 1.4.0-dev.3 · latest 1.4.0
tool/ui/filter-bar live · dev 0.9.0-dev.22 ← moving
tool/ui/table live · dev 3.0.0-dev.7 · latest 2.9.1
tool/data/warehouse live · latest 1.2.0 ← frozen by choice
tool/app/dashboard live · deps: 5 (3 live, 1 ^2.0.0, 1 dev)
W2
std/currencies latest 1.4.0 · dev 1.5.0-dev.9 · 168 keys
1.5.0-dev.9 adds: XCD, SRD, ZWG (3 contributors, 0 conflicts)
acme/currencies fork of std/currencies@1.4.0 · +3 internal codes
state: rebased (absorbed 1.4.0 → 1.5.0-dev.9 automatically)
W3 — note the four strata coexisting in one realm
hub/slack latest 2.1.0 · 41 dependents · frozen, wide, public
hub/gdocs latest 1.4.0 · 38 dependents
… 297 more adapters
team/message-to-doc latest 1.2.0 · 9 dependents · config.schema.json
me/ship-notes dev 0.1.0-dev.212 · 1 dependent (me) · private fork of
team/message-to-doc@1.0.0 · deps: hub/slack ^2.0.0,
me/format live
me/ship-notes-config instance data · secrets: [SLACK_TOKEN, GDOCS_SA] (refs)
offers: 200 open — 197 current/rebased, 3 conflicted
you/stripe-slack ← hub/stripe-slack@2.1.0 conflicted: auth.js
ana/webhook-any ← hub/webhook-any@1.0.0 rebased
kim/notion-sync ← hub/notion-sync@3.2.0 unresolvable (base pruned)
W4
skills/reviewer latest 4.2.0 · dev 4.3.0-dev.171
you/reviewer-strict fork of skills/reviewer@4.2.0 · state: current
seals today: 171 · last: "save: prompt.md" 40s ago
Sample payloads. GET /_packages:
{ "meta": { "history": { "tier": 2, "kind": "sealed-tree", "jj": true,
"historyd": false, "realms": ["site"] },
"layout": "<realm>/<publisher>/<package>/ on disk and in the URL; …" },
"data": [{ "type": "realm", "id": "site", "name": "site",
"history": "jj", "historyPath": "/site/_history",
"packages": [{ "type": "package", "id": "site/acme/palette",
"publisher": "acme", "name": "palette",
"live": true, "livePath": "/site/acme/palette/",
"versions": { "1.0.0-dev.1": { "treeHash": "bbbfb346…" },
"1.0.0": { "treeHash": "bbbfb346…" } },
"distTags": { "dev": "1.2.0-dev.1", "latest": "1.2.0" } }] }] }Note 1.0.0-dev.1 and 1.0.0 share a treeHash: that is a release that
copied nothing, and it is the normal case, not a duplicate.
GET /site/_offers:
{ "meta": { "realm": "site", "open": 200, "conflicted": 3 },
"data": [{ "type": "offer", "id": "you/stripe-slack",
"attributes": { "upstream": "hub/stripe-slack", "state": "conflicted",
"upstreamVersion": "2.1.0", "conflicts": ["auth.js"],
"tryWith": "?with=hub/stripe-slack=you/stripe-slack" } }] }GET /site/_history:
{ "meta": { "backend": "jj", "tier": 2, "realm": "site" },
"data": [{ "type": "seal", "id": "wovmruymqrvw…",
"attributes": { "timestamp": "2026-08-07T20:13:24-0400",
"description": "save: you/app/app.js",
"filesSummary": ["M you/app/app.js"],
"filesUrl": "/site/_history/wovmruymqrvw…" } }] }Run any candidate design against this. It is the fastest way to find a design that is secretly single-workload.
- The quarantine test (W1). From "chart 3 is broken", how many actions to freeze only chart 3? Is it obvious that nothing else stopped?
- The two-additions test (W2). When two people add different keys, does the interface communicate combination — or does it use conflict-resolution language for something that was not a conflict?
- The needle test (W3). With 200 proposals of which 3 are conflicted, how long to find and open all three? Do the 197 reassure or clutter?
- The scrub test (W4). With 171 unnamed iterations today, can a user find "the one from 40 minutes ago" without reading them all?
- The volatility test (all). Point at any element on screen: can you say whether it is live, sealed, or a trial, without clicking?
- The share test (all). Can any state on screen be handed to a colleague as a URL that reproduces it?
- The honesty test (all). Does a release say it copied nothing? Does a restore say it is undoable? Does a missing jj say Versions only rather than showing an empty history?
A design that passes 1–4 is serving all four workloads. 5–7 are the protocol's character; failing them yields a competent tool for a different product.
The server is read-only by design (C1), but most jobs in §5 mutate. Three options:
- A — Read-only UI, copyable commands. Every action renders the exact CLI command. Honest, zero new surface, slowest.
- B — Local action endpoint (recommended).
deck servegains a small, localhost-only, non-protocol action API used only by the UI (release, lock, fork, restore, adopt, rebase-now). The read-only protocol surface is untouched; actions call the CLI's own functions. In the realm server this becomes the Matrix-authenticated write path. - C — UI writes files directly. Rejected: bypasses the invariants the CLI enforces (manifest agreement, immutability).
Design should assume B and treat action affordances as a capability that can be absent, so the same components work in a read-only or remote context.
| Dimension | Target | Driven by |
|---|---|---|
| decks per realm | 100s | W3 |
| versions per deck | 1000s | W4, W1 |
| seals per realm | 10,000s | W4 |
| open proposals | 200+ | W3 |
| files per deck | 1000s | W1 |
| keys per data deck | 10,000s | W2 |
| concurrent editors | 20 | W1 |
Each is real and reachable, and each is covered by a test.
- Empty: no realms · realm with no decks · deck with no versions · no proposals · no seals.
- Degraded: tier-1 history (no jj) · backend cannot enumerate a seal's tree · cross-realm dependency refused (not yet supported, not an error).
- Two flavours of miss, and they must not look alike: invalid (a malformed spec can never resolve — permanent) vs not-found-yet (a legal tag nobody has published — transient).
- Never servable:
.deck/,.jj/. - Binary content: no preview; size, digest, download.
- Conflicted proposal: per file, with the three-sided marker content available in a comparison.
- Trial active: unmistakable, one action to exit.
- Unresolvable proposal: the base tree is gone; needs an explanation, not a retry.
- Are lenses (§7) real, or four screens wearing a costume?
- Is the timeline one object with different densities, or genuinely different objects for W4 (iterations) and W1 (audit)?
- Where do proposals live — realm-level board, per-deck inbox on upstream, or in the contributor's own space? The data supports all three.
- How prominent should
treeHashbe? It is the notion of identity and the proof behind "zero copies", but it is 64 hex characters. - Is a data deck a different kind of thing in the IA, or the same thing read differently?
- What does "we looked and said no" look like, given the protocol has no reject — an unadopted proposal just stays a fork forever?
- Should the UI ever show the CLI command it is about to run? (It is a teaching surface, and it is the honest answer under option A.)
- How does a fork say whether it is a proposal? (R15.) Candidates: a choice at fork time; inferred from whether an actor was recorded; a private realm making it structurally invisible; or a fork that is private by default and becomes an offer only when someone points at it. The last matches how people work, and it changes the offers board from "everything anyone forked" to "everything anyone offered".
- Is an instance a deck, or a document inside one? A configured automation is data, one-of-a-kind, private, and edited through a form. It may not want to look like a package at all.
- Should a deck's position on the axes (§2.1a) be shown, and how? It is derivable — velocity from seal frequency, width from dependent count, privacy from realm and content — but derived signals can mislead.
| Endpoint | Provides | Cache |
|---|---|---|
GET /_packages |
realms, decks, versions, tags, history capability | no-store |
GET /_packages/<realm>/<pub>/<pkg> |
one deck's versions/tags/flags | 60s |
GET /_browse/<realm>[/<pub>[/<pkg>[@<spec>]]][/path] |
tree listing / file with text preview, size, sha256 | live: no-store; sealed: 60s |
GET /<realm>/<pub>/<pkg>/<path> |
live bytes | no-store |
GET /<realm>/<pub>/<pkg>@<spec>/<path> |
sealed bytes (302 for tag/range, 301 for form) | immutable |
GET /<realm>/<pub>/<pkg>@<v>?meta |
entry, exports, files, sealChangeId, treeHash |
60s |
GET /<realm>/<pub>/<pkg>@<v>?format=pack |
the pack | immutable |
…?with=<spec> (repeatable) |
trial override | no-store |
GET /<realm>/_history[/<changeId>[/<path>]] |
seals; tree at a seal; bytes at a seal | log: no-store; seal: immutable |
GET /<realm>/_offers |
proposals with state, conflicts, tryWith |
no-store |
GET /_live/events |
SSE change events {name, treeHash} |
stream |
Headers worth surfacing in a details affordance: content-digest (RFC 9530),
x-deck-tree-hash, x-deck-seal, x-deck-package, x-deck-realm,
x-deck-with, x-deck-importmap.