@cat-factory/gatekeeper-worker 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# @cat-factory/gatekeeper-worker
+
+## What it is
+
+The Cloudflare Worker machinery behind a cat-factory **Gatekeeper**: a credential-holding front
+end that lets a [Cloudflare OS](https://github.com/cloudflare/cloudflare-os) workspace (or any
+agent runtime speaking Cap'n Web) drive cat-factory without an agent ever seeing a credential.
+Agents hold an object-capability whose methods are exactly what policy granted; the keys stay in
+Worker secrets and Durable Object storage.
+
+It is the machinery half of the Gatekeeper family:
+
+| Piece                                                                                                | What it is                                                                     | How you take it                       |
+| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- |
+| [`@cat-factory/gatekeeper-bindings`](https://www.npmjs.com/package/@cat-factory/gatekeeper-bindings) | the generated operation table this package compiles policy against             | comes in as a dependency              |
+| `@cat-factory/gatekeeper-worker` (this package)                                                      | the capability surface, key broker, webhook receiver, approval inbox, state DO | install, and write only a policy      |
+| [`deploy/gatekeeper`](https://github.com/kibertoad/cat-factory/tree/main/deploy/gatekeeper)          | the deployment template: policy, wrangler bindings, three lines of wiring      | copy, and edit `src/policy.config.ts` |
+
+You install this package and write one file. Everything a deployment differs by is the
+**policy**; everything else, from the capability surface down to the Durable Object the minted
+keys live in, comes from here. That split is the goal: upgrading the machinery is a version bump
+rather than a merge against files you have edited, and "did you get the security-relevant fix" is
+answerable from a version number.
+
+## Purpose and goal
+
+Its purpose is to put cat-factory behind an organization's own governance pane: per-actor
+credentials so every run traces back to a person, per-tier operation grants so an agent can reach
+only what its operator decided, field masking, and the platform's parked decisions surfaced as an
+approval inbox instead of a polling loop.
+
+It is a **consumer of the stable public surface**: it rides `/api/v1` and the outbound webhook
+delivery contract through [`@cat-factory/sdk`](https://www.npmjs.com/package/@cat-factory/sdk) and
+reaches nothing else. A cat-factory deployment that has never heard of it is byte-for-byte
+unchanged.
+
+## How to use it
+
+The starting point is the template at
+[`deploy/gatekeeper`](https://github.com/kibertoad/cat-factory/tree/main/deploy/gatekeeper): copy
+it, point it at your workspace, and edit its `src/policy.config.ts`. A deployment's whole Worker
+is:
+
+```ts
+import { createGatekeeperWorker } from '@cat-factory/gatekeeper-worker'
+import { POLICY } from './policy.config'
+
+// wrangler resolves `class_name` against the Worker's OWN exports, so the Durable Object class has
+// to be named here even though it is implemented in this package.
+export { GatekeeperState } from '@cat-factory/gatekeeper-worker'
+
+export default createGatekeeperWorker({ policy: POLICY })
+```
+
+```ts
+// policy.config.ts: the `/policy` entry point carries the vocabulary without the Worker runtime,
+// so this file and its tests load anywhere.
+import { DECISION_BINDINGS, type GatekeeperPolicy } from '@cat-factory/gatekeeper-worker/policy'
+
+export const POLICY: GatekeeperPolicy = {
+  defaultTier: null, // no implicit access: an ungranted actor gets `unknown_actor`, not a capability
+  tiers: {
+    observer: { description: 'Read the board and runs.', keyScope: 'read', allow: '*' },
+    approver: {
+      description: 'Answer a run’s parked decisions.',
+      keyScope: 'decide',
+      // Derived from the answerer table, never transcribed: a run parks on thirteen different
+      // things and the surface carries more than forty operations for answering them.
+      allow: ['tasks_get_run', ...DECISION_BINDINGS],
+      mask: ['run.pullRequestUrl'],
+    },
+  },
+  grants: { 'someone@your-org.example': 'approver' },
+}
+```
+
+`@cloudflare/workers-types` is a **required** peer, not an optional one. Every type this package
+publishes is stated in terms of the Worker globals (`ExportedHandler`, `DurableObjectNamespace`,
+`Request`) and the Durable Object base class comes from `cloudflare:workers`, so a consumer without
+those types cannot compile the three lines above, let alone anything else. It is a peer rather than
+a dependency because the globals are ambient: two copies in one tree redeclare each other, so the
+version has to be the consumer's.
+
+## What it does
+
+- **Object-capability bindings over Cap'n Web.** An agent holds an object whose METHODS are the
+  operations policy granted it. There is no allow-list consulted per call, because there is nothing
+  to consult: an operation the tier does not carry is not a method that refuses, it is absent.
+- **Per-actor credentials.** Each caller gets their own cat-factory key, minted through
+  `POST /api/v1/keys` at the tier's scope and stamped with your identity for that person
+  (`externalIdentity`), so a run traces back to a human and role-scoped merge policy stays real.
+  Minting is claimed before it runs and re-mints once on a 401, so concurrent first calls mint
+  once and rotating the provisioning key heals instead of wedging.
+- **Approvals as an inbox, for every park.** The platform's outbound webhook delivers
+  parked-decision cards; the Worker verifies the HMAC over the raw bytes, dedupes on `deliveryId`,
+  and raises a card. A run can stop on thirteen different things and each has an answerer keyed on
+  the SDK's own kind union, so a park the platform adds fails this package's build rather than
+  reporting `stale` forever. Answering re-reads the run's live decisions and posts through the
+  caller's own key.
+- **Run lifecycle without polling.** `run.started` / `run.completed` / `run.failed` land as a
+  `runs_watched()` projection, and a terminal event settles that run's open cards.
+- **Self-enrolment and offboarding.** The endpoint registers itself under a caller-chosen webhook
+  id, hourly and idempotently. `POST /admin/retire?actorId=…` revokes every key minted for one
+  person, upstream first and then here.
+
+One thing to tell whoever writes the agent on the other side: **a task filed with only a title
+parks immediately**, before any agent runs. cat-factory reduces a task's own authored fields before
+the first dispatch, and a missing description is a blocking finding, so `tasks_create` +
+`tasks_start` with a bare title yields a run stopped on an `input-gate` decision rather than one
+that is working. That park is answerable from here like any other, but the cheaper fix is filing
+work that says what it wants.
+
+## What to configure
+
+Everything operational comes from the Worker's environment, through two mechanisms that are not
+interchangeable: the vars and the Durable Object binding are written in the template's
+`wrangler.toml`, and the three credentials are secrets, put with `wrangler secret put` into the
+platform's secret store. A credential in a config file is a credential in a repository, so a
+refusal names the mechanism its binding actually takes rather than offering both.
+
+| Binding                | Kind           | What it is                                                                    |
+| ---------------------- | -------------- | ----------------------------------------------------------------------------- |
+| `CAT_FACTORY_BASE_URL` | var            | The cat-factory deployment this Gatekeeper is paired with.                    |
+| `PUBLIC_URL`           | var            | This Worker's own public origin; deliveries arrive at `<PUBLIC_URL>/webhook`. |
+| `WEBHOOK_ID`           | var            | The outbound-webhook id to enrol under. Caller-chosen; keep it stable.        |
+| `PROVISIONING_KEY`     | secret         | An `admin` cat-factory API key. Mints per-actor keys; nothing else.           |
+| `WEBHOOK_SECRET`       | secret         | 16-200 chars. Registered with the endpoint and verified on every delivery.    |
+| `OS_SHARED_TOKEN`      | secret         | The bearer the paired OS deployment presents on every RPC call.               |
+| `STATE`                | Durable Object | A namespace bound to `GatekeeperState`: cards, dedupe log, minted keys.       |
+
+A missing binding is answered as a 503 naming it and how it is set, never defaulted: there is no
+safe stand-in for a credential or for the identity of the deployment it talks to. `GET /health`
+asks the whole table at once rather than the bindings a given request path happens to read, so a
+deployment that is wired for liveness and unwired for traffic reads as what it is.
+
+The Worker serves five routes:
+
+| Route                          | Auth              | What it is                                                    |
+| ------------------------------ | ----------------- | ------------------------------------------------------------- |
+| `POST /webhook`                | delivery HMAC     | The platform's outbound deliveries. Verified over raw bytes.  |
+| `ALL /rpc`                     | `OS_SHARED_TOKEN` | The Cap'n Web endpoint the OS deployment talks to.            |
+| `POST /admin/enroll`           | `OS_SHARED_TOKEN` | Re-assert the webhook registration. Also runs hourly on cron. |
+| `POST /admin/retire?actorId=…` | `OS_SHARED_TOKEN` | Offboarding: revoke every key minted for one OS user.         |
+| `GET /health`                  | none              | Green only when every binding is set and the policy compiles. |
+
+`/rpc` is bearer-gated even though the intended path is a Worker service binding, which never
+traverses the internet: a Worker with a route attached is reachable by anyone who finds it, and a
+capability surface whose only defence is obscurity is not one.
+
+## What to customize: the policy
+
+The policy is the ONE thing a deployment writes, and it is an argument
+(`createGatekeeperWorker({ policy })`), never a file this package reads. A `GatekeeperPolicy` has
+three fields:
+
+- `defaultTier`: the tier an actor with no explicit grant receives, or `null` to refuse unknown
+  actors (`unknown_actor`). `null` is the shipped default and the safe one: adding a person is
+  then a deliberate edit.
+- `tiers`: named `TierPolicy` entries, each carrying:
+  - `description`: prose the OS shows beside the tier.
+  - `keyScope`: the scope of the per-actor key minted for this tier (`read` / `write` /
+    `decide`). It is also the ceiling on the grants; `admin` is refused outright, because
+    `POST /api/v1/keys` cannot mint it and a tier asking for it is asking for the Gatekeeper's
+    own provisioning secret.
+  - `allow`: binding names to grant, or `'*'` for everything within `keyScope`.
+  - `deny`: binding names to subtract from `allow`. Applied last, so a deny always wins; the
+    template uses it to keep the debug surface (model prompts, captured output) away from a
+    `'*'` read tier.
+  - `mask`: dotted paths redacted from every result before it reaches the caller (see below).
+- `grants`: OS actor identity (whatever the OS authenticates and passes to `connect()`) to tier
+  name.
+
+A policy is compiled against the LIVE operation table and only ever SUBTRACTS from
+`bindingsWithinScope(tier.keyScope)`, so a tier cannot grant above the key backing it, and a
+retired or misspelled operation is a refusal to serve (`PolicyError`) rather than a method that
+403s on every call. Two rules are worth keeping whatever else you change:
+
+- **Grant by name above `read`.** `'*'` is honest for a read-only tier and dangerous above it: a
+  deployment that adds an operation ships it to every `'*'` tier on upgrade with nobody deciding to.
+- **Keep `keyScope` as low as the grants allow.** It is the scope of the key minted for each actor,
+  so it is the blast radius of that actor's credential.
+
+**Masking replaces, never deletes.** A masked leaf becomes the exported `MASKED` sentinel
+(`[masked by gatekeeper policy]`) rather than disappearing, because a removed key and a key the
+platform had no value for read identically to the consuming agent, and they are different facts.
+Paths are dotted and traverse arrays element-wise (`steps.status` masks every step's status); a
+path that matches nothing is not an error, because result shapes legitimately vary by operation.
+
+## What a caller holds
+
+`connect({ actorId, label? })` on the `/rpc` session resolves the actor's tier and returns the
+capability. `actorId` is the OS's own authenticated identity for the person, and it is the ONLY
+claim the Gatekeeper trusts: nothing the caller sends picks a tier. Beyond the granted operation
+methods, every capability carries seven reserved methods:
+
+- `tier()`: who the caller is acting as (actor, tier name, description, key scope).
+- `bindings()`: the granted operations, each with its scope floor, consequence (cautious default
+  applied) and argument shape, so the OS can run its own approval governance per call.
+- `withheld()`: every binding the deployment serves that this capability does NOT carry, with the
+  reason. The four reasons are kept apart on purpose: `not_in_policy` and `denied_by_policy` are
+  questions for the policy's author, `above_key_scope` is a different one (raise the tier's key,
+  or accept the ceiling), and `not_relayable` is neither: an SSE stream or a binary blob cannot
+  cross a Cap'n Web call, so the fix is to ask another way (poll `tasks_get_run` instead of the
+  event stream).
+- `approvals_list()`, `approvals_inspect(cardId)`, `approvals_answer(cardId, input)`: the
+  approval inbox; see the template README for the flow and the three answer outcomes.
+- `runs_watched()`: the run-lifecycle projection built from the `run.*` webhook events.
+
+Refusals from a live Gatekeeper are `GatekeeperError`s carrying a machine-readable `reason`
+(`unknown_actor`, `card_not_found`, `ambiguous_park`, …), the same role the platform's own
+`details.reason` plays: an OS Gadget maps it to copy and a remedy. Operator mistakes are
+`PolicyError`s raised at compile time, before any capability exists, so a misconfigured Gatekeeper
+serves nothing rather than serving methods that fail.
+
+## Custody, and what it does not promise
+
+The provisioning key is a Worker secret and never leaves the platform's secret store. The per-actor
+keys it mints live in the Durable Object's storage: outside every agent's reach, but at rest in
+your account. If that is not acceptable, mint per call and revoke after, at the cost of a key row
+per operation.
+
+What this enforces is which operations an actor may reach and on whose credential. What a run then
+does inside cat-factory is governed by cat-factory's own merge policy and approvals.
+
+## Upgrading
+
+Upgrade this package. `@cat-factory/gatekeeper-bindings` arrives as its dependency, pinned to an
+exact version, so bumping this package IS how the operation table moves and there is nothing to
+keep in step by hand. Do not add a direct dependency on the bindings to keep them "together": an
+exact pin plus a second range installs a SECOND copy of the table, while policy still compiles
+against the one resolved here. Everything a policy names is re-exported from
+`@cat-factory/gatekeeper-worker/policy`, so a deployment never needs that dependency.
+
+Version skew is reported rather than absorbed. A policy naming an operation newer than the
+installed table fails with a `PolicyError` telling you to upgrade, and the ladder helpers throw on
+a scope rung they do not carry, so a deployment ahead of your packages reads as skew, never as a
+key with no permissions.
+
+## Tests
+
+The suite runs inside real `workerd` under `@cloudflare/vitest-pool-workers`, against a Worker
+built from this package's own factory with a real Durable Object, real WebCrypto and a real Cap'n
+Web client, talking to a scripted cat-factory origin bound as the pool's outbound service. The
+credential-custody story IS "the key is a Worker secret", so a Node mock of a Worker would prove
+nothing about it.
+
+```sh
+pnpm --filter @cat-factory/gatekeeper-worker test:run
+```
+
+`test/live/` is the same Worker with the scripted origin taken away. A fixture agrees with this
+package by construction, so a request shape the bindings and the SDK both consider correct can only
+be wrong against a real deployment: the live specs enrol on the real webhook collection, mint a real
+per-actor key (and recover from its revocation), forward the everyday loop, and answer a run that
+really parked, off the card the platform's own notification raises. They are run by
+`@cat-factory/sdk-smoketest`, which owns the deployment they need, so this package carries no
+Postgres-shaped devDependency:
+
+```sh
+DATABASE_URL=... pnpm --filter @cat-factory/sdk-smoketest run smoketest -- --only=gatekeeper
+```
+
+What that deliberately does not cover is a delivery that TRAVELLED: the platform refuses to register
+a loopback endpoint, so the receiver is driven with an envelope the suite signs around the
+platform's own notification object.
+
+## References
+
+- [`deploy/gatekeeper`](https://github.com/kibertoad/cat-factory/tree/main/deploy/gatekeeper): the
+  template you copy, its configuration walkthrough and the OS-side usage example.
+- [The initiative tracker](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/cloudflare-os-gatekeeper.md):
+  design notes, the decisions behind each half, and what the suite deliberately does not cover.
+- [`backend/docs/public-api.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/public-api.md):
+  the API this rides (keys, scopes, webhooks, endpoint semantics).
+- [`@cat-factory/gatekeeper-bindings`](https://www.npmjs.com/package/@cat-factory/gatekeeper-bindings):
+  the generated operation table policy is compiled against.

package/dist/approvals.d.ts

@@ -0,0 +1,90 @@
+import { type AnswerFields, type DecisionVerb, type LiveDecision } from './policy/decisions.js';
+import type { ApprovalCard } from './state.js';
+export interface AnswerInput extends AnswerFields {
+    /** The verb, as the kind's answerer names it (`approve`, `reply`, `resolve`, …). */
+    action: string;
+    /**
+     * Which park to answer, when the run holds more than one.
+     *
+     * Optional because the common case is a run parked on exactly one thing. Where two are pending
+     * (a follow-up triage accrues while a later step's gate is open), answering without naming the
+     * kind is REFUSED rather than resolved by order: the platform lists them in a shape order, not a
+     * priority order, so picking the first would settle whichever the projection happened to build
+     * first.
+     */
+    kind?: string;
+}
+/**
+ * What answering did.
+ *
+ * `stale` and `recorded` are the two outcomes an integration gets wrong when they are collapsed
+ * into "it worked": the first means the run no longer holds a park this surface can answer, and
+ * the second means the answer was taken but the park is still holding the run (an approval short
+ * of quorum, a reply recorded before the incorporation that folds it in). Reporting either as
+ * "answered" leaves a person believing a run is moving when it is not.
+ */
+export type AnswerOutcome = {
+    status: 'answered';
+    runId: string;
+    kind: string;
+    action: string;
+    decisions: unknown;
+} | {
+    status: 'recorded';
+    runId: string;
+    kind: string;
+    action: string;
+    /** Why the park still holds, in the run's own numbers where it has them. */
+    detail: string;
+    decisions: unknown;
+} | {
+    status: 'stale';
+    runId: string;
+    detail: string;
+    decisions: unknown;
+};
+/** The minimal shape this module reads off a decision list. */
+export interface DecisionListShape {
+    parked?: boolean;
+    status?: string;
+    decisions?: unknown[];
+    unanswerable?: {
+        reason?: string;
+        detail?: string;
+    }[];
+}
+/** Invoke a granted binding. Supplied by the capability, so policy is enforced on every hop. */
+export type BindingInvoker = (name: string, args: Record<string, unknown>) => Promise<unknown>;
+/** One park holding a run, paired with the answerer that knows how to settle it. */
+export interface PendingPark {
+    kind: string;
+    decision: LiveDecision;
+    verbs: readonly DecisionVerb[];
+    summary: string;
+}
+/**
+ * Every park in the list this Gatekeeper could answer, in the platform's own order.
+ *
+ * A settled entry is skipped by its kind's own `pending` predicate, and a kind this package does
+ * not model is skipped entirely: both are cases where posting an answer would be a guess.
+ */
+export declare function pendingParks(list: DecisionListShape): PendingPark[];
+/**
+ * Why nothing here is answerable, in the run's own words where it has them.
+ *
+ * Four different facts, and an integration acts on each differently: the run finished, a person on
+ * the VCS host is the gate, the run is parked on a kind this package does not model (a deployment
+ * newer than this Gatekeeper), or it is parked on one that is modelled but already settled.
+ * Flattening those into "not parked" would send an operator looking in the wrong place for each.
+ */
+export declare function describeStale(list: DecisionListShape): string;
+/**
+ * Answer one card against the live run.
+ *
+ * `invoke` carries the policy check, so this function never consults the tier itself: a binding the
+ * caller was not granted rejects on the way through, with the capability's own refusal.
+ */
+export declare function answerCard(card: ApprovalCard, input: AnswerInput, invoke: BindingInvoker): Promise<AnswerOutcome>;
+/** Refuse a card that cannot be answered, with the reason the OS maps to copy. */
+export declare function assertAnswerable(card: ApprovalCard | null, cardId: string): ApprovalCard;
+//# sourceMappingURL=approvals.d.ts.map

package/dist/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../src/approvals.ts"],"names":[],"mappings":"AAqBA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GACvF;IACE,MAAM,EAAE,UAAU,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,OAAO,CAAA;CACnB,GACD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAA;AAE1E,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;IACrB,YAAY,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACtD;AAED,gGAAgG;AAChG,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAE9F,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,YAAY,CAAA;IACtB,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAQD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,GAAG,WAAW,EAAE,CAenE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CA0B7D;AAwED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,aAAa,CAAC,CAqCxB;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAgBxF"}

package/dist/approvals.js

@@ -0,0 +1,193 @@
+// Answering a card: the half of the pattern where the OS's workspace inbox becomes a real decision
+// on a real run.
+//
+// The card is a POINTER, never the decision. Between the delivery that raised it and the answer,
+// the run may have advanced, been stopped, or had the same park answered by a person in the
+// cat-factory app; and the ids every action addresses (`approvalId`, `decisionId`, the brainstorm
+// `stage`) are not on the card at all, because the notification does not carry them. So answering
+// re-reads `/runs/:runId/decisions` first, every time. That is the platform's own instruction
+// ("the webhook is a trigger; the API is the truth") and it is what makes a stale card a REPORT
+// rather than a 404 someone has to interpret.
+//
+// What this module does NOT do is decide how any particular park is answered. It finds the entry
+// holding the run and hands it to that kind's answerer in `decisions.ts`. The run can be parked on
+// any of thirteen things and the card's notification type is at best a hint about which: a
+// `decision_required` card can be an approval gate or an agent question, and a run that parked
+// twice is answering the SECOND park by the time anyone reads the first card.
+//
+// Every upstream call goes through the caller's own granted bindings, so a tier that was not
+// granted `decisions_approve_step` cannot approve through this route either. The answer flow gets
+// no privilege of its own.
+import { answererFor, } from './policy/decisions.js';
+import { GatekeeperError } from './errors.js';
+function asDecision(entry) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+        return null;
+    const kind = entry.kind;
+    return typeof kind === 'string' ? entry : null;
+}
+/**
+ * Every park in the list this Gatekeeper could answer, in the platform's own order.
+ *
+ * A settled entry is skipped by its kind's own `pending` predicate, and a kind this package does
+ * not model is skipped entirely: both are cases where posting an answer would be a guess.
+ */
+export function pendingParks(list) {
+    const parks = [];
+    for (const entry of list.decisions ?? []) {
+        const decision = asDecision(entry);
+        if (decision === null)
+            continue;
+        const answerer = answererFor(decision.kind);
+        if (answerer === undefined || !answerer.pending(decision))
+            continue;
+        parks.push({
+            kind: decision.kind,
+            decision,
+            verbs: answerer.verbs,
+            summary: answerer.summary,
+        });
+    }
+    return parks;
+}
+/**
+ * Why nothing here is answerable, in the run's own words where it has them.
+ *
+ * Four different facts, and an integration acts on each differently: the run finished, a person on
+ * the VCS host is the gate, the run is parked on a kind this package does not model (a deployment
+ * newer than this Gatekeeper), or it is parked on one that is modelled but already settled.
+ * Flattening those into "not parked" would send an operator looking in the wrong place for each.
+ */
+export function describeStale(list) {
+    const waits = list.unanswerable ?? [];
+    if (waits.length > 0) {
+        return waits
+            .map((wait) => `${wait.reason ?? 'unknown'}: ${wait.detail ?? 'no detail supplied'}`)
+            .join('; ');
+    }
+    const kinds = (list.decisions ?? [])
+        .map(asDecision)
+        .filter((decision) => decision !== null)
+        .map((decision) => decision.kind);
+    if (kinds.length > 0) {
+        const unmodelled = kinds.filter((kind) => answererFor(kind) === undefined);
+        if (unmodelled.length > 0) {
+            return (`The run is parked on '${[...new Set(unmodelled)].join("', '")}', which this Gatekeeper ` +
+                'does not know how to answer. Upgrade it if the deployment is newer, or answer in the ' +
+                'cat-factory app.');
+        }
+        return `The run carries '${[...new Set(kinds)].join("', '")}', all already settled.`;
+    }
+    if (list.parked === false) {
+        return `The run is '${list.status ?? 'unknown'}' and holds no parked decision; it was answered elsewhere, or it has moved on.`;
+    }
+    return 'The run is parked, and the platform named no decision and no unanswerable wait for it.';
+}
+/**
+ * Whether the run has left the park entirely.
+ *
+ * This is what decides a card's fate, and it is deliberately a question about the RUN rather than
+ * about the answer: an approve that met its quorum settles the card, an approve short of it does
+ * not, and neither is visible in the action's own status code. A `stale` answer settles nothing at
+ * all: the run may be parked on a wait a person has to clear, and destroying its inbox entry
+ * would hide the one pointer anybody had to it.
+ */
+function stillParked(after, kind) {
+    return pendingParks(after).find((park) => park.kind === kind) ?? null;
+}
+function pickPark(parks, requested) {
+    if (requested !== undefined) {
+        const park = parks.find((candidate) => candidate.kind === requested);
+        if (park === undefined) {
+            throw new GatekeeperError('no_such_park', `The run holds no pending '${requested}' decision. It is parked on ` +
+                `'${parks.map((candidate) => candidate.kind).join("', '")}'.`);
+        }
+        return park;
+    }
+    if (parks.length > 1) {
+        throw new GatekeeperError('ambiguous_park', `The run is parked on ${parks.length} decisions at once ` +
+            `('${parks.map((park) => park.kind).join("', '")}'). Name which one with \`kind\`: the ` +
+            'platform lists them in a shape order, not a priority order, so answering the first would ' +
+            'settle whichever the projection happened to build first.');
+    }
+    return parks[0];
+}
+function pickVerb(park, action) {
+    const verb = park.verbs.find((candidate) => candidate.action === action);
+    if (verb === undefined) {
+        throw new GatekeeperError('unsupported_action', `A '${park.kind}' decision does not take '${action}'. It takes ` +
+            `'${park.verbs.map((candidate) => candidate.action).join("', '")}'.`);
+    }
+    return verb;
+}
+/**
+ * Why a park that survived the answer is still holding the run.
+ *
+ * Derived from the platform's own numbers, never from prose: a quorum reports its tally, an
+ * iterative review reports the pass it is on. Where the park states neither, the honest answer is
+ * that it is still there, which is itself the fact the caller needs.
+ */
+function describeProgress(park) {
+    const { decision } = park;
+    if (typeof decision.recordedApprovals === 'number' &&
+        typeof decision.requiredApprovals === 'number') {
+        return `${decision.recordedApprovals} of ${decision.requiredApprovals} approvals recorded; the gate still needs the rest.`;
+    }
+    if (typeof decision.iteration === 'number' && typeof decision.maxIterations === 'number') {
+        return `The loop is on pass ${decision.iteration} of ${decision.maxIterations} and has not converged.`;
+    }
+    return `The '${park.kind}' decision is still holding the run; there is more to answer on it.`;
+}
+/**
+ * Answer one card against the live run.
+ *
+ * `invoke` carries the policy check, so this function never consults the tier itself: a binding the
+ * caller was not granted rejects on the way through, with the capability's own refusal.
+ */
+export async function answerCard(card, input, invoke) {
+    const before = (await invoke('decisions_list', { runId: card.runId }));
+    const parks = pendingParks(before);
+    if (parks.length === 0) {
+        return { status: 'stale', runId: card.runId, detail: describeStale(before), decisions: before };
+    }
+    const park = pickPark(parks, input.kind);
+    const verb = pickVerb(park, input.action);
+    const call = verb.call(park.decision, input);
+    const after = (await invoke(call.binding, {
+        runId: card.runId,
+        ...call.args,
+    }));
+    // Every decision action returns the run's WHOLE list, re-read after the action. So whether the
+    // answer moved the run is in hand already, with no second call.
+    const survived = stillParked(after, park.kind);
+    if (survived !== null) {
+        return {
+            status: 'recorded',
+            runId: card.runId,
+            kind: park.kind,
+            action: verb.action,
+            detail: describeProgress(survived),
+            decisions: after,
+        };
+    }
+    return {
+        status: 'answered',
+        runId: card.runId,
+        kind: park.kind,
+        action: verb.action,
+        decisions: after,
+    };
+}
+/** Refuse a card that cannot be answered, with the reason the OS maps to copy. */
+export function assertAnswerable(card, cardId) {
+    if (card === null) {
+        throw new GatekeeperError('card_not_found', `No approval card '${cardId}'. It may have been raised against a different paired workspace, ` +
+            'or predate this Gatekeeper.');
+    }
+    if (card.resolvedAt !== null) {
+        throw new GatekeeperError('card_already_resolved', `Approval card '${cardId}' was settled as '${card.resolution}'. Read the run's decisions if ` +
+            'it has parked again since.');
+    }
+    return card;
+}
+//# sourceMappingURL=approvals.js.map

package/dist/approvals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../src/approvals.ts"],"names":[],"mappings":"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"}