alkgit/docs/architecture/decisions/015-manage-grant-and-op-gate.md

# ADR-015: The `manage` grant tier and the repo-op gate

## Status

Accepted (resolves review 001 A-1; amends ADR-011's action set and
ADR-012 §3's gate table)

## Context

Review 001 (A-1, critical) established that ADR-012 §3's two-tier op gate
— "scope `git:admin` **or** ownership" — is not expressible in alkcall's
`AccessControl`, which composes restrictions as AND
(`required_scopes` fail hard before the ownership block ever runs;
spec.rs:94-171). The review's recommended resolution was a handler-side
check: admin scope OR `OwnershipProvider::owns(...)`.

That resolution is correct mechanically but wrong in granularity. "Owner
or admin" is the ceiling of what ownership can express, and it is the
wrong ceiling: the moment a second maintainer, a bot account, or a
collaborator needs to administer a repo they did not create, the model
has no answer short of handing out global `git:admin` (too broad) or
minting alkcall ownership records for them (wrong home — ownership is
spawn-tracking, alkcall ADR-011's mint-and-own records *who created a
resource*, not *who may administer it*). The coming platform app
(issues, PRs, per-repo admins, teams) needs per-repo administration to
be grantable, and the eventual distributed/replicator deployment needs
the same grant data to be replicable as flat state.

The mechanism to express this already exists in the corpus: ADR-011's
`authorize` policy function evaluated on the `RepoRecord` — which today
knows only `read|write`. The gap is not a missing mechanism; it is a
missing action.

## Decision

1. **The grant action set gains `manage`.** ADR-011's
   `grants: identity_id → {read, write}` becomes
   `grants: identity_id → {read, write, manage}` — a flat set, no
   hierarchy: a grant entry is the set of actions one identity holds on
   one repo, and `manage` includes read and write (a manager of the repo
   can access it; `authorize` treats `manage ⊇ write ⊇ read` for the
   actions below it).

2. **`authorize` is the single per-repo policy function for both git
   access and repo administration.** Its action domain extends:
   `authorize(record, identity: Option<&Identity>, action: read|write|manage) -> bool`.
   Semantics per action:
   - `read` — unchanged (ADR-011 §3: anonymous-first-class on Public).
   - `write` — unchanged (identity + write-or-manage grant).
   - `manage` — identity required, plus a `manage` grant. No anonymous
     and no owner-bypass path: the owner administers because repo
     creation *seeds their `manage` grant* (§3), not because identity
     has any special shape.
   - Grant-monotonicity: a `manage` grant satisfies `manage`, `write`,
     and `read` checks; a `write` grant satisfies `write` and `read`;
     `read` satisfies `read` only.

3. **The repo-op gate is: global admin scope OR `manage` grant.**
   ADR-012 §3's gate table becomes:

   | Op | Gate |
   |---|---|
   | `git/repo/create` | scope `git:repo:create` (static registry gate, unchanged) |
   | `git/repo/delete` | scope `git:admin` **or** `manage` grant (handler-evaluated) |
   | `git/repo/update` | scope `git:admin` **or** `manage` grant (handler-evaluated) |
   | `git/repo/get` (list/read) | scope `git:admin` **or** `manage` grant (handler-evaluated) |

   Mechanically this is review 001's option (a) with the OR-term
   generalized from ownership to the `manage` grant: `create` keeps its
   pure-scope `AccessControl` (`required_scopes: ["git:repo:create"]` —
   the static engine serves it, AND-composition is fine with one
   restriction); `delete`/`update`/`get` carry an empty
   `AccessControl::default()` and the handler evaluates the two-tier
   rule as one tested function in alkgit core (admin scope in
   `Identity.scopes` OR `authorize(record, identity, manage)`), denying
   with the generic FORBIDDEN. The ADR-008 rule is preserved at the op
   layer: unknown-repo and not-authorized collapse to the same denial —
   no existence oracle.

4. **Repo creation seeds the creator's `manage` grant.** `git/repo/create`
   mints alkcall ownership (alkcall ADR-011, `OwnershipStore::record` —
   unchanged; ownership remains the platform's spawn-tracking record)
   **and** writes the creator's grants as the full set `{read, write,
   manage}` in the `RepoRecord`. "Creator administers their own repos"
   becomes a grant, administered with the repo: the creator can
   `update_repo` to promote a collaborator to `manage` or demote
   themselves, using the op that already exists (`update_repo`), with no
   new op and no trait change.

5. **alkcall's `AccessControl` is not extended.** The scope-OR-grant
   composition lives handler-side, which is exactly where ADR-011 §4
   put policy ("data and policy are split across the backend seam" —
   data in the backend, policy in core). This sidesteps
   `AccessControl`'s AND-composition rather than changing it: an
   upstream family-crate change (review 001's option (c)) is not
   required, and the two-tier rule stays unit-testable in-crate instead
   of hiding in an assembly-supplied `OwnershipProvider` overload
   (option (b)'s rejected shape).

6. **Ownership no longer implies administration; grants do.** This
   supersedes the ADR-011/ADR-012 sentence "ownership never implies git
   access" — the two-data-sources rule is *retired*, not extended: repo
   records now carry the grant state both access tiers evaluate. The
   op ACL (scopes) and the record grants remain distinct *sources* —
   scopes govern platform-level capability, grants govern per-repo
   capability — but the record is now the single per-repo surface. The
   `manage` grant is the app's promotion path today (the platform app
   compiles roles/teams into flat grants and writes them with
   `update_repo`); nothing about roles, teams, or orgs enters the
   protocol crate — ADR-012 §5's split trigger stands: that is
   downstream's crate, compiling down to these flat grants.

7. **Grant keys are opaque strings; the id namespace is deliberately
   open.** Grants key on the resolved identity's stable logical id
   (ADR-011 §1), which is alkcall-cluster-local today. The id format is
   deliberately unspecified at the alkgit layer — an opaque string — so
   a downstream identity space (e.g. a `user/repo`-shaped, or
   contract-derived, globally-comparable id) can be introduced by the
   assembly/identity-provider seam without an alkgit change. Two
   identities colliding on one string is the embedder's identity
   guarantee to make, not alkgit's.

8. **Flat grants are the replication substrate.** Grants being flat
   sets keyed on opaque id strings, carried in the record, and mutated
   only through the store's `update_repo` is precisely the shape a
   future replicator/hub needs: an external authority (the planned
   contract watcher) can hold and publish grant state, and the local
   store consumes it as records. Nothing here builds replication — but
   the data model is chosen so that the external-authority case is
   `update_repo` calls from a sync writer, not a schema change.

## Consequences

- **Positive:** A-1 resolves without upstream changes; per-repo
  administration becomes grantable (the collaborator/admin case is now
  expressible); one policy function serves git access and repo
  management; the eventual app's roles/teams compile to flat grants
  with no protocol-crate growth; the record is the single per-repo authz
  surface a replicator would mirror.
- **Negative:** the grant set widens from two to three actions — a
  wire-schema decision that enters OQ-03's freeze inventory (N-3's
  schema pinning must land *after* this, so the freeze captures the
  three-action shape once); the two-data-sources consequence recorded in
  ADR-011 is partially retired, so readers of that ADR must follow the
  amendment (recorded there).
- **Neutral:** ownership records and grants coexist with distinct
  purposes (platform spawn-tracking vs per-repo capability); nothing in
  v1 reads ownership for authorization except the create-op's mint, so
  the mint could even become optional in a downstream that doesn't want
  spawn-tracking — kept in v1 because `git/repo/*` ops are family-shared
  and the record is cheap.

## References

- Review 001 A-1 (the trigger; this ADR takes its option (a) shape with
  the OR-term generalized), N-3 (the schema-pinning rider this ADR must
  precede)
- ADR-011 (the `authorize` policy function and grant storage this ADR
  amends), ADR-012 §3 (the gate table this ADR replaces), ADR-012 §5
  (the platform-crate split trigger this ADR preserves)
- ADR-007 (enforcement order), ADR-008 (unknown ≡ unauthorized at the
  op layer), ADR-010 (trait family, no-doors)
- alkcall ADR-011 (ownership mint-and-own — retained as spawn-tracking),
  `AccessControl` (spec.rs:94 — the AND-composition this ADR routes
  around, not through)
- vision.md §"Primary deployment target" (the grant set remains
  simple enough to reason about completely)
- backend.md §"The two op kinds" (op-gate restatement)