@serfab/cadre-core 1.15.0 → 1.17.0

package/src/control-schema.ts

@@ -1,15 +1,43 @@
+import { Parser } from '@quereus/quereus';
+
 /**
- * Embedded control schema for cross-platform compatibility.
+ * The version of the declared control schema, carried in the schema text as the
+ * {@link CONTROL_SCHEMA_VERSION_TAG} tag on the `OwnerKey` table. A warm start compares
+ * it with the version the store records before applying anything
+ * (`control-schema-version.ts`, which also says why that is the version the store was
+ * created under).
  *
- * This is the authoritative runtime copy of the CadreControl authorization
- * schema. It is duplicated from `schemas/control.qsql` so that React Native and
- * other filesystem-less environments get the schema without a runtime file read.
+ * When it changes, what a new version may change, and the fixture each version keeps:
+ * docs/architecture.md → "Control schema changes and incompatible stores", enforced by
+ * `control-schema-versions.spec.ts`.
+ */
+export const CONTROL_SCHEMA_VERSION = 3;
+
+/**
+ * The first control schema version whose fixture is kept, and the oldest a store can be
+ * migrated from. Stores that record no version (written by 1.16.0 and earlier) are not
+ * migrated; docs/architecture.md says why.
+ */
+export const CONTROL_SCHEMA_BASELINE_VERSION = 3;
+
+/** The `OwnerKey` table tag that records {@link CONTROL_SCHEMA_VERSION} in the schema and in every store. */
+export const CONTROL_SCHEMA_VERSION_TAG = 'sereus.controlSchemaVersion';
+
+/**
+ * The `declare schema CadreControl { … }` statement, with its header comment.
+ *
+ * Together with {@link APPLY_CONTROL_SCHEMA} this is the authoritative runtime copy of
+ * the CadreControl authorization schema ({@link CONTROL_SCHEMA}). It is duplicated from
+ * `schemas/control.qsql` so that React Native and other filesystem-less environments
+ * get the schema without a runtime file read. Held apart from the apply because
+ * `ControlDatabase.loadSchema` declares, checks the pending changes, and only then
+ * applies.
  *
  * The two copies MUST stay identical — `control-schema-drift.spec.ts` fails the
  * build if they drift. Any edit here must be mirrored in `schemas/control.qsql`
  * and vice versa.
  */
-export const CONTROL_SCHEMA = `-- A Sereus party's cadre (its nodes) and their participation in strands (networks).
+export const CONTROL_SCHEMA_DECLARATION = `-- A Sereus party's cadre (its nodes) and their participation in strands (networks).
 --
 -- Every write is authorized by a check: an owner signs an action-tagged digest of the row
 -- (cadre-core control-authorization.ts), or a peer signs its own record. Each digest leads
@@ -21,13 +49,14 @@ export const CONTROL_SCHEMA = `-- A Sereus party's cadre (its nodes) and their p
 -- two digests scoped by the invitation token instead (FormationUsage.Authorized).
 --
 -- Rows of the guarded tables (OwnerKey, ValidationKey, Strand, StrandPartyKey, JoinedStrand,
--- JoinRequest, CadrePeer, DeviceToken, CadreInvite) carry a one-off StampId bound into their
--- add and remove digests. \`unique\` holds over live rows only, so a delete retires the stamp
--- into Revocation in the same transaction (RevocationRecorded) and an insert refuses a retired
--- stamp (NotRevoked): the never-expiring add approval cannot re-seat a removed row. A
--- legitimate re-add mints a fresh stamp and a fresh signature. CadreInvite is the one guarded
--- table that is never deleted: its tombstone withdraws the invitation while the row stays,
--- because the rows it admitted prove their membership through it.
+-- JoinRequest, CadrePeer, DeviceToken, CadreInvite, OwnerGrant) carry a one-off StampId bound
+-- into their add and remove digests. \`unique\` holds over live rows only, so a delete retires
+-- the stamp into Revocation in the same transaction (RevocationRecorded) and an insert refuses
+-- a retired stamp (NotRevoked): the never-expiring add approval cannot re-seat a removed row.
+-- A legitimate re-add mints a fresh stamp and a fresh signature. CadreInvite and OwnerGrant
+-- are the two guarded tables that are never deleted: a tombstone there withdraws the
+-- invitation or grant while the row stays, because the rows it admitted prove themselves
+-- through it.
 --
 -- A check whose expression evaluates to null passes (SQL three-valued logic), so every
 -- comparison over a nullable column that is meant to pin a value is written null-safe
@@ -47,12 +76,16 @@ export const CONTROL_SCHEMA = `-- A Sereus party's cadre (its nodes) and their p
 declare schema CadreControl {
     -- A key that can authorize control changes. A row is seated one of three ways, told apart
     -- by the vouch columns: the founding row (all three null), an owner-signed add (VouchOwner
-    -- and VouchSig pinned to the insert context, VouchUsage null), or an owner-granting
-    -- invitation redeemed by consent (VouchOwner = the invitation's IssuerKey, VouchSig null,
-    -- VouchUsage = the CadreInviteUsage row that admitted it). A reader judges the stored proof
-    -- against its node-local anchor, never against this replicated table.
+    -- and VouchSig pinned to the insert context, VouchUsage null), or an owner grant redeemed
+    -- by consent (VouchOwner = the grant's IssuerKey, VouchSig null, VouchUsage = the
+    -- OwnerGrantUsage row that seated it). A machine invitation (CadreInvite) admits a machine
+    -- and never seats a row here: a machine's identity key is never an owner key. A reader
+    -- judges the stored proof against its node-local anchor, never against this replicated
+    -- table.
     table OwnerKey (
         Key text primary key,
+        Label text null,                -- the user's name for the key ("phone", "paper backup"); bound into the
+                                        -- signed add, so a relayed approval cannot seat the key under another name
         StampId text unique,
         VouchOwner text null,
         VouchSig text null,
@@ -60,6 +93,10 @@ declare schema CadreControl {
         constraint NotRevoked check on insert (
             not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = new.StampId)
         ),
+        -- Never empty: the add digest binds coalesce(Label, ''), so an empty label would sign as none.
+        constraint LabelLength check (
+            Label is null or length(Label) between 1 and 64
+        ),
         -- The tombstone must name the removed row, not just its stamp (Revocation.RowKey).
         constraint RevocationRecorded check on delete (
             exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = old.StampId and R.RowKey = old.Key)
@@ -81,29 +118,34 @@ declare schema CadreControl {
         -- deliberately raw, the one owner read here that ignores Revocation: a machine holding only
         -- a retired owner row must still be refused a second genesis, or a removed device could
         -- re-found the party on its own copy. An owner cannot sign its own removal.
-        -- The consent branch seats an owner with no signature at all: a CadreInviteUsage row
-        -- written in the same transaction names this exact row (Key and stamp), and the
-        -- invitation it redeemed grants ownership and was issued by the stored VouchOwner. The
-        -- invitation is read from committed.CadreInvite, so an invitation cannot be seated and
-        -- redeemed in one transaction; the usage row carries the liveness conditions.
+        -- The consent branch seats an owner with no signature at all: an OwnerGrantUsage row
+        -- written in the same transaction names this exact row (Key and stamp), and the grant
+        -- it redeemed was issued by the stored VouchOwner and carries the row's label (the
+        -- issuer's choice, bound into the grant's signature). The grant is read from its
+        -- committed table, so it cannot be seated and redeemed in one transaction; the usage
+        -- row carries the liveness conditions.
         constraint Authorized check on insert, delete (
             (old.Key is null and (select count(1) from committed.OwnerKey) = 0
                 and new.VouchOwner is null and new.VouchSig is null and new.VouchUsage is null)
-                or (old.Key is null and exists (select 1 from committed.OwnerKey A where A.Key = context.OwnerKey and not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = A.StampId) and verify(digest('CadreControl.OwnerKey', 'add', party_id(), new.Key, new.StampId), context.Signature, A.Key, 'ed25519'))
+                or (old.Key is null and exists (select 1 from committed.OwnerKey A where A.Key = context.OwnerKey and not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = A.StampId) and verify(digest('CadreControl.OwnerKey', 'add', party_id(), new.Key, coalesce(new.Label, ''), new.StampId), context.Signature, A.Key, 'ed25519'))
                     and coalesce(new.VouchOwner, '') = context.OwnerKey
                     and coalesce(new.VouchSig, '') = context.Signature
                     and new.VouchUsage is null)
                 or (old.Key is null and new.VouchSig is null and new.VouchUsage is not null
                     and exists (
-                        select 1 from CadreInviteUsage U
+                        select 1 from OwnerGrantUsage U
                             where U.UsageStampId = new.VouchUsage
-                                and U.PeerKey = new.Key
-                                and U.OwnerStampId = new.StampId
-                                and exists (select 1 from committed.CadreInvite I where I.Key = U.InviteKey and I.GrantsOwner = 1 and I.IssuerKey = new.VouchOwner)
+                                and U.SeatedKey = new.Key
+                                and U.SeatedStampId = new.StampId
+                                and exists (select 1 from committed.OwnerGrant G
+                                    where G.Key = U.GrantKey and G.IssuerKey = new.VouchOwner
+                                        and coalesce(G.Label, '') = coalesce(new.Label, ''))
                     ))
                 or (new.Key is null and exists (select 1 from committed.OwnerKey A where A.Key = context.OwnerKey and A.Key <> old.Key and not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = A.StampId) and verify(digest('CadreControl.OwnerKey', 'remove', party_id(), old.Key, old.StampId), context.Signature, A.Key, 'ed25519')))
         )
-    ) with context (OwnerKey text null, Signature text null);
+    -- The tag is the version of this whole schema (cadre-core CONTROL_SCHEMA_VERSION): every edit
+    -- to the schema bumps it, and a warm start reads the store's copy before applying anything.
+    ) with tags ("${CONTROL_SCHEMA_VERSION_TAG}" = ${CONTROL_SCHEMA_VERSION}) with context (OwnerKey text null, Signature text null);
 
     -- A key that can validate a strand formation disclosure (FormationUsage.Authorized).
     table ValidationKey (
@@ -136,9 +178,12 @@ declare schema CadreControl {
         Id text primary key,                -- UUID
         MemberPrivateKey text null unique,  -- the strand's shared read secret; closed strands only
         Type text,                          -- 'o' open | 'c' closed: open gates writes in the sApp, only closed gates reads
-        FounderOwnerKey text null,          -- owner key of the machine that published the row, the founding machine
-                                            -- (cadre-node.ts launchStrand); null on a consent-seated strand, whose
-                                            -- insert carries no signature. Provenance, not content (strandRowMismatches).
+        FounderOwnerKey text null,          -- the owner key that signed the insert; null on a consent-seated strand,
+                                            -- whose insert carries no signature. Provenance, not content (strandRowMismatches).
+        FounderPeerId text null,            -- peer id of the machine that runs the founder bootstrap (cadre-node.ts
+                                            -- launchStrand), bound into the signed add; null on a consent-seated strand.
+                                            -- Not pinned to a CadrePeer row: a solo founder publishes before its own
+                                            -- row exists, and only an owner can name it. Provenance, as FounderOwnerKey.
         StampId text unique,
         constraint NotRevoked check on insert (
             not exists (select 1 from Revocation R where R.TableName = 'Strand' and R.StampId = new.StampId)
@@ -149,9 +194,10 @@ declare schema CadreControl {
         -- The consent branch below carries no signature, so an update rule would let anyone rewrite
         -- a consent-seated strand.
         constraint NoUpdate check on update (false),
-        -- Owner-signed, with FounderOwnerKey pinned to the verified signer; or consent-seated by a
-        -- FormationUsage row naming this exact row (id and stamp), written in the same transaction
-        -- (ControlDatabase.redeemInvitation). Binding the stamp is what makes a removal stick:
+        -- Owner-signed, with FounderOwnerKey pinned to the verified signer and FounderPeerId bound
+        -- into the signature; or consent-seated by a FormationUsage row naming this exact row (id
+        -- and stamp), written in the same transaction (ControlDatabase.redeemInvitation). Binding
+        -- the stamp is what makes a removal stick:
         -- the usage row outlives the strand, and keyed on the id alone it would re-authorize an
         -- unsigned re-seat under a fresh stamp. The consent branch is narrow, each clause closing
         -- one door:
@@ -164,12 +210,14 @@ declare schema CadreControl {
         -- A standalone tombstone (no accompanying delete, Revocation.Authorized) lets an owner
         -- foreclose consent-seating of an id that never existed: owner-only, and ids are random.
         constraint AuthorizedInsert check on insert (
-            (exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = A.StampId) and verify(digest('CadreControl.Strand', 'add', party_id(), new.Id, new.Type, coalesce(new.MemberPrivateKey, ''), new.StampId), context.Signature, A.Key, 'ed25519'))
-                and new.FounderOwnerKey = context.OwnerKey)
+            (exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = A.StampId) and verify(digest('CadreControl.Strand', 'add', party_id(), new.Id, new.Type, coalesce(new.MemberPrivateKey, ''), new.FounderPeerId, new.StampId), context.Signature, A.Key, 'ed25519'))
+                and new.FounderOwnerKey = context.OwnerKey
+                and new.FounderPeerId is not null)
                 or (
                     new.Type = 'o'
                     and new.MemberPrivateKey is null
                     and new.FounderOwnerKey is null
+                    and new.FounderPeerId is null
                     and exists (
                         select 1 from FormationUsage FU
                             where FU.StrandId = new.Id
@@ -623,11 +671,13 @@ declare schema CadreControl {
     -- convergence is guarded by the integration scenario strand-formation-concurrent-redemption.
     index FormationUsageByToken on FormationUsage (Token);
 
-    -- An owner-signed invitation to join this cadre, redeemable on the owner's behalf by any
-    -- member machine (ControlDatabase.redeemCadreInvite). The invitation is a keypair, not a
+    -- An owner-signed invitation to join this cadre as a machine, redeemable on the owner's
+    -- behalf by any member machine (ControlDatabase.redeemCadreInvite). It admits a machine
+    -- and grants nothing else; ownership is an OwnerGrant. The invitation is a keypair, not a
     -- bearer token: the row holds the public half and the holder proves possession by signing
-    -- with the private half (CadreInviteUsage.InvitePossessed), so the member that redeems it
-    -- can verify but never redeem it for itself. Rows are never deleted: a device admitted
+    -- with the private half (CadreInviteUsage.InvitePossessed), so a member that only relays
+    -- it can neither admit a machine of its own choosing with it nor spend its uses. Rows are
+    -- never deleted: a device admitted
     -- through one carries no owner signature of its own, and its membership is the chain
     -- invitation -> usage -> peer row, verified at read time, so the row must outlive every
     -- device it admitted. Withdrawing an invitation is an owner-signed Revocation tombstone
@@ -640,7 +690,6 @@ declare schema CadreControl {
     table CadreInvite (
         Key text primary key,       -- the invitation's ed25519 public key (base64url)
         PeerId text null,           -- the device this invitation is for; null: whoever redeems first designates it
-        GrantsOwner integer check (GrantsOwner = 0 or GrantsOwner = 1),   -- 1: redemption also seats an OwnerKey row
         ExpiresAt datetime null,
         TotalUses int null check (TotalUses >= 0),
         IssuerKey text,             -- the owner that signed the row (== insert context.OwnerKey). A reader checks it
@@ -661,7 +710,6 @@ declare schema CadreControl {
                     'CadreControl.CadreInvite', 'add', party_id(),
                     new.Key,
                     coalesce(new.PeerId, ''),
-                    cast(new.GrantsOwner as text),
                     coalesce(cast(new.ExpiresAt as text), ''),
                     coalesce(cast(new.TotalUses as text), ''),
                     new.StampId
@@ -676,8 +724,7 @@ declare schema CadreControl {
     ) with context (OwnerKey text, Signature text);
 
     -- Append-only record of cadre invitation redemptions, one row per redemption: the proof a
-    -- CadrePeer row (and, for an owner-granting invitation, an OwnerKey row) was admitted by
-    -- consent rather than by an owner signature.
+    -- CadrePeer row was admitted by consent rather than by an owner signature.
     table CadreInviteUsage (
         UsageStampId text primary key,  -- nonce minted by the redeeming device and signed into both signatures
                                         -- below. The primary key: this table never deletes, so the key alone
@@ -691,22 +738,20 @@ declare schema CadreControl {
         PeerStampId text,               -- the CadrePeer.StampId this usage seats: one row incarnation, not a peer id
                                         -- forever. Minted by the writer inside the redeeming transaction and not
                                         -- signed (FormationUsage.StrandStampId).
-        OwnerStampId text null,         -- the OwnerKey.StampId this usage seats when the invitation grants ownership
         InviteSig text,                 -- by the invitation's private key over the 'redeem' digest: proof of possession
         PeerSig text,                   -- by PeerKey over the 'consent' digest: the device agreed to join
         constraint InsertOnly check on update, delete (false),
         -- The invitation is read from the pre-transaction snapshot, so an invitation cannot be
-        -- seated and redeemed in one transaction (the OwnerKey consent branch rests on that).
+        -- seated and redeemed in one transaction (the CadrePeer consent branch rests on that).
         -- NOTE: accepted tradeoff — the use cap counts committed usage, so two redeemers racing
-        -- for a single-use invitation on different machines may both be admitted until merge,
-        -- and after merge both rows stand (FormationUsage.Authorized), for owner grants too.
-        -- Serializing would need cross-machine coordination the control plane does not have;
-        -- the mitigations are the defaults the redemption protocol sets (untargeted owner
-        -- invitations single-use with a short expiry), the targeted form for owner grants, and
-        -- the owner seeing the extra owner and removing it. Revisit if the control plane gains
-        -- a cross-machine sequencer. An issuer removed since issuing takes its outstanding
-        -- invitations with it (the committed.OwnerKey clause, which a tombstone alone
-        -- satisfies); devices it already admitted stay members.
+        -- for a single-use machine invitation on different machines may both be admitted until
+        -- merge, and after merge both rows stand (FormationUsage.Authorized). Serializing would
+        -- need cross-machine coordination the control plane does not have; the mitigations are
+        -- the single-use default, the targeted form, and the owner seeing the extra machine and
+        -- removing it. Revisit if the control plane gains a cross-machine sequencer. The owner
+        -- grant's half of this tradeoff is at OwnerGrantUsage.Authorized. An issuer removed
+        -- since issuing takes its outstanding invitations with it (the committed.OwnerKey
+        -- clause, which a tombstone alone satisfies); devices it already admitted stay members.
         constraint Authorized check on insert (
             exists (
                 select 1 from committed.CadreInvite I
@@ -731,33 +776,143 @@ declare schema CadreControl {
         ),
         -- Deferred, so the same-transaction peer insert counts: a usage row can never be held in
         -- reserve to seat a row later (FormationUsage.StrandExists). PeerKey must be the key the
-        -- peer row stores: a redemption that only completes an already-admitted device with its
-        -- OwnerKey row (no peer insert to pin it) cannot name a key other than that device's.
+        -- peer row stores, so the usage names the admitted machine's own key and no other.
         constraint PeerExists check (exists (
             select 1 from CadrePeer P where P.PeerId = new.PeerId and P.StampId = new.PeerStampId and P.PublicKey = new.PeerKey
-        )),
-        constraint OwnerExists check (
-            new.OwnerStampId is null
-                or exists (select 1 from OwnerKey K where K.Key = new.PeerKey and K.StampId = new.OwnerStampId)
-        )
+        ))
     ) with context (Now datetime);
 
     -- Serves the cap count above and the liveness reads (cadre-core countCadreInviteUsage,
     -- hasLiveCadreInvite) on an append-only table, as FormationUsageByToken does.
     index CadreInviteUsageByInvite on CadreInviteUsage (InviteKey);
 
+    -- An owner-signed grant of ownership to whoever holds the grant's private half: it seats an
+    -- OwnerKey row for a key the holder generates or already holds, and admits no machine (a
+    -- machine is admitted by a CadreInvite; peer identity and ownership are unrelated, so the
+    -- row names no peer id). The grant is a keypair as the invitation is: the row holds the
+    -- public half, the holder proves possession by signing with the private half
+    -- (OwnerGrantUsage.GrantPossessed), and the member machine that writes the redemption can
+    -- verify that signature but never produce it, so it cannot seat an owner for itself. Rows
+    -- are never deleted: a key seated through one carries no owner signature of its own, and
+    -- its proof is the chain grant -> usage -> OwnerKey row, verified at read time, so the row
+    -- must outlive every key it seated. Withdrawal is an owner-signed Revocation tombstone over
+    -- the row's stamp with the row kept (Revocation.RowIsGone); liveness is read as no
+    -- tombstone, unexpired, uses left, issuer still an owner (OwnerGrantUsage.Authorized).
+    -- NOTE: expired and withdrawn rows accumulate for the life of the party, as CadreInvite's.
+    -- The label is the issuer's: it is bound into the grant's signature and the seated OwnerKey
+    -- row must carry it (the grant branch of OwnerKey.Authorized), so a key seated on a fresh
+    -- device during recovery needs no naming prompt, and nothing the holder writes names it.
+    table OwnerGrant (
+        Key text primary key,       -- the grant's ed25519 public key (base64url)
+        Label text null,            -- the label the seated OwnerKey row carries, chosen by the issuer
+        ExpiresAt datetime null,    -- null: never. The writer defaults to a short expiry; a lifetime with
+                                    -- no end is the issuer's explicit choice (a backup grant)
+        TotalUses int null check (TotalUses >= 0),
+        IssuerKey text,             -- the owner that signed the row (== insert context.OwnerKey); a reader checks
+                                    -- it against its node-local anchor, never against the replicated OwnerKey table
+        IssuerSig text,             -- that owner's 'add' signature (== insert context.Signature), stored so any
+                                    -- reader can re-verify the row from the holder's copy or the replicated one
+        StampId text unique,
+        -- A withdrawn grant cannot be re-seated from the signed copy its holder keeps, on any
+        -- node that holds the tombstone (schema header for the node that does not).
+        constraint NotRevoked check on insert (
+            not exists (select 1 from Revocation R where R.TableName = 'OwnerGrant' and R.StampId = new.StampId)
+        ),
+        -- Never empty, as OwnerKey.LabelLength: the add digest binds coalesce(Label, '').
+        constraint LabelLength check (
+            Label is null or length(Label) between 1 and 64
+        ),
+        -- The owner signs the whole row, nullable columns as '' (cadre-core ownerGrantRowFields),
+        -- and the stored issuer pair must be the pair verified here, as CadreInvite pins its issuer.
+        constraint AuthorizedInsert check on insert (
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = A.StampId) and verify(
+                digest(
+                    'CadreControl.OwnerGrant', 'add', party_id(),
+                    new.Key,
+                    coalesce(new.Label, ''),
+                    coalesce(cast(new.ExpiresAt as text), ''),
+                    coalesce(cast(new.TotalUses as text), ''),
+                    new.StampId
+                ),
+                context.Signature, A.Key, 'ed25519'))
+            and coalesce(new.IssuerKey, '') = context.OwnerKey
+            and coalesce(new.IssuerSig, '') = context.Signature
+        ),
+        constraint NoUpdate check on update (false),
+        -- Never deleted (table comment). Withdrawal is the tombstone alone.
+        constraint NoDelete check on delete (false)
+    ) with context (OwnerKey text, Signature text);
+
+    -- Append-only record of owner-grant redemptions, one row per redemption: the proof an
+    -- OwnerKey row was seated by consent rather than by an owner signature.
+    table OwnerGrantUsage (
+        UsageStampId text primary key,  -- nonce minted by the holder and signed into both signatures below. The
+                                        -- primary key: this table never deletes, so the key alone makes a nonce
+                                        -- permanent and there is no NotRevoked pair here (CadreInviteUsage).
+        GrantKey text,                  -- the OwnerGrant redeemed
+        SeatedKey text,                 -- the owner key seated (base64url ed25519): the holder's, fresh or already held
+        SeatedStampId text,             -- the OwnerKey.StampId this usage seats: one row incarnation, not a key
+                                        -- forever. Minted by the writer inside the redeeming transaction and not
+                                        -- signed (CadreInviteUsage.PeerStampId).
+        GrantSig text,                  -- by the grant's private key over the 'redeem' digest: proof of possession
+        OwnerSig text,                  -- by SeatedKey over the 'consent' digest: the holder holds the key it seats
+        constraint InsertOnly check on update, delete (false),
+        -- The grant is read from the pre-transaction snapshot, so a grant cannot be seated and
+        -- redeemed in one transaction (the grant branch of OwnerKey.Authorized rests on that).
+        -- NOTE: accepted tradeoff — the use cap counts committed usage, so two holders of one
+        -- single-use grant redeeming on different machines may both be seated until merge, and
+        -- after merge both rows stand (CadreInviteUsage.Authorized). Serializing would need
+        -- cross-machine coordination the control plane does not have; the mitigations are the
+        -- defaults the writer sets (single use and a 15-minute expiry, a longer lifetime only
+        -- when the user chooses one) and the owner seeing the extra key in the owner-key list
+        -- and removing it. Revisit if the control plane gains a cross-machine sequencer. An
+        -- issuer removed since issuing takes its outstanding grants with it (the
+        -- committed.OwnerKey clause, which a tombstone alone satisfies); keys it already
+        -- seated stay owners.
+        constraint Authorized check on insert (
+            exists (
+                select 1 from committed.OwnerGrant G
+                    where G.Key = new.GrantKey
+                        and not exists (select 1 from Revocation R where R.TableName = 'OwnerGrant' and R.StampId = G.StampId)
+                        and (G.ExpiresAt is null or G.ExpiresAt > context.Now)
+                        and (G.TotalUses is null or G.TotalUses > (select count(1) from committed.OwnerGrantUsage U where U.GrantKey = new.GrantKey))
+                        and exists (select 1 from committed.OwnerKey K where K.Key = G.IssuerKey and not exists (select 1 from Revocation R where R.TableName = 'OwnerKey' and R.StampId = K.StampId))
+            )
+        ),
+        -- Verified against the grant key itself: the member writing the row can check this
+        -- signature but, holding only the public half, cannot produce it.
+        constraint GrantPossessed check on insert (
+            verify(digest('CadreControl.OwnerGrantUsage', 'redeem', party_id(), new.GrantKey, new.UsageStampId, new.SeatedKey),
+                   new.GrantSig, new.GrantKey, 'ed25519')
+        ),
+        -- The holder proves it holds the key being seated (CadreInviteUsage.PeerConsented).
+        constraint OwnerConsented check on insert (
+            verify(digest('CadreControl.OwnerGrantUsage', 'consent', party_id(), new.GrantKey, new.UsageStampId, new.SeatedKey),
+                   new.OwnerSig, new.SeatedKey, 'ed25519')
+        ),
+        -- Deferred, so the same-transaction OwnerKey insert counts: a usage row can never be
+        -- held in reserve to seat a row later (CadreInviteUsage.PeerExists).
+        constraint SeatedExists check (
+            exists (select 1 from OwnerKey K where K.Key = new.SeatedKey and K.StampId = new.SeatedStampId)
+        )
+    ) with context (Now datetime);
+
+    -- Serves the cap count above and the liveness reads (cadre-core countOwnerGrantUsage,
+    -- listOwnerGrantStatuses) on an append-only table, as CadreInviteUsageByInvite does.
+    index OwnerGrantUsageByGrant on OwnerGrantUsage (GrantKey);
+
     -- Append-only retirement record for the stamps of removed rows of every guarded table, with
     -- the removed row's key. Every append is owner-signed, so the growth surface is the owner
     -- keys. One singleton marker row, ('Revocation', 'ledger', 'opened'), retires nothing: an
     -- owner's connected reconcile pass files it (ControlDatabase.openRevocationLedger) so this
     -- table is never a never-written block, which the storage layer would consult the cohort
     -- for on every guarded insert and membership lookup. Readers filter on their own guarded
-    -- TableName, and queryRevocations skips it. A 'CadreInvite' row withdraws an invitation
-    -- whose row stays (CadreInvite table comment).
+    -- TableName, and queryRevocations skips it. A 'CadreInvite' or 'OwnerGrant' row withdraws
+    -- an invitation or a grant whose row stays (the table comments).
     table Revocation (
         TableName text,             -- 'OwnerKey' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'JoinedStrand' |
-                                    -- 'JoinRequest' | 'CadrePeer' | 'DeviceToken' | 'CadreInvite', or 'Revocation'
-                                    -- for the marker
+                                    -- 'JoinRequest' | 'CadrePeer' | 'DeviceToken' | 'CadreInvite' | 'OwnerGrant', or
+                                    -- 'Revocation' for the marker
         RowKey text,                -- primary key of the removed row
         StampId text,               -- the retired stamp
         ReissuedAt integer default 0,   -- bumped by an owner-signed re-issue so a tombstone committed while the
@@ -785,9 +940,9 @@ declare schema CadreControl {
         -- counts). Keyed on the stamp, not RowKey: a node that converges on a re-admission before
         -- the earlier removal's tombstone must still accept that tombstone. Retiring a stamp that
         -- never existed is harmless: stamps carry 128 random bits (generateStampId). For
-        -- 'CadreInvite' there is no row-gone test: a tombstone there is a withdrawal, and the
-        -- row stays (CadreInvite table comment). The last branch admits the marker row and
-        -- nothing else under 'Revocation'.
+        -- 'CadreInvite' and 'OwnerGrant' there is no row-gone test: a tombstone there is a
+        -- withdrawal, and the row stays (the table comments). The last branch admits the marker
+        -- row and nothing else under 'Revocation'.
         constraint RowIsGone check on insert (
             (new.TableName = 'OwnerKey' and not exists (select 1 from OwnerKey K where K.StampId = new.StampId))
                 or (new.TableName = 'CadrePeer' and not exists (select 1 from CadrePeer P where P.StampId = new.StampId))
@@ -798,6 +953,7 @@ declare schema CadreControl {
                 or (new.TableName = 'JoinRequest' and not exists (select 1 from JoinRequest J where J.StampId = new.StampId))
                 or (new.TableName = 'DeviceToken' and not exists (select 1 from DeviceToken D where D.StampId = new.StampId))
                 or (new.TableName = 'CadreInvite')
+                or (new.TableName = 'OwnerGrant')
                 or (new.TableName = 'Revocation' and new.RowKey = 'ledger' and new.StampId = 'opened')
         ),
         -- Owner-signed over the whole row under its own domain tag, so the delete's 'remove'
@@ -822,7 +978,46 @@ declare schema CadreControl {
                            context.Signature, A.Key, 'ed25519'))
         )
     ) with context (OwnerKey text, Signature text);
-}
+}`;
+
+/** The name the control schema is declared under; Quereus compares schema names without regard to case. */
+export const CONTROL_SCHEMA_NAME = 'CadreControl';
+
+/** The statement that applies {@link CONTROL_SCHEMA_DECLARATION}, run only after the store has been checked against it. */
+export const APPLY_CONTROL_SCHEMA = `apply schema ${CONTROL_SCHEMA_NAME};`;
+
+/** The whole control schema as `schemas/control.qsql` holds it: the declaration, then the apply. */
+export const CONTROL_SCHEMA = `${CONTROL_SCHEMA_DECLARATION}
 
-apply schema CadreControl;
+${APPLY_CONTROL_SCHEMA}
 `;
+
+/**
+ * The declaration statement of a control schema file (`ControlDatabaseConfig.schemaPath`),
+ * cut from the file's own text.
+ *
+ * Refuses a file that is anything other than one `declare schema CadreControl { … }`
+ * followed by one plain `apply schema CadreControl` — the shape of {@link CONTROL_SCHEMA}.
+ * `loadSchema` runs its own {@link APPLY_CONTROL_SCHEMA} once the store has been checked,
+ * so any other statement in the file, or an option on its apply, would be dropped or run
+ * unchecked.
+ */
+export function controlSchemaFileDeclaration(source: string): string {
+	const statements = new Parser().parseAll(source);
+	const [declaration, apply] = statements;
+	if (statements.length !== 2
+		|| declaration.type !== 'declareSchema' || !isControlSchemaName(declaration.schemaName)
+		|| apply.type !== 'applySchema' || !isControlSchemaName(apply.schemaName)
+		|| apply.options !== undefined || apply.toVersion !== undefined || apply.withSeed === true
+		|| declaration.loc === undefined) {
+		throw new Error(
+			`A control schema file must hold exactly \`declare schema ${CONTROL_SCHEMA_NAME} { … }\` ` +
+			`followed by \`${APPLY_CONTROL_SCHEMA}\`, the shape of schemas/control.qsql.`
+		);
+	}
+	return source.slice(declaration.loc.start.offset, declaration.loc.end.offset);
+}
+
+function isControlSchemaName(name: string | undefined): boolean {
+	return name?.toLowerCase() === CONTROL_SCHEMA_NAME.toLowerCase();
+}