yichus 0.3.3 → 0.3.4

package/dist/studio-reference/signups-case.json

@@ -0,0 +1,122 @@
+{
+  "schemaVersion": "protocol-case-1.0",
+  "name": "Every action that changes sign-ups keeps the shift count",
+  "assumptions": [
+    "serializable-atomic-transactions",
+    "rollback-on-abort-and-retry-exhaustion",
+    "commit-unknown-may-commit",
+    "stable-time-within-attempt",
+    "no-unmodeled-writers",
+    "preauthenticated-principals"
+  ],
+  "initialRows": {
+    "shifts": {
+      "s1": {
+        "title": "Sorting",
+        "starts_at": "9am",
+        "spots": 2,
+        "taken": 1
+      },
+      "s2": {
+        "title": "Packing",
+        "starts_at": "1pm",
+        "spots": 1,
+        "taken": 1
+      }
+    },
+    "signups": {
+      "ann": [
+        {
+          "shift_id": "s1",
+          "volunteer_name": "Ann"
+        }
+      ],
+      "bo": [
+        {
+          "shift_id": "s2",
+          "volunteer_name": "Bo"
+        }
+      ]
+    }
+  },
+  "initialize": [],
+  "requests": [
+    {
+      "instance": "ann-again",
+      "delivery": "ann-again",
+      "call": {
+        "binding": "Example/Signups::add_signup",
+        "arguments": {
+          "p": {
+            "user_id": "ann",
+            "roles": []
+          },
+          "item": {
+            "shift_id": "s1",
+            "volunteer_name": "Ann"
+          }
+        }
+      }
+    },
+    {
+      "instance": "ann-cancel",
+      "delivery": "ann-cancel",
+      "call": {
+        "binding": "Example/Signups::cancel_signup",
+        "arguments": {
+          "p": {
+            "user_id": "ann",
+            "roles": []
+          },
+          "shift_id": "s1"
+        }
+      }
+    },
+    {
+      "instance": "cy",
+      "delivery": "cy",
+      "call": {
+        "binding": "Example/Signups::add_signup",
+        "arguments": {
+          "p": {
+            "user_id": "cy",
+            "roles": []
+          },
+          "item": {
+            "shift_id": "s2",
+            "volunteer_name": "Cy"
+          }
+        }
+      }
+    }
+  ],
+  "times": [
+    1000
+  ],
+  "externalResults": {},
+  "invariants": [
+    {
+      "name": "spots-match-signups",
+      "binding": "Example/SignupsCase::spots_match_signups",
+      "arguments": {
+        "after": "after"
+      },
+      "when": "always"
+    }
+  ],
+  "traceInvariants": [],
+  "witnesses": [
+    {
+      "name": "someone-signed-up",
+      "kind": "table-nonempty",
+      "table": "signups"
+    }
+  ],
+  "bounds": {
+    "maxStates": 100000,
+    "maxDepth": 30,
+    "maxOperations": 60,
+    "maxFaults": 0,
+    "maxCrashes": 0
+  }
+}

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

@@ -0,0 +1,32 @@
+package Example/SignupsLaws
+
+from Example/Signups import Shift, take_spot
+from Yichus/Law import Domain, Law, Obligation, Witness
+
+export (never_overbooked,)
+exposes Yichus/Law
+
+def show(input: (Int, Int)) -> String:
+  (spots, taken) = input
+  concat_String(["spots ", int_to_String(spots), ", taken ", int_to_String(taken)])
+
+# "each shift has a limited number of spots": a sign-up never takes a
+# shift past its spots; a full shift turns the volunteer away.
+def never_over(input: (Int, Int)) -> Bool:
+  (spots, taken) = input
+  match take_spot(Shift("s", "t", spots, taken)):
+    case Some(Shift(_, _, _, after)): cmp_Int(after, spots) matches (LT | EQ)
+    case None: cmp_Int(taken, spots) matches (GT | EQ)
+
+def has_space(input: (Int, Int)) -> Bool:
+  (spots, taken) = input
+  cmp_Int(taken, spots) matches LT
+
+def full(input: (Int, Int)) -> Bool:
+  (spots, taken) = input
+  eq_Int(taken, spots)
+
+never_overbooked = Obligation(
+  Law("a shift never has more volunteers than spots", Domain("a shift's spots and spots taken", show, None, None), never_over),
+  [Witness("a volunteer signs up for a shift with room", has_space), Witness("a volunteer tries a full shift", full)]
+)

package/dist/studio-reference/signups.bosatsu

@@ -0,0 +1,155 @@
+package Example/Signups
+
+# A food bank's shifts: a volunteer signs up while a spot is left, and
+# cancelling gives the spot back. Every action that changes sign-ups
+# changes the shift's count in the same transaction.
+
+from Yichus/IO import IO, pure, flat_map
+from Yichus/Transaction import TxTable, Txn, stored_table, tx_bind, tx_pure, tx_read, tx_write, tx_abort, transaction, replied
+from Yichus/Access import Principal, AccessRule, AccessSpec, Public, OwnerScoped
+from Yichus/Data import Db, Table, table, db_read, db_query
+from Yichus/Service import Reply, Done, Refused, TryAgain, handler, route, service_def, ReadPerm, WritePerm, QueryPerm
+
+export (signups_api, access_rules, Shift(), Signup(), take_spot)
+exposes (Yichus/Access, Yichus/Service)
+
+struct Shift(title: String, starts_at: String, spots: Int, taken: Int)
+
+struct Signup(shift_id: String, volunteer_name: String)
+
+# The decision: a shift with `spots` places, `taken` already taken,
+# has room for one more only while taken is below spots.
+def has_room(spots: Int, taken: Int) -> Bool:
+  cmp_Int(taken, spots) matches LT
+
+# The shift after one more volunteer takes a spot, or None when full.
+def take_spot(shift: Shift) -> Option[Shift]:
+  Shift(title, starts_at, spots, taken) = shift
+  if has_room(spots, taken):
+    Some(Shift(title, starts_at, spots, taken.add(1)))
+  else:
+    None
+
+# The declared access surface. `api_verify` proves each rule against
+# the handlers below — and keeps proving it as this file is edited.
+access_rules = AccessSpec([
+  AccessRule("shifts", Public),
+  AccessRule("signups", OwnerScoped),
+])
+
+# Why a change was refused; the error body's code is its name in
+# snake_case. maybe_saved: the commit was not confirmed, so sending
+# the change again could repeat it. The others were refused before
+# anything was saved, and sending the same change again is refused again.
+enum ChangeRefused:
+  MaybeSaved
+  ShiftFull
+  NoSuchShift
+  AlreadySignedUp
+
+def unsaved[a](reason: ChangeRefused) -> Reply[ChangeRefused, a]:
+  match reason:
+    case ShiftFull: Refused("the shift is full", reason)
+    case NoSuchShift: Refused("there is no such shift", reason)
+    case AlreadySignedUp: Refused("the volunteer is already signed up for this shift", reason)
+    case MaybeSaved: Refused("the change may already be saved; list the signups before sending it again", reason)
+
+# Shifts are public: shared rows, no key discipline claimed.
+def shifts_table(db: Db) -> Table[Shift]:
+  table(db, "shifts")
+
+def get_shift(db: Db, id: String) -> IO[Shift]:
+  db_read(shifts_table(db), id)
+
+def list_shifts(db: Db) -> IO[List[Shift]]:
+  db_query(shifts_table(db))
+
+# Signups are owner-scoped: one row per user, keyed by exactly
+# Principal.user_id, holding that user's list. The analyzer proves no
+# handler can reach another caller's row.
+def signups_table(db: Db) -> Table[List[Signup]]:
+  table(db, "signups")
+
+# The same table inside a transaction. Every change to a caller's row
+# goes through one, so changes made at the same moment, on one server
+# or several, never lose one another.
+signups_rows: TxTable[s, List[Signup]] = stored_table("signups")
+
+def list_signups(db: Db, p: Principal) -> IO[List[Signup]]:
+  Principal(uid, _) = p
+  db_read(signups_table(db), uid)
+
+shifts_rows: TxTable[s, Shift] = stored_table("shifts")
+
+# A volunteer takes at most one spot on a shift.
+def signed_up(items: List[Signup], shift_id: String) -> Bool:
+  items.foldl_List(False, (seen, Signup(id, _)) -> seen.or(eq_String(id, shift_id)))
+
+def add_signup_plan[s](uid: String, item: Signup) -> Txn[s, ChangeRefused, List[Signup]]:
+  Signup(shift_id, _) = item
+  found <- tx_bind(tx_read(signups_rows, uid))
+  saved = match found:
+    case Some(saved): saved
+    case None: []
+  if signed_up(saved, shift_id):
+    tx_abort(AlreadySignedUp)
+  else:
+    shift_found <- tx_bind(tx_read(shifts_rows, shift_id))
+    match shift_found:
+      case None: tx_abort(NoSuchShift)
+      case Some(shift):
+        match take_spot(shift):
+          case None: tx_abort(ShiftFull)
+          case Some(updated):
+            _ <- tx_bind(tx_write(shifts_rows, shift_id, updated))
+            items = [item, *saved]
+            _ <- tx_bind(tx_write(signups_rows, uid, items))
+            tx_pure(items)
+
+def add_signup(db: Db, p: Principal, item: Signup) -> IO[Reply[ChangeRefused, List[Signup]]]:
+  Principal(uid, _) = p
+  outcome <- flat_map(transaction(db, _ -> add_signup_plan(uid, item)))
+  pure(replied(outcome, Done, unsaved, Refused("the signup may already be saved; list the signups before adding it again", MaybeSaved)))
+
+def without(items: List[Signup], shift_id: String) -> List[Signup]:
+  items.foldr_List((item, kept) -> (
+    Signup(id, _) = item
+    kept if eq_String(id, shift_id) else [item, *kept]
+  ), [])
+
+def give_back(shift: Shift) -> Shift:
+  Shift(title, starts_at, spots, taken) = shift
+  Shift(title, starts_at, spots, taken.sub(1))
+
+def cancel_signup_plan[s](uid: String, shift_id: String) -> Txn[s, ChangeRefused, List[Signup]]:
+  found <- tx_bind(tx_read(signups_rows, uid))
+  items = match found:
+    case Some(saved): saved
+    case None: []
+  kept = without(items, shift_id)
+  if eq_Int(length_List(kept), length_List(items)):
+    tx_pure(items)
+  else:
+    shift_found <- tx_bind(tx_read(shifts_rows, shift_id))
+    match shift_found:
+      case None: tx_abort(NoSuchShift)
+      case Some(shift):
+        _ <- tx_bind(tx_write(shifts_rows, shift_id, give_back(shift)))
+        _ <- tx_bind(tx_write(signups_rows, uid, kept))
+        tx_pure(kept)
+
+def cancel_signup(db: Db, p: Principal, shift_id: String) -> IO[Reply[ChangeRefused, List[Signup]]]:
+  Principal(uid, _) = p
+  outcome <- flat_map(transaction(db, _ -> cancel_signup_plan(uid, shift_id)))
+  pure(replied(outcome, Done, unsaved, TryAgain("the sign-up may not have been cancelled; send the request again")))
+
+signups_api = service_def(
+  "signups",
+  [
+    route("/shifts/get", handler("get_shift", get_shift), [ReadPerm("shifts")]),
+    route("/shifts", handler("list_shifts", list_shifts), [QueryPerm("shifts")]),
+    route("/signups", handler("list_signups", list_signups), [ReadPerm("signups")]),
+    route("/signups/add", handler("add_signup", add_signup), [ReadPerm("shifts"), WritePerm("shifts"), ReadPerm("signups"), WritePerm("signups")]),
+    route("/signups/cancel", handler("cancel_signup", cancel_signup), [ReadPerm("shifts"), WritePerm("shifts"), ReadPerm("signups"), WritePerm("signups")]),
+  ]
+)

package/dist/studio-reference/spots.bosatsu

@@ -0,0 +1,27 @@
+package Example/SignupsCase
+
+from Example/Signups import Shift, Signup
+from Yichus/Data import Db, table, db_query, db_read_opt
+from Yichus/IO import IO, pure, flat_map
+
+export (spots_match_signups,)
+exposes (Yichus/Data, Yichus/IO)
+
+def signed_up_for(lists: List[List[Signup]], shift_id: String) -> Int:
+  lists.foldl_List(0, (n, list) -> list.foldl_List(n, (m, Signup(id, _)) -> m.add(1) if eq_String(id, shift_id) else m))
+
+# The case's shifts, "s1" and "s2": each one's taken count is the number
+# of sign-ups for it across every volunteer, and never more than its spots.
+def shift_matches(after: Db, lists: List[List[Signup]], shift_id: String) -> IO[Bool]:
+  shift <- flat_map(db_read_opt(table(after, "shifts"), shift_id))
+  match shift:
+    case None: pure(False)
+    case Some(Shift(_, _, spots, taken)):
+      within = cmp_Int(taken, spots) matches (LT | EQ)
+      pure(within.and(eq_Int(taken, signed_up_for(lists, shift_id))))
+
+def spots_match_signups(after: Db) -> IO[Bool]:
+  lists <- flat_map(db_query(table(after, "signups")))
+  first <- flat_map(shift_matches(after, lists, "s1"))
+  second <- flat_map(shift_matches(after, lists, "s2"))
+  pure(first.and(second))

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

@@ -1,6 +1,6 @@
 # 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`.
+The person does not read documentation. The yich.us studio page only tells them what the studio is, that the QuickStart is the route for browser data apps, 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.
 
@@ -19,7 +19,7 @@ What it costs them, with what limits each cost:
 - 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.
+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 unrecorded 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.
 
@@ -56,7 +56,7 @@ The studio moves you through these steps in order, after every change. Tell the
 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.
+10. Test failures: for answers about crashes and outside services, you write a failure scenario and the studio runs it. For a rule that other actions could go around (a sign-up checks the spots left, and replacing or cancelling a sign-up does not), you write a scenario that runs every one of those actions.
 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.
@@ -90,13 +90,15 @@ Each choice they made shows on the page under "What your program must do", with
 | 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. |
+| scenario being written | You are writing the failure scenario this answer needs, or the scenario that runs every action that changes the records a rule is about. |
 | 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". |
+| no check needed | They chose an option that adds no check, such as "partial is fine", or records anyone may change, which nothing protects. |
 | answered, waiting for your agent to check | They answered on the page; the result appears after your next check. |
 
+Under each property and each rule that holds, the page says what its check does not cover ("Not checked: ..."). When the person reads a green status as "safe", read that line with them: a status says the program does what they chose, never more.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yichus",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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.5"
+    "@yichus/api-mcp": "0.1.6"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",