feat: scaffold outreach engine monorepo on the novelpad-desktop stack

Workspaces: config (copied), outreach-core (schema + actions/queries +
hard gates), outreach-ai (Gemini client + embeddings copies, profiler and
mission-fit-judge agent stubs), outreach-worker (DBOS executor with
nightly ingest + hourly expiry workflows), outreach-review (RR7 review
queue v0). Initial drizzle migration incl. pgvector extension.

Stack contract: Yarn 4.5.0 + Turbo, Node 22.16, Drizzle 0.44.6 +
pgvector, DBOS 4.17.6, @google/genai on Vertex, gemini-embedding-001
@1536, React Router v7. Files copied from novelpad-desktop carry
provenance headers @ 62c56b87.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

apps/outreach-worker/src/main.ts

@@ -0,0 +1,76 @@
+// Copied/adapted from novelpad-desktop apps/workflow-worker/src/main.ts @ 62c56b87
+/**
+ * Outreach worker — DBOS executor process.
+ *
+ * Runs the grant-match outreach engine's scheduled workflows (nightly grant
+ * ingestion, hourly expiry sweep, and future scoring/sync jobs) against the
+ * outreach Postgres schema. Kept as its own process (mirroring novelpad's
+ * workflow-worker split) so long-running ingestion/scoring steps don't share
+ * a runtime with any future HTTP-facing app in this monorepo.
+ *
+ * Boot order is load-bearing (see ADR 0007 in novelpad-desktop):
+ *   1. Import the workflow modules for side-effect registration
+ *      (`DBOS.registerWorkflow` / `DBOS.registerScheduled`) BEFORE
+ *      `DBOS.launch()` — DBOS only dispatches scheduled/queued jobs for
+ *      workflows that were registered before launch.
+ *   2. Build the pg Pool + Drizzle db.
+ *   3. `DBOS.setConfig(...)`.
+ *   4. `DBOS.launch()` — register-mark closes; the scheduler starts firing.
+ */
+import { DBOS } from '@dbos-inc/dbos-sdk';
+import { DrizzleDataSource } from '@dbos-inc/drizzle-datasource';
+import { schema } from '@novelpad/outreach-core';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import pg from 'pg';
+
+// Importing these modules registers `ingestGrants` (nightly) and
+// `expireGrants` (hourly) as DBOS workflows + scheduled functions as a side
+// effect of module evaluation. Must happen before `DBOS.launch()` below. Each
+// module also exports a `set*Deps` injector — DBOS serializes
+// scheduled-function args, so the `db` handle can't be passed through the
+// scheduler; it's threaded in via this module-scope registry instead (same
+// pattern as novelpad-desktop's `setStartDeps`).
+import { setExpireGrantsDeps } from './workflows/expire-grants.js';
+import { setIngestGrantsDeps } from './workflows/ingest-grants.js';
+
+if (process.env.DATABASE_URL == null) {
+  throw new Error('outreach-worker: DATABASE_URL is required');
+}
+
+const { Pool } = pg;
+const dbosClientConfig = {
+  connectionString: process.env.DATABASE_URL,
+  application_name: 'helmdocs-outreach-worker',
+} satisfies pg.ClientConfig;
+const pool = new Pool({
+  ...dbosClientConfig,
+  max: Number(process.env.PG_POOL_MAX ?? 20),
+});
+
+export const db = drizzle(pool, { schema });
+
+async function main() {
+  // DBOS system schema lives in this same database; initialize it with the
+  // same connection settings as the worker pool.
+  await DrizzleDataSource.initializeDBOSSchema(dbosClientConfig);
+
+  // Inject the shared `db` handle into each scheduled workflow's deps
+  // registry before launch, so the first scheduled tick (which may fire
+  // immediately on an `ExactlyOncePerInterval` catch-up) always has it.
+  setIngestGrantsDeps({ db });
+  setExpireGrantsDeps({ db });
+
+  DBOS.setConfig({
+    name: 'helmdocs-outreach-worker',
+    systemDatabasePool: pool,
+    runAdminServer: false,
+  });
+  await DBOS.launch();
+
+  console.log('[outreach-worker] launched; scheduled workflows active');
+}
+
+main().catch((err) => {
+  console.error('[outreach-worker] fatal:', err);
+  process.exit(1);
+});

apps/outreach-worker/src/workflows/expire-grants.ts

@@ -0,0 +1,70 @@
+/**
+ * Hourly grant expiry sweep.
+ *
+ * Marks grants whose close date has passed as closed so they drop out of the
+ * active match/scoring pool. See `ingest-grants.ts` for the registration
+ * pattern this mirrors (deps-registry + dual workflow/scheduled registration).
+ */
+import { DBOS, SchedulerMode } from '@dbos-inc/dbos-sdk';
+import type { schema } from '@novelpad/outreach-core';
+import { serverExpireClosedGrants } from '@novelpad/outreach-core/server';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+export type OutreachDb = NodePgDatabase<typeof schema>;
+
+export interface ExpireGrantsDeps {
+  readonly db: OutreachDb;
+}
+
+let registeredDeps: ExpireGrantsDeps | null = null;
+
+export function setExpireGrantsDeps(deps: ExpireGrantsDeps): void {
+  registeredDeps = deps;
+}
+
+function getExpireGrantsDeps(): ExpireGrantsDeps {
+  if (registeredDeps == null) {
+    throw new Error(
+      'ExpireGrantsDeps not registered. Call setExpireGrantsDeps() before DBOS.launch().',
+    );
+  }
+  return registeredDeps;
+}
+
+async function expireClosedGrants(db: OutreachDb): Promise<void> {
+  await serverExpireClosedGrants(db);
+}
+const expireClosedGrantsStep = DBOS.registerStep(expireClosedGrants, {
+  name: 'expireClosedGrants',
+  retriesAllowed: true,
+  maxAttempts: 3,
+});
+
+async function runExpireGrants(): Promise<void> {
+  const { db } = getExpireGrantsDeps();
+  await expireClosedGrantsStep(db);
+}
+
+const g = globalThis as unknown as {
+  __outreachExpireGrantsRegistered?: boolean;
+};
+
+if (!g.__outreachExpireGrantsRegistered) {
+  g.__outreachExpireGrantsRegistered = true;
+
+  const expireGrants = async (_scheduledTime: Date, _startedAt: Date) => {
+    try {
+      await runExpireGrants();
+    } catch (err) {
+      console.error('[expire-grants] pass failed:', err);
+      throw err;
+    }
+  };
+
+  DBOS.registerWorkflow(expireGrants, { name: 'expireGrants' });
+  DBOS.registerScheduled(expireGrants, {
+    crontab: '0 * * * *',
+    name: 'expireGrants',
+    mode: SchedulerMode.ExactlyOncePerInterval,
+  });
+}

apps/outreach-worker/src/workflows/ingest-grants.ts

@@ -0,0 +1,137 @@
+/**
+ * Nightly grant ingestion workflow.
+ *
+ * Pulls open grant opportunities from upstream sources (currently just
+ * Grants.gov; NH state postings and 990-PF extracts land as additional
+ * fetch+normalize steps later) and upserts them into the outreach schema.
+ *
+ * Registration follows the pattern established in novelpad-desktop's
+ * `packages/core/src/workflow/dbos/register-readiness-reconcile.server.ts`:
+ * the scheduled function must ALSO be registered as a plain workflow (both
+ * registrations referencing the same function object), and deps are pulled
+ * from a module-scope registry populated before `DBOS.launch()` — DBOS
+ * serializes workflow args, so closures/functions can't cross that boundary.
+ */
+import { DBOS, SchedulerMode } from '@dbos-inc/dbos-sdk';
+import type { schema } from '@novelpad/outreach-core';
+import {
+  serverInsertGrants,
+  type NewGrantInput,
+} from '@novelpad/outreach-core/server';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+export type OutreachDb = NodePgDatabase<typeof schema>;
+
+/** Shape of a single opportunity as returned by the Grants.gov Search2 API. */
+export interface RawGrantsGovOpportunity {
+  readonly opportunityId: string;
+  readonly opportunityNumber: string;
+  readonly opportunityTitle: string;
+  readonly agencyCode: string | null;
+  readonly openDate: string | null;
+  readonly closeDate: string | null;
+  readonly awardCeiling: number | null;
+  readonly awardFloor: number | null;
+}
+
+export interface IngestGrantsDeps {
+  readonly db: OutreachDb;
+}
+
+let registeredDeps: IngestGrantsDeps | null = null;
+
+export function setIngestGrantsDeps(deps: IngestGrantsDeps): void {
+  registeredDeps = deps;
+}
+
+function getIngestGrantsDeps(): IngestGrantsDeps {
+  if (registeredDeps == null) {
+    throw new Error(
+      'IngestGrantsDeps not registered. Call setIngestGrantsDeps() before DBOS.launch().',
+    );
+  }
+  return registeredDeps;
+}
+
+/**
+ * Fetch open opportunities from Grants.gov.
+ *
+ * Real implementation calls the Grants.gov Search2 API
+ * (`POST https://api.grants.gov/v1/api/search2`, JSON body with
+ * `oppStatuses: "posted"` and pagination via `rows`/`startRecordNum`). Stubbed
+ * to an empty array until that integration lands.
+ */
+async function fetchGrantsGov(): Promise<ReadonlyArray<RawGrantsGovOpportunity>> {
+  // TODO(outreach): call Grants.gov Search2 API and paginate through results.
+  return [];
+}
+const fetchGrantsGovStep = DBOS.registerStep(fetchGrantsGov, {
+  name: 'fetchGrantsGov',
+  retriesAllowed: true,
+  maxAttempts: 3,
+});
+
+function normalize(
+  raw: ReadonlyArray<RawGrantsGovOpportunity>,
+): ReadonlyArray<NewGrantInput> {
+  return raw.map((opp) => ({
+    // Stable identity across re-crawls; also the schema's upsert key.
+    sourceUrl: `https://www.grants.gov/search-results-detail/${opp.opportunityId}`,
+    source: 'grants_gov' as const,
+    title: opp.opportunityTitle,
+    funder: opp.agencyCode ?? 'Unknown federal agency',
+    openDate: opp.openDate == null ? null : new Date(opp.openDate),
+    closeDate: opp.closeDate == null ? null : new Date(opp.closeDate),
+    // Schema stores whole dollars (award amounts are never sub-dollar).
+    awardFloor: opp.awardFloor == null ? null : Math.round(opp.awardFloor),
+    awardCeiling: opp.awardCeiling == null ? null : Math.round(opp.awardCeiling),
+    lastVerifiedAt: new Date(),
+  }));
+}
+
+async function upsertGrants(
+  db: OutreachDb,
+  grants: ReadonlyArray<NewGrantInput>,
+): Promise<void> {
+  if (grants.length === 0) return;
+  await serverInsertGrants(db, grants);
+}
+const upsertGrantsStep = DBOS.registerStep(upsertGrants, {
+  name: 'upsertGrants',
+  retriesAllowed: true,
+  maxAttempts: 3,
+});
+
+async function runIngestGrants(): Promise<void> {
+  const { db } = getIngestGrantsDeps();
+
+  const raw = await fetchGrantsGovStep();
+  const normalized = normalize(raw);
+  await upsertGrantsStep(db, normalized);
+}
+
+const g = globalThis as unknown as {
+  __outreachIngestGrantsRegistered?: boolean;
+};
+
+if (!g.__outreachIngestGrantsRegistered) {
+  g.__outreachIngestGrantsRegistered = true;
+
+  const ingestGrants = async (_scheduledTime: Date, _startedAt: Date) => {
+    try {
+      await runIngestGrants();
+    } catch (err) {
+      console.error('[ingest-grants] pass failed:', err);
+      throw err;
+    }
+  };
+
+  // Must be registered as BOTH a workflow and a scheduled function,
+  // referencing the same function object — see module doc comment.
+  DBOS.registerWorkflow(ingestGrants, { name: 'ingestGrants' });
+  DBOS.registerScheduled(ingestGrants, {
+    crontab: '0 3 * * *',
+    name: 'ingestGrants',
+    mode: SchedulerMode.ExactlyOncePerInterval,
+  });
+}