integration.meeting-intake-worker-postgres-http

Meeting Intake Worker PostgreSQL/HTTP Composition

Production composition for @lssm-tech/app.meeting-intake-worker. It claims the canonical owner-scoped PostgreSQL queue and invokes one protected HTTPS execution service. Only opaque job, connection, and protected-configuration references cross the boundary; provider credentials and meeting content do not. The database lease token remains inside the worker and is never sent to the execution service.

Configure:

• OPA_MEETING_INTAKE_WORKER_COMPOSITION_MODULE=@lssm-tech/integration.meeting-intake-worker-postgres-http
• OPA_MEETING_INTAKE_DATABASE_URL
• OPA_MEETING_INTAKE_OWNER_SCOPES_JSON with 1–100 unique exact five-axis scopes
• OPA_MEETING_INTAKE_EXECUTION_URL using HTTPS
• OPA_MEETING_INTAKE_EXECUTION_TOKEN, at least 32 UTF-8 bytes
• optional bounded SSL, interval, limit, lease, attempt, and timeout settings
• Optional OPA_MEETING_INTAKE_JOBS_JSON, 1–100 declared jobs (see below)

A misconfigured worker fails at start with meeting_intake_worker_configuration_invalid: <KEY>,<KEY>, naming every missing or invalid key and never a value. meetingIntakeWorkerReadiness() (./config) returns the same names without throwing.

Declared jobs and provisioning ownership (./jobs)

OPA_MEETING_INTAKE_JOBS_JSON is for self-hosted or worker deployments. Each entry names an ownerScope from the served scopes, a jobRef, a connectionRef and a protectedConfigRef (opaque references, unique jobRef and connectionRef per scope), an optional scheduleIntervalSeconds (60–86400, default 900) and an optional enabled (default true). The worker upserts the declared jobs of a scope once before its first claim, so a restart re-enables a paused job.

When the variable is unset, the worker declares and provisions nothing. It defers to the CompanyOS API provisioner and only claims jobs that already exist in its served scopes.

A scope must have one provisioner. Before every claim of a scope with declared jobs, the worker looks for an enabled job of the API owner opt-in provisioner (MEETING_INTAKE_API_OWNER_JOB_PREFIX, meeting-intake-job:auto:). That prefix is reserved: a declared jobRef using it makes OPA_MEETING_INTAKE_JOBS_JSON invalid. If such a job exists, the worker skips that scope and keeps serving the others:

• it claims nothing in the scope;
• it emits meeting_intake.provisioning_blocked (metric opa_meeting_intake_provisioning_blocked_total) once each time the scope becomes blocked;
• it still applies the scope's declared enabled: false jobs, because disabling a job cannot create a second provisioner.

A connectionRef belongs to one job row per scope (unique(owner, connection_ref)), even a disabled one. When another row already holds a declared job's connectionRef (for example after a jobRef rename), the upsert's unique violation does not stop the worker: the scope is skipped the same way with the blocker meeting_intake_declared_job_conflict and the declared jobRef, and every later claim retries the write. The worker never deletes or re-points the other row; a database operator does.

provisioningBlockers() on the composition lists the scopes skipped by their latest claim, each with its readiness blocker (meeting_intake_api_provisioner_conflict or meeting_intake_declared_job_conflict); the worker app's /readyz reports them and fails closed, answering 503 while any remains (its other scopes keep running). PGlite tests run the provisioner check and the 23505 connection conflict as opa_app under the 0041 FORCE RLS policies. findMeetingIntakeProvisioningBlocker() runs the owner-scoped API provisioner check, and MeetingIntakeProvisioningBlockedError lets a host fail closed on a blocker.

Reauthorization (./reauthorization)

The HTTP boundary keeps the execution service's closed, redacted error code (for example granola_auth_failed) instead of execution_http_<status>. A code in MEETING_INTAKE_REAUTHORIZATION_CODES (the three Granola credential codes and calendar_reauthorization_required, the credential lapses the CompanyOS API cron also recognizes) emits meeting_intake.reauthorization_required (metric opa_meeting_intake_reauthorization_required_total) and, for a job this worker declared, pauses it (SqlMeetingIntakeJobControl.pause, owner-scoped, FORCE RLS); a worker restart re-provisions and re-enables it. The worker never pauses a job provisioned elsewhere (no declared jobs): that provisioner keeps control and the alert reports jobPaused: false. Alerts carry opaque references and closed codes only; the default sink writes one JSON line to stderr.

Executor readiness (./execution-readiness)

meetingIntakeExecutionReadiness(env, expectedPath) names the API host keys that are unset or unusable for the protected executor route: the execution URL (HTTPS and the mounted path), the token (at least 32 bytes), the owner scopes and protected configurations, and the Granola credential each configured recorder transport needs. A calendar-only configuration (no recorder, or recorder: null) needs no Granola credential. It never echoes a value. The CompanyOS API serves it, with the in-process cron and calendar sync readiness, on the service-authorized operator route GET /api/opa/meeting-intake/readiness (key names and states only).

The operator runbook is docs/operations/founder-ops-v2/meetings-enable.md (section 3).

The execution service must authenticate the worker, resolve the protected configuration and provider credentials server-side, re-prove current owner and provider authority, run calendar/recorder intake idempotently by executionRef, persist occurrence/review/binding results, and return exactly:

{
  "version": "v1",
  "requestRef": "request:opaque",
  "executionRef": "execution:opaque",
  "status": "completed",
  "providerReceiptRef": "receipt:opaque"
}

Non-200 responses fail closed. HTTP 408, 429, and 5xx are retryable; other 4xx and malformed or mismatched receipts are terminal.

Protected execution service

./execution-service provides the server side of this boundary as a Request -> Response handler. It authenticates the worker token in constant time, accepts only configured exact owner scopes, re-proves authority through the host authorize port, executes once per executionRef (a replay returns the stored receipt; a changed request under the same reference is 409) and returns the exact v1 receipt. Executor failures map to 503 (retryable) or 422 (terminal) with a redacted code. Hosts compose execute from the calendar/recorder evidence ingestion and governed binding; credentials are resolved server-side from protectedConfigRef and never cross the boundary.