@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/ingestion/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Errors raised by the ingestion module.
+ *
+ * Every code carries a fixed HTTP status, and the split is deliberate:
+ *
+ *   code                  | httpStatus | meaning
+ *   ----------------------|------------|------------------------------------------
+ *   PIPEDREAM_OFF         | 422        | this server has no Pipedream credentials
+ *   COMPOSIO_OFF          | 422        | this server has no Composio credentials
+ *   COMPOSIO_NEEDS_SETUP  | 422        | the app needs setup Composio cannot manage
+ *   PIPEDREAM_OFFLINE     | 502        | Pipedream unreachable
+ *   PIPEDREAM_AUTH        | 502        | Pipedream rejected our platform credential
+ *   COMPOSIO_OFFLINE      | 502        | Composio unreachable
+ *   COMPOSIO_AUTH         | 502        | Composio rejected our platform credential
+ *   COMPOSIO_ERROR        | 502        | Composio answered non-ok for any other reason
+ *   SOURCE_GONE           | 502        | a resource we cached was deleted upstream
+ *   SOURCE_ERROR          | 502        | any other non-ok aggregator response
+ *   FILTER_MISSING        | 404        | no such filter on THIS daemon
+ *   SOURCE_MISSING        | 404        | no such source on THIS daemon
+ *
+ * The 422 group means "this server is not set up for that", which is a
+ * configuration fact the caller can be told plainly. The 502 group means the
+ * upstream aggregator failed us. The 404 group means the LOCAL record the
+ * caller named does not exist, which is neither of those: reporting a deleted
+ * filter as SOURCE_GONE/502 would send the next reader to check an aggregator
+ * that is working perfectly. Two codes rather than one because the code is what
+ * reaches a client, and "which of the two is missing" is the first thing the
+ * user needs in order to fix it.
+ *
+ * COMPOSIO_ERROR is deliberately distinct from COMPOSIO_OFFLINE. Without it a
+ * Composio 500 would have to be reported as "offline", which is a false
+ * diagnosis in a user-facing string: the next reader debugs their network
+ * instead of Composio. One extra code buys that distinction.
+ *
+ * `*_AUTH` is 502 rather than 401 on purpose: the credential that was rejected
+ * is the SERVER's platform credential, not the caller's. Returning 401 would
+ * tell the caller to re-authenticate, which cannot fix anything, and would
+ * blame the wrong party for an operator's misconfiguration.
+ */
+export declare const INGESTION_ERROR_CODES: readonly ["PIPEDREAM_OFF", "COMPOSIO_OFF", "COMPOSIO_NEEDS_SETUP", "PIPEDREAM_OFFLINE", "PIPEDREAM_AUTH", "COMPOSIO_OFFLINE", "COMPOSIO_AUTH", "COMPOSIO_ERROR", "SOURCE_GONE", "SOURCE_ERROR", "FILTER_MISSING", "SOURCE_MISSING"];
+export type IngestionErrorCode = (typeof INGESTION_ERROR_CODES)[number];
+/** A domain error from the ingestion seam, with a message ready for a client. */
+export declare class IngestionError extends Error {
+    readonly code: IngestionErrorCode;
+    readonly httpStatus: number;
+    constructor(code: IngestionErrorCode, message: string, httpStatus: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/server/server/ingestion/errors.js

@@ -0,0 +1,63 @@
+/**
+ * Errors raised by the ingestion module.
+ *
+ * Every code carries a fixed HTTP status, and the split is deliberate:
+ *
+ *   code                  | httpStatus | meaning
+ *   ----------------------|------------|------------------------------------------
+ *   PIPEDREAM_OFF         | 422        | this server has no Pipedream credentials
+ *   COMPOSIO_OFF          | 422        | this server has no Composio credentials
+ *   COMPOSIO_NEEDS_SETUP  | 422        | the app needs setup Composio cannot manage
+ *   PIPEDREAM_OFFLINE     | 502        | Pipedream unreachable
+ *   PIPEDREAM_AUTH        | 502        | Pipedream rejected our platform credential
+ *   COMPOSIO_OFFLINE      | 502        | Composio unreachable
+ *   COMPOSIO_AUTH         | 502        | Composio rejected our platform credential
+ *   COMPOSIO_ERROR        | 502        | Composio answered non-ok for any other reason
+ *   SOURCE_GONE           | 502        | a resource we cached was deleted upstream
+ *   SOURCE_ERROR          | 502        | any other non-ok aggregator response
+ *   FILTER_MISSING        | 404        | no such filter on THIS daemon
+ *   SOURCE_MISSING        | 404        | no such source on THIS daemon
+ *
+ * The 422 group means "this server is not set up for that", which is a
+ * configuration fact the caller can be told plainly. The 502 group means the
+ * upstream aggregator failed us. The 404 group means the LOCAL record the
+ * caller named does not exist, which is neither of those: reporting a deleted
+ * filter as SOURCE_GONE/502 would send the next reader to check an aggregator
+ * that is working perfectly. Two codes rather than one because the code is what
+ * reaches a client, and "which of the two is missing" is the first thing the
+ * user needs in order to fix it.
+ *
+ * COMPOSIO_ERROR is deliberately distinct from COMPOSIO_OFFLINE. Without it a
+ * Composio 500 would have to be reported as "offline", which is a false
+ * diagnosis in a user-facing string: the next reader debugs their network
+ * instead of Composio. One extra code buys that distinction.
+ *
+ * `*_AUTH` is 502 rather than 401 on purpose: the credential that was rejected
+ * is the SERVER's platform credential, not the caller's. Returning 401 would
+ * tell the caller to re-authenticate, which cannot fix anything, and would
+ * blame the wrong party for an operator's misconfiguration.
+ */
+export const INGESTION_ERROR_CODES = [
+    "PIPEDREAM_OFF",
+    "COMPOSIO_OFF",
+    "COMPOSIO_NEEDS_SETUP",
+    "PIPEDREAM_OFFLINE",
+    "PIPEDREAM_AUTH",
+    "COMPOSIO_OFFLINE",
+    "COMPOSIO_AUTH",
+    "COMPOSIO_ERROR",
+    "SOURCE_GONE",
+    "SOURCE_ERROR",
+    "FILTER_MISSING",
+    "SOURCE_MISSING",
+];
+/** A domain error from the ingestion seam, with a message ready for a client. */
+export class IngestionError extends Error {
+    constructor(code, message, httpStatus) {
+        super(message);
+        this.name = "IngestionError";
+        this.code = code;
+        this.httpStatus = httpStatus;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/server/server/ingestion/external-user-id.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The external-user id handed to an aggregator, identifying this daemon (and
+ * optionally one workspace inside it) as a tenant.
+ *
+ * ONE place only, on purpose. Isolation at the aggregator lives entirely in
+ * this string, because the platform key is shared across every source paseo
+ * connects. An id assembled by hand anywhere else, in a route or a service or
+ * a test helper, is the breach: it either collides with another host's
+ * namespace or escapes the one this daemon owns. A guard test enforces the
+ * rule mechanically by asserting no other file under `ingestion/` contains the
+ * `srv_` prefix.
+ *
+ * Mirrors `aggregatorExternalUserId` at
+ * `packages/entities/clients/integrahr-app/src/modules/connectors/targets.ts:29`,
+ * with one intentional divergence: paseo's axis is host plus workspace rather
+ * than tenant, and the daemon id is **hashed, not passed through**. The value
+ * `getOrCreateServerId` produces is a local identity persisted under
+ * `$PASEO_HOME/server-id`; it is never handed to a third party verbatim, so
+ * only its digest crosses the boundary.
+ *
+ * Pure and deterministic: no filesystem, no network, no `process.env`.
+ */
+export declare function sourceExternalUserId(serverId: string, workspaceId?: string): string;
+//# sourceMappingURL=external-user-id.d.ts.map

package/dist/server/server/ingestion/external-user-id.js

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+function sha256Hex16(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex").slice(0, 16);
+}
+/**
+ * The external-user id handed to an aggregator, identifying this daemon (and
+ * optionally one workspace inside it) as a tenant.
+ *
+ * ONE place only, on purpose. Isolation at the aggregator lives entirely in
+ * this string, because the platform key is shared across every source paseo
+ * connects. An id assembled by hand anywhere else, in a route or a service or
+ * a test helper, is the breach: it either collides with another host's
+ * namespace or escapes the one this daemon owns. A guard test enforces the
+ * rule mechanically by asserting no other file under `ingestion/` contains the
+ * `srv_` prefix.
+ *
+ * Mirrors `aggregatorExternalUserId` at
+ * `packages/entities/clients/integrahr-app/src/modules/connectors/targets.ts:29`,
+ * with one intentional divergence: paseo's axis is host plus workspace rather
+ * than tenant, and the daemon id is **hashed, not passed through**. The value
+ * `getOrCreateServerId` produces is a local identity persisted under
+ * `$PASEO_HOME/server-id`; it is never handed to a third party verbatim, so
+ * only its digest crosses the boundary.
+ *
+ * Pure and deterministic: no filesystem, no network, no `process.env`.
+ */
+export function sourceExternalUserId(serverId, workspaceId) {
+    const base = `srv_${sha256Hex16(serverId)}`;
+    const workspace = workspaceId?.trim();
+    if (!workspace) {
+        return base;
+    }
+    return `${base}__ws_${sha256Hex16(workspace)}`;
+}
+//# sourceMappingURL=external-user-id.js.map

package/dist/server/server/ingestion/filters/store.d.ts

@@ -0,0 +1,28 @@
+import { type StoredFilter } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+/**
+ * The one place the directory name is written. Story 2.3 wires the store with
+ * `filtersDir(options.paseoHome)` rather than repeating a magic string next to the
+ * `join(options.paseoHome, "schedules")` that constructs `ScheduleStore`.
+ */
+export declare const FILTERS_DIR_NAME = "filters";
+export declare function filtersDir(paseoHome: string): string;
+export declare class FilterStore {
+    private readonly dir;
+    constructor(dir: string);
+    private filePath;
+    private ensureDir;
+    list(): Promise<StoredFilter[]>;
+    get(id: string): Promise<StoredFilter | null>;
+    /** Returns the parsed document, so the value the caller holds and the bytes on disk agree. */
+    create(filter: Omit<StoredFilter, "id">): Promise<StoredFilter>;
+    /**
+     * Parses before writing, unlike `ScheduleStore`, which parses on read only.
+     * Filter documents cross an RPC boundary in Epic 5, and a rail-shaped field
+     * (`send`, `merge`, `deploy`, `delete`, `allowIrreversible`) must be stripped before it
+     * reaches disk, not on the way back out - an untyped caller must not be able to land one
+     * in the file at all.
+     */
+    put(filter: StoredFilter): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/server/server/ingestion/filters/store.js

@@ -0,0 +1,74 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { StoredFilterSchema, } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+import { writeJsonFileAtomic } from "../../atomic-file.js";
+/**
+ * The one place the directory name is written. Story 2.3 wires the store with
+ * `filtersDir(options.paseoHome)` rather than repeating a magic string next to the
+ * `join(options.paseoHome, "schedules")` that constructs `ScheduleStore`.
+ */
+export const FILTERS_DIR_NAME = "filters";
+export function filtersDir(paseoHome) {
+    return join(paseoHome, FILTERS_DIR_NAME);
+}
+function generateFilterId() {
+    return randomBytes(4).toString("hex");
+}
+export class FilterStore {
+    constructor(dir) {
+        this.dir = dir;
+    }
+    filePath(id) {
+        return join(this.dir, `${id}.json`);
+    }
+    async ensureDir() {
+        await mkdir(this.dir, { recursive: true });
+    }
+    async list() {
+        await this.ensureDir();
+        const entries = await readdir(this.dir, { withFileTypes: true });
+        const filters = await Promise.all(entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map(async (entry) => {
+            const content = await readFile(join(this.dir, entry.name), "utf-8");
+            return StoredFilterSchema.parse(JSON.parse(content));
+        }));
+        return filters.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    }
+    async get(id) {
+        await this.ensureDir();
+        try {
+            const content = await readFile(this.filePath(id), "utf-8");
+            return StoredFilterSchema.parse(JSON.parse(content));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /** Returns the parsed document, so the value the caller holds and the bytes on disk agree. */
+    async create(filter) {
+        const created = StoredFilterSchema.parse({ ...filter, id: generateFilterId() });
+        await this.put(created);
+        return created;
+    }
+    /**
+     * Parses before writing, unlike `ScheduleStore`, which parses on read only.
+     * Filter documents cross an RPC boundary in Epic 5, and a rail-shaped field
+     * (`send`, `merge`, `deploy`, `delete`, `allowIrreversible`) must be stripped before it
+     * reaches disk, not on the way back out - an untyped caller must not be able to land one
+     * in the file at all.
+     */
+    async put(filter) {
+        await this.ensureDir();
+        await writeJsonFileAtomic(this.filePath(filter.id), StoredFilterSchema.parse(filter));
+    }
+    async delete(id) {
+        await this.ensureDir();
+        await rm(this.filePath(id), { force: true });
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/server/server/ingestion/fingerprint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Join the non-nullish parts with `|` and return the first 12 hex chars of the
+ * sha1 digest.
+ *
+ * `null` / `undefined` parts are DROPPED, not stringified, so
+ * `fingerprint("a", null, "b")` equals `fingerprint("a", "b")`.
+ *
+ * Because the separator is not escaped, `fingerprint("a|b")` collides with
+ * `fingerprint("a", "b")`. That is the ported behaviour and is left as-is:
+ * callers pass structured id parts (source, thread, date), not user prose.
+ */
+export declare function fingerprint(...parts: (string | null | undefined)[]): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/server/server/ingestion/fingerprint.js

@@ -0,0 +1,31 @@
+// Stable item keys for the ingestion ledger.
+//
+// This is a VERBATIM port of `fingerprint()` in
+// `~/super-repo/tooling/loops/lib/ledger.mjs:15`, and it must stay byte-
+// identical to it: the loops tooling and the daemon address the same items, so
+// a divergence here silently splits one item into two ledger rows and
+// re-dispatches work that was already handled.
+//
+// sha1-truncated-to-12 is retained deliberately (epic decision D3). It is not a
+// security primitive - it never guards a trust boundary, it only names an item
+// - so the usual "upgrade sha1 to sha256" reflex would buy nothing and would
+// invalidate every existing ledger row.
+import { createHash } from "node:crypto";
+/**
+ * Join the non-nullish parts with `|` and return the first 12 hex chars of the
+ * sha1 digest.
+ *
+ * `null` / `undefined` parts are DROPPED, not stringified, so
+ * `fingerprint("a", null, "b")` equals `fingerprint("a", "b")`.
+ *
+ * Because the separator is not escaped, `fingerprint("a|b")` collides with
+ * `fingerprint("a", "b")`. That is the ported behaviour and is left as-is:
+ * callers pass structured id parts (source, thread, date), not user prose.
+ */
+export function fingerprint(...parts) {
+    return createHash("sha1")
+        .update(parts.filter((p) => p != null).join("|"))
+        .digest("hex")
+        .slice(0, 12);
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/server/server/ingestion/grouping.d.ts

@@ -0,0 +1,26 @@
+import type { MatchedItem, MatchedItemGroup } from "./types.js";
+/**
+ * Collapse matched items into the groups that will each mint one session.
+ *
+ * The result is total and stable under input shuffle: groups ascend by resolved key,
+ * ties break on the group's earliest `observedAt`, and items inside a group ascend by
+ * `observedAt` then by `key`. All string order is byte-wise.
+ *
+ * The key tie-break is defensive rather than reachable (bucketing on a `Map` makes a
+ * resolved key unique by construction), but it keeps the comparator total, so the sort
+ * never falls through to the engine's own stability guarantees.
+ */
+export declare function groupMatchedItems(items: MatchedItem[], groupKey: string | null): MatchedItemGroup[];
+/**
+ * How many items are selected, and how many sessions that collapses to.
+ *
+ * Delegates to `groupMatchedItems` rather than re-deriving the count with a `Set`, so
+ * the number a caller is shown before a batch runs is produced by the same code path
+ * that decides what actually dispatches. Two implementations could disagree; one
+ * cannot.
+ */
+export declare function collapseCount(items: MatchedItem[], groupKey: string | null): {
+    selected: number;
+    groups: number;
+};
+//# sourceMappingURL=grouping.d.ts.map

package/dist/server/server/ingestion/grouping.js

@@ -0,0 +1,116 @@
+/**
+ * Byte-wise string order, and the only string comparison this module performs.
+ *
+ * The locale-aware comparison on `String.prototype` is banned here because it reads
+ * the host's ICU data: two machines with different ICU builds would order the same
+ * groups differently. That would turn the ordering test into a flake and, worse,
+ * make "which group runs next" host-dependent.
+ */
+function compareStrings(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Read a dot path against a payload, walking OWN properties only.
+ *
+ * The path is a runtime string out of a user-authored filter document, so every hop
+ * is gated on `Object.prototype.hasOwnProperty`: `__proto__.x`, `constructor.name`
+ * and `prototype.y` resolve to `undefined` rather than to something off the
+ * prototype chain. Any hop that is not a non-null object ends the walk.
+ */
+function readOwnPath(payload, path) {
+    let cursor = payload;
+    for (const segment of path.split(".")) {
+        if (typeof cursor !== "object" || cursor === null) {
+            return undefined;
+        }
+        if (!Object.prototype.hasOwnProperty.call(cursor, segment)) {
+            return undefined;
+        }
+        // Reflect.get, not an index expression: the `typeof`/`null` guards above narrow
+        // `unknown` to `object`, which Reflect.get accepts without a cast.
+        cursor = Reflect.get(cursor, segment);
+    }
+    return cursor;
+}
+/**
+ * The group an item belongs to.
+ *
+ * A `null` group key means the filter declares no grouping, so every item is its own
+ * group. Otherwise the resolved value is coerced narrowly: a non-blank string
+ * verbatim, a finite number or a boolean via `String`, and everything else falls
+ * back to `item.key`.
+ *
+ * That fallback is the important part: an item whose path does not resolve becomes a
+ * singleton group and still gets dispatched. Dropping it instead would make an
+ * ingestion miss invisible, which is the one failure mode grouping must not create.
+ */
+function resolveGroupKey(item, groupKey) {
+    if (groupKey === null) {
+        return item.key;
+    }
+    const resolved = readOwnPath(item.payload, groupKey);
+    if (typeof resolved === "string") {
+        return resolved.trim().length > 0 ? resolved : item.key;
+    }
+    if (typeof resolved === "number") {
+        return Number.isFinite(resolved) ? String(resolved) : item.key;
+    }
+    if (typeof resolved === "boolean") {
+        return String(resolved);
+    }
+    return item.key;
+}
+function compareItems(a, b) {
+    const byObservedAt = compareStrings(a.observedAt, b.observedAt);
+    return byObservedAt !== 0 ? byObservedAt : compareStrings(a.key, b.key);
+}
+/**
+ * Collapse matched items into the groups that will each mint one session.
+ *
+ * The result is total and stable under input shuffle: groups ascend by resolved key,
+ * ties break on the group's earliest `observedAt`, and items inside a group ascend by
+ * `observedAt` then by `key`. All string order is byte-wise.
+ *
+ * The key tie-break is defensive rather than reachable (bucketing on a `Map` makes a
+ * resolved key unique by construction), but it keeps the comparator total, so the sort
+ * never falls through to the engine's own stability guarantees.
+ */
+export function groupMatchedItems(items, groupKey) {
+    const buckets = new Map();
+    for (const item of items) {
+        const key = resolveGroupKey(item, groupKey);
+        const bucket = buckets.get(key);
+        if (bucket === undefined) {
+            buckets.set(key, { key, items: [item], earliestObservedAt: item.observedAt });
+            continue;
+        }
+        bucket.items.push(item);
+        if (compareStrings(item.observedAt, bucket.earliestObservedAt) < 0) {
+            bucket.earliestObservedAt = item.observedAt;
+        }
+    }
+    return [...buckets.values()]
+        .sort((a, b) => {
+        const byKey = compareStrings(a.key, b.key);
+        return byKey !== 0 ? byKey : compareStrings(a.earliestObservedAt, b.earliestObservedAt);
+    })
+        .map((bucket) => ({ key: bucket.key, items: [...bucket.items].sort(compareItems) }));
+}
+/**
+ * How many items are selected, and how many sessions that collapses to.
+ *
+ * Delegates to `groupMatchedItems` rather than re-deriving the count with a `Set`, so
+ * the number a caller is shown before a batch runs is produced by the same code path
+ * that decides what actually dispatches. Two implementations could disagree; one
+ * cannot.
+ */
+export function collapseCount(items, groupKey) {
+    return { selected: items.length, groups: groupMatchedItems(items, groupKey).length };
+}
+//# sourceMappingURL=grouping.js.map

package/dist/server/server/ingestion/hard-failure.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The eight literal phrases that mark a non-self-resolving failure.
+ *
+ * Verbatim from `run-agent.sh:37`'s `LOOP_HARD_FAIL_RE`, in the same order.
+ *
+ * NON-GLOBAL on purpose, and it must stay that way. A `/g` regex carries
+ * `lastIndex` between calls, so `hardFailureSig(text)` would return a different
+ * answer the second time it was handed the same text - and the first thing a
+ * retry loop does is call it again with the same text. Non-global `.exec()`
+ * also reproduces `grep -aoiE ... | head -1` exactly: first match in document
+ * order, across lines.
+ */
+export declare const HARD_FAILURE_PATTERN: RegExp;
+/**
+ * How much of a failure signature the ledger will store.
+ *
+ * Every signature this module produces is one of eight short kebab strings, so
+ * the cap never bites here. It exists as a guard at the ledger's write boundary
+ * (NFR1): a caller passing its own signature cannot turn `fail_sig` into a
+ * dumping ground for a raw log line, which is how a bearer token would end up
+ * in a column nobody thinks of as sensitive.
+ */
+export declare const FAIL_SIG_MAX_LENGTH = 64;
+/**
+ * Every signature `hardFailureSig` can ever return.
+ *
+ * This is what makes `isHardFailureSig` an ENUMERATION of what aborts a tick
+ * rather than a second, drifting regex over an already-kebabed string. Note
+ * that a kebab signature does NOT match `HARD_FAILURE_PATTERN` any more -
+ * `rate-limit` is not `Rate limit` - so testing a stored signature against the
+ * pattern would quietly answer "not a hard failure" for every one of them.
+ */
+export declare const HARD_FAILURE_SIGS: ReadonlySet<string>;
+/**
+ * The kebab signature for a failure log, or `null` when nothing in it says the
+ * failure is permanent.
+ *
+ * Port of `hard_failure_sig()` at `run-agent.sh:41`. The AC table this is
+ * asserted against was produced by running that shell function, not by reading
+ * it, so the two are known to agree byte for byte.
+ */
+export declare function hardFailureSig(text: string): string | null;
+/**
+ * Is this signature one of the eight that abort a tick?
+ *
+ * Deliberately false for `daemon-restart` (the signature `releaseStaleClaims()`
+ * stamps): a crash counts toward backoff, but it is not an auth or quota wall
+ * and must never abort a tick or wake anybody up.
+ */
+export declare function isHardFailureSig(sig: string | null | undefined): boolean;
+/**
+ * Thrown to unwind the REST of the current ingestion tick after a hard failure.
+ *
+ * This is the typed equivalent of the `break` at `inbox-watcher/run.sh:113`.
+ * Read that line carefully before changing anything here: `alert_once` is
+ * deduped by a `/tmp` marker, but `break` is NOT. The alert is at most once a
+ * day; the abort happens on EVERY hard failure. Suppressing the alert must
+ * never suppress the abort, or the second dead-credential failure of the day
+ * burns the entire remaining tick against the same dead credential.
+ *
+ * The ledger never throws this. It is Epic 2's dispatch loop that throws it and
+ * `instanceof`-catches it, on seeing `FailureOutcome.abortTick`.
+ */
+export declare class AbortTickError extends Error {
+    /** The filter whose tick is being abandoned, carried structurally so no caller regexes the message. */
+    readonly filterId: string;
+    /** The kebab signature that caused the abort - one of `HARD_FAILURE_SIGS`. */
+    readonly sig: string;
+    constructor(filterId: string, sig: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=hard-failure.d.ts.map

package/dist/server/server/ingestion/hard-failure.js

@@ -0,0 +1,125 @@
+// HARD FAILURES - the failures that will NOT fix themselves on retry.
+//
+// An expired credential, a revoked key, an exhausted quota: retrying these is
+// pure cost. The loops fleet learned that the expensive way, and the answer it
+// settled on lives in `~/super-repo/tooling/loops/lib/run-agent.sh:37-49`:
+// recognise the failure, alert AT MOST once a day, and stop the current pass
+// instead of burning it against a wall.
+//
+// This module is the faithful port of the recognition half. The alerting half
+// (once per (filter, sig, UTC date)) lives on the ledger, because it needs
+// durable storage; the abort half is `AbortTickError`, which Epic 2's dispatch
+// loop throws and catches. This file deliberately owns none of the policy - it
+// only answers "is this a hard failure, and what do we call it?".
+/**
+ * The eight literal phrases that mark a non-self-resolving failure.
+ *
+ * Verbatim from `run-agent.sh:37`'s `LOOP_HARD_FAIL_RE`, in the same order.
+ *
+ * NON-GLOBAL on purpose, and it must stay that way. A `/g` regex carries
+ * `lastIndex` between calls, so `hardFailureSig(text)` would return a different
+ * answer the second time it was handed the same text - and the first thing a
+ * retry loop does is call it again with the same text. Non-global `.exec()`
+ * also reproduces `grep -aoiE ... | head -1` exactly: first match in document
+ * order, across lines.
+ */
+export const HARD_FAILURE_PATTERN = /Not logged in|Please run \/login|Invalid API key|authentication_error|insufficient_quota|quota exceeded|Rate limit|forbidden/i;
+/**
+ * The same eight phrases as data, so the CLOSED SET of signatures can be
+ * derived rather than hand-maintained beside the regex.
+ *
+ * A test asserts these two declarations cannot drift apart: every phrase must
+ * match the pattern, and the pattern must have exactly this many alternations.
+ * Without that pairing, adding a ninth phrase to one and not the other would
+ * make a real hard failure silently register as an ordinary one.
+ */
+const HARD_FAILURE_PHRASES = [
+    "Not logged in",
+    "Please run /login",
+    "Invalid API key",
+    "authentication_error",
+    "insufficient_quota",
+    "quota exceeded",
+    "Rate limit",
+    "forbidden",
+];
+/**
+ * How much of a failure signature the ledger will store.
+ *
+ * Every signature this module produces is one of eight short kebab strings, so
+ * the cap never bites here. It exists as a guard at the ledger's write boundary
+ * (NFR1): a caller passing its own signature cannot turn `fail_sig` into a
+ * dumping ground for a raw log line, which is how a bearer token would end up
+ * in a column nobody thinks of as sensitive.
+ */
+export const FAIL_SIG_MAX_LENGTH = 64;
+/**
+ * The shell's `tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/-\{1,\}/-/g;s/^-//;s/-$//'`.
+ *
+ * `tr -c 'a-z0-9' '-'` also rewrites the trailing newline `grep` emits, which
+ * is why the `sed` trims a leading and trailing dash. On a JS string there is
+ * no trailing newline, so collapse-then-trim is the whole of it.
+ */
+function toSig(match) {
+    return match
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, FAIL_SIG_MAX_LENGTH);
+}
+/**
+ * Every signature `hardFailureSig` can ever return.
+ *
+ * This is what makes `isHardFailureSig` an ENUMERATION of what aborts a tick
+ * rather than a second, drifting regex over an already-kebabed string. Note
+ * that a kebab signature does NOT match `HARD_FAILURE_PATTERN` any more -
+ * `rate-limit` is not `Rate limit` - so testing a stored signature against the
+ * pattern would quietly answer "not a hard failure" for every one of them.
+ */
+export const HARD_FAILURE_SIGS = new Set(HARD_FAILURE_PHRASES.map(toSig));
+/**
+ * The kebab signature for a failure log, or `null` when nothing in it says the
+ * failure is permanent.
+ *
+ * Port of `hard_failure_sig()` at `run-agent.sh:41`. The AC table this is
+ * asserted against was produced by running that shell function, not by reading
+ * it, so the two are known to agree byte for byte.
+ */
+export function hardFailureSig(text) {
+    const match = HARD_FAILURE_PATTERN.exec(text);
+    if (!match)
+        return null;
+    return toSig(match[0]);
+}
+/**
+ * Is this signature one of the eight that abort a tick?
+ *
+ * Deliberately false for `daemon-restart` (the signature `releaseStaleClaims()`
+ * stamps): a crash counts toward backoff, but it is not an auth or quota wall
+ * and must never abort a tick or wake anybody up.
+ */
+export function isHardFailureSig(sig) {
+    return sig != null && HARD_FAILURE_SIGS.has(sig);
+}
+/**
+ * Thrown to unwind the REST of the current ingestion tick after a hard failure.
+ *
+ * This is the typed equivalent of the `break` at `inbox-watcher/run.sh:113`.
+ * Read that line carefully before changing anything here: `alert_once` is
+ * deduped by a `/tmp` marker, but `break` is NOT. The alert is at most once a
+ * day; the abort happens on EVERY hard failure. Suppressing the alert must
+ * never suppress the abort, or the second dead-credential failure of the day
+ * burns the entire remaining tick against the same dead credential.
+ *
+ * The ledger never throws this. It is Epic 2's dispatch loop that throws it and
+ * `instanceof`-catches it, on seeing `FailureOutcome.abortTick`.
+ */
+export class AbortTickError extends Error {
+    constructor(filterId, sig, options) {
+        super(`Ingestion tick for filter ${filterId} aborted: hard failure "${sig}" will not resolve on retry.`, options);
+        this.name = "AbortTickError";
+        this.filterId = filterId;
+        this.sig = sig;
+    }
+}
+//# sourceMappingURL=hard-failure.js.map