The aidran package, end to end.

3 · contracts — types & schemas

Everything under @aidran/contracts is re-exported. Zod schemas suffixed *Schema parse runtime payloads; inferred TS types share the base name.

4 · db — Drizzle ORM

Tables grouped by service-boundary ownership. AIDRAN's discipline: services do not import from one another; they read shared schemas from @aidran/db and write only to their owned tables.

• A

  Records

  Ingestion team writes
  aidran/db (schema/records.ts)
  • · sources — source adapters and ingest cursors
  • · records — every ingested document, link, post, paper
  • · sourceKindEnum · recordCategoryEnum · contentTypeEnum
• B

  Analysis

  Analysis team writes
  aidran/db (schema/analysis.ts)
  • · entities · entityMentions
  • · topics · topicAssignments
  • · embeddings · analysisCursors
• C

  Signals

  Signal team writes
  aidran/db (schema/signals.ts)
  • · signals — novelty / velocity / divergence detections
  • · signalEvidence — joined records that justified each signal
  • · signalSeverityEnum · evidenceTargetEnum
• D

  Editorial

  Editorial team writes
  aidran/db (schema/editorial.ts)
  • · stories · storyCitations · storyReferences
  • · storyContentVariants · storyRelated
  • · storyArcs · storyArcMembership
  • · seoMetadata
  • · storyTypeEnum · arcStatusEnum · citationTypeEnum
• E

  Search-sync

  Search-sync team writes
  aidran/db (schema/search-sync.ts)
  • · searchSyncCheckpoints — per-target index sync watermarks

5 · Common workflows

Three load-bearing patterns. Validate an inbound event at the boundary; query the corpus through Drizzle; apply migrations programmatically when the CLI isn't in your runtime.

import { RecordIngestedSchema } from 'aidran/contracts';
 
// Validate at the boundary — anything that survives parse() is typed.
const event = RecordIngestedSchema.parse(payload);
 
// event: { recordId, kind, contentType, externalId, capturedAt }
//   - kind narrowed to a SourceKind union
//   - capturedAt typed as an ISO datetime string

import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';
import * as schema from 'aidran/db';
import { type Database } from 'aidran/db';
 
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const db: Database = drizzle(pool, { schema });
 
// Pull the 50 most recent records, typed end to end.
const rows = await db
  .select()
  .from(schema.records)
  .orderBy(schema.records.capturedAt)
  .limit(50);

import { drizzle } from 'drizzle-orm/node-postgres';
import { migrate } from 'drizzle-orm/node-postgres/migrator';
import { Pool } from 'pg';
import { migrationsFolder } from 'aidran/db/migrations-path';
 
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
await migrate(drizzle(pool), { migrationsFolder });