@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/packages/public-runtime/src/activity/catalog.ts

@@ -0,0 +1,553 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Action catalog — the ALLOWLISTED registry of actionKeys (card D0).
+//
+// The `action` field of an ActivityEvent is NEVER a free string. It is one of
+// the keys below, and each key ships a spec: which actor kinds may emit it,
+// which source, which store sink(s) it lands in, and — critically — the
+// default-DENY allowlist of payload fields that survive redaction for it.
+//
+// WHY A FIXED CATALOG. Free-string actions make the downstream query/alert
+// surface (D5/D6/D7) intractable: you cannot build a dashboard, an alert rule,
+// or a redaction allowlist against an open vocabulary. Adding a NEW action is a
+// deliberate edit HERE (plus, for the CLI, the JS mirror + its keep-in-step
+// test — see the module README), not an ad-hoc string at a call site.
+//
+// GROUNDING. These keys were reverse-engineered from the activity surfaces that
+// already exist informally in this repo, so D1–D3 map onto them 1:1 rather than
+// inventing new vocab:
+//   • CLI command dispatch + ~/.tot/activity.log  → cli.command.*
+//   • obstacle beacon (obstacle-beacon.cjs)       → cli.obstacle.reported
+//   • local→hosted dev bridge (dev/activityStore, runtimeStore, obstacleStore)
+//                                                 → dev.*
+//   • preview serve / reconcile / Gitea webhook   → preview.* / reconcile.* / webhook.*
+//   • deploy version observed (provenance, D2)    → deploy.version_observed
+//   • ShipLoop CHANGE_STATES + admin routes
+//     (accept/reject/ship/revert/rollback/integrate/publish/invite/retire)
+//                                                 → change.* / content.* / grant.* / preview.*
+//   • app installs (STOREFRONT_APPS_DB)           → app.*
+//   • agent cohort (later)                         → agent.*
+// ─────────────────────────────────────────────────────────────────────────────
+import type { ActorKind, ActivitySource, ActivitySink } from "./event.js";
+
+/**
+ * Metadata for one catalog action. `argsAllow` / `renderedAllow` are the
+ * default-DENY payload allowlists consumed by redaction.ts: ONLY these top-level
+ * keys survive; everything else is dropped. An empty allowlist means the action
+ * stores no payload of that lane at all.
+ */
+export interface ActionSpec {
+  /** Actor kinds legitimately allowed to emit this action (ingest rejects others). */
+  actors: readonly ActorKind[];
+  /** Where the action originates. */
+  source: ActivitySource;
+  /**
+   * Store routing (the per-action half of the store decision, DECISIONS.md §8).
+   * Every action includes "logs" (universal, zero-provision firehose). High-
+   * volume/query-light actions add "analytics" (Cloudflare Analytics Engine).
+   * Low-volume/high-value lifecycle actions add "timeline" (D1, queryable ops UI).
+   */
+  sinks: readonly ActivitySink[];
+  /** Allowlist: payload.args keys that survive redaction. Default-deny. */
+  argsAllow: readonly string[];
+  /** Allowlist: payload.rendered keys that survive redaction. Default-deny. */
+  renderedAllow: readonly string[];
+  /** One-line human description for a query legend / UI. */
+  desc: string;
+}
+
+// Sink shorthands — keep the registry readable and the routing policy in one place.
+const LOGS: readonly ActivitySink[] = ["logs"];
+const HIGH_VOLUME: readonly ActivitySink[] = ["logs", "analytics"];
+const LIFECYCLE: readonly ActivitySink[] = ["logs", "timeline"];
+const PROVENANCE: readonly ActivitySink[] = ["logs", "analytics", "timeline"];
+
+/**
+ * THE CATALOG. Add a new action by adding a key here (and its JS mirror for the
+ * CLI).
+ *
+ * NAMING STANDARD (two-tier — every key is dot-namespaced; the FIRST segment is a
+ * DOMAIN from the closed set below, and there are NO un-namespaced keys):
+ *
+ *   • `<domain>.<verb>` — IMPERATIVE, for an ATOMIC action that happens in one
+ *     shot: `change.ship`, `grant.invite`, `store.connect`, `change.go_live`.
+ *   • `<domain>.<entity>.<verb|state>` — PARTICIPLE/STATE, for a TWO-PHASE / async
+ *     action that opens then closes (an invoke/result pair, or a received/terminal
+ *     span): `cli.command.invoked` + `cli.command.result`, `preview.build.requested`
+ *     + `preview.build.completed`, `webhook.reconcile.received` + `reconcile.terminal`.
+ *
+ * The DOMAIN prefix is stable (dashboards and alert rules glob on it) and MUST be one
+ * of the closed set: cli, dev, preview, webhook, reconcile, deploy, change, content,
+ * grant, store, app, agent, system.
+ *
+ * TWO-PHASE PAIRING GOING FORWARD: a NEW two-phase action uses `.invoked` / `.result`.
+ * The pre-existing `.requested` / `.completed` (preview.build.*) and `.received` /
+ * `.terminal` (webhook.reconcile.received + reconcile.terminal) pairs are GRANDFATHERED
+ * verbatim — do NOT rename them (alerts.ts hardcodes some of these literals).
+ */
+export const ACTION_CATALOG = {
+  // ── CLI (source: cli) ──────────────────────────────────────────────────────
+  // Grounded in packages/cli command dispatch + activity-log.mjs. High-volume:
+  // a developer runs dozens–hundreds of commands/day. NOTE the redaction
+  // allowlist excludes raw `args` argv (paths/emails/codes) — only the command
+  // NAME + version survive; the CLI's own activity-log.mjs already redacts
+  // --code/--token, and here we go further (deny-by-default).
+  "cli.command.invoked": {
+    actors: ["dev", "agent"], source: "cli", sinks: HIGH_VOLUME,
+    argsAllow: ["command", "subcommand", "cliVersion", "node"], renderedAllow: [],
+    desc: "A `tot` CLI command was invoked.",
+  },
+  "cli.command.result": {
+    actors: ["dev", "agent"], source: "cli", sinks: HIGH_VOLUME,
+    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs"], renderedAllow: [],
+    desc: "A `tot` CLI command finished (exit code + duration).",
+  },
+  "cli.obstacle.reported": {
+    // The obstacle beacon (obstacle-beacon.cjs) — a failed `tot start`/`tot clone`
+    // preflight. Low volume but support-valuable → also timelined.
+    actors: ["dev"], source: "cli", sinks: PROVENANCE,
+    argsAllow: ["kind", "have", "need", "cliVersion"], renderedAllow: [],
+    desc: "A local `tot start`/`tot clone` failed preflight (node-too-old, pnpm-missing, install/clone).",
+  },
+  "cli.signin.requested": {
+    actors: ["dev"], source: "cli", sinks: LOGS,
+    argsAllow: ["cliVersion"], renderedAllow: [],
+    desc: "The CLI requested a browserless sign-in code.",
+  },
+
+  // ── Local dev loop → hosted bridge (source: cli) ───────────────────────────
+  // Grounded in dev/activityStore.ts, runtimeStore.ts. Heartbeats are the single
+  // highest-volume stream (one every few seconds while `tot dev` runs) → analytics
+  // only, never timelined. Local paths (cwd/url/editor) are DROPPED by allowlist.
+  "dev.runtime.heartbeat": {
+    actors: ["dev"], source: "cli", sinks: HIGH_VOLUME,
+    argsAllow: ["cliVersion", "runnerVersion", "os", "osVersion", "arch"], renderedAllow: [],
+    desc: "The developer's local dev loop reported a liveness heartbeat.",
+  },
+  "dev.file.changed": {
+    actors: ["dev"], source: "cli", sinks: HIGH_VOLUME,
+    // Raw file path is DROPPED (local, may carry names); only the event kind +
+    // the server-composed business description (activityStore.describeActivity)
+    // survive.
+    argsAllow: ["event"], renderedAllow: ["description"],
+    desc: "A file save was reported by the local dev loop.",
+  },
+  "dev.serve.up": {
+    actors: ["dev"], source: "cli", sinks: LOGS,
+    argsAllow: [], renderedAllow: [],
+    desc: "The developer's store came up locally.",
+  },
+
+  // ── Preview / reconcile / webhook (source: server) ─────────────────────────
+  "preview.serve": {
+    actors: ["system"], source: "server", sinks: HIGH_VOLUME,
+    argsAllow: [], renderedAllow: [],
+    desc: "A preview environment served a request (per-request, high volume).",
+  },
+  "preview.build.requested": {
+    actors: ["admin", "dev", "system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: [],
+    desc: "A preview build was requested.",
+  },
+  "preview.build.completed": {
+    actors: ["system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "result"], renderedAllow: [],
+    desc: "A preview build finished (result: ok|failed).",
+  },
+  "preview.override": {
+    // D9: an AUTHENTICATED operator accepted the risk of a blocking-safety finding for a
+    // specific commit (/api/preview/override), letting the reconcile materialize past it.
+    // Cockpit-gated (signed-in real developer capability + session tenant), so the acting
+    // cohort is owner→merchant, staff→admin, or a signed-in developer→dev. The required
+    // justification is operator-authored → rendered (truncated + canary-scanned).
+    actors: ["admin", "merchant", "dev"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["commit"], renderedAllow: ["reason"],
+    desc: "An operator overrode a blocking-safety finding for a preview commit (auditable).",
+  },
+  "webhook.reconcile.received": {
+    // Gitea candidate-reconcile webhook (api/changes/candidate-reconcile.ts). Low
+    // volume (one per PR push, NOT per request) and the lifecycle PARTNER of
+    // `reconcile.terminal` — timelined so D7's reconcile-hang watchdog can correlate
+    // "received" against "terminal" for the same changeId and detect an ABSENCE.
+    actors: ["system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["repo", "action", "branch", "changeId"], renderedAllow: [],
+    desc: "A Gitea reconcile webhook was received.",
+  },
+  "reconcile.terminal": {
+    // A reconcile reached a terminal state (reconciled|blocked|failed). Low
+    // volume, high value → timelined for the ops UI (D5).
+    actors: ["system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "result", "evidenceStatus"], renderedAllow: [],
+    desc: "A candidate reconcile reached a terminal state.",
+  },
+  "candidate.closed": {
+    // A `pull_request` `closed` webhook drove a candidate to its TERMINAL status
+    // (candidate-reconcile.ts): `merged` (squash-merged) or `closed` (closed
+    // unmerged), so the row leaves the operator's review queue. Low volume (one
+    // per PR close), high value — the end-of-life marker for a candidate's timeline.
+    actors: ["system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "merged", "result", "status"], renderedAllow: [],
+    desc: "A merged/closed PR webhook transitioned a candidate to a terminal state.",
+  },
+  "prebuild.dispatched": {
+    // T1 background pre-build (docs/epics/proposed/storefront-instant-static-rollback.md
+    // Addendum §B): a successful candidate reconcile fired (or failed to fire) the
+    // materialize+validate+STAGE-ONLY repository_dispatch for a static-publish
+    // tenant (candidate-reconcile.ts). Fail-open by design — this never gates the
+    // candidate reaching `ready`; recorded so a stuck/never-dispatched prebuild is
+    // observable rather than silently absent.
+    actors: ["system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "headSha"], renderedAllow: [],
+    desc: "A candidate's background static-prebuild dispatch (stage-only) succeeded or failed.",
+  },
+
+  // ── Deploy provenance (source: server or cli) — card D2 ────────────────────
+  "deploy.version_observed": {
+    actors: ["system", "dev"], source: "server", sinks: PROVENANCE,
+    argsAllow: ["version", "commit", "env", "observedFrom"], renderedAllow: [],
+    desc: "A deployed worker version/commit was observed (provenance).",
+  },
+  "publish.readiness_evidence.recorded": {
+    actors: ["system"], source: "server", sinks: PROVENANCE,
+    argsAllow: ["routes", "cfFailures", "statusMismatches", "targetHealthy"], renderedAllow: [],
+    desc: "Go-live readiness dual-run evidence was recorded for a tenant (u9 producer).",
+  },
+
+  // ── ShipLoop change lifecycle (source: ui/server) ──────────────────────────
+  // 1:1 with the admin ship routes + CHANGE_STATES (change-record.ts). Low
+  // volume, high value, needs joins/point-queries → timelined. `reason` is
+  // operator-authored justification → goes through rendered (truncated +
+  // canary-scanned), never core.
+  "change.submit": {
+    actors: ["dev", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: ["title"],
+    desc: "A change/candidate was submitted for review.",
+  },
+  "change.accept": {
+    actors: ["admin"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: [],
+    desc: "A change was accepted/approved.",
+  },
+  "change.reject": {
+    // Supersedes the interim admin slice's "candidate.reject" (recordActivity.ts).
+    actors: ["admin"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: ["reason"],
+    desc: "A change was rejected (reason required).",
+  },
+  "change.resolve": {
+    // u3 (tot-merge-conflict-resolution-ux): one-click conflict resolution via
+    // candidate_refresh. Same admission ladder as change.reject (resolveShipSession
+    // → ship-on-behalf floor), so the same actor cohort. `strategy` is a
+    // low-cardinality enum (ours|theirs|merge), safe to render.
+    actors: ["admin"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: ["strategy"],
+    desc: "A not-mergeable change was resolved by rebuilding it from the base tip under a strategy.",
+  },
+  "change.ship": {
+    // D6: the admin/cockpit "Publish" (go-live) handler admits the store OWNER
+    // (merchant), ToT staff (admin), a ship-on-behalf developer (dev), AND the
+    // headless Bearer/CLI operator (agent) — the actor list reflects who actually
+    // reaches POST /api/changes/ship, not a placeholder subset.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "version"], renderedAllow: [],
+    desc: "A change was shipped to the live channel.",
+  },
+  "change.revert": {
+    // D9: same admission ladder as change.ship/rollback (resolveShipSession) — owner
+    // (merchant), staff (admin), ship-on-behalf dev, headless operator (agent). The
+    // `/api/changes/revert` route gates on the SAME seam, so the emitter cohort matches.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: ["reason"],
+    desc: "A change was reverted.",
+  },
+  "change.hotfix": {
+    // D9: the owner-only emergency HOTFIX lane (/api/changes/hotfix) — a DISTINCT verb
+    // from change.ship (never a `--base main` flag): a bypass-normal-flow live promote
+    // from `main` while `preview` holds other unshipped work. Same resolveShipSession
+    // ladder as ship/rollback (owner ⊇ ship-on-behalf), so the same cohort set.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: ["reason"],
+    desc: "An emergency hotfix was released to the live channel (bypassing unshipped preview work).",
+  },
+  "change.rollback": {
+    // D6: same admission ladder as change.ship (resolveShipSession) — owner
+    // (merchant), staff (admin), ship-on-behalf dev, headless operator (agent).
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "toVersion"], renderedAllow: ["reason"],
+    desc: "The live channel was rolled back to a prior version.",
+  },
+  "change.integrate": {
+    // D6: accept/integrate (resolveShipSession) admits the same cohort set.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: [],
+    desc: "A change was integrated into the shared preview.",
+  },
+  "change.rebuild": {
+    // u15: retry a dead aggregate rebuild without a new merge (/api/changes/rebuild).
+    // Same admission ladder as change.integrate/revert (resolveShipSession) — the
+    // route gates on the SAME seam, so the emitter cohort matches. No changeId: a
+    // rebuild retries the tenant's most recent integration attempt, not one candidate.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: [], renderedAllow: [],
+    desc: "A dead aggregate rebuild was retried without a new merge.",
+  },
+  "change.resync": {
+    // u12: advance the shared preview aggregate to an out-of-band branch tip
+    // without a candidate/<changeId> PR (/api/changes/resync). Same admission
+    // ladder as change.integrate/rebuild (resolveShipSession). No changeId: a
+    // resync pins an operator-supplied branch/sha, not one candidate.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: [], renderedAllow: [],
+    desc: "The shared preview aggregate was resynced to an out-of-band branch tip.",
+  },
+  "change.transition": {
+    // Generic SDLC transition for states without a dedicated verb above
+    // (triage↔in_progress↔ready_for_review↔announced↔closed).
+    actors: ["admin", "dev", "system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "from", "to"], renderedAllow: ["reason"],
+    desc: "A ShipLoop change moved between SDLC states.",
+  },
+
+  // ── Content / customization publish (source: ui/server) ────────────────────
+  "content.publish": {
+    actors: ["admin", "merchant", "dev"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["versionId", "scope"], renderedAllow: [],
+    desc: "Tenant customization/content was published to a version.",
+  },
+  "content.checkout_style.saved": {
+    // NEW (D10): a tenant's checkout styling was saved to a versioned test artifact
+    // (Settings → Checkout styling → publishToTest spine). A persistent tenant
+    // customization — low volume, high value → timelined. Actor cohort mirrors the
+    // route's own auth (resolveOwnerSession): a merchant saving their own tenant, or
+    // a ToT-staff operator "operating as" another tenant via the admin picker.
+    actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["versionId", "scope"], renderedAllow: [],
+    desc: "A tenant's checkout styling was saved to a version.",
+  },
+  "change.go_live": {
+    // D9: renamed from the orphaned, un-namespaced `go_live` (the ONE key that broke the
+    // domain-prefix rule). The snake_case suffix is kept (the `deploy.version_observed`
+    // precedent) — only the missing `change.` domain prefix is added. Wired into
+    // /api/preview/promote (promote the current preview snapshot to live).
+    actors: ["admin", "merchant"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["versionId"], renderedAllow: [],
+    desc: "A store's current preview was promoted to go-live.",
+  },
+
+  // ── Access / grants / connect (source: ui/server) ──────────────────────────
+  // Invitee identity is PII → DROPPED by allowlist; only the role/resource +
+  // an opaque hashed invitee ref (rendered) survive.
+  "grant.invite": {
+    // D6: the self-serve "Invite a Developer" handler admits an owner (merchant) or
+    // staff (admin) session, and the headless operator (agent) via the Bearer seam.
+    // D11: the SECOND invite path (grants/team-invite.ts) is session-authed by vendor
+    // MEMBERSHIP — a signed-in team member who is neither owner nor staff classifies as
+    // "dev" (see uiActor.classifyActorKind), so `dev` joins the admission set.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["role", "resource"], renderedAllow: ["inviteeRef"],
+    desc: "A developer/team invite was issued.",
+  },
+  "grant.approve": {
+    // D6: the browserless CLI sign-in approval is taken by whoever is signed in
+    // (owner→merchant, staff→admin, or a signed-in developer→dev).
+    actors: ["admin", "merchant", "dev"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["role", "resource"], renderedAllow: [],
+    desc: "A pending access request / CLI sign-in was approved.",
+  },
+  "grant.revoke": {
+    // D9: the self-serve "remove a developer from my team" handler (/api/grants/revoke),
+    // the inverse of grant.invite — same resolveOwnerSession seam, so the same cohort
+    // (owner→merchant, staff→admin, headless operator→agent). The revoked developer's
+    // identity is PII → DROPPED by the allowlist; only an opaque hashed ref survives.
+    actors: ["admin", "merchant", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["role", "resource"], renderedAllow: ["principalRef"],
+    desc: "A developer was revoked from the owner's team.",
+  },
+  "preview.invite": {
+    // D10 wired this into POST /api/preview/invite (the DEV-4 developer-onboarding
+    // invite), a Bearer-operator (headless) route with no human session — so `agent`
+    // is added to the cohort, mirroring how grant.invite admits the headless
+    // Bearer seam. The route mints a signed repo-onboarding LINK (owner/repo/
+    // cloneUrl), not an email invite, so there is no invitee PII to hash.
+    actors: ["admin", "merchant", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: ["inviteeRef"],
+    desc: "A reviewer/developer was invited to a preview.",
+  },
+  "preview.retire": {
+    actors: ["admin", "merchant"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: [],
+    desc: "A preview environment was retired.",
+  },
+  "store.connect": {
+    actors: ["merchant", "admin"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["provider"], renderedAllow: [],
+    desc: "A store/provider was connected.",
+  },
+
+  // ── App installs (source: server) — STOREFRONT_APPS_DB ─────────────────────
+  "app.install": {
+    actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["appId", "appVersion", "env"], renderedAllow: [],
+    desc: "A private app was installed.",
+  },
+  "app.uninstall": {
+    actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["appId", "env"], renderedAllow: [],
+    desc: "A private app was uninstalled.",
+  },
+  // ── App lifecycle mutations (source: server) — card D10 ─────────────────────
+  // Modeled on app.install/app.uninstall: the SAME `/api/apps/admin/*` operator
+  // cohort reaches these (a store OWNER managing their own app → merchant, ToT
+  // staff operating-as → admin), so the actor list mirrors those two, NOT a
+  // narrower placeholder. Security note (app.credential.rotated): the rotated
+  // secret NEVER enters the payload — the allowlist names only the non-sensitive
+  // install handle + rotation time (redaction would scrub a secret anyway, but the
+  // allowlist is deliberately minimal so there is nothing to scrub).
+  "app.credential.rotated": {
+    // The rotated secret NEVER enters the payload. We identify WHICH app rotated by
+    // its (appId, env) — NOT the installId, which is a UUID and would be scrubbed by
+    // the high-entropy canary anyway; appId/env survive redaction and are the same
+    // non-sensitive handle app.install/uninstall/suspend use.
+    actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["appId", "env", "rotatedAt"], renderedAllow: [],
+    desc: "A private app's client secret was rotated.",
+  },
+  "app.suspend": {
+    actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["appId", "env"], renderedAllow: [],
+    desc: "A private app install was suspended.",
+  },
+  "app.resume": {
+    actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["appId", "env"], renderedAllow: [],
+    desc: "A private app install was resumed to active.",
+  },
+  "app.update": {
+    actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["appId", "env"], renderedAllow: [],
+    desc: "A private app install was updated (version/scopes/manifest/webhook).",
+  },
+
+  // ── Agent cohort (source: server/cli) — later ──────────────────────────────
+  // Placeholder spine so the agent cohort (a later card) has stable keys to emit
+  // against without reopening D0. Args are deliberately empty until that card
+  // defines what an agent action is allowed to record.
+  "agent.action.invoked": {
+    actors: ["agent"], source: "server", sinks: HIGH_VOLUME,
+    argsAllow: ["tool"], renderedAllow: [],
+    desc: "An automated agent invoked an action.",
+  },
+  "agent.action.result": {
+    actors: ["agent"], source: "server", sinks: HIGH_VOLUME,
+    argsAllow: ["tool", "durationMs"], renderedAllow: [],
+    desc: "An automated agent action finished.",
+  },
+
+  // ── D11: remaining grant/staff-ops gaps + machine/agent-driven mutations ─────
+  // Follow-on to D0–D8: wires the invite/grant paths, staff-impersonation, cache,
+  // and machine-authed (signature/idempotency/app-JWT) mutations that D6 left out.
+  // Grant/staff actions are low-volume lifecycle → timelined; the machine cohort's
+  // high-volume streams (order-forward, attribution) are analytics-only.
+  "grant.issue": {
+    // grants/index.ts POST — the owner's team grant fan-out (one grantRepoAccess per
+    // member×repo). DISTINCT from `grant.invite` (which emails a developer to establish
+    // eligibility): this issues repo access to EXISTING principals. `resolveOwnerSession`
+    // admits owner (merchant), staff (admin), and the headless Bearer operator (agent).
+    // Principals are emails/usernames (PII) → NEVER stored; only counts + the owner.
+    actors: ["merchant", "admin", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["resource", "granted", "failed"], renderedAllow: [],
+    desc: "A team was granted repo access (grant fan-out).",
+  },
+  "grant.provisioned": {
+    // grants/provisioned.ts — bulk re-grant of the owner's EXISTING team onto a newly
+    // provisioned repo. DISTINCT from `grant.approve` (a CLI sign-in approval): this is
+    // a merchant-driven re-grant onto a new resource. Same admission ladder as the
+    // grants surface (resolveOwnerSession → merchant primary, staff/headless too).
+    actors: ["merchant", "admin", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["repo", "regranted", "failed"], renderedAllow: [],
+    desc: "An existing team was re-granted onto a newly provisioned repo.",
+  },
+  "dashboard.vendor_entered": {
+    // dashboard/enter-vendor.ts — a ToT-STAFF viewer enters/impersonates a vendor tenant.
+    // A classic audit event on the staff-impersonation boundary → timelined. Emitted
+    // ONLY after the staff gate passes, so the actor is always `admin` (staff); the
+    // staff email is PII and never stored (actor.id is its salted hash).
+    actors: ["admin"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["resource", "capability"], renderedAllow: [],
+    desc: "A ToT-staff operator entered a vendor tenant (impersonation boundary).",
+  },
+  "cache.purged": {
+    // cache-purge.ts — bumps a tenant's edge page-cache version (the ETL load step calls
+    // it per tenant post-migration). Bearer-secret service call (no session) → emitted
+    // server-side as the machine caller (agent); an operator manual purge is the admin.
+    actors: ["admin", "agent"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["version"], renderedAllow: [],
+    desc: "A tenant's edge page-cache version was bumped (purge).",
+  },
+  "store.connect.completed": {
+    // domain/callback.ts — the CI completion callback for the www-domain job, the
+    // machine-side terminal PARTNER of D6's `store.connect`. Signature-authed, one per
+    // connect run (rare) → low-volume lifecycle terminal, timelined like reconcile.terminal.
+    actors: ["system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["status", "state", "action"], renderedAllow: [],
+    desc: "A store apex-domain connect/rollback CI job reported completion.",
+  },
+  "app.order.forwarded": {
+    // apps/internal/order-forward.ts — an order forwarded to a private app (the
+    // tot-foxycart reconciliation unit, HMAC-signature-authed). HIGH-VOLUME (per order)
+    // → analytics only, NEVER timelined. Customer/order ids are excluded from the
+    // allowlist; only the coarse status/env/currency dimensions survive.
+    actors: ["agent", "system"], source: "server", sinks: HIGH_VOLUME,
+    argsAllow: ["status", "env", "currency"], renderedAllow: [],
+    desc: "An order was forwarded to a private app.",
+  },
+  "app.attribution.recorded": {
+    // apps/v1/attribution.ts — an installed private app (external bot, app-JWT authed,
+    // idempotency-keyed) records an attribution. HIGH-VOLUME → analytics only. The
+    // referralCode/customerHash are excluded; only the campaign dimension survives.
+    actors: ["agent"], source: "server", sinks: HIGH_VOLUME,
+    argsAllow: ["campaign"], renderedAllow: [],
+    desc: "A private app recorded an order attribution.",
+  },
+  "webhook.delivery.replayed": {
+    // apps/{admin,v1}/webhooks/deliveries/[deliveryId]/replay.ts — a webhook delivery was
+    // re-enqueued. TWO call sites, ONE key: the admin/ops console (session-authed →
+    // admin/merchant per resolveOperatorSession) and the app-facing v1 route (app-JWT →
+    // agent). A deliberate remediation action, low-volume → timelined for audit. The
+    // deliveryId is the opaque CloudEvents wire id (non-PII); `surface` disambiguates.
+    actors: ["admin", "merchant", "agent"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["deliveryId", "surface"], renderedAllow: [],
+    desc: "A webhook delivery was replayed (re-enqueued).",
+  },
+
+  // ── Meta (source: server) ──────────────────────────────────────────────────
+  "system.ingest.rejected": {
+    // The ingest endpoint (D4) rejected an event (unknown action, actor
+    // mismatch, canary tripped). Self-telemetry so a leak attempt is visible.
+    actors: ["system"], source: "server", sinks: HIGH_VOLUME,
+    argsAllow: ["reason", "attemptedAction"], renderedAllow: [],
+    desc: "An inbound activity event was rejected at ingest.",
+  },
+} as const satisfies Record<string, ActionSpec>;
+
+/** The allowlisted set of action keys. `action` on an ActivityEvent must be one. */
+export type ActionKey = keyof typeof ACTION_CATALOG;
+
+/** All action keys as a runtime array (for ingest validation, tests, docs). */
+export const ACTION_KEYS = Object.keys(ACTION_CATALOG) as ActionKey[];
+
+/** Type guard: is this string an allowlisted action key? Deny-by-default. */
+export function isActionKey(v: unknown): v is ActionKey {
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(ACTION_CATALOG, v);
+}
+
+/** The spec for an action key. Returns undefined for an unknown key (caller
+ * treats undefined as "reject" — never as "allow everything"). */
+export function getActionSpec(action: string): ActionSpec | undefined {
+  return isActionKey(action) ? ACTION_CATALOG[action] : undefined;
+}
+
+/** May this actor kind emit this action? Ingest (D4) uses this to reject spoofed
+ * cohorts (e.g. a `dev`-sourced token claiming an `admin` lifecycle action). */
+export function isActorAllowed(action: ActionKey, actor: ActorKind): boolean {
+  return (ACTION_CATALOG[action].actors as readonly ActorKind[]).includes(actor);
+}