wake-bridge 0.9.0-preview.8

package/dist/src/sdk-error.js

@@ -0,0 +1,12 @@
+/** Error raised by a public contract validator or SDK client. */
+export class WakeBridgeSdkError extends Error {
+    code;
+    status;
+    constructor(message, code = "invalid_contract", status = 400) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "WakeBridgeSdkError";
+    }
+}
+//# sourceMappingURL=sdk-error.js.map

package/dist/src/sdk-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-error.js","sourceRoot":"","sources":["../../src/sdk-error.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAGhC;IACA;IAHX,YACE,OAAe,EACN,OAAe,kBAAkB,EACjC,SAAiB,GAAG;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,SAAI,GAAJ,IAAI,CAA6B;QACjC,WAAM,GAAN,MAAM,CAAc;QAG7B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/src/source-adapter.d.ts

@@ -0,0 +1,32 @@
+import { WakeBridge } from "./core.js";
+import type { PullSourceAdapter, SourceAdapterManifest, SourceCheckpoint, SourceCursor, SourceRunResult } from "./types.js";
+export declare class SourceCheckpointStore {
+    readonly bridge: WakeBridge;
+    constructor(bridge: WakeBridge);
+    get(source: string): SourceCheckpoint | null;
+    /** Compare-and-swap prevents two pollers from silently moving one cursor. */
+    commit(manifest: SourceAdapterManifest, cursor: SourceCursor, expectedRevision: number): SourceCheckpoint;
+    replace(manifest: SourceAdapterManifest, cursor: SourceCursor, expectedRevision: number, reason: string): SourceCheckpoint;
+}
+export declare class SourceControlStore {
+    readonly bridge: WakeBridge;
+    constructor(bridge: WakeBridge);
+    get(source: string): boolean | null;
+    set(source: string, enabled: boolean): void;
+}
+export interface SourceRunnerOptions {
+    limit?: number;
+    /** Unsafe sources remain test-only unless an embedding opts in explicitly. */
+    allow_read_side_effects?: boolean;
+    /**
+     * Broad/unknown provider credentials are allowed behind an external connector,
+     * but remain fail-closed when injected into the Wake Bridge process itself.
+     */
+    allow_in_process_broad_credentials?: boolean;
+}
+export declare class SourceRunner {
+    readonly bridge: WakeBridge;
+    readonly checkpoints: SourceCheckpointStore;
+    constructor(bridge: WakeBridge);
+    runOnce(adapter: PullSourceAdapter, options?: SourceRunnerOptions): Promise<SourceRunResult>;
+}

package/dist/src/source-adapter.js

@@ -0,0 +1,164 @@
+import { BridgeError } from "./core.js";
+import { sqlValue } from "./db.js";
+import { validateSourceManifest } from "./source-sdk.js";
+const MAX_CURSOR_BYTES = 4096;
+function cursorJson(cursor) {
+    let encoded;
+    try {
+        encoded = JSON.stringify(cursor);
+    }
+    catch {
+        throw new BridgeError("source cursor must be JSON", "invalid_source_cursor", 400);
+    }
+    if (typeof encoded !== "string") {
+        throw new BridgeError("source cursor must be JSON", "invalid_source_cursor", 400);
+    }
+    if (Buffer.byteLength(encoded, "utf8") > MAX_CURSOR_BYTES) {
+        throw new BridgeError("source cursor is too large", "invalid_source_cursor", 413);
+    }
+    return encoded;
+}
+export class SourceCheckpointStore {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    get(source) {
+        const row = this.bridge.db.query(`SELECT * FROM source_checkpoints WHERE instance_id=${sqlValue(this.bridge.config.instance_id)} AND source=${sqlValue(source)} LIMIT 1;`)[0];
+        if (!row)
+            return null;
+        let cursor;
+        try {
+            cursor = JSON.parse(String(row.cursor_json));
+            cursorJson(cursor);
+        }
+        catch (error) {
+            if (error instanceof BridgeError)
+                throw error;
+            throw new BridgeError("stored source cursor is corrupt", "source_cursor_corrupt", 500);
+        }
+        return {
+            instance_id: String(row.instance_id),
+            source: String(row.source),
+            adapter_version: String(row.adapter_version),
+            subject_ref: String(row.subject_ref),
+            binding_fingerprint: String(row.binding_fingerprint),
+            cursor,
+            revision: Number(row.revision),
+            updated_at: String(row.updated_at),
+        };
+    }
+    /** Compare-and-swap prevents two pollers from silently moving one cursor. */
+    commit(manifest, cursor, expectedRevision) {
+        const encoded = cursorJson(cursor);
+        const now = this.bridge.nowIso();
+        const statements = expectedRevision === 0
+            ? [`INSERT OR IGNORE INTO source_checkpoints(instance_id, source, adapter_version, subject_ref, binding_fingerprint, cursor_json, revision, updated_at)
+          VALUES(${sqlValue(this.bridge.config.instance_id)}, ${sqlValue(manifest.id)}, ${sqlValue(manifest.version)}, ${sqlValue(manifest.subject_ref)}, ${sqlValue(manifest.binding_fingerprint)}, ${sqlValue(encoded)}, 1, ${sqlValue(now)});`]
+            : [`UPDATE source_checkpoints SET adapter_version=${sqlValue(manifest.version)}, subject_ref=${sqlValue(manifest.subject_ref)}, binding_fingerprint=${sqlValue(manifest.binding_fingerprint)}, cursor_json=${sqlValue(encoded)}, revision=revision+1, updated_at=${sqlValue(now)}
+          WHERE instance_id=${sqlValue(this.bridge.config.instance_id)} AND source=${sqlValue(manifest.id)} AND revision=${expectedRevision}
+            AND subject_ref=${sqlValue(manifest.subject_ref)} AND binding_fingerprint=${sqlValue(manifest.binding_fingerprint)};`];
+        this.bridge.db.transaction(statements);
+        const checkpoint = this.get(manifest.id);
+        if (!checkpoint || checkpoint.revision !== expectedRevision + 1 || checkpoint.adapter_version !== manifest.version
+            || checkpoint.subject_ref !== manifest.subject_ref || checkpoint.binding_fingerprint !== manifest.binding_fingerprint
+            || cursorJson(checkpoint.cursor) !== encoded) {
+            throw new BridgeError("source cursor changed concurrently", "source_cursor_conflict", 409);
+        }
+        return checkpoint;
+    }
+    replace(manifest, cursor, expectedRevision, reason) {
+        const before = this.get(manifest.id);
+        if (!before || before.revision !== expectedRevision) {
+            throw new BridgeError("source checkpoint changed concurrently", "source_cursor_conflict", 409);
+        }
+        const encoded = cursorJson(cursor);
+        const now = this.bridge.nowIso();
+        this.bridge.db.transaction([
+            `INSERT INTO source_checkpoint_history(instance_id, source, adapter_version, subject_ref, binding_fingerprint, cursor_json, revision, updated_at, archived_at, reason)
+       SELECT instance_id, source, adapter_version, subject_ref, binding_fingerprint, cursor_json, revision, updated_at, ${sqlValue(now)}, ${sqlValue(reason)}
+       FROM source_checkpoints
+       WHERE instance_id=${sqlValue(this.bridge.config.instance_id)} AND source=${sqlValue(manifest.id)} AND revision=${expectedRevision};`,
+            `UPDATE source_checkpoints SET adapter_version=${sqlValue(manifest.version)}, subject_ref=${sqlValue(manifest.subject_ref)}, binding_fingerprint=${sqlValue(manifest.binding_fingerprint)}, cursor_json=${sqlValue(encoded)}, revision=revision+1, updated_at=${sqlValue(now)}
+       WHERE instance_id=${sqlValue(this.bridge.config.instance_id)} AND source=${sqlValue(manifest.id)} AND revision=${expectedRevision};`,
+        ]);
+        const checkpoint = this.get(manifest.id);
+        if (!checkpoint || checkpoint.revision !== expectedRevision + 1 || checkpoint.subject_ref !== manifest.subject_ref
+            || checkpoint.binding_fingerprint !== manifest.binding_fingerprint || cursorJson(checkpoint.cursor) !== encoded) {
+            throw new BridgeError("source checkpoint replacement failed", "source_cursor_conflict", 409);
+        }
+        return checkpoint;
+    }
+}
+export class SourceControlStore {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    get(source) {
+        const row = this.bridge.db.query(`SELECT enabled FROM source_controls WHERE instance_id=${sqlValue(this.bridge.config.instance_id)} AND source=${sqlValue(source)} LIMIT 1;`)[0];
+        return row ? Boolean(Number(row.enabled)) : null;
+    }
+    set(source, enabled) {
+        const now = this.bridge.nowIso();
+        this.bridge.db.exec(`INSERT INTO source_controls(instance_id, source, enabled, updated_at)
+      VALUES(${sqlValue(this.bridge.config.instance_id)}, ${sqlValue(source)}, ${sqlValue(enabled)}, ${sqlValue(now)})
+      ON CONFLICT(instance_id, source) DO UPDATE SET enabled=excluded.enabled, updated_at=excluded.updated_at;`);
+    }
+}
+export class SourceRunner {
+    bridge;
+    checkpoints;
+    constructor(bridge) {
+        this.bridge = bridge;
+        this.checkpoints = new SourceCheckpointStore(bridge);
+    }
+    async runOnce(adapter, options = {}) {
+        const manifest = validateSourceManifest(adapter.manifest);
+        if (manifest.read_side_effects !== "none" && !options.allow_read_side_effects) {
+            throw new BridgeError(`source ${manifest.id} has ${manifest.read_side_effects} read side effects`, "unsafe_source_read", 409);
+        }
+        // This gate checks the deployment's declared custody; it is not a sandbox
+        // and cannot inspect where an arbitrary adapter object really keeps a token.
+        // Production launchers must derive/attest custody instead of trusting an
+        // untrusted provider payload. Provider credentials never arrive via events.
+        if (manifest.credential_custody === "wake_bridge_process"
+            && !["none", "read_only"].includes(manifest.upstream_credential_breadth)
+            && !options.allow_in_process_broad_credentials) {
+            throw new BridgeError(`source ${manifest.id} injects a broad or unknown credential into Wake Bridge`, "unsafe_source_credential", 409);
+        }
+        const limit = Math.min(1000, Math.max(1, Math.floor(options.limit ?? 100)));
+        const before = this.checkpoints.get(manifest.id);
+        if (before && (before.subject_ref !== manifest.subject_ref || before.binding_fingerprint !== manifest.binding_fingerprint)) {
+            throw new BridgeError(`source ${manifest.id} identity differs from its checkpoint`, "source_identity_mismatch", 409);
+        }
+        const result = await adapter.poll({ cursor: before?.cursor ?? null, limit });
+        if (!result || !Array.isArray(result.events) || result.events.length > limit) {
+            throw new BridgeError("source poll returned an invalid or oversized event page", "invalid_source_page", 502);
+        }
+        cursorJson(result.next_cursor);
+        let inserted = 0;
+        let duplicate = 0;
+        for (const event of result.events) {
+            const emitted = this.bridge.emitEvent(manifest.id, event);
+            if (emitted.duplicate)
+                duplicate += 1;
+            else
+                inserted += 1;
+        }
+        // Cursor advancement happens only after every event in this page is
+        // durably accepted. A crash in the gap replays the page and is absorbed by
+        // the event dedupe key rather than losing source facts.
+        const checkpoint = this.checkpoints.commit(manifest, result.next_cursor, before?.revision ?? 0);
+        return {
+            source: manifest.id,
+            adapter_version: manifest.version,
+            checkpoint_revision: checkpoint.revision,
+            events_seen: result.events.length,
+            events_inserted: inserted,
+            events_duplicate: duplicate,
+            has_more: result.has_more === true,
+        };
+    }
+}
+//# sourceMappingURL=source-adapter.js.map

package/dist/src/source-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-adapter.js","sourceRoot":"","sources":["../../src/source-adapter.ts"],"names":[],"mappings":"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"}

package/dist/src/source-connector.d.ts

@@ -0,0 +1,50 @@
+import { WakeBridge } from "./core.js";
+import { SourceCheckpointStore } from "./source-adapter.js";
+import type { PullSourceAdapter, SourceAdapterManifest, SourceConnectorConfig, SourcePollContext, SourcePollResult, SourceSupervisorStatus, SourceVerification } from "./types.js";
+export declare function validateSourceConnectorConfig(value: SourceConnectorConfig): Required<SourceConnectorConfig>;
+export declare function loadSourceConnectorFile(path: string): Required<SourceConnectorConfig>[];
+type Fetch = typeof fetch;
+/** One connected poll view. Provider credentials never cross this boundary. */
+export declare class HttpPullSourceAdapter implements PullSourceAdapter {
+    readonly manifest: SourceAdapterManifest;
+    private readonly config;
+    private readonly environment;
+    private readonly fetcher;
+    private constructor();
+    static connect(config: Required<SourceConnectorConfig>, environment?: NodeJS.ProcessEnv, fetcher?: Fetch): Promise<HttpPullSourceAdapter>;
+    poll(context: SourcePollContext): Promise<SourcePollResult>;
+}
+export declare function bootstrapSourceConnector(bridge: WakeBridge, rawConfig: SourceConnectorConfig, mode: "from-now", environment?: NodeJS.ProcessEnv, fetcher?: Fetch, expected?: {
+    subject_ref: string;
+    binding_fingerprint: string;
+}): Promise<ReturnType<SourceCheckpointStore["commit"]>>;
+export declare class SourceSupervisor {
+    private readonly environment;
+    private readonly fetcher;
+    private readonly runner;
+    private readonly controls;
+    private readonly slots;
+    private stopped;
+    constructor(bridge: WakeBridge, configs: SourceConnectorConfig[], environment?: NodeJS.ProcessEnv, fetcher?: Fetch);
+    list(): SourceSupervisorStatus[];
+    verify(source: string): Promise<SourceVerification>;
+    bootstrap(source: string, expected: {
+        subject_ref: string;
+        binding_fingerprint: string;
+    }): Promise<SourceVerification>;
+    rebind(source: string, expectedRevision: number, expected: {
+        subject_ref: string;
+        binding_fingerprint: string;
+    }, reason: string): Promise<SourceVerification>;
+    enable(source: string): Promise<SourceSupervisorStatus>;
+    disable(source: string): Promise<SourceSupervisorStatus>;
+    start(): void;
+    runOnce(source: string): Promise<SourceSupervisorStatus>;
+    private slot;
+    private refreshCheckpoint;
+    stop(): Promise<void>;
+    private schedule;
+    private launch;
+    private run;
+}
+export {};

package/dist/src/source-connector.js

@@ -0,0 +1,358 @@
+import { readFileSync } from "node:fs";
+import { BridgeError } from "./core.js";
+import { SourceCheckpointStore, SourceControlStore, SourceRunner } from "./source-adapter.js";
+import { validateSourceManifest } from "./source-sdk.js";
+import { WakeBridgeSdkError } from "./sdk-error.js";
+const SOURCE_ID = /^[A-Za-z0-9_.:-]{1,128}$/u;
+const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/u;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "::1"]);
+function integer(value, fallback, min, max, field) {
+    const candidate = value === undefined ? fallback : Number(value);
+    if (!Number.isSafeInteger(candidate) || candidate < min || candidate > max) {
+        throw new BridgeError(`${field} is invalid`, "invalid_source_connector", 400);
+    }
+    return candidate;
+}
+export function validateSourceConnectorConfig(value) {
+    if (!value || !SOURCE_ID.test(value.id || "")) {
+        throw new BridgeError("source connector id is invalid", "invalid_source_connector", 400);
+    }
+    if (!ENV_NAME.test(value.token_env || "")) {
+        throw new BridgeError(`source connector ${value.id} token_env is invalid`, "invalid_source_connector", 400);
+    }
+    let url;
+    try {
+        url = new URL(value.base_url);
+    }
+    catch {
+        throw new BridgeError(`source connector ${value.id} base_url is invalid`, "invalid_source_connector", 400);
+    }
+    if (url.protocol !== "http:" || !LOOPBACK_HOSTS.has(url.hostname) || url.username || url.password
+        || (url.pathname !== "/" && url.pathname !== "") || url.search || url.hash) {
+        throw new BridgeError(`source connector ${value.id} must use a loopback HTTP origin`, "unsafe_source_connector", 409);
+    }
+    return {
+        id: value.id,
+        base_url: url.origin,
+        token_env: value.token_env,
+        enabled: value.enabled !== false,
+        poll_interval_ms: integer(value.poll_interval_ms, 60_000, 1_000, 86_400_000, "poll_interval_ms"),
+        max_backoff_ms: integer(value.max_backoff_ms, 900_000, 1_000, 86_400_000, "max_backoff_ms"),
+        limit: integer(value.limit, 100, 1, 1000, "limit"),
+        max_pages_per_cycle: integer(value.max_pages_per_cycle, 4, 1, 100, "max_pages_per_cycle"),
+    };
+}
+export function loadSourceConnectorFile(path) {
+    let document;
+    try {
+        document = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new BridgeError(`cannot read source connector file: ${error instanceof Error ? error.message : String(error)}`, "invalid_source_connector_file", 400);
+    }
+    const file = document;
+    if (!file || file.version !== 1 || !Array.isArray(file.sources)) {
+        throw new BridgeError("source connector file must have version 1 and a sources array", "invalid_source_connector_file", 400);
+    }
+    const sources = file.sources.map(validateSourceConnectorConfig);
+    const ids = new Set();
+    for (const source of sources) {
+        if (ids.has(source.id))
+            throw new BridgeError(`duplicate source connector id: ${source.id}`, "invalid_source_connector_file", 400);
+        ids.add(source.id);
+    }
+    return sources;
+}
+async function connectorJson(fetcher, config, environment, path, body) {
+    const token = environment[config.token_env];
+    if (!token)
+        throw new BridgeError(`source connector ${config.id} token is unavailable`, "source_connector_auth_unavailable", 503);
+    let response;
+    try {
+        response = await fetcher(`${config.base_url}${path}`, {
+            method: body === undefined ? "GET" : "POST",
+            headers: { authorization: `Bearer ${token}`, accept: "application/json", ...(body === undefined ? {} : { "content-type": "application/json" }) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (error) {
+        throw new BridgeError(`source connector ${config.id} is unavailable: ${error instanceof Error ? error.message : String(error)}`, "source_connector_unavailable", 503);
+    }
+    if (!response.ok) {
+        const errorClass = response.status === 401 || response.status === 403
+            ? "source_connector_unauthorized"
+            : response.status === 408 || response.status === 425 || response.status === 429 || response.status >= 500
+                ? "source_connector_http_error"
+                : "source_connector_contract_error";
+        throw new BridgeError(`source connector ${config.id} returned HTTP ${response.status}`, errorClass, 502);
+    }
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new BridgeError(`source connector ${config.id} returned invalid JSON`, "source_connector_invalid_json", 502);
+    }
+}
+/** One connected poll view. Provider credentials never cross this boundary. */
+export class HttpPullSourceAdapter {
+    manifest;
+    config;
+    environment;
+    fetcher;
+    constructor(manifest, config, environment, fetcher) {
+        this.manifest = manifest;
+        this.config = config;
+        this.environment = environment;
+        this.fetcher = fetcher;
+    }
+    static async connect(config, environment = process.env, fetcher = fetch) {
+        const manifest = await connectorJson(fetcher, config, environment, "/v1/manifest");
+        if (!manifest || manifest.id !== config.id) {
+            throw new BridgeError(`source connector ${config.id} manifest id does not match`, "source_connector_identity_mismatch", 409);
+        }
+        if (!["connector", "none"].includes(manifest.credential_custody)) {
+            throw new BridgeError(`source connector ${config.id} reports invalid credential custody`, "source_connector_identity_mismatch", 409);
+        }
+        return new HttpPullSourceAdapter(manifest, config, environment, fetcher);
+    }
+    async poll(context) {
+        return await connectorJson(this.fetcher, this.config, this.environment, "/v1/poll", context);
+    }
+}
+export async function bootstrapSourceConnector(bridge, rawConfig, mode, environment = process.env, fetcher = fetch, expected) {
+    const config = validateSourceConnectorConfig(rawConfig);
+    const adapter = await HttpPullSourceAdapter.connect(config, environment, fetcher);
+    const manifest = validateSourceManifest(adapter.manifest);
+    if (manifest.read_side_effects !== "none") {
+        throw new BridgeError(`source ${manifest.id} has ${manifest.read_side_effects} read side effects`, "unsafe_source_read", 409);
+    }
+    if (!expected || manifest.subject_ref !== expected.subject_ref || manifest.binding_fingerprint !== expected.binding_fingerprint) {
+        throw new BridgeError(`source ${manifest.id} identity was not explicitly confirmed`, "source_identity_unconfirmed", 409);
+    }
+    const checkpoints = new SourceCheckpointStore(bridge);
+    if (checkpoints.get(manifest.id)) {
+        throw new BridgeError(`source ${manifest.id} already has a checkpoint`, "source_already_bootstrapped", 409);
+    }
+    const result = await connectorJson(fetcher, config, environment, "/v1/bootstrap", { mode });
+    if (!result || typeof result !== "object" || !("cursor" in result)) {
+        throw new BridgeError(`source connector ${config.id} returned an invalid bootstrap`, "source_connector_invalid_bootstrap", 502);
+    }
+    return checkpoints.commit(manifest, result.cursor, 0);
+}
+export class SourceSupervisor {
+    environment;
+    fetcher;
+    runner;
+    controls;
+    slots = new Map();
+    stopped = false;
+    constructor(bridge, configs, environment = process.env, fetcher = fetch) {
+        this.environment = environment;
+        this.fetcher = fetcher;
+        this.runner = new SourceRunner(bridge);
+        this.controls = new SourceControlStore(bridge);
+        for (const raw of configs) {
+            const config = validateSourceConnectorConfig(raw);
+            if (this.slots.has(config.id))
+                throw new BridgeError(`duplicate source connector id: ${config.id}`, "invalid_source_connector", 400);
+            config.enabled = this.controls.get(config.id) ?? config.enabled;
+            const checkpoint = this.runner.checkpoints.get(config.id);
+            this.slots.set(config.id, {
+                config,
+                status: {
+                    source: config.id, enabled: config.enabled, state: config.enabled ? "idle" : "stopped",
+                    last_started_at: null, last_success_at: null, last_error_at: null, last_error_class: null,
+                    consecutive_failures: 0, next_poll_at: null,
+                    checkpoint_revision: checkpoint?.revision ?? 0,
+                    checkpoint_subject_ref: checkpoint?.subject_ref ?? null,
+                    checkpoint_binding_fingerprint: checkpoint?.binding_fingerprint ?? null,
+                    last_run: null,
+                },
+            });
+        }
+    }
+    list() {
+        return [...this.slots.values()].map((slot) => ({ ...slot.status, last_run: slot.status.last_run ? { ...slot.status.last_run } : null }));
+    }
+    async verify(source) {
+        const slot = this.slot(source);
+        const adapter = await HttpPullSourceAdapter.connect(slot.config, this.environment, this.fetcher);
+        const manifest = validateSourceManifest(adapter.manifest);
+        const storedCheckpoint = this.runner.checkpoints.get(source);
+        const checkpoint = storedCheckpoint ? {
+            source: storedCheckpoint.source,
+            adapter_version: storedCheckpoint.adapter_version,
+            subject_ref: storedCheckpoint.subject_ref,
+            binding_fingerprint: storedCheckpoint.binding_fingerprint,
+            revision: storedCheckpoint.revision,
+            updated_at: storedCheckpoint.updated_at,
+        } : null;
+        return {
+            source,
+            manifest,
+            checkpoint,
+            binding_matches: Boolean(storedCheckpoint && storedCheckpoint.subject_ref === manifest.subject_ref
+                && storedCheckpoint.binding_fingerprint === manifest.binding_fingerprint),
+            enabled: slot.config.enabled,
+        };
+    }
+    async bootstrap(source, expected) {
+        const slot = this.slot(source);
+        if (slot.config.enabled)
+            throw new BridgeError("disable the source before bootstrap", "source_must_be_disabled", 409);
+        await bootstrapSourceConnector(this.runner.bridge, slot.config, "from-now", this.environment, this.fetcher, expected);
+        this.refreshCheckpoint(slot);
+        return await this.verify(source);
+    }
+    async rebind(source, expectedRevision, expected, reason) {
+        const slot = this.slot(source);
+        if (slot.config.enabled)
+            throw new BridgeError("disable the source before rebind", "source_must_be_disabled", 409);
+        if (!reason || reason.length > 300)
+            throw new BridgeError("source rebind reason is invalid", "invalid_arguments", 400);
+        const adapter = await HttpPullSourceAdapter.connect(slot.config, this.environment, this.fetcher);
+        const manifest = validateSourceManifest(adapter.manifest);
+        if (manifest.subject_ref !== expected.subject_ref || manifest.binding_fingerprint !== expected.binding_fingerprint) {
+            throw new BridgeError(`source ${source} identity was not explicitly confirmed`, "source_identity_unconfirmed", 409);
+        }
+        const result = await connectorJson(this.fetcher, slot.config, this.environment, "/v1/bootstrap", { mode: "from-now" });
+        if (!result || typeof result !== "object" || !("cursor" in result)) {
+            throw new BridgeError(`source connector ${source} returned an invalid bootstrap`, "source_connector_invalid_bootstrap", 502);
+        }
+        this.runner.checkpoints.replace(manifest, result.cursor, expectedRevision, reason);
+        this.refreshCheckpoint(slot);
+        return await this.verify(source);
+    }
+    async enable(source) {
+        const slot = this.slot(source);
+        const verified = await this.verify(source);
+        if (!verified.checkpoint || !verified.binding_matches) {
+            throw new BridgeError("source identity is not bound to its checkpoint", "source_identity_mismatch", 409);
+        }
+        this.controls.set(source, true);
+        slot.config.enabled = true;
+        slot.status.enabled = true;
+        if (!this.stopped && !slot.promise)
+            this.schedule(slot, 0);
+        return this.list().find((item) => item.source === source);
+    }
+    async disable(source) {
+        const slot = this.slot(source);
+        this.controls.set(source, false);
+        slot.config.enabled = false;
+        slot.status.enabled = false;
+        if (slot.timer)
+            clearTimeout(slot.timer);
+        slot.timer = undefined;
+        slot.status.next_poll_at = null;
+        await slot.promise;
+        slot.status.state = "stopped";
+        return this.list().find((item) => item.source === source);
+    }
+    start() {
+        this.stopped = false;
+        for (const slot of this.slots.values())
+            if (slot.config.enabled)
+                this.schedule(slot, 0);
+    }
+    async runOnce(source) {
+        const slot = this.slot(source);
+        if (slot.promise)
+            throw new BridgeError(`source connector ${source} is already polling`, "source_connector_busy", 409);
+        if (slot.timer)
+            clearTimeout(slot.timer);
+        slot.timer = undefined;
+        slot.promise = this.launch(slot);
+        await slot.promise;
+        return this.list().find((status) => status.source === source);
+    }
+    slot(source) {
+        const slot = this.slots.get(source);
+        if (!slot)
+            throw new BridgeError(`source connector ${source} is not configured`, "source_connector_not_found", 404);
+        return slot;
+    }
+    refreshCheckpoint(slot) {
+        const checkpoint = this.runner.checkpoints.get(slot.config.id);
+        slot.status.checkpoint_revision = checkpoint?.revision ?? 0;
+        slot.status.checkpoint_subject_ref = checkpoint?.subject_ref ?? null;
+        slot.status.checkpoint_binding_fingerprint = checkpoint?.binding_fingerprint ?? null;
+    }
+    async stop() {
+        this.stopped = true;
+        for (const slot of this.slots.values()) {
+            if (slot.timer)
+                clearTimeout(slot.timer);
+            slot.timer = undefined;
+            slot.status.next_poll_at = null;
+        }
+        await Promise.all([...this.slots.values()].map((slot) => slot.promise).filter(Boolean));
+        for (const slot of this.slots.values())
+            slot.status.state = "stopped";
+    }
+    schedule(slot, delay) {
+        if (this.stopped || !slot.config.enabled)
+            return;
+        if (slot.timer)
+            clearTimeout(slot.timer);
+        slot.status.next_poll_at = new Date(Date.now() + delay).toISOString();
+        slot.timer = setTimeout(() => {
+            slot.timer = undefined;
+            if (slot.promise)
+                return;
+            slot.promise = this.launch(slot);
+        }, delay);
+        slot.timer.unref();
+    }
+    launch(slot) {
+        let nextDelay = null;
+        return this.run(slot)
+            .then((delay) => { nextDelay = delay; })
+            .finally(() => {
+            slot.promise = undefined;
+            if (nextDelay !== null)
+                this.schedule(slot, nextDelay);
+        });
+    }
+    async run(slot) {
+        slot.status.state = "polling";
+        slot.status.last_started_at = new Date().toISOString();
+        slot.status.next_poll_at = null;
+        try {
+            const adapter = await HttpPullSourceAdapter.connect(slot.config, this.environment, this.fetcher);
+            let result = await this.runner.runOnce(adapter, { limit: slot.config.limit });
+            const aggregate = { ...result };
+            for (let page = 1; result.has_more && page < slot.config.max_pages_per_cycle; page += 1) {
+                result = await this.runner.runOnce(adapter, { limit: slot.config.limit });
+                aggregate.checkpoint_revision = result.checkpoint_revision;
+                aggregate.events_seen += result.events_seen;
+                aggregate.events_inserted += result.events_inserted;
+                aggregate.events_duplicate += result.events_duplicate;
+                aggregate.has_more = result.has_more;
+            }
+            slot.status.state = "healthy";
+            slot.status.last_success_at = new Date().toISOString();
+            slot.status.last_error_at = null;
+            slot.status.last_error_class = null;
+            slot.status.consecutive_failures = 0;
+            slot.status.checkpoint_revision = aggregate.checkpoint_revision;
+            this.refreshCheckpoint(slot);
+            slot.status.last_run = aggregate;
+            return aggregate.has_more ? 0 : slot.config.poll_interval_ms;
+        }
+        catch (error) {
+            const errorClass = error instanceof WakeBridgeSdkError ? error.code : "source_connector_error";
+            const retryable = errorClass === "source_connector_unavailable" || errorClass === "source_connector_http_error";
+            slot.status.state = retryable ? "backoff" : "needs_attention";
+            slot.status.last_error_at = new Date().toISOString();
+            slot.status.last_error_class = errorClass;
+            slot.status.consecutive_failures += 1;
+            if (retryable) {
+                return Math.min(slot.config.max_backoff_ms, slot.config.poll_interval_ms * (2 ** Math.min(10, slot.status.consecutive_failures - 1)));
+            }
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=source-connector.js.map