🤖 Tenancy: what one instance is, and what that buys

The first decision for any CARLOS app, before trust model, shape, hosting or identity (decisions.md). Every other benefit on carlosframework.com follows from it: isolation, hibernation, residency, erasure, taking the data home. Settle it on day one and write it down as a tenancy declaration (§6). Changing it later is a data migration across every instance, not an edit.

Status as of 2026-10-18. Carloku serves platform v0.28.0; rastrillo is v0.28.0. Where a piece below is designed but not shipped, it says so.

1. The boundary: what is one instance?

The instance boundary is the app's choice (the family doctrine). No unit is the default. The gallery at carlosframework.com/apps runs all of these, and all of them are correct for their app:

| One instance is… | Person : instance | Apps that do it | |---|---|---| | a person | 1 : 1 | Kass (a training log; a coach is a member of the client's instance), Slopbox (one account), Dineraya (a buyer) | | a conversation or space | 1 : N | Eleven (one chat) | | a mailbox | 1 : 1 | Keymail | | a team | N : 1 | Oficina (one per team, per app: docs, sheets), Correomona, an internal finance ledger | | a customer organisation | N : 1 | Tito (one per organiser account, plus a sandbox instance each), Dineraya (a merchant), Jelly (designed: one per signup) | | a community | N : N | Woodstar (a relay: founder plus invited members) | | a repository | N : N | amadan (one per repo; the hub holds only names and membership) | | a connection | 1 : 1 | a payments app with one instance per bank connection | | the whole app | N : 1 | Movement (one sign-up list); a rastrillo app out of the box | | nothing: no user data | none | static sites (carlosframework.com, carloku.com) |

Most products run more than one pattern: a central app plus per-unit instances (Tito, amadan, Oficina, Slopbox, Eleven), or one binary in several roles (Dineraya: buyer, merchant, and one shared dispatcher).

Choosing the unit. Ask, in order:

1. Whose data is it? The unit is the smallest group that owns data together and would be harmed if it leaked to the next group.
2. What should fail together? A panic or a runaway query takes down one instance. Choose the unit whose outage you can explain to one customer.
3. Who leaves together? A unit's data is its own database and its own objects, so exporting it is copying them and erasing it is a bounded list (the platform keeps a deleted instance's data until you remove it). Pick the unit a customer would ask to export, delete or move to their own boxes.
4. What crosses units? Sharing is membership, never copying: a person joins someone else's instance (a coach in a client's log, a member in a team). If a feature needs to query across units (reporting, search across all customers), the unit is too small or that feature belongs in its own app. A central app answers "what might I have access to", never "may I have this". A view across tenants (a vendor's dashboard, a person's search over their own spaces) has its own pattern: §2 "Seeing across tenants".
5. Does it idle? Instances that sit idle hibernate and cost nothing. Small units that are used in bursts get the most from this.

The anti-pattern: tenancy by WHERE clause. One instance, a tenant_id column, every customer in one file. It gives up isolation, per-unit erasure, per-unit residency and per-unit hibernation at once, and one missed WHERE exposes everyone. On CARLOS, isolation is a process and a file. Use one shared instance only when the whole app really is one unit (one team, one list).

2. How people reach their instance

Four recommended models, from the user-models design (approved 2026-09-28). They are recommendations, not rules: if none fits, choose your own and record why.

| | Model | You sign in to… | Recommended when | Runs it today | |---|---|---|---|---| | A | One instance, in-app accounts | the app itself | one team, one household, one list, a personal tool | the internal finance ledger, Movement, the rastrillo default | | B | Simple home | your instance | each person or team owns a space that stands alone | Oficina, Kass (in-process), the bank-connection app | | C | Hub | a whole product | people belong to several spaces and move between them all day | Tito (subdomains and a proxy), amadan (path routes) | | D | Blind home | your instances, server-blind | end-to-end encrypted apps where the centre must hold nothing readable | Eleven's home, Slopbox's home; rastrillo/vault is the client |

• A is the least machinery: rastrillo auth or password, owner scoping, and idear for roles and invitations. Its cost is that one instance's blast radius is everyone in it, and it never grows into a product with many independent customers.
• B is a small central app where you sign in, see your instances, add one, and open one. Each instance has its own hostname and its own sessions, and still accepts ordinary sign-in on its own origin, so it works if the home is down. The home hands you in with a signed, single-use assertion (rastrillo assertion, issuer the home, audience the instance), posted in a form, never in a URL. Smallest leak profile of the recommended models: the home knows who signed up and which instances they own, nothing inside any of them. Cost: no shared chrome; moving between spaces goes through the home.
• C puts the product on one domain and each tenant under a path (example.com/acme) via the platform's path routes. One origin, one session, one switcher; every tenant still its own process and file. Costs: one origin is one browser security boundary, so use C only when every tenant runs the app's own code (a product whose tenants publish raw HTML their customers wrote needs B's per-tenant hostnames). The hub's session-signing key is the product's crown jewel. Today a path target must live on the same box as the hostname, so a path-routed product is one box big. How it fits together: the tenant receives /acme/... unchanged, so the tenant app serves everything (routes, assets, redirects, form actions) under its base path, and its own direct hostname redirects to the product path. Because hub and tenants share one origin, there is one session: the hub mints a short-lived signed cookie (15 minutes, with a per-user epoch so "sign out everywhere" works), and tenants hold the hub's public key (carlos env set) and verify it on every request, never minting their own. Ordinary per-tenant rastrillo sessions do not work under model C: every tenant would set the same cookie name on the same origin and sign the others out. The hub delivers roster changes to the instance first, with a signed request, then records its directory copy.
• D is B's shape for server-blind apps: the home holds credential public keys and one sealed blob per person and can read neither.

Central apps are stateless (ruled 2026-09-27, a foundational CARLOS principle). A home, hub, directory or sign-in service keeps no database: its records are objects in its own store (carlos store create), created with If-None-Match: * and updated with If-Match, at keys it can compute (users/<uid>.json, tenants/<slug>.json). Nothing to replicate, restore or migrate, and it moves between boxes with nothing to copy. Anything relational (reporting, search) belongs in an instance.

Safety invariants, whichever model:

1. The provisioning credential (carlos services create --role instance --app <tenant-app>) lives on the central app, never on the tenant app. It is app-wide today: it can also delete any sibling instance. Publish that as a leak until the platform ships a create-only role. The same goes for any instance-role token (CARLOS_INSTANCE_TOKEN): never put one in the tenant app's secrets, whatever the convenience.
2. An instance decides access from its own roster. A signature proves who, never what.
3. Handoff tokens never ride in URLs, and the receiver enforces single use.
4. Model C only where every tenant runs the app's own code.
5. Every model publishes its leak profile (§3).

What is real today, and what is not (2026-10-15):

| Piece | State | |---|---| | Instances API, instance service role, path routes, assertion, vault, idear, stores | Shipped. Use them. platform.md "Provisioning instances from your own app" | | Create-only, quota-bounded provisioning role | Not built (platform #185). Use the instance role and name the leak | | Path targets on another box | Not built (platform #186). Model C is one box big | | rastrillo objrec, stateless auth store, signed-cookie sessions, provision, base-path serving, rastrillo new --model home\|hub | Not released (objrec is on a branch). Hand-build on the patterns above, and don't claim the framework does it |

Seeing across tenants

A vendor wants totals across every customer; a person wants to search every space they belong to. Tito runs both with one rule: the centre reports only what it owns or witnesses. It never opens a tenant's database. Four ways data legitimately crosses the boundary, in order of preference:

1. Witnessed facts. Make the number a fact the vendor owns (a fee, a charge, usage) and record it where the vendor already sits on the path: the proxy, payment egress, mail egress, a payment provider's webhook. Tito's staff console gets collections, request timings and capacity this way, from facts its router, payment relay and the payment provider saw for themselves. Fees owed are partly computed from facts instances report, which is step 2.
2. Pushed facts through an outbox. Where only the instance knows, it writes a fixed-shape record (a fee accrual, a ticket count) to an outbox table in the same transaction as the work, and a sender delivers it to the central side, retrying until accepted. The instance is usually asleep, so send at the end of the request that did the work, and let anything undelivered go on the next wake or a daily carlos schedule tick (a tighter schedule keeps the instance awake, and that is billed). Retries mean duplicates, so each record carries a stable id; the receiver dedupes on it in the same transaction as the ledger write, acknowledges only after commit, and refuses a different payload under an id it already holds (Tito does all four for fees). The record's shape is declared residue, published like any other. The receiver files each record under the instance that sent it, so an instance can only speak for itself. Short self-descriptions (name, region, counts) can also ride on responses the centre already proxies.
3. Browser fan-out for a person's own view. A search or switcher across someone's spaces asks each instance they are a member of, from the browser. Every instance answers as it would any other request from that person: membership, then their role's capabilities and any narrower scope (Tito filters by the events and series a member may see), so a result list never shows what the person could not open. No central copy; nothing widens the set beyond real memberships. Tito does this on one origin (model C), where the one session already reaches every tenant. Across per-tenant hostnames (model B) each request needs that origin's own session, so there it is usually a link per space instead. Every request can wake a sleeping instance, so Tito answers typing from a cache the browser built from each instance's own answers (refreshed when that account's digest changes), and asks the instances live only when the person asks for more results, at most four at a time.
4. One tenant at a time, with consent. Support access is granted from inside the tenant (in Tito, by a member, never above their own role, and capped at admin), time-limited, and logged before the first read, failing closed if the log write fails. Never aggregation.

Where the vendor's records live. Not in the router, hub or home. A back office app with its own instance and database holds the vendor's ledger, partners and statements, receives the outbox, takes signed identity like any tenant instance, and asks the central app for anything else through a narrow API (list accounts, create one). Tito's console holds these in its router today; its proposed split moves them into a back office app of this shape.

Not allowed: a central app or reporting job opening tenant databases (carlos db pull across every instance is a backup of everyone, not a report); copying tenant content (buyers, messages, documents) into a central store; a tenant_id warehouse.

The sender problem (2026-10-16). Step 2 is only as good as the receiver's knowledge of which instance sent a record. It must derive that from a credential bound to the sending instance and verified by the receiver, never from a name the sender supplies, and never from the app-wide instance token, which every holder can present for any sibling. Tito today trusts box-local sockets plus a header the instance sets, so a compromised instance could report as a sibling. The family has no ready-made per-instance sender credential on Carloku: platform tokens are app-wide (#155, not built), and even scoped platform tokens would not by themselves authenticate an instance to your receiver. Until a pattern exists, cross-check pushed facts against what you witnessed where you can (a fee against the provider's webhook), keep pushed records to facts a lying instance gains little from, and name the gap as a leak.

3. What the host can see: the trust class

Tenancy says where the walls are; the trust class says what a host can read inside them. Pick a class per workload, not per product: an end-to-end encrypted app with an automation sidecar is two answers (Eleven and Kass: instance A2, agent sidecar C). Classes order S ≤ A < B < C; the A variants are flavours, not grades.

| Class | The host holds | Examples | |---|---|---| | S stateless | no user data at all | static sites; a central app holding only public keys can be S plus declared residue (Dineraya's dispatcher) | | A1 host-blind | ciphertext; only transport shape leaks (who connects when, sizes, timing) | Slopbox (padded blobs, encrypted names) | | A2 host-blind, declared residue | ciphertext plus a published list of plaintext metadata | Keymail (routing headers), Kass (log timestamps), Eleven (thread membership), Dineraya buyer | | A/pub public by design | A, plus surfaces that are public on purpose, listed one by one | Woodstar (public posts; DMs and blobs sealed) | | B sealed single-tenant | sealed at rest (parked DB, replica, blobs); the live instance holds a key while awake because unattended work needs plaintext | an internal finance ledger, one instance per team (the defining example); Dineraya merchant | | C host-sighted | plaintext at rest, chosen and written down: support visibility, SQL over personal data, payments | Tito (the defining example) |

Several apps have not published a class letter yet (amadan's is unresolved; Oficina, Movement and Correomona describe their posture in words, without a letter). Don't assign one on their behalf.

The test is the CARLOS one: publish the database and see what leaks. A leaks its declared residue and nothing more; B's cold copy leaks nothing; C leaks the data, and said so up front. Enforce it in CI: push a marker through the app, then grep the raw SQLite bytes and bucket objects for it. An undeclared plaintext surface is a class violation whatever the intent. decisions.md §1 has each app's recorded reasoning.

Placement follows the class (designed, not yet enforced). Hosts are tiered by who controls the box: 0 the operator, 1 a named counterparty under a data-processing agreement, 2 a stranger. S and A run anywhere, B never on tier 2, C only on tier 0 or where the agreement names the data. As of 2026-10-15 the platform does not record or enforce trust classes, so declare the class in your README and AGENTS.md now; don't tell users the platform enforces it.

Two more axes, independent of the class: a licence class (L1 libre, L2 source-available commercial, L3 open with a hosted offering, L4 closed hosted-only, L5 closed hosted and on-prem: Tito, Jelly) and three remix flags (forkable, agent-driveable through typed tools, agent-rebuildable from a published skill). An L5 app can be class A; an L1 app can be class C.

4. What the choice buys

The benefits on carlosframework.com, each with the mechanism behind it and what it depends on. State a benefit only with its mechanism, and only the ones your tenancy actually earns.

| Benefit | Mechanism | Depends on | State on Carloku, 2026-10-15 | |---|---|---|---| | Isolated data per tenant | each unit is its own process, SQLite file and socket; instances get CPU and IO limits and no loopback or private-network access | a boundary smaller than "the whole app" | live | | Blast radius of one | a panic or runaway query kills one process; the next request restarts it | same | live | | A security claim you can falsify | publish the database and see what leaks; the residue is declared | a declared class plus the CI grep test | yours to write | | Multiple trust classes | one product, a class per workload (instance, sidecar, central app) | splitting workloads that need plaintext from those that don't | declare now; placement enforcement not built | | Encryption encouraged | sealed content (A), sealed at rest (B), keys in browsers | the class you pick | rastrillo crypto, vault, webauthn are primitives; app-level E2EE is hand-built | | Continuous security monitoring | carlos errors, carlos availability, edge analytics, opt-in virus scanning of stores | nothing | live | | Cost/performance efficiency | idle instances hibernate to the bucket and cost nothing; the fleet is sized to concurrent use, not headcount | units that idle (smaller units idle more) | live | | Wake in under 500 ms | a request for a sleeping instance is held while it wakes | same | live | | Replicated from the first byte | every database streams to object storage; every wake is a restore | an instance with a database (central apps keep records in the store instead) | live | | Export and erasure per tenant | a tenant's data is its own database and its own objects, never rows mixed with others, so export is copying them and erasure is a bounded list | the unit matching who leaves together | export live (carlos db pull); erasure is a procedure you write: instances delete deliberately keeps the parked database, replica and store objects, so name each and how it goes | | Residency per app or per instance | an instance only wakes on a host in its region | per-unit instances, so each customer can be pinned | released, switched off on Carloku | | Self-hostable, first class | one binary, a bucket and DNS; same binary hosted, on a customer's boxes (carlos fleets), or on a self-run platform | nothing; licence class decides what customers may do | live | | One codebase, every deployment (vendors) | one instance per customer means on-prem is a fleet you administer, not a fork | per-customer instances | customer fleets live; Tito self-hosts in three regions | | API- and agent-driveable | actions opt in as tools that reach the same handler a form does | rastrillo tools (manifest-generated) | in rastrillo; no app has published tools yet |

What a tenancy choice costs belongs in the same declaration: cross-unit queries are hard by design; a stateless centre makes writes dearer than a SQLite row; model C is one box big today; class A or B makes recovery and search product surface; class C puts confidentiality on operator policy and authorization, not mathematics.

5. Worked choices

Short, to show the reasoning. Each still needs its own declaration.

• A bookkeeping ledger per small business, synced nightly with the bank. One instance per business; model B (a stateless home lists the business's ledgers). Class B: sealed at rest, the live instance holds the key for the unattended sync, and the README says a live-host compromise reads data. Nightly work is carlos schedule, so the instance sleeps the rest of the day.
• A forge where people belong to several organisations. One instance per repository (amadan) or per organisation; model C, a stateless hub with path routes and one session. Trust is per content tier: public and private repos are server-readable (C), end-to-end encrypted repos are A. Rendered markdown is the app's own code, so C's one-origin rule holds; raw user-hosted HTML (pages) needs its own hostnames. One box big until cross-box path targets ship.
• A support desk sold to companies, whose agents read customer email; big customers want on-prem. One instance per customer company. Class C, argued from support load, repaid with origin splits (credentials on one origin, customer-authored mail rendered on another). Licence L5 if closed. On-prem is a customer fleet or a self-hosted platform following your release channel: the same binary, not a fork.
• Team chat. One instance per conversation or team; model D, a blind home. Class A2 with the residue listed (membership, timestamps).
• A product site. No instance at all: carlos deploy --kind static. Class S.

6. The tenancy declaration

Write this into AGENTS.md (and the README's trade-offs) before code. It is the answer an agent planning a CARLOS app gives first.

Tenancy declaration: <app>, <date>, <who decided>
One instance is:      <the unit>  (person : instance = 1:1 | N:1 | 1:N | N:N)
Why this unit:        <whose data; what fails together; who leaves together>
Reached through:      model A | B | C | D, or <own model, and why>
Central app:          none | home | hub; stateless, records in its store
Workloads and class:  instance = <S|A1|A2|A/pub|B|C>; sidecar = <…>; central = <…>
Declared residue:     <every plaintext surface, one per line>
Keys live:            <browsers | instance memory while awake | n/a>
Hosting:              Carloku | customer fleets | self-hosted platform
Licence class:        L1–L5, or "not published yet"
Benefits claimed:     <each with its mechanism, from §4>
Costs accepted:       <each, plainly>
Waiting on:           <unshipped platform or rastrillo pieces relied on, by name>

Common mistakes

| Mistake | Reality | |---|---| | A Carloku account per customer | Accounts are the app author's tenancy on the platform. Customers are instances of your app. | | A tenant_id column in one shared instance | Gives up isolation, erasure, residency and hibernation per tenant. Make the tenant an instance. | | A stateful home or hub with its own SQLite | Central apps are stateless; records are objects in the store. | | The provisioning credential on the tenant app | Every instance would hold a token that can delete its siblings. It lives on the central app only. | | Trusting the hub's membership list for access | The instance's own roster decides. The hub's copy is a directory. | | One class for the whole product | Class is per workload. A sidecar or central app that sees plaintext gets its own letter. | | Claiming the platform enforces your class or residency | Neither is enforced on Carloku as of 2026-10-15. Declare; don't overclaim. | | Copying data between instances to share it | Sharing is membership. Data never crosses a boundary. | | A reporting job that opens every tenant's database | The centre reports what it owns or witnesses; instances push fixed-shape facts through an outbox; a person's cross-space view fans out in the browser — §2 "Seeing across tenants". |