Skip to content

Todo (shared lists) ​

demos/todo — the smallest vertical that is still a real one: lists, the items on them, and sharing a list with one person by email, or inviting an address that has not joined yet. No engine, no money, two roles, two tenants.

Overview ​

Todo exists for a shape none of the other demos show — a record app with user-initiated sharing — and for a reason a todo app is usually a bad demo: the reader spends no attention on the domain, so the platform is the only thing on the page. It proves:

  • Per-record sharing is two kernel calls. Sharing "Groceries" with Björn is ctx.grant(principal, 'list:contribute', listRef) in src/module.ts; revoking it is ctx.revoke(…) with the same three arguments. The grant is entity-narrowed (this list, not all lists), delegating (the caller's own right to that list is re-checked), and transactional with the operation. Neither alternative fits: a ctx.link edge can be moved but never removed, and org membership is a whole org rather than one record — so Todo is the reference against minting an org per row to get a revoke. Read it before designing any "share this with a person" feature.
  • An address that has not joined gets an invitation, not an error. todo/share-list needs the person to exist (not_found otherwise); todo/invite shares at once when they do, and when they do not, stores a todo_invites row, queues the email in the same transaction (a failed operation sends nothing) and returns status: 'invited'. A consumer of todo.owner-joined turns each open invitation for that address into the same share when the person joins — a consumer, because a grant delegates and the person joining holds nothing on the list yet — so todo/invite checks list:contribute as well as list:manage: what the invitation will hand on is asked of the inviter up front. An invitation to a binned list waits until it is restored. todo/list-invites shows who is still waiting and todo/cancel-invite withdraws one (all three need list:manage). On a local server the queued mail is a file in .data/outbox; see Deploying.
  • Finding a list is a search, per hit. todo/search-lists looks up list.name in the kernel's search index (declared as a searchable in src/manifest.ts, like item.text), then checks list:contribute on each hit, so a list you were never shared is not a result. Archived and binned lists are left out of the index; the table's search box is offered over the active view only. todo/search-items and todo/search-list-items do the same for items.
  • A 403 wall is not an empty list. A list you were never shared reaches you neither in the listing nor by id — asking directly is refused, not answered with nothing — and the React app tells the two apart on screen.
  • It can be the app a plugin takes its people from. An admin gives a member plugin access (todo/grant-plugin-access, todo/revoke-plugin-access), and a plugin asks who a login is with todo/resolve-person, through the peer door and nowhere else: its key is held by the plugin and by no person. The admin's screen is Plugins, in the account menu (todo/list-members). Notes is the plugin. It keeps notes on items, shown on the list screen, and asks todo/vouch-access whether a person may see the list first; Todo answers from the list's owner and its shares.
  • No engine is a fact, not an omission. An item is open or done and can go back; there are no stages to skip, so there is nothing for an engine to own. What Björn may do is decided by the share on that list, not by anything about Björn.
  • The whole process, as whole files. Walkthrough: the todo app shows this vertical end to end — brief, interview, approved concept, declared model, what is derived, and the one file of business logic — pulled from demos/todo/ at build time.

At a glance ​

Package@substrat-run/demo-todo
Engines composednone — kernel only
Own tablestodo_owners · todo_lists · todo_items · todo_shares · todo_invites · todo_plugin_access
Rolesmember (create lists) and admin (a member who also decides plugin access) — everything else is an entity-narrowed grant: list:contribute on a list shared with you; list:contribute + list:manage on your own
Permission surfacePERMISSIONS.md — 7 keys, 1 module, 2 roles
AuthOIDC only — the dev issuer is a real provider you sign into by picking a name; there is no dev auth branch
AppsAPI (:8878) + one React app (:5278) for owners and invitees alike — no separate portal
StatusWorking — demo seed

The cast & what's denied ​

WhoHoldsCannot
Adaadmin, tenant one — owns Groceries and Work, and decides who may use plugins—
Björnmember, same tenant; Groceries is shared with himdelete the list, delete items, share it onward, or see Work — not in his listing, and refused by id
Cleomember in a different tenantanything of Ada's or Björn's — not by listing, not by id; the cross-tenant denial

The control beside each closed door: Björn can add bread and tick milk off, so the denials are not passing because every door is shut. Revoking his share takes effect immediately.

An invitation has one limit: it becomes a share only when the invitee signs in with an address the issuer verified. /api/me joins them on sign-in (todo/join reads ctx.verifiedEmail), and a person whose address is unverified is signed in but not joined, so their invitation keeps waiting.

Run it ​

bash
pnpm --filter @substrat-run/demo-todo dev
# API   http://localhost:8878
# web   http://localhost:5278   (sign in by picking Ada, Björn or Cleo)

test/scenario.test.ts replays the happy path and every denial above; test/server.test.ts drives the HTTP layer; test/entity-checks.test.ts generates, from the declared model, the behavioural pair that proves each handler honours its entity-scoped permission — Björn as the probe, admitted to Ada's lists one grant at a time.

Deliberately out of scope ​

Due dates, reminders and recurrence; sub-tasks, attachments, comments, re-sharing and public links. A list is shared with a person, never a link. Search covers list names and item text, not comments or attachments.