@cat-factory/gatekeeper-worker 0.4.3 → 0.6.0

package/dist/os/hook-controller.js

@@ -0,0 +1,53 @@
+// The handle a workspace turns one bound hook on and off by.
+//
+// It is a fifth named export for the same reason the verifier is a fourth: what the workspace has
+// to hold is not what the workspace has to be able to DO. A controller carries no capability, no
+// key and no session; it names one registration, and its two methods are the only two things
+// anybody may do to that registration from outside. Handing over a session or an account instead
+// would hand over everything they carry along with the ability to disable a hook.
+//
+// Its props ARE the registration's identity, which is what keeps this class stateless: the
+// workspace persists the controller, so the id, the topic, the account and the tier ride back in
+// on `enable` without this Gatekeeper keeping a table of hooks nobody has approved yet. That is
+// also the contract's own instruction ("avoid storing any state until the hook is enabled") read
+// literally rather than approximately.
+import { WorkerEntrypoint } from 'cloudflare:workers';
+import { stateFor } from '../env.js';
+/**
+ * Build the hook controller class a deployment exports.
+ *
+ * No policy argument, like the verifier: nothing here resolves a tier or compiles a grant. The
+ * tier a delivery is described at was resolved by the session that bound the hook and rides the
+ * props, because re-resolving it here would silently re-tier a live hook the day an operator edits
+ * the policy, with the workspace still believing it enabled the one it was shown.
+ */
+export function createGatekeeperHookController() {
+    return class CatFactoryHookController extends WorkerEntrypoint {
+        /**
+         * The workspace approved the hook: record it, and hold the initiator it handed over.
+         *
+         * Re-enabling an already-enabled hook REPLACES the initiator, which the contract asks for, and
+         * the store keeps the counters this call zeroes (see `enableHook`): they are the
+         * registration's history rather than that stub's, so resetting them would erase the record of
+         * the deliveries a workspace missed at exactly the moment it is re-arming to stop missing them.
+         */
+        async enable(initiator, target) {
+            const record = {
+                ...this.ctx.props,
+                target,
+                enabledAt: Date.now(),
+                deliveries: 0,
+                missed: 0,
+                failures: 0,
+                lastDeliveryAt: null,
+                lastError: null,
+            };
+            await stateFor(this.env).enableHook(record, initiator);
+        }
+        /** The workspace withdrew the hook: the record and the live half both go, permanently. */
+        async disable() {
+            await stateFor(this.env).disableHook(this.ctx.props.hookId);
+        }
+    };
+}
+//# sourceMappingURL=hook-controller.js.map

package/dist/os/hook-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-controller.js","sourceRoot":"","sources":["../../src/os/hook-controller.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,kGAAkG;AAClG,iGAAiG;AACjG,6FAA6F;AAC7F,iGAAiG;AACjG,kFAAkF;AAClF,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,gGAAgG;AAChG,iGAAiG;AACjG,uCAAuC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAsB,MAAM,WAAW,CAAA;AAMxD;;;;;;;GAOG;AACH,MAAM,UAAU,8BAA8B;IAI5C,OAAO,MAAM,wBAAyB,SAAQ,gBAG7C;QACC;;;;;;;WAOG;QACH,KAAK,CAAC,MAAM,CAAC,SAAwB,EAAE,MAA0B;YAC/D,MAAM,MAAM,GAAe;gBACzB,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK;gBACjB,MAAM;gBACN,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,UAAU,EAAE,CAAC;gBACb,MAAM,EAAE,CAAC;gBACT,QAAQ,EAAE,CAAC;gBACX,cAAc,EAAE,IAAI;gBACpB,SAAS,EAAE,IAAI;aAChB,CAAA;YACD,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;QACxD,CAAC;QAED,0FAA0F;QAC1F,KAAK,CAAC,OAAO;YACX,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QAC7D,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/os/hooks.d.ts

@@ -0,0 +1,200 @@
+import type { ApprovalCard, RunState } from '../state.js';
+import type { HookDescription, HookInitiator, HookTargetMetadata, ObservationDescription } from './protocol.js';
+/** What a workspace can be pushed. */
+export type HookTopic = 'approval_card' | 'run_event';
+/**
+ * The two topics, as an exhaustive `Record`, so a third one cannot be half-added.
+ *
+ * A topic is a delivery FAMILY this Gatekeeper already receives and projects, never a new
+ * subscription upstream: what the platform sends is decided by `enroll()`, and a hook that pushed
+ * something the webhook does not carry would be a promise no delivery could keep.
+ */
+export declare const HOOK_TOPICS: {
+    readonly approval_card: {
+        readonly sessionMethod: 'approvals_subscribe';
+        readonly callbackMethod: 'onApprovalCard';
+        readonly title: 'Push cat-factory approval cards as they are raised';
+        readonly description: string;
+    };
+    readonly run_event: {
+        readonly sessionMethod: 'runs_subscribe';
+        readonly callbackMethod: 'onRunEvent';
+        readonly title: 'Push cat-factory run lifecycle transitions';
+        readonly description: string;
+    };
+};
+/** Every topic, for a caller that has to cover all of them. */
+export declare const HOOK_TOPIC_NAMES: HookTopic[];
+/** What a hook's controller is imbued with when a session binds it. */
+export interface HookControllerProps {
+    hookId: string;
+    topic: HookTopic;
+    /** The account whose session bound it. A session reads back only its own account's hooks. */
+    accountId: string;
+    /** The policy tier that account resolved to, for the delivery's own description. */
+    tier: string;
+    /** The paired deployment, so the record can describe a delivery without resolving config. */
+    deployment: string;
+}
+/** One enabled hook, as it is stored. Written on `enable`, deleted on `disable`. */
+export interface HookRecord extends HookControllerProps {
+    /** The workspace the hook was enabled from, and the gadget within it where there is one. */
+    target: HookTargetMetadata;
+    enabledAt: number;
+    /** Deliveries this hook has taken. */
+    deliveries: number;
+    /**
+     * Deliveries that found no live initiator, so nothing was pushed.
+     *
+     * The one number that must never be inferred from silence: it is what tells a workspace that
+     * its hook stopped receiving without anybody deciding it should.
+     */
+    missed: number;
+    /** Deliveries the workspace's own side refused or failed. */
+    failures: number;
+    lastDeliveryAt: number | null;
+    /** The most recent failure, kept so a reader has something to act on beyond a count. */
+    lastError: string | null;
+}
+/**
+ * What IDENTIFIES a registration in storage: the place its deliveries land.
+ *
+ * Not the hook id, which is the wrong key for the one lifecycle a workspace is documented to run.
+ * The live half of a registration cannot be stored, so a durable object evicted between two
+ * deliveries keeps the record and loses the stub, and the remedy is to bind again. A bind mints a
+ * FRESH hook id, so a hook-id-keyed row made every one of those cycles a new row: the dead
+ * registration stayed forever, never live, counting a `missed` against every delivery for the rest
+ * of the deployment's life, and no reader could tell it from a hook that had genuinely gone quiet.
+ *
+ * Keying on the target makes re-binding what it reads as: the same registration, re-armed. The row
+ * is replaced, its counters carry forward (the `missed` count is the evidence the workspace acted
+ * on, so re-arming must not erase it), and the set of rows stays bounded by the gadgets a
+ * workspace actually runs rather than by how many times one was re-armed.
+ *
+ * The account comes first and is never the caller's to assert, so no target a workspace names can
+ * collide with another account's row; the remaining parts are escaped so a separator inside one of
+ * them cannot make two different targets share a key.
+ */
+export declare function registrationKey(record: {
+    accountId: string;
+    topic: HookTopic;
+    target: HookTargetMetadata;
+}): string;
+/**
+ * One hook as a session reads it back, which is the record PLUS the fact it cannot store.
+ *
+ * `live` is computed at read time from whether the initiator is still held, never persisted: a
+ * stored flag would say "live" from before the eviction that made it false, which is the one
+ * reading that must not be available.
+ */
+export interface HookRegistration extends HookRecord {
+    live: boolean;
+}
+/**
+ * What one fan-out did, summed over every push it made.
+ *
+ * It carries no topic: a change can produce payloads for more than one (a terminal run event
+ * settles the run's open cards as it records the transition), and one number per outcome across
+ * all of them is what a caller acts on. WHICH topics were dispatched is the receiver's to report,
+ * because it is knowable before any push is made.
+ */
+export interface HookDispatchReport {
+    delivered: number;
+    /** Registrations whose live half was lost, so nothing was pushed and the record counted it. */
+    stale: number;
+    failed: number;
+}
+/** What a topic pushes, as the callback receives it. */
+export type HookPayload = {
+    topic: 'approval_card';
+    card: ApprovalCard;
+} | {
+    topic: 'run_event';
+    state: RunState;
+};
+/**
+ * One thing a committed write left to push, named by its id rather than carried whole.
+ *
+ * The fan-out runs in the durable object and the write is reported out of it, so what crosses that
+ * boundary is a list of ids and the dispatcher reads each row back. Two reasons, and the second is
+ * the one that decides it. A `RunState` carries the run projection verbatim as an open record,
+ * which a Durable Object stub's serialization type will not carry (the same constraint
+ * `runs_watched()` annotates around), so a payload cannot make the trip. And re-reading is the
+ * more correct half anyway: a card that has been answered between the commit and the push is
+ * pushed as it now stands, rather than as the delivery left it.
+ */
+export type HookPushTarget = {
+    topic: 'approval_card';
+    cardId: string;
+} | {
+    topic: 'run_event';
+    runId: string;
+};
+/** What the approver is asked when a workspace binds a hook. */
+export declare function describeHook(topic: HookTopic, subject: {
+    accountId: string;
+    tier: string;
+    deployment: string;
+}): HookDescription;
+/**
+ * What the queue is asked before ONE delivery is pushed.
+ *
+ * A hook delivery is an observation and is authorized as one, which the contract asks for and
+ * which is also the only reading that holds: the bytes are a card the paired deployment raised,
+ * and that they arrived here over a webhook rather than over a read is an implementation detail of
+ * how they got here. The refusal path is what makes it matter: a workspace that has withdrawn a
+ * person's access can stop the push without this Gatekeeper having to be told.
+ */
+export declare function describeHookDelivery(payload: HookPayload, record: HookRecord): ObservationDescription;
+/** The live half of a registration: the workspace's initiator, held past the call it arrived on. */
+export type HookRegistry = Map<string, HookInitiator>;
+/**
+ * Take a reference to a stub that outlives the call it arrived on.
+ *
+ * The same loan rule `holdQueue` documents, arriving on the other parameter the contract hands
+ * over: the runtime disposes a parameter stub when the method returns, and an initiator kept for
+ * the next delivery is used long after that. The optional call is the in-process case, where the
+ * "stub" is an ordinary object with nothing to duplicate.
+ */
+export declare function holdInitiator(initiator: HookInitiator): HookInitiator;
+/** Give back a held reference. Paired with {@link holdInitiator} and kept beside it. */
+export declare function releaseInitiator(initiator: HookInitiator): void;
+/**
+ * What one push did, SEPARATE from the record it will be counted on.
+ *
+ * The split is the whole safety property of the fan-out. A push awaits a call into another Worker,
+ * which is not a storage operation, so the durable object's input gate is open across it and the
+ * record read before the push is a snapshot that may be stale by the time it resolves: a
+ * concurrent `disable` may have removed the registration, and a concurrent delivery may have moved
+ * the very counters this one is about to bump. Reporting the outcome and folding it onto whatever
+ * is stored AFTERWARDS is what keeps both of those true, where writing back a modified snapshot
+ * resurrected the withdrawn registration and lost the sibling's increments.
+ */
+export type HookPushOutcome = {
+    outcome: 'delivered';
+}
+/** The registration's live half was lost, so there was nothing to push through. */
+ | {
+    outcome: 'stale';
+} | {
+    outcome: 'failed';
+    error: string;
+};
+/**
+ * Push one payload to one enabled hook, and report what that did.
+ *
+ * Every outcome is a REPORT rather than a throw, because the caller is a fan-out on behalf of a
+ * delivery whose record has already committed: a workspace that refuses, breaks or hangs costs a
+ * notification, and must never cost the acknowledgement the platform's retry is protecting.
+ */
+export declare function pushToHook(payload: HookPayload, record: HookRecord, initiator: HookInitiator | undefined): Promise<HookPushOutcome>;
+/**
+ * Fold one push's outcome onto the record as it stands NOW.
+ *
+ * Pure, and takes the current record rather than the one the push was described from, so a caller
+ * can re-read between the two. `lastError` is cleared by a delivery on purpose: it is what a
+ * reader acts on beside `failures`, and a stale one beside a hook that has since recovered points
+ * at a fix nobody needs to make.
+ */
+export declare function applyPushOutcome(record: HookRecord, result: HookPushOutcome, now: number): HookRecord;
+//# sourceMappingURL=hooks.d.ts.map

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

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

package/dist/os/hooks.js

@@ -0,0 +1,253 @@
+// PUSHING what the inbox already holds: the approval cards and run transitions a workspace would
+// otherwise have to ask for.
+//
+// Nothing here is a new source of truth, and that is the whole design. A delivery arrives on the
+// webhook, is verified, deduped and written to durable state, and only THEN is anything pushed:
+// `approvals_list()` and `runs_watched()` go on answering the same question for a workspace that
+// never bound a hook, and for one whose hook missed an event. So a hook is an accelerator over a
+// projection, never the projection itself, and every failure mode below is safe in exactly that
+// way: what a hook loses, a read still has.
+//
+// The lifecycle is the published contract's, and each step exists for a reason worth keeping:
+//
+//   1. A session calls `approvals_subscribe(callback)`. We mint a hook id, build a CONTROLLER of
+//      our own, and hand both the controller and the callback to `queue.bindHook`. We store
+//      NOTHING: the workspace may still have to ask a person, and a gatekeeper that wrote a row
+//      here would be holding registrations for hooks nobody ever approved.
+//   2. The workspace approves and calls `enable(initiator, target)` on that controller. NOW there
+//      is state: the durable record, plus the initiator held live.
+//   3. Each event calls `initiator.startHook()` for a FRESH callback and the queue that governs
+//      it, authorizes the delivery as the observation it is, and delivers.
+//   4. `disable()` removes both halves. The contract asks for a permanent clean-up and means it.
+//
+// THE CALLBACK IS NEVER STORED, at any point. It is a parameter stub, so the runtime disposes it
+// when the call it arrived on returns; storing one would leave a registration that looks live and
+// throws on the first delivery, months after the mistake.
+//
+// THE INITIATOR IS HELD IN MEMORY, and that is a real limit rather than an oversight. A stub is a
+// reference into another Worker and there is no way to write one to storage, so a Durable Object
+// that is evicted between two deliveries keeps the record and loses the live half. That is why
+// every record COUNTS its missed deliveries and why `hooks_bound()` publishes the count beside
+// `live`: a workspace can see that its hook went quiet, and reconcile from the projection that
+// never did. A silent stop would be the one failure this design cannot tolerate, because a
+// workspace has no way to tell it from a deployment where nothing happened.
+//
+// So RE-BINDING IS THE DOCUMENTED REMEDY, and a registration is therefore keyed on where its
+// deliveries land rather than on the id one bind minted (`registrationKey`). Re-arming a hook is
+// the same registration coming back, not a second one beside the first.
+import { describeError } from '../errors.js';
+import { fenced } from '../markdown.js';
+/**
+ * The two topics, as an exhaustive `Record`, so a third one cannot be half-added.
+ *
+ * A topic is a delivery FAMILY this Gatekeeper already receives and projects, never a new
+ * subscription upstream: what the platform sends is decided by `enroll()`, and a hook that pushed
+ * something the webhook does not carry would be a promise no delivery could keep.
+ */
+export const HOOK_TOPICS = {
+    approval_card: {
+        sessionMethod: 'approvals_subscribe',
+        callbackMethod: 'onApprovalCard',
+        title: 'Push cat-factory approval cards as they are raised',
+        description: 'Each time the paired cat-factory deployment reports that a run has parked on a human ' +
+            'decision, or that a card it raised has been settled elsewhere, the card is pushed to this ' +
+            'callback. It carries exactly what `approvals_list()` answers with, which stays available ' +
+            'and stays authoritative: a delivery missed while this hook was not live is still readable ' +
+            'there.',
+    },
+    run_event: {
+        sessionMethod: 'runs_subscribe',
+        callbackMethod: 'onRunEvent',
+        title: 'Push cat-factory run lifecycle transitions',
+        description: 'Each time the paired cat-factory deployment reports that a run has started, completed or ' +
+            'failed, the run’s latest state is pushed to this callback. It carries exactly what ' +
+            '`runs_watched()` answers with, which stays available and stays authoritative.',
+    },
+};
+/** Every topic, for a caller that has to cover all of them. */
+export const HOOK_TOPIC_NAMES = Object.keys(HOOK_TOPICS);
+/**
+ * What IDENTIFIES a registration in storage: the place its deliveries land.
+ *
+ * Not the hook id, which is the wrong key for the one lifecycle a workspace is documented to run.
+ * The live half of a registration cannot be stored, so a durable object evicted between two
+ * deliveries keeps the record and loses the stub, and the remedy is to bind again. A bind mints a
+ * FRESH hook id, so a hook-id-keyed row made every one of those cycles a new row: the dead
+ * registration stayed forever, never live, counting a `missed` against every delivery for the rest
+ * of the deployment's life, and no reader could tell it from a hook that had genuinely gone quiet.
+ *
+ * Keying on the target makes re-binding what it reads as: the same registration, re-armed. The row
+ * is replaced, its counters carry forward (the `missed` count is the evidence the workspace acted
+ * on, so re-arming must not erase it), and the set of rows stays bounded by the gadgets a
+ * workspace actually runs rather than by how many times one was re-armed.
+ *
+ * The account comes first and is never the caller's to assert, so no target a workspace names can
+ * collide with another account's row; the remaining parts are escaped so a separator inside one of
+ * them cannot make two different targets share a key.
+ */
+export function registrationKey(record) {
+    return [
+        record.accountId,
+        record.topic,
+        record.target.workspaceId,
+        record.target.gadgetId === undefined ? '' : String(record.target.gadgetId),
+    ]
+        .map((part) => encodeURIComponent(part))
+        .join(':');
+}
+/** What the approver is asked when a workspace binds a hook. */
+export function describeHook(topic, subject) {
+    const definition = HOOK_TOPICS[topic];
+    return {
+        title: `${definition.title} (${subject.deployment})`,
+        description: `${definition.description}\n\nDeliveries are made for account \`${subject.accountId}\` at ` +
+            `policy tier \`${subject.tier}\`, and each one is authorized as an observation before it ` +
+            'is pushed.',
+    };
+}
+/**
+ * What the queue is asked before ONE delivery is pushed.
+ *
+ * A hook delivery is an observation and is authorized as one, which the contract asks for and
+ * which is also the only reading that holds: the bytes are a card the paired deployment raised,
+ * and that they arrived here over a webhook rather than over a read is an implementation detail of
+ * how they got here. The refusal path is what makes it matter: a workspace that has withdrawn a
+ * person's access can stop the push without this Gatekeeper having to be told.
+ */
+export function describeHookDelivery(payload, record) {
+    const subject = payload.topic === 'approval_card'
+        ? `The approval card \`${payload.card.cardId}\` raised for run \`${payload.card.runId}\`, ` +
+            `titled:\n\n${fenced(payload.card.title, '')}`
+        : `Run \`${payload.state.runId}\` reported \`${payload.state.event}\`.`;
+    return {
+        title: `${HOOK_TOPICS[payload.topic].title} (${record.deployment})`,
+        description: `${subject}\n\nPushed to a hook this workspace enabled for account ` +
+            `\`${record.accountId}\` at policy tier \`${record.tier}\`, from the record of what the ` +
+            `paired deployment at ${record.deployment} delivered.`,
+    };
+}
+/**
+ * Take a reference to a stub that outlives the call it arrived on.
+ *
+ * The same loan rule `holdQueue` documents, arriving on the other parameter the contract hands
+ * over: the runtime disposes a parameter stub when the method returns, and an initiator kept for
+ * the next delivery is used long after that. The optional call is the in-process case, where the
+ * "stub" is an ordinary object with nothing to duplicate.
+ */
+export function holdInitiator(initiator) {
+    const stub = initiator;
+    return typeof stub.dup === 'function' ? stub.dup() : initiator;
+}
+/** Give back a held reference. Paired with {@link holdInitiator} and kept beside it. */
+export function releaseInitiator(initiator) {
+    ;
+    initiator[Symbol.dispose]?.();
+}
+/**
+ * How long one workspace has to take one push before it is counted as a failure.
+ *
+ * A hook delivery is a call into somebody else's Worker, and the failure this bounds is the one
+ * with no natural end: a workspace that accepts the connection and never answers. Unbounded, one
+ * such hook holds the fan-out (and, on the receiver, the invocation carrying it) until the runtime
+ * kills it, and the counter update that would have SAID so never lands, so the registration reads
+ * as one nothing was ever pushed to.
+ */
+const PUSH_TIMEOUT_MS = 10_000;
+/**
+ * Push one payload to one enabled hook, and report what that did.
+ *
+ * Every outcome is a REPORT rather than a throw, because the caller is a fan-out on behalf of a
+ * delivery whose record has already committed: a workspace that refuses, breaks or hangs costs a
+ * notification, and must never cost the acknowledgement the platform's retry is protecting.
+ */
+export async function pushToHook(payload, record, initiator) {
+    if (initiator === undefined)
+        return { outcome: 'stale' };
+    try {
+        await withDeadline(deliverThrough(initiator, payload, record), PUSH_TIMEOUT_MS);
+        return { outcome: 'delivered' };
+    }
+    catch (error) {
+        return { outcome: 'failed', error: describeError(error) };
+    }
+}
+/**
+ * Fold one push's outcome onto the record as it stands NOW.
+ *
+ * Pure, and takes the current record rather than the one the push was described from, so a caller
+ * can re-read between the two. `lastError` is cleared by a delivery on purpose: it is what a
+ * reader acts on beside `failures`, and a stale one beside a hook that has since recovered points
+ * at a fix nobody needs to make.
+ */
+export function applyPushOutcome(record, result, now) {
+    if (result.outcome === 'stale')
+        return { ...record, missed: record.missed + 1 };
+    if (result.outcome === 'failed') {
+        return { ...record, failures: record.failures + 1, lastError: result.error };
+    }
+    return { ...record, deliveries: record.deliveries + 1, lastDeliveryAt: now, lastError: null };
+}
+/** One delivery, through a callback minted for it and released with it. */
+async function deliverThrough(initiator, payload, record) {
+    const started = await initiator.startHook();
+    try {
+        await started.approvalQueue.authorizeObservation(describeHookDelivery(payload, record));
+        await callBack(started.callback, payload);
+    }
+    finally {
+        releaseStarted(started);
+    }
+}
+/**
+ * Give up on a push that never answers, and say that is what happened.
+ *
+ * The timer is cleared on both paths: a Worker invocation stays alive while one is outstanding, so
+ * leaving them behind would hold every delivery's invocation open for the timeout even when every
+ * push answered at once.
+ */
+async function withDeadline(work, timeoutMs) {
+    let timer;
+    const expiry = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`The workspace did not answer this hook delivery within ${timeoutMs}ms, so it was ` +
+            'counted as a failure rather than waited on.')), timeoutMs);
+    });
+    try {
+        return await Promise.race([work, expiry]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Call the topic's method on the workspace's callback.
+ *
+ * A callback with no such method is a FAILURE that says so, rather than a push that quietly does
+ * nothing: the workspace implements the interface this package publishes in the session types, and
+ * a mismatch between the two is exactly the thing a count of failures should make visible.
+ */
+async function callBack(callback, payload) {
+    const method = HOOK_TOPICS[payload.topic].callbackMethod;
+    if (callback === null || callback === undefined) {
+        throw new Error('This hook was started with no callback, so nothing could be delivered to it.');
+    }
+    const target = callback;
+    // Two things about a stub decide the shape of these three lines, and both read as pedantry until
+    // they bite. A stub answers EVERY property, so the absent-method check can only catch a plain
+    // object (which is the in-process case, and the one where a helpful message is worth having);
+    // for a real callback the missing method surfaces from the far side, as it should. And the
+    // invocation is DIRECT rather than through `Function.prototype.call`, because `deliver.call(…)`
+    // on a stub asks the far side for an operation named `onApprovalCard.call`.
+    if (target[method] === undefined) {
+        throw new Error(`The callback this hook was started with has no ${method}() method, so nothing could be ` +
+            'delivered to it.');
+    }
+    await target[method](payload.topic === 'approval_card' ? payload.card : payload.state);
+}
+/** Release both stubs one `startHook()` handed over. Neither outlives the delivery. */
+function releaseStarted(started) {
+    ;
+    started.callback?.[Symbol.dispose]?.();
+    started.approvalQueue?.[Symbol.dispose]?.();
+}
+//# sourceMappingURL=hooks.js.map

package/dist/os/hooks.js.map

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