yichus 0.3.3 → 0.3.4

package/dist/studio-reference/calculator.md

@@ -5,6 +5,7 @@ The studio gives you this file when the program has no actions people call and k
 ## What the studio still does for it
 
 - Every rule the person states about the numbers is a law the studio runs after each change: "more debt never raises what they can borrow", "the payment is never negative". Write each one (`yichus_reference` topic `laws`) and record it with `yichus_rules`. A law checked over every input is proven; one checked on sample inputs is bounded, and the page says which.
+- `api_suggest_properties` drafts a law for each answer the calculation offers: a floor every answer stays at or above, for the inputs the person means. Fill in the floor and which inputs are in use from the person's words; the draft checks inconclusive until then, never broken.
 - The page shows the shape of the program in the person's words.
 
 ## Putting it on a page

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

@@ -13,9 +13,12 @@ The studio gives you this file when the person has said where their app will run
     An app that already signs people in with Supabase Auth keeps it: set `YICHUS_JWT_PROFILE=supabase-session`, `YICHUS_JWT_ISSUER=https://<project>.supabase.co/auth/v1` and `YICHUS_JWKS_URL` to that issuer plus `/.well-known/jwks.json`. A project still on its legacy JWT secret (HS256) sets `YICHUS_JWT_SECRET` to that secret as well as, or instead of, `YICHUS_JWKS_URL`; ask the person which their project uses (Supabase's JWT settings show it), and keep the secret in the engine host's environment only.
   - `clerk-api-key` is for API keys.
   - `proxy-header` is only for running behind a proxy you control that sets the caller's id.
+  - `public` is for an app where everyone may do everything and nobody signs in. The engine starts in this mode only when every action is open to everyone, and otherwise it names the ones that need to know the caller.
   - `dev` is never used in production.
 - **HTTPS in front.** Every platform below terminates TLS for you.
 
+An app that keeps no records and lets everyone use every action, such as a calculator served as an API, needs less than this. It needs no database, because the memory store has nothing to lose. It needs no identity provider either: run it with `YICHUS_AUTH=public`. It still needs a Node.js process and HTTPS. A calculator that only runs in the page people open needs no server at all (`yichus_reference` topic `calculator`).
+
 Where the person chose "one server", configure the platform so that exactly one copy runs. Each platform below says how. Several platforms add copies on their own when traffic grows, and then the one-server assumption is false. If the person can't accept that limit, go back and answer the topology question "several copies".
 
 Work that takes longer than one request, waits on an outside service, or must finish later should never be one long request. Write it as a portable step program (`yichus_reference` topic `portable-programs`). Then have a scheduled job or a worker call the route that advances it. Every platform below can run that job.

package/dist/studio-reference/mutants/double-signup.bosatsu

@@ -0,0 +1,149 @@
+package Example/Signups
+
+# A mutant of ../signups.bosatsu, kept so cases/signups-case.json is shown
+# to fail on it: the same app without the check that the volunteer already
+# holds a spot on the shift, so one volunteer takes two spots, and
+# cancelling removes both sign-ups but gives back only one spot.
+
+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")
+
+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: []
+  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/mutants/overfill.bosatsu

@@ -0,0 +1,153 @@
+package Example/Signups
+
+# A mutant of ../signups.bosatsu, kept so cases/signups-case.json is shown
+# to fail on it: sign-up takes a spot without asking take_spot whether one
+# is left, so a full shift takes one more volunteer.
+
+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):
+        Shift(title, starts_at, spots, taken) = shift
+        _ <- tx_bind(tx_write(shifts_rows, shift_id, Shift(title, starts_at, spots, taken.add(1))))
+        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/near-miss-case.json

@@ -0,0 +1,104 @@
+{
+  "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": 1,
+        "taken": 0
+      }
+    },
+    "signups": {}
+  },
+  "initialize": [],
+  "requests": [
+    {
+      "instance": "a",
+      "delivery": "a",
+      "call": {
+        "binding": "Example/Signups::add_signup",
+        "arguments": {
+          "p": {
+            "user_id": "ann",
+            "roles": []
+          },
+          "item": {
+            "shift_id": "s1",
+            "volunteer_name": "Ann"
+          }
+        }
+      }
+    },
+    {
+      "instance": "b",
+      "delivery": "b",
+      "call": {
+        "binding": "Example/Signups::put_signups",
+        "arguments": {
+          "p": {
+            "user_id": "bo",
+            "roles": []
+          },
+          "items": [
+            {
+              "shift_id": "s1",
+              "volunteer_name": "Bo"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "instance": "c",
+      "delivery": "c",
+      "call": {
+        "binding": "Example/Signups::clear_signups",
+        "arguments": {
+          "p": {
+            "user_id": "ann",
+            "roles": []
+          }
+        }
+      }
+    }
+  ],
+  "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/near-miss-signups.bosatsu

@@ -0,0 +1,139 @@
+package Example/Signups
+
+# The near miss: the same sign-up with room checked, beside the starter
+# actions that replace or clear a volunteer's list without the count.
+# The law over the room check still passes; a scenario that runs every
+# action that changes sign-ups does not.
+
+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_delete, 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, DeletePerm, 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)
+
+# A change that may or may not have been saved (the commit was not
+# confirmed) is answered so the caller knows whether sending it again
+# is safe: replacing or clearing the row again is; adding again could
+# add the item twice.
+def put_signups(db: Db, p: Principal, items: List[Signup]) -> IO[Reply[ChangeRefused, List[Signup]]]:
+  Principal(uid, _) = p
+  outcome <- flat_map(transaction(db, _ -> tx_bind(tx_write(signups_rows, uid, items), _ -> tx_pure(items))))
+  pure(replied(outcome, Done, unsaved, TryAgain("the signups may not have been saved; send them again")))
+
+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 clear_signups(db: Db, p: Principal) -> IO[Reply[ChangeRefused, Unit]]:
+  Principal(uid, _) = p
+  outcome <- flat_map(transaction(db, _ -> tx_delete(signups_rows, uid)))
+  pure(replied(outcome, Done, unsaved, TryAgain("the signups may not have been cleared; 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/put", handler("put_signups", put_signups), [WritePerm("signups")]),
+    route("/signups/add", handler("add_signup", add_signup), [ReadPerm("shifts"), WritePerm("shifts"), ReadPerm("signups"), WritePerm("signups")]),
+    route("/signups/clear", handler("clear_signups", clear_signups), [DeletePerm("signups")]),
+  ]
+)

package/dist/studio-reference/protocol-cases.md

@@ -1,6 +1,6 @@
 # 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.
+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. It also asks for one for a rule the person gave when other actions change the same records as the actions that decide with the rule's laws (see below). You write the case as JSON at the path `yichus_next` names (`.yichus/cases/<question>.json`, or `.yichus/cases/rule-<the rule's words>.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.
 
@@ -8,4 +8,10 @@ Observation predicates the case names are Bosatsu functions. Put them in `.yichu
 
 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.
 
+## A rule across actions
+
+A law checks the function it calls, so it speaks only for the actions that decide with that function. When another action changes the same records without it (a starter action that replaces or clears a list, beside the sign-up that checks the spots left), the law still passes while that action goes around the rule. So the studio asks for a scenario that sends a request to every one of those actions, from starting records where the rule matters, with the rule as an invariant over the records after every step. A case that leaves one of the actions out is not run.
+
+For a limit, the invariant says that what a record counts matches the records it counts, and never passes the limit, and it fails when a record it names is missing, so it never passes by finding nothing. `signups.bosatsu`, `signups-laws.bosatsu`, `signups-case.json` and `spots.bosatsu` are a complete example: signing up checks the spots left and turns away a second sign-up for the same shift, cancelling gives the spot back, and the case holds. The case starts from one shift with a spot left and one that is full, so both halves of the invariant can fail: it fails on `mutants/double-signup.bosatsu` (one volunteer takes two spots) and on `mutants/overfill.bosatsu` (a sign-up that never checks the spots left). `near-miss-signups.bosatsu` (`near-miss/signups.bosatsu` in the repository) with `near-miss-case.json` is the same app with the starter actions that replace or clear a volunteer's list, and the case fails there.
+
 `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.