@cat-factory/gatekeeper-worker 0.4.3 → 0.6.0

package/dist/os/protocol.d.ts

@@ -0,0 +1,193 @@
+/** An image the workspace renders beside a vendor, an account or a resource. */
+export interface AvatarImage {
+    url: string;
+}
+/**
+ * The stable tag an OS admin rule is keyed on, plus the label a human reads.
+ *
+ * The tag has to survive a rename of the label, because a pre-approval rule an operator wrote
+ * months ago is matched by it. Ours is the binding name, which is generated from the operation's
+ * own group and method, so it is exactly as stable as the public API is.
+ */
+export interface ActionKind {
+    tag: string;
+    label: string;
+}
+/** What the OS shows about a vendor before any account exists. */
+export interface VendorDescription {
+    displayName: string;
+    url: string;
+    logo?: AvatarImage;
+    color?: string;
+    tagline?: string;
+    description?: string;
+    /** True only if the connect flow yields a provider-verified email. Ours does not. */
+    providesAuth?: boolean;
+    /** True when the vendor can mint an account with no OAuth flow (see `createAccount`). */
+    autoProvisionsAccount?: boolean;
+}
+/** A class of thing this vendor can serve, matched against a URL by `urlPattern`. */
+export interface SupportedResource {
+    /** A URLPattern string, e.g. `https://cat-factory.example.com/*`. */
+    urlPattern: string;
+    title: string;
+    description: string;
+    icon?: AvatarImage;
+    /** True when the account must be granted access to this type separately. */
+    grantable?: boolean;
+}
+/** What the OS shows about one connected account. */
+export interface AccountDescription {
+    displayName?: string;
+    /** The canonical, unique name for the account. */
+    uniqueName?: string;
+    avatar: AvatarImage;
+    grantedResourceUrlPatterns?: string[];
+}
+/** What the OS shows about one bound resource, and how it types the session behind it. */
+export interface ResourceDescription {
+    /** The resource's canonical URL: visiting it in a browser opens the resource's own UI. */
+    url: string;
+    title: string;
+    snippet: string;
+    /** The name the binding is first created with. The user may rename it. */
+    suggestedBindingName: string;
+    /** A type name exported by this gatekeeper's `getTypeScriptTypes()`. */
+    tsType: string;
+}
+/**
+ * A read the gadget wants to make, described for the authorizer.
+ *
+ * `prohibitAllSharing` is the strongest statement available and the one worth getting right: it
+ * says the data this read returns may not be shared onward with any observer, whatever their own
+ * access is.
+ */
+export interface ObservationDescription {
+    title: string;
+    description: string;
+    prohibitAllSharing?: boolean;
+    excludeObservers?: string[];
+}
+/** A side effect the gadget wants to make, described for the approver. */
+export interface ActionDescription {
+    /** One line, like an email subject, for a list. */
+    title: string;
+    /** Markdown. Everything an approver needs in order to decide, with nothing held back. */
+    description: string;
+    /** Whether this gatekeeper implements `revertAction` for this action. */
+    implementsRevert: boolean;
+    /**
+     * Tells the agent not to keep working until this settles. Set by a gatekeeper that does NOT
+     * simulate the action's effects, which is ours: there is no provisional run id to hand back.
+     */
+    awaitDecision?: boolean;
+    /** The author's verdict that this action is safe to auto-apply, if the user opted in. */
+    autoApprovable?: boolean;
+    actionKind?: ActionKind;
+}
+/** The half of the queue that governs reads. */
+export interface ObservationAuthorizer {
+    /** Resolves when the read is permitted, and THROWS when it is not. */
+    authorizeObservation(description: ObservationDescription): Promise<void>;
+}
+/** What an approver is told about a hook the workspace is being asked to enable. */
+export interface HookDescription {
+    title: string;
+    description: string;
+}
+/** Where an enabled hook's deliveries land, as the workspace names it. */
+export interface HookTargetMetadata {
+    workspaceId: string;
+    gadgetId?: number;
+}
+/**
+ * What the workspace turns a bound hook on and off through. Implemented on THIS side.
+ *
+ * A hook is not live when it is bound: the workspace may have to ask a person first, and it calls
+ * `enable` if and when they say yes. The initiator it hands over is the ONLY thing worth keeping,
+ * and `disable` means every trace of the registration goes.
+ */
+export interface HookController {
+    enable(initiator: HookInitiator, target: HookTargetMetadata): Promise<void>;
+    disable(): Promise<void>;
+}
+/**
+ * What an enabled hook is delivered THROUGH: a fresh callback per event, never a stored one.
+ *
+ * The callback handed to `bindHook` is a loan like every other parameter stub, so the contract
+ * gives the initiator instead: ask for a callback when there is something to deliver, and get an
+ * approval queue with it, because a delivery is a read of the paired deployment and has to be
+ * authorized exactly as `approvals_list()` is.
+ */
+export interface HookInitiator {
+    startHook(): Promise<{
+        callback: unknown;
+        approvalQueue: ObservationAuthorizer;
+    }>;
+}
+/**
+ * What the OS hands to `startSession`: the chokepoint every operation passes through.
+ *
+ * `submitAction` takes an id this gatekeeper assigns and returns as soon as the action is QUEUED,
+ * not when it is decided. The decision arrives later as `applyAction(id)` or `rejectAction(id)` on
+ * the resource object.
+ */
+export interface ApprovalQueue extends ObservationAuthorizer {
+    submitAction(action: number, description: ActionDescription): Promise<void>;
+    /**
+     * Register a persistent callback, which the workspace holds and may not enable at once.
+     *
+     * The gatekeeper hands over a CONTROLLER of its own rather than keeping the callback: the
+     * callback is a parameter stub whose lifetime ends with this call, and what has to survive is
+     * the registration. Enabling arrives later on that controller.
+     */
+    bindHook(controller: unknown, callback: unknown, description: HookDescription): Promise<void>;
+}
+/** What a `GATEKEEPER_*` service binding reaches. */
+export interface VendorEntrypoint {
+    describe(): Promise<VendorDescription>;
+    getSupportedResources(options?: {
+        userId?: string;
+    }): Promise<SupportedResource[]>;
+    getTypeScriptTypes(): Promise<string>;
+    /** Returns the account stub the workspace persists. Opaque here: it is the OS's to hold. */
+    createAccount(): Promise<unknown>;
+}
+/** What the workspace holds for one connected account. */
+export interface AccountEntrypoint {
+    describe(): Promise<AccountDescription>;
+    getSupportedResources(): Promise<SupportedResource[]>;
+    getGatekeeperClassFor(url: string): Promise<{
+        class: unknown;
+        resource: SupportedResource;
+    }>;
+    ensureResources(resourceUrlPatterns: string[]): Promise<Record<string, never>>;
+    revoke(): Promise<void>;
+    getVerifier(): Promise<unknown>;
+    getAuthenticatedEmail(): Promise<string | null>;
+    reconnect(): Promise<{
+        url: string;
+    }>;
+}
+/** What one bound resource serves: the session, its types, and the action lifecycle. */
+export interface ResourceObject {
+    describe(): Promise<ResourceDescription>;
+    getTypeScriptTypes(): Promise<string>;
+    startSession(approvalQueue: ApprovalQueue): Promise<unknown>;
+    getAutoApprovableActions(): Promise<ActionKind[]>;
+    applyAction(action: number): Promise<void>;
+    rejectAction(action: number): Promise<void>;
+    revertAction(action: number): Promise<{
+        message: string;
+        canRetry: false;
+    }>;
+    addObserver(id: string, user: unknown): Promise<void>;
+    removeObserver(id: string): Promise<void>;
+}
+/** The identity stub another vendor's gatekeeper is handed. Carries no authority by design. */
+export interface VerifierEntrypoint {
+    describe(): Promise<{
+        accountId: string;
+    }>;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/os/protocol.d.ts.map

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

package/dist/os/protocol.js

@@ -0,0 +1,22 @@
+// The Cloudflare OS gatekeeper contract, transcribed.
+//
+// The published source (`cloudflare/cloudflare-os`, `packages/workshop-shared/src/gatekeeper.ts`)
+// is the authority for every shape below. It is TRANSCRIBED rather than imported because this
+// package depends on the cat-factory public surface and nothing else: taking a dependency on the
+// partner workspace would make their release cadence this package's build, which is the same
+// coupling the initiative's own CI rule refuses. The cost is that these declarations can fall
+// behind, and the answer to that is the nightly leg (`GATEKEEPER_OS_REF`), which boots a pinned
+// partner commit against this Worker and is allowed to go red on its own.
+//
+// The transcription is deliberately PARTIAL: it carries the members this Worker implements or is
+// handed, and omits the ones it does not (`getAgentCatalog`, `getSlashCommandProvider`,
+// `startAppUi`, the UI frames). An omitted optional member is a capability the OS correctly
+// reports as absent; a transcribed one this Worker did not implement would be a method that
+// exists and lies.
+//
+// Structural typing is what makes this safe. Nothing here is `extends`ed by a class the OS
+// constructs: the OS reaches a bound Worker's entrypoint over native RPC and calls methods by
+// name, so what has to match is the SHAPE. These interfaces exist to make our shape a compile-time
+// claim rather than a hope.
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/os/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/os/protocol.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,kGAAkG;AAClG,8FAA8F;AAC9F,iGAAiG;AACjG,6FAA6F;AAC7F,8FAA8F;AAC9F,gGAAgG;AAChG,0EAA0E;AAC1E,EAAE;AACF,iGAAiG;AACjG,wFAAwF;AACxF,4FAA4F;AAC5F,4FAA4F;AAC5F,mBAAmB;AACnB,EAAE;AACF,2FAA2F;AAC3F,8FAA8F;AAC9F,mGAAmG;AACnG,4BAA4B"}

package/dist/os/queue.d.ts

@@ -0,0 +1,99 @@
+import type { SessionGovernance } from '../capability.js';
+import { type CallSubject } from './descriptions.js';
+import { type HookControllerProps } from './hooks.js';
+import type { ApprovalQueue } from './protocol.js';
+/**
+ * One session's view of the ledger: what it may register, and the end of everything it registered.
+ *
+ * A handle rather than a second store, because the IDS are the object's (see {@link ActionLedger})
+ * while the LIFETIME is the session's, and the two facts have to live in one map for a decision
+ * naming an id to find the entry it settles.
+ */
+export interface LedgerSession {
+    /** Register an effect, returning the id to submit it under and the promise the caller awaits. */
+    register(label: string, perform: () => Promise<unknown>): {
+        id: number;
+        settled: Promise<unknown>;
+    };
+    /**
+     * Drop a registration whose submission never reached the queue.
+     *
+     * Without it a queue that throws would leave an entry the workspace can never decide, and the
+     * caller would be told about the submission failure while the ledger silently grew.
+     */
+    abandon(id: number): void;
+    /** The session is over: refuse every action it left undecided and drop them. */
+    end(): void;
+}
+/**
+ * The submitted-but-undecided actions of one resource object, and the decisions that settle them.
+ *
+ * Ids are sequential per object rather than per session, because the OS hands them back to the
+ * OBJECT (`applyAction` is a method on the resource, not on the session): two sessions minting
+ * overlapping ids would settle each other's actions.
+ */
+export declare class ActionLedger {
+    #private;
+    /** Open one session's handle. Ending it is what bounds the entries it registered. */
+    openSession(): LedgerSession;
+    /**
+     * Perform an approved action and hand its result to the waiting caller.
+     *
+     * The entry is removed BEFORE the effect runs, so a redelivered `applyAction` cannot perform it
+     * twice: at-least-once delivery is the normal state of a decision arriving over a network, and
+     * the second copy must be a refusal rather than a second write.
+     *
+     * A failing effect rejects the caller AND throws on to the workspace, which the contract asks
+     * for: the person who approved it is the one who gets to retry or discard.
+     */
+    apply(id: number): Promise<void>;
+    /** Reject an action: the awaiting call throws, and nothing is performed. */
+    reject(id: number): void;
+    /**
+     * How many actions are still waiting, across every live session on this object.
+     *
+     * Here so the ledger's one growth path is observable: an entry is added by a session and removed
+     * by a decision, an abandoned submission, or that session ending, and a count that does not
+     * return to zero once the sessions are gone is the leak this exists to fail a test on.
+     */
+    get pendingCount(): number;
+}
+/**
+ * Take a reference to the workspace's queue that outlives the call it arrived on.
+ *
+ * Workers RPC disposes every stub a call received as a PARAMETER the moment that call returns, and
+ * `startSession` returns immediately with a session that goes on using the queue for the rest of
+ * its life. Without this the first governed read or write would authorize against a stub the
+ * runtime had already torn down, and the failure would reach the caller as a broken connection
+ * rather than as anything naming the queue. `dup()` is what the RPC contract offers for exactly
+ * this case.
+ *
+ * The check is not defensiveness about a malformed argument: `ResourceCore` is also driven
+ * IN-PROCESS, by this package's own suite and by anything embedding it, and there the queue is an
+ * ordinary object that was never a stub and has nothing to duplicate.
+ *
+ * Paired with {@link releaseQueue} and kept beside it, because a duplicate taken here and released
+ * anywhere else is a leak that nothing about either half would show on its own.
+ */
+export declare function holdQueue(queue: ApprovalQueue): ApprovalQueue;
+/**
+ * The governance one session applies, over the queue the workspace handed it at `startSession`.
+ *
+ * Every method here is a thin translation: what to describe comes from the operation table
+ * (`descriptions.ts`), what to do about the answer is the contract's, and the effect itself stays
+ * the machinery's. That is what keeps this a facade rather than a second implementation.
+ */
+export declare function queueGovernance(deps: {
+    queue: ApprovalQueue;
+    ledger: LedgerSession;
+    subject: CallSubject;
+    /**
+     * Build the controller for one hook, which is this Worker's own `CatFactoryHookController`
+     * export imbued with the registration's identity.
+     *
+     * Supplied by the caller rather than built here because only the resource object can reach
+     * `ctx.exports`, and a session that could not build one is a session on a door with no hooks.
+     */
+    controllerFor: (props: HookControllerProps) => unknown;
+}): SessionGovernance;
+//# sourceMappingURL=queue.d.ts.map

package/dist/os/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/os/queue.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEzD,OAAO,EAAuC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACzF,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAclD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAC9B;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAA;IAC5C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,gFAAgF;IAChF,GAAG,IAAI,IAAI,CAAA;CACZ;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;;IAKvB,qFAAqF;IACrF,WAAW,IAAI,aAAa,CAO3B;IAED;;;;;;;;;OASG;IACG,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQrC;IAED,4EAA4E;IAC5E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAQvB;IAED;;;;;;OAMG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;CAiDF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAG7D;AAaD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,KAAK,EAAE,aAAa,CAAA;IACpB,MAAM,EAAE,aAAa,CAAA;IACrB,OAAO,EAAE,WAAW,CAAA;IACpB;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAA;CACvD,GAAG,iBAAiB,CAgGpB"}

package/dist/os/queue.js

@@ -0,0 +1,240 @@
+// The approval queue, threaded onto the session's one `invoke` seam.
+//
+// This is the half of the published contract that runs in the opposite direction from our approval
+// INBOX, and the two must not be confused. The inbox carries the PLATFORM's parked runs outward to
+// the OS, so a person can answer them. The queue carries the OS's governance INWARD over every call
+// an agent makes, so nothing is read or written without the workspace's kernel having authorized
+// it. A Gatekeeper needs both, and having one is no reason to skip the other.
+//
+// The action lifecycle is genuinely asynchronous, and the shape follows from that:
+//
+//   1. A mutating call assigns the next action id and records the effect in memory, UNPERFORMED.
+//   2. It submits the description and awaits a decision that does not come back from `submitAction`.
+//   3. `applyAction(id)` performs the effect and resolves the awaiting call with its result;
+//      `rejectAction(id)` rejects it.
+//
+// The pending set is in MEMORY, on purpose. The awaiting caller is a suspended RPC into this object,
+// so the object cannot be evicted while an action is pending, and if the RPC dies there is nobody
+// left to resolve: persisting the effect would only let a later `applyAction` perform a write whose
+// result nothing reads and whose caller was told nothing. An action that outlives its session is a
+// SIMULATING gatekeeper's problem, and simulation is deliberately not what this one does
+// (`awaitDecision: true` says so on every action it submits).
+//
+// So an entry's LIFETIME IS ITS SESSION'S, and nothing else bounds it. A TTL would be the wrong
+// bound twice over: the thing being waited on is a person deciding, which has no deadline worth
+// guessing, and expiring an entry would settle an action the workspace can still legitimately
+// apply. What DOES end is the session: when the workspace drops it, every action it submitted is
+// refused and dropped together, so the ledger of a long-lived resource object holds pending work
+// for live sessions only. Without that, an approval card nobody ever answered pinned its entry for
+// the object's whole lifetime, and `#take`'s "the session that submitted it has ended" was a
+// sentence nothing made true.
+import { describeError, GatekeeperError } from '../errors.js';
+import { describeAction, describeObservation } from './descriptions.js';
+import { describeHook, HOOK_TOPICS } from './hooks.js';
+/**
+ * The submitted-but-undecided actions of one resource object, and the decisions that settle them.
+ *
+ * Ids are sequential per object rather than per session, because the OS hands them back to the
+ * OBJECT (`applyAction` is a method on the resource, not on the session): two sessions minting
+ * overlapping ids would settle each other's actions.
+ */
+export class ActionLedger {
+    #nextId = 1;
+    #nextSession = 1;
+    #pending = new Map();
+    /** Open one session's handle. Ending it is what bounds the entries it registered. */
+    openSession() {
+        const session = this.#nextSession++;
+        return {
+            register: (label, perform) => this.#register(session, label, perform),
+            abandon: (id) => this.#pending.delete(id),
+            end: () => this.#endSession(session),
+        };
+    }
+    /**
+     * Perform an approved action and hand its result to the waiting caller.
+     *
+     * The entry is removed BEFORE the effect runs, so a redelivered `applyAction` cannot perform it
+     * twice: at-least-once delivery is the normal state of a decision arriving over a network, and
+     * the second copy must be a refusal rather than a second write.
+     *
+     * A failing effect rejects the caller AND throws on to the workspace, which the contract asks
+     * for: the person who approved it is the one who gets to retry or discard.
+     */
+    async apply(id) {
+        const action = this.#take(id, 'apply');
+        try {
+            action.resolve(await action.perform());
+        }
+        catch (error) {
+            action.reject(error);
+            throw error;
+        }
+    }
+    /** Reject an action: the awaiting call throws, and nothing is performed. */
+    reject(id) {
+        const action = this.#take(id, 'reject');
+        action.reject(new GatekeeperError('action_rejected', `The workspace rejected this action (${action.label}), so it was not performed.`));
+    }
+    /**
+     * How many actions are still waiting, across every live session on this object.
+     *
+     * Here so the ledger's one growth path is observable: an entry is added by a session and removed
+     * by a decision, an abandoned submission, or that session ending, and a count that does not
+     * return to zero once the sessions are gone is the leak this exists to fail a test on.
+     */
+    get pendingCount() {
+        return this.#pending.size;
+    }
+    #register(session, label, perform) {
+        const id = this.#nextId++;
+        const settled = new Promise((resolve, reject) => {
+            this.#pending.set(id, { perform, resolve, reject, label, session });
+        });
+        return { id, settled };
+    }
+    /**
+     * End one session: every action it submitted and nobody decided is refused, and nothing is
+     * performed.
+     *
+     * The awaiting caller is told, rather than left on a promise that can no longer settle: the
+     * session it called through is gone, so no `applyAction` can ever reach its effect again.
+     */
+    #endSession(session) {
+        // Deleting the entry the iterator is standing on is defined behaviour for a Map, so this
+        // walks the live one rather than a snapshot of it.
+        for (const [id, action] of this.#pending) {
+            if (action.session !== session)
+                continue;
+            this.#pending.delete(id);
+            action.reject(new GatekeeperError('session_ended', `The session that submitted this action (${action.label}) ended before the workspace ` +
+                'decided it, so it was not performed.'));
+        }
+    }
+    #take(id, verb) {
+        const action = this.#pending.get(id);
+        if (action === undefined) {
+            throw new GatekeeperError('unknown_action', `No action ${id} is pending on this resource, so there is nothing to ${verb}. It was ` +
+                'already decided, or the session that submitted it has ended.');
+        }
+        this.#pending.delete(id);
+        return action;
+    }
+}
+/**
+ * Take a reference to the workspace's queue that outlives the call it arrived on.
+ *
+ * Workers RPC disposes every stub a call received as a PARAMETER the moment that call returns, and
+ * `startSession` returns immediately with a session that goes on using the queue for the rest of
+ * its life. Without this the first governed read or write would authorize against a stub the
+ * runtime had already torn down, and the failure would reach the caller as a broken connection
+ * rather than as anything naming the queue. `dup()` is what the RPC contract offers for exactly
+ * this case.
+ *
+ * The check is not defensiveness about a malformed argument: `ResourceCore` is also driven
+ * IN-PROCESS, by this package's own suite and by anything embedding it, and there the queue is an
+ * ordinary object that was never a stub and has nothing to duplicate.
+ *
+ * Paired with {@link releaseQueue} and kept beside it, because a duplicate taken here and released
+ * anywhere else is a leak that nothing about either half would show on its own.
+ */
+export function holdQueue(queue) {
+    const stub = queue;
+    return typeof stub.dup === 'function' ? stub.dup() : queue;
+}
+/**
+ * Release this session's hold on the workspace's queue.
+ *
+ * The other half of {@link holdQueue}: a duplicate nobody disposes holds the workspace's end of
+ * the connection open for the resource object's whole lifetime. The optional call is the
+ * in-process case again, where nothing was duplicated and there is nothing to give back.
+ */
+function releaseQueue(queue) {
+    ;
+    queue[Symbol.dispose]?.();
+}
+/**
+ * The governance one session applies, over the queue the workspace handed it at `startSession`.
+ *
+ * Every method here is a thin translation: what to describe comes from the operation table
+ * (`descriptions.ts`), what to do about the answer is the contract's, and the effect itself stays
+ * the machinery's. That is what keeps this a facade rather than a second implementation.
+ */
+export function queueGovernance(deps) {
+    return {
+        async observe(binding, args) {
+            await deps.queue.authorizeObservation(describeObservation(binding, args, deps.subject));
+        },
+        async observeLocal(title, detail) {
+            await deps.queue.authorizeObservation({
+                title: `${title} (${deps.subject.deployment})`,
+                description: `${detail}\n\nServed from this Gatekeeper's own record of what the paired deployment ` +
+                    `at ${deps.subject.deployment} delivered, for account \`${deps.subject.accountId}\` at ` +
+                    `policy tier \`${deps.subject.tier}\`.`,
+            });
+        },
+        async act(binding, args, perform) {
+            const { id, settled } = deps.ledger.register(binding.summary, perform);
+            try {
+                await deps.queue.submitAction(id, describeAction(binding, args, deps.subject));
+            }
+            catch (error) {
+                // The submission failed, so no decision will ever arrive for this id. Dropping the
+                // registration is what stops the caller waiting on a promise nothing can settle.
+                deps.ledger.abandon(id);
+                throw error;
+            }
+            return (await settled);
+        },
+        /**
+         * Hand the workspace a controller and the callback, and keep NEITHER.
+         *
+         * Everything about the registration rides the controller's props, so this call leaves no
+         * state behind: the workspace may take days to approve the hook, or never approve it, and a
+         * row written here would be a registration for something nobody enabled. What comes back is
+         * nothing at all, because there is nothing to report yet; `hooks_bound()` answers once the
+         * workspace has enabled it.
+         */
+        async subscribe(topic, callback) {
+            // Reachable only in process, and kept for exactly that: an embedding suite hands over a
+            // plain object, where a missing method is a mistake worth naming. It CANNOT catch a
+            // workspace whose queue predates hooks, because a stub answers every property (the same
+            // fact `callBack` turns on), so `typeof` reads `function` for a method the far side does not
+            // implement. That case arrives below, as a failure from the far side.
+            if (typeof deps.queue.bindHook !== 'function') {
+                throw new GatekeeperError('hooks_unavailable', 'The approval queue this session was opened with offers no bindHook(), so this ' +
+                    'workspace cannot hold a callback for us. Read `approvals_list()` and ' +
+                    '`runs_watched()` instead: they carry exactly what a hook would push.');
+            }
+            const props = {
+                hookId: `hook_${crypto.randomUUID().replaceAll('-', '')}`,
+                topic,
+                accountId: deps.subject.accountId,
+                tier: deps.subject.tier,
+                deployment: deps.subject.deployment,
+            };
+            try {
+                await deps.queue.bindHook(deps.controllerFor(props), callback, describeHook(topic, deps.subject));
+            }
+            catch (error) {
+                // A workspace whose queue has no `bindHook` and a person who declined the registration
+                // both surface here, and this Gatekeeper cannot tell them apart: the contract offers no
+                // way to ask whether hooks are servable, and the two failures cross the wire the same way.
+                // So the cause is reported VERBATIM rather than sorted into a guess, because it is the one
+                // thing that distinguishes them and the two need opposite fixes.
+                throw new GatekeeperError('hook_bind_refused', `This workspace did not take the ${HOOK_TOPICS[topic].sessionMethod}() binding ` +
+                    `(${describeError(error)}). Either its approval queue serves no hooks, or the ` +
+                    'registration was declined. `approvals_list()` and `runs_watched()` answer exactly ' +
+                    'what the hook would have pushed, and go on doing so.');
+            }
+        },
+        close() {
+            // Order matters: the actions are refused while the queue is still ours to hold, so an
+            // awaiting caller is told the session ended rather than left on a promise whose only route
+            // to a decision has already been released.
+            deps.ledger.end();
+            releaseQueue(deps.queue);
+        },
+    };
+}
+//# sourceMappingURL=queue.js.map

package/dist/os/queue.js.map

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