@heychunky/core 0.14.0 → 0.15.0

package/register/0002-orgs/16-backfill-api-tokens-org.sql

@@ -0,0 +1,12 @@
+-- A token names its own organisation, which is what answers "whose data is
+-- this" for a request that arrives with no session behind it.
+--
+-- `created_by` keeps the person, because a token is minted by somebody and a
+-- revoked key is only findable if the register remembers who made it. The
+-- organisation is the tenancy; the user is the provenance — the same split
+-- `apps` makes between `org_id` and `owner_id`.
+update api_tokens t
+   set org_id = o.id, created_by = coalesce(t.created_by, t.user_id)
+  from users u
+  join orgs o on lower(o.name) = lower(u.username) and o.kind = 'personal'
+ where u.id = t.user_id and t.org_id is null;

package/register/README.md

@@ -0,0 +1,73 @@
+# The register's own schema
+
+`.heychunky/migrations` is how an *app's* database changes: files ride the
+branch, and `_heychunky_migrations` records what each database has applied. The
+register had no equivalent — it is not an app and has no repository of its own,
+so its schema lived only in the database and in whoever remembered typing it.
+
+It has one now. This directory is that repository, and the mechanism is the
+same one an app gets rather than a second one.
+
+```
+register/
+  0001-baseline/   the register as it stood on 2026-09-08, 22 statements
+  0002-orgs/       organisations, the tenancy boundary — 16 statements
+```
+
+**A change is a directory, its statements numbered inside it.** One statement
+per file, because the database client sends one query per request and answers a
+string holding two as though all was well. The ledger id is the path —
+`0002-orgs/05-apps-org-id.sql` — so what a database has applied reads as whole
+changes rather than as filenames somebody has to regroup mentally.
+
+Both numbers pad, because everything sorts lexically.
+
+## Applying it
+
+```
+heychunky register                        what it has, and what it owes
+heychunky register migrate --confirm      apply what it owes
+heychunky register verify                 what must be true of the rows
+```
+
+All four take `--app <app> --env <environment>` to reach a register other than
+the factory's own. There is more than one: heychunky-app runs in six
+environments and each has a database of this shape, which is how the schema
+reaches the one the tests and the dev deployment use.
+
+The files are read from the installed Core rather than from a repository at a
+ref, which is the one place this differs from an app's migrations. An app's
+files ride the branch, because "what does staging still owe" has to be
+answerable from the branch alone. The register has one database and no ladder,
+so the schema it can be brought to is the schema its CLI was built against —
+and no unreviewed local edit can reach it by accident.
+
+## Adopting, for a database that predates the ledger
+
+The baseline is a record before it is a script. The live register already held
+every statement in it, so running it would fail on the first `create table`:
+
+```
+heychunky register adopt 0001-baseline --confirm
+```
+
+That records the statements as applied having run none of them. It is **checked
+rather than trusted** — every statement's table or index is looked up in the
+catalog first, and a change that is not entirely true of the register is refused
+with the missing pieces named. The failure it guards is invisible otherwise: a
+false receipt, and then a schema change silently skipped forever after.
+
+It found real drift the first time it ran. The factory's dev register had no
+`runs` table where production did, so the honest sequence there was to apply
+that one statement and adopt the rest. A single statement id is accepted as well
+as a change name, which is how that is done.
+
+## What is deliberately not enforced
+
+**Deleting a user leaves their personal organisation behind.** `org_members`
+cascades; `orgs` does not, because an organisation outlives the people in it —
+and no foreign key can say "except the personal one". There is no delete-a-user
+path in the product today, so the invariant is left to `register verify`, which
+counts a personal organisation whose name is nobody's username. When deleting a
+user becomes a real operation it deletes the organisation too, and that check is
+what will catch anyone who forgets.