Interface ConnectorCreationPipelineOptions

Directory for structured progress artifacts. Defaults to <cwd>/logs/integration-runs. Each run gets its own <runID>/ subdir containing manifest.json, progress.jsonl, result.json.

CompanyIntegration row to authenticate with.

The connector instance to drive (already constructed by caller).

Mirror progress to console (default false).

User context for all entity operations.

§7 — when true, this is a COMPREHENSIVE re-discovery: declared/discovered objects (and their fields) ABSENT from this run are deactivated (Status='Disabled', never deleted; reversible on a later rediscovery). Only set on a full-surface refresh — a scoped/partial discovery must leave it false so it never disables what it didn't look at. Threaded to PersistDiscoveredSchema.

Optional subset filter — limits introspection to a named set of objects.

Optional one-shot LLM callback for the PK classifier's last-resort step.

Optional metadata provider override (multi-provider scenarios).

Hard ceiling for the WHOLE run. Default DEFAULT_RUN_DEADLINE_MS; 0 disables it.

Every other budget in this system bounds something INSIDE a stage, and none of them can preempt an await that never settles. A connector's outOfTime() is only checked BETWEEN requests; an HTTP abort signal governs only its own request; the discovery sample budget is spent by the code reading the stream. There is always one more layer able to stall — and when one does, this pipeline waits on it forever.

Forever is literal. complete() and fail() are the only writers of result.json and both sit inside the try/catch around the stages, so a stage that never returns reaches neither. Since isInFlight is computed as "result.json is absent", the run then reports itself running for the rest of time: no client can learn otherwise and no retry clears it.

Observed live 2026-08-12 three times on one connector: ConnectionTest completes in ~1s, Introspect starts, and the event stream is flat for ten minutes and counting — against a reference run that finished the entire pipeline in 3m53s.

This does NOT stop the stalled work; a promise is not cancellable, so it keeps running until the process ends. It stops WAITING on it, so the run fails honestly, writes its artifact, and becomes retryable. A reported failure you can act on beats silence you cannot.

Optional explicit runID. When omitted, generated as connector-<ts>-<rand>. Supply your own when resuming a previously-killed run.

Optional pre-fetched sample rows per object for statistical PK detection.

Trigger reason recorded in the manifest.

Optional vendor-wide PK convention hint (e.g. "id" for HubSpot).