Elixir · Ash · Phoenix · Postgres · MIT

The hard 80% of a B2B SaaS. Solved once. Proven on every commit.

Samen is a foundry for launching many B2B products from one substrate. Customer data is masked by default, support sees it only through a second person's approval, erasure destroys keys instead of rows, and the AI agent can only propose. One command emits a running product that passes its own gate. Every guarantee ships with a sabotage that proves its test can fail.

Take the tour ↓ Read the source ↗

Nothing is configured per surface. Each one renders what the field already returns.

604

committed sabotages, each proving a named test can fail

ls scripts/sabotages/*.patch

verifiers in the gate, from no_plaintext_pii to no_pan_columns

mix samen.verify.*

scope blueprints a product mounts as-is: CRM, billing, support, work, automation…

samen_core/lib/samen/scopes

hand-edits for a generated app to pass its own 19-step gate

gen_app_flagship_probe.exs

00The whole story

Every B2B product rebuilds the same 80%. And the same leak with it.

Auth, billing, a CRM, a support desk, files, search, exports, an admin tool for your own staff. Every one of those surfaces is also a door onto customer data, each with its own idea of who may open it. Samen builds the 80% once, at the substrate, and makes the safe answer the default value of a field, not a feature someone remembers to add. Then it tries to break every promise it makes.

Act I · Start

One command, a running product

Not a scaffold. A thing you can boot, with its own gate.

01Generate

Act II · Trust, by construction

Customer data that defaults to safe

Seven features that only work because the planes share one core.

02The vault
03Reveal
04Two planes
05Erasure
06Replay
07Cross-plane chat
08The AI agent

Act III · The rest of the 80%

Everything else a B2B SaaS needs

Surfaces, vendors and a cockpit for running many products.

09Working surfaces
10Billing & email
11Portfolio cockpit

Act IV · Proof

A test that cannot fail is a bug

Sabotages, mutants, and CI an agent can afford to run.

12Sabotage & mutation
13CI for agents
—What this is not

Act I · Start

The proof that a substrate is real is generative.

01Generate

One command. A product you can boot.

mix samen.gen.app doesn't hand you a folder of TODOs. It emits a product with a web UI, a JSON:API, seeds, observability, tests and its own verifier gate, and that app passes the gate on its first run with nothing edited in between.

19steps in the generated app's own gate, all green on the first run, zero hand-edits. re-run every PR

Billing, notifications, flags, an operator workspace and a deny-by-default API, mounted, not copied
One authored resource with a real PII field, so the vault and reveal path are live from the first migration
Four generators: app, scope, resource and agent, plus a fail-honest --deploy

What you actually get →Getting started ↗

# emit a new vertical from the substrate$ mix samen.gen.app --module Harbor --prefix hb --abbrev hrb * creating harbor/ web · api · seeds · telemetry · ci.sh * mounting Billing · Notifications · Flags · Operator desk * reserving abbrev hrb (permanent, like a ticker) # run the generated app's own gate. nothing edited.$ cd ../harbor && MIX_ENV=test bash ci.sh ✓ prefixes · catalog_parity · vault_declared_parity ✓ no_plaintext_pii · no_pii_columns · pii_reads ✓ api_contract · ai_prompt_masking · tnt_boundary ✓ migrations · same_org_fk · oban_queues · …19/19 steps ALL PASSED zero hand-edits $ mix harbor.seed && mix phx.server→ http://localhost:4050 ▍

The root gate does exactly this on every PR: generate a fresh app, run its whole gate, seed it, boot it, probe its routes, then sabotage it.

01Generate

Close ✕

Not an empty shell. Working surfaces.

You give the generator three things: a module name, a table prefix and a permanent abbreviation. Every table and column the app ever creates is projected through that abbrev, so storage self-qualifies from the first migration (attribute :name becomes hrb_name in the database, the CDC stream, the logs and the catalog).

What the generated app ships with

Surface	What makes it different
Billing scope	Plans, subscriptions, invoices and checkout, mounted as a framework scope, not copied into your tree
One authored resource	With a real `pii_attribute`, so masking and reveal are live, not described in a README
Token-blind aggregate	Cross-tenant rollups over resources with no `pii_*` columns at all
Notifications	One send chokepoint; unconfigured, it says so instead of pretending
Feature flags	Tenant-scoped, deterministic bucketing, fail-safe kill switch
Operator workspace	The second plane, masked by default
Deny-by-default API	`/api/v1` as JSON:API; a resource is hidden until explicitly allowed
The gate	19 verifier steps the app inherits, not just the code

The four generators

mix samen.gen.app       # a whole product
mix samen.gen.scope     # a new scope inside it
mix samen.gen.resource  # a resource, catalogued and vaulted
mix samen.gen.agent     # an AI agent + its emitted proof

How "zero hand-edits" is kept true

Four generator probes run in CI on every pull request. The flagship probe generates a fresh app, runs its full gate, seeds it, boots it, HTTP-probes its routes and drives two sabotages against the generated gate. If the substrate drifts from what it generates, this is where it shows. The probes work on a private copy of the abbreviation registry and fail if the committed one changes by a single byte.

Measured honestly. In pawchart, the veterinary vertical, the four scope-mount files total about 188 authored lines. That number is about mounting framework surfaces, not about apps: pawchart as a whole is a hand-built product of about 3,900 lines. An earlier page quoted the first number as if it were the second; that overclaim was retracted in the repo.

source · ADR-022 (the generator emits a running product) · ADR-024 (fail-honest deploy) · samen_core/priv/gen_app_flagship_probe.exs

Act II · Trust, by construction

Seven features that only work because both planes share one core.

Most products guard customer data in the places someone thought of. Samen moves the decision into the field itself, then builds every feature on top of that one decision.

02The vault

•••• isn't a redaction. It's the value.

Declare pii_attribute :email and the value goes to a per-subject-keyed vault. The row keeps a vt_… token; plaintext is nowhere at rest. Every reader gets %Masked{} back: the UI, the API, the CSV writer, the log line. Forgetting to mask is not a mistake available to you.

1decrypt path in the whole system. One function to gate, one to log, one for a reviewer to read. built

Validated, then tokenized: Money, Email, Phone, Address… each type's cast runs before encryption
CSV masks by omission: the column isn't in the file, so there's nothing to un-redact
A verifier in a separate OS process attests no tier holds plaintext

Why exactly one chokepoint →

02The vault

Close ✕

Why exactly one chokepoint

If plaintext can be produced at forty call sites, "no plaintext leaks" is forty separate claims, each decaying as the code grows. Route every read through one function and the claim becomes one question a machine can answer: who called it, under what grant, and was it recorded?

What happens to one PII field

Where	What it holds
Domain row	`vt_9f2c…`, a stable token you can join and group on, which says nothing about the value
Vault	AES-256-GCM ciphertext under a per-subject key held in an external KMS
UI · JSON:API · logs · CDC	`%Masked{}`, rendered •••• (four fixed bullets, so the mask doesn't leak the length)
CSV export	Nothing: the column isn't emitted

Six idioms, applied to every object

Self-qualifying storage: abbrevs projected at compile time into the DB, CDC, logs and catalog
A machine catalog written inside the migration transaction; an uncatalogued column doesn't compile
The PII vault with one decrypt chokepoint
Postgres as the engine: LISTEN/NOTIFY, SKIP LOCKED, Oban in the same transaction
A malleability ladder: config rows, validated custom fields, tenant objects, code
Two planes, one core: the next three sections

What it costs, on purpose

The guarantee is exactly as strong as key custody. Destroying a subject's key destroys their data everywhere; that's how erasure works. It also means a lost key is an accidental erasure, not a recoverable incident. Samen makes that trade deliberately.

source · ADR-001 key hierarchy · ADR-003 vault on OTP :crypto · ADR-036 rich types · mix samen.verify.no_plaintext_pii · Samen.Pii.WriteGuard

03Reveal

Support can see PII. Only with a second person's yes.

A dispatcher needs the address that bounced. Pretending support never sees data just moves the work into a spreadsheet nobody audits. Samen keeps the exception inside the system and makes it expensive, visible and self-expiring.

2people, always. The requester cannot approve: a database CHECK makes that row impossible, not just a form rule. built

Time-boxed: the auto-revoke job commits in the same transaction as the approval
Never renewed in place: an extension is a new request and a new approval
Tenant-readable: a hash-chained log the operator cannot edit, the tenant can read without asking

The four properties, with teeth →

03Reveal

Close ✕

Four properties, three enforced by the database

A property enforced only in application code holds until the next refactor. Three of these four live where a wrong deploy can't reach them.

Property	How it's enforced
Second-party	Policy check and `CHECK (granted_by <> requestor_id)`. They fail differently and share no failure mode.
Time-boxed	Every grant has `expires_at`; the revoke job is enqueued in the approval's transaction. If it can't be enqueued, the approval doesn't commit.
Logged, tenant-side	Hash-chained, append-only; a trigger refuses `UPDATE` and `DELETE`. Each entry carries the hash of the one before.
Scoped	These fields, this subject. Not a role that gets unmasked, not a session that gets elevated.

Why "never renewed in place" matters

A grant with a renew button becomes permanent the first afternoon someone puts it on a schedule. Here every extension is a separate, separately approved entry, so the log shows how many times access was granted, not one row with a date that keeps moving.

The actor that can't be granted anything

Cross-tenant analytics run as a token-blind actor over resources with no pii_* columns at all. The reveal path refuses that actor before any grant lookup, so an actor that can reveal can't run cross-tenant, and one that runs cross-tenant has nothing to reveal.

What we deliberately don't claim. An earlier version of this page said "run support without ever seeing PII." It sounded better and was false by construction, so it was retired. Support can see PII: through a grant a second person approved, that expires on its own, and that the tenant can audit without asking permission.

source · ADR-002 hash-chained audit + WORM anchor · ADR-010 operator plane · ADR-040 approvals (distinct-party CHECK)

04Two planes, one core

Your admin tool is the biggest leak in the company. Unless it's the same app.

The operator plane isn't a second application with its own queries. It's the same objects rendered for a different actor. Support sees the real UI, the real layout, the real bug. The PII inside it renders ••••.

3actors, one substrate. What you can see is a property of you, not of the page. built

Tenant: reads its own org in the clear; scoping is enforced at the resource, not per query
Operator: masked impersonation, grant-capable, every read in the tenant's log
Aggregate: token-blind, over resources with zero PII columns

Why a separate admin app is the leak →

In the productdriftwood, the freight vertical · one Blue Ridge Logistics roster, three actors

Switch the actor. The rows don't move; what resolves inside them does.

Tenant /broker?panel=roster Operator /operator/impersonate Aggregate /operator/aggregate

Rosa dispatches for Blue Ridge, so her actor is a tenant member of that org: every vaulted field on her own drivers resolves in the clear. No grant, no ceremony; this is the ordinary case.

Support opened a masked impersonation session with a reason. Same drivers, same order, same FMCSA badges, read through the same Driftwood.Reads.driver_roster; name and CDL resolve to %Masked{} because the plane is :operator and no grant is held.

The portfolio view runs as the token-blind aggregate actor over projections that have no pii_ column at all. Nothing is masked because nothing is maskable, and a lane with fewer than five tenants is suppressed to ⊘.

Blue Ridge Logistics/Operations/DriversRMRosa Medina
dispatchertenant plane

DriversFilter+ New driver

Driver roster5· your org — driver names in the clear

Driver	CDL #	State	CDL expiry	Med card	Status	FMCSA	Dispatch
MVMarcus Vale	D4471-8820	IL	2027-03-14	2026-11-02	on_load	OK	Dispatch
DWDana Whitfield	D5120-3364	MA	2028-06-30	2027-01-18	available	OK	Dispatch
TBTheo Brannigan	D3388-1907	OH	2027-09-02	2026-09-30	available	BLOCKED: medical card expired	Dispatch (blocked)
PRPriya Raghunathan	D6642-5518	IL	2029-02-11	2027-05-06	out_of_service	BLOCKED: out of service	Dispatch (blocked)
COCurtis Okafor	D2907-4471	OH	2028-12-01	2027-08-22	on_load	OK	Dispatch

Freight.Driver · resolvedfull_namecdl_numbercdl_statecdl_expirymedical_card_expirystatus

Operator plane/Impersonation/Blue Ridge Logistics/DriversCKC. Kluis
operator · supportoperator plane

Driver rosterFilter

Masked impersonation. Impersonating brokerage Blue Ridge Logistics. PII is masked (••••). Unmasking a subject needs a second-party reveal grant, is time-boxed, and is written to the tenant-readable audit log.Reason: ticket #7781: dispatch dispute · Session expires 14:52grants held: 0

Driver roster5· real tenant data, personal fields render ••••

Driver	CDL #	CDL state	CDL expiry	Status	FMCSA	Reveal
·••••	••••	IL	2027-03-14	on_load	OK	Reveal driver record Request reveal
·••••	••••	MA	2028-06-30	available	OK	Reveal driver record Request reveal
·••••	••••	OH	2027-09-02	available	BLOCKED: medical card expired	Reveal driver record Request reveal
·••••	••••	IL	2029-02-11	out_of_service	BLOCKED: out of service	Reveal driver record Request reveal
·••••	••••	OH	2028-12-01	on_load	OK	Reveal driver record Request reveal

Freight.Driver · resolvedfull_name → %Masked{}cdl_number → %Masked{}cdl_statecdl_expirystatus

Operator plane/Aggregate/PortfolioAGoperator_aggregate
token-blind actor, no orgaggregate plane

Portfolio

Token-blind aggregate plane. This actor has no pii_ column in its domain by construction — it reads a vault-excluded projection over tenant orgs. Cohorts below the k-anonymity floor are suppressed (⊘).no reveal path · k-anon suppressed

Portfolio MRR$104,800across tiers

Active tenants42org-level cohorts

Loads / total1,284across all lanes

Total gross$2.41Macross all lanes

Load volume by lane5· org-level aggregates only — no personal data

Lane	Tenants	Loads	Gross
TX->CA	14	412	$771,400
IL->GA	11	366	$648,900
FL->NY	9	297	$602,300
WA->AZ	6	209	$389,700
MT->ND	2	⊘	⊘

1 cohort below the k-anonymity floor — suppressed to prevent re-identification.

Aggregate.LoadVolumeByLane · resolvedlanetenant_countload_countgross_centspii_ columns: none

Pinch to zoom: the desktop screen, scaled to fit.

Redrawn from driftwood's own screens: DriftwoodWeb.BrokerLive, DriftwoodWeb.OperatorImpersonationLive and the framework's Samen.Web.Operator.AggregateLive, with fictional tenant data. Tenant and operator render through the same read layer and the same Samen.Api.PiiResolution resolver; only the actor's plane differs. The FMCSA badge stays readable on both, so support can work the problem without the person.

04Two planes

Close ✕

Why a separate admin app is the leak

The usual shape is an internal console with its own controllers, queries and serializers, written faster and reviewed less than the product. Same database, none of the same discipline.

Every query path is a road to plaintext. Masking in the product's render layer simply isn't present in the admin app.
Divergence is silent. The product adds a field; the admin app never learns it's sensitive.
Audit coverage doesn't transfer. A separate app that reads the row directly produces no audit record, so the tenant can't see it happened.

Building the operator plane from the same resources inverts all three: one decrypt chokepoint means one place to gate, one place to log, one place to review. And impersonation is genuinely useful for support, because the reproduction is real.

The SaaS company is itself a tenant

The operator org mounts the same universal scopes as every customer: its own help desk, its own CRM, platform billing over tenants. The plane boundary is a property of actors, not of codebases.

The cost, named. The operator plane is constrained by what the resource layer exposes. There's no escape hatch to "just run a query," by design, because that escape hatch is the thing being removed.

source · ADR-009 two-plane mountable modules · ADR-010 the operator plane · Samen.Policy.OrgScope · Samen.Api.PiiResolution

05Erasure

"Delete my data" is a `DELETE`. That isn't erasure.

The row goes; the value survives in the audit log, last night's rollup, a queued job's arguments, the CDC stream and the backup. Samen erases by destroying the subject's key: the ciphertext everywhere becomes unreadable at once, including in tiers you forgot you had.

6tiers a separate OS process walks to attest a shredded subject is unrecoverable, including backups, PITR and replay. every CI run

A positive over a finite set, not a negative over every copy that might exist
The audit chain survives: you can prove a reveal happened, not recover what it showed
A new tier that stores plaintext turns CI red instead of slipping past a migration

Why key destruction is checkable →

$ mix samen.verify.no_plaintext_pii --subject drv_8821 spawning verifier in a separate OS process committed state only · no app caches · no warm keys domain rows unreadable pii vault unreadable audit events unreadable (chain intact) rollups unreadable oban args unreadable cdc mirror unreadable backup · PITR unreadable session replay [erased] kms store key material absent ATTESTED drv_8821 is unrecoverable across all tiers

Nothing was walked, scrubbed or rewritten. One destruction, and every tier is unreadable at the same instant.

05Erasure

Close ✕

Why key destruction is checkable and row-scrubbing isn't

Row-scrubbing asks you to prove a negative over an unbounded set: no copy of the value survives in any table, rollup, job, log, replica, backup or downstream consumer, including the ones added last week. There's no finite list, so there's no test. What ships is a migration and a hope.

Key destruction asks you to prove a positive over a finite set: this key material doesn't exist, and every tier that could hold this subject's data holds only ciphertext. Both halves are enumerable, so a verifier can walk them and a sabotage can make the walk fail.

The tiers the oracle walks

17 tier checks in all, 6 of them run after a shred: database content, the CDC mirror, backups and PITR restores, the KMS attestation, session replay, and the trace-sink ingress. The others cover audit rows and the chain, the catalog, logs and telemetry, Oban jobs, rollups and vault declarations.

Why a separate OS process

An in-process check can be satisfied by the same memory that produced the data: a cached struct, a warm decrypt, a connection still holding a key. A fresh process sees only committed state, so what it attests is what actually persists.

Agent transcripts are inside the envelope

An AI conversation about a subject is subject data. Transcripts live under the subject's key with a 90-day default retention, so a shred takes them too, with no separate cleanup job to remember.

Scope, stated plainly. The full regenerate-and-shred game-day runs end to end in driftwood, the deepest vertical; the verifier itself ships with every generated app. Erasure can't reach a system samen never wrote to: a spreadsheet someone exported, or a downstream consumer that stored its own plaintext.

source · ADR-001 per-subject KMS keys · ADR-046 erasure completeness (E1–E7 built) · samen_core/lib/samen/no_plaintext_pii/tiers/

06Session replay

Watch what happened. Never what they typed.

Session replay is how support finally sees the bug. It's also usually a recording of every value a user typed. Samen's replay records references and shapes: which record, which field, how long the text was. The value never enters the recording, so no viewer can get it back.

0plaintext bytes stored. The same recording plays four ways, by who's watching, and erased subjects render [erased]. built

Per-viewer playback: the tenant admin sees their org clear, an operator sees ••••
Shred-aware: after erasure every reference resolves to [erased]; the replay rows aren't touched
Inert playback: a script-free, sandboxed iframe

What the recorder keeps →

In the product/operator/replays/:org_id/:id/settings/replays/:id

One recording of the real CRM contacts page. Four viewers. The stored bytes never change.

Operator · no grant Operator · reveal grant Tenant admin After erasure

An operator inside an impersonation session for Blue Ridge, the only way an operator can open a replay. Every referenced field resolves to ••••.

The same operator, holding a second-party-approved reveal grant on Ada Whitfield. Her row resolves through the vault; nobody else's does. A grant is per subject.

Blue Ridge's own admin, on the tenant plane: their org, in the clear. Typed text is still only a length; the recording never had it.

The same admin after Samen.Erasure.shred of Ada Whitfield. Her key is gone, so every reference to her resolves to [erased]. The replay rows were not touched.

/operator/replays/b1112d00…0001/bafe11ed…d9df/settings/replays/bafe11ed…d9df

Operator planeSettings/Replays/ContactsLive
Session replaycode unchanged since recording

ContactsLive recorded 2026-10-10 13:26:23 · 14 frames. Referenced fields show their current value, resolved for you now. Typed input is shape only.values are CURRENT · resolved on your plane now

render (17 changed) · at 22 ms · frame 3 / 14

Blue Ridge Logistics/CRM/Contacts
ContactsShow archived+ New contact

Operator · operator plane · masked

Blue Ridge Logistics · tenant plane · in the clear

Contacts5· name / email / phone via PiiResolution

Name	Email	Phone	Company	Title
·AV••••Ada Villanueva	••••ada.v@laurelfork.example	••••+1 555 0177	▒▒▒ (18)	▒▒▒ (15)
·AW••••Ada WhitfieldAda Whitfield[erased]	••••ada.whitfield@blueridge.exampleada.whitfield@blueridge.example[erased]	••••+1 555 0142+1 555 0142[erased]	▒▒▒ (20)	▒▒▒ (13)
·LH••••Lena Hartmann	••••lena@shenandoahcold.example	••••+1 555 0108	▒▒▒ (21)	▒▒▒ (5)
·MO••••Marcus Okafor	••••marcus@cumberlandmills.example	••••+1 555 0119	▒▒▒ (16)	▒▒▒ (13)
·PR••••Priya Raman	••••priya.raman@blueridge.example	••••+1 555 0163	▒▒▒ (20)	▒▒▒ (10)

References 1515 •••• masked12 •••• masked3 shown (current)15 shown (current)12 shown (current)3 erased (shredded)

What Postgres holdsreplay_frame.rpf_payloadsame bytes · four viewers

seq 3 · kind render · 7,537 bytessha256 8ff7d8f4f827…

// one contact row, as stored

{"display_name": {"$redacted": {"kind": "free_text", "label": null, "length": 13}},"full_name": {"$ref": {"pk": "efb44c49-…-b4ae49c18be9", "resource": "Samen.WebTest.Crm.Person", "attribute": "full_name"}},"emails": {"$ref": {"pk": "efb44c49-…", "attribute": "emails"}},"phones": {"$ref": {"pk": "efb44c49-…", "attribute": "phones"}},"job_title": {"$redacted": {"kind": "free_text", "length": 13}}}

// frame 8 · event validate_new: the form being typed

{"$shape": {"fields": [{"key": "form", "fields": [{"key": "display_name", "class": "name", "length": 11},{"key": "full_name", "fields": [{"key": "first", "length": 4}, {"key": "last", "length": 6}]},{"key": "job_title", "class": "name", "length": 12}]}]}}

Switch the viewer: nothing on this side changes, not one byte, not after the erasure either. $ref is a pointer the player resolves for whoever is watching; $redacted and $shape keep a kind and a length, never the text.

Timeline · 14 frames01 mount02 navigate03 render04 event05 render06 event07 render08 event09 render10 event11 render12 event13 render14 exit

Pinch to zoom: the desktop screen, scaled to fit.

Real data, redrawn: one session recorded by the ADR-052 recorder over the real Samen.Web.CRM.ContactsLive (fictional Blue Ridge contacts) and replayed by the real player for each viewer. Labels, payloads, cell text and reference outcomes are exported by scripts/landing/replay_demo_export_test.exs; the JSON is abridged (ids shortened, some keys dropped), never altered. The player itself shows the recorded screen in a script-free sandboxed iframe.

06Replay

Close ✕

A replay that records by value keeps all of it. This one keeps the shape.

A conventional recorder stores the DOM and every input. Masking it after the fact means trusting every viewer, export and retention job to apply the same rule. Samen stores references, so the rule is applied at playback by the viewer's own scope, the same way every other page is rendered.

What a frame holds

Kept	Never kept
Which record (`samen:` ref)	Field values
Which field was touched	Typed text
Text length, timing, clicks	Rendered HTML of a form

Who may watch

The tenant's own admin, on the tenant plane, sees their org clear. An operator sees masked values. A frame the current code can't render (a removed view, a form the recorder never stored) shows an honest placeholder card instead of a guess.

Proof

Two verifier tiers cover it: :replay checks recordings carry no plaintext; :post_shred_replay runs inside the driftwood crypto-shred game-day. Sabotages 421–494 cover capture, playback, authorization and the shred path.

Credit. Inspired by phoenix_replay by Danila Poyarkov (MIT). We took its capture shape, not its code or its storage model, and rebuilt it around references.

source · ADR-052 (all phases built) · docs/runbooks/session-replay.md · mix samen.verify.replay_schema

07Cross-plane chat

One thread. Two truths.

Your support team and your customer talk in one realtime thread. Paste any object id and it unfurls into a live card, clear to the customer and •••• to support, resolved per viewer through the same two gates every page uses.

1renderer, two actors. No if operator branch exists in the card. built

The broadcast carries an id, never a body: every subscriber re-reads under its own actor
Any catalogued object unfurls the day it's catalogued, with zero card code
Identity masked by default; disclosing it is an opt-in, recorded act

How one message renders twice →

send · Rosa Medina · tenant

Persist the message through Ash. Its body goes to the vault.

broadcast

pubsub · samen:chat:<thread_id>

{:chat_message, %{message_id, sender_party, refs}}

no body field exists on the wire

each subscriber re-reads under its own scope

tenant

OrgScopeown orgPiiResolutiontenant

Rosa MedinaConfirmed. Here is the contact and the driver on BR-4471.

operator

OrgScopevia impersonationPiiResolutionoperator

•••• blueridge-dispatch••••

In the productone thread, one message, one pair of refs, rendered per viewer's plane

Paste an object id and it unfurls into a live card: clear on one side, •••• on the other.

Blue Ridge · tenant /chat/:id

#Rate confirmation for load BR-4471cross-plane thread · owned by the tenant orgtenant

SaaS support driftwood-desk · 10:24

Confirming the rate on BR-4471. Can you send the shipper contact and the assigned driver?

Rosa Medina blueridge-dispatch · 10:26

Confirmed. Here is the contact and the driver on BR-4471: samen:crm.person:0f00…aa samen:freight.driver:0f00…cc

PAda Whitfieldsamen:crm.personcustomer

TitleShipping manager

Emailada.whitfield@blueridge.example

Phone+1 555 0142

your org · resolved clear (tenant plane)

DMarcus Valesamen:freight.driver · Driveron load

CDLD4471-8820

CDL stateIL

ELDsamsara

driftwood's own card for freight.driver · clear

2 online · driftwood-desk is typing…

Driftwood Ops · operator /operator/desk-chat/:id

#Rate confirmation for load BR-4471the same thread · reached through impersonationoperator · masked

•••• blueridge-dispatch · 10:26

••••

P••••samen:crm.personcustomer

TitleShipping manager

Email••••

Phone••••

tenant's customer · identity •••• · non-PII clear

D••••samen:freight.driver · Driveron load

CDL••••

CDL stateIL

ELDsamsara

the same card · state, ELD, status still readable

2 online · blueridge-dispatch shown as a handle only

Pinch to zoom: the desktop screen, scaled to fit.

Redrawn from Samen.Web.Chat.ThreadLive, mounted twice by driftwood: samen_chat_routes on the tenant plane and again at /operator/desk-chat with plane: :operator. The person card is the framework's; the driver card is DriftwoodWeb.Chat.DriverCard, registered as data on the mount. Message bodies are vaulted too, so the operator reads the tenant's words as ••••. Proven by chat_unfurl_masking_test.exs: the live operator DOM is scanned for leaks.

07Chat

Close ✕

Why one message can render two truths without a second code path

The naive build is two renderers: the tenant view, and an operator view that redacts. The redacting one is newer and less reviewed, and it drifts the first time someone adds a field.

Two mechanisms, both reused

The PubSub envelope carries an id, never a body. Every subscriber re-reads the message through its own scope. A masked session can't receive plaintext by subscribing, because the topic never carried any.
The unfurl resolver composes two kernel gates that didn't change: OrgScope, then PiiResolution. Nothing in chat reads a column directly, unwraps %Masked{} or calls the vault.

A framework capability, not a chat trick

Samen.Web.ObjectRef takes a ref and an actor and returns a card. Chat is its first consumer: a CRM page can unfurl a related object, an audit entry its subject, a notification its target. Declare a new field as PII and it masks in every card on the next render, because the card was never the thing deciding.

Crossing the plane boundary

The thread belongs to the tenant org. Support reaches it through the impersonation grant, so OrgScope is satisfied for both parties with no new policy. An operator session targeting a different org sees the thread as zero rows.

source · ADR-012 cross-plane chat + object unfurl · chat_unfurl_masking_test.exs (live operator DOM scanned: 0 leaks)

08The AI agent

The agent proposes. A human approves. The write runs as the human.

An agent near customer data is a governance problem before it's a feature. So samen's agent loop starts at authority: the agent holds no credential that can write. A write is a proposal parked for a person; on approval it executes under that person's actor, recorded as agent-originated.

0vault values, plaintext or token, that reach a model. Agent runs are masked-only on every plane. built

Durable, multi-step tool use with fail-honest budgets: 8 turns, 12 tool calls, 10 minutes by default
Grounded in the machine catalog, not guessed field names
mix samen.gen.agent scaffolds a new agent with its own masking proof

Why "runs as the approver" is the whole design →

1 · the agentwrite credential: none

search_recordsread · personal fields come back ••••fetch_recordread · masked like any other actorassign_record_ownerwrite · calling it executes nothing

proposes

2 · the approval · ai_agent_writerun parked

Records the tool, the turn, the arg key names and a sha256 digest, never an argument value. A person who isn't the requester decides.

no decision in 24h → withdrawn, nothing executed

approve

3 · the write · runs as the approver

Executes once, inside the decision, bound to that digest. actor is the approver; requested_by is the AI principal, which holds no write authority anywhere.

the blast radius is what the approver could do by hand

In the product/ai/agents/:ida support-triage run, parked at the human gate

"Why is load BR-4471 late, and who should own it?" Two reads, one proposal, and a person decides.

Blue Ridge Logistics/AI/Agent runsRMRosa Medina
dispatchertenant plane

awaiting_approvaldriftwood.support_triageturn 3/8 · tool calls 3/12 · tokens 2,914/388← All runs

Awaiting your decisionThe agent PROPOSED this write. It has not run, and it cannot run without a decision from a person who is not the requester (ADR-043 §6.2).

tool:: assign_record_owner
turn:: 3
arg keys:: id, resource, user_id
args digest:: 9c41d07be2…e07a

Only key NAMES and a digest are recorded on the approval, never argument values (INV-1). Approving executes the write as you, once, inside the decision; the digest binds it to exactly this proposal. Deadline: 2026-10-14 10:31Z.

Approve + executeReject

Transcript

Vault-routed. An agent run is masked-only toward the model on every plane (ADR-047 §4.4); this panel resolves on YOUR plane.

Why is load BR-4471 late, and who should own it?

search_records "BR-4471" → 3 hits
fetch_record support.agent → full_name •••• · email ••••
assign_record_owner proposed → waiting for a person

Turns

#	Status	Tool	Arg keys	Tokens	Provider
1	done	search_records	limit, query	806/94	scripted SIMULATED — not a real model
2	done	fetch_record	id, resource	1,031/151	scripted SIMULATED — not a real model
3	proposed	assign_record_owner	id, resource, user_id	1,077/143	scripted SIMULATED — not a real model

Pinch to zoom: the desktop screen, scaled to fit.

Redrawn from Samen.Web.AI.AgentLive, which driftwood inherits through one samen_ai_routes call. The agent is Driftwood.Support.TriageAgent: a name, a goal prompt and three tool kinds, nothing else. Driftwood configures no model provider, so its runs are honest about it: the deterministic Scripted provider, with a SIMULATED badge on every turn. Built and gated: ADR-047 batches A1–A7 landed.

08The AI agent

Close ✕

Why "runs as the approver" is the whole design

Approval workflows usually get this backwards: the agent asks, a human clicks yes, and the write executes under the agent's identity because that process already holds a connection. That launders the agent's permissions through a click. The human approved one write; the credential that performed it can perform every other write, and the audit trail names a service account.

Authority is bound at approval, not before. There's no standing agent credential to escalate, steal or forget to rotate.
The blast radius is the approver's own permissions. An agent can't propose its way past what its approver could do by hand.
The write is attributable to a person, and ai_agent_write keeps its origin distinguishable from ordinary traffic.

The no-PII-egress chokepoint

Every prompt, tool definition, tool argument and tool result passes one chokepoint before it reaches a provider. No vault-routed value, neither plaintext nor its vt_ token, may cross it. Tool results re-enter the conversation masked. A live reveal grant does not admit plaintext into an agent run: runs persist, and grants never apply to persisted egress.

The ratified decisions

Decision	Taken
Autonomous writes	Never: every mutating tool is propose-then-approve
Plaintext in runs	Never: masked-only on every plane
Budgets	8 turns · 12 tool calls · 60k in / 8k out tokens · 600 s; exhaustion is fail-honest, never a partial answer
Transcript retention	90 days, inside the subject's erasure envelope
Token streaming	Deferred: it would be a second egress surface

Also on the AI plane

A keyless kernel: CI runs a deterministic fake provider, and live providers ship as packages (samen_anthropic). There are pgvector embeddings, plus MCP over HTTP+SSE with per-operator tokens.

source · ADR-043 AI plane, INV-7 no-PII-egress · ADR-047 agent loop (A1–A7 built, zero new dependencies) · verifiers: ai_prompt_masking · agent_coverage · tool_surface · tool_actor_identity

Act III · The rest of the 80%

Everything else a B2B SaaS needs, built on the same decision.

Table stakes are where products quietly leak: the export that writes every column, the search index that holds names, the vendor SDK in the kernel. Here each one inherits the masking default instead of re-deciding it.

09Working surfaces

The table stakes, without the leaks.

CRM, billing, a support desk, work tracking, automation, files, search, CSV, settings, notifications, flags, analytics. Each ships as a scope blueprint a product mounts in one call, and each renders through the same masking default as everything else.

18scope blueprints plus 19 route macros a vertical mounts at roughly zero authored lines. built

Search over a non-PII index: ⌘K finds the record without the index ever holding the name
Files quarantined by default: promoted only after a clean scan
Automation with approvals: workflows compile to Reactor; approvals carry the distinct-party CHECK

Every surface and its twist →

09Surfaces

Close ✕

Every surface, and the twist that keeps it honest

Surface	The governed part
CRM	Contacts, companies, activity timeline, sequences, prospecting; PII through the vault
Support desk	The SaaS's own help desk runs on the same scope its tenants use
Work	One canonical Project/Task/Subtask tree, archivable
Automation	Workflows, runs, reminders, escalations; compiled to Reactor
Approvals	A state machine with a distinct-party `CHECK`, reused by reveal and the agent
Search	`Search.query/2` over a non-PII tsvector, org-scoped, ⌘K in the UI
CSV	Export is a masking surface (omission); import goes through the write chokepoint
Files	One upload chokepoint mints storage keys; fresh files are quarantined
Settings	Profile self-edit through the vault, API-key minting, sessions
Notifications	Masking-aware rendering, an inbox, one send chokepoint
Feature flags	Kernel evaluation, deterministic bucketing, non-PII keys, fail-safe kill switch
Product analytics	A governed event resource that refuses PII at capture
Marketing · outreach · calendar · docs · CMS	Mountable scopes on the same primitives

Shaped per customer, without bending the guarantees

A malleability ladder in order of blast radius: config rows, then JSONB custom fields validated at write, then tenant-defined objects, then builder code. Types are declared, not stringly (Money, Percent, Score, Duration, Priority, URL, Email, Phone, Address), and the vault path re-runs each type's cast before tokenizing.

Mobile, once

One kit-level stylesheet and one shell component made every vertical usable on a phone at once, with no per-app CSS.

source · ADR-011 CRM · ADR-016 kit + notifications · ADR-020 flags · ADR-021 analytics · ADR-026 files · ADR-027 search · ADR-028 CSV · ADR-029 settings · ADR-030 responsive · ADR-039 automation · ADR-040 lifecycle · ADR-041 work

10Billing & email

Delete every vendor package. The kernel still passes.

Payments and email are where frameworks quietly marry a vendor: a webhook signature here, a customer id there, until leaving costs a quarter. Samen's kernel names zero Stripe strings. Adapters live in sibling packages, and removing all of them leaves samen_core and samen_web green.

0card-number columns that can compile. Payment methods are hosted-only, and a verifier refuses any PAN-shaped column. built

Three email vendors that disagree: Basic-Auth, SNS-RSA and Svix-HMAC behind one conformance suite
Webhooks are hints, not facts: verify, fetch current state, apply idempotently, survive reordering
Usage metering as an insert-only ledger, with quotas summed from it

What the keyless lane proves →

10Billing & email

Close ✕

The seams are proven. The wires are yours.

A vendor boundary you can only argue about isn't a boundary. One you can falsify in a command is: remove the four adapter packages and the kernel stays green; if a Stripe string ever leaks into the kernel, that check turns red.

Billing, the unglamorous correct part

Hosted checkout and hosted-only payment methods: no column for a card number to land in
Webhook signatures fail closed; a verified event triggers a fetch of current state
Idempotent, out-of-order safe; anything unappliable lands in a dead-letter queue a human can see
Invoice and tax mirroring, dunning, a subscription-change ledger for MRR movements
Metered usage: an insert-only event ledger behind one chokepoint, tallies derived from it, quotas checked against it

Email: one behaviour, three vendors that disagree

A seam is only proven by vendors that disagree at the most awkward layer, inbound webhook authentication. Postmark uses Basic-Auth, SES uses SNS with RSA certificate chains, and Resend uses Svix HMAC with its own replay window. All three pass one shared, non-vacuous conformance suite, and a sabotage proves the suite can fail.

Honest scope: the keyless lane. Dispatch is proven against hermetic fakes and injected-transport cassettes. No host wires a live provider, and every generated app boots with billing and email unconfigured and says so, a :not_configured state rather than a fake success. The live lanes are documented and runnable by hand; they aren't in CI, so nothing here rests on them.

source · ADR-038 adapter architecture · ADR-038-A billing persistence · ADR-051 usage metering (P1–P3 built) · ADR-014 fail-honest delivery · mix samen.verify.no_pan_columns

11Portfolio cockpit

Run ten products from one seat.

Samen exists to launch many products, so the operator needs one view across them: which app is healthy, which tenant is churning, which flag is rolled out where. The cockpit reads every product over a token-blind report wire, so the portfolio view never becomes the leak.

1notion of "up". The public status page is a projection of the fleet's own health, not a second opinion. built

Tenant names masked by default, unmasked per role down to account level: a salesperson sees their accounts
Fleet directives push flags across products; an unreachable app degrades honestly, never a fake "applied"
Explainable health scores and an MRR-movement ledger per tenant

How the cockpit stays token-blind →

11Cockpit

Close ✕

One portfolio, still token-blind

A cross-product dashboard is where a careful company's data model goes to die: it wants everything from everywhere. Samen's cockpit gets a report from each product, never a query into it.

Piece	What it does
Fleet registry	Manual registration for any app, plus opt-in self-registration and heartbeat for generated apps, with a signed heartbeat credential
Report wire	Token-blind by construction, verified by `fleet_wire`; dead-man staleness when an app goes quiet
Operator identity	One operator across products; tenant identity masked by default, unmasked per role and account assignment
Fleet directives	Push a flag to many products; an app that can't confirm shows observability without the flag, never a fake "applied"
Public status page	Opt-in per app, rate-limited, a lossy projection of the same status the cockpit shows
Health score	Composite and explainable, computed over already-assembled operational data, not a new PII surface
Observability	Wide events with id-shape checks, metric labels verified, the telemetry plane on by default

source · ADR-044 portfolio cockpit · ADR-050 status page · ADR-017 subscription movements · ADR-019 health score · ADR-052 observability

Act IV · Proof

Every claim above is attached to something that can go red.

A guarantee nobody has tried to break is a decoration. So samen tries, on every pull request, and keeps the attempts.

12Sabotage & mutation

A test that can't fail is a bug.

Each guarantee ships with a sabotage: a committed patch that breaks exactly that behaviour. The harness applies it, demands that the named tests fail (not just that something breaks), reverts, and checks the tree is restored byte for byte. Then a mutation gate asks the converse: what break did nobody think to sabotage?

604committed sabotages, replayed on every PR where they touch the diff and in full every night. counted from the tree

3,960 mutants across 228 targets, enumerated from the AST, each run against only its owning tests
A survivor fails the build until a test kills it or a ledger row proves it can't matter
25 verifiers check structure the tests can't: no PII columns, catalog parity, fleet wire…

The sabotage loop, step by step →Read the patches ↗

$ scripts/sabotage.sh --range 187-187187-pp13-reveal-approver-distinct-party-…patch APP samen_core · TEST_FILES test/reveal_approver_test.exs MUST_FAIL "a self-approval is refused with :self_approval" 1 preflight tree clean, header linted2 apply disable both policy-layer self-approval checks3 run ✗ a self-approval is refused with :self_approval4 revert git apply -R5 restore sha-256 byte-exact ✓ FLIPPED the named test went red, then green again $ ./scripts/mutate.sh --file samen_core/lib/samen/approvals/gate.ex EQ · REL · BOOLOP · BOOLLIT mutants, owning tests onlyMUTATION GATE: ALL PASSED

Sabotage 187 is real: the database CHECK still backstops the write, but the clean policy refusal degrades, and the named test catches it. Both layers are load-bearing.

12Proof

Close ✕

Proving the proofs

A test suite can be large and still prove nothing. The sabotage count is the number that carries weight, because each one is a demonstration that a specific test notices a specific break.

A sabotage, mechanically

The patch carries a header: the app, the test files, and the literal names of the tests that must fail
Apply it to a clean tree
Run the named tests: they must fail, by name; "something else broke" doesn't count
Revert, then check every touched file's SHA-256 against the original
New sabotages must anchor: they have to attack code the change actually added, or a double sweep rejects them

Agents add sabotages with scripts/sabotage new, which refuses one that can't flip, breaks the build instead of a test, or names its test with string interpolation the harness can't find.

The mutation gate

Sabotages prove the guarantees someone thought to claim. The mutation gate enumerates four operator families (equality, relational, boolean operators, boolean literals) from the AST and splices each mutant at an exact line and column. A watch-list of 12 chokepoint modules (166 mutants) runs on PRs; the full corpus (3,960 mutants) runs as a soak. A compiler refusal isn't a kill; only a named test failure is.

The verifiers

25 mix samen.verify.* tasks check what tests can't express, for example: no plaintext PII in any tier, no PII or card-number columns, catalog and vault-declaration parity, same-org foreign keys, the API contract, the AI prompt masking and agent coverage, the fleet wire, the replay schema.

source · ADR-049 mutation gate · docs/ci.md · scripts/sabotage.sh · scripts/mutate.sh

13CI for agents

Verdicts, not logs.

This codebase is written by AI agents, so its CI is built for them: cheap, fast and mechanical. quick during a round, pr before a pull request, full nightly. Every call fits a single tool call, ends in one verdict line, and resumes where it stopped.

0.4seconds for quick when nothing changed, because every step is cached by the content it reads. A failure is never cached. measured

A flaky test still fails the run: fix the flake, don't retry it green
Mirrored on GitHub Actions: the PR check verifies every step ran once, on this commit
The old ci.sh took about 13 minutes and never fit one tool call; agents cut it up by hand

The measured before and after →docs/ci.md ↗

$ scripts/ci quick CACHED dialyzer_samen_core PASS samen_core 151.2sCI(quick): PASS 19/19 in 197.5s — NOT PR-READY — run: scripts/ci pr $ scripts/ci pr CI(pr): budget — next step sabotage_changed[3/5] would overrunCI(pr): INCOMPLETE 49/52 — continue: scripts/ci resume $ scripts/ci resume PASS sabotage_changed[4/5] 226.6s PASS sabotage_changed[5/5] 211.7sCI(pr): PASS 52/52 in 212.3s — PR-READY

Lines from real runs on this repo, trimmed. A red step prints a digest and its log path; the verdict also lands in _ci/last.json.

13CI for agents

Close ✕

Measured: a one-line kernel change

	Before	Now
During a round	`ci-fast.sh`, 174–195 s every time	`quick`, ~200 s in one call; 0.4 s when nothing changed
Before a PR	`ci.sh`, ~13 min, hand-cut into 3+ calls	`pr`, 708 s over 2 calls warm; 0.6 s unchanged
Full sabotage corpus	~79 min serial (about 4 h hand-chunked)	51 min in parallel lanes, or nightly on Actions
PR check on GitHub	none	9–30 min, sharded into 18 jobs

Not everything got faster. A cold run with nothing cached isn't faster than before. The wins are the cache, every call fitting the budget, and verdicts instead of logs.

What can't be weakened

A failure evicts any cached pass for that step
A flaky test is reported FLAKY and still fails the run
quick never claims PR-ready
The GitHub aggregate check verifies every step ran exactly once, on this commit's tree, against this base
Counts in the docs are generated; drift fails quick

source · ADR-053 CI as an agent tool · docs/ci.md · ci/steps.conf

—Scope, stated on purpose

What this is not, stated as precisely as what it is.

A project that can draw its own boundary is one whose other claims you can price. Each limit below is written in the repo in the same words. When a reviewer finds a claim that outruns its evidence, the fix is a commit, and the retraction stays visible.

01 · Keyless lane

No live vendor is wired in CI.

Billing and email are proven against hermetic fakes and recorded transports through a real conformance suite, never a real account. Generated apps boot with both unconfigured and say so. The seams are proven; the wires are yours.

02 · Support access

Support can see PII.

Through a grant a second person approved, that expires on its own and that the tenant can audit. "Support never sees plaintext" was once on this page; it was false by construction and was retired.

03 · Verticals

The verticals are proof, not product.

driftwood (freight), pawchart (veterinary) and demo exist so the substrate must survive unrelated domains. They aren't for sale. If a vertical does something clever, that's a bug in the kernel.

04 · Leverage

188 lines is a mount number, not an app size.

pawchart mounts framework surfaces in about 188 authored lines; pawchart itself is about 3,900. An earlier page conflated the two, and the overclaim was corrected rather than reworded.

05 · Residency & distribution

US-only, and not on Hex yet.

One Postgres per host, no per-tenant region selection. The framework ships as path dependencies inside this monorepo; publishing waits on a stated trigger.

06 · Erasure's edge

Erasure can't reach what samen never wrote.

A spreadsheet someone exported, or a downstream system that stored its own plaintext, is outside the boundary. The page won't pretend otherwise.

—Two ways in

Run it in ten minutes, or read it for an afternoon.

Path A · Use it

Generate an app and make it prove itself.

You need Elixir 1.20 on OTP 29 and a local PostgreSQL with pgvector. No Docker, no API keys, no accounts.

$ git clone https://github.com/ckluis/samen && cd samen/samen_core$ mix samen.gen.app --module Harbor --prefix hb --abbrev hrb$ cd ../harbor && MIX_ENV=test bash ci.sh19/19 steps ALL PASSED # zero hand-edits

If the generated app needs a fix from you to go green, the generator is broken, not your setup.

Path B · Take the ideas

For readers who'll never run it.

Most of what's interesting here transfers to a stack that has nothing to do with Elixir.

The decisions, with their losers 54 ADRs ↗ Claim → evidence map claim-evidence.md ↗ The compliance story for an auditor ↗ Zero to first feature getting-started.md ↗ How to prove a test can fail 604 patches ↗ CI an agent can afford docs/ci.md ↗

Every B2B product rebuilds the same 80%. And the same leak with it.

One command, a running product

Customer data that defaults to safe

Everything else a B2B SaaS needs

A test that cannot fail is a bug

The proof that a substrate is real is generative.

One command. A product you can boot.

Seven features that only work because both planes share one core.

•••• isn't a redaction. It's the value.

Support can see PII. Only with a second person's yes.

Your admin tool is the biggest leak in the company. Unless it's the same app.

"Delete my data" is a DELETE. That isn't erasure.

Watch what happened. Never what they typed.

One thread. Two truths.

The agent proposes. A human approves. The write runs as the human.

Everything else a B2B SaaS needs, built on the same decision.

The table stakes, without the leaks.

Delete every vendor package. The kernel still passes.

Run ten products from one seat.

Every claim above is attached to something that can go red.

A test that can't fail is a bug.

Verdicts, not logs.

What this is not, stated as precisely as what it is.

No live vendor is wired in CI.

Support can see PII.

The verticals are proof, not product.

188 lines is a mount number, not an app size.

US-only, and not on Hex yet.

Erasure can't reach what samen never wrote.

Run it in ten minutes, or read it for an afternoon.

Generate an app and make it prove itself.

For readers who'll never run it.

"Delete my data" is a `DELETE`. That isn't erasure.