A series of working prototypes demonstrating local-first architecture applied across domains: governance monitoring, commerce, healthcare, and social networking. Plus a published architectural specification — with a built reference implementation — that extends the same argument into the employment relationship.
The central argument: local-first works when something irreducibly server-dependent has to happen. The question is not whether to touch a server — sometimes you must. The question is how to design that boundary deliberately, minimize it, and ensure the client loses nothing when it fails.
The name for that boundary is the seam.
The series demonstrates a four-layer architecture for local-first systems where boundary events carry weight. I call it the Seam Stack, documented at seamstack.org and in the seam-stack repository.
| Layer | Question it answers | Technology in this series |
|---|---|---|
| Substrate | Where does the data live, who owns it, who can access it? | Y.js + IndexedDB (prototypes #1–#4); Automerge + Keyhive (employment seam — built reference implementation) |
| Governance | How is meaning structured, classified, and made machine-legible? | The Tiered Content Framework (TCF) — six tiers with three cross-cutting governance dimensions |
| Boundary | What happens at the transition where the relationship between client and server changes state? | The Pattern Commons seam discipline — the seam as architectural object |
| Evidence | What makes the record contemporaneous, tamper-evident, and legible to deferred parties without platform mediation? | W3C Verifiable Credentials Data Model 2.0 + RFC 3161 trusted timestamping + OpenTimestamps + bilateral cryptographic signatures (employment seam); seam:CrossingRecord base shape (all seam types) |
The synthesis claim: all four layers are required when boundary events carry legal and evidentiary weight, and they compose into a coherent architecture for local-first systems in those domains. None of the four layers is novel in isolation; the synthesis is the architectural composition.
Status: early working idea. Read the speculative treatment here.
This is a sketch, not a finished specification. It describes a direction under active exploration, in plain terms. The detailed version is being revised and will be published here when it's ready.
The idea in one paragraph
Software that keeps your data on your own devices — "local-first" software — is getting good at storing, syncing, and protecting that data. What it doesn't yet have is a good answer for the moment your data has to leave: when you share a record with an employer, a doctor, a marketplace, or another person's system. Today, that moment of crossing is usually invisible — it just happens, with no record, no rules, and nothing to point to afterward. The crossing-layer framework is a proposal to make that moment a first-class, governed event.
What it would do
Three commitments, in plain terms:
The record comes first. Before your data crosses a boundary, a durable record of the crossing is written — who, what, under which agreement. The record isn't an optional log added later; the crossing can't happen without it. No middleman required. Producing and verifying that record doesn't depend on a cloud service, a blockchain, or any central authority being reachable. The rules travel with the data. Evidence that outlives the moment. Each crossing produces a tamper-evident receipt that someone arriving later — an auditor, a counterpart, your future self — can check on its own, without access to anyone's private systems.
Where this stands
A working prototype has demonstrated the core of this on a real stack, with test evidence. The results so far are scoped to that one setup — no broader claims yet. The full design sketch, including how it relates to existing work in this space and the open questions still unresolved, is in revision and will be published in this directory.
If you've found this early: the finished, reviewed versions of ideas from this project live in the Pattern Commons entries elsewhere in this repository. Everything in this proposed framework is workshop material — read its README for what that means.
| # | Prototype | Seam | Live | Repo |
|---|---|---|---|---|
| 1 | Governance Window Tracker | None — browser is the application | infinitydrive.net | governance-tracker |
| 2 | checkout-seam | One seam per transaction (Stripe) | checkout-seam.vercel.app | checkout-seam |
| 3 | fhir-seam | One seam per intake submission (FHIR R4) | fhir-seam.vercel.app | fhir-seam |
| 4 | Local-First Social | One seam per new connection (WebSocket relay) | localfirst.social | local-first-social-network |
| 5 | employment-seam | One seam per transition (entry, exit, stage change, re-engagement) | Reference implementation — Automerge + Keyhive | employment-seam |
Each prototype introduces a harder version of the seam problem. The Tracker has no seam at all. checkout-seam has one seam per transaction. fhir-seam has one seam per intake submission, with a richer failure taxonomy and higher stakes. Local-First Social has a seam that fires on every new connection — the social graph itself is a distributed seam. The employment seam fires on every transition in the employer–worker relationship, with nine failure states, multi-perspective preservation in contested cases, and a legal record format designed for evidentiary use across jurisdictions.
The fifth entry is the first in the series where the specification preceded the reference implementation. The spec and reference implementation (Automerge + Keyhive substrate, v0.5 build plan) are both at employment-seam.
The institution keeps its copy. So do you. Person-side infrastructure for the records a life produces.
The five entries above are probes into four life domains — labor, health, commerce, and personal communication. In several of these, people already hold legal rights to copies of their records; what doesn't exist is the receiving side — person-owned infrastructure that can accept, hold, verify, and re-present them. What's unproven is composition: records from different domains coexisting in one person-owned store under a common schema. That, not a fifth vertical, is the roadmap. Full direction at seam-stack.
A root abstract pattern plus seven domain instantiations documented across the series. Each is designed as a reusable template — domain-agnostic, extractable, applicable beyond the prototype that first demonstrated it.
#00 — The governed crossing. The abstract pattern that all prior entries have been instantiating. A governed crossing is the boundary event at which a party with contextual knowledge crosses into or out of a structured relationship under a capability grant. Four constitutive properties — declared scope, grant, gate, record — are invariant across all domain instantiations. The architectural argument: every such crossing must be explicit, gated, and recorded before it fires, with the platform facilitating the event and exiting rather than accumulating the relationship. Spec at pattern-commons-00.
#1 — The checkout seam. Minimum server-dependent surface for a payment operation. Client preserves state on failure; writes the result record on success. Server is stateless and never consulted again after confirmation. Applies to: payment processing, identity verification, legal record creation, compliance logging.
#2 — The high-stakes seam. Write-before-POST discipline for operations where data loss is clinically or legally consequential. Richer failure taxonomy (accepted / validation error / transient error / permanent failure). Format translation at the seam boundary, not inside either system. Applies to: healthcare intake, government benefit submissions, regulatory filings.
#3 — The profile map as local CRM. Y.js document as the user's full relationship with a service — address, order history, intake history, trust graph — all local, sync-capable as an opt-in enhancement. No server-side session required.
#4 — The attachArrayObserver() pattern. How to correctly observe a Y.Array nested inside a Y.Map when the document hydrates from IndexedDB. Prevents the stale-reference bug. Must be applied from the start — not discovered during debugging. Applies to any hook in this stack.
#5 — The distributed seam. Where the server-dependent operation is a peer handshake rather than a server transaction. The relay facilitates connection and exits. The social graph is built from the accumulation of distributed seams, each of which fires once. Applies to any peer-to-peer application where a minimal relay facilitates connection without accumulating relationship data.
#6 — CRDT as trust graph. Trust tier assignments, connection history, and sync status stored as local-first Y.js state, synchronized via the distributed seam. No server owns the relationships.
#7 — The employment seam. The boundary event when a person enters or exits an employer–worker relationship. Worker owns the knowledge graph; the platform facilitates the handoff and exits. Bundle schema (SHACL over RDF, JSON-LD canonical), legal record format (W3C Verifiable Credentials 2.0 + RFC 3161 + OpenTimestamps), nine-state failure taxonomy, multi-perspective record in contested cases, seven-class participant model including AI agents (Class G). Generalizes WARN Act, EU European Works Council Directive, EU Collective Redundancies Directive, and contractor classification regimes. The first Pattern Commons entry where all four Seam Stack layers become necessary at once. Spec at pattern-commons-07. Reference implementation at employment-seam.
#8 — The substrate-crossing seam. The boundary event when a local-first system crosses into a substrate with different properties — different revocation semantics, different exposure guarantees, different epistemic regime. Where the employment seam crosses within a single substrate, the substrate-crossing seam crosses between substrates: the seam-side architecture enforces up to the boundary, then terminates by declaration. The pattern introduces a two-record intent/completion discipline (the crossing is declared before it fires, recorded after it lands), a new exposure-unbounded bound type (the architecture cannot assert an upper bound on post-crossing exposure), and a six-state failure taxonomy for crossing attempts. First worked domain: AT Protocol (Bluesky) as target substrate. Prototype-verified on that substrate (Phases 0–3, eight governed runs against a live PDS; reference implementation at employment-seam). Spec at pattern-commons-08.
#9 — The governed content production crossing. The boundary event when a content object crosses from an author-controlled local-first substrate to an externally legible surface — a CMS, a public AT Protocol record, a publication endpoint — at a declared TCF tier-compliance threshold. Where prior seams govern who crosses and what transfers, this seam governs the governed state of the content object itself at crossing time. The gate checks TCF Quark-level constraint satisfaction and tcf:register before the publish call fires; the crossing record is the schema-checkable artifact that makes TCF tier boundaries machine-verifiable rather than editorial. Design intent, speculative. Spec at pattern-commons-09.
These files govern the prototypes. They are series artifacts, not prototype-specific artifacts.
DESIGN.md — Design tokens and rationale for the series. The seam state palette (seam-none, seam-connecting, seam-established, seam-error) is the load-bearing design decision — it makes the architectural argument visible in the UI.
STATE_CONVENTIONS.md — Authoritative conventions for Y.js state across prototypes #1–#4 (Y.js + IndexedDB stack). Does not apply to employment-seam, which runs Automerge + Keyhive — see the employment-seam README for its state conventions. Every build session on #1–#4 reads this before writing any code that touches Y.js state.
Vocabulary and schemas — The base crossing-record vocabulary and employment-seam vocabulary are served from the seam-stack repository via GitHub Pages:
| Namespace | IRI |
|---|---|
| Crossing record (base shape) | https://jediwright.github.io/seam-stack/vocab/crossing-record/0.1/ |
| Employment seam | https://jediwright.github.io/seam-stack/vocab/employment-seam/0.5/ |
| Canonical assurance scale | https://jediwright.github.io/seam-stack/vocab/assurance/ |
The failures that produced this governance framework are documented honestly in the companion article at Systems of Thought.
The core principle is that boundary events with legal and evidentiary weight can't be governed after the fact. The spec has to exist before the code. The failure taxonomy has to be named before the seam is implemented. The record has to be a first-class output of the crossing, not an audit log appended afterward. This is not a software-quality argument — it's an architectural one. A boundary you haven't declared is a boundary you can't govern.
That principle produces a small set of rules that govern every build session in this series:
- Specification exists and is read before any implementation begins
- State conventions document exists and is read before any Y.js code is written
- Acceptance criteria written as testable conditions before code generation begins
- Failure taxonomy named before the seam implementation
- Hypothesis written before a fix is generated when a bug appears
- External user testing required before any phase involving network behavior is closed
The governance framework itself is documented at governed-pr-framework.
The theoretical frame for this series — why local-first systems need a theory of the boundary, and what worker-side governance infrastructure for AI agents at employment boundaries requires — is developed in Full Personhood: The Governance Model AI Requires and Capitalism Never Built.
| Repo | What it is |
|---|---|
| seam-stack | Architecture documentation, vocabulary namespaces, GitHub Pages IRI resolution |
| employment-seam | Pattern Commons #7 spec + Automerge + Keyhive reference implementation |
| governed-pr-framework | Governed PR Framework (GPRF) — blast-radius classification and epistemic-status tagging for pull requests |
MIT License · Built with AI-collaborative methods · Intellectual direction and authorial responsibility: Jedi Wright · Systems of Thought · UX Minds, LLC