yichus 0.3.0 → 0.3.1

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/render.yaml

@@ -0,0 +1,42 @@
+# A Render Blueprint for the engine and its database. Commit it at the root
+# of the folder Render deploys, with engine.mjs, server.mjs, store.mjs, a
+# package.json that depends on @yichus/postgres-store and pg, and the
+# package-lock.json npm writes (npm ci installs from it).
+databases:
+  - name: app-db
+    plan: basic-256mb
+services:
+  - type: web
+    name: app-api
+    runtime: node
+    plan: starter
+    # One server: keep it at 1 and leave autoscaling off. Raise it only when
+    # the person chose several copies and the studio's checks hold for that.
+    numInstances: 1
+    buildCommand: npm ci --omit=dev
+    startCommand: node server.mjs
+    # Render sends traffic to a new deploy only once this answers.
+    healthCheckPath: /health
+    envVars:
+      - key: NODE_VERSION
+        value: "22"
+      - key: DATABASE_URL
+        fromDatabase:
+          name: app-db
+          property: connectionString
+      - key: YICHUS_STORE
+        value: adapter:./store.mjs
+      - key: YICHUS_POSTGRES_NAMESPACE
+        value: app-1
+      # How the engine checks who is calling (see "An identity mode" in
+      # deploy-platforms.md). For sign-in with a provider's sessions:
+      - key: YICHUS_AUTH
+        value: jwt
+      - key: YICHUS_JWKS_URL
+        sync: false
+      # The page's origin, when a browser calls the API directly.
+      - key: YICHUS_CORS_ORIGIN
+        sync: false
+      # Only with worker routes; set it here and on the page host.
+      - key: INGEST_WORKER_SECRET
+        sync: false

package/dist/studio-reference/server.mjs

@@ -0,0 +1,33 @@
+// The start command. Applies the store's schema (it is safe to run on every
+// start), then starts the engine api_deploy generated as engine.mjs, which
+// reads YICHUS_STORE, YICHUS_AUTH and PORT from the environment and refuses
+// to listen when sign-in is not configured.
+import pg from 'pg';
+import { migrateYichusPostgres } from '@yichus/postgres-store';
+
+import { attachYichusWorkerVerifier, startYichusApiEngine, yichusSecretWorkerVerifier } from './engine.mjs';
+
+const connectionString = process.env.DATABASE_URL;
+if (!connectionString) {
+  console.error('refusing to start: DATABASE_URL is not set');
+  process.exit(1);
+}
+const pool = new pg.Pool({ connectionString });
+try {
+  await migrateYichusPostgres(pool);
+} finally {
+  await pool.end();
+}
+
+// Only for an app with worker routes: the page host's route handlers call
+// them with this secret after checking a webhook's signature or a form's
+// bot check. The roles are the grants the program's worker_route calls
+// name ("ingest" here). Leave it out when the program declares no worker_route.
+if (process.env.INGEST_WORKER_SECRET) {
+  attachYichusWorkerVerifier(yichusSecretWorkerVerifier([
+    { name: 'ingest', secret: process.env.INGEST_WORKER_SECRET, roles: ['ingest'] },
+  ]));
+}
+
+const server = await startYichusApiEngine();
+process.on('SIGTERM', () => server.close(() => process.exit(0)));

package/dist/studio-reference/store.mjs

@@ -0,0 +1,16 @@
+// The engine's store: PostgreSQL through @yichus/postgres-store, which runs
+// every transaction at SERIALIZABLE isolation and retries a bounded number
+// of times. The engine loads this module from YICHUS_STORE=adapter:./store.mjs
+// and calls the factory with no arguments, so the connection comes from the
+// environment.
+import { createYichusPostgresAdapter } from '@yichus/postgres-store';
+
+// The namespace has no default: rows of one namespace are never served
+// under another, so a missing value stops the engine.
+export function createYichusStoreAdapter() {
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) throw new Error('DATABASE_URL is not set');
+  const namespace = process.env.YICHUS_POSTGRES_NAMESPACE;
+  if (!namespace) throw new Error('YICHUS_POSTGRES_NAMESPACE is not set');
+  return createYichusPostgresAdapter({ connectionString, namespace, maxAttempts: 5 });
+}

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

@@ -4,11 +4,30 @@ The person does not read documentation. The yich.us studio page only tells them
 
 `yichus_page` shows you what the page shows them right now, and what they have on screen and last clicked.
 
+## Is this worth it?
+
+When the person asks whether the studio is worth it, compared with you building the app the usual way, answer for their app, honestly, and give a clear recommendation.
+
+You build the app either way. The difference is what they can know about it. You could often avoid these bugs yourself with careful code and tests, but tests cover the cases you thought of, and they cannot read the code or the tests. With the studio they choose the rules, a check that does not depend on you says whether each one holds, on every path through the program, and it says so again after every change you make later. Use what the checks found so far: a bug they caught in your own first draft is the clearest answer to the question.
+
+What else they get: the product decisions behind those bugs come to them, so nothing is settled by your default, and a page shows their app in their words.
+
+What it costs them, with what limits each cost:
+
+- The code is in a less common typed language. You write and maintain it, and they read no code either way, so it matters mostly if a developer will join later and have to learn it. They are not stuck with it: the rules are written down in one place, so an agent can port the app to a mainstream stack later, as cheaply as you can port one in today.
+- It runs on Yichus's engine: MIT-licensed npm packages on a host they pick, with their data in their own PostgreSQL. A built app runs nothing on Yichus's servers.
+- It is slower to start than a quick build: a few questions first, and fixes until the rules hold.
+- The checks cover the rules as written. Read each rule back to them in plain words, because a wrong rule passes. Payments, email, file uploads and scheduled jobs are not asked about yet. They can be built beside the checked part, unchecked; a download they click, such as a monthly export, is an ordinary action and is checked.
+
+Recommend it when the app keeps records several people touch and a leak, a double booking or a half-saved change would hurt: bookings, sign-ups, approvals, anything with customers, patients or money. When some parts are not covered, recommend it for the part with the records and the people. For a live app, the port is a side copy: the old app keeps running untouched while the checks run on the new one. With you doing the port it is a much smaller job than it sounds: in one rehearsal a fresh agent ported a copy of a live Next.js and Supabase app in about 45 minutes, keeping its pages and its sign-in, with every property proven (locally, on test data). For a large app you can start with the part they worry about most. If the app keeps no records at all, such as a calculator, the studio's checks have nothing to hold; Yichus's calculator path (Why on every number, checked rules about the numbers) fits better, through the separate @yichus/mcp connection and the QuickStart at https://yich.us/start/quickstart.html. Its exported page carries its own scripts, so the person can host it anywhere. It is usually not worth it for a throwaway prototype, or for code they want to keep in its current language.
+
+A scaffold is a starting point: shape its records and who may see them to the person's roles (a coordinator who sees everyone's sign-ups, a manager who approves) before you show them results.
+
 ## 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.
+- The page runs on the computer the studio runs on. Nobody else can open it, and it keeps the same address when you restart the studio. If that is not their computer (you run in a cloud container, say), they cannot open it: tell them, and describe what it shows from `yichus_page` instead.
 - It updates by itself after every check, so they can leave it open in a tab.
 - They can ask you about anything on it.
 
@@ -19,7 +38,7 @@ Do not explain the sections until something appears in them.
 - 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 your program must do: each rule they gave and 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.
@@ -29,14 +48,14 @@ Do not explain the sections until something appears in them.
 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.
+2. Write the first version.
+3. Make it run: fix the mistakes that stop it from running.
+4. Their rules: each rule they gave about what the app must always or never do becomes a law the studio runs on every check.
 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.
+6. Ask them the questions the studio found. For an app with a server, one of them is where it runs: Render, Vercel, Netlify, Amazon Web Services, Google Cloud, Microsoft Azure, or not sure yet. The app is the same wherever it runs, so this only decides how you put it online. Vercel and Netlify hold only the pages, so there they also pick where the server goes: a second service with its own bill. A calculation with no actions people call and no records has no server, and the studio does not ask.
+7. Match their answers: write the answers into the program as rules the checks hold it to.
+8. Fix whatever does not hold yet. A broken rule comes first, before describing what happens.
+9. 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.
 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.
 
@@ -49,7 +68,9 @@ Questions come from what the program does, never from what things are called. A
 | 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 |
+| Some actions are for signed-in people | How do people sign in? | Not yet; Clerk; Supabase; another provider; only programs, with keys |
+| The app saves records | Are there records somewhere today that this app must start with? | No, it starts empty; copy them in; keep the database they are in |
+| The app saves a kind of record | Who may see one of these records, and who may change it? | Only its creator; only the people a rule lets in (a team, say); no person, only the app's own server; 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 |
@@ -63,13 +84,15 @@ Each choice they made shows on the page under "What your program must do", with
 | 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. |
+| proven | Checked against every path through the program: no input, user or timing breaks the rule as written. Whether the rule is the right one is theirs to judge. |
 | 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. |
+| check being written | A rule they gave has no law that checks it yet. You write one. |
+| checked, but your app does not use it yet | Its law passes, but no action of the app reaches what the law checks, so the check says nothing about what the actions do. You make the action decide with that function. |
 | 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yichus",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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.2"
+    "@yichus/api-mcp": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",