@tangen/db 0.0.0-stage → 0.1.54

package/src/schema/saved-views.ts

@@ -0,0 +1,33 @@
+/**
+ * File Name: saved-views.ts
+ * Purpose: Defines the `saved_views` table, which persists named filter presets
+ *   for content-type list views in the admin UI.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: drizzle-orm/pg-core; visibility controls whether a view is
+ *   private to its creator or shared across the workspace.
+ */
+import { pgTable, text, timestamp, jsonb, index } from 'drizzle-orm/pg-core'
+import { sql } from 'drizzle-orm'
+
+/**
+ * Stores a named, reusable filter configuration for a specific content type's list
+ * view, optionally shared with other workspace members.
+ */
+export const savedViews = pgTable('saved_views', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull(),
+  typeName: text('type_name').notNull(),
+  name: text('name').notNull(),
+  /** Serialised FilterState — status, search, dateFilters, fieldFilters */
+  filters: jsonb('filters').notNull().default(sql`'{}'`),
+  /** 'private' = only creator sees it; 'shared' = all workspace members see it */
+  visibility: text('visibility').notNull().default('private'),
+  createdBy: text('created_by').notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  workspaceIdx: index('saved_views_workspace_idx').on(t.workspaceId),
+}))

package/src/schema/schema-pushes.ts

@@ -0,0 +1,43 @@
+/**
+ * File Name: schema-pushes.ts
+ * Purpose: The per-environment push ledger: one row per `tangen push` that
+ *          reached the apply phase - started, finished, status (running /
+ *          applied / failed), the git sha and CLI version that ran it, the
+ *          plan and statements it applied, and the error when it failed.
+ *          `/api/v1/types/health`, the Schema Builder banner and `tangen
+ *          doctor` read the last row to say whether the last push finished.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: drizzle-orm/pg-core. Migration 0032 and the
+ *          ensure-system-schema guard create it; 0042 adds `checksum`.
+ *          `--plan` never writes here; a row left at `running` means the
+ *          process died mid-push.
+ */
+import { pgTable, text, timestamp, jsonb, index } from 'drizzle-orm/pg-core'
+import { sql } from 'drizzle-orm'
+
+export const schemaPushes = pgTable('schema_pushes', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull(),
+  startedAt: timestamp('started_at', { withTimezone: true }).notNull().defaultNow(),
+  finishedAt: timestamp('finished_at', { withTimezone: true }),
+  /** running | applied | failed */
+  status: text('status').notNull().default('running'),
+  gitSha: text('git_sha'),
+  cliVersion: text('cli_version'),
+  /** The content plan (planToJson shape) this push applied. */
+  planJson: jsonb('plan_json').notNull().default(sql`'{}'`),
+  /** The migration statements this push executed, in order. */
+  statementsJson: jsonb('statements_json').notNull().default(sql`'[]'`),
+  error: text('error'),
+  /**
+   * sha256 of the canonical plan summary and the ordered statement SQL
+   * (migration 0042). The next push re-fingerprints every row and refuses
+   * when one disagrees; NULL marks a row written before checksums existed.
+   */
+  checksum: text('checksum'),
+}, (t) => ({
+  startedIdx: index('schema_pushes_started_idx').on(t.startedAt),
+}))

package/src/schema/search-documents.ts

@@ -0,0 +1,47 @@
+/**
+ * File Name: search-documents.ts
+ * Purpose: The content-search index, held in PostgreSQL rather than in the
+ *   application process.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Identity is (workspace, environment, source, type,
+ *   object, LOCALE). The locale is part of it because `cfg` - the text-search
+ *   configuration - is per row: a French document must be stemmed and queried
+ *   as French, and one row holding every translation could only be stemmed once.
+ *
+ *   `search_vector` is a GENERATED column (migration 0038) computed from `cfg`,
+ *   so it is deliberately absent here: nothing writes it, and typing it would
+ *   invite something to try. `cfg` is `regconfig` in the database and is only
+ *   ever written through the engine's raw upsert, which casts explicitly.
+ */
+import { pgTable, text, boolean, jsonb, timestamp, primaryKey, index } from 'drizzle-orm/pg-core'
+
+export const searchDocuments = pgTable('search_documents', {
+  workspaceId: text('workspace_id').notNull(),
+  /** 'content' | 'media' | 'ext:<extensionId>:<sourceId>' - and the unit of uninstall. */
+  source: text('source').notNull(),
+  typeSlug: text('type_slug').notNull(),
+  objectId: text('object_id').notNull(),
+  /** '' for content that is not localized. Part of the identity, never a filter afterthought. */
+  locale: text('locale').notNull().default(''),
+  /** PostgreSQL text-search configuration name; `simple` is the honest fallback. */
+  cfg: text('cfg').notNull().default('simple'),
+  title: text('title').notNull().default(''),
+  slug: text('slug'),
+  body: text('body').notNull().default(''),
+  /** Bounded snippet source - ts_headline is linear in the text handed to it. */
+  excerpt: text('excerpt').notNull().default(''),
+  status: text('status').notNull().default('draft'),
+  isPublished: boolean('is_published').notNull().default(false),
+  metadata: jsonb('metadata').notNull().default({}),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  pk: primaryKey({ columns: [t.workspaceId, t.source, t.typeSlug, t.objectId, t.locale] }),
+  slugIdx: index('search_documents_slug').on(t.workspaceId, t.slug),
+  scopeIdx: index('search_documents_scope').on(t.workspaceId, t.isPublished, t.typeSlug),
+  objectIdx: index('search_documents_object').on(t.workspaceId, t.source, t.objectId),
+}))
+
+export type SearchDocumentRow = typeof searchDocuments.$inferSelect

package/src/schema/search-query-log.ts

@@ -0,0 +1,24 @@
+/**
+ * File Name: search-query-log.ts
+ * Purpose: Search analytics — one row per search query (Admin or Site Search),
+ *   for the Settings → Search dashboards (top searches, zero-result, volume).
+ *   NO PII: the term + result count + audience + timestamp only. Rows are purged
+ *   past the workspace's retention window (hard-capped at 90 days).
+ *
+ * Author: Raghunath J
+ * License: MIT
+ */
+import { pgTable, text, integer, timestamp, index } from 'drizzle-orm/pg-core'
+
+export const searchQueryLog = pgTable('search_query_log', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull(),
+  /** 'internal' (Admin Search) or 'public' (Site Search). */
+  audience: text('audience').notNull(),
+  /** The query term. No PII beyond what the user typed. */
+  term: text('term').notNull(),
+  resultCount: integer('result_count').notNull().default(0),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  byWorkspace: index('search_query_log_ws_idx').on(t.workspaceId, t.createdAt),
+}))

package/src/schema/search-recommendations.ts

@@ -0,0 +1,27 @@
+/**
+ * File Name: search-recommendations.ts
+ * Purpose: Marketing-managed query curation ("query rules", Settings → Search).
+ *   For a query (exact or pattern), pin results to the top, and/or hide results.
+ *   Applied at query time after the providers run.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ */
+import { pgTable, text, jsonb, timestamp, index } from 'drizzle-orm/pg-core'
+
+export const searchRecommendations = pgTable('search_recommendations', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull(),
+  /** The query this rule applies to (matched case-insensitively). */
+  query: text('query').notNull(),
+  /** Result ids (or urls) to pin to the top, in order (string[]). */
+  pins: jsonb('pins').notNull().default([]),
+  /** Result ids (or urls) to remove from results (string[]). */
+  hides: jsonb('hides').notNull().default([]),
+  /** Optional audience scope: 'internal' | 'public' | null (both). */
+  audience: text('audience'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  byWorkspace: index('search_recommendations_ws_idx').on(t.workspaceId),
+}))

package/src/schema/search-synonyms.ts

@@ -0,0 +1,23 @@
+/**
+ * File Name: search-synonyms.ts
+ * Purpose: Marketing-managed synonym groups (Settings → Search). A group is a set
+ *   of interchangeable terms ("laptop", "notebook"); a query matching any term is
+ *   expanded to match the others. Applied at query time in the search pipeline.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ */
+import { pgTable, text, jsonb, timestamp, index } from 'drizzle-orm/pg-core'
+
+export const searchSynonyms = pgTable('search_synonyms', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull(),
+  /** Human title for the group (e.g. "Footwear"), so marketing knows its purpose. */
+  label: text('label'),
+  /** Interchangeable terms in this group (string[]). */
+  terms: jsonb('terms').notNull().default([]),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  byWorkspace: index('search_synonyms_ws_idx').on(t.workspaceId),
+}))

package/src/schema/webhook-deliveries.ts

@@ -0,0 +1,37 @@
+/**
+ * File Name: webhook-deliveries.ts
+ * Purpose: Defines the `webhook_deliveries` table, which records individual outbound
+ *   HTTP delivery attempts for webhook events including response details and success status.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: drizzle-orm/pg-core; rows are append-only delivery receipts — one row
+ *   per attempt, including retries.
+ */
+import { pgTable, text, timestamp, jsonb, boolean, integer, index } from 'drizzle-orm/pg-core'
+
+/**
+ * Records a single outbound webhook delivery attempt, capturing the event payload sent,
+ * the HTTP response code and body received, latency, and whether the delivery succeeded.
+ */
+export const webhookDeliveries = pgTable('webhook_deliveries', {
+  id: text('id').primaryKey(),
+  webhookId: text('webhook_id').notNull(),
+  workspaceId: text('workspace_id').notNull(),
+  event: text('event').notNull(),
+  typeName: text('type_name').notNull(),
+  objectId: text('object_id').notNull(),
+  payload: jsonb('payload').notNull(),
+  statusCode: integer('status_code'),
+  responseBody: text('response_body'),
+  durationMs: integer('duration_ms'),
+  success: boolean('success').notNull(),
+  error: text('error'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  workspaceIdx: index('webhook_deliveries_workspace_idx').on(t.workspaceId),
+  webhookIdx: index('webhook_deliveries_webhook_idx').on(t.webhookId),
+  /** Retention: the purge scans by workspace and age (migration 0044). */
+  retentionIdx: index('webhook_deliveries_retention_idx').on(t.workspaceId, t.createdAt),
+}))

package/src/schema/webhooks.ts

@@ -0,0 +1,36 @@
+/**
+ * File Name: webhooks.ts
+ * Purpose: Defines the `webhooks` table, which stores registered outbound webhook
+ *   endpoints including their subscribed events, signing secret, and auto-pause state.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: drizzle-orm/pg-core; consecutiveFailures drives auto-pause logic
+ *   in the webhook dispatcher.
+ */
+import { pgTable, text, timestamp, jsonb, boolean, integer, index } from 'drizzle-orm/pg-core'
+import { sql } from 'drizzle-orm'
+
+/**
+ * Stores a webhook registration for a workspace environment, including the target URL,
+ * optional HMAC signing secret, subscribed event types, custom headers, and auto-pause
+ * state based on consecutive delivery failures.
+ */
+export const webhooks = pgTable('webhooks', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull(),
+  label: text('label').notNull(),
+  url: text('url').notNull(),
+  secret: text('secret'),
+  events: text('events').array().notNull().default(sql`'{}'`),
+  typeNames: text('type_names').array().notNull().default(sql`'{}'`),
+  enabled: boolean('enabled').notNull().default(true),
+  headers: jsonb('headers').notNull().default(sql`'{}'`),
+  consecutiveFailures: integer('consecutive_failures').notNull().default(0),
+  pausedReason: text('paused_reason'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  workspaceIdx: index('webhooks_workspace_idx').on(t.workspaceId),
+}))

package/src/schema/workspace-activity.ts

@@ -0,0 +1,35 @@
+/**
+ * File Name: workspace-activity.ts
+ * Purpose: Defines the `workspace_activity` table, which is an append-only audit log
+ *   recording significant actions taken by members or API keys across a workspace.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: drizzle-orm/pg-core; actor and object fields are denormalized at
+ *   write time so the log remains readable even after records are deleted.
+ */
+import { pgTable, text, timestamp, index } from 'drizzle-orm/pg-core'
+
+/**
+ * Append-only audit log entry capturing who did what, on which object, via which
+ * interface (admin, REST, GraphQL, SDK) within a workspace or environment.
+ */
+export const workspaceActivity = pgTable('workspace_activity', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull(),
+  category: text('category').notNull(),      // 'content' | 'schema' | 'members' | 'webhooks' | 'api-keys' | 'media'
+  action: text('action').notNull(),          // 'created' | 'published' | 'unpublished' | 'deleted' | 'scheduled' | 'pushed' | 'invited' | 'revoked' | 'uploaded' | 'updated'
+  actorId: text('actor_id'),
+  actorName: text('actor_name'),             // denormalized at write time
+  actorType: text('actor_type'),             // 'member' | 'api_key'
+  source: text('source').notNull().default('admin'),  // 'admin' | 'rest' | 'graphql' | 'sdk'
+  typeName: text('type_name'),               // content type slug, e.g. 'post'
+  objectId: text('object_id'),
+  objectTitle: text('object_title'),
+  targetLabel: text('target_label'),         // human label: webhook name, member email, api key label
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  idxWorkspaceCreated: index('workspace_activity_workspace_created').on(t.workspaceId, t.createdAt),
+  idxCreated: index('workspace_activity_created').on(t.createdAt),
+}))

package/src/schema/workspace-domains.ts

@@ -0,0 +1,24 @@
+/**
+ * File Name: workspace-domains.ts
+ * Purpose: Defines the `workspace_domains` table, which maps verified custom domains
+ *   to their owning workspace for tenant-aware routing.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: drizzle-orm/pg-core; domain column has a unique constraint — one
+ *   domain cannot be claimed by multiple workspaces.
+ */
+import { pgTable, text, timestamp } from 'drizzle-orm/pg-core'
+import { workspaces } from './workspaces'
+
+/**
+ * Associates a verified custom domain with a workspace, enabling domain-based tenant
+ * resolution for the API and delivery layer.
+ */
+export const workspaceDomains = pgTable('workspace_domains', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull().references(() => workspaces.id, { onDelete: 'cascade' }),
+  domain: text('domain').notNull().unique(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+})

package/src/schema/workspace-installed-apps.ts

@@ -0,0 +1,48 @@
+/**
+ * File Name: workspace-installed-apps.ts
+ * Purpose: The extension installation state, one row per workspace x
+ *          environment x extension (closure plan Phase 4, Unit 1): whether
+ *          it is installed or retired, enabled, at which version, and when
+ *          it was installed, upgraded or uninstalled. The row is the INSTALL
+ *          / ENABLE / UPGRADE / UNINSTALL truth; the runtime registry reads
+ *          it, never a second source.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Migration 0045 adds the environment scope and adopts
+ *          the workspace-wide rows that existed before it: one row per
+ *          environment of the workspace (from `environments`), enabled,
+ *          version unknown until the first boot records the manifest's.
+ *          `state` is `installed` or `uninstalled`; an uninstalled row is
+ *          the tombstone that keeps retained extension data diagnosable and
+ *          lets a reinstall adopt it. Uniqueness is (workspace, env, app).
+ */
+import { pgTable, text, timestamp, jsonb, boolean, uniqueIndex } from 'drizzle-orm/pg-core'
+import { sql } from 'drizzle-orm'
+
+export const workspaceInstalledApps = pgTable(
+  'workspace_installed_apps',
+  {
+    id: text('id').primaryKey(),
+    workspaceId: text('workspace_id').notNull(),
+    /** The environment this installation belongs to (`env_<slug>`). */
+    appId: text('app_id').notNull(),
+    options: jsonb('options').notNull().default(sql`'{}'`),
+    /** `installed` | `uninstalled` (retired; data retained, diagnosable, adoptable). */
+    state: text('state').notNull().default('installed'),
+    /** ENABLE: may contribute active behaviour in this environment. */
+    enabled: boolean('enabled').notNull().default(true),
+    /** The extension version this installation runs; null until recorded. */
+    version: text('version'),
+    installedAt: timestamp('installed_at', { withTimezone: true }).notNull().defaultNow(),
+    installedBy: text('installed_by'),
+    upgradedAt: timestamp('upgraded_at', { withTimezone: true }),
+    uninstalledAt: timestamp('uninstalled_at', { withTimezone: true }),
+    /** K5.2a: the grants an operator approved (JSON array); NULL = not reviewed, the manifest's required grants apply. */
+    grantedGrants: jsonb('granted_grants'),
+  },
+  (t) => ({
+    uniqueWorkspaceApp: uniqueIndex('workspace_installed_apps_ws_app_unique').on(t.workspaceId, t.appId),
+  }),
+)

package/src/schema/workspaces.ts

@@ -0,0 +1,24 @@
+/**
+ * File Name: workspaces.ts
+ * Purpose: Defines the `workspaces` table, the top-level multi-tenant boundary; every
+ *   other resource in the platform is scoped to a workspace.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: drizzle-orm/pg-core; soft-delete via deletedAt — rows with a
+ *   non-null deletedAt are treated as decommissioned workspaces.
+ */
+import { pgTable, text, timestamp } from 'drizzle-orm/pg-core'
+
+/**
+ * Top-level tenant record representing a single organization or project space;
+ * all environments, members, API keys, and content types belong to a workspace.
+ */
+export const workspaces = pgTable('workspaces', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  slug: text('slug').notNull().unique(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  deletedAt: timestamp('deleted_at', { withTimezone: true }),
+})

package/src/schema-kit.ts

@@ -0,0 +1,64 @@
+/**
+ * File Name: schema-kit.ts
+ * Purpose: Re-exports the drizzle-orm/pg-core primitives used by generated
+ *          content-tables.ts / custom-tables.ts. The generated files import from
+ *          HERE (@tangen/db, a top-level project dep) instead of drizzle-orm
+ *          directly — because drizzle-orm is a NESTED transitive dep and isn't
+ *          resolvable from a consumer project's app/generated/ location.
+ *          Also home of customTablePg() — the SINGLE col.kind → drizzle-column
+ *          mapping for custom tables, used by both the generated registry file
+ *          and the API's build-from-definition fallback.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ */
+import { pgTable, text, numeric, boolean, timestamp, jsonb } from 'drizzle-orm/pg-core'
+
+export { pgTable, text, numeric, boolean, timestamp, jsonb, index, uniqueIndex, primaryKey } from 'drizzle-orm/pg-core'
+export { sql } from 'drizzle-orm'
+
+// Structural mirror of @tangen/types' ColumnDefinition / CustomTableDefinition —
+// declared locally so @tangen/db takes no dependency on @tangen/types.
+export interface CustomTableColumnDef {
+  kind: 'text' | 'number' | 'boolean' | 'json' | 'timestamp'
+  nullable?: boolean
+  defaultValue?: unknown
+  defaultNow?: boolean
+}
+
+export interface CustomTablePgDef {
+  name: string
+  columns: Record<string, CustomTableColumnDef>
+}
+
+function columnFor(name: string, def: CustomTableColumnDef) {
+  switch (def.kind) {
+    case 'number':    return numeric(name)
+    case 'boolean':   return boolean(name)
+    case 'json':      return jsonb(name)
+    case 'timestamp': return timestamp(name, { withTimezone: true })
+    case 'text':
+    default:          return text(name)
+  }
+}
+
+/**
+ * Build the Drizzle pgTable for a custom-table definition. JS keys are the
+ * EXACT column names (workspace_id, not workspaceId) so drizzle select() rows
+ * are byte-identical to the raw `SELECT *` rows the old SQL path returned.
+ * DDL stays owned by the CLI's custom-table-migration (this object is the
+ * query/execution layer only, so column defaults are not re-declared here).
+ */
+export function customTablePg(def: CustomTablePgDef) {
+  // Builders are heterogeneous (text/numeric/boolean/…): keep the record loose;
+  // callers consume the table as an untyped registry entry anyway.
+  const cols: Record<string, any> = {
+    id: text('id').primaryKey().notNull(),
+    workspace_id: text('workspace_id').notNull(),
+  }
+  for (const [colName, colDef] of Object.entries(def.columns ?? {})) {
+    const col = columnFor(colName, colDef)
+    cols[colName] = colDef.nullable === false ? col.notNull() : col
+  }
+  return pgTable(def.name, cols)
+}

package/src/sealed.ts

@@ -0,0 +1,84 @@
+/**
+ * File Name: sealed.ts
+ * Purpose: Secrets at rest for connections (Extension Kernel K6.1/K6.3,
+ *          tasks/plan-extension-kernel.md): an AES-256-GCM envelope under a
+ *          key derived from the deployment's connections key material. The
+ *          database holds `v1.<iv>.<tag>.<ciphertext>` and never plaintext;
+ *          a different key or a tampered byte fails to open. Lives in
+ *          @tangen/db so the API (which seals and opens) and the CLI (which
+ *          rotates the key and diagnoses unreadable rows) share ONE
+ *          envelope. Pure over node:crypto and a SQL executor.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: One key per deployment (`connections.encryptionKey`,
+ *          `TANGEN_CONNECTIONS_KEY`, else derived from the member session
+ *          secret). Rotation re-seals every row under the new key; a row
+ *          neither key opens is reported, never dropped.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto'
+
+export type SealedKey = Buffer & { readonly __sealedKey: true }
+
+type SqlExec = (text: string, params?: unknown[]) => Promise<Array<Record<string, unknown>>>
+
+/** A 32-byte key from any key material (a passphrase, a base64 blob): sha256, so a short or long secret both work. */
+export function deriveConnectionsKey(material: string): SealedKey {
+  if (!material || material.length < 8) throw new Error('The connections key material must be at least 8 characters')
+  return createHash('sha256').update(`tangen.connections.v1:${material}`).digest() as SealedKey
+}
+
+/** `v1.<iv>.<tag>.<ciphertext>`, base64url; a fresh iv every call. */
+export function sealSecret(key: SealedKey, value: unknown): string {
+  const iv = randomBytes(12)
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+  const data = Buffer.concat([cipher.update(JSON.stringify(value), 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  return `v1.${iv.toString('base64url')}.${tag.toString('base64url')}.${data.toString('base64url')}`
+}
+
+/** The value back, or a throw: wrong key, tampered envelope, unknown version. */
+export function openSecret<T = unknown>(key: SealedKey, sealed: string): T {
+  const [version, iv, tag, data] = sealed.split('.')
+  if (version !== 'v1' || !iv || !tag || !data) throw new Error('Not a sealed secret this platform understands')
+  const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'base64url'))
+  decipher.setAuthTag(Buffer.from(tag, 'base64url'))
+  const plain = Buffer.concat([decipher.update(Buffer.from(data, 'base64url')), decipher.final()])
+  return JSON.parse(plain.toString('utf8')) as T
+}
+
+function opens(key: SealedKey, sealed: unknown): boolean {
+  try { openSecret(key, String(sealed)); return true } catch { return false }
+}
+
+export interface UnreadableConnection { id: string; workspaceId: string; connectorId: string; label: string }
+
+/** The connection rows, every workspace, that this key cannot open - what Doctor names as CONNECTION_UNREADABLE. */
+export async function unreadableConnections(exec: SqlExec, key: SealedKey): Promise<UnreadableConnection[]> {
+  const rows = await exec(`SELECT id, workspace_id, connector_id, label, secret FROM connections ORDER BY workspace_id, created_at`)
+  return rows
+    .filter((r) => !opens(key, r.secret))
+    .map((r) => ({ id: String(r.id), workspaceId: String(r.workspace_id), connectorId: String(r.connector_id), label: String(r.label) }))
+}
+
+/**
+ * Re-seals every row the old key opens under the new key, every workspace,
+ * one row at a time (a row is either re-sealed or untouched, never half).
+ * Rows neither key opens are returned by id and left as they are; a row the
+ * NEW key already opens is skipped, so running twice is safe.
+ */
+export async function rotateConnectionsKey(exec: SqlExec, keys: { from: SealedKey; to: SealedKey }): Promise<{ resealed: number; unreadable: string[] }> {
+  const rows = await exec(`SELECT id, secret FROM connections ORDER BY created_at`)
+  let resealed = 0
+  const unreadable: string[] = []
+  for (const r of rows) {
+    const sealed = String(r.secret)
+    if (opens(keys.to, sealed)) continue
+    let value: unknown
+    try { value = openSecret(keys.from, sealed) } catch { unreadable.push(String(r.id)); continue }
+    await exec(`UPDATE connections SET secret = $2, updated_at = now() WHERE id = $1`, [r.id, sealSecret(keys.to, value)])
+    resealed++
+  }
+  return { resealed, unreadable }
+}

package/src/seed/skeleton.ts

@@ -0,0 +1,77 @@
+/**
+ * File Name: skeleton.ts
+ * Purpose: Seeds the minimum set of records required to run the platform locally —
+ *   a workspace, an admin member, and a full-access API key.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Requires Bun runtime for password hashing (Bun.password.hash with
+ *   argon2id). Run directly with `bun packages/db/src/seed/skeleton.ts` or import
+ *   `seedSkeleton` programmatically. DATABASE_URL must be set in the environment.
+ */
+import { createHash } from 'node:crypto'
+import { createDb } from '../client'
+import { workspaces, members, apiKeys } from '../schema'
+
+/** Stable ID for the local-dev workspace inserted by this seed. */
+export const SEED_WORKSPACE_ID = 'wsp_local_dev'
+/** Email address of the seeded admin member; password is "password". */
+export const SEED_ADMIN_EMAIL = 'admin@example.com'
+/** Stable member ID for the seeded admin user. */
+export const SEED_ADMIN_MEMBER_ID = 'mem_seed_admin_001'
+/** Stable API key record ID for the seeded full-access key. */
+export const SEED_API_KEY_ID = 'key_seed_admin_001'
+/** Raw (unhashed) value of the local-dev API key — never use in production. */
+export const SEED_RAW_API_KEY = 'tgn_dev_seed_local_dev_0000001'
+/** First 12 characters of the raw key, stored in the DB for display purposes. */
+export const SEED_API_KEY_PREFIX = SEED_RAW_API_KEY.slice(0, 12)
+
+/**
+ * Inserts the minimal skeleton records needed to run the platform locally.
+ * All inserts use `onConflictDoNothing` so the function is safe to call repeatedly.
+ * @param db - Drizzle database client returned by `createDb`
+ */
+export async function seedSkeleton(db: ReturnType<typeof createDb>) {
+  await db.insert(workspaces).values({
+    id: SEED_WORKSPACE_ID,
+    name: 'Local Dev',
+    slug: 'local-dev',
+  }).onConflictDoNothing()
+  console.log(`✓ workspace    ${SEED_WORKSPACE_ID}`)
+
+  const passwordHash = await Bun.password.hash('password', {
+    algorithm: 'argon2id',
+    memoryCost: 19456,
+    timeCost: 2,
+  })
+  await db.insert(members).values({
+    id: SEED_ADMIN_MEMBER_ID,
+    workspaceId: SEED_WORKSPACE_ID,
+    email: SEED_ADMIN_EMAIL,
+    name: 'Admin',
+    passwordHash,
+    role: 'admin',
+  }).onConflictDoNothing()
+  console.log(`✓ member       ${SEED_ADMIN_EMAIL}  role=admin  password=password`)
+
+  const keyHash = createHash('sha256').update(SEED_RAW_API_KEY).digest('hex')
+  await db.insert(apiKeys).values({
+    id: SEED_API_KEY_ID,
+    workspaceId: SEED_WORKSPACE_ID,
+    label: 'Local dev seed key (full-access)',
+    keyPrefix: SEED_API_KEY_PREFIX,
+    keyHash,
+    permissions: { admin: true },
+  }).onConflictDoNothing()
+  console.log(`✓ api_key      ${SEED_API_KEY_PREFIX}...  (full-access)`)
+  console.log(`  raw key: ${SEED_RAW_API_KEY}`)
+}
+
+if (import.meta.main) {
+  const url = process.env.DATABASE_URL
+  if (!url) throw new Error('DATABASE_URL is not set')
+  const db = createDb(url)
+  await seedSkeleton(db)
+  process.exit(0)
+}