yichus 0.2.0 → 0.3.1

package/dist/studio-reference/balance-listed-laws.bosatsu

@@ -0,0 +1,29 @@
+package Example/BalanceListedLaws
+
+from Example/Balance import opening_balance
+from Yichus/Law import Domain, Law, Obligation, FiniteObligation, Witness
+
+export (never_negative,)
+exposes (Yichus/Law)
+
+# The person's rule, "a balance never goes below zero", checked only on
+# the deposits listed here. Every one passes, yet a deposit of -1 breaks
+# the rule: a listed check is bounded, never a proof for every input.
+
+def show(deposit: Int) -> String: int_to_String(deposit)
+
+def stays_above_zero(deposit: Int) -> Bool:
+  match cmp_Int(opening_balance(deposit), 0):
+    case LT: False
+    case _: True
+
+def empty_account(deposit: Int) -> Bool:
+  match deposit:
+    case 0: True
+    case _: False
+
+never_negative = FiniteObligation(
+  Obligation(Law("a balance never goes below zero", Domain("a first deposit", show, None, None), stays_above_zero),
+    [Witness("an account opened with nothing", empty_account)]),
+  [0, 5, 10]
+)

package/dist/studio-reference/balance.bosatsu

@@ -0,0 +1,7 @@
+package Example/Balance
+
+export (opening_balance,)
+
+# A new account opens with the first deposit as its balance. Nothing stops
+# a negative deposit, so a balance can go below zero.
+def opening_balance(deposit: Int) -> Int: deposit

package/dist/studio-reference/calculator.md

@@ -0,0 +1,20 @@
+# A calculation with no server
+
+The studio gives you this file when the program has no actions people call and keeps no records: a calculator, a quote, a planning tool. Such a program needs no server, no database and no sign-in, so the studio asks the person nothing about where it runs, who may see records or what happens when two people act at once.
+
+## What the studio still does for it
+
+- Every rule the person states about the numbers is a law the studio runs after each change: "more debt never raises what they can borrow", "the payment is never negative". Write each one (`yichus_reference` topic `laws`) and record it with `yichus_rules`. A law checked over every input is proven; one checked on sample inputs is bounded, and the page says which.
+- The page shows the shape of the program in the person's words.
+
+## Putting it on a page
+
+Yichus's calculator path turns the calculation into a page with sliders, results, charts and a Why button beside every number. Why shows the formula, the values that went into it and the source line it came from. The path runs in the person's browser, through a separate connection to the agent (`@yichus/mcp`, set up from the QuickStart at https://yich.us/start/quickstart.html, with the calculator walkthrough at https://yich.us/start/calculator.html). Keep the same calculation file: the laws the studio checked stay true of the page's numbers.
+
+Tell the person, in product terms:
+
+- The result is one page they can host anywhere and link to. Yichus does not document embedding it inside a site builder such as Squarespace or Wix.
+- The saved page carries its own scripts and styles, so it keeps working wherever it is hosted, whatever happens to yich.us. It leaves out the formula editor the workspace has.
+- Why explains what was calculated, not whether the model's assumptions suit their situation.
+
+If the person needs their own branded page instead, build it the usual way around the same pure calculation, and say plainly that the Why buttons then are not there.

package/dist/studio-reference/consent-laws.bosatsu

@@ -0,0 +1,37 @@
+package Example/ConsentLaws
+
+from Example/Consent import Consent, OptedIn, OptedOut, merge_consent
+from Yichus/Law import Domain, Law, Obligation, Witness
+
+export (opt_out_is_sticky,)
+exposes (Example/Consent, Yichus/Law)
+
+# The person's rule: "a fan who opts out stays opted out". The input is
+# what the fan said before (nothing yet, in or out) and a new sign-up.
+
+def said(choice: Consent) -> String:
+  match choice:
+    case OptedIn: "opted in"
+    case OptedOut: "opted out"
+
+def show(input: (Option[Consent], Consent)) -> String:
+  (before, signup) = input
+  earlier = match before:
+    case Some(choice): said(choice)
+    case None: "new"
+  concat_String([earlier, ", then signs up ", said(signup)])
+
+def stays_out(input: (Option[Consent], Consent)) -> Bool:
+  (before, signup) = input
+  match before:
+    case Some(OptedOut): merge_consent(before, signup) matches OptedOut
+    case _: True
+
+def had_opted_out(input: (Option[Consent], Consent)) -> Bool:
+  (before, _) = input
+  before matches Some(OptedOut)
+
+opt_out_is_sticky = Obligation(
+  Law("a fan who opted out stays opted out", Domain("an earlier choice and a new sign-up", show, None, None), stays_out),
+  [Witness("a fan who had opted out signs up again", had_opted_out)]
+)

package/dist/studio-reference/consent.bosatsu

@@ -0,0 +1,15 @@
+package Example/Consent
+
+export (Consent(), merge_consent)
+
+# What a fan said last about texts from an artist.
+enum Consent:
+  OptedIn
+  OptedOut
+
+# A fan who signs up again keeps an opt-out: only the fan's own "start"
+# can undo it, never a form.
+def merge_consent(before: Option[Consent], signup: Consent) -> Consent:
+  match before:
+    case Some(OptedOut): OptedOut
+    case _: signup

package/dist/studio-reference/deploy-platforms.md

@@ -0,0 +1,79 @@
+# Where the app runs: how to put it online on each platform
+
+The studio gives you this file when the person has said where their app will run. The program is the same on every platform. This file says how to put it online on each one: which pieces run where, the database, and how background work starts. Tell the person about the choices in product terms, such as "your app's server", "its database" or "the page people open". Never name the programming language, and never mention file names or tool names.
+
+## What every platform has to provide
+
+`api_deploy` produces one JavaScript module, the API engine. You don't write a server of your own. The engine needs four things:
+
+- **A Node.js process that keeps running.** `startYichusApiEngine(port)` listens on `PORT` and answers every route as a POST of JSON. It also serves `GET /health`, `GET /openapi.json` and the MCP endpoint at `/mcp`. The process holds state between requests (the idempotency cache, the JWKS cache), so it has to be a server process. A platform that starts a fresh function for each request is not enough.
+- **A PostgreSQL database.** The default store, `YICHUS_STORE=memory`, loses everything on restart. In production, use `@yichus/postgres-store` through `YICHUS_STORE=adapter:<module>`. The module reads `DATABASE_URL` and a namespace from the environment, and the start script runs `migrateYichusPostgres` first. `store.mjs` and `server.mjs`, which come with this file, are both parts, ready to copy. Transactions run at SERIALIZABLE isolation and retry a bounded number of times. The database can be one the person already has, such as their Supabase project's PostgreSQL: the store keeps its rows in a schema of its own (`yichus_runtime`), apart from the old tables, and its migration needs a role that may create that schema.
+- **An identity mode.** The engine refuses to listen without `YICHUS_AUTH`:
+  - `jwt` takes `YICHUS_JWKS_URL` from any provider that publishes a JWKS, such as Auth0, Clerk, Amazon Cognito, Google Identity Platform or Firebase Auth, or Microsoft Entra ID.
+    An app that already signs people in with Supabase Auth keeps it: set `YICHUS_JWT_PROFILE=supabase-session`, `YICHUS_JWT_ISSUER=https://<project>.supabase.co/auth/v1` and `YICHUS_JWKS_URL` to that issuer plus `/.well-known/jwks.json`. A project still on its legacy JWT secret (HS256) sets `YICHUS_JWT_SECRET` to that secret as well as, or instead of, `YICHUS_JWKS_URL`; ask the person which their project uses (Supabase's JWT settings show it), and keep the secret in the engine host's environment only.
+  - `clerk-api-key` is for API keys.
+  - `proxy-header` is only for running behind a proxy you control that sets the caller's id.
+  - `dev` is never used in production.
+- **HTTPS in front.** Every platform below terminates TLS for you.
+
+Where the person chose "one server", configure the platform so that exactly one copy runs. Each platform below says how. Several platforms add copies on their own when traffic grows, and then the one-server assumption is false. If the person can't accept that limit, go back and answer the topology question "several copies".
+
+Work that takes longer than one request, waits on an outside service, or must finish later should never be one long request. Write it as a portable step program (`yichus_reference` topic `portable-programs`). Then have a scheduled job or a worker call the route that advances it. Every platform below can run that job.
+
+## Render
+
+Render runs the whole app in one place, and it is the simplest choice.
+
+- **Server:** a Web Service with `runtime: node`. The start command runs the migration, then starts the engine. Set `healthCheckPath: /health`. For "one server", set `numInstances: 1` and turn off autoscaling.
+- **Database:** Render Postgres. Connect it to the service's `DATABASE_URL` with `fromDatabase`.
+- **Page people open:** a Static Site in the same Blueprint, or the API alone if the person's users are other programs.
+- **Background work:** a Cron Job or a Background Worker that calls the advance route.
+- **Config:** one `render.yaml` Blueprint holds all of these. The `render.yaml` that comes with this file is a working start for the server and its database. Keep secrets (the auth keys and model keys) as `sync: false` environment variables set in the dashboard.
+
+## Vercel
+
+Vercel is the place for the page people open, not for the API engine. Vercel Functions start per request with time limits and share no memory, so the engine can't run there.
+
+- **Page people open:** a Next.js app on Vercel. It calls the API from the server side (route handlers or server actions), so secret keys never reach the browser. A publishable key is the only kind that may sit in browser code.
+- **Server and database:** host the engine on Render, Google Cloud Run, AWS App Runner or Azure Container Apps (see their sections). Set `YICHUS_CORS_ORIGIN` on the engine to the Vercel site's origin if the browser calls the API directly.
+- **Background work:** a Vercel Cron Job runs a function on a schedule, and that function calls the advance route on the engine's host. A cron job on the engine's host works too.
+
+- **Webhooks and public forms that save something:** a public route only reads, so a provider's webhook (Twilio, Stripe, Meta) or a sign-up form a stranger submits goes to a Vercel route handler first. It checks the provider's signature against the exact request bytes, or the form's bot check, and then calls a `worker_route` on the engine with a worker secret (`yichusSecretWorkerVerifier`, kept in both hosts' environments). The engine's rules still decide what is saved.
+
+Tell the person their app lives in two places, the page on Vercel and the server elsewhere, and why. The second place is a second account and a second monthly bill; the studio asks them where it goes.
+
+## Netlify
+
+The same shape as Vercel. Netlify Functions are per request and can't hold the engine.
+
+- **Page people open:** a static site or a framework site on Netlify that calls the API.
+- **Server and database:** on Render, Cloud Run, App Runner or Azure Container Apps. Set `YICHUS_CORS_ORIGIN` to the Netlify site's origin.
+- **Background work:** a Netlify scheduled function can call the advance route.
+
+## AWS
+
+- **Server:** AWS App Runner from a container image or from source with the Node runtime, or Amazon ECS on Fargate behind an Application Load Balancer. Either runs the engine as a long-lived process. Lambda doesn't: the engine expects to listen on a port. For "one server", set App Runner's maximum instances (or the ECS service's desired and maximum task count) to 1.
+- **Database:** Amazon RDS for PostgreSQL, or Aurora PostgreSQL. Keep `DATABASE_URL` in AWS Secrets Manager.
+- **Page people open:** AWS Amplify Hosting, or S3 with CloudFront.
+- **Identity:** Amazon Cognito user pools publish a JWKS, so use `YICHUS_AUTH=jwt` with that URL.
+- **Background work:** EventBridge Scheduler, running a task that calls the advance route.
+
+## Google Cloud
+
+- **Server:** Cloud Run, from a container image or from source with the Node runtime. Cloud Run adds instances under load. For "one server", set maximum instances to 1. Minimum instances of 1 avoids a cold start on the first request.
+- **Database:** Cloud SQL for PostgreSQL, reached through the Cloud SQL connection Cloud Run provides. Keep the connection string in Secret Manager.
+- **Page people open:** Firebase Hosting, or a second Cloud Run service.
+- **Identity:** Google Identity Platform or Firebase Auth ID tokens, with `YICHUS_AUTH=jwt` and the provider's JWKS URL.
+- **Background work:** Cloud Scheduler calling the advance route, or a Cloud Run job.
+
+## Microsoft Azure
+
+- **Server:** Azure Container Apps, or Azure App Service with the Node runtime. Container Apps scales by rules. For "one server", set minimum and maximum replicas to 1. On App Service, keep the instance count at 1.
+- **Database:** Azure Database for PostgreSQL (flexible server). Keep the connection string in Key Vault or in the app's secrets.
+- **Page people open:** Azure Static Web Apps.
+- **Identity:** Microsoft Entra ID (or Entra External ID for customers) issues JWTs. Use `YICHUS_AUTH=jwt` with its JWKS URL.
+- **Background work:** a scheduled Container Apps job that calls the advance route.
+
+## Not decided yet
+
+Recommend Render unless the person already pays for one of the others. It holds the server, the database, the page and background jobs in one Blueprint. Moving later is a configuration change, not a rewrite, because the engine and its store are the same everywhere.

package/dist/studio-reference/laws.md

@@ -0,0 +1,62 @@
+# Rules the person states, written as laws
+
+When the person says what their app must always or never do ("a fan who opts out stays opted out", "a balance never goes below zero"), write the rule as a law in a `.bosatsu` file of the app. The studio runs every law on each `yichus_next`. A law that fails keeps the app from being done, and the page shows each rule with its status.
+
+The two files that come with this topic are a complete example: `consent.bosatsu` holds the rule the app follows, and `consent-laws.bosatsu` holds the law that checks it.
+
+## Writing a law
+
+Put the decision in a pure function, then state the rule about that function:
+
+```
+opt_out_is_sticky = Obligation(
+  Law("a fan who opted out stays opted out", Domain("an earlier choice and a new sign-up", show, None, None), stays_out),
+  [Witness("a fan who had opted out signs up again", had_opted_out)]
+)
+```
+
+- `Law(name, domain, check)`: `check` takes one input and is `True` when the rule holds for it. Pack several values into a tuple, as the example does.
+- `Domain(name, show, gen, shrink)`: `show` turns an input into text for a counterexample. With `gen` and `shrink` set to `None`, inputs come from the input's type.
+- `Witness(name, check)`: an input the rule is about must occur among the inputs checked. Without one, a law that holds because nothing ever happens would look like it holds. Name every case the rule is about.
+- Export the obligation, and list the packages its type mentions in `exposes`: `exposes (Example/Consent, Yichus/Law)`.
+- `FiniteObligation(obligation, [values])` checks exactly the listed inputs and nothing else. A pass covers only those inputs, so the rule shows as holding where checked, never as proven. Use it when the inputs that matter can truly be listed. `balance.bosatsu` and `balance-listed-laws.bosatsu`, which come with this topic, show one: the law passes on each listed deposit, while a deposit of -1 breaks the rule.
+
+Import `Domain`, `Law`, `Obligation`, `Witness` and `FiniteObligation` from `Yichus/Law`.
+
+State the person's rule, never what the code does. When a law fails, change the code. Never loosen the law.
+
+## How the studio checks it
+
+Each law is checked in two ways:
+
+- **Every input**, when the input's type has finitely many values (`Bool`, enums, `Option` and tuples of them). A pass here covers every value of the type, and the rule shows as proven.
+- **The listed inputs**, when the law is a `FiniteObligation`. A pass covers only the listed values, and the rule shows as holding where checked, not proven.
+- **200 generated inputs**, for types such as `Int` and `String`. A pass here is a bounded observation, not a proof, and the page says so.
+
+When a law cannot be decided (for example, a fold it cannot finish over every input), the rule shows as not decided. Simplify the function the law calls, give it an input type with finitely many values, or list the inputs that matter with `FiniteObligation` (a bounded check, as above).
+
+Once the laws are written, record each rule with the laws that check it: `yichus_rules` with `{"rules": [{"rule": "a fan who opts out stays opted out", "laws": ["opt_out_is_sticky"]}]}`. A law is named by its binding (`opt_out_is_sticky`) or by the name in its `Law`.
+
+A rule about what a page shows, or about something outside the app, can't be a law. Tell the person it is not checked, and leave it out.
+
+## Standard functions
+
+Every package can use these without an import (`Bosatsu/Predef`). There is no `trim`, lower-casing, `any` or `filter` here. The libraries below have some of those. Write the rest from `uncons_String`, `partition_String` and the folds.
+
+- **Booleans:** `and`, `or`, `not`, `xor`, `implies`, `eq_Bool`, `cmp_Bool`. These are functions, never infix words: write `a.and(b)` or `and(a, b)`, not `a and b`.
+- **Whole numbers (`Int`):** `add`, `sub`, `mul`, `div`, `div_mod`, `mod_Int`, `gcd_Int`, `eq_Int`, `cmp_Int`, `shift_left_Int`, `shift_right_Int`, `and_Int`, `or_Int`, `xor_Int`, `not_Int`, `popcount_Int`, `int_to_String`, `string_to_Int`, `int_to_Char`, `range`
+- **Decimals (`Float64`):** `addf`, `subf`, `mulf`, `divf`, `eq_Float64`, `cmp_Float64`
+- **Text (`String`, `Char`):** `concat_String`, `length_String`, `eq_String`, `cmp_String`, `string_Order`, `partition_String`, `rpartition_String`, `uncons_String`, `tail_or_empty_String`, `char_to_String`, `char_to_Int`, `char_List_to_String`, `eq_Char`, `cmp_Char`
+- **Lists:** `map_List`, `flat_map_List`, `foldl_List`, `foldr_List`, `length_List`, `reverse`, `reverse_concat`, `concat`, `replicate_List`, `build_List`
+- **Lookup tables (`Dict`):** `empty_Dict`, `add_key`, `get_key`, `remove_key`, `items`, `clear_Dict`
+- **Comparisons:** `eq_Comparison`, `cmp_Comparison`
+- **Debugging:** `trace`
+
+`foldl_List(list, start, fn)` takes its accumulator before the function: `foldl_List(items, 0, (total, item) -> total.add(item))`.
+
+These libraries come with every program, by import:
+
+- `Bosatsu/Char`: `string_to_Char_List`, `to_ascii_lower_case`, `to_ascii_upper_case`, `eq_ignore_ascii_case`, `is_ascii_whitespace`, `is_ascii_digit`, `is_ascii_alpha`, `to_digit` and more character tests.
+- `Yichus/Num/Float64`: `int_to_Float64`, `float64_to_Int`, `powf`, `minf`, `maxf`, and the operators `+.`, `-.`, `*.`, `/.`, for money and rates worked out in decimals. Its `Float64` is its own type, apart from the one above: import every decimal function and operator you use from it, and build constants with `int_to_Float64` or `divf` rather than writing decimal literals.
+- `Yichus/Law`: `exists_List`, `filter_List`, `size_List`, `contains_String`, besides the law types.
+- `Zafu/Control/IterState`: `foldl_List` with `done` and `continue`, for a scan that stops at the first match.

package/dist/studio-reference/portable-programs.md

@@ -0,0 +1,58 @@
+# Portable programs: decisions in one pure step, effects in a rule-free engine
+
+The studio gives you this file before you write work that takes more than one step or waits on something outside the app, such as a model, a web page, a payment or another person. Write that work in this shape. The person never sees this file or the words in it. To them it is "the rules your app follows" and "the part that does the work".
+
+## The shape
+
+Split the work into two parts:
+
+- **The program** is a pure function. Given the input and the record of every request and reply so far, it answers either `Ruled(result)` or `Perform(request)`, where the request is the one thing the outside world must do next. It reads, writes and calls nothing.
+- **The engine** is the effectful code around it. It reads the record, asks the program what happens next, performs the one request, decodes the answer into a typed value, appends the exchange to the record, and asks again. It never branches on what the business wants.
+
+Name the program's two answers for what they mean, such as `Ruled` and `Perform`. `Done` already names a route's reply and a loop's end, and `Decided` a decision call's result, and an engine imports them.
+
+Because the program is pure:
+
+- Each rule lives in one place, not spread across handlers, workers and labels.
+- Replaying a stored record through the program rebuilds the same result with no effects, so any outcome can be explained after the fact. Give the program a `replay` that checks each exchange answers the request it made at that point, and refuses a record it would not have made.
+- The decision tree and the checks read the rules once, in one package.
+- Any engine (an API route, a scheduled job, a worker) can drive the same program.
+
+## Rules
+
+1. **Put the decision in the program and the doing in the engine.** The program says what happens next as a typed request. The engine checks it, performs it, and feeds the reply back.
+2. **Make requests a closed enum.** A program can ask only for what its request type names. A new kind of request is a change to that enum and to the engine, never a rule an engine adds on its own.
+3. **Carry the record with the work.** Store the input and every exchange in one row, keyed by the work itself (`owner_key(principal, order)`), never only by the person, and create it with `tx_insert` so a new request never overwrites old work. Any engine can resume from it, and any reader can replay it.
+4. **Keep engines free of rules.** An engine validates, authorises, performs effects, retries and leases. If engine code branches on a business condition, move that branch into the program.
+5. **Don't route on labels.** Never tag work "needs-review" for a later stage to interpret. The program's next request is the instruction.
+6. **Validate at the boundary.** Decode replies from models and the network with real parsers into typed values before the program sees them. A reply that doesn't decode is that request's failure arm, not a string the program inspects.
+7. **Count a retry as a new attempt.** A reply that may differ on a retry, such as a model call, is appended as a new exchange, never written over an old one.
+8. **Bound the loop.** The engine drives the program with `Yichus/IO::fold_until(range(n), start, round)`, or with `Yichus/Transaction::tx_fold_until` inside a transaction. The list of items is the bound. The analyses read the round once as the body every iteration runs, and they refuse recursive effect code.
+9. **Write each exchange in a transaction that re-reads the record.** Keep a version on the row that every write raises with `add(1)`, and append only if `eq_Int(version, seen)` says it is still the one the round read, so two rounds can never both land the same step. A round whose write did not land reads the record again; it never reports a result it did not save.
+10. **Write the round as a two-argument `def`**, local or top level, as `def round(state, item)`. That is the shape the checks read; a round returned from another function hides its reads and writes from them.
+11. **Keep the person out of outside requests.** A request key or session id names the work by an opaque reference stored on its row (`tx_new_token`), never the person's id.
+
+## Work that outlives one request
+
+When the work must finish later (the person chose "save the request and finish it later", or a reply can take minutes), the route records the input and returns. A scheduled job or a worker then runs rounds until the program answers with its result (`Ruled` in the example). `yichus_reference` topic `deploy` says how each platform starts that job. For several copies of the server, claim each round with a `Yichus/Job` lease (api_guide section "Durable jobs with Yichus/Job"), so exactly one copy performs a request.
+
+## Worked example: refunds
+
+`refund-policy.bosatsu` is the program. Small refunds are approved. A larger one asks a model judge whether the reason is covered, approves or denies on the judge's typed answer, asks again when the judge fails, and leaves the decision to a person (`Escalated`) after `most_requests` attempts. `replay` reads a stored record back.
+
+`refund-desk.bosatsu` is the engine. It has two routes and no refund rule:
+
+- A refund is kept per person and order, created once with `tx_insert` with version 0.
+- The route turns away an empty order, an empty reason and an amount of zero or less before anything is stored.
+- Each round, a local `def round(_, _)`, reads the case. If the stored refund is not the same one (`same_refund`: order, amount and reason), it turns the request away; asking again for the same refund carries on with the stored one. Otherwise it replays the record, and either saves the decision or performs the one request, decoding the model's answer with the JSON parser at the boundary (`answer_of`). A failed call keeps its reason.
+- The exchange and the decision are each written in a transaction that re-reads the case, checks its version is the one the round read, and raises it. A round whose write did not land, or that found the store busy, reads again.
+- `fold_until(range(most_requests + 2), ...)` bounds the rounds. A refund still open when they run out answers `TryAgain`, and `/refunds/status` shows the refund, its decision and how many attempts it took.
+
+`refund-test.bosatsu` holds its laws as native tests: what each record leads to, which records replay, and which model answers decode.
+
+On one server (`instances: 1`) the example verifies, with two warnings that one server accepts. With several copies of the server they are violations:
+
+- `rmw-transactions`: the round reads the case in one transaction and writes it in a later one, around the model call. The writing transaction re-reads the case and checks its version, which is the remedy the warning names. The checks recognise a version compared with `eq_Int` and raised with `add` on every write, but not yet inside a `fold_until` round, a known limit of the checks. `refund-desk-one-round.bosatsu` is the same desk run as one round, and it proves on several copies. It is not an engine to copy: one round never asks the judge twice.
+- `integrity` (`race-free:refunds`): its counterexample orders one request's `tx_insert` before or after another request's round. The race check reads the same version fence and has the same limit: the one-round desk holds `race-free:refunds` on several copies.
+
+Two copies can also both ask the judge for the same step. The version check keeps one answer, so the cost is a repeated call, and the checks do not report it.

package/dist/studio-reference/porting.md

@@ -0,0 +1,34 @@
+# Replacing an app the person already has
+
+Read this file when the new app replaces one the person already has. Reading the old app is your job. The studio never sees the old code and never records what you found there. It checks only the new program and the answers the person gives.
+
+## Read the old app first
+
+Before you write the new program, read the old app's code and find:
+
+- the records it keeps and the actions people take,
+- who may see and change each record,
+- what happens when two people act on the same record at once,
+- what it does when a server or an outside service fails.
+
+Write the new program in a folder of its own, beside the old app rather than inside it: the studio reads every `.bosatsu` file in its folder. Then build the new program so that it does the same, unless the person asks for something different. Move every rule into it, wherever the old app kept it (database policies and triggers, server routes, code in the pages): a rule left behind is one no check sees. A rule the old app enforces, or the person states ("a fan who opts out stays opted out"), becomes a law the studio runs (reference topic `laws`). Records only the old app's server touched, such as which phone number belongs to whom or which webhook deliveries it has already seen, are the app's own: the person can choose "No person, only the app's own server" for them. The old pages can stay as the screens people use, calling the new program.
+
+## Where the old app's entry points go
+
+Public routes on the new program only read. Anything the old app saves from outside a signed-in page goes through the page host instead: a webhook from a payment or messaging provider, or a public sign-up or contact form. A route handler on the page host (on Vercel, a Next.js route handler) checks the provider's signature or the bot check. It then calls a worker route on the new program, and that route holds the rules. worker-authority.md, which comes with this topic, says how to declare a worker route and how its caller signs in.
+
+## Bring the existing data over
+
+Before anything moves, list for the person every kind of record the old app keeps that the new program does not: timestamps such as first seen or consent time, a log of messages, raw payloads. Ask about each one: add it to the new program, or agree to leave it behind. A record dropped without their word is data lost.
+
+Write a one-off worker route that takes a batch of the old app's records and inserts them as the new program's typed rows in one transaction. Then write a script that posts the old database's export to it in batches. The imported rows pass the program's own types and rules, just like any other write, and a row the rules reject shows up as an error rather than as bad data. Map the old app's user ids to the ids the new sign-in gives the same people before you insert, or rows that belong to someone will not match the new program's ownership checks. Remove the route once the import is done and the person has checked the result.
+
+## Use what you found in the conversation
+
+When `yichus_next` lists a question, you may tell the person what their old app does about it, in product terms, and say where you saw it. For example: "Today each artist can see only their own fans. Do you want to keep that?" Say that this is your reading of the old code, not something the studio checked.
+
+The person still picks the answer. Record only what they decide, with `yichus_answer`. What the old app does is never their answer, and it is never a default. If the old app's behaviour is one the person would not choose, such as two people being able to overwrite each other's changes, say so plainly and let them decide.
+
+## Point at the pictures
+
+Once the new program's pictures are on the studio page, `yichus_point` can show the person which part matches which piece of their old app. The notes appear above the pictures and are labelled as yours.

package/dist/studio-reference/protocol-cases.md

@@ -0,0 +1,11 @@
+# Failure scenarios for an action
+
+The studio asks for one of these when the person chose "all or nothing" for an action that changes records in several steps, or chose a plan for an action that calls an outside service. You write the case as JSON at the path `yichus_next` names (`.yichus/cases/<question>.json`). Each `yichus_next` runs it with `api_protocol_check` against the program in the folder. You never run a command for it.
+
+A case lists the starting rows, the requests (two deliveries of one request on two servers, for example), the clock values and outside results to try, and the rules that must hold in every order the steps can run, with crashes between them. The checker tries every order within those bounds. "Holds" means it holds for every order in the case, not for every input. The page says so.
+
+Observation predicates the case names are Bosatsu functions. Put them in `.yichus/cases/*.bosatsu`: the studio passes those files to protocol checks only, so they never count as part of the app.
+
+Write the rules from the person's choice ("a withdrawal is taken once, or not at all"), never from what the code does. Then test the case on a deliberately broken copy of the program: the check must fail there with a named counterexample. A case that passes against broken code checks nothing.
+
+`withdrawal-case.json` and `withdrawal.bosatsu`, which come with this topic, are a complete case and the program it checks. Two servers deliver the same withdrawal, and the case requires exactly one durable receipt. The specification follows.

package/dist/studio-reference/{protocol-specification.txt → protocol-specification.md}

@@ -38,9 +38,11 @@ section does not change the report's universal proof result.
 ## Case format: protocol-case-1.0
 
 Every top-level field below is required. Unknown fields and duplicate JSON keys
-are rejected recursively. The complete runnable example is
-[article-retrieval.protocol.json](../icetakes/probes/article-retrieval.protocol.json).
-The replacement-worker and final-attempt cases sit beside it.
+are rejected recursively. A complete runnable example is the withdrawal case,
+`withdrawal-case.json`, with the program it checks, `withdrawal.bosatsu`. Both
+come with the studio's `protocol-case` reference; in this repository they are
+`eval/corpus/webmcp-traps/iteration-003/programs/Q15/twin/case.json` and
+`ledger.bosatsu` beside it.
 
 | Field | Contract |
 | --- | --- |
@@ -109,8 +111,8 @@ An invariant entry names a compiled `IO[Bool]` function:
 
 ```json
 {
-  "name": "current-lease-and-input",
-  "binding": "Icetakes/RetrievalInvariants::completion_has_current_lease",
+  "name": "balance-never-negative",
+  "binding": "Ledger/Invariants::balance_never_negative",
   "arguments": { "before": "before", "after": "after", "now": "time" },
   "when": "always"
 }
@@ -124,16 +126,14 @@ named argument. Selector types must equal parameter types. Predicates may read
 these databases; writes and other IO are rejected. Return predicates automatically
 require a return witness, preventing success from a wholly unobserved return path.
 
-Use `explore --agenda` and `organize` on the predicate's complete source set,
-then read their findings alongside the protocol case. The explorer does not
-see entry points selected by a separate case JSON, and generic samples of
-unrelated records may never satisfy an identity comparison. An unexecuted
-reference or constant-result observation is therefore a prompt to investigate,
-not evidence that a predicate is dead or correct. Require witnesses for the
-states the invariant describes, and test a deliberately broken implementation
-that must produce a named counterexample. The
-[Icetakes completion cases](../icetakes/probes/2026-09-25-completion-coherence.md)
-demonstrate this workflow with typed source relationships and durable receipts.
+Exploring the predicate's complete source set (`api_explore`, or the CLI's
+`explore --agenda` and `organize`) helps, but the explorer does not see entry
+points selected by a separate case JSON, and generic samples of unrelated
+records may never satisfy an identity comparison. An unexecuted reference or
+constant-result observation is therefore a prompt to investigate, not evidence
+that a predicate is dead or correct. Require witnesses for the states the
+invariant describes, and test a deliberately broken implementation that must
+produce a named counterexample.
 
 ## Trace assertions
 
@@ -191,6 +191,4 @@ history, not an exploration of every possible five-attempt history.
 The conformance suites replay actual generated JavaScript with a controlled
 adapter and compare JVM transaction and model-call behavior with model transitions. They test
 that boundary under the declared adapter contract; they do not certify a deployed
-PostgreSQL adapter, JWT implementation, external fetch service, or model provider. The retained
-[earlier retrieval report](../icetakes/probes/article-retrieval-report.json) remains
-a separate artifact and is not replaced by a runtime-test success label.
+PostgreSQL adapter, JWT implementation, external fetch service, or model provider.

package/dist/studio-reference/refund-desk-one-round.bosatsu

@@ -0,0 +1,196 @@
+package Demo/Portable/Limits/RefundDeskOneRound
+
+# A known limit of the checks, pinned (studio-engine.test.ts): this is
+# Demo/Portable/RefundDesk with one round in place of the fold_until loop.
+# Its version fence proves rmw-transactions and race-free:refunds on
+# several copies; the same fence inside the loop does not yet (register
+# D-34). Not an example to copy: one round never asks the judge twice.
+
+# The refund engine: it holds no refund rule. A refund is kept per person
+# and order. The one round reads the case, replays its record through
+# Demo/Portable/RefundPolicy to learn what happens next, and either saves
+# the decision or performs the one request that comes back (a model call),
+# decodes the answer at the boundary, and appends the exchange. Each write
+# runs in a transaction that re-reads the case and checks its version is
+# the one the round read. A lost write or a busy store ends the request
+# with TryAgain.
+
+from Bosatsu/Predef import Int, Bool, String, List, Option, Some, None, True, False, Unit, GT, cmp_Int, eq_Int, eq_String, length_List, concat, int_to_String, add
+from Yichus/IO import IO, flat_map, pure
+from Yichus/Access import Principal, AccessRule, AccessSpec, OwnerScoped, owner_key
+from Yichus/Data import Db
+from Yichus/Service import Reply, Done, Invalid, NotFound, Refused as Turned, TryAgain, handler, route, service_def, ReadPerm, WritePerm, CreatePerm
+from Yichus/Transaction import Scope, TxTable, Txn, Committed, transaction, replied, tx_table, tx_bind, tx_pure, tx_read, tx_write, tx_insert, tx_new_token
+from Yichus/OpenRouter import ProviderPolicy, ModelRequest, ModelResult, Completed, Refused, RetryableFailure, PermanentFailure, TimedOut, openrouter_call
+from Yichus/Json import JsonObject, JsonString, JsonArray, JsonBool, Parsed, InvalidJson, Rendered, RenderError, Decoded, DecodeError, parse_json, render_json, decode_bind, required_field, as_bool
+from Zafu/Control/IterState import IterState, Continue, Done as Finished
+from Demo/Portable/RefundPolicy import (
+  Refund, Request, AskJudge, Answer, Judged, JudgeFailed, Exchange, Decision, Ruled, Perform, replay, same_refund
+)
+
+export (refund_desk, access_rules, answer_of, Case(), RefundView(), RefundError(), StatusRequest())
+exposes (Demo/Portable/RefundPolicy, Yichus/Access, Yichus/OpenRouter, Yichus/Service)
+
+# One refund: an opaque reference for outside services, a version every
+# write raises, the request, every exchange so far, and the decision once
+# there is one.
+struct Case(reference: String, version: Int, refund: Refund, record: List[Exchange], decision: Option[Decision])
+
+# What the person sees of a refund: the failure reasons outside services
+# gave stay in the record.
+struct RefundView(refund: Refund, decision: Option[Decision], attempts: Int)
+
+struct StatusRequest(order: String)
+
+enum RefundError:
+  NoSuchRefund
+  # The order already has a refund request for another amount or reason.
+  AlreadyRequested
+  # The stored record is not one the refund policy makes.
+  Unreadable
+
+access_rules = AccessSpec([
+  AccessRule("refunds", OwnerScoped),
+])
+
+def cases[s](scope: Scope[s]) -> TxTable[s, Case]: tx_table(scope, "refunds")
+
+# Open the order's refund, unless it already has one.
+def open_plan[s](scope: Scope[s], key: String, refund: Refund) -> Txn[s, RefundError, Unit]:
+  reference <- tx_bind(tx_new_token(scope))
+  tx_insert(cases(scope), key, Case(reference, 0, refund, [], None))
+
+def read_plan[s](scope: Scope[s], key: String) -> Txn[s, RefundError, Option[Case]]:
+  tx_read(cases(scope), key)
+
+# Append an exchange to an undecided case, or decide it, only if its
+# version is still the one the round read; either raises the version.
+def append_plan[s](scope: Scope[s], key: String, seen: Int, exchange: Exchange) -> Txn[s, RefundError, Bool]:
+  found <- tx_bind(tx_read(cases(scope), key))
+  match found:
+    case Some(Case(reference, version, refund, record, None)):
+      if eq_Int(version, seen):
+        _ <- tx_bind(tx_write(cases(scope), key, Case(reference, version.add(1), refund, record.concat([exchange]), None)))
+        tx_pure(True)
+      else: tx_pure(False)
+    case _: tx_pure(False)
+
+def decide_plan[s](scope: Scope[s], key: String, seen: Int, decision: Decision) -> Txn[s, RefundError, Bool]:
+  found <- tx_bind(tx_read(cases(scope), key))
+  match found:
+    case Some(Case(reference, version, refund, record, None)):
+      if eq_Int(version, seen):
+        _ <- tx_bind(tx_write(cases(scope), key, Case(reference, version.add(1), refund, record, Some(decision))))
+        tx_pure(True)
+      else: tx_pure(False)
+    case _: tx_pure(False)
+
+# ---- The judge, behind the boundary ----
+
+# A model that takes a temperature, through OpenAI only.
+judge_model = "openai/gpt-4.1-mini"
+judge_policy = ProviderPolicy(["openai"], False, True, False, False)
+
+# {"covered": boolean}, and nothing else, as a strict schema needs.
+judge_schema = JsonObject([
+  ("type", JsonString("object")),
+  ("properties", JsonObject([("covered", JsonObject([("type", JsonString("boolean"))]))])),
+  ("required", JsonArray([JsonString("covered")])),
+  ("additionalProperties", JsonBool(False)),
+])
+
+# The request key names the case by its reference, never the person.
+def judge_request(reference: String, attempt: Int, reason: String, schema: String) -> ModelRequest:
+  ModelRequest(
+    "refund:${reference}:${int_to_String(attempt)}", judge_model,
+    "Decide whether the customer's reason is covered by the refund policy: damaged, never arrived, or not as described. Answer JSON.",
+    reason, "refund_judgment", schema, judge_policy, 200, 0, 20000)
+
+# The boundary: the model's text becomes a typed answer here, and anything
+# else is the request failing, with why.
+def answer_of(result: ModelResult) -> Answer:
+  match result:
+    case Completed(_, _, _, content, _, _):
+      match parse_json(content):
+        case Parsed(value):
+          match decode_bind(required_field("covered", value), field -> as_bool("covered", field)):
+            case Decoded(covered): Judged(covered)
+            case DecodeError(path, reason): JudgeFailed("its answer is not a judgment: ${path}: ${reason}")
+        case InvalidJson(reason): JudgeFailed("its answer is not JSON: ${reason}")
+    case Refused(reason): JudgeFailed("it refused: ${reason}")
+    case RetryableFailure(reason) | PermanentFailure(reason): JudgeFailed("the call failed: ${reason}")
+    case TimedOut(millis): JudgeFailed("it did not answer within ${int_to_String(millis)} ms")
+
+def perform(reference: String, attempt: Int, request: Request) -> IO[Answer]:
+  match request:
+    case AskJudge(reason):
+      match render_json(judge_schema):
+        case Rendered(schema):
+          result <- flat_map(openrouter_call(judge_request(reference, attempt, reason, schema)))
+          pure(answer_of(result))
+        case RenderError(why): pure(JudgeFailed("its schema did not render: ${why}"))
+
+# ---- Routes ----
+
+def request_refund(db: Db, p: Principal, refund: Refund) -> IO[Reply[RefundError, Decision]]:
+  Refund(order, amount, reason) = refund
+  key = owner_key(p, order)
+  # One round: what the policy says next, done. The same request again
+  # carries on with the stored refund; a different one for the same order
+  # is turned away.
+  def round(_: Unit, _: Int) -> IO[IterState[Unit, Reply[RefundError, Decision]]]:
+    found <- flat_map(transaction(db, scope -> read_plan(scope, key)))
+    match found:
+      case Committed(Some(Case(reference, seen, stored, record, decided))):
+        if same_refund(stored, refund):
+          match (decided, replay(stored, record)):
+            case (Some(decision), _): pure(Finished(Done(decision)))
+            case (None, Some(Ruled(decision))):
+              saved <- flat_map(transaction(db, scope -> decide_plan(scope, key, seen, decision)))
+              match saved:
+                case Committed(True): pure(Finished(Done(decision)))
+                case _: pure(Continue(()))
+            case (None, Some(Perform(request))):
+              answer <- flat_map(perform(reference, length_List(record), request))
+              _ <- flat_map(transaction(db, scope -> append_plan(scope, key, seen, Exchange(request, answer))))
+              pure(Continue(()))
+            case (None, None): pure(Finished(Turned("this refund's record cannot be read back", Unreadable)))
+        else: pure(Finished(Turned("this order already has a refund request for another amount or reason", AlreadyRequested)))
+      case Committed(None): pure(Finished(NotFound("no refund for this order", NoSuchRefund)))
+      # The store was busy: read again next round.
+      case _: pure(Continue(()))
+  def decide():
+    opened <- flat_map(transaction(db, scope -> open_plan(scope, key, refund)))
+    match opened:
+      case Committed(_):
+        ended <- flat_map(round((), 0))
+        match ended:
+          case Finished(reply): pure(reply)
+          case Continue(_): pure(TryAgain("the refund is still being decided; ask for its status"))
+      case _: pure(TryAgain("the refund could not be opened; try again"))
+  if eq_String(order, ""): pure(Invalid("say which order to refund"))
+  elif eq_String(reason, ""): pure(Invalid("say why the order should be refunded"))
+  else:
+    match cmp_Int(amount, 0):
+      case GT: decide()
+      case _: pure(Invalid("a refund is for an amount above zero"))
+
+def refund_status(db: Db, p: Principal, input: StatusRequest) -> IO[Reply[RefundError, RefundView]]:
+  StatusRequest(order) = input
+  found <- flat_map(transaction(db, scope -> read_plan(scope, owner_key(p, order))))
+  pure(replied(found,
+    c -> (
+      match c:
+        case Some(Case(_, _, refund, record, decision)): Done(RefundView(refund, decision, length_List(record)))
+        case None: NotFound("no refund for this order", NoSuchRefund)
+    ),
+    reason -> Turned("the refund could not be read", reason),
+    TryAgain("the store was busy; try again")))
+
+refund_desk = service_def(
+  "refunds",
+  [
+    route("/refunds/request", handler("request_refund", request_refund), [ReadPerm("refunds"), WritePerm("refunds"), CreatePerm("refunds")]),
+    route("/refunds/status", handler("refund_status", refund_status), [ReadPerm("refunds")]),
+  ]
+)