yichus 0.2.0 → 0.3.0

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

@@ -0,0 +1,97 @@
+package Demo/Portable/RefundPolicy
+
+# Every refund decision, as one pure step. Given the refund and the record
+# of every request and answer so far, `step` says what happens next: the
+# one request the engine must perform, or the decision. The engine holds
+# no refund rule of its own. `replay` reads a stored record back through
+# `step`, with no effects, and refuses a record this program would not
+# have made.
+
+from Bosatsu/Predef import Int, Bool, String, List, Option, Some, None, True, False, LT, cmp_Int, eq_Int, eq_String, length_List, foldl_List
+
+export (Refund(), Request(), Answer(), Exchange(), Decision(), Next(), step, replay, same_request, same_refund, small_refund_cents, most_requests)
+
+struct Refund(order: String, amount_cents: Int, reason: String)
+
+# The only things a refund can ask the outside world for. A new kind of
+# request is a change to this enum and to every engine, never a rule an
+# engine adds by itself.
+enum Request:
+  AskJudge(reason: String)
+
+# An answer, decoded at the boundary into a typed value before the program
+# sees it.
+enum Answer:
+  Judged(covered: Bool)
+  JudgeFailed(why: String)
+
+struct Exchange(request: Request, answer: Answer)
+
+enum Decision:
+  Approved
+  Denied
+  # The judge failed every time it was asked: a person decides.
+  Escalated
+
+# Named so as to clash with no constructor an engine imports: `Done` is a
+# route's reply and a loop's end, and `Decided` a decision call's result.
+enum Next:
+  Ruled(decision: Decision)
+  Perform(request: Request)
+
+# Refunds below this are approved without asking.
+small_refund_cents = 2000
+
+# A refund asks the judge at most this many times, then a person decides.
+most_requests = 3
+
+def last_answer(record: List[Exchange]) -> Option[Answer]:
+  foldl_List(record, None, (_, exchange) -> (
+    Exchange(_, answer) = exchange
+    Some(answer)
+  ))
+
+def step(refund: Refund, record: List[Exchange]) -> Next:
+  Refund(_, amount, reason) = refund
+  match cmp_Int(amount, small_refund_cents):
+    case LT: Ruled(Approved)
+    case _:
+      match last_answer(record):
+        case Some(Judged(True)): Ruled(Approved)
+        case Some(Judged(False)): Ruled(Denied)
+        case _:
+          # No answer yet, or the judge failed: ask again until the limit.
+          match cmp_Int(length_List(record), most_requests):
+            case LT: Perform(AskJudge(reason))
+            case _: Ruled(Escalated)
+
+def same_request(left: Request, right: Request) -> Bool:
+  match (left, right):
+    case (AskJudge(l), AskJudge(r)): eq_String(l, r)
+
+# Two requests for one order ask for the same refund.
+def same_refund(left: Refund, right: Refund) -> Bool:
+  Refund(lo, la, lr) = left
+  Refund(ro, ra, rr) = right
+  if eq_String(lo, ro):
+    if eq_Int(la, ra): eq_String(lr, rr)
+    else: False
+  else: False
+
+# A record replays when each exchange answers the request `step` made at
+# that point. The result is the step the record leads to; None means the
+# record is not one this program makes.
+def replay(refund: Refund, record: List[Exchange]) -> Option[Next]:
+  def answered(prefix: Option[List[Exchange]], exchange: Exchange) -> Option[List[Exchange]]:
+    match prefix:
+      case None: None
+      case Some(made):
+        Exchange(asked, _) = exchange
+        match step(refund, made):
+          case Perform(expected):
+            if same_request(expected, asked): Some([*made, exchange])
+            else: None
+          case Ruled(_): None
+  match foldl_List(record, Some([]), answered):
+    case Some(made): Some(step(refund, made))
+    case None: None

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

@@ -0,0 +1,75 @@
+package Demo/Portable/RefundTest
+
+# Native Bosatsu tests for the refund example: the laws of `step` and
+# `replay`, and the boundary that turns the model's text into an answer.
+# They evaluate (PortableRefundExampleTest.scala), so they pin behaviour, not just
+# types.
+
+# Test, TestSuite and Assertion come from the implicit Predef import.
+from Bosatsu/Predef import String, True, False, Bool, eq_String
+from Yichus/OpenRouter import ModelResult, Completed, TimedOut
+from Demo/Portable/RefundPolicy import (
+  Refund, AskJudge, Judged, JudgeFailed, Exchange, Approved, Denied, Escalated, Ruled, Perform, step, replay
+)
+from Demo/Portable/RefundDesk import answer_of
+
+export (tests)
+
+small = Refund("order-1", 1500, "it arrived broken")
+large = Refund("order-2", 9000, "it never arrived")
+asked = AskJudge("it never arrived")
+failed = Exchange(asked, JudgeFailed("the call failed: busy"))
+
+def completed(content: String) -> ModelResult: Completed("id", "openai/gpt-4.1-mini", "openai", content, 10, 5)
+
+def is_judged(result: ModelResult, covered: Bool, said: String) -> Test:
+  match answer_of(result):
+    case Judged(got):
+      match (covered, got):
+        case (True, True) | (False, False): Assertion(True, said)
+        case _: Assertion(False, said)
+    case JudgeFailed(_): Assertion(False, said)
+
+def is_failed(result: ModelResult, said: String) -> Test:
+  match answer_of(result):
+    case JudgeFailed(_): Assertion(True, said)
+    case Judged(_): Assertion(False, said)
+
+tests = TestSuite("Refund example", [
+  match step(small, []):
+    case Ruled(Approved): Assertion(True, "a small refund is approved without asking")
+    case _: Assertion(False, "a small refund is approved without asking"),
+  match step(large, []):
+    case Perform(AskJudge(reason)): Assertion(eq_String(reason, "it never arrived"), "a large refund asks the judge about its reason")
+    case _: Assertion(False, "a large refund asks the judge about its reason"),
+  match step(Refund("order-3", 2000, "it never arrived"), []):
+    case Perform(_): Assertion(True, "a refund of exactly the limit asks the judge")
+    case _: Assertion(False, "a refund of exactly the limit asks the judge"),
+  match step(large, [Exchange(asked, Judged(True))]):
+    case Ruled(Approved): Assertion(True, "a covered reason is approved")
+    case _: Assertion(False, "a covered reason is approved"),
+  match step(large, [Exchange(asked, Judged(False))]):
+    case Ruled(Denied): Assertion(True, "a reason not covered is denied")
+    case _: Assertion(False, "a reason not covered is denied"),
+  match step(large, [failed, failed]):
+    case Perform(_): Assertion(True, "a failed judge is asked again")
+    case _: Assertion(False, "a failed judge is asked again"),
+  match step(large, [failed, failed, failed]):
+    case Ruled(Escalated): Assertion(True, "after three failures a person decides")
+    case _: Assertion(False, "after three failures a person decides"),
+  match replay(large, [Exchange(AskJudge("something else"), Judged(True))]):
+    case None: Assertion(True, "a record answering a request the policy did not make does not replay")
+    case Some(_): Assertion(False, "a record answering a request the policy did not make does not replay"),
+  match replay(small, [Exchange(asked, Judged(True))]):
+    case None: Assertion(True, "a record past the decision does not replay")
+    case Some(_): Assertion(False, "a record past the decision does not replay"),
+  match replay(large, [failed, Exchange(asked, Judged(False))]):
+    case Some(Ruled(Denied)): Assertion(True, "a stored record replays to its decision")
+    case _: Assertion(False, "a stored record replays to its decision"),
+  is_judged(completed("{ \"covered\" : true }"), True, "any valid JSON spelling of a judgment is read"),
+  is_judged(completed("{\"covered\":false}"), False, "a judgment that the reason is not covered is read"),
+  is_failed(completed("{\"covered\":\"yes\"}"), "a judgment of the wrong type is a failure"),
+  is_failed(completed("covered"), "an answer that is not JSON is a failure"),
+  is_failed(completed("{\"covered\":true,\"covered\":false}"), "an answer that says covered twice is a failure"),
+  is_failed(TimedOut(20000), "a call that timed out is a failure"),
+])

package/dist/studio-reference/the-page.md

@@ -0,0 +1,107 @@
+# Guiding the person through the studio
+
+The person does not read documentation. The yich.us studio page only tells them what the studio is and how to connect you. Everything they need to know while building comes from you, a little at a time, when it becomes relevant. This file is what you need to know to do that. Do not read it out. Bring in one piece when the conversation reaches it, in their words, and point at the part of the page you mean with `yichus_point`.
+
+`yichus_page` shows you what the page shows them right now, and what they have on screen and last clicked.
+
+## When you give them the link
+
+Tell them three things, briefly:
+
+- The page runs on their computer only. Nobody else can open it, and it keeps the same address when you restart the studio.
+- It updates by itself after every check, so they can leave it open in a tab.
+- They can ask you about anything on it.
+
+Do not explain the sections until something appears in them.
+
+## The page, top to bottom
+
+- What you asked for: their description, exactly as recorded.
+- What is happening now: the step you are on, in one sentence.
+- Questions for you: shown while a question is open. Saving an answer there and answering you in the chat do the same thing.
+- What your program must do: each choice they made, with its status.
+- What happens when: each thing the app does, followed to every way it can end.
+- How your app is built: the parts of the app, stacked on the parts they are built from.
+- The shape of your program: a picture of the whole program as it is now.
+
+## The steps you go through
+
+The studio moves you through these steps in order, after every change. Tell the person which one you are on when it changes, in one sentence. The page's "What is happening now" says the same.
+
+1. Describe: their description is recorded word for word.
+2. Where it runs: Render, Vercel, Netlify, Amazon Web Services, Google Cloud, Microsoft Azure, or not sure yet. You build the pieces that place can run, so nothing has to be rebuilt later.
+3. Write the first version.
+4. Make it run: fix the mistakes that stop it from running.
+5. Name the parts in their words, so the questions and the pictures use their words instead of the code's.
+6. Ask them the questions the studio found.
+7. What happens when: for each thing the app does, write down in their words every way it can go and what they should get at the end. The studio checks each one.
+8. Match their answers: write the answers into the program as rules the checks hold it to.
+9. Fix whatever does not hold yet.
+10. Test failures: for answers about crashes and outside services, you write a failure scenario and the studio runs it.
+11. Done: everything they chose holds.
+
+When a check fails, the code changes, never the rule. If they ask why something is taking a while, this is usually the answer.
+
+## The questions
+
+Questions come from what the program does, never from what things are called. A new feature can bring new questions. When you ask one, say why it matters, using the question's own "why", and give every choice.
+
+| Asked when | The question | The choices |
+| --- | --- | --- |
+| The app answers requests | One server, or several copies sharing one database? | Several copies (safer, the default); one server (shown as an assumption on every result) |
+| The app saves a kind of record | Who may see one of these records, and who may change it? | Only its creator; the creator and people they share with; everyone reads, certain roles change; anyone |
+| An action reads a record and then changes it | Two people change the same record at the same moment. What should happen? | Both changes are kept; the second is refused and they try again |
+| An action saves in more than one step | If the server stops halfway, may part of the change stay saved? | All or nothing; partial is fine |
+| An action calls an outside service or an AI model | If that service is down or slow, what should the person see? | An error with nothing saved; save the request and finish it later; no preference |
+
+They can answer in the chat or on the page; both are the same. The page keeps their words next to the choice, and a later answer replaces an earlier one. The answers live in their project folder, so a new session starts from the same decisions. Tell them that once, the first time they answer.
+
+## What each status means
+
+Each choice they made shows on the page under "What your program must do", with one of these statuses. When a status changes, say what it means if they have not seen it before.
+
+| On the page | Meaning |
+| --- | --- |
+| waiting for your answer | A question they have not answered yet. Ask it. |
+| proven | Checked against every path through the program. No input, user or timing can break it. |
+| holds in every scenario checked | The failure scenario ran and stopped or failed the app at every step it covers. Strong, but limited to that scenario. |
+| holds, under an assumption | Proven only while the assumption is true, usually that exactly one server runs. A second copy can break it. |
+| decided | A choice that sets up the other checks, such as several copies of the server. |
+| broken | The check found a way it fails. You have the evidence; say in their terms what goes wrong, then fix it. |
+| the code says otherwise | The rule in the program does not match their answer yet. You update it. |
+| scenario being written | You are writing the failure scenario this answer needs. |
+| not decided yet | The check ran but could not decide. You find out why. |
+| no check needed | They chose an option that adds no check, such as "partial is fine". |
+| answered, waiting for your agent to check | They answered on the page; the result appears after your next check. |
+
+The evidence for a status comes to you, never to the page. When they ask why, explain it in product terms.
+
+## Reading the pictures with them
+
+Everything in a box marked "Yichus output" comes straight from the checks. The pictures are drawn by the checks too, but their words in italics are the names and descriptions you chose, and nothing checks those words. Never let a picture's italic words or your notes stand in for a check.
+
+"What happens when" follows each thing the app does to every way it can end.
+
+- Each question the app asks itself, such as "are you signed in?", splits into the ways it can go. A way that ends at once sits just under its question. The way that leads on furthest continues straight down after an arrow. Any other way that leads on is folded until they open it.
+- Each way ends in a mark: a bar when the request is turned away, a ring with a dot when it is answered.
+- Under the mark are the things they said should be true there. A tick means the check finds it holds, a cross means it does not, and a question mark means the check cannot say.
+- A red ending is one where something they expect is false, or where someone could reach another person's records. Green means an ending that was broken is now fixed. A dashed outline means the check cannot say.
+- "Not described yet" marks a part you have not put into words. It is still checked.
+
+"How your app is built" stacks the parts of the app. Each box is one part, in their words, with the records it changes or only looks at. Parts in a higher band are built from parts in the bands below, and requests come in at the top. A wider box is one more of the app is built on.
+
+"The shape of your program" is the system map. Requests come in on the left, and the records and outside services sit on the right. Tapping a part shows it on its own. A label that looks like code is a part you have not named yet. For a person who wants to learn the marks, https://yich.us/system-map-blocks.html explains each one, and https://yich.us/lessons/index.html has short lessons with practice.
+
+## Your notes and what you can see
+
+Your `yichus_point` notes appear as bubbles marked "Your agent · not checked", each beside the part it is about. Tell the person once that the bubbles are you pointing, like a finger on the page, and that the statuses and checks say whether something holds. They can close a bubble with its ×.
+
+You can see what the page shows and what they have in view. When they say "this one" or "the red one", call `yichus_page` before you answer. If they ask what you can see, it is only which parts of the studio page are on screen, which folds they opened, and what they last clicked, nothing else from their browser.
+
+## What the studio does not check
+
+Say these plainly when they come up, and before the person treats "done" as a guarantee:
+
+- Whether they chose well. The studio checks that the program does what they chose, not that the choice suits their users.
+- Questions it does not ask yet: payments, email, file uploads and scheduled jobs.
+- Mathematical proofs and whole-system model checking. A failure scenario covers only the steps it names.

package/dist/studio-reference/worker-authority.md

@@ -0,0 +1,159 @@
+# Worker authority in generated APIs
+
+A worker is trusted deployment code, but its network caller still needs an
+identity. `worker_route` declares that identity separately from a user's roles.
+The declaration participates in the same typed route, permission and access
+analysis as other service routes:
+
+```bosatsu
+worker_route("/complete", handler("complete", complete),
+  "judgment", ["job-manager"], [WritePerm("results")])
+```
+
+Import `worker_route`, `handler` and `WritePerm` from `Yichus/Service`.
+The named handler takes the usual `Db`, injected `Principal` and typed inputs,
+and returns `IO`. The name and role list must be statically readable, nonblank
+literals or aliases; roles are nonempty and distinct. A matching
+`GuardedOrRoles` or `PublicReadRoleWrite` resource policy still governs the
+handler's effects. Shared `Table` and `TxTable` helper parameters retain the
+calling route's exact resource and authority; a dynamic table or an ordinary
+unprivileged caller does not inherit another route's grants.
+
+The name `judgment` is a logical deployment binding. It is not a credential,
+a client-supplied field or a session claim. A user session with `job-manager`
+cannot call this route. The server adapter maps a verified machine subject to
+the declared logical name and deployment-owned role grants. Worker credentials
+can call only worker routes for that name; they cannot impersonate users on
+ordinary routes. Worker principals have an opaque namespaced identity, derived
+from the logical name and verified subject; application code must not parse it.
+
+## Secret bootstrap
+
+A deployment without a machine identity provider can give each worker a long
+random secret instead. The worker sends it as its Bearer token, and the API
+holds the same secrets in its environment. The generated engine exports the
+verifier:
+
+```js
+import {
+  attachYichusWorkerVerifier, yichusSecretWorkerVerifier, startYichusApiEngine,
+} from './engine.mjs';
+
+attachYichusWorkerVerifier(yichusSecretWorkerVerifier([
+  { name: 'ingest', secret: process.env.INGEST_WORKER_SECRET, roles: ['ingest'] },
+]));
+await startYichusApiEngine(8080);
+```
+
+Each secret is at least 32 characters, and no two workers share one. Make it with
+`openssl rand -base64 48`, or with any other source of random bytes. A token is
+compared by its SHA-256 digest against every worker's in full. Rotating a secret
+means restarting the engine with the new one. Unlike Clerk M2M tokens, a secret
+does not expire on its own, so keep it on servers only.
+
+This fits a page host such as Vercel that receives a provider's webhook or a
+public form. Its route handler checks the provider's signature, or the form's
+bot check, and then calls the engine's worker route with the secret.
+
+## Clerk bootstrap
+
+The workspace package `@yichus/clerk-worker-auth` verifies **opaque Clerk M2M
+tokens** online. It does not accept session JWTs or M2M JWTs. Configure a
+receiving machine for the API and a sending machine for the judgment worker;
+the token's scopes must include the receiving machine. Keep the receiving
+machine's secret on the API server and the sending credential on the worker.
+Grant creation and token issuance are deployment setup, not frontend actions.
+
+With Node 20 or newer, first set the listener's authentication environment
+using the [session configuration](hosted-sessions.md), then attach the adapter
+before starting the generated engine:
+
+```js
+import {
+  attachYichusWorkerVerifier, attachYichusStore, startYichusApiEngine,
+} from './engine.mjs';
+import { createClerkWorkerVerifier } from '@yichus/clerk-worker-auth';
+
+attachYichusWorkerVerifier(createClerkWorkerVerifier({
+  machineSecretKey: process.env.CLERK_API_MACHINE_SECRET,
+  targetMachine: process.env.CLERK_API_MACHINE_ID,
+  workers: [{
+    name: 'judgment',
+    subject: process.env.CLERK_JUDGMENT_MACHINE_ID,
+    roles: ['job-manager'],
+  }],
+}));
+await attachYichusStore('memory'); // Local example; configure the production store separately.
+await startYichusApiEngine(8080);
+```
+
+These are illustrative environment variable names. No Clerk resource or
+secret is provisioned by this example. The package is currently a workspace
+package; deployment packaging must include it, rather than assuming a registry
+release. The listener always requires a supported `YICHUS_AUTH` mode, even when all
+routes are worker routes; the worker verifier supplements that configuration.
+The engine refuses to start with worker routes but no worker verifier.
+
+A worker sends its opaque token as `Authorization: Bearer <token>` on the
+worker route and supplies an `Idempotency-Key` for a mutation it may retry.
+Body and result JSON come from the generated OpenAPI operation. Its
+`x-yichus-worker` extension identifies the required worker; the operation
+description lists every required grant.
+The user-authenticated `/mcp` tool list excludes worker operations. This change
+does not introduce machine authentication for that MCP endpoint. Generated
+user frontends refuse worker routes as views rather than suggesting that a
+user session could supply their authority; ordinary user views can coexist
+with separately authenticated worker routes in the same API.
+
+The in-process counterpart is
+`yichusApiEngine.handleWithWorkerToken(path, token, args, { idempotencyKey })`.
+Direct `handle`, raw role arrays and forged proof objects cannot obtain worker
+authority. Installing a verifier is a trusted host capability: client code
+running its own local engine cannot confer authority on the deployed API.
+Never ship the Clerk adapter configured with a secret into a browser.
+
+## Refusals, retries and trust limits
+
+Each request, including an idempotent replay, calls Clerk's
+`POST /v1/m2m_tokens/verify` with the receiving machine's secret. The adapter
+checks the provider's subject, target scopes, revocation and expiry. Custom
+claims never select a worker name or role. The Clerk adapter copies configured grants at construction; attaching it stores
+the verifier reference. Replacing the verifier invalidates earlier and pending
+authority proofs.
+The runtime preserves its private proof through async dispatch and rechecks
+route authority before reading an idempotency record and before executing.
+A restart during authentication refuses the in-flight request.
+
+Invalid credentials return 401; an unconfigured sender, wrong target or
+insufficient route grant returns 403. Provider outages, malformed provider
+responses and verifier failures return 503 without returning credentials or
+provider error bodies. Verification defaults to a five-second timeout and
+has no successful-authentication cache. An outage therefore prevents even a
+previously completed request from being replayed through this entry.
+
+Revocation is checked at request authentication, not continuously throughout
+an already executing request. A worker is trusted to implement its program;
+its credential does not prove that its result is correct. The handler must
+still enforce leases, fences, current revisions, payload validation and atomic
+state transitions. Static access verification covers declared service entries;
+it does not certify every exported function a custom host could invoke.
+
+## Executed evidence and Icetakes integration
+
+`ApiWorkerAuthorityTest` compiles the real Bosatsu fixture, reads its authority
+through API MCP, and exercises the generated HTTP and in-process engine with
+the actual adapter and a local Clerk stand-in. It covers forged/user authority,
+wrong sender/target, revoked retry, outage, restart and role loss before replay.
+Runtime tests also cover proof replacement and malformed verifier results;
+adapter tests cover timeout, provider failures and ignored custom grants.
+The CLI proves all nine API properties for the fixture; negative variants
+reject dynamic tables and an unprivileged caller to its shared helper.
+
+These are local fixtures, not a live Clerk deployment. Icetakes still needs
+its worker entry wired and audited against the actual stage protocol, live
+machine provisioning, token rotation and outage/retry checks. Keep its combined
+provider-dispatch path until that conversion is validated. The whole-product
+G34 deployment verification work remains separate.
+
+Provider contracts: [Clerk M2M verification](https://clerk.com/docs/reference/backend/m2m-tokens/verify)
+and [M2M tokens](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yichus",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local Bosatsu compilation, Yichus analysis, and generated apps using the WebMCP engine",
   "license": "MIT",
   "homepage": "https://yich.us",
@@ -20,7 +20,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@yichus/api-mcp": "0.1.1"
+    "@yichus/api-mcp": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",