@indigoai-us/hq-cli 5.345.178 → 5.345.180

package/dist/lib/hot-channels/contract.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Declarative hot-channel adapter contract.
+ *
+ * Owner requirement (hot-signal-sync US-001), verbatim: "we want to be able to
+ * add more hot channels to the list without some massive engineering effort."
+ *
+ * Every channel-specific fact lives on the adapter object as data. The shared
+ * loop (loop.ts) is written once against this contract and only branches on
+ * `transport`. Adding a channel is one adapter registered in the registry plus
+ * one catalog entry; the loop, landing format, and readers do not change.
+ */
+/** How events reach HQ: pushed into the person's buffer, or polled by cursor. */
+export type HotTransport = "push" | "poll";
+export declare const HOT_TRANSPORTS: readonly HotTransport[];
+/** Upper bound on any adapter's catch-up window (30 days). */
+export declare const MAX_CATCH_UP_WINDOW_MS: number;
+/**
+ * Bounded look-back. The loop never lands an event older than
+ * `now - maxLookbackMs`, and poll adapters receive it as `since`.
+ */
+export interface CatchUpWindow {
+    maxLookbackMs: number;
+}
+/** The connection a channel needs: provider id plus the scopes it requires. */
+export interface TokenScope {
+    provider: string;
+    scopes: readonly string[];
+}
+/**
+ * Rule-based suggestion declaration. Pure data, evaluated without a model
+ * call. US-001 declares and validates it; evaluation belongs to US-014.
+ */
+export type SuggestionRule = {
+    kind: "recent-activity";
+    withinMs: number;
+    minEvents: number;
+} | {
+    kind: "assigned-to-me";
+} | {
+    kind: "owned-by-me";
+};
+export declare const SUGGESTION_RULE_KINDS: readonly SuggestionRule["kind"][];
+/** The normalized event an adapter emits, independent of the provider. */
+export interface HotEvent {
+    /** Provider-side id of the object the event is about. */
+    providerId: string;
+    /** Provider-side version (revision, updated-at, sequence). Part of the dedupe key. */
+    version: string;
+    who: string;
+    what: string;
+    where: string;
+    /** ISO 8601 time the event happened. */
+    when: string;
+    audience: string[];
+    title?: string;
+    body?: string;
+    /** Provider payload, written verbatim to the `.raw.json` sidecar. */
+    raw?: unknown;
+}
+/**
+ * The adapter's handle to one connection, routed through the HQ integration
+ * gateway. The gateway holds the provider token; an adapter never sees it.
+ */
+export interface HotChannelGateway {
+    connectionId: string;
+    provider: string;
+    /** Call one provider tool on this connection and return its unwrapped result. */
+    call(tool: string, args: Record<string, unknown>): Promise<unknown>;
+}
+export interface PollContext {
+    /** ISO time: now minus the adapter's catch-up window. */
+    since: string;
+    personUid: string;
+    /** Present when the run is bound to a connection (on-demand and scheduled syncs). */
+    gateway?: HotChannelGateway;
+    /**
+     * Gateways for the adapter's `companionProviders`, one per usable
+     * connection. Set only for adapters that declare companions (meetings reads
+     * the vault and also pulls Fireflies or Granola notes).
+     */
+    gateways?: HotChannelGateway[];
+    /**
+     * Called before an adapter writes to the vault itself (meetings writes
+     * provider notes during fetch). Throws to stop the run when the sync lock
+     * was lost.
+     */
+    beforeWrite?: () => Promise<void>;
+}
+export interface PollPage {
+    events: HotEvent[];
+    /** Cursor to resume from. Stored only after every event on the page lands. */
+    cursor: string | null;
+    /** True when the provider has another page ready now. */
+    hasMore?: boolean;
+}
+/** Fields every adapter declares, whatever its transport. */
+export interface HotChannelDeclaration {
+    /** Adapter id. Used in `event_key` and for push-buffer / cursor paths. */
+    id: string;
+    /** Source channel segment: landed docs go to `sources/{channel}/`. */
+    channel: string;
+    transport: HotTransport;
+    hotEventTypes: readonly string[];
+    catchUpWindow: CatchUpWindow;
+    tokenScope: TokenScope;
+    suggestionRule: SuggestionRule;
+    /**
+     * Optional feature-flag gate. When set, the adapter runs only for companies
+     * whose catalog lists it, which hq-pro does only while `flag` is on. With the
+     * flag off, `hq sources sync` reports the adapter as `gated` and never calls it.
+     */
+    gate?: HotChannelGate;
+    /**
+     * Optional extra providers whose usable connections this one channel also
+     * reads, e.g. meetings pulls Fireflies and Granola beside the HQ bot. The
+     * run hands every matching connection to `fetch` as `PollContext.gateways`.
+     */
+    companionProviders?: readonly string[];
+}
+/** A feature flag the adapter needs on before it runs. */
+export interface HotChannelGate {
+    /** Flag key as registered in hq-pro, e.g. `hq.hot-channel-gmail`. */
+    flag: string;
+}
+export interface PushHotChannelAdapter extends HotChannelDeclaration {
+    transport: "push";
+}
+export interface PollHotChannelAdapter extends HotChannelDeclaration {
+    transport: "poll";
+    fetch(cursor: string | null, ctx: PollContext): Promise<PollPage>;
+}
+export type HotChannelAdapter = PushHotChannelAdapter | PollHotChannelAdapter;
+/** Minimal catalog entry shape; the hq-pro catalog (US-002) extends it. */
+export interface CatalogEntry {
+    provider: string;
+    enabled?: boolean;
+    /**
+     * The connection this entry runs against. A channel runs once per usable
+     * connection, and each connection keeps its own cursor. Unset for channels
+     * that need no connection (meetings reads the vault).
+     */
+    connectionId?: string;
+    /** Companion connections (see `companionProviders`) handed to this entry's run. */
+    companionConnectionIds?: readonly string[];
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/lib/hot-channels/contract.js

@@ -0,0 +1,20 @@
+/**
+ * Declarative hot-channel adapter contract.
+ *
+ * Owner requirement (hot-signal-sync US-001), verbatim: "we want to be able to
+ * add more hot channels to the list without some massive engineering effort."
+ *
+ * Every channel-specific fact lives on the adapter object as data. The shared
+ * loop (loop.ts) is written once against this contract and only branches on
+ * `transport`. Adding a channel is one adapter registered in the registry plus
+ * one catalog entry; the loop, landing format, and readers do not change.
+ */
+export const HOT_TRANSPORTS = ["push", "poll"];
+/** Upper bound on any adapter's catch-up window (30 days). */
+export const MAX_CATCH_UP_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+export const SUGGESTION_RULE_KINDS = [
+    "recent-activity",
+    "assigned-to-me",
+    "owned-by-me",
+];
+//# sourceMappingURL=contract.js.map

package/dist/lib/hot-channels/cursors.d.ts

@@ -0,0 +1,41 @@
+/** What one cursor file holds. */
+export interface CursorRecord {
+    cursor: string | null;
+    updatedAt: string;
+    /** `{adapter}:{provider_id}:{version}` of the last event processed before this cursor. */
+    lastEventKey: string | null;
+}
+/**
+ * Where poll cursors live, keyed by the person's audience key (see
+ * `audienceKey`). `set` keeps the stored `lastEventKey` when none is passed.
+ */
+export interface CursorStore {
+    get(personKey: string, adapterId: string): Promise<string | null>;
+    set(personKey: string, adapterId: string, cursor: string | null, lastEventKey?: string | null): Promise<void>;
+}
+/** `@{personKey}`, the per-person directory name under `_cursors/` and `_runs/`. */
+export declare function personDirName(personKey: string): string;
+/**
+ * The poller only writes under `sources/`. This refuses any path that resolves
+ * into `secrets/integrations/`, so a misconfigured vault root cannot make a run
+ * touch integration credentials.
+ */
+export declare function assertNotIntegrationSecretsPath(file: string): void;
+/**
+ * The cursor-store key for one adapter on one connection:
+ * `{adapterId}.{connectionId}`, or `{adapterId}` when the channel has no
+ * connection. A connection id that cannot be a file-name segment as-is
+ * (uppercase, other characters, too long) is replaced by a hash of it, so two
+ * connections never share a cursor file.
+ */
+export declare function cursorKey(adapterId: string, connectionId?: string | null): string;
+/** `{vaultRoot}/sources/_cursors/@{personKey}/{adapterId}.json` (adapterId may be a `cursorKey`). */
+export declare function cursorFilePath(vaultRoot: string, personKey: string, adapterId: string): string;
+export interface VaultCursorStore extends CursorStore {
+    read(personKey: string, adapterId: string): Promise<CursorRecord | null>;
+}
+/** One JSON file per person and adapter in the company vault. */
+export declare function createVaultCursorStore(vaultRoot: string, options?: {
+    now?: () => Date;
+}): VaultCursorStore;
+//# sourceMappingURL=cursors.d.ts.map

package/dist/lib/hot-channels/cursors.js

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { assertSafeSegment, writeFileAtomic } from "./landing.js";
+/** `@{personKey}`, the per-person directory name under `_cursors/` and `_runs/`. */
+export function personDirName(personKey) {
+    assertSafeSegment(personKey, "person key");
+    return `@${personKey}`;
+}
+/**
+ * The poller only writes under `sources/`. This refuses any path that resolves
+ * into `secrets/integrations/`, so a misconfigured vault root cannot make a run
+ * touch integration credentials.
+ */
+export function assertNotIntegrationSecretsPath(file) {
+    const parts = path.resolve(file).split(path.sep);
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        if (parts[i] === "secrets" && parts[i + 1] === "integrations") {
+            throw new Error("hot-channel runs never write under secrets/integrations/");
+        }
+    }
+}
+const SAFE_KEY = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/**
+ * The cursor-store key for one adapter on one connection:
+ * `{adapterId}.{connectionId}`, or `{adapterId}` when the channel has no
+ * connection. A connection id that cannot be a file-name segment as-is
+ * (uppercase, other characters, too long) is replaced by a hash of it, so two
+ * connections never share a cursor file.
+ */
+export function cursorKey(adapterId, connectionId) {
+    assertSafeSegment(adapterId, "adapter id");
+    if (connectionId === undefined || connectionId === null)
+        return adapterId;
+    if (typeof connectionId !== "string" || connectionId.length === 0) {
+        throw new Error("connection id must be a non-empty string");
+    }
+    const plain = `${adapterId}.${connectionId}`;
+    if (SAFE_KEY.test(plain) && !plain.includes(".."))
+        return plain;
+    const hash = createHash("sha256").update(connectionId).digest("hex").slice(0, 16);
+    return `${adapterId}.c-${hash}`;
+}
+/** `{vaultRoot}/sources/_cursors/@{personKey}/{adapterId}.json` (adapterId may be a `cursorKey`). */
+export function cursorFilePath(vaultRoot, personKey, adapterId) {
+    assertSafeSegment(adapterId, "adapter id");
+    const file = path.join(vaultRoot, "sources", "_cursors", personDirName(personKey), `${adapterId}.json`);
+    assertNotIntegrationSecretsPath(file);
+    return file;
+}
+/** One JSON file per person and adapter in the company vault. */
+export function createVaultCursorStore(vaultRoot, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const read = async (personKey, adapterId) => {
+        let text;
+        try {
+            text = await fs.readFile(cursorFilePath(vaultRoot, personKey, adapterId), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        const parsed = JSON.parse(text);
+        return {
+            cursor: typeof parsed.cursor === "string" ? parsed.cursor : null,
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+            lastEventKey: typeof parsed.lastEventKey === "string" ? parsed.lastEventKey : null,
+        };
+    };
+    return {
+        read,
+        async get(personKey, adapterId) {
+            return (await read(personKey, adapterId))?.cursor ?? null;
+        },
+        async set(personKey, adapterId, cursor, lastEventKey) {
+            const file = cursorFilePath(vaultRoot, personKey, adapterId);
+            const kept = lastEventKey === undefined ? ((await read(personKey, adapterId))?.lastEventKey ?? null) : lastEventKey;
+            const record = { cursor, updatedAt: now().toISOString(), lastEventKey: kept };
+            await writeFileAtomic(file, `${JSON.stringify(record)}\n`);
+        },
+    };
+}
+//# sourceMappingURL=cursors.js.map

package/dist/lib/hot-channels/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./contract.js";
+export * from "./registry.js";
+export * from "./landing.js";
+export * from "./audience.js";
+export * from "./cursors.js";
+export * from "./loop.js";
+export * from "./ledger.js";
+export * from "./run.js";
+export * from "./adapters/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/hot-channels/index.js

@@ -0,0 +1,10 @@
+export * from "./contract.js";
+export * from "./registry.js";
+export * from "./landing.js";
+export * from "./audience.js";
+export * from "./cursors.js";
+export * from "./loop.js";
+export * from "./ledger.js";
+export * from "./run.js";
+export * from "./adapters/index.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/hot-channels/landing.d.ts

@@ -0,0 +1,83 @@
+import type { HotChannelDeclaration, HotEvent } from "./contract.js";
+/** `origin` written on every hot-signal landed document. */
+export declare const HOT_SIGNAL_ORIGIN = "hot-signal-sync";
+export type LandingOutcome = "landed" | "duplicate";
+/**
+ * Optional landing hints an adapter may set on an event it emits. They change
+ * only how the event is written, never its dedupe identity.
+ */
+export interface HotEventLandingHints {
+    /**
+     * Vault-relative key of an existing source document the event points at,
+     * under `sources/`. When set, the landed document's `payload_ref` names it
+     * and `raw_ref` names the `.raw.json` sidecar.
+     */
+    payloadRef?: string;
+    /** Extra scalar frontmatter fields. They may not replace a field landing writes. */
+    frontmatter?: Record<string, string>;
+}
+export interface LandHotEventInput {
+    /** Root of the person's vault scope; `sources/` lives directly under it. */
+    vaultRoot: string;
+    adapter: Pick<HotChannelDeclaration, "id" | "channel">;
+    personUid: string;
+    event: HotEvent & HotEventLandingHints;
+    now?: Date;
+}
+export interface LandHotEventResult {
+    outcome: LandingOutcome;
+    eventKey: string;
+    sourceId: string;
+    /** Vault-relative key of the landed markdown document. */
+    markdownKey: string;
+    /** Vault-relative key of the raw payload sidecar (`payload_ref`). */
+    rawKey: string;
+}
+/** Index row; same shape as hq-pro's `SourceIndexEntry`. */
+export interface HotSourceIndexEntry {
+    source_ref: {
+        channel: string;
+        source_id: string;
+        key: string;
+    };
+    channel: string;
+    source_id: string;
+    keys: {
+        markdown: string;
+        raw: string;
+    };
+    written_at: string;
+    title?: string | null;
+    ingested_at?: string;
+    event_key: string;
+}
+/** `{adapter}:{provider_id}:{version}`, the dedupe identity of an event. */
+export declare function eventKey(adapterId: string, providerId: string, version: string): string;
+/**
+ * Deterministic, path-safe source id for an event key. The same event always
+ * maps to the same file, which is what makes landing idempotent.
+ */
+export declare function hotSourceId(adapterId: string, key: string): string;
+export declare function assertSafeSegment(value: string, label: string): void;
+/** A single event is malformed. The loop quarantines it and keeps going. */
+export declare class HotEventValidationError extends Error {
+    constructor(message: string);
+}
+/** Throws `HotEventValidationError` unless the event has every required field. */
+export declare function assertHotEvent(event: HotEvent): void;
+/**
+ * A payload ref is a vault-relative key under `sources/`: at least three
+ * segments, none empty, `.` or `..`, and no backslash or NUL. The signals pass
+ * checks a landed `payload_ref` with the same rule before reading it.
+ */
+export declare function assertPayloadRef(ref: string): void;
+/** Write via a sibling temp file and rename, so readers never see a partial file. */
+export declare function writeFileAtomic(file: string, contents: string): Promise<void>;
+/**
+ * Land one normalized event as a source document under
+ * `sources/{channel}/{source_id}.md`, with its raw payload alongside and a row
+ * in the day's source index. Returns `duplicate` without writing anything when
+ * a document for the same `event_key` already exists.
+ */
+export declare function landHotEvent(input: LandHotEventInput): Promise<LandHotEventResult>;
+//# sourceMappingURL=landing.d.ts.map

package/dist/lib/hot-channels/landing.js

@@ -0,0 +1,175 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+/** `origin` written on every hot-signal landed document. */
+export const HOT_SIGNAL_ORIGIN = "hot-signal-sync";
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** `{adapter}:{provider_id}:{version}`, the dedupe identity of an event. */
+export function eventKey(adapterId, providerId, version) {
+    return `${adapterId}:${providerId}:${version}`;
+}
+/**
+ * Deterministic, path-safe source id for an event key. The same event always
+ * maps to the same file, which is what makes landing idempotent.
+ */
+export function hotSourceId(adapterId, key) {
+    const digest = createHash("sha256").update(key).digest("hex").slice(0, 32);
+    return `${adapterId}-${digest}`;
+}
+export function assertSafeSegment(value, label) {
+    if (typeof value !== "string" ||
+        value.includes("..") ||
+        value.includes("/") ||
+        value.includes("\\") ||
+        value.includes("\0") ||
+        !SAFE_SEGMENT.test(value)) {
+        throw new Error(`${label} must be a safe path segment`);
+    }
+}
+/** A single event is malformed. The loop quarantines it and keeps going. */
+export class HotEventValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HotEventValidationError";
+    }
+}
+/** Throws `HotEventValidationError` unless the event has every required field. */
+export function assertHotEvent(event) {
+    if (!event || typeof event !== "object")
+        throw new HotEventValidationError("hot event is not an object");
+    for (const field of ["providerId", "version", "who", "what", "where", "when"]) {
+        if (typeof event[field] !== "string" || event[field].length === 0) {
+            throw new HotEventValidationError(`hot event is missing ${field}`);
+        }
+    }
+    if (Number.isNaN(Date.parse(event.when))) {
+        throw new HotEventValidationError("hot event `when` must be an ISO date-time");
+    }
+    if (!Array.isArray(event.audience) || !event.audience.every((a) => typeof a === "string")) {
+        throw new HotEventValidationError("hot event audience must be a list of strings");
+    }
+}
+/**
+ * A payload ref is a vault-relative key under `sources/`: at least three
+ * segments, none empty, `.` or `..`, and no backslash or NUL. The signals pass
+ * checks a landed `payload_ref` with the same rule before reading it.
+ */
+export function assertPayloadRef(ref) {
+    const parts = typeof ref === "string" ? ref.split("/") : [];
+    if (ref.includes("\\") ||
+        ref.includes("\0") ||
+        parts.length < 3 ||
+        parts[0] !== "sources" ||
+        parts.some((part) => part === "" || part === "." || part === "..")) {
+        throw new HotEventValidationError("hot event payloadRef must be a vault-relative key under sources/");
+    }
+}
+async function exists(file) {
+    try {
+        await fs.access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Write via a sibling temp file and rename, so readers never see a partial file. */
+export async function writeFileAtomic(file, contents) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        await fs.writeFile(tmp, contents, "utf8");
+        await fs.rename(tmp, file);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true });
+        throw err;
+    }
+}
+async function appendIndexEntry(vaultRoot, day, entry) {
+    const file = path.join(vaultRoot, "sources", "_index", `${day}.json`);
+    let rows = [];
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        if (Array.isArray(parsed))
+            rows = parsed;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    if (rows.some((row) => row.channel === entry.channel && row.source_id === entry.source_id))
+        return;
+    rows.push(entry);
+    await writeFileAtomic(file, `${JSON.stringify(rows, null, 2)}\n`);
+}
+/**
+ * Land one normalized event as a source document under
+ * `sources/{channel}/{source_id}.md`, with its raw payload alongside and a row
+ * in the day's source index. Returns `duplicate` without writing anything when
+ * a document for the same `event_key` already exists.
+ */
+export async function landHotEvent(input) {
+    const { vaultRoot, adapter, personUid, event } = input;
+    const now = (input.now ?? new Date()).toISOString();
+    assertSafeSegment(adapter.id, "adapter id");
+    assertSafeSegment(adapter.channel, "channel");
+    assertSafeSegment(personUid, "person uid");
+    assertHotEvent(event);
+    const key = eventKey(adapter.id, event.providerId, event.version);
+    const sourceId = hotSourceId(adapter.id, key);
+    const markdownKey = `sources/${adapter.channel}/${sourceId}.md`;
+    const rawKey = `sources/${adapter.channel}/${sourceId}.raw.json`;
+    const markdownFile = path.join(vaultRoot, markdownKey);
+    const result = { eventKey: key, sourceId, markdownKey, rawKey };
+    if (await exists(markdownFile))
+        return { outcome: "duplicate", ...result };
+    if (event.payloadRef !== undefined)
+        assertPayloadRef(event.payloadRef);
+    const title = event.title ?? event.what;
+    const frontmatter = {
+        id: sourceId,
+        channel: adapter.channel,
+        source_id: sourceId,
+        source_ref: { channel: adapter.channel, source_id: sourceId, key: markdownKey },
+        title,
+        origin: HOT_SIGNAL_ORIGIN,
+        person_uid: personUid,
+        created_at: event.when,
+        updated_at: now,
+        ingested_at: now,
+        event_key: key,
+        who: event.who,
+        what: event.what,
+        where: event.where,
+        when: event.when,
+        audience: [...event.audience],
+        payload_ref: event.payloadRef ?? rawKey,
+    };
+    if (event.payloadRef !== undefined)
+        frontmatter.raw_ref = rawKey;
+    for (const [field, value] of Object.entries(event.frontmatter ?? {})) {
+        if (field in frontmatter || typeof value !== "string") {
+            throw new HotEventValidationError(`hot event frontmatter field ${field} is reserved or not a string`);
+        }
+        frontmatter[field] = value;
+    }
+    const markdown = `---\n${yaml.dump(frontmatter, { lineWidth: -1, noRefs: true }).trimEnd()}\n---\n${event.body ?? ""}`;
+    // Raw first, markdown second: the markdown is the dedupe marker, so it must
+    // only exist once its payload_ref target does.
+    await writeFileAtomic(path.join(vaultRoot, rawKey), `${JSON.stringify(event.raw ?? event, null, 2)}\n`);
+    await writeFileAtomic(markdownFile, markdown);
+    await appendIndexEntry(vaultRoot, now.slice(0, 10), {
+        source_ref: frontmatter.source_ref,
+        channel: adapter.channel,
+        source_id: sourceId,
+        keys: { markdown: markdownKey, raw: rawKey },
+        written_at: now,
+        title,
+        ingested_at: now,
+        event_key: key,
+    });
+    return { outcome: "landed", ...result };
+}
+//# sourceMappingURL=landing.js.map

package/dist/lib/hot-channels/ledger.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The sources/signals run ledger. Every hot-channel run appends one JSON line
+ * per adapter to `sources/_runs/@{personKey}/{YYYY-MM-DD}.jsonl`, so a person
+ * can see what each run landed and what it produced.
+ *
+ * Owner, verbatim: "sync and build feels wrong. we should be logging sources and signals generated."
+ */
+import { type HotChannelRunResult, type RunHotChannelLoopInput, type WriteGuard } from "./loop.js";
+/** The signals pass over one adapter's landed sources; checks `guard` before each write. */
+export type SignalsGeneratedFn = (result: HotChannelRunResult, guard?: WriteGuard) => number | Promise<number>;
+export type RunTrigger = "scheduled" | "on-demand";
+export type RunStatus = "ok" | "failed" | "skipped";
+export declare const RUN_TRIGGERS: readonly RunTrigger[];
+/** One line of the run ledger: one adapter in one run. */
+export interface RunLedgerEntry {
+    runId: string;
+    trigger: RunTrigger;
+    adapter: string;
+    /**
+     * The connection the adapter ran against; one line per adapter and
+     * connection. Null for a channel with no connection. Lines written before
+     * this field existed omit it.
+     */
+    connectionId?: string | null;
+    sourcesLanded: number;
+    signalsGenerated: number;
+    startedAt: string;
+    finishedAt: string;
+    status: RunStatus;
+    error: string | null;
+    /** Malformed events this adapter quarantined and skipped. Omitted when 0. */
+    rejected?: number;
+    /** Why each rejected event was skipped. Omitted when nothing was rejected. */
+    rejectedReasons?: string[];
+    /** Why a `skipped` run did not run (for example, another sync is running). */
+    reason?: string;
+    /** The person the key in the path belongs to, so a human can map it back. */
+    personUid: string;
+    /**
+     * True when a scheduled run fired late, after a missed window (the computer
+     * was asleep or the bot was stopped). Omitted for runs that were not marked.
+     */
+    catchUp?: boolean;
+}
+/** The UTC calendar day of an instant, `YYYY-MM-DD`. Ledger files are per UTC day. */
+export declare function ledgerDay(at: Date): string;
+/** `{vaultRoot}/sources/_runs/@{personKey}/{day}.jsonl` */
+export declare function runLedgerPath(vaultRoot: string, personKey: string, day: string): string;
+/**
+ * Append one entry to the ledger for the day it started. The file is opened
+ * with O_APPEND and the line is written in one call, so concurrent runs do not
+ * interleave within a line.
+ */
+export declare function appendRunLedgerEntry(vaultRoot: string, personKey: string, entry: RunLedgerEntry): Promise<string>;
+export interface RunLedgerRead {
+    file: string;
+    entries: RunLedgerEntry[];
+    /** Lines that were not valid ledger entries; skipped and counted. */
+    malformed: number;
+}
+/** Read one day's ledger. A missing file is an empty ledger. */
+export declare function readRunLedger(vaultRoot: string, personKey: string, day: string): Promise<RunLedgerRead>;
+/** Per-adapter totals for one day's ledger. */
+export interface RunLedgerAdapterSummary {
+    adapter: string;
+    runs: number;
+    sourcesLanded: number;
+    signalsGenerated: number;
+    failed: number;
+    firstStartedAt: string;
+    lastFinishedAt: string;
+    lastError: string | null;
+}
+export declare function summarizeRunLedger(entries: readonly RunLedgerEntry[]): RunLedgerAdapterSummary[];
+export interface RunHotChannelSyncInput extends RunHotChannelLoopInput {
+    trigger: RunTrigger;
+    runId?: string;
+    /** Mark every ledger line of this run as a catch-up of a missed scheduled window. */
+    catchUp?: boolean;
+    /**
+     * The signals pass for this adapter's landed sources; returns the number of
+     * signals it wrote. Any throw makes this adapter's line `failed` with a count
+     * of 0 and the run goes on to the next adapter: a `SignalsPassError` (claude
+     * logged out, timed out, or returned bad output) records its code, any other
+     * error its message. With no callback the count is 0.
+     */
+    signalsGenerated?: SignalsGeneratedFn;
+}
+export interface RunHotChannelSyncResult {
+    runId: string;
+    results: HotChannelRunResult[];
+    entries: RunLedgerEntry[];
+}
+/**
+ * Run the hot-channel loop one adapter at a time and write a ledger line for
+ * each. The line is written in a `finally`, so an adapter that fails, or a run
+ * that throws partway, still leaves a `failed` line carrying the error text.
+ * A thrown error is re-raised after its line is written.
+ */
+export declare function runHotChannelSync(input: RunHotChannelSyncInput): Promise<RunHotChannelSyncResult>;
+//# sourceMappingURL=ledger.d.ts.map