nordisk/monetize

Integrating an application with monetize v2.0

Write a small operator and a resource. Monetize is the control plane that runs it. If you know Kubernetes, the parts map like this:

The SDK is a library compiled into your operator: the types and the signatures of the 6 ops. The product operator is your signed .wasm; the ONE box pulls it and calls it through the 6 ops. Unlike a Kubernetes operator it runs no loop of its own and calls nothing: monetize runs the loop and asks it the product questions (pull only, no secrets).

Premade with monetize: Stripe, UpCloud and Cloudflare DNS.

This guide is for the author of an application that the ONE box is to sell. It describes the v2.0 target (MONETIZE-V2.0-PLAN.md, A24, A25), not today's 28-op contract. The older ASD-STE100 manual (integration-guide.md) describes today's code and stays until P3 lands; where the two differ, this guide wins for new work.

Every statement that depends on a phase that has not landed carries its tag: [P1], [P2], [P3], [P4]. A statement with no tag holds on main today. Where a v2.0 name differs from today's, today's name follows in brackets.

The pictures of this guide are operator-v2.svg (the whole idea, above), integration-v2.svg (the parts and the plugins, section 2), datamodel-v2.svg (the data model, section 7) and buyflows-v2.svg (the buy flows, section 8).

Contents:

1. The parts and who owns them
2. The plugins, and who writes each one
3. Write: your product operator, your pages, your estate front
4. How it ships
5. How you test it
6. A worked example: the Lake
7. The data model: what is stored where
8. The buy flows, step by step
9. Where it lives: traits and crates

1. The parts and who owns them

Three parties. Each owns what it writes.

Two rules shape everything below.

• PULL only. The ONE box never calls into an estate. Your boxes report and pull their orders. Your product operator dials nothing.
• Runtime code calls Rust libraries, never cargo, xtask, dwarves or a shell.

2. The plugins, and who writes each one

The ONE box runs four kinds of plugin, one slot per trait. A plugin is a signed .wasm guest that the box pulls from the release bucket and pins by sha256, or an open impl linked into the open binary. You write exactly one of them: your product operator (guest). Everything else is premade.

The picture integration-v2.svg draws the same list. Its colours mean the same in every picture of this guide: green = you write it, cyan = premade in open monetize, amber = premade in monetize-impl (private, signed), grey = outside (the buyer, the vendors, the operator). A dashed outline is a stub of the lowest priority (owner rule).

The money-free default (owner 2026-10-24) is the open build's default features: the sandbox payment and cloud and the invoice vendor. A fresh open build sells free plans and lays on play iron until a payment guest and a cloud guest are fed.

Test doubles stand in for a vendor's API, not for a plugin. They run only in tests:

An outside author cannot run the fake Stripe or monetize's cargo xtask trials (the 12 buy trials, which build from the private siblings ../monetize-impl, ../gunnar and ../holger). Use the money-free default.

The crates you link are not plugins: monetize-product-guest (the SDK of your product operator), monetize-site-buy (the buy flow, the relay, the browser scripts), nordisk-pairing (pairing and the live door) and monetize-estate-side (the box pump). Section 9 lists them with their paths.

Also reused as they are:

• monetize-admin: the box itself. The operator lays it from monetize-admin-installer. You never build it.
• The open monetize-server inside it: the state machine instantiate(order) is lay → install → sale check → capture → DNS → ready. It is the only place that lays, pairs and captures.
• The shop's installer (monetize-shop-pairing): it pairs your laid boxes over WireGuard and mTLS, once, at the install. It holds no product code: it pairs by the contract your facts declare and the sale check reads the paths your facts().proof names.
• monetize-site-buy: the 26 relay routes, the budgets, the return pages, the browser scripts BUY_JS and WELCOME_JS. Gunnar's copies of the grow and renew doors go into it [P4].
• Sign-up: the engine's own sink on the ONE box. The private sign-up guests are deleted [P2].

What a vendor guest reads is NAMES only: MONETIZE_STRIPE_<INSTANCE>_SECRET_KEY, UPCLOUD_TOKEN, and so on. The keys stay on the ONE box in the operator's custody. Your product never sees them.

3. Write: your product operator (guest), your pages, your estate front

3.1 The product operator: one crate, six ops

Make a crate in your own repository, crates/<id>-monetize-guest, with crate-type = ["cdylib", "rlib"] and the dependency monetize-product-guest. Gunnar's is gunnar/crates/gunnar-monetize-guest; the Lake's is monetize/guests/lake [P1].

The trait, as A24 §2.2 writes it [P3]. The names in brackets are today's ops (monetize_product_guest::Guest), which are what you implement until P2/P3 land.

pub trait Product {
    /// Op 1. Who the product is: id, ABI, meters. No grants.
    fn manifest(&self) -> Manifest;                                   // [today: manifest(), the meters in it (Manifest::with_meters), P2 T13]

    /// Op 90. What an estate of this product IS. Pure data, read once per guest digest.
    fn facts(&self) -> Facts;                                         // [today: lifecycle_facts(host) -> LifecycleFacts, with tickets, test_actions, guardian (P2 T13)]

    /// Op 91. The plan of ONE order: machines (role, plan, disks, medium), stores, names.
    fn plan(&self, order: &Order, ctx: &PlanContext) -> Result<EstatePlan, Refusal>;   // [today: lifecycle_lay_plan(host, &LayPlanReq) -> serde_json::Value]

    /// Ops 100-102. The guardian: pure, over the estate as the boxes reported it.
    fn diagnose(&self, view: &EstateView) -> Vec<Finding>;                              // [today: guardian_diagnose]
    fn remedy(&self, remedy: Remedy, view: &EstateView) -> Result<Vec<Step>, String>;   // [today: guardian_plan]
    fn observe(&self, role: &str, what: &str, view: &EstateView) -> StepState;          // [today: guardian_observe]
}
export_product!(YourGuest);   // [today: export_product!(YourGuest, grants = [])]

What happened to the other 22 ops of the old table (A25 §2; P2 T13, monetize_product_guest::ops::RETIRED):

A guest implements only the six. Grants: none, for every product guest (Gunnar, Holger and the Lake ask for [] since P2 T13).

3.2 manifest()

Manifest::new("<id>", meters![...])          // [today: Manifest::new("<id>", &[]) and meters() -> Vec<WireMeter>]

One meter per thing you measure or cap. Gunnar: pack_bytes (enforced, disk). Holger: disk_bytes (enforced, disk). The Lake: ingested_bytes (enforced, disk: Backing::DiskBytes) and query_seconds (cap only).

3.3 facts(): the shape as data

Everything the core and the shop's installer know about your product is in this one answer. Nothing about your product is written in the core [P3].

pub struct Facts {
    pub kind: String,                  // "gunnar" | "holger" | "lake"
    pub words: Words,                  // name, title, account_home, the mail words       [today: words + default_shape.mail_words]
    pub roles: Vec<RoleFacts>,         // one per role the plan may lay                   [today: medium_of, other_medium, keep_medium, data_roles, live_slot, backup_roles]
    pub front_role: String,            // serves the public names, drives the update and is upgraded LAST [today: front_role]
    pub primary_role: String,          // holds the tenants, the ticket key, the backups  [today: the first data role]
    pub twin: Option<TwinFacts>,       // None = no election, no mirror                   [today: a data role with mirrors_primary = true]
    pub update_order: Vec<String>,     //                                                 [today: update_order]
    pub names: Vec<String>,            // served name prefixes: "", "www.", "git."        [today: default_shape.names]
    pub proof: SaleProof,              // the routes the sale check reads and what proves the sale [today: per-kind code in monetize-shop-pairing sale_check.rs; the type: P3a]
    pub form: OrderForm,               // the fields a buyer sets, their ranges, the named offers  [today: default_shape.ladder and EstateSizes]
    pub grow: GrowRule,                // what may change on a running estate             [today: "data never shrinks" in the core]
    pub tickets: bool,                 // your main mints actor tickets                   [today: LifecycleFacts.tickets]
    pub test_actions: Vec<TestAction>, // the shop's test buttons                         [today: LifecycleFacts.test_actions]
    pub feed: Vec<FeedKey>,            // the product-specific feed keys your boxes read  [today: monetize-shop-pairing CONTRACTS]
}
pub struct RoleFacts { role, medium, keep_medium: Option<String>, live_slot: bool, backed_up: bool, data: Option<DataRole>, many: bool, optional: bool }

Landed (P3a, additive): monetize_product_guest::facts::Facts, today's LifecycleFacts field for field plus the shop contract's fields as data (billing, offsite, boxes_hold_console_token, welcome, sold_variant, site_variant, box_kind, free_feed; proof_name is domain_proof_name, and the old name is still read) and proof: Option<SaleProof>. Every field is defaulted, so today's lifecycle.facts answer reads as a Facts.

Landed (P3, T15): Facts IS the answer to lifecycle.facts (op 90); wire::LifecycleFacts is its old name. It also carries console_token_feed, passkey_rp_feed, welcome_readme (your welcome README, {host}, {account}, {repo}), reserved_accounts (your boxes' own principals, never a buyer's account) and form (your OrderForm, below). The shop's installer reads its contract for your estate off these facts (monetize_shop_pairing::ProductContract::of) and holds none of its own: a fact your guest does not declare is refused by name ([contract-…]), and no estate of yours is paired or captured until it does. roles, twin and grow are still to come.

Each product declares its own sizes, networks and disks. The core has no opinion:

• Gunnar: front, main, twin; four data disks on main; the twin mirrors main and is elected; names "", www., git..
• Holger: front, main, twin; one data disk; every disk on the hdd tier; the lean shape (STARTER-1xCPU-1GB front, STARTER-1xCPU-2GB main, STARTER-1xCPU-1GB twin); the front has a public and a utility IPv4, main and twin a utility IPv4 only (they sit behind the front); names "", www..
• The Lake: front, ingestor (n), be (x), fe (y), graph (0 or 1), and a store input of class object; no twin.

Today the shape rides in LifecycleFacts.default_shape as JSON (front, main, twin machine shapes with plan, disks, interfaces). Keep that until P3; A24 §4.1-4.3 shows the same facts in the target form.

3.4 plan(order, ctx): the "instantiate" function

Pure. The buyer's order is validated against facts().form before it reaches you. ctx is what the operator fed: zone, labels, the template tiers (today's LayPlanReq: config, company, sizes, twin_plan, template_tiers).

You answer an EstatePlan: reference = estate/<company>, zone, one machine per role instance (role, hostname, title, plan, boot order, labels with role = <role>, disks with the system disk first), and stores [P3]. The core prices it at the cloud (Cloud.price), lays it (Cloud.lay), and on a change diffs the laid plan against your new one (Cloud.change) [P3]. A refusal refuses the order with your words; there is no native fallback [P3].

Today's rules that still hold: each title unique; each role laid once (the Lake names its n-th member <role>-<n> [P1]); a plan that names front, main or twin must have exactly those three [until P3].

Gunnar's and Holger's plan is one call to the shared plan_from_shape(ctx, &shape) [P4]; today each has its own lay_plan (lifecycle.rs, estate.rs).

3.5 The guardian: diagnose, remedy, observe

Unchanged from today. Pure, over EstateView (what the boxes reported). diagnose answers findings with a code, a role, words, evidence and the remedies a person or auto-fix may press. remedy answers steps (cloud steps, orders for a box, waits). observe answers whether a wait is met. The shared step helpers (guardian::steps::plan, ::observe) replace the four copies [P4].

3.6 Your declaration: the toml block

The operator's feed file (solo.toml in private-monetize-ops) carries one block per product. You write it with the operator. After P3 the product's own facts are gone from it: no grants, no shape, no contract.

[products.<id>]
module = "<id>_monetize_guest.wasm"     # your signed product operator, pinned by sha256 (cargo xtask pins)
sha256 = "..."
purge_after_days = 10                   # an unpaid account is deleted 10 days after its end
prices = """
[SE]
disk_gib_month = 1000
"""
[products.<id>.media]                   # how YOUR kit makes the media the ONE box lays from
kit = "private-<id>-ops"
argv = ["cargo", "xtask", "estate-media", "--where", "{where}", "--media-to", "{to}", "--apply"]
[products.<id>.bundles."10gb"]
cap_delta = { pack_bytes = 10737418240 }
[products.<id>.signup]
cap_meter = "pack_bytes"
[products.<id>.signup.plans."<id>/account"]   # the free account an order lands on
amount_minor = 0
cap_bytes = 0
[products.<id>.mail]

The ONE box also needs [vendors.stripe.instances.<id>] (the operator's; it names the key NAMES) and [boxes.prod.estates.<site>] for each site that sells your product (product, vendor, owner). Your estate's own declaration on its media (Holger's RON for its server) is your kit's business; monetize does not read it.

Migration (RA2-16, 2026-10-26): two retired keys are refused by name. [products.<id>.plans.<plan>] and return_hosts fed only the ONE box's old /kop purchase page, which OD6 deleted. A config or a feed (plugin.<id>.toml) that still sets either is now refused at load, naming the key; before, both were parsed and ignored. To migrate, delete the [products.<id>.plans.*] tables and the return_hosts line from the kit that writes the feed (for private-monetize-ops, solo.toml and the writer in xtask/src/solo.rs). Nothing else changes: a product sells through its own sign-up ([products.<id>.signup.plans], fed as [signups.<id>.plans]) and its [products.<id>.bundles]. Deploy the kit's change BEFORE this monetize: an older monetize reads a block without those keys as before.

3.7 Your buy pages: BuySite and the assets

Implement monetize_site_buy::BuySite once, in your site's server (Gunnar: gunnar-ui-server/src/auth/buy_site.rs; Holger: holger-estate-front/src/buy.rs). Twelve methods, 6 required + 6 defaults (P4b added operator; A32-9 deleted the grow_needs_checked_tickets knob: every site's grow doors wait for checked tickets; monetize-site-buy tests/h15_stepped_up_refuses.rs holds the count). The default of stepped_up REFUSES (Err(STEP_UP_WORDS)): a site that does not prove a fresh key touch cannot end an estate. Implement it.

pub trait BuySite: Send + Sync + 'static {
    fn origin(&self) -> String;                              // "https://www.holger.rs"
    fn product_word(&self) -> String;                        // "Holger"
    fn who(&self, headers: &HeaderMap) -> Future<Result<Who, Refusal>>;            // Visitor | Person | Machine, from YOUR session
    fn ticket(&self, headers, buyer: &Buyer, purpose: &str, caps: &BTreeMap<String, u64>) -> Future<Result<Vec<u8>, Refusal>>;  // your main signs it
    fn held_caps(&self, headers, buyer: &Buyer) -> Future<Result<BTreeMap<String, u64>, Refusal>>;
    fn signup_account(&self, user: &str) -> Future<Result<Account, Refusal>>;      // NoPasskey | HasPasskey
    // defaults: pages(), allowed(), trusted_proxies(), fixed_buy_url(), operator(), and
    fn stepped_up(&self, headers) -> Future<Result<(), String>> { Err(STEP_UP_WORDS) }  // a fresh key touch; ending an estate needs it, so implement it
}

Then: a ShopLink to the ONE box with your site's bearer, a Relay over your site and the link, and monetize_site_buy::router(relay) mounted on your web server. Do not copy a buy door; the relay has all 26.

The browser side is one script, rendered once: monetize_site_buy::assets::buy_js(&Settings) and welcome_js(&Settings). Your Settings names the product word, the storage prefix, the free plan id, the manage URL, the bearer key, the status and offer URLs and the contact. Your UI server serves the rendered script; your markup and CSS are your own. No product server serves a byte of UI.

The relay carries your product's own order: your page sends the buyer's form as order (a JSON object) through untouched, and the relay passes it on as EstateSizes.order on EstateOrder.Start and ChangePlan. The ONE box checks it against your facts' form (OrderForm::check: every key a field of the form, each value of its kind and in its range, the rest filled in from the defaults) before anything is priced or held, keeps the filled order with the run, and hands it to your plan() as LayPlanReq.sizes.order. A product with no form is sized by the three plan fields (front_plan, main_plan, main_data_gib), and an order for it is refused by name.

The buyer's path: your sign-up page → your relay → the ONE box mints the vendor's page → the buyer pays at the vendor (the only page off your site) → back to your paid page → your welcome page polls until the estate is ready. The buyer never sees monetize. Stripe once, e-mail once, "Pay ".

3.8 Your estate front and boxes

Every box of your estate runs:

• nordisk-pairing's box side: Product (kind, tunnel_pubkey, capacity, offer, fed, the live door). The box offers its fleet_pubkey and ticket_pubkey at the pairing. The shop pins fleet_pubkey for every box; it pins the primary's ticket_pubkey only for a site order today (site_ticket_key), and for every estate [P3].
• the shared pump in monetize-estate-side (pump, with your PumpBox: health, report, the executor of your order kinds; landed in P4a, the products move onto it [P4]) (until then your own loop over Fleet.Report, Fleet.Orders, Fleet.Ask: Gunnar gunnar-repair/src/fleet.rs, Holger holger-fleet/src/puller.rs), with your Estate [P3]:

pub trait Estate: Send + Sync {
    fn report(&self) -> Report;                                   // build, health, usage per tenant, twin review
    fn execute(&self, order: &Order) -> Result<Ack, Refusal>;     // one signed order the box pulled; an unknown kind is refused BY NAME
    fn box_key(&self) -> &SigningKey;                             // what the box signs its Fleet calls with
}

The core's kinds are ONE list, monetize_product::pull (A28 M25): 7 orders, entitlement, add_principal, add_users, grow_room, purge_tenant, grow_go_ahead, sign_in_again (order::CORE), and 1 ask, grow_set (ask::CORE). A product whose guardian runs a twin adds its own guardian kinds (Gunnar's repair verbs: monetize_embed::fleet::kind::GUARDIAN). Name the kinds your boxes run in your facts (order_kinds); Facts::runs(kind) is the refusal BY NAME for any other kind, from those facts alone.

The front also runs nordisk-pairing's FrontProduct (the relay's tunnel key, its offer, the live door) and the shared update step [P4] (Fleet.Ask kinds update_take / update_report since P3, the old SoldEstate.UpdateTake / UpdateReport served one release more; the step itself is still in gunnar-front/src/update.rs and holger-estate-front/src/update.rs). The update is an order the front pulls; the front stages the live app through each box's live door, in facts().update_order, or reports falls_to_keep.

The sale check: before the capture the ONE box reads, over public HTTPS, the routes your facts().proof names on the front [P3]. A SaleProof (landed in P3a: monetize_product_guest::facts, run by monetize_shop_pairing::sale_proof) is a list of typed checks, each one request and what its answer must hold: the method and body (POST with {invite} and {account}), a JSON status field (passkey_enabled true, bootstrap_spent false), a non-empty challenge, and the bearer list rule (exactly one <account>/welcome). Each product names its own routes; there is no shared /auth/first-admin (Gunnar: /auth/status and /auth/passkey/register/start; Holger: /-/auth/passkey/config; the Lake: /first-login). The shop runs your guest's own facts().proof and has no judge of its own (P3: the judges went once their SaleProof was proven to give the same answers). Serve the login page and the first-admin door on the front from the first boot.

4. How it ships

Pull only, at every hop.

1. The Build Thing of monetize-impl builds your product operator (guest) from your repository ([[build.variant]] name = "<id>-guest", manifest_dir = "../<id>", target = "wasm32-unknown-unknown", sign.purpose = "plugin") and signs it under the plugin root the ONE box trusts. Every vendor guest is a row of the same file.
2. cargo xtask pins (private-monetize-ops) checks the sha256 of every built guest against solo.toml. A stale pin is refused before anything is laid.
3. cargo xtask release --publish --apply writes the signed release-manifest.toml and puts the guests into the release bucket: release/plugins/<blake3>/<name> and its .p7s.
4. cargo xtask feed --where upcloud --box prod --apply puts the feed built from solo.toml on the box's door. It prints key NAMES only.
5. The ONE box pulls: its own Plugins.Update (monetize box plugins --apply) takes the plugins the manifest names and verifies each against the root; a module that is not its pin is refused by name.
6. Your media come the same way: your kit's estate-media step uploads them to the release bucket and writes media-<kind>.toml; the ONE box lays from them.

A release of the ONE box itself is one verb (self-release) and goes out only from a green, gated main. Your estates are updated by the ONE box (EstateOrder.UpdateEstate), which your front pulls.

5. How you test it

Three rings, innermost first.

What the fast test checks, among others [P1]: the quote's words match the plan your product operator answered; the vendor page is minted once; the lay has exactly the plan's machines; every box offered fleet_pubkey; the election happened where facts.twin is Some and did not where it is None; your product operator made ZERO door calls over the run; a grow changed exactly the diff at the mock; a shrink was refused by name; the terminate left zero resources with the reference, backups included.

The Lake is the reference product: it runs the same rings in monetize's own CI (cargo xtask ci). When your product behaves like the Lake, it behaves like Gunnar and Holger.

Money: your tests run on the money-free default [P1] or the fake Stripe. A change to the money flow is proven by one real purchase on test2 before gunnar.rs. Test addresses are *@mock.invalid.

6. A worked example: the Lake

The Lake is the parametric case: the buyer sets numbers, the product operator (guest) turns them into a plan, the core prices the plan at the cloud. No Lake code is in the core. On main it is guests/lake and crates/lake-product [P1]; what it still waits for from P3 is listed in its P3_WAITS.

The order:

struct LakeOrder { store_gib: u64, ingestors: u32, ingestor_plan: String, be: u32, fe: u32, graph: bool }
// store_gib 100..=100_000 in steps of 100; ingestors 1..=64; be 1..=32; fe 1, 3 or 5; graph yes/no

The facts (A24 §4.3, target form) [P3]:

// one medium for every role: "lake" (keep medium "lake-keep"); one binary runs each role
roles: [ role("front", medium "lake", live_slot),
         role("ingestor", medium "lake", many),
         role("be", medium "lake", many, data: data1),
         role("fe", medium "lake", many),
         role("graph", medium "lake", optional),
         store("input", class "object") ],
front_role: "front", primary_role: "fe", twin: None,      // today the core's primary is the first data role, `be` (P3_WAITS)
update_order: ["ingestor", "fe", "be", "front"],        // the front LAST (guests/lake role::UPDATE_ORDER)
names: ["", "www.", "s3."],
proof: SaleProof { checks: [check("the login page", GET "/login"), check("the first-login door", GET "/first-login")] },   // its own routes (lake_box.rs)
form: OrderForm { fields: [gib("store_gib", 100..=100_000, step 100), count("ingestors", 1..=64), plan("ingestor_plan"),
                           count("be", 1..=32), count("fe", 1..=5, odd), bool_("graph")],
                  offers: [offer("Starter", {store_gib: 500, ingestors: 2, be: 3, fe: 1, graph: false}), offer("Team", ...)] },
grow: GrowRule { never_shrinks: ["store_gib"], may_add: ["ingestors", "be", "fe"], may_remove: ["ingestors"] },
tickets: true, test_actions: [private("lake-mini")],     // "Test: the smallest Lake"

The plan (plan_of on main today [P1]; plan() at P3):

let o: LakeOrder = order.parse()?;
let mut p = EstatePlan::new(ctx, "lake");
p.machine("front", "STARTER-1xCPU-2GB", disks![system 20]);
for i in 1..=o.ingestors { p.machine_n("ingestor", i, &o.ingestor_plan, disks![system 20]); }
for i in 1..=o.be        { p.machine_n("be", i, "STARTER-4xCPU-16GB", disks![system 20, data1 (o.store_gib / o.be).max(50) tier "maxiops"]); }
for i in 1..=o.fe        { p.machine_n("fe", i, "STARTER-2xCPU-4GB", disks![system 20]); }
if o.graph               { p.machine("graph", "STARTER-4xCPU-16GB", disks![system 20, data1 100]); }
p.store("input", o.store_gib, "object");                      // [P3: today the input store is the BE data disks]
Ok(p)

Machines laid: 1 + n + x + y (+1), roles front, ingestor, ingestor-2, be, be-2, be-3, fe, graph.

What the core does with it, with no Lake code of its own:

• the quote: Cloud.price(plan) plus the margin;
• a grow: a new order {be: 4} → plan(new) → the diff against the laid plan (one BE added) → Cloud.change(laid, new) [P3] → an order to the FE leader ("a new BE joins") that the Lake's box executes;
• a shrink of store_gib: refused by name from facts().grow [P3];
• the guardian: a silent be → remedy NewServer of that index; a silent FE leader → a person.

The Lake's box side, as a target [P4]: one binary for every role (--role front|ingestor|be|fe|graph --index n) with impl Estate, nordisk-pairing's Product, and FrontProduct on the front. Today it is lake-product/src/lake_box.rs, one in-process LakeBox per role. It runs the kinds its facts name (order_kinds: entitlement, add_principal, purge_tenant, grow_room) and refuses any other kind BY NAME in its ack, from those facts alone (A28 M23; a member joining is a target, no join_member kind exists). Its site is LakeSite: BuySite with Settings { product: "Lake", .. }. Today the Lake implements neither Product nor FrontProduct: its bench pairs its boxes with an in-process double (lake-product/src/installer.rs). nordisk-pairing can pair it since P3a (seed::Kind::Box(role): each box names its own kind, which is not elected). The Lake names its kind in its facts (box_kind = "lake", a box kind, never elected; T15, A28 H13).

The Lake's fast test is monetize's own cargo xtask fast --product lake [P3] (today the verb refuses lake and names cargo xtask bench lake), and its receipt adds the rows that only a parametric product can prove: a grow be: 3 → 4, a shrink refusal, an order with graph: true, a terminate that lists zero stores.

7. The data model: what is stored where

1. The buy flows, step by step
2. Where it lives: traits and crates

The picture is datamodel-v2.svg. Three stores hold the data of a sale, and each has one writer. Only four links cross between them: the tenant name, the paid sign-up that makes an account, the order that ties an account to a sold estate, and the first-login invite.

On the selling site (gunnar.rs, holger.rs). The product owns its people. Gunnar keeps them in one redb file, control.redb: the AuthDoc (refs/gunnar/auth) holds principals, passkeys (WebCredential), SSH keys, tokens, grants and invites; the catalog doc holds namespaces and repos; refs/gunnar/entitlements holds the signed fact per tenant. An account is a principal and the namespace of the same name (owns_account(pid, ns) is pid == ns); both are made in one call (ControlPlane::add_principal). A grant gives a principal a level (Read, Write, Admin) on the server, a namespace or a repo. An invite stores the hash of its secret, never the secret. The site keeps nothing of monetize but its ShopLink (the ONE box's URL, the site's bearer, product, vendor). The tenant name it uses at monetize is the account's namespace (Gunnar) or the account's repository (Holger) (monetize_site_buy::Buyer.tenant).

In monetize (the ONE box). monetize-admin's server writes every row, in redb files and one run file per sold estate. An ACCOUNT is the pair (product, tenant): its signed entitlement fact (ledger.redb entitlements), its usage (usage.redb), and its rows: one subscription, any number of purchases, any number of private instances (monetize.v1.Accounts). A purchase is append-only ledger rows under the reference <product>/<tenant>/<period>. A paid or free sign-up is a row in signups.redb keyed by the vendor's (vendor, session). A sold estate is estate-orders/<company>/run.json (EstateRun): who owns it (account), which site sold it (estate), its quote, its phase and what was laid. Its secrets are sealed apart, in custody/<company>.sealed. The fleet store (fleet.redb) pins each box's key and queues the orders the boxes pull. The operator console keeps its own passkeys and sessions in state.redb. Sites, vendor instances, plans and the release are the feed (solo.toml, the signed release manifest); they are configuration, not customer data.

On the sold instance (acme.gunnar.rs). The instance has its own store, with the same model as the selling site. Its first admin is the principal named EstateRun.account. The installer feeds the hash of the first-login invite (operator_invite_sha256), and Gunnar stores it as the invite operator-bootstrap (single use, short lived). The buyer redeems it from the "ready" mail (/login?invite=…&user=<account>) and registers the first passkey. Everyone else on the instance is invited by that admin. Neither the selling site nor monetize holds a row of the instance's people. Its boxes report and pull their orders. The ONE box never calls into them.

What changes in v2.0: the sign-up guests are deleted and the entitlement is only a pulled order, never a push [P2]; the feed loses grants, shapes and the shop-pairing contracts [P2]; the quote carries the product's own Order JSON instead of the three Gunnar sizes, the plan offers come from facts().form, SoldEstate folds into Fleet (the front's five calls are Fleet.Ask kinds upgrade, recharge, material, update_take, update_report, signed as role = front by the estate's client key; the ONE box serves the old door for one release more), and custody also keeps the main's ticket_pubkey [P3]; terminate destroys the cloud backups with the estate [P1].

A visitor who buys a private instance gets two things.

1. An account on the selling site, made with the payment. The page sends EstateOrder.Start with new_account = true, the account name and the e-mail. When the vendor says PAID, the ONE box queues a signed add_principal order. The site's main pulls it and makes the principal and its namespace, and the sign-in link is mailed. The buyer registers a passkey there. A signed-in buyer sends an actor ticket instead, and no new account is made.
2. The instance itself, <company>.gunnar.rs, with its own first admin. The instance is the EstateRun of that account. Its first admin has the same name as the site account, but it is a separate principal in a separate store, made by the first-login invite. The selling site's account sees the instance as one instance row (its phase, its price, renew, terminate). It holds no rights inside the instance.

8. The buy flows, step by step

Every buy method has an id (B1 … B10), and every step of it has one (B3.4). The picture buyflows-v2.svg shows each method as one row of hops, in the lane of the party that acts. The tables below give, for each step: who calls whom, the relay route and the gRPC call it maps to, the state the order is in after it, the exact words a buyer or the log can show there, and the log lines it writes. The words are copied from the code on main (2026-10-25), with file:line; {…} is a value the code fills in.

Use it two ways. For design: read a method top to bottom. For an error: search this section for a phrase of the error or the log line, and its row names the step, the file and the line.

8.1 The files the tables cite

Every file is named once here with its path in nordisk/monetize. The tables use the short name on the left.

Log targets.

• Relay audit lines are tracing events on target monetize_site_buy::audit (relay.rs:55). Each has an event = "…" field.
• Server lines are eprintln!("monetize-server: …").
• ALERTs have the form monetize-server: ALERT <kind> <ref>: ….
• functional_status rows have the form skidbladnir::functional_status(<component>, <what>, ok, words).

8.2 The relay's routes (relay.rs router_of 1363–1406; the doc table at 8–34)

Routes outside the relay:

• Vendor webhook. POST /callback/{*vendor} on monetize-server (crates/monetize-server/src/lib.rs:282), handled at callback.rs:80.

• The site's own return pages. /paid/<reference> and /cancel/<reference> belong to the site, not the relay (relay.rs:1420 test; returns.rs:14–18).

• Operator doors on monetize-admin. These are at admin-door.rs:869:

  • POST /site/order → EstateOrder.OrderSite{test_order:false}
  • POST /site/test-order → OrderSite{test_order:true}
  • POST /site/cancel → EstateOrder.Cancel
  • POST /site/terminate → EstateOrder.Terminate
  • POST /site/settle → EstateOrder.Settle

• Operator UI. monetize-ui-server has POST /api/test-purchase/start → TestPurchase.Start and POST /api/sites/order → OrderSite with test_order: false (crates/monetize-ui-server/src/serve.rs:57–62; site_order.rs:98).

• ONE shop's own pages. None are left: /shop/signup* was deleted too (A33-12). The ONE box's own order pages /shop/private* and /kop* (and the /shop intake that linked to /kop) were deleted by owner decision OD6 (2026-10-26): buying happens on each product site's own sign-up. The edge answers them 404 (monetize-admin edge::RETIRED_PAGES).

Relay deadlines (link.rs:65–76):

• connect 3 s, call 10 s, mint 20 s
• buy-bundle adds MINT_GRACE 2 s
• Sells/Plans wait 2 s

8.3 How a refusal reaches the buyer

Private-instance, purchase and grow doors use from_status (relay.rs:524) / refused_call (relay.rs:942), which call rules::http_status_of (rules.rs:190–199):

Sign-up doors have their own maps:

• signup_start:

  • FailedPrecondition or InvalidArgument → 409, anything else → 502 (relay.rs:304–307).
  • Unimplemented → fixed buy link, or 501 ACCOUNT_NOT_SOLD_HERE (relay.rs:291–300).

• signup_rename: InvalidArgument or FailedPrecondition → 409, NotFound → 404, else 502 (relay.rs:409–413).

• signup_sign_in_again: ResourceExhausted → 429, NotFound or FailedPrecondition → 409, InvalidArgument → 400, else 502 (relay.rs:443–448).

• signup_status: any error → 502 (relay.rs:375).

• signup_plans: Unimplemented → 501; other errors → 503 with the last offer it holds (relay.rs:167–179).

What the buyer reads. rules::words_for_a_visitor (rules.rs:173–187) decides the error text:

• PermissionDenied → WHO_NOT_CONFIRMED (rules.rs:159): "This page could not confirm who you are. Reload it and try again; if it happens again, sign in again." The audit event is buy.refused_ticket (rules.rs:177).

• InvalidArgument, FailedPrecondition, AlreadyExists, NotFound, OutOfRange or Unauthenticated → the server's message verbatim.

  • Exception: if the message contains "monetize", "one box", "ignalina", "appliance key", "[products.", "[estates." or "[estate_orders" (rules.rs:166), the buyer reads NOT_DONE_HERE (rules.rs:161): "This cannot be done here right now. Try again in a while." The audit event is buy.refused_internal (rules.rs:181).

• Anything else → SHOP_DID_NOT_ANSWER (rules.rs:12): "The shop did not answer. Try again in a minute."

Fixed relay refusals:

• Mint timeout → 504 START_TOO_SLOW (relay.rs:62): "The payment page did not open in time. Nothing has been charged — please try again in a minute."
• Bad pay URL → 502 PAY_URL_REFUSED (rules.rs:220): "the payment address is not one this console will send a browser to".
• Every refusal body is {"error": "<sentence>"} (relay.rs:110–112).

Cancel of a paid order = 409. Purchase.Cancel returns FAILED_PRECONDITION "{ref} has been paid, so it cannot be cancelled: it finishes as paid, and ending it now is a refund (Abandon)" (svc-purchase.rs:2030–2033). refused_call maps that to 409 (test: crates/monetize-site-buy/tests/a16_cancel_door.rs:100–105).

monetize-admin door map (admin-door.rs:223–233):

• InvalidArgument 400, NotFound 404, AlreadyExists/FailedPrecondition 409
• PermissionDenied/Unauthenticated 403, Unavailable 503, else 502
• body {"refused":"<Code>","words":"…"}

8.4 B1 – Free account sign-up (the free row: card check, nothing charged)

8.5 B2 – Paid account (plan row; pay once, account made after the payment)

8.6 B3 – Private instance as a visitor (new_account = true, "pay once")

8.7 B4 – Private instance, signed in (actor ticket)

Same as B3 except for the following rows.

8.8 B5 – Grow the account (bundle; caps)

8.9 B6 – Grow an instance (ChangePlan; one step of the ladder)

8.10 B6b – Instance sign-in link again (method the code has beyond the list)

POST /auth/private/sign-in-again → EstateOrder.SendSignInAgain (relay.rs:739–758; svc-eo.rs:267).

• Refusals (all NotNow → 409):

  • "{host} is not delivered yet: its ready mail will carry the first sign-in link" (eo.rs:2076)
  • "{host}'s order names no account to sign in as" (2079)
  • "a new sign-in link was asked a moment ago; ask again in {n} minute(s)" (2084)
  • "{host}'s {role} cannot pull a new sign-in link: {why}" (2088)

• What happens: the estate main pulls a sign_in_again order (embed-fleet.rs:66) and mails the link itself.

• Logs: relay private.sign_in_again (relay.rs:753).

8.11 B7 – Renew

B7a – Renew an instance ("Renew ")

B7b – Prolong the account (hosted plan)

8.12 B8 – Cancel

B8a – Cancel an unpaid account order ("Cancel order")

B8b – Cancel an instance ("Stop renewing")

B8c – An unpaid instance order

There is no buyer door. The vendor's Cancel returns to cancel_url {origin}{pages.private} (urls.rs:48). The tick releases the order after order_ttl_secs: released "the payment page expired unpaid; nothing was held" (eo.rs:3823).

The operator can instead call EstateOrder.Settle refund:

• Not yet paid → released "the operator cancelled it before it was paid; nothing was charged" (eo.rs:4666).
• Paid → refunded with mail estate.refunded (4640–4656).

• Refusals:

  • "{ref} is {phase}: an order is refunded before anything is laid for it (an owed or waiting one)" (4629)
  • "{ref}'s buyer authorised the payment just now: it is captured on the next tick; refund it after that" (4661)

8.13 B9 – Terminate (no backup)

8.14 B10 – Test-order paths (operator)

8.15 What the trace found worth a look

1. Where the vendor sends the buyer back after paying for an instance (B3/B4). Fixed by BUYFLOW-4 (2026-10-25): a console's buyer (signed in, or a visitor paying once) now returns to https://<site>/paid/estate/<co> of the site bought on, and the page shows "paid, setting up": the steps, where the order stands, and the instance's link when ready. As traced before:

   • The relay always sends cancel_url, so a signed-in start becomes OrderedBy::Shop{back_to:"", cancel_to} (svc-eo.rs:198–203). A visitor's start is OrderedBy::NewAccount with an empty back_to.
   • Both therefore call reserve_returning(req, "", cancel_to) (eo.rs:3196–3213). The default trait impl ignores cancel_to and calls reserve(req) (crates/monetize-pay/src/lib.rs:456–463).
   • Only OrderedBy::Buyer gets site_returns (https://<site>/paid/estate/<co>, eo.rs:3204).
   • So the return page depends on the vendor's configured success_url (https://{site}/paid/{reference}, monetize-admin/src/app_config.rs:178) and on whether the Stripe guest honours cancel_to. The trace did not read that guest.
   • The visitor's welcome page is reached through the mailed sign-in link (welcome_url plus the acct_ session), not through the vendor return.

2. Renewal return lands on the plain private page. Fixed by BUYFLOW-4: renewal-<n> lands on {private}&company=<co>, as the first buy's way back. As traced before: A renewal's return is /paid/estate/<co>/renewal-N (returns.rs). paid_change_to only recognises change-<n>, so the buyer lands on plain /signup?plan=private without &company= (urls.rs:62–65). That looks unintended.

3. Buyers may see operator text on bundle and renew refusals. Fixed by BUYFLOW-4: rules::buyer_words shows the customer's words from metadata first; without them, a message with a word of rules::OPERATOR_WORDS (lay, estate, guest, operator, cap, …) reads NOT_DONE_HERE; tests/buyflow4.rs scans the buy pages' and the relay's sentences. As traced before: On buy-bundle and renew, refused_call shows the gRPC message, which is the operator's sentence, e.g. "the product cannot deliver this to …". It does not use the customer words in metadata monetize-customer-words-bin (svc-purchase.rs:876–883); only account_offer reads them (relay.rs:1133). The NOT_DONE_HERE filter catches only messages containing the keywords at rules.rs:166.

4. PermissionDenied surfaces as 502. Fixed by BUYFLOW-4: 403 with WHO_NOT_CONFIRMED. As traced before: http_status_of does not map PermissionDenied, so it falls to the default 502 (rules.rs:190–199) with WHO_NOT_CONFIRMED words. Examples: "REFUSED [estate-unnamed] …" and a refused actor ticket.

5. Pulled-product sign-up shows a maintenance sentence while it waits. While the main has not yet acked add_principal, note_waiting is set, so a pulled product's pending sign-up reads the MAINTENANCE sentence (signup.rs:1762, 1850–1851), not "being created".

6. Some line numbers are approximate. The lines marked "~" in eo/site.rs (~117–132) and term.rs (~436) were not read one by one. The B2.3 note about [signups. is also uncertain: the internal-word filter (rules.rs:166) does not list "[signups.", so that plan refusal probably reaches the buyer verbatim.

7. Not traced:

   • (The ONE shop's own /shop/signup*, /shop/private* and /kop pages are deleted: OD6, A33-12.)
   • Purchase.Abandon (refund of a captured order, svc-purchase.rs:1946–1983).
   • EstateOrder.RestoreFront details.

Proposal (not done in this change): put the step id (for example B3.4) into each of these error and log lines in the code, so that a log line maps to its row of this guide.

9. Where it lives: traits and crates

Every trait and crate an integrator touches or should know. The links go to the source on gunnar.rs. monetize-impl is private and is not on gunnar.rs; its rows name the path in that repository only. "Integrator" = you implement or link it; "premade" = you only name it. The last column names the buy steps of section 8 the row serves.

9.1 The traits

9.2 The crates

Sources: MONETIZE-V2.0-PLAN.md (§2 decisions, §3 traits, §6 phases); A24 monetize-small-trait-design (§2.2 Product, §2.3 Estate, §2.4 BuySite, §4.1-4.3 the three guests, §8.2 the fast test); A25 p2-cut-list §2 (the 28 → 6 mapping); A21 (what runs on the ONE box); the STE manual integration-guide.md (today's names). The data model: monetize-server (estate_order.rs, custody.rs, signup.rs, signup_pull.rs, config.rs), monetize/src/ledger.rs, monetize-guardian/src/store.rs, monetize-proto (accounts.proto, site_book.proto, estate_order.proto), monetize-site-buy/src/site.rs, and Gunnar's gunnar-core (model.rs, auth.rs) and gunnar-server (control_plane.rs, fed_principals.rs, repair.rs).