@cat-factory/gatekeeper-worker 0.4.2 → 0.5.0

package/dist/os/protocol.d.ts

@@ -0,0 +1,150 @@
+/** 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 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>;
+}
+/** 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,90 @@
+import type { SessionGovernance } from '../capability.js';
+import { type CallSubject } from './descriptions.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;
+}): 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,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;CACrB,GAAG,iBAAiB,CA4CpB"}

package/dist/os/queue.js

@@ -0,0 +1,197 @@
+// 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 { GatekeeperError } from '../errors.js';
+import { describeAction, describeObservation } from './descriptions.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);
+        },
+        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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"}

package/dist/os/resource-core.d.ts

@@ -0,0 +1,100 @@
+import type { GatekeeperEnv } from '../env.js';
+import type { GatekeeperPolicy } from '../policy/compile.js';
+import type { ActionKind, ApprovalQueue, ResourceDescription, ResourceObject } from './protocol.js';
+/**
+ * What the account imbues a resource object with when it hands the class to the workspace.
+ *
+ * The account and NOTHING else. The URL the workspace matched is deliberately not here: under this
+ * Gatekeeper's own model a resource IS the paired workspace, so every URL that matches the pattern
+ * binds the same one and the matched URL decides nothing. Carrying it would be state whose only
+ * effect is that the next reader has to work out it decides nothing, and it had already been
+ * assigned the pattern rather than the match without anything noticing. A consumer that genuinely
+ * needs the bound URL adds it back WITH the reader that wants it, which is also the change that
+ * would say which of the two it meant.
+ */
+export interface ResourceProps {
+    /** The account this resource is bound for. Every key minted through it is stamped with this. */
+    accountId: string;
+}
+/** One bound resource: the session it opens, its types, and the action lifecycle behind it. */
+export declare class ResourceCore implements ResourceObject {
+    #private;
+    constructor(env: GatekeeperEnv, policy: GatekeeperPolicy, props: ResourceProps);
+    describe(): Promise<ResourceDescription>;
+    /**
+     * The session's own types, rendered for the tier this account holds.
+     *
+     * Tier-specific rather than a copy of the vendor's, because this is the one the contract points a
+     * caller at: `ResourceDescription.tsType` must name an export of THIS method's output, and a
+     * session carries exactly its granted operations.
+     */
+    getTypeScriptTypes(): Promise<string>;
+    /**
+     * Open a governed session.
+     *
+     * The queue is not optional and not a decoration: every operation the returned object carries
+     * funnels through the one `invoke` closure, which submits actions to this queue and authorizes
+     * observations against it. The tier policy underneath is the FLOOR, so an operation the policy
+     * never granted is absent from the object rather than something the queue has to refuse.
+     *
+     * The queue passed here is OWNED by the session that comes back: it is released, along with
+     * every action that session left undecided, when the session is disposed. A caller reaching this
+     * over RPC therefore hands in a reference of its own rather than the parameter it received (see
+     * `resource.ts`), because the parameter's lifetime ends when this call returns and the session's
+     * does not.
+     */
+    startSession(approvalQueue: ApprovalQueue): Promise<unknown>;
+    /**
+     * How many submitted actions this object is still holding, across every live session.
+     *
+     * Exposed for the same reason the ledger counts them: the ONE unbounded thing about a long-lived
+     * resource object is this set, and a count that does not fall back to zero when the sessions are
+     * gone is the leak rather than a slow day.
+     */
+    get pendingActionCount(): number;
+    /**
+     * The action kinds this Gatekeeper may auto-apply, if the user opted into the kind.
+     *
+     * Derived from the same table and the same consequence reading `describeAction` stamps onto each
+     * submission, so a pre-approval UI listing kinds before any action exists and the `autoApprovable`
+     * flag on an action that has been submitted cannot disagree.
+     *
+     * TODAY THIS IS EMPTY, and that is the honest answer rather than a gap. The public surface
+     * annotates a consequence only where the stakes are real money or a merged pull request, so every
+     * other mutation is unannotated, and the table's documented reading of an unannotated mutation is
+     * that it is destructive. Offering those for unattended auto-approval would mean inverting that
+     * default here, which is precisely the misreading `resolveConsequence` exists to stop. If the
+     * surface ever states that a write is safe, it appears here with no further decision.
+     */
+    getAutoApprovableActions(): Promise<ActionKind[]>;
+    /** The workspace approved an action: perform it, and hand the result to the waiting call. */
+    applyAction(action: number): Promise<void>;
+    /** The workspace rejected an action: the waiting call throws and nothing is performed. */
+    rejectAction(action: number): Promise<void>;
+    /**
+     * Reverting is not something this Gatekeeper can do, which every action it submits already states
+     * (`implementsRevert: false`).
+     *
+     * It answers rather than throwing because the caller is the workspace UI on behalf of a person who
+     * wants their change undone: a message naming what they have to do themselves is the useful
+     * answer, where an exception would surface as a failed revert they might retry.
+     */
+    revertAction(_action: number): Promise<{
+        message: string;
+        canRetry: false;
+    }>;
+    /**
+     * Sharing this resource's observations onward is REFUSED, which blocks the share.
+     *
+     * The contract asks the gatekeeper to verify that the new viewer could directly read everything
+     * historically observed through it. This Gatekeeper cannot answer that: it keeps no observation
+     * log, and the plausible rule (the observer's own tier reaches every operation that produced the
+     * observed data) needs a tier for a viewer this deployment's policy has never named. A share
+     * blocked loudly beats an observation leaked quietly, so the refusal stands until there is a rule
+     * worth writing down.
+     */
+    addObserver(id: string, _user: unknown): Promise<void>;
+    /** Idempotent by contract: nothing was ever added, so there is nothing to forget. */
+    removeObserver(_id: string): Promise<void>;
+}
+//# sourceMappingURL=resource-core.d.ts.map

package/dist/os/resource-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-core.d.ts","sourceRoot":"","sources":["../../src/os/resource-core.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAG9C,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE1E,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAInG;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,gGAAgG;IAChG,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,+FAA+F;AAC/F,qBAAa,YAAa,YAAW,cAAc;;IAMjD,YAAY,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa,EAI7E;IAEK,QAAQ,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAW7C;IAED;;;;;;OAMG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAE1C;IAED;;;;;;;;;;;;;OAaG;IACG,YAAY,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAejE;IAED;;;;;;OAMG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED;;;;;;;;;;;;;OAaG;IACG,wBAAwB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAKtD;IAED,6FAA6F;IACvF,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;IAED,0FAA0F;IACpF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhD;IAED;;;;;;;OAOG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAA;KAAE,CAAC,CAOjF;IAED;;;;;;;;;OASG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAO3D;IAED,qFAAqF;IAC/E,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAG;CASpD"}