@hyperdrive.bot/fleet-server 0.3.99

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

@@ -0,0 +1,57 @@
+import type { FilterMatch } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+import type { SourceItem } from "./types.js";
+/**
+ * The deterministic gate: does this item satisfy this filter, and which
+ * predicates said so.
+ *
+ * PURE, and the purity is the point. No clock, no I/O, no injected service, no
+ * import of `ledger.ts` or `backfill.ts`. The import direction is one way -
+ * `backfill.ts` imports this module and never the reverse - so the thing that
+ * decides "matched" can be tested with nothing but two literals, and can never
+ * quietly acquire a dependency on when it runs or on what was handled before.
+ *
+ * No model decides anything here either (README: `gate.mjs [DETERMINISTIC, no
+ * LLM]`). Every clause is a plain string predicate over a dotted path.
+ */
+/**
+ * Why one item matched, in the user's own words.
+ *
+ * `value` is the operand EXACTLY as it was written on the filter, never a
+ * normalized or lower-cased copy, so a row can render it verbatim and the user
+ * recognises the thing they typed. A reason the user cannot recognise is a
+ * reason that fails to explain.
+ */
+export interface MatchReason {
+    /** The dotted payload path the clause read, e.g. `from` or `headers.subject`. */
+    field: string;
+    /** The operator that was satisfied: one of FILTER_MATCH_OPS. */
+    predicate: string;
+    /** The operand as the filter declares it. */
+    value: string;
+}
+export interface MatchVerdict {
+    matched: boolean;
+    /**
+     * One entry per SATISFIED clause, in the order the clauses are declared on
+     * the filter. Empty whenever `matched` is false: a filter's `all` array is
+     * AND-ed, so a partial set of satisfied clauses is not a match and must not
+     * read like a weak one.
+     */
+    reasons: MatchReason[];
+}
+/**
+ * Evaluate a filter's match against one source item.
+ *
+ * `all` is AND-ed: every clause must hold. `reasons` is populated for each
+ * satisfied clause in declaration order, so an item matching two predicates
+ * returns exactly two reasons and the screen can render them in the order the
+ * user wrote them.
+ *
+ * `appSlug` and `eventType` are deliberately NOT re-checked here. Both scope
+ * which upstream trigger a source subscribes to, and `listItems` is already
+ * called against that source; re-deriving either from the payload would mean
+ * enumerating aggregator field names in code, which Epic 1 forbids. A clause in
+ * `all` is the only thing that reads the payload.
+ */
+export declare function evaluateMatch(item: SourceItem, match: FilterMatch): MatchVerdict;
+//# sourceMappingURL=match.d.ts.map

package/dist/server/server/ingestion/match.js

@@ -0,0 +1,102 @@
+/**
+ * Resolve a dotted path against the payload, by STRING LOOKUP ONLY.
+ *
+ * App slugs and payload field names are runtime strings from a user-authored
+ * filter document, so nothing here may enumerate them. A path that runs off the
+ * end of the object returns undefined and the clause simply does not match,
+ * which is the honest outcome for a field the item does not have.
+ *
+ * Arrays are indexed by their numeric segment (`to.0.email`); a segment that is
+ * not a key of the current object ends the walk.
+ */
+function readPath(payload, field) {
+    let current = payload;
+    for (const segment of field.split(".")) {
+        if (current === null || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * The value a predicate compares against.
+ *
+ * Only primitives are stringified. An object or an array becomes `null` (no
+ * match) rather than `"[object Object]"` or a comma-joined list, because both
+ * of those make `contains` succeed on text the item does not actually contain -
+ * a false reason, which is worse than a missed match.
+ */
+function comparable(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return null;
+}
+/**
+ * One clause against one field value.
+ *
+ * `equals`, `contains` and `startsWith` are case-insensitive: a filter on
+ * `juridico@` must match a `From:` header the mail client capitalized.
+ *
+ * `matches` is left case-SENSITIVE. FilterMatchClauseSchema stores a pattern
+ * with no flags field, so adding `i` here would be this module deciding it for
+ * every user, with no way to turn it off; a user who wants insensitivity has
+ * `contains` and `startsWith`, or writes a character class. The pattern already
+ * compiled once at schema-parse time (FilterMatchClauseSchema's refine, run by
+ * FilterStore.put BEFORE the bytes hit disk), so this cannot throw for a filter
+ * that came off the store.
+ *
+ * The switch is exhaustive over FILTER_MATCH_OPS by way of the `never`
+ * assertion: an operator added to the schema fails the build here rather than
+ * falling through to "did not match" at run time, which is the silent
+ * disappearance this shape exists to prevent.
+ */
+function clauseSatisfied(clause, raw) {
+    const value = comparable(raw);
+    if (value === null) {
+        return false;
+    }
+    switch (clause.op) {
+        case "equals":
+            return value.toLowerCase() === clause.value.toLowerCase();
+        case "contains":
+            return value.toLowerCase().includes(clause.value.toLowerCase());
+        case "startsWith":
+            return value.toLowerCase().startsWith(clause.value.toLowerCase());
+        case "matches":
+            return new RegExp(clause.value).test(value);
+        default: {
+            const exhaustive = clause.op;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Evaluate a filter's match against one source item.
+ *
+ * `all` is AND-ed: every clause must hold. `reasons` is populated for each
+ * satisfied clause in declaration order, so an item matching two predicates
+ * returns exactly two reasons and the screen can render them in the order the
+ * user wrote them.
+ *
+ * `appSlug` and `eventType` are deliberately NOT re-checked here. Both scope
+ * which upstream trigger a source subscribes to, and `listItems` is already
+ * called against that source; re-deriving either from the payload would mean
+ * enumerating aggregator field names in code, which Epic 1 forbids. A clause in
+ * `all` is the only thing that reads the payload.
+ */
+export function evaluateMatch(item, match) {
+    const reasons = [];
+    for (const clause of match.all) {
+        if (!clauseSatisfied(clause, readPath(item.payload, clause.field))) {
+            return { matched: false, reasons: [] };
+        }
+        reasons.push({ field: clause.field, predicate: clause.op, value: clause.value });
+    }
+    return { matched: true, reasons };
+}
+//# sourceMappingURL=match.js.map

package/dist/server/server/ingestion/pipedream/gateway.d.ts

@@ -0,0 +1,8 @@
+import type { PipedreamConfig, SourceGateway } from "../types.js";
+/**
+ * The gateway's config block. Re-exported from the shared contract so the
+ * adapter's whole configuration surface is readable from this file alone.
+ */
+export type { PipedreamConfig };
+export declare function createPipedreamGateway(config: PipedreamConfig): SourceGateway;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/server/server/ingestion/pipedream/gateway.js

@@ -0,0 +1,282 @@
+import { PipedreamClient } from "@pipedream/sdk";
+import { IngestionError } from "../errors.js";
+import { fingerprint } from "../fingerprint.js";
+/**
+ * Gateway for Pipedream Connect.
+ *
+ * It talks to Pipedream three ways:
+ *  - `apps.list` (SDK) for the integration catalogue;
+ *  - `tokens.create` (SDK) for the connect token behind the browser flow;
+ *  - OAuth client_credentials (REST) for the Bearer that authorizes calls to
+ *    the remote MCP server. That token is cached until shortly before expiry.
+ *
+ * All of this is server side: the client secret and every token stay here and
+ * never reach a client, a log line or the filesystem.
+ */
+const OAUTH_URL = "https://api.pipedream.com/v1/oauth/token";
+const MCP_URL = "https://remote.mcp.pipedream.net/v3";
+/** One catalogue page: the infinite scroll in the client loads 20 at a time. */
+const APPS_LIMIT = 20;
+/**
+ * Deployed triggers scanned per `listItems` page.
+ *
+ * A history read is per trigger, so this bounds the fan-out of a single page:
+ * one `deployedTriggers.list` call plus at most this many `listEvents` calls.
+ */
+const TRIGGERS_PER_PAGE = 10;
+/**
+ * A deployed trigger belongs to `appSlug` when its component key is prefixed by
+ * it, which is Pipedream's own naming convention (`gmail-new-email-received`).
+ *
+ * The `-` is required: without it `git` would claim `github-*` triggers.
+ */
+function triggerBelongsToApp(componentKey, appSlug) {
+    return typeof componentKey === "string" && componentKey.startsWith(`${appSlug}-`);
+}
+/**
+ * The human line for a row.
+ *
+ * Pipedream's own `sum` when it wrote one, otherwise the trigger's name. Never
+ * the raw payload: an event body can carry anything the upstream app sends,
+ * and this string is rendered in a client.
+ */
+function eventTitle(summary, triggerName) {
+    const trimmed = (summary ?? "").trim();
+    return trimmed || triggerName;
+}
+function notConfigured() {
+    throw new IngestionError("PIPEDREAM_OFF", "Pipedream sources are not configured on this daemon.", 422);
+}
+export function createPipedreamGateway(config) {
+    const configured = Boolean(config.clientId && config.clientSecret && config.projectId);
+    /**
+     * The credentials, narrowed. Every path into Pipedream goes through here, so
+     * an unconfigured daemon fails with PIPEDREAM_OFF before it can build a
+     * client, open a socket, or reach for a token.
+     */
+    const credentials = () => {
+        const { clientId, clientSecret, projectId } = config;
+        if (!clientId || !clientSecret || !projectId) {
+            notConfigured();
+        }
+        return { clientId, clientSecret, projectId };
+    };
+    // Built on demand, at most once, so an unconfigured daemon never constructs
+    // an SDK client and a configured one never rebuilds it per call.
+    let sdk = null;
+    const client = () => {
+        const { clientId, clientSecret, projectId } = credentials();
+        if (!sdk) {
+            sdk = new PipedreamClient({
+                clientId,
+                clientSecret,
+                projectId,
+                projectEnvironment: config.environment,
+            });
+        }
+        return sdk;
+    };
+    // Instance-local on purpose, NOT module scope: two gateways built in the same
+    // process must not share a bearer. A module-scoped cache would also survive
+    // between tests and hide exactly the kind of leak this module exists to avoid.
+    let cached = null;
+    async function accessToken() {
+        const { clientId, clientSecret } = credentials();
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.accessToken;
+        }
+        let response;
+        try {
+            response = await fetch(OAUTH_URL, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    grant_type: "client_credentials",
+                    client_id: clientId,
+                    client_secret: clientSecret,
+                }),
+            });
+        }
+        catch {
+            throw new IngestionError("PIPEDREAM_OFFLINE", "Could not reach Pipedream. Check this machine's network connection.", 502);
+        }
+        if (!response.ok) {
+            // Every non-ok status maps here, 401 and 403 included: what Pipedream
+            // rejected is this daemon's own client id/secret, which is an operator
+            // problem no caller can re-authenticate their way out of.
+            throw new IngestionError("PIPEDREAM_AUTH", "Pipedream rejected this daemon's credentials (client id/secret).", 502);
+        }
+        const body = (await response.json());
+        if (!body.access_token) {
+            throw new IngestionError("PIPEDREAM_AUTH", "Pipedream returned no access token.", 502);
+        }
+        // Assigned only here, after the token is known good: a failed fetch must
+        // leave the cache untouched so the next call retries instead of replaying
+        // the failure until the process restarts.
+        const ttlMs = (body.expires_in ?? 3600) * 1000;
+        cached = {
+            accessToken: body.access_token,
+            expiresAt: Date.now() + ttlMs - 60000,
+        };
+        return cached.accessToken;
+    }
+    return {
+        configured,
+        async listSources(query, cursor) {
+            const trimmed = query.trim();
+            const page = await client().apps.list({
+                q: trimmed || undefined,
+                limit: APPS_LIMIT,
+                ...(cursor ? { after: cursor } : {}),
+                // With no search term, popular first (Gmail, Slack...), not alphabetical.
+                ...(trimmed ? {} : { sortKey: "featured_weight", sortDirection: "desc" }),
+            });
+            // Only the first batch is taken (the limit above); the cursor pages the rest.
+            const items = [];
+            for (const app of page.data ?? []) {
+                items.push({
+                    slug: app.nameSlug,
+                    name: app.name,
+                    imgSrc: app.imgSrc,
+                    description: app.description ?? "",
+                });
+                if (items.length >= APPS_LIMIT) {
+                    break;
+                }
+            }
+            const endCursor = page.response?.pageInfo?.endCursor ?? null;
+            return {
+                items,
+                // A next page is only offered when this one came back full. A cursor
+                // handed out from a partial page makes the UI request blank pages
+                // forever.
+                nextCursor: items.length === APPS_LIMIT ? endCursor : null,
+            };
+        },
+        async connect(externalUserId, appSlug) {
+            const result = await client().tokens.create({
+                externalUserId,
+                allowedOrigins: config.allowedOrigins,
+            });
+            // URL + searchParams rather than string concatenation: the SDK's link
+            // already carries query params, and a slug can hold characters that must
+            // be percent-encoded.
+            const redirect = new URL(result.connectLinkUrl);
+            redirect.searchParams.set("app", appSlug);
+            return {
+                redirectUrl: redirect.toString(),
+                expiresAt: result.expiresAt instanceof Date
+                    ? result.expiresAt.toISOString()
+                    : String(result.expiresAt),
+            };
+        },
+        async listAccounts(externalUserId, appSlug) {
+            const page = await client().accounts.list({ externalUserId, app: appSlug });
+            const accounts = [];
+            for (const account of page.data ?? []) {
+                // An absent `healthy` counts as healthy, matching Pipedream's own
+                // reading of the field. Pipedream has no "pending" account: while the
+                // user is still inside the hosted popup no account exists yet, so the
+                // pending signal here is an empty list, not a status.
+                accounts.push({
+                    id: account.id,
+                    status: account.healthy === false ? "inactive" : "active",
+                });
+            }
+            return accounts;
+        },
+        /**
+         * One page of history, read from the triggers this user has deployed for
+         * the app.
+         *
+         * Pipedream Connect has no "list everything that ever happened on this
+         * account" endpoint. What it does have is the event buffer of each deployed
+         * trigger (`deployedTriggers.listEvents`), which IS the history a filter
+         * would have seen, so that is what this reads.
+         *
+         * `accountId` is accepted for contract symmetry with Composio and is
+         * deliberately unused here: Pipedream scopes a deployed trigger by
+         * `externalUserId`, not by connected account, so filtering on the account
+         * would drop every event rather than narrow them.
+         *
+         * Nothing here resolves an MCP target and nothing here takes a bearer. It
+         * is a read, and a read that could arm something is not a preview.
+         */
+        async listItems(input) {
+            const page = await client().deployedTriggers.list({
+                externalUserId: input.externalUserId,
+                limit: TRIGGERS_PER_PAGE,
+                ...(input.cursor ? { after: input.cursor } : {}),
+            });
+            const items = [];
+            for (const emitter of page.data ?? []) {
+                // Only DeployedComponent carries a componentKey; the HTTP and timer
+                // interfaces in the Emitter union are not app triggers at all.
+                const componentKey = emitter.componentKey;
+                if (!triggerBelongsToApp(componentKey, input.appSlug)) {
+                    continue;
+                }
+                const triggerId = emitter.id;
+                if (!triggerId) {
+                    continue;
+                }
+                const triggerName = emitter.name ?? input.appSlug;
+                const events = await client().deployedTriggers.listEvents(triggerId, {
+                    externalUserId: input.externalUserId,
+                    n: input.limit,
+                });
+                for (const event of events.data ?? []) {
+                    // An event we cannot date cannot be placed in the window, and
+                    // inventing a timestamp would silently move it into or out of one.
+                    if (typeof event.ts !== "number" || !Number.isFinite(event.ts)) {
+                        continue;
+                    }
+                    if (event.ts < input.sinceMs) {
+                        continue;
+                    }
+                    const payload = event.e ?? {};
+                    items.push({
+                        key: fingerprint("pipedream", input.appSlug, event.id),
+                        contentHash: fingerprint(JSON.stringify(payload)),
+                        timestampMs: event.ts,
+                        title: eventTitle(event.sum, triggerName),
+                        subtitle: triggerName,
+                        payload,
+                    });
+                }
+            }
+            // A cursor is only handed out when this page came back full. One offered
+            // from a partial page makes the caller request blank pages forever.
+            const triggersSeen = (page.data ?? []).length;
+            const endCursor = page.response?.pageInfo?.endCursor ?? null;
+            return {
+                items,
+                cursor: triggersSeen >= TRIGGERS_PER_PAGE ? endCursor : null,
+            };
+        },
+        /**
+         * The remote MCP endpoint plus the headers that authorize one agent turn.
+         *
+         * The result is built per turn and deliberately goes nowhere else: it is
+         * never persisted, never logged, and never returned to a client. It carries
+         * a live platform bearer, so anything that widens its reach (a store
+         * write, a cache keyed outside this gateway, an RPC response) is a
+         * credential leak.
+         */
+        async mcpTarget(externalUserId, appSlug) {
+            const { projectId } = credentials();
+            const token = await accessToken();
+            return {
+                url: MCP_URL,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "x-pd-project-id": projectId,
+                    "x-pd-environment": config.environment,
+                    "x-pd-external-user-id": externalUserId,
+                    "x-pd-app-slug": appSlug,
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=gateway.js.map

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

@@ -0,0 +1,57 @@
+import type { StoredFilter } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+export declare const FILTER_PRESET_IDS: readonly ["watch", "draft", "ship"];
+export type FilterPresetId = (typeof FILTER_PRESET_IDS)[number];
+/**
+ * A preset is a seed function, never a discriminant. It returns the handful of form fields
+ * a user would otherwise type; no `preset` field exists on `StoredFilterSchema`, so nothing
+ * downstream can ever branch on "which preset made this filter".
+ */
+export type FilterPreset = () => Partial<StoredFilter>;
+/**
+ * `as const satisfies Record<FilterPresetId, FilterPreset>` is what makes a missing preset a
+ * compile error: `as const` alone would happily accept two of the three ids, because the
+ * object would simply have a narrower type than the map anyone reads it as. The `satisfies`
+ * clause is the check; the `as const` only keeps the literal types.
+ *
+ * Every preset seeds `status: "paused"`. Arming is a user action and is never a side effect
+ * of choosing a preset - the document-level sibling of the epic's `runOnCreate` rule.
+ */
+export declare const FILTER_PRESETS: {
+    readonly watch: () => {
+        brief: string;
+        cap: {
+            runsPerDay: number;
+            backoff: {
+                readonly failuresBeforeBackoff: 3;
+                readonly backoffMs: 21600000;
+            };
+        };
+        groupKey: null;
+        status: "paused";
+    };
+    readonly draft: () => {
+        brief: string;
+        cap: {
+            runsPerDay: number;
+            backoff: {
+                readonly failuresBeforeBackoff: 3;
+                readonly backoffMs: 21600000;
+            };
+        };
+        groupKey: null;
+        status: "paused";
+    };
+    readonly ship: () => {
+        brief: string;
+        cap: {
+            runsPerDay: number;
+            backoff: {
+                readonly failuresBeforeBackoff: 3;
+                readonly backoffMs: 21600000;
+            };
+        };
+        groupKey: null;
+        status: "paused";
+    };
+};
+//# sourceMappingURL=presets.d.ts.map

package/dist/server/server/ingestion/presets.js

@@ -0,0 +1,57 @@
+export const FILTER_PRESET_IDS = ["watch", "draft", "ship"];
+/** 3 failures, then 6h. Matches `tooling/loops/lib/ledger.mjs`. */
+const BACKOFF = { failuresBeforeBackoff: 3, backoffMs: 21600000 };
+/**
+ * Read-only. The stop line restated in the tool's own vocabulary, because the agent reads
+ * the brief and never reads the rails.
+ */
+const WATCH_BRIEF = [
+    "Read the matched item and report on it. Say what it is, why it matched, and what it would",
+    "take to handle it. Create nothing, modify nothing, send nothing, delete nothing.",
+    "If action looks needed, stop and say what you would do and why - then wait.",
+].join(" ");
+/**
+ * Prepares, never sends. The empty recipient field is deliberate: README open risk 1 is that
+ * a draft addressed to the wrong recipient is one thumb from irreversible.
+ */
+const DRAFT_BRIEF = [
+    "Do the work and leave the artifact as a draft in the tool it belongs to.",
+    "Leave the recipient field empty - name the recipients you would have used in your report",
+    "instead. Never send, never share, never publish, never delete.",
+].join(" ");
+/** Branch, change, test, merge request - and stop one step before anything irreversible. */
+const SHIP_BRIEF = [
+    "Create a branch, make the change, run the tests, and open the merge request. Then stop.",
+    "Never merge, never push to the default branch, never deploy, never delete.",
+    "Leave the merge request for a human to read and merge.",
+].join(" ");
+/**
+ * `as const satisfies Record<FilterPresetId, FilterPreset>` is what makes a missing preset a
+ * compile error: `as const` alone would happily accept two of the three ids, because the
+ * object would simply have a narrower type than the map anyone reads it as. The `satisfies`
+ * clause is the check; the `as const` only keeps the literal types.
+ *
+ * Every preset seeds `status: "paused"`. Arming is a user action and is never a side effect
+ * of choosing a preset - the document-level sibling of the epic's `runOnCreate` rule.
+ */
+export const FILTER_PRESETS = {
+    watch: () => ({
+        brief: WATCH_BRIEF,
+        cap: { runsPerDay: 20, backoff: BACKOFF },
+        groupKey: null,
+        status: "paused",
+    }),
+    draft: () => ({
+        brief: DRAFT_BRIEF,
+        cap: { runsPerDay: 10, backoff: BACKOFF },
+        groupKey: null,
+        status: "paused",
+    }),
+    ship: () => ({
+        brief: SHIP_BRIEF,
+        cap: { runsPerDay: 5, backoff: BACKOFF },
+        groupKey: null,
+        status: "paused",
+    }),
+};
+//# sourceMappingURL=presets.js.map

package/dist/server/server/ingestion/reconcile/artifact-kind.d.ts

@@ -0,0 +1,19 @@
+import type { ReconcilableArtifactKind } from "./kinds.js";
+/**
+ * The artifact kind behind an OPEN-WORLD app slug, or null when paseo has none.
+ *
+ * `Object.hasOwn` rather than a bare index, and that is a correctness fix rather
+ * than a style preference. `appSlug` is an open-world string from an aggregator
+ * catalogue, so it can be `"toString"`, `"constructor"` or `"__proto__"` - all
+ * of which a bare index resolves to an INHERITED member of `Object.prototype`.
+ * The caller would then treat `Object.prototype.toString` as an artifact kind.
+ * Own-property-only makes the table actually closed.
+ *
+ * `null` is PERMANENT, not transient, and that distinction is load-bearing: it
+ * must never be turned into `unreachable` by a caller. `unreachable` feeds a
+ * retry counter and a backoff window, so spending one on "paseo has no
+ * reconciler for Notion" would burn a retry budget on a network condition that
+ * never happened. See `ReconciliationService.verifyIfStale`, gate 2.
+ */
+export declare function resolveArtifactKind(appSlug: string): ReconcilableArtifactKind | null;
+//# sourceMappingURL=artifact-kind.d.ts.map

package/dist/server/server/ingestion/reconcile/artifact-kind.js

@@ -0,0 +1,65 @@
+// THE ONE app-slug table in this codebase, and `null` is a safe answer.
+//
+// Decision D-6.2-B:
+//
+// Reconciliation is per artifact kind by definition - "is this Gmail draft
+// sent?" cannot be written without naming Gmail - but the only kind-carrying
+// field on a filter is `FilterMatch.appSlug`, an opaque aggregator catalogue
+// string that Epic 1's rule says is never enumerated in code
+// (`packages/protocol/src/ingestion/types.ts`, `FilterMatchSchema`: "App slugs
+// are never enumerated in code (Epic 1 rule); only aggregator kinds are").
+// Something has to bridge the two, so this file is the single, deliberate,
+// documented exception.
+//
+// Its failure mode is the safe one. A slug this map does not know resolves
+// `null`; `ReconciliationService` then performs NO read, the item keeps whatever
+// verdict it already had (`pending` when never verified), and the row stays.
+// Connecting a Notion source therefore produces rows that never close
+// automatically - mildly annoying, and completely safe.
+//
+// The alternative, guessing a reconciler from a slug prefix, would let an
+// unrecognised source close rows using another tool's semantics. An unknown slug
+// means "we cannot verify", which is never "it was handled".
+/**
+ * Known aggregator catalogue slugs, mapped onto the artifact axis.
+ *
+ * Both aggregators spell the calendar app differently and both spellings are in
+ * the wild, so all three land on the one `calendar` kind rather than forcing a
+ * second reconciler that would read the same API.
+ *
+ * Keys are lowercase; `resolveArtifactKind` lowercases and trims before the
+ * lookup, so casing and stray whitespace from a catalogue string do not matter.
+ */
+const ARTIFACT_KIND_BY_APP_SLUG = {
+    gmail: "gmail",
+    gitlab: "gitlab",
+    github: "github",
+    jira: "jira",
+    sentry: "sentry",
+    google_calendar: "calendar",
+    googlecalendar: "calendar",
+    calendar: "calendar",
+};
+/**
+ * The artifact kind behind an OPEN-WORLD app slug, or null when paseo has none.
+ *
+ * `Object.hasOwn` rather than a bare index, and that is a correctness fix rather
+ * than a style preference. `appSlug` is an open-world string from an aggregator
+ * catalogue, so it can be `"toString"`, `"constructor"` or `"__proto__"` - all
+ * of which a bare index resolves to an INHERITED member of `Object.prototype`.
+ * The caller would then treat `Object.prototype.toString` as an artifact kind.
+ * Own-property-only makes the table actually closed.
+ *
+ * `null` is PERMANENT, not transient, and that distinction is load-bearing: it
+ * must never be turned into `unreachable` by a caller. `unreachable` feeds a
+ * retry counter and a backoff window, so spending one on "paseo has no
+ * reconciler for Notion" would burn a retry budget on a network condition that
+ * never happened. See `ReconciliationService.verifyIfStale`, gate 2.
+ */
+export function resolveArtifactKind(appSlug) {
+    const normalized = appSlug.trim().toLowerCase();
+    if (!Object.hasOwn(ARTIFACT_KIND_BY_APP_SLUG, normalized))
+        return null;
+    return ARTIFACT_KIND_BY_APP_SLUG[normalized] ?? null;
+}
+//# sourceMappingURL=artifact-kind.js.map

package/dist/server/server/ingestion/reconcile/calendar.d.ts

@@ -0,0 +1,19 @@
+import type { Reconciler } from "./types.js";
+/**
+ * The event id off the item's URL.
+ *
+ * Google's `eventedit/<base64>` and `?eid=<base64>` forms both carry an opaque
+ * blob that IS the id as far as the API is concerned, so neither is decoded -
+ * decoding would produce `<eventId> <calendarId>` and require guessing where to
+ * split.
+ */
+export declare function parseCalendarEventId(url: string | null): string | null;
+/**
+ * The registry member's factory, so `now` is an argument rather than a global.
+ *
+ * Signatures: `calendar:past:<eventId>`, `calendar:gone:<eventId>`.
+ */
+export declare function createCalendarReconciler(now: () => number): Reconciler;
+/** The registry member. The wall clock is bound HERE and nowhere deeper. */
+export declare const calendarReconciler: Reconciler;
+//# sourceMappingURL=calendar.d.ts.map