@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-10-28
+
+### Fixed
+- The interaction notifier and chat answer correlation now inspect
+  records through core's non-consuming `peekInteraction` instead of the
+  one-shot delivery read. The early-answer race is closed: a secret
+  interaction answered in the webui before the notifier's first pass no
+  longer loses the owning extension's raw-secret delivery (the gateway
+  owns no delivery; regression-tested with a fixture owner).
+- Home-DM settled notices report failed/aborted runs truthfully:
+  `Reply ready` only for answered runs; unanswered runs read `Run ended
+  without a reply` with the settle reason (empty reasons included).
+  Recipient, dedup, bound-conversation suppression, and `notify.home`
+  gating are unchanged.
+
+## [0.1.1] - 2026-10-27
+### Fixed
+- First real publish. `0.1.0` was registered with the npm name bootstrap but
+  never published: a staged `0.1.0` entry (left by the bootstrap) made the
+  registry reject the release with `E409 Cannot publish over previously
+  staged version`. Rejecting that entry removed the package name entirely,
+  so the name was re-bootstrapped and `0.1.1` published past it. The package
+  contents are the 0.1.0 contents plus the `@sigrun/shared` 0.2.0 peer.
+
+### Changed
+- `@sigrun/shared` peer follows the family 0.2.0 cut.
+
+## [0.1.0] - 2026-10-23
+### Added
+- Channel supervision with retry/backoff, adapter status and pairing
+  health surfaces, and bounded ordered shutdown.
+- The live inbound pipeline: dedupe, allowlist/pairing/self-link access,
+  DM and group routing, albums, media uploads, and chat commands.
+- Durable final delivery with access re-checks, retry classification,
+  crash recovery, home notifications, and one-shot job targets.
+- Live response previews through adapter editing, typing fallback,
+  authoritative final hand-off, and preview cleanup at shutdown.
+- `send_message` and `list_chats` agent tools and the bound-chat prompt
+  section.
+- User-deletion cleanup for gateway identity links and home chats.
+- Operator guide covering configuration, pairing, groups, jobs, and
+  disabling the engine or one channel.
+- Repository scaffold from the sigrun-ext-codemode shape (host modules as
+  `peerDependencies` mirrored in `devDependencies`; `@sigrun/sigrun` and
+  `@sigrun/shared` as `file:` devDependencies; manifest hygiene check
+  wired into `npm test`; dist committed).
+- The loader-contract factory: `createGateway(host)` →
+  `{ extension, gateway }` with the pi-durable extension (declared name
+  `gateway`) and the engine skeleton — `start` creates
+  `<stateDir>/gateway/`, starts every READY channel adapter, and records
+  the channel set; `stopIntake`/`stop` resolve; `health` reads `"ok"`.
+- `parseGatewayConfig`/`readConfig` (live per-read parsing of
+  `settings/gateway.json`; malformed channel/group blocks parse to
+  `{failed}` forms without affecting siblings).
+- `JsonFile<T>` state primitive (serialized updates, atomic 0600 writes,
+  malformed-file errors naming the path).
+- `hashId` + the scoped `createLog` logger with per-key `once` dedupe.
+- `test/fake-host.ts`: the in-memory `SigrunHost` (conversations, users,
+  access, identity, models, commands, interactions, stores; `fake.calls`
+  ordered log, `fake.setClaimed`, `fake.pushView`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+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

@@ -1,3 +1,242 @@
-# Temporary Holding Version
+# @sigrun/ext-gateway
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The gateway engine for [sigrun](https://github.com/sigrun-ai/sigrun):
+chat-platform supervision, access-controlled inbound conversations,
+live responses, and durable outbound delivery. Platform adapters are
+separate extensions; this package owns their shared lifecycle and chat
+semantics.
+
+## Install and operation
+
+Sigrun includes the gateway as its fourth built-in extension, enabled by
+default. Install or enable channel adapters through sigrun's normal
+extension configuration, then configure the gateway in
+`<config-dir>/settings/gateway.json`.
+
+To disable only the engine, set this in sigrun's `settings.json` and
+restart. Contributed adapters then remain inert and do not receive chat
+traffic.
+
+```json
+{
+  "builtinExtensions": { "gateway": false }
+}
+```
+
+To disable one channel while leaving the engine and other channels
+running, set `"enabled": false` in its gateway channel block. A channel
+without a block is also disabled. Channel enablement is restart-required;
+other gateway settings are live reads.
+
+`GET /v1/ext/gateway/status` is the admin status surface. It reports
+adapter state, failures, retry/backoff state, and pending pairing
+requests (with sender ids hashed, never raw).
+
+## Configuration reference (spec §8.1)
+
+The top-level object has three keys:
+
+| Key | Meaning |
+| --- | --- |
+| `channels` | Map of adapter channel id to channel settings. |
+| `media` | `{ "maxBytes": number }`; per-attachment cap, default 16 MiB. |
+| `notify` | `{ "home": boolean }`; home-DM notifications, default `true`. |
+
+A channel block supports:
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Start this channel at boot. Changes require restart. |
+| `dm` | `"pairing"` | Unknown-DM policy: `"pairing"`, `"allowlist"`, or `"disabled"`. |
+| `selfLink` | `true` for pairing, otherwise `false` | Permit `/link` self-linking in DMs. |
+| `allow` | `[]` | Static sender mappings: `[{ "sender": "100000001", "user": "alice" }]`. These take precedence over paired/self-linked identities. |
+| `groups` | `[]` | Explicit group-chat policy rows; unlisted groups are ignored. |
+| `busy` | `"followUp"` | Input while a run is live: `"followUp"` or `"steer"`. |
+| `stream` | `true` | Stream live responses when the adapter supports editing. |
+| `allowBots` | `false` | Admit bot senders (the loop guard still applies). |
+
+Group rows have `chat` (platform chat id) and `owner` (sigrun user)
+required, plus:
+
+- `mention`: `"required"` (default) admits only messages that mention
+  or reply to the bot; `"always"` admits every otherwise-eligible
+  message without a mention.
+- `members`: `"linked"` (default) or `"anyone"`. The open `"anyone"`
+  mode requires a non-empty `tools` array; `extensions` optionally pins
+  the extension selection as well. Unknown senders still cannot use
+  control commands or answer interactions.
+- `tools` and `extensions`: optional arrays for the group's fixed agent
+  selection. The gateway prompt is included in open-group selections.
+
+A malformed channel block appears as `failed` in the status surface.
+A malformed group block drops only that group's messages and logs the
+reason; group failures do not appear in channel status. Neither disables
+siblings.
+
+Example (synthetic ids):
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "dm": "pairing",
+      "selfLink": true,
+      "groups": [
+        {
+          "chat": "-100000000002",
+          "owner": "alice",
+          "members": "linked",
+          "mention": "required"
+        }
+      ],
+      "busy": "followUp",
+      "stream": true,
+      "allowBots": false
+    }
+  },
+  "media": { "maxBytes": 16777216 },
+  "notify": { "home": true }
+}
+```
+
+## Pairing and self-linking
+
+With `dm: "pairing"`, an unknown DM sender gets a single-use pairing
+code. Their message is not submitted. An effective admin approves or
+denies it in any webui/TUI conversation:
+
+```text
+/pair
+/pair approve <code> <user>
+/pair deny <code>
+```
+
+Admins' home DMs also receive pairing notices, with approve/deny buttons
+where supported. Pairing requests expire after one hour, with at most
+one pending request per sender, three per channel, and a ten-minute
+request cooldown per sender. Deleting a user removes their links and
+home chats but does not reset an existing request cooldown.
+
+Self-linking requires no admin and is how the first operator can link:
+
+1. In webui/TUI, run `/link <channel>`.
+2. Send the returned `/link <code>` to the bot in a direct message on
+   that channel.
+3. The chat account is linked to the invoking sigrun user.
+
+Codes are single-use and expire after one hour. A code posted in a
+group is invalidated; redeem only in a DM. An existing link to another
+user is never silently re-pointed. Static `allow` mappings take
+precedence over stored links and are useful for a closed allowlist.
+Use `/home` in a DM to move a user's notification home chat there.
+
+## Chat commands and jobs
+
+Bound chats support `/new`, `/stop`, `/model`, `/thinking`, `/compact`,
+`/attach`, `/status`, `/home`, `/link`, `/pair`, and `/help`. Except for
+the identity commands, control requires write access to the bound
+conversation; `/attach` additionally requires write access to its target.
+Native command menus merge non-colliding extension commands.
+
+A prompt job with `conversation: "new"` can deliver its first settled
+answer to gateway targets using `deliver`:
+
+```json
+{
+  "name": "morning-note",
+  "schedule": { "cron": "0 9 * * *", "timezone": "UTC" },
+  "action": {
+    "kind": "prompt",
+    "prompt": "Write the morning note.",
+    "conversation": "new",
+    "deliver": ["loop", "telegram:-100000000002"]
+  }
+}
+```
+
+Use a channel id for a user's home DM or `<channel>:<chatId>` for an
+explicit chat (thread suffixes belong to the opaque platform chat id).
+An explicit target must be that home chat or a chat bound to a
+conversation the job owner can write. Delivery also re-checks access.
+Job answers are one-shot and durable: retries or later submissions do
+not duplicate the delivered answer. A job targeting an existing bound
+conversation uses that conversation's ordinary gateway fan-out instead.
+
+## Interactions in chat
+
+Pending interaction records render through the shared block-tree text
+projection. A single closed choice becomes buttons when they fit the
+channel's button limit, or a numbered list otherwise; a lone text or
+long-text field accepts a reply to its prompt. Other forms, including
+all forms containing secrets, point to the webui instead of collecting
+values over chat.
+
+Button taps, numbered replies, and reply-to text answers require a linked
+sender with current write access to the conversation. Numbered answers
+match only when exactly one choice interaction is pending in that chat.
+A prompt answered elsewhere is edited to show its outcome and loses its
+buttons; a later tap reports that outcome rather than answering again.
+Unbound conversations notify each write-access user's home DMs, while
+bound conversations prompt each bound chat once.
+
+Every gateway interaction read is a non-consuming `peekInteraction`:
+the gateway owns no secret delivery (secret records are webui-plan), so
+inspection can never eat the owning extension's one-shot raw-secret
+read. A secret interaction answered in the webui before the notifier's
+first pass is safe — the notifier peeks masked data and the owner still
+receives the secret exactly once.
+
+Home-DM settled notices are truthful about the outcome: an answered run
+reads `Reply ready`; a failed or aborted run reads `Run ended without a
+reply` with the settle reason, never reply-ready language.
+
+### Prompt retention
+
+Platform prompt messages are never deleted by the gateway. What the
+gateway retains locally is the correlation/edit metadata in
+`prompts.json`: message refs and answer plans expire seven days after
+the interaction settles, so a settlement edit (or a late delivery
+receipt's self-heal edit) is only possible inside that window. Compact
+settled tombstones — recipient identity, settlement time, and outcome
+text — persist permanently for replay suppression: a delayed receipt
+or replay after the row expired recreates nothing and can never make
+an answered prompt answerable again. Pending, unsettled prompts are
+never age-pruned. Refs/plans are therefore bounded by active prompts
+plus seven days of settled history; the small tombstone set grows with
+interaction history by design (the file as a whole is NOT bounded).
+Legacy unversioned state migrates on startup without losing refs or
+re-opening old prompts; a wholly malformed `prompts.json` fails loudly
+rather than silently resetting interaction state.
+
+## Delivery, state, and shutdown
+
+Responses stream through adapter edit support where available. Final
+outbound messages enter a durable ledger; transient sends retry with
+backoff, chat-gone errors disable the dead binding, and delivered
+entries prune after seven days. State files live under
+`<state-dir>/ext-gateway/gateway/` with atomic 0600 writes.
+
+On shutdown, intake closes and open album windows flush. The event bus
+finishes the last run-settle window, delivery workers drain for up to
+10 seconds, adapter stops are bounded at 5 seconds, and preview watches
+are released. Undelivered `pending` or `attempting` entries remain in
+the ledger for restart recovery; attempting entries are marked as
+recovered before resend.
+
+Restarting mid-operation is safe for durable delivery, with one explicit
+exception: SIGKILL inside the 1.5-second album window loses the merged
+submission by design. Its events were already deduplicated, so platform
+redelivery is a no-op; graceful shutdown flushes the album instead.
+
+## Development
+
+```sh
+npm install
+npm test            # vitest + manifest check
+npm run typecheck
+npm run build       # tsc -> dist/ (COMMIT the result)
+```
+
+Tests use `test/fake-host.ts` and synthetic users/channels only. Adapter
+authors should read sigrun's `docs/extending.md`; this README is the
+operator guide for the built-in engine.

package/dist/access/codes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pairing/link codes (spec §8.2): 8 characters drawn from a 32-character
+ * unambiguous alphabet (no I/O/0/1 — the Hermes/OpenClaw shared
+ * parameter set) via `crypto.randomInt`, plus the normalizer that folds
+ * user-typed input (whitespace, `-` separators, lowercase) onto the
+ * canonical form before any comparison. Codes are NEVER logged.
+ */
+/** The 32-character unambiguous code alphabet (no I, O, 0, 1). */
+export declare const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/** Draw one code: 8 uniform characters from {@link CODE_ALPHABET}. */
+export declare function newCode(): string;
+/**
+ * Fold user-typed input onto the canonical form: uppercase, then drop
+ * every character outside the alphabet (separators, whitespace, the
+ * ambiguous glyphs a paste may carry). An input that normalizes to the
+ * empty string simply never matches an issued code.
+ */
+export declare function normalizeCode(input: string): string;

package/dist/access/codes.js

@@ -0,0 +1,34 @@
+/**
+ * Pairing/link codes (spec §8.2): 8 characters drawn from a 32-character
+ * unambiguous alphabet (no I/O/0/1 — the Hermes/OpenClaw shared
+ * parameter set) via `crypto.randomInt`, plus the normalizer that folds
+ * user-typed input (whitespace, `-` separators, lowercase) onto the
+ * canonical form before any comparison. Codes are NEVER logged.
+ */
+import { randomInt } from "node:crypto";
+/** The 32-character unambiguous code alphabet (no I, O, 0, 1). */
+export const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/** The pinned code length (spec §8.2). */
+const CODE_LENGTH = 8;
+/** Draw one code: 8 uniform characters from {@link CODE_ALPHABET}. */
+export function newCode() {
+    let code = "";
+    for (let i = 0; i < CODE_LENGTH; i++) {
+        code += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+    }
+    return code;
+}
+/**
+ * Fold user-typed input onto the canonical form: uppercase, then drop
+ * every character outside the alphabet (separators, whitespace, the
+ * ambiguous glyphs a paste may carry). An input that normalizes to the
+ * empty string simply never matches an issued code.
+ */
+export function normalizeCode(input) {
+    let out = "";
+    for (const char of input.toUpperCase()) {
+        if (CODE_ALPHABET.includes(char))
+            out += char;
+    }
+    return out;
+}

package/dist/access/link-codes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Self-link codes (spec §8.2): the single-use, channel-bound codes the
+ * webui/TUI `/link <channel>` command issues and the chat-side
+ * `/link <code>` redeems. Proof by holding both sessions — the code is
+ * the only bridge.
+ *
+ * In memory by design: a restart voids outstanding codes (the user
+ * re-runs `/link <channel>`; the webui session outlives nothing). The
+ * pinned expiry matches pairing codes (3600000 ms).
+ */
+/** The outstanding self-link codes (one instance per engine). */
+export declare class LinkCodes {
+    private readonly live;
+    /** Issue a code binding `user` on `channel`. */
+    issue(user: string, channel: string, now: number): string;
+    /**
+     * Redeem `code` on `channel`: the bound user when live and unexpired,
+     * undefined otherwise. A SUCCESSFUL redeem consumes the code; a
+     * wrong-channel or expired attempt does not (a wrong-channel probe
+     * learns nothing).
+     */
+    redeem(code: string, channel: string, now: number): string | undefined;
+    /**
+     * Peek WITHOUT consuming: the bound user when live, unexpired, and
+     * bound to `channel` — the self-link conflict guard reads the
+     * binding before the single-use consume so a conflict reply leaves
+     * the code live (the user fixes the link, then sends it again).
+     */
+    peek(code: string, channel: string, now: number): string | undefined;
+    /** Void a code outright (the group-message leak path: the code was
+     *  seen by other members, so it can never redeem again). */
+    invalidate(code: string): void;
+}

package/dist/access/link-codes.js

@@ -0,0 +1,63 @@
+/**
+ * Self-link codes (spec §8.2): the single-use, channel-bound codes the
+ * webui/TUI `/link <channel>` command issues and the chat-side
+ * `/link <code>` redeems. Proof by holding both sessions — the code is
+ * the only bridge.
+ *
+ * In memory by design: a restart voids outstanding codes (the user
+ * re-runs `/link <channel>`; the webui session outlives nothing). The
+ * pinned expiry matches pairing codes (3600000 ms).
+ */
+import { newCode } from "./codes.js";
+/** The pinned expiry (ms) — the same window as pairing codes. */
+const LINK_TTL_MS = 3_600_000;
+/** The outstanding self-link codes (one instance per engine). */
+export class LinkCodes {
+    live = new Map();
+    /** Issue a code binding `user` on `channel`. */
+    issue(user, channel, now) {
+        const code = newCode();
+        this.live.set(code, { user, channel, issuedAt: now });
+        return code;
+    }
+    /**
+     * Redeem `code` on `channel`: the bound user when live and unexpired,
+     * undefined otherwise. A SUCCESSFUL redeem consumes the code; a
+     * wrong-channel or expired attempt does not (a wrong-channel probe
+     * learns nothing).
+     */
+    redeem(code, channel, now) {
+        const issued = this.live.get(code);
+        if (issued === undefined)
+            return undefined;
+        if (issued.channel !== channel)
+            return undefined;
+        if (now - issued.issuedAt >= LINK_TTL_MS) {
+            this.live.delete(code);
+            return undefined;
+        }
+        this.live.delete(code);
+        return issued.user;
+    }
+    /**
+     * Peek WITHOUT consuming: the bound user when live, unexpired, and
+     * bound to `channel` — the self-link conflict guard reads the
+     * binding before the single-use consume so a conflict reply leaves
+     * the code live (the user fixes the link, then sends it again).
+     */
+    peek(code, channel, now) {
+        const issued = this.live.get(code);
+        if (issued === undefined)
+            return undefined;
+        if (issued.channel !== channel)
+            return undefined;
+        if (now - issued.issuedAt >= LINK_TTL_MS)
+            return undefined;
+        return issued.user;
+    }
+    /** Void a code outright (the group-message leak path: the code was
+     *  seen by other members, so it can never redeem again). */
+    invalidate(code) {
+        this.live.delete(code);
+    }
+}

package/dist/access/loop-guard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The bot-loop guard (spec §8.2, from Hermes): an admitted bot may send
+ * at most 10 messages per chat per 60000 ms; once the cap trips, the
+ * chat enters a 300000 ms cooldown during which EVERY bot message on it
+ * drops. Human senders never pass through the guard.
+ */
+/** The loop guard, one instance per engine (per chat key). */
+export declare class LoopGuard {
+    private readonly chats;
+    /**
+     * May this bot message through? Records the admit on true; arms the
+     * cooldown on false (the refusal itself is the trip-wire — an
+     * attacker probing the cap re-arms the cooldown with every attempt
+     * inside it, which is exactly the behavior a loop needs stopped).
+     */
+    admit(chatKey: string, now: number): boolean;
+}

package/dist/access/loop-guard.js

@@ -0,0 +1,42 @@
+/**
+ * The bot-loop guard (spec §8.2, from Hermes): an admitted bot may send
+ * at most 10 messages per chat per 60000 ms; once the cap trips, the
+ * chat enters a 300000 ms cooldown during which EVERY bot message on it
+ * drops. Human senders never pass through the guard.
+ */
+/** The pinned window (ms). */
+const WINDOW_MS = 60_000;
+/** The pinned per-window cap. */
+const CAP = 10;
+/** The pinned cooldown (ms). */
+const COOLDOWN_MS = 300_000;
+/** The loop guard, one instance per engine (per chat key). */
+export class LoopGuard {
+    chats = new Map();
+    /**
+     * May this bot message through? Records the admit on true; arms the
+     * cooldown on false (the refusal itself is the trip-wire — an
+     * attacker probing the cap re-arms the cooldown with every attempt
+     * inside it, which is exactly the behavior a loop needs stopped).
+     */
+    admit(chatKey, now) {
+        const state = this.chats.get(chatKey) ?? { admits: [] };
+        if (state.cooldownUntil !== undefined && now < state.cooldownUntil) {
+            return false;
+        }
+        // A cooldown that lifted leaves no residue: the window restarts.
+        delete state.cooldownUntil;
+        const windowStart = now - WINDOW_MS;
+        const inWindow = state.admits.filter((at) => at > windowStart);
+        if (inWindow.length >= CAP) {
+            state.cooldownUntil = now + COOLDOWN_MS;
+            state.admits = inWindow;
+            this.chats.set(chatKey, state);
+            return false;
+        }
+        inWindow.push(now);
+        state.admits = inWindow;
+        this.chats.set(chatKey, state);
+        return true;
+    }
+}

package/dist/access/pairing.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The pairing store (spec §8.2): pending pairing requests persisted at
+ * `<stateDir>/gateway/pairing.json`.
+ *
+ * Pinned limits (the Hermes/OpenClaw shared parameters):
+ * - at most 1 pending request per sender (`limited: "sender"`);
+ * - at most 1 new request per sender per 600000 ms (`limited:
+ *   "cooldown"` — enforced even after the previous request left the
+ *   queue, so a spamming sender gets exactly one reply per window);
+ * - at most 3 pending per channel (`limited: "channel"` — a visible
+ *   DoS floor an admin clears through `/pair deny` and the status
+ *   route).
+ *
+ * Codes expire after 3600000 ms; expired entries are dropped on every
+ * read. Codes are never logged.
+ */
+import type { ChatRef } from "@sigrun/sigrun/extension";
+/** The pinned expiry (ms). */
+export declare const PAIRING_TTL_MS = 3600000;
+/** One pending pairing request. */
+export interface PairingRequest {
+    readonly code: string;
+    readonly channel: string;
+    readonly senderId: string;
+    readonly senderName?: string;
+    /** The requester's DM — the approval's "linked" reply routes here. */
+    readonly chat: ChatRef;
+    readonly createdAt: number;
+}
+/** The request outcome: the code, or which limit applied. */
+export type RequestResult = {
+    readonly code: string;
+} | {
+    readonly limited: "sender" | "cooldown" | "channel";
+};
+/**
+ * The pairing queue, one instance per engine. The public API is
+ * SYNCHRONOUS by interface (the pipeline's step 5 answers inline), so
+ * every mutation writes the file through JsonFile's SYNCHRONOUS
+ * update — a crash between the verdict and a deferred flush would
+ * silently lose a pending request (the operator's queue).
+ */
+export declare class PairingStore {
+    private readonly file;
+    private readonly now;
+    private mirror;
+    constructor(path: string, opts?: {
+        readonly now?: () => number;
+    });
+    /**
+     * Create (or refuse) a pairing request. The caller hands `now` so the
+     * pipeline can pin a clock in tests; the store's own clock seeds the
+     * cooldown record.
+     */
+    request(channel: string, sender: {
+        id: string;
+        name?: string;
+    }, chat: ChatRef, now: number): RequestResult;
+    /** The live pending rows, optionally filtered to one channel. */
+    pending(channel?: string): readonly PairingRequest[];
+    /** Approve by code: the request leaves the queue and returns. */
+    approve(code: string, now?: number): PairingRequest | undefined;
+    /** Deny by code: true when a live request was removed. */
+    deny(code: string): boolean;
+    /** The expired-row sweep: expired requests count against no limit. */
+    private livePending;
+    /**
+     * Persist the mirror: the SYNCHRONOUS atomic write (see the class
+     * doc). A failed persist is loud, never swallowed — the verdict
+     * already returned to the pipeline, but the operator must see the
+     * file diverged (the JsonFile throw names the path).
+     */
+    private persist;
+}