yichus 0.2.0 → 0.3.0

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

@@ -0,0 +1,79 @@
+# Where the app runs: what to build for each platform
+
+The studio gives you this file when the person has said where their app will run. It tells you what to build for that platform. Tell the person about the choices in product terms, such as "your app's server", "its database" or "the page people open". Never mention the programming language, 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. `mathstreams/deploy/store.mjs` and `mathstreams/deploy/server.mjs` in the Yichus repository show both parts. Transactions run at SERIALIZABLE isolation and retry a bounded number of times.
+- **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`. The project must sign with asymmetric keys (RS256 or ES256), not its legacy shared secret.
+  - `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. `web/quickstart-app/render.yaml` and `mathstreams/deploy/render.yaml` are working examples. 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.
+
+## 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/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,32 @@
+# 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.
+
+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. 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
+
+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/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")]),
+  ]
+)

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

@@ -0,0 +1,194 @@
+package Demo/Portable/RefundDesk
+
+# The refund engine: it holds no refund rule. A refund is kept per person
+# and order. Each round reads the case, replays its record through
+# Demo/Portable/RefundPolicy to learn what happens next, performs the one
+# request that comes back (a model call), decodes the answer at the
+# boundary, and appends the exchange in a transaction that re-reads the
+# case and checks its version is the one the round read. The decision is
+# saved the same way, and a round that lost either write reads the case
+# again.
+
+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, range, add
+from Yichus/IO import IO, flat_map, pure, fold_until
+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, most_requests
+)
+
+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 ----
+
+# Enough rounds to ask the judge every time, save the decision, and lose
+# one write to another round.
+rounds = most_requests.add(2)
+
+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(fold_until(range(rounds), (), round))
+        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")]),
+  ]
+)