@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/session/chat/chat-ingestion-session.d.ts

@@ -0,0 +1,285 @@
+import type pino from "pino";
+import type { SessionInboundMessage, SessionOutboundMessage } from "../../messages.js";
+import { type CohortRecorder } from "../../ingestion/apply.js";
+import { type CohortStore } from "../../ingestion/cohort-store.js";
+import type { FilterStore } from "../../ingestion/filters/store.js";
+import type { IngestionLedger } from "../../ingestion/ledger.js";
+import type { SourceStore } from "../../ingestion/sources/store.js";
+import type { SourceGateway, SourceKind } from "../../ingestion/types.js";
+import type { CapLimiterAdmit } from "../../ingestion/cap-limiter.js";
+import type { DryRunDispatcher } from "../../ingestion/dry-run.js";
+import type { ReconciliationPort } from "../../ingestion/reconcile/runner.js";
+import type { StoredSchedule } from "@hyperdrive.bot/fleet-protocol/schedule/types";
+/**
+ * The one method the runs handler needs from `ScheduleService`.
+ *
+ * A narrow port, for the same reason `dispatcher` is one: the class already
+ * holds a one-method dispatch port so nothing here can arm, edit or trigger a
+ * schedule, and handing it the whole service to answer a READ would give that
+ * argument away for a `list()`.
+ */
+export interface ScheduleLister {
+    list(): Promise<StoredSchedule[]>;
+}
+/** What an ingestion handler needs from the Session shell: somewhere to emit. */
+export interface ChatIngestionSessionHost {
+    emit(msg: SessionOutboundMessage): void;
+}
+export interface ChatIngestionSessionOptions {
+    host: ChatIngestionSessionHost;
+    filterStore: FilterStore;
+    sourceStore: SourceStore;
+    gatewayResolver: (kind: SourceKind) => SourceGateway;
+    /**
+     * Nullable: a daemon whose sqlite could not be opened still answers a
+     * backfill, it just cannot say what was already handled. Failing the whole
+     * preview over a missing dedupe memory would hide the history as well as the
+     * marks.
+     */
+    ledger: IngestionLedger | null;
+    /**
+     * The daemon's ONE `CapLimiter`, reached through
+     * `ScheduleService.getCapLimiter()` at the wiring site rather than constructed
+     * here. Null when the ledger is: a limiter with nowhere durable to count
+     * cannot bound outward artifacts, so the apply verb refuses rather than
+     * dispatching against an in-memory number that a restart would hand back.
+     */
+    limiter: CapLimiterAdmit | null;
+    /** `ScheduleService`, structurally. The ONE new-agent minting path in the daemon. */
+    dispatcher: DryRunDispatcher;
+    cohorts: CohortRecorder;
+    /**
+     * Where `ingestion/cohort/inspect` and `ingestion/cohort/cancel` read and write.
+     *
+     * Nullable, and null is a REAL state rather than a defect: a daemon whose
+     * sqlite could not be opened has no cohorts to inspect, and the two handlers
+     * say so in their response instead of the class refusing to construct. It is
+     * the same object `cohorts` writes through, never a second store.
+     */
+    cohortStore: CohortStore | null;
+    /**
+     * Where `ingestion/runs` looks up which schedule belongs to a filter.
+     *
+     * `ScheduleService` satisfies this structurally. Read-only by shape: `list()`
+     * is the only member, so this handler cannot write a schedule document even
+     * by accident - which is the mechanical half of epic D1 ("no schedule
+     * document on disk ever contains verifiedAt").
+     */
+    schedules: ScheduleLister;
+    /**
+     * The background re-read fired AFTER `ingestion/runs` has already answered.
+     *
+     * Nullable, and null is an ordinary state rather than a defect: a daemon with
+     * no ledger has nothing to reconcile against, and one whose operator turned
+     * the feature off should not even construct the service. When it is null the
+     * handler answers from stored verdicts and issues zero source reads, which is
+     * exactly what it did before this story.
+     */
+    reconciliation: ReconciliationPort | null;
+    clientId: string;
+    logger: pino.Logger;
+}
+type IngestionRequest = Extract<SessionInboundMessage, {
+    type: "ingestion/backfill";
+}>;
+type IngestionApplyRequest = Extract<SessionInboundMessage, {
+    type: "ingestion/apply";
+}>;
+type CohortInspectRequest = Extract<SessionInboundMessage, {
+    type: "ingestion/cohort/inspect";
+}>;
+type CohortCancelRequest = Extract<SessionInboundMessage, {
+    type: "ingestion/cohort/cancel";
+}>;
+type IngestionRunsRequest = Extract<SessionInboundMessage, {
+    type: "ingestion/runs";
+}>;
+/**
+ * A client's ingestion PREVIEW and APPLY surface.
+ *
+ * Story 5.1 built this as a preview-only class whose safety argument was an
+ * absent collaborator: with no `ScheduleService` in scope, no handler here could
+ * mint a session by accident. Story 5.3 adds the apply verb, which mints
+ * sessions on purpose, so that argument no longer covers the class as a whole
+ * and is replaced by two narrower ones that still hold:
+ *
+ *   - `dispatcher` is the `DryRunDispatcher` PORT, one method wide
+ *     (`runUnattendedSession`), not the whole service. `create`, `runOnce`,
+ *     `pause` and `tick` are not on the object this class holds, so nothing here
+ *     can arm, edit or trigger a schedule. Minting one unattended session for a
+ *     selection the user just confirmed is the verb; changing a filter's cadence
+ *     is not, and is unreachable.
+ *   - `runBackfill` still gets the one-method ledger port rather than the ledger,
+ *     so the PREVIEW path remains structurally unable to write a row even though
+ *     the apply path, one method over, must.
+ *
+ * The confirmation gate that bounds the apply is not in this class either: it is
+ * in `applySelection`, on the server side of the wire, so a second caller (a
+ * CLI, a script, an MCP tool) gets the same gate without re-implementing it.
+ */
+export declare class ChatIngestionSession {
+    private readonly host;
+    private readonly filterStore;
+    private readonly sourceStore;
+    private readonly gatewayResolver;
+    private readonly ledger;
+    private readonly limiter;
+    private readonly dispatcher;
+    private readonly cohorts;
+    private readonly cohortStore;
+    private readonly schedules;
+    private readonly reconciliation;
+    private readonly clientId;
+    private readonly logger;
+    constructor(options: ChatIngestionSessionOptions);
+    /**
+     * A failed backfill is reported IN THE RESPONSE, not as an `rpc_error`.
+     *
+     * The screen has two distinct states - "the window held nothing" and "the
+     * read failed" - and it can only tell them apart if a failure arrives on the
+     * same channel as a success, carrying `result: null` beside a non-null
+     * `error`. An out-of-band rpc_error would leave the correlated request
+     * resolving to nothing, which the screen would render as an empty window.
+     */
+    private emitIngestionRpcError;
+    /**
+     * Adapt `IngestionLedger` to the one-method reader `runBackfill` accepts.
+     *
+     * Three mismatches are absorbed here rather than by widening either side:
+     * the ledger's `get` is synchronous, is keyed by `(filterId, itemKey)`, and
+     * names the mark `handledAt`.
+     *
+     * A row whose `content_hash` was never written reports as "no comparable
+     * mark" (null) rather than as a row with an empty hash. Both produce
+     * `handled: false`, but only one of them says so honestly instead of
+     * inventing a sentinel hash that happens never to collide.
+     */
+    private ledgerReaderFor;
+    /**
+     * Preview what a filter would have matched over a window of its source's
+     * history.
+     *
+     * Reads only. Nothing on this path writes a ledger row, mints a session or
+     * resolves an MCP target, and `backfill.no-side-effects.test.ts` asserts that
+     * against the real table rather than by reading this comment.
+     */
+    handleIngestionBackfillRequest(request: IngestionRequest): Promise<void>;
+    /**
+     * Turn item keys back into payload-bearing items.
+     *
+     * The work lives in `resolve-items.ts` so the RESUME path (Story 5.4) reaches
+     * the same resolution rather than a second one that could quietly disagree
+     * about which items a group covers.
+     */
+    private resolveMatchedItems;
+    /**
+     * Dispatch a confirmed selection, or tell the client what it would dispatch.
+     *
+     * Mirrors `handleScheduleCreateRequest` (`chat-schedule-loop-session.ts:304`)
+     * in shape: try, emit, and on a throw emit a response carrying the error
+     * rather than an out-of-band `rpc_error`. The reason is the same one the
+     * backfill handler documents - a correlated request that resolves to nothing
+     * is indistinguishable, on screen, from a successful call that did nothing.
+     *
+     * Every number in the response is computed HERE. `confirmedGroups` off the
+     * request is used only as something to disagree with.
+     */
+    handleIngestionApplyRequest(request: IngestionApplyRequest): Promise<void>;
+    /**
+     * Read one cohort back: counters, derived counts, and whether it is finished.
+     *
+     * `cohort: null` with `error: null` means THIS COHORT DOES NOT EXIST.
+     * `cohort: null` with a non-null `error` means the read failed. The row must
+     * be able to tell those apart, so they are never collapsed into one empty
+     * answer - "empty output is not evidence of absence" is a wire-shape rule
+     * here, not just a habit.
+     */
+    handleIngestionCohortInspectRequest(request: CohortInspectRequest): Promise<void>;
+    /**
+     * Cancel what has not started, and report how many sessions were left running.
+     *
+     * The set this touches is decided by row status on this side of the wire; the
+     * request carries no list of groups and no force flag, so a client structurally
+     * cannot ask for a live session to be interrupted.
+     *
+     * `stillRunning` travels back with the cohort because a cancel that stopped 3
+     * of 5 groups must not read like a cancel that stopped everything.
+     */
+    handleIngestionCohortCancelRequest(request: CohortCancelRequest): Promise<void>;
+    /**
+     * One filter's ingestion runs, from the LEDGER, with the closed ones dropped.
+     *
+     * Follows `handleScheduleLogsRequest` (`chat-schedule-loop-session.ts:370`)
+     * verbatim in shape: try, emit with `error: null`, catch, emit the error on
+     * the same channel.
+     *
+     * THE ORDER OF THE LAST TWO STATEMENTS IS THE WHOLE OF AC 15, so it is spelled
+     * out rather than left to be inferred:
+     *
+     *   1. read the schedule's runs and join them to the ledger    (disk only)
+     *   2. project into `IngestionRunView`                          (pure)
+     *   3. drop the views whose verdict maps to `inInbox === false` (pure)
+     *   4. EMIT
+     *   5. only THEN kick off `verifyIfStale`, without awaiting it
+     *
+     * Step 5's `void` is LOAD-BEARING. Awaiting it would put up to six MCP round-
+     * trips - a 10s Gmail timeout among them - in front of the Inbox's first
+     * paint, on every render, for a result the very next poll would have picked
+     * up anyway. The app already re-queries every five seconds
+     * (`use-schedules.ts`, `staleTime: 5_000` + `keepPreviousData`), so the
+     * verdict this call writes lands on screen within seconds, with no flicker and
+     * no push channel (decision D-6.2-D).
+     *
+     * Step 3 happens HERE, at the daemon, and not in the app. Closure is not a
+     * rendering decision: a client that forgot the filter would show a row for
+     * work that is already done, and the whole epic is about not doing that.
+     */
+    handleIngestionRunsRequest(request: IngestionRunsRequest): Promise<void>;
+    /**
+     * Fire the background re-read, and never let it reach the caller.
+     *
+     * Every failure mode is swallowed at ERROR rather than propagated, because
+     * this call is downstream of a response that has already been emitted: a
+     * rejection here would surface as an unhandled rejection on the daemon's event
+     * loop, having already told the client everything was fine.
+     *
+     * A filter that resolves to no source, or a daemon with no reconciliation
+     * wiring, does nothing at all. Reconciliation is an enhancement to a read that
+     * already worked.
+     */
+    private scheduleReconciliation;
+    /**
+     * Resolve a filter to its schedule, then join that schedule's runs to the
+     * ledger rows.
+     *
+     * A LINEAR SCAN over `list()`, and deliberately so (decision D-6.1-I):
+     * schedules are one small JSON file each in a low-cardinality directory that
+     * the service has already loaded, so an index would be a second thing to keep
+     * correct for a list that fits in a screenful.
+     *
+     * No match resolves to `[]`, never a throw. A filter that has not been armed
+     * yet has no source schedule, and that is a state the Inbox asks about
+     * routinely rather than an error.
+     *
+     * A ledger that could not open resolves to `[]` too, on the same reasoning as
+     * everywhere else in this class: a missing dedupe memory must not blank the
+     * Inbox, and `[]` with `error: null` is the honest empty.
+     *
+     * The cadence is narrowed with `"filterId" in cadence` rather than by
+     * asserting the member exists, so this compiles against any shape of
+     * `ScheduleCadenceSchema` - including one without the `source` member.
+     */
+    private readRunViews;
+    /**
+     * The inspect path's own error emitter.
+     *
+     * Not `emitIngestionRpcError`: that one emits an `ingestion/backfill/response`,
+     * because it was written for the backfill request type. Answering a cohort
+     * inspect on the backfill channel would leave the correlated request hanging
+     * forever - the exact "resolves to nothing" failure this file's other comments
+     * exist to prevent - so each ingestion RPC pair reports on its own channel.
+     */
+    private emitCohortInspectError;
+}
+export {};
+//# sourceMappingURL=chat-ingestion-session.d.ts.map