yichus 0.2.0 → 0.3.1

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")]),
+  ]
+)

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/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

@@ -0,0 +1,130 @@
+# 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.
+
+## 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 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.
+
+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 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.
+
+## 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. 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. 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.
+
+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) |
+| 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 |
+
+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 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. |
+
+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.