@fabrika/platform-node 0.2.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/platform-node",
-	"version": "0.2.0",
+	"version": "0.3.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -32,6 +32,6 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/platform": "^0.2.0"
+		"@fabrika/platform": "^0.3.2"
 	}
 }

package/src/index.ts

@@ -20,14 +20,19 @@
 
 export { FileSystemAssetServer, type FileSystemAssetServerOptions } from './asset-server-fs'
 export { S3BlobStore, type S3BlobStoreOptions } from './blob-s3'
-export { type Job, PostgresJobConsumer, type PostgresJobConsumerOptions, PostgresJobQueue, type PostgresJobQueueOptions } from './job-queue-postgres'
+export {
+	decodeJob,
+	type Job,
+	PostgresJobConsumer,
+	type PostgresJobConsumerOptions,
+	PostgresJobQueue,
+	type PostgresJobQueueOptions,
+} from './job-queue-postgres'
 export { rewritePlaceholders, type RewrittenSql } from './placeholders'
 export {
 	applyPostgresMigrations,
 	definePostgresMigrationPlan,
 	platformNodePostgresMigrationBundle,
-	type PostgresLegacyMigrationEffect,
-	type PostgresLegacyMigrationLedger,
 	type PostgresMigration,
 	type PostgresMigrationBundle,
 	postgresMigrationFilenames,
@@ -43,5 +48,4 @@ export {
 	type PostgresServiceMigrationsConfig,
 } from './service-postgres-migrations'
 export { PostgresDatabase, PostgresStatement, type SqlBindValue } from './sql-postgres'
-export { uuidv7 } from './uuid'
 export { type BackgroundTasks, type BackgroundTasksOptions, createBackgroundTasks } from './wait-until'

package/src/job-queue-postgres.ts

@@ -25,10 +25,9 @@
 // `FOR UPDATE SKIP LOCKED` is the one Postgres-specific statement in this package; the DDL itself
 // (migrations/0001_jobs.sql) is in the SQLite ∩ Postgres common subset.
 
-import type { JobQueue, SqlDatabase } from '@fabrika/platform'
-import { uuidv7 } from './uuid'
+import { type JobQueue, type SqlDatabase, uuidv7 } from '@fabrika/platform'
 
-/** A claimed job, as handed to a handler. `payload` has been through the caller's `decode`. */
+/** A claimed delivery. Raw claims carry stored JSON text; typed claims carry the caller's decoded payload. */
 export interface Job<T> {
 	id: string
 	payload: T
@@ -38,6 +37,12 @@ export interface Job<T> {
 	maxAttempts: number
 }
 
+/** Parse and narrow one stored delivery without losing its settlement metadata. */
+export function decodeJob<T>(job: Job<string>, decode: (payload: unknown) => T): Job<T> {
+	const parsed: unknown = JSON.parse(job.payload)
+	return { ...job, payload: decode(parsed) }
+}
+
 export interface PostgresJobQueueOptions {
 	/** Table holding the jobs. Must already exist; see migrations/0001_jobs.sql. */
 	table?: string
@@ -121,6 +126,12 @@ export class PostgresJobQueue<T> implements JobQueue<T> {
 	 * than reaching a handler that assumes a shape.
 	 */
 	async claim(options: { limit: number; visibilityTimeoutMs: number; decode: (payload: unknown) => T }): Promise<Job<T>[]> {
+		const jobs = await this.claimRaw(options)
+		return jobs.map((job) => decodeJob(job, options.decode))
+	}
+
+	/** Claim stored JSON text so consumers can decode and settle each delivery independently. */
+	async claimRaw(options: { limit: number; visibilityTimeoutMs: number }): Promise<Job<string>[]> {
 		const now = this.now()
 		const { results } = await this.db
 			.prepare(this.claimSql)
@@ -131,10 +142,7 @@ export class PostgresJobQueue<T> implements JobQueue<T> {
 		// restores enqueue order, because ids are monotonic UUIDv7 and therefore strictly time-ordered.
 		return results
 			.sort((left, right) => (left.id < right.id ? -1 : 1))
-			.map((row) => {
-				const parsed: unknown = JSON.parse(row.payload)
-				return { id: row.id, payload: options.decode(parsed), attempts: row.attempts, maxAttempts: row.max_attempts }
-			})
+			.map((row) => ({ id: row.id, payload: row.payload, attempts: row.attempts, maxAttempts: row.max_attempts }))
 	}
 
 	/** The job is done (or permanently abandoned) — drop the row. Idempotent. */
@@ -149,7 +157,7 @@ export class PostgresJobQueue<T> implements JobQueue<T> {
 }
 
 export interface PostgresJobConsumerOptions<T> {
-	/** Narrow the stored JSON to the message type. Throwing here abandons the job as undecodable. */
+	/** Narrow the stored JSON to the message type. Invalid deliveries retry until their budget is spent. */
 	decode: (payload: unknown) => T
 	/** Handle one job. A throw schedules a retry until `maxAttempts` is spent. */
 	handler: (job: Job<T>) => Promise<void>
@@ -196,23 +204,26 @@ export class PostgresJobConsumer<T> {
 			visibilityTimeoutMs: options.visibilityTimeoutMs ?? DEFAULT_VISIBILITY_TIMEOUT_MS,
 			retryDelayMs: options.retryDelayMs ?? ((attempts) => Math.min(60_000, 1_000 * 2 ** attempts)),
 		}
-		this.onError = options.onError ?? ((error) => {
-			console.error('job handler failed:', error instanceof Error ? error.message : 'unknown error')
+		this.onError = options.onError ?? (() => {
+			console.error('job handler failed')
 		})
 		this.onAbandoned = options.onAbandoned ?? ((job) => {
 			console.warn(`job ${job.id} abandoned after ${job.attempts} attempt(s)`)
 		})
 	}
 
-	/** Run one pass. Returns how many jobs were handled — 0 means the queue was empty. Exposed for tests. */
+	/** Run one pass. Returns the raw claimed count, including invalid deliveries. Exposed for tests. */
 	async poll(): Promise<number> {
-		const jobs = await this.queue.claim({
+		const jobs = await this.queue.claimRaw({
 			limit: this.options.batchSize,
 			visibilityTimeoutMs: this.options.visibilityTimeoutMs,
-			decode: this.options.decode,
 		})
 		for (const job of jobs) {
-			await this.handle(job)
+			try {
+				await this.handleRaw(job)
+			} catch {
+				console.error('job settlement failed')
+			}
 		}
 		return jobs.length
 	}
@@ -249,19 +260,34 @@ export class PostgresJobConsumer<T> {
 		let handled = 0
 		try {
 			handled = await this.poll()
-		} catch (error) {
+		} catch {
 			// A claim failure is usually the database being unreachable — log short and back off.
-			console.error('job poll failed:', error instanceof Error ? error.message : 'unknown error')
+			console.error('job poll failed')
 		}
 		if (this.running) {
 			this.schedule(handled > 0 ? 0 : this.options.pollIntervalMs)
 		}
 	}
 
+	private async handleRaw(raw: Job<string>): Promise<void> {
+		let job: Job<T>
+		try {
+			job = decodeJob(raw, this.options.decode)
+		} catch {
+			if (raw.attempts >= raw.maxAttempts) {
+				await this.queue.ack(raw.id)
+				console.warn('undecodable job abandoned', { id: raw.id, attempts: raw.attempts, maxAttempts: raw.maxAttempts })
+			} else {
+				await this.queue.defer(raw.id, this.options.retryDelayMs(raw.attempts))
+			}
+			return
+		}
+		await this.handle(job)
+	}
+
 	private async handle(job: Job<T>): Promise<void> {
 		try {
 			await this.options.handler(job)
-			await this.queue.ack(job.id)
 		} catch (error) {
 			this.onError(error, job)
 			if (job.attempts >= job.maxAttempts) {
@@ -270,6 +296,8 @@ export class PostgresJobConsumer<T> {
 				return
 			}
 			await this.queue.defer(job.id, this.options.retryDelayMs(job.attempts))
+			return
 		}
+		await this.queue.ack(job.id)
 	}
 }

package/src/postgres-migrations.ts

@@ -1,4 +1,4 @@
-import type { SqlDatabase, SqlStatement } from '@fabrika/platform'
+import type { SqlDatabase } from '@fabrika/platform'
 import { readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
@@ -15,23 +15,6 @@ export interface PostgresMigration {
 export interface PostgresMigrationBundle {
 	name: string
 	migrations: readonly PostgresMigration[]
-	/** Only service-owned bundles may adopt matching entries from the old unqualified ledger. */
-	adoptLegacy?: boolean
-}
-
-export interface PostgresLegacyMigrationLedger {
-	/** Old filename-only ledger. */
-	table: string
-	/** Tables created atomically by this service's first migration. Every sentinel must exist. */
-	sentinelTables: readonly string[]
-	/** Extra effect probes for migrations whose filename could have collided in a shared old ledger. */
-	effects?: readonly PostgresLegacyMigrationEffect[]
-}
-
-export interface PostgresLegacyMigrationEffect {
-	migration: string
-	/** A parameterless SELECT returning one boolean column named `proven`. */
-	probeSql: string
 }
 
 export interface PostgresMigrationPlan {
@@ -40,14 +23,12 @@ export interface PostgresMigrationPlan {
 	/** Service-specific session advisory lock. Keep this stable across runner upgrades. */
 	lockKey: number
 	bundles: readonly PostgresMigrationBundle[]
-	legacy?: PostgresLegacyMigrationLedger
 }
 
 export interface ReadPostgresMigrationBundleOptions {
 	name: string
 	directory: string
 	files?: readonly string[]
-	adoptLegacy?: boolean
 }
 
 interface LedgerRow {
@@ -55,19 +36,6 @@ interface LedgerRow {
 	name: string
 }
 
-interface LegacyLedgerRow {
-	name: string
-	applied_at: number | string
-}
-
-interface PresenceRow {
-	present: boolean
-}
-
-interface ProvenRow {
-	proven: boolean
-}
-
 /** Read one ordered migration bundle from disk. An explicit file list fails closed when a file is absent. */
 export function readPostgresMigrationBundle(options: ReadPostgresMigrationBundleOptions): PostgresMigrationBundle {
 	validateBundleName(options.name)
@@ -88,7 +56,6 @@ export function readPostgresMigrationBundle(options: ReadPostgresMigrationBundle
 			name,
 			sql: readFileSync(join(options.directory, name), 'utf8'),
 		})),
-		...(options.adoptLegacy === true ? { adoptLegacy: true } : {}),
 	}
 	validateBundle(bundle)
 	return bundle
@@ -122,36 +89,6 @@ export function definePostgresMigrationPlan(plan: PostgresMigrationPlan): Postgr
 			identities.add(identity)
 		}
 	}
-	if (plan.legacy !== undefined) {
-		validateIdentifier(plan.legacy.table, 'legacy migration ledger table')
-		if (plan.legacy.sentinelTables.length === 0) {
-			throw new Error('Legacy migration adoption requires at least one service sentinel')
-		}
-		for (const sentinel of plan.legacy.sentinelTables) {
-			validateIdentifier(sentinel, 'legacy migration sentinel table')
-		}
-		const adoptingBundles = plan.bundles.filter((bundle) => bundle.adoptLegacy === true)
-		if (adoptingBundles.length !== 1) {
-			throw new Error('Legacy migration adoption requires exactly one adopting bundle')
-		}
-		const adoptable = new Set(
-			adoptingBundles.flatMap((bundle) => bundle.migrations.map((migration) => migration.name)),
-		)
-		const effectNames = new Set<string>()
-		for (const effect of plan.legacy.effects ?? []) {
-			validateMigrationName(effect.migration)
-			if (!adoptable.has(effect.migration)) {
-				throw new Error(`Legacy migration effect references non-adoptable migration ${effect.migration}`)
-			}
-			if (effectNames.has(effect.migration)) {
-				throw new Error(`Duplicate legacy migration effect ${effect.migration}`)
-			}
-			if (effect.probeSql.trim() === '') {
-				throw new Error(`Legacy migration effect ${effect.migration} is empty`)
-			}
-			effectNames.add(effect.migration)
-		}
-	}
 	return plan
 }
 
@@ -194,8 +131,6 @@ export async function applyPostgresMigrations(
 	const fresh: string[] = []
 	try {
 		await ensureLedger(db, plan.ledgerTable)
-		const beforeAdoption = await appliedIdentities(db, plan.ledgerTable)
-		if (beforeAdoption.size === 0) await adoptLegacyMigrations(db, plan)
 		const applied = await appliedIdentities(db, plan.ledgerTable)
 		for (const bundle of plan.bundles) {
 			for (const migration of bundle.migrations) {
@@ -272,84 +207,6 @@ async function appliedIdentities(db: SqlDatabase, ledgerTable: string): Promise<
 	return new Set(results.map((row) => postgresMigrationIdentity(row.bundle, row.name)))
 }
 
-async function adoptLegacyMigrations(db: SqlDatabase, plan: PostgresMigrationPlan): Promise<void> {
-	const legacy = plan.legacy
-	if (legacy === undefined) return
-	const sentinelStates = await Promise.all(legacy.sentinelTables.map((sentinel) => relationExists(db, sentinel)))
-	const presentSentinels = sentinelStates.filter(Boolean).length
-	if (presentSentinels === 0) return
-	if (presentSentinels !== sentinelStates.length) {
-		throw new Error('Legacy migration service sentinels are inconsistent')
-	}
-	if (!(await relationExists(db, legacy.table))) {
-		throw new Error('Legacy migration ledger is missing for an existing service schema')
-	}
-	for (const sentinel of legacy.sentinelTables) {
-		if (!(await relationExists(db, sentinel))) {
-			throw new Error('Legacy migration service sentinels changed during adoption')
-		}
-	}
-	const { results } = await db.prepare(`SELECT name, applied_at FROM ${legacy.table}`).all<LegacyLedgerRow>()
-	const legacyApplied = new Map(results.map((row) => [row.name, appliedAt(row.applied_at)]))
-	const adoptingBundle = plan.bundles.find((bundle) => bundle.adoptLegacy === true)
-	if (adoptingBundle === undefined) throw new Error('Legacy migration adopting bundle is missing')
-	const firstMigration = adoptingBundle.migrations[0]
-	if (firstMigration === undefined || !legacyApplied.has(firstMigration.name)) {
-		throw new Error(`Legacy migration ledger does not prove ${adoptingBundle.name}'s first migration`)
-	}
-	for (const effect of legacy.effects ?? []) {
-		if (!legacyApplied.has(effect.migration)) continue
-		const row = await db.prepare(effect.probeSql).first<ProvenRow>()
-		if (row === null || typeof row.proven !== 'boolean') {
-			throw new Error(`Legacy migration effect ${effect.migration} did not return a boolean proven column`)
-		}
-		if (!row.proven) {
-			throw new Error(`Legacy migration effect ${effect.migration} is missing`)
-		}
-	}
-	const statements: SqlStatement[] = []
-	for (const bundle of plan.bundles) {
-		if (bundle.adoptLegacy !== true) continue
-		for (const migration of bundle.migrations) {
-			const timestamp = legacyApplied.get(migration.name)
-			if (timestamp === undefined) continue
-			statements.push(
-				db
-					.prepare(`INSERT INTO ${plan.ledgerTable} (bundle, name, applied_at)
-						VALUES (?, ?, ?)
-						ON CONFLICT (bundle, name) DO NOTHING`)
-					.bind(
-						bundle.name,
-						migration.name,
-						timestamp,
-					),
-			)
-		}
-	}
-	if (statements.length > 0) await db.batch(statements)
-}
-
-async function relationExists(db: SqlDatabase, name: string): Promise<boolean> {
-	const row = await db
-		.prepare(`SELECT EXISTS (
-			SELECT 1
-			FROM pg_catalog.pg_class relation
-			JOIN pg_catalog.pg_namespace namespace ON namespace.oid = relation.relnamespace
-			WHERE namespace.nspname = current_schema()
-				AND relation.relname = ?
-				AND relation.relkind IN ('r', 'p')
-		) AS present`)
-		.bind(name)
-		.first<PresenceRow>()
-	return row?.present === true
-}
-
-function appliedAt(value: number | string): number {
-	const parsed = typeof value === 'number' ? value : Number(value)
-	if (!Number.isSafeInteger(parsed) || parsed < 0) throw new Error('Legacy migration ledger contains an invalid timestamp')
-	return parsed
-}
-
 function unixNow(): number {
 	return Math.floor(Date.now() / 1_000)
 }

package/src/service-postgres-migrations.ts

@@ -2,7 +2,6 @@ import type { SqlDatabase } from '@fabrika/platform'
 import {
 	applyPostgresMigrations,
 	definePostgresMigrationPlan,
-	type PostgresLegacyMigrationLedger,
 	type PostgresMigration,
 	type PostgresMigrationBundle,
 	postgresMigrationFilenames,
@@ -18,7 +17,6 @@ export interface PostgresServiceMigrationsConfig {
 	/** Stable service advisory lock. */
 	readonly lockKey: number
 	readonly directory: string
-	readonly legacy: PostgresLegacyMigrationLedger
 	/** Runtime-owned bundles applied before the service schema. */
 	readonly dependencies?: readonly PostgresMigrationBundle[]
 }
@@ -32,14 +30,13 @@ export interface PostgresServiceMigrations {
 
 /**
  * Define the repeated service migration wrapper while keeping service identity and lifecycle local.
- * Bundle names, ledgers, lock ids, dependency order, and legacy evidence remain explicit inputs.
+ * Bundle names, ledgers, lock ids, and dependency order remain explicit inputs.
  */
 export function definePostgresServiceMigrations(config: PostgresServiceMigrationsConfig): PostgresServiceMigrations {
 	const read = (directory: string = config.directory): PostgresMigration[] => [
 		...readPostgresMigrationBundle({
 			name: config.name,
 			directory,
-			adoptLegacy: true,
 		}).migrations,
 	]
 	const plan = (migrations: readonly PostgresMigration[] = read()): PostgresMigrationPlan =>
@@ -48,9 +45,8 @@ export function definePostgresServiceMigrations(config: PostgresServiceMigration
 			lockKey: config.lockKey,
 			bundles: [
 				...(config.dependencies ?? []),
-				{ name: config.name, migrations, adoptLegacy: true },
+				{ name: config.name, migrations },
 			],
-			legacy: config.legacy,
 		})
 	const applyQualified = (
 		db: SqlDatabase,

package/src/uuid.ts

@@ -1,94 +0,0 @@
-/**
- * UUIDv7 generator — time-ordered ids, so a jobs table orders by id chronologically and a keyset
- * cursor works, monotonic WITHIN a millisecond as well as across one. Ids are minted CALLER-SIDE,
- * never by SQL (the repo-wide convention, and the one thing that keeps inserts identical across
- * SQLite and Postgres). Self-contained so this package has no dependencies beyond the port it
- * implements.
- *
- * RFC 9562 layout, with §6.2's "fixed bit-length dedicated counter" monotonic variant:
- *
- *   bytes 0..5   48-bit big-endian Unix-millis timestamp
- *   byte  6      version nibble `7` + the high 4 bits of a 12-bit counter (`rand_a`)
- *   byte  7      the low 8 bits of that counter
- *   byte  8      variant bits `10` + 6 random bits
- *   bytes 9..15  56 random bits
- *
- * so **62 random bits per id** — down from the 74 of the unguarded Method 0 this used to be — plus 8
- * fresh random bits seeding the counter at each new millisecond.
- *
- * The counter is re-seeded from 8 random bits (the top 4 left zero, the RFC's rollover guard, so at
- * least 3840 ids per millisecond are guaranteed) whenever the millisecond advances, and incremented
- * otherwise. `rand_a` sits immediately after the timestamp and the version nibble in the canonical
- * string, so two ids minted in the same millisecond differ there and a TEXT `ORDER BY` puts them in
- * mint order, strictly.
- *
- * Two clock hazards are handled explicitly rather than by wrapping:
- *   - counter exhausted inside one millisecond → borrow one millisecond from the future (RFC 9562
- *     §6.2) and re-seed; the borrowed time is repaid as soon as the clock catches up.
- *   - the timestamp goes BACKWARDS → keep the last effective millisecond and keep counting, so the
- *     sequence never repeats and never decreases.
- *
- * The counter is per GENERATOR — one process. Two ids minted in the same millisecond by two processes
- * tie only if their independently seeded counters collide (~1/256), and the 62 random bits break
- * that; within one process the order is exact. That is the whole promise: strictly increasing per
- * generator, chronological to the millisecond across generators.
- *
- * `millis` is injectable so a caller that already has a clock (the job queue does) mints ids on THAT
- * clock, keeping id order and row order consistent. Because the generator is monotonic, the timestamp
- * actually embedded is `max(millis, last embedded)`: a supplied millisecond BEHIND one already used
- * is clamped, and the counter carries the ordering instead. Ordering is the promise; an exact
- * round-trip of an arbitrary past `millis` is not.
- *
- * `@fabrika/auth-core` and `@fabrika/control` carry deliberate copies of this same algorithm — see
- * the note in each.
- */
-
-/** `rand_a` is 12 bits, all of it counter. */
-const COUNTER_MAX = 0xfff
-/** Seed from 8 random bits only — the leading 4 stay zero so a millisecond has room to count. */
-const COUNTER_SEED_MASK = 0xff
-
-/** Effective millisecond of the last id. NEVER decreases; a backwards clock is absorbed here. */
-let lastMillis = -1
-let counter = 0
-
-export function uuidv7(millis: number = Date.now()): string {
-	const bytes = new Uint8Array(16)
-	crypto.getRandomValues(bytes)
-
-	// Byte 7 is read as the counter seed BEFORE the counter overwrites it, so the seed costs no extra
-	// randomness.
-	const seed = (bytes[7] ?? 0) & COUNTER_SEED_MASK
-	if (millis > lastMillis) {
-		lastMillis = millis
-		counter = seed
-	} else if (counter < COUNTER_MAX) {
-		// Same millisecond, or a clock that went backwards: hold the effective timestamp, count on.
-		counter += 1
-	} else {
-		// Exhausted — borrow a millisecond from the future rather than wrap back under the last id.
-		lastMillis += 1
-		counter = seed
-	}
-
-	// 48-bit big-endian timestamp in bytes 0..5.
-	bytes[0] = (lastMillis / 2 ** 40) & 0xff
-	bytes[1] = (lastMillis / 2 ** 32) & 0xff
-	bytes[2] = (lastMillis / 2 ** 24) & 0xff
-	bytes[3] = (lastMillis / 2 ** 16) & 0xff
-	bytes[4] = (lastMillis / 2 ** 8) & 0xff
-	bytes[5] = lastMillis & 0xff
-
-	// Version 7 in the high nibble of byte 6, the counter in the remaining 12 bits of `rand_a`;
-	// variant (10xx) in the high bits of byte 8.
-	bytes[6] = 0x70 | (counter >>> 8)
-	bytes[7] = counter & 0xff
-	bytes[8] = (bytes[8] ?? 0) & 0x3f | 0x80
-
-	const hex: string[] = []
-	for (const b of bytes) {
-		hex.push(b.toString(16).padStart(2, '0'))
-	}
-	const s = hex.join('')
-	return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20)}`
-}