@qlever-llc/trellis 0.10.22 → 0.11.0-rc.1

package/src/service/outbox_inbox.ts

@@ -1,14 +1,31 @@
-import { type AsyncResult, type BaseError, isErr } from "@qlever-llc/result";
+import {
+  type AsyncResult,
+  type BaseError,
+  isErr,
+  UnexpectedError,
+} from "@qlever-llc/result";
 import { type StaticDecode, Type } from "typebox";
-import type { PreparedTrellisEvent, Trellis } from "../trellis.js";
+import type { PreparedTrellisEvent } from "../trellis.js";
 import { TypedKV } from "../kv.js";
 import { recordTrellisError } from "../telemetry/mod.js";
 
 export type OutboxMessageState = "pending" | "dispatched" | "failed";
 
+export type OutboxRecordKind = "event.publish" | "job.create" | "job.submit";
+
+export type PreparedOutboxRecord = {
+  readonly id: string;
+  readonly kind: OutboxRecordKind;
+  readonly name: string;
+  readonly subject: string;
+  readonly payload: string;
+  readonly headers: Readonly<Record<string, string>>;
+};
+
 export type OutboxMessage = {
   id: string;
-  event: string;
+  kind: OutboxRecordKind;
+  name: string;
   subject: string;
   payload: string;
   headers: Record<string, string>;
@@ -18,6 +35,7 @@ export type OutboxMessage = {
   updatedAt: string;
   nextAttemptAt?: string;
   lastError?: string;
+  outcome?: unknown;
 };
 
 export type OutboxDispatchResult = {
@@ -39,10 +57,21 @@ export type OutboxDispatcherOptions = {
   onError?: (error: unknown) => void;
 };
 
+export type OutboxDispatchRuntime = {
+  /** Dispatches an event-publish outbox record. Returns Void on success, err on transient failure. */
+  publishPreparedEvent(
+    event: PreparedTrellisEvent,
+  ): AsyncResult<void, UnexpectedError>;
+  /** Dispatches a job create/submit outbox record. Stub until Phase 3. */
+  dispatchJobSubmission?(
+    message: OutboxMessage,
+  ): AsyncResult<void, BaseError>;
+};
+
 export type OutboxRepository = {
-  enqueue(event: PreparedTrellisEvent): Promise<OutboxMessage>;
+  enqueue(record: PreparedOutboxRecord): Promise<OutboxMessage>;
   claimDue(limit: number, now: Date): Promise<OutboxMessage[]>;
-  markDispatched(id: string, now: Date): Promise<void>;
+  markDispatched(id: string, now: Date, outcome?: unknown): Promise<void>;
   markFailed(
     id: string,
     failure: { error: string; nextAttemptAt: Date; now: Date },
@@ -53,26 +82,55 @@ export type InboxRepository = {
   record(messageId: string, now?: Date): Promise<boolean>;
 };
 
+/** SQL dialects supported by Trellis SQL outbox helpers. */
 export type SqlDialect = "sqlite" | "postgres";
 
+/** Table names used by Trellis SQL outbox and inbox helper tables. */
 export type SqlOutboxTables = {
   outbox: string;
   inbox: string;
 };
 
+/** Minimal SQL execution surface used by Trellis SQL outbox repositories. */
 export type SqlExecutor = {
   query(sql: string, params: readonly unknown[]): Promise<readonly SqlRow[]>;
   execute(sql: string, params: readonly unknown[]): Promise<void>;
 };
 
+/** Row shape returned by a {@link SqlExecutor}. */
 export type SqlRow = Record<string, unknown>;
 
+/** SQL outbox adapter bundle over caller-owned SQL execution. */
 export type SqlOutboxAdapter = {
   outbox: SqlOutboxRepository;
   inbox: SqlInboxRepository;
   ddl: readonly string[];
 };
 
+/** Versioned Trellis-owned SQL outbox/inbox migration artifact. */
+export type SqlOutboxMigration = {
+  /** Stable migration identifier for the dialect and schema version. */
+  readonly id: string;
+  /** Monotonic Trellis helper-table schema version. */
+  readonly version: number;
+  /** SQL dialect targeted by this migration artifact. */
+  readonly dialect: SqlDialect;
+  /** SQL statements that apply this migration. */
+  readonly up: readonly string[];
+  /** SQL statements that revert this migration when supported by the runner. */
+  readonly down?: readonly string[];
+  /** Deterministic checksum over the canonical migration SQL. */
+  readonly checksum: string;
+};
+
+/** Options for generating Trellis SQL outbox/inbox migration artifacts. */
+export type SqlOutboxMigrationOptions = {
+  /** SQL dialect targeted by the generated migration artifacts. */
+  readonly dialect: SqlDialect;
+  /** Optional helper-table names; omitted names use Trellis defaults. */
+  readonly tables?: Partial<SqlOutboxTables>;
+};
+
 type KvAsyncResult<T> = Pick<AsyncResult<T, BaseError>, "take">;
 
 export type OutboxKvEntry = {
@@ -88,41 +146,70 @@ export type OutboxKvStore = {
   keys(filter?: string | string[]): KvAsyncResult<AsyncIterable<string>>;
 };
 
+/** Default Trellis helper-table names for SQL outbox and inbox storage. */
 export const defaultSqlOutboxTables: SqlOutboxTables = Object.freeze({
   outbox: "trellis_outbox",
   inbox: "trellis_inbox",
 });
 
+const sqlIdentifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
 /**
- * Creates SQL outbox/inbox repositories plus DDL for caller-owned migrations.
+ * Creates SQL outbox/inbox repositories plus current helper-table DDL.
  *
- * Trellis does not import Drizzle here to avoid making every service depend on a
- * specific migration library. Services should include the returned DDL, or an
- * equivalent Drizzle table definition using these table and column names, in
- * their own Drizzle-managed migration flow.
+ * Use {@link getSqlOutboxMigrations} when services need versioned Trellis-owned
+ * migration artifacts for their normal database migration tooling.
  */
 export function createSqlOutboxAdapter(
   executor: SqlExecutor,
   dialect: SqlDialect,
   tables: SqlOutboxTables = defaultSqlOutboxTables,
 ): SqlOutboxAdapter {
+  const sqlTables = validateSqlOutboxTables(tables);
   return {
-    outbox: new SqlOutboxRepository(executor, dialect, tables),
-    inbox: new SqlInboxRepository(executor, dialect, tables),
+    outbox: new SqlOutboxRepository(executor, dialect, sqlTables),
+    inbox: new SqlInboxRepository(executor, dialect, sqlTables),
     ddl: dialect === "postgres"
-      ? createPostgresOutboxSchema(tables)
-      : createSqliteOutboxSchema(tables),
+      ? createPostgresOutboxSchema(sqlTables)
+      : createSqliteOutboxSchema(sqlTables),
   };
 }
 
+/**
+ * Returns Trellis-owned SQL outbox/inbox migration artifacts for a dialect.
+ *
+ * Trellis generates the helper-table SQL, but services remain responsible for
+ * running these artifacts through their normal database migration tooling.
+ */
+export function getSqlOutboxMigrations(
+  options: SqlOutboxMigrationOptions,
+): readonly SqlOutboxMigration[] {
+  const tables = resolveSqlOutboxTables(options.tables);
+  const up = options.dialect === "postgres"
+    ? createPostgresOutboxSchema(tables)
+    : createSqliteOutboxSchema(tables);
+  const down = createSqlOutboxDownSchema(tables);
+  return Object.freeze([
+    Object.freeze({
+      id: `trellis_sql_outbox_inbox_${options.dialect}_v1`,
+      version: 1,
+      dialect: options.dialect,
+      up,
+      down,
+      checksum: checksumMigrationSql(up, down),
+    }),
+  ]);
+}
+
 /** Returns SQLite DDL for Trellis outbox and inbox tables. */
 export function createSqliteOutboxSchema(
   tables: SqlOutboxTables = defaultSqlOutboxTables,
 ): readonly string[] {
+  const sqlTables = validateSqlOutboxTables(tables);
   return [
-    `CREATE TABLE IF NOT EXISTS ${tables.outbox} (id TEXT PRIMARY KEY, event TEXT NOT NULL, subject TEXT NOT NULL, payload TEXT NOT NULL, headers TEXT NOT NULL, state TEXT NOT NULL, attempts INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, next_attempt_at TEXT, last_error TEXT)`,
-    `CREATE INDEX IF NOT EXISTS ${tables.outbox}_due_idx ON ${tables.outbox} (state, next_attempt_at)`,
-    `CREATE TABLE IF NOT EXISTS ${tables.inbox} (message_id TEXT PRIMARY KEY, received_at TEXT NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS ${sqlTables.outbox} (id TEXT PRIMARY KEY, kind TEXT NOT NULL, name TEXT NOT NULL, subject TEXT NOT NULL, payload TEXT NOT NULL, headers TEXT NOT NULL, state TEXT NOT NULL, attempts INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, next_attempt_at TEXT, last_error TEXT, outcome TEXT)`,
+    `CREATE INDEX IF NOT EXISTS ${sqlTables.outbox}_due_idx ON ${sqlTables.outbox} (state, next_attempt_at)`,
+    `CREATE TABLE IF NOT EXISTS ${sqlTables.inbox} (message_id TEXT PRIMARY KEY, received_at TEXT NOT NULL)`,
   ];
 }
 
@@ -130,28 +217,91 @@ export function createSqliteOutboxSchema(
 export function createPostgresOutboxSchema(
   tables: SqlOutboxTables = defaultSqlOutboxTables,
 ): readonly string[] {
+  const sqlTables = validateSqlOutboxTables(tables);
+  return [
+    `CREATE TABLE IF NOT EXISTS ${sqlTables.outbox} (id text PRIMARY KEY, kind text NOT NULL, name text NOT NULL, subject text NOT NULL, payload text NOT NULL, headers jsonb NOT NULL, state text NOT NULL, attempts integer NOT NULL, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL, next_attempt_at timestamptz, last_error text, outcome jsonb)`,
+    `CREATE INDEX IF NOT EXISTS ${sqlTables.outbox}_due_idx ON ${sqlTables.outbox} (state, next_attempt_at)`,
+    `CREATE TABLE IF NOT EXISTS ${sqlTables.inbox} (message_id text PRIMARY KEY, received_at timestamptz NOT NULL)`,
+  ];
+}
+
+function createSqlOutboxDownSchema(
+  tables: SqlOutboxTables,
+): readonly string[] {
+  const sqlTables = validateSqlOutboxTables(tables);
   return [
-    `CREATE TABLE IF NOT EXISTS ${tables.outbox} (id text PRIMARY KEY, event text NOT NULL, subject text NOT NULL, payload text NOT NULL, headers jsonb NOT NULL, state text NOT NULL, attempts integer NOT NULL, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL, next_attempt_at timestamptz, last_error text)`,
-    `CREATE INDEX IF NOT EXISTS ${tables.outbox}_due_idx ON ${tables.outbox} (state, next_attempt_at)`,
-    `CREATE TABLE IF NOT EXISTS ${tables.inbox} (message_id text PRIMARY KEY, received_at timestamptz NOT NULL)`,
+    `DROP INDEX IF EXISTS ${sqlTables.outbox}_due_idx`,
+    `DROP TABLE IF EXISTS ${sqlTables.inbox}`,
+    `DROP TABLE IF EXISTS ${sqlTables.outbox}`,
   ];
 }
 
+function resolveSqlOutboxTables(
+  tables: Partial<SqlOutboxTables> | undefined,
+): SqlOutboxTables {
+  return validateSqlOutboxTables({
+    outbox: tables?.outbox ?? defaultSqlOutboxTables.outbox,
+    inbox: tables?.inbox ?? defaultSqlOutboxTables.inbox,
+  });
+}
+
+function validateSqlOutboxTables(tables: SqlOutboxTables): SqlOutboxTables {
+  validateSqlIdentifier("outbox", tables.outbox);
+  validateSqlIdentifier("inbox", tables.inbox);
+  return Object.freeze({ outbox: tables.outbox, inbox: tables.inbox });
+}
+
+function validateSqlIdentifier(
+  kind: keyof SqlOutboxTables,
+  name: string,
+): void {
+  if (!sqlIdentifierPattern.test(name)) {
+    throw new Error(
+      `Invalid SQL ${kind} table name "${name}". Use a simple identifier matching ${sqlIdentifierPattern.source}.`,
+    );
+  }
+}
+
+function checksumMigrationSql(
+  up: readonly string[],
+  down: readonly string[],
+): string {
+  return `fnv1a64:${
+    fnv1a64Hex([
+      "-- up",
+      ...up,
+      "-- down",
+      ...down,
+    ].join("\n"))
+  }`;
+}
+
+function fnv1a64Hex(input: string): string {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (const character of input) {
+    hash ^= BigInt(character.codePointAt(0) ?? 0);
+    hash = BigInt.asUintN(64, hash * prime);
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
 /** In-memory outbox repository intended for tests and local process adapters. */
 export class MemoryOutboxRepository implements OutboxRepository {
   #messages = new Map<string, OutboxMessage>();
 
-  async enqueue(event: PreparedTrellisEvent): Promise<OutboxMessage> {
+  async enqueue(record: PreparedOutboxRecord): Promise<OutboxMessage> {
     const now = new Date().toISOString();
-    const id = messageId(event);
+    const id = record.id;
     const existing = this.#messages.get(id);
     if (existing) return existing;
     const message: OutboxMessage = {
       id,
-      event: event.event,
-      subject: event.subject,
-      payload: event.encodedPayload,
-      headers: { ...event.headers },
+      kind: record.kind,
+      name: record.name,
+      subject: record.subject,
+      payload: record.payload,
+      headers: { ...record.headers },
       state: "pending",
       attempts: 0,
       createdAt: now,
@@ -177,7 +327,11 @@ export class MemoryOutboxRepository implements OutboxRepository {
     return claimed;
   }
 
-  async markDispatched(id: string, now: Date): Promise<void> {
+  async markDispatched(
+    id: string,
+    now: Date,
+    outcome?: unknown,
+  ): Promise<void> {
     const message = this.#messages.get(id);
     if (!message) return;
     this.#messages.set(id, {
@@ -186,6 +340,7 @@ export class MemoryOutboxRepository implements OutboxRepository {
       updatedAt: now.toISOString(),
       nextAttemptAt: undefined,
       lastError: undefined,
+      outcome: outcome ?? message.outcome,
     });
   }
 
@@ -226,20 +381,25 @@ export class MemoryInboxRepository implements InboxRepository {
 
 /** SQL-backed outbox repository over a caller-owned executor. */
 export class SqlOutboxRepository implements OutboxRepository {
+  readonly tables: SqlOutboxTables;
+
   constructor(
     readonly executor: SqlExecutor,
     readonly dialect: SqlDialect,
-    readonly tables: SqlOutboxTables = defaultSqlOutboxTables,
-  ) {}
+    tables: SqlOutboxTables = defaultSqlOutboxTables,
+  ) {
+    this.tables = validateSqlOutboxTables(tables);
+  }
 
-  async enqueue(event: PreparedTrellisEvent): Promise<OutboxMessage> {
+  async enqueue(record: PreparedOutboxRecord): Promise<OutboxMessage> {
     const now = new Date().toISOString();
     const message: OutboxMessage = {
-      id: messageId(event),
-      event: event.event,
-      subject: event.subject,
-      payload: event.encodedPayload,
-      headers: { ...event.headers },
+      id: record.id,
+      kind: record.kind,
+      name: record.name,
+      subject: record.subject,
+      payload: record.payload,
+      headers: { ...record.headers },
       state: "pending",
       attempts: 0,
       createdAt: now,
@@ -250,12 +410,13 @@ export class SqlOutboxRepository implements OutboxRepository {
       ? "ON CONFLICT (id) DO NOTHING"
       : "ON CONFLICT(id) DO NOTHING";
     await this.executor.execute(
-      `INSERT INTO ${this.tables.outbox} (id, event, subject, payload, headers, state, attempts, created_at, updated_at, next_attempt_at, last_error) VALUES (${
-        placeholders(this.dialect, 11)
+      `INSERT INTO ${this.tables.outbox} (id, kind, name, subject, payload, headers, state, attempts, created_at, updated_at, next_attempt_at, last_error, outcome) VALUES (${
+        placeholders(this.dialect, 13)
       }) ${conflict}`,
       [
         message.id,
-        message.event,
+        message.kind,
+        message.name,
         message.subject,
         message.payload,
         headers,
@@ -265,6 +426,7 @@ export class SqlOutboxRepository implements OutboxRepository {
         message.updatedAt,
         null,
         null,
+        null,
       ],
     );
     return message;
@@ -272,7 +434,7 @@ export class SqlOutboxRepository implements OutboxRepository {
 
   async claimDue(limit: number, now: Date): Promise<OutboxMessage[]> {
     const rows = await this.executor.query(
-      `SELECT id, event, subject, payload, headers, state, attempts, created_at, updated_at, next_attempt_at, last_error FROM ${this.tables.outbox} WHERE state != ${
+      `SELECT id, kind, name, subject, payload, headers, state, attempts, created_at, updated_at, next_attempt_at, last_error, outcome FROM ${this.tables.outbox} WHERE state != ${
         placeholder(this.dialect, 1)
       } AND (next_attempt_at IS NULL OR next_attempt_at <= ${
         placeholder(this.dialect, 2)
@@ -282,16 +444,21 @@ export class SqlOutboxRepository implements OutboxRepository {
     return rows.map(rowToOutboxMessage);
   }
 
-  async markDispatched(id: string, now: Date): Promise<void> {
+  async markDispatched(
+    id: string,
+    now: Date,
+    outcome?: unknown,
+  ): Promise<void> {
+    const outcomeJson = outcome !== undefined ? JSON.stringify(outcome) : null;
     await this.executor.execute(
       `UPDATE ${this.tables.outbox} SET state = ${
         placeholder(this.dialect, 1)
       }, updated_at = ${
         placeholder(this.dialect, 2)
-      }, next_attempt_at = NULL, last_error = NULL WHERE id = ${
+      }, next_attempt_at = NULL, last_error = NULL, outcome = ${
         placeholder(this.dialect, 3)
-      }`,
-      ["dispatched", now.toISOString(), id],
+      } WHERE id = ${placeholder(this.dialect, 4)}`,
+      ["dispatched", now.toISOString(), outcomeJson, id],
     );
   }
 
@@ -320,11 +487,15 @@ export class SqlOutboxRepository implements OutboxRepository {
 
 /** SQL-backed inbox repository over a caller-owned executor. */
 export class SqlInboxRepository implements InboxRepository {
+  readonly tables: SqlOutboxTables;
+
   constructor(
     readonly executor: SqlExecutor,
     readonly dialect: SqlDialect,
-    readonly tables: SqlOutboxTables = defaultSqlOutboxTables,
-  ) {}
+    tables: SqlOutboxTables = defaultSqlOutboxTables,
+  ) {
+    this.tables = validateSqlOutboxTables(tables);
+  }
 
   async record(messageId: string, now: Date = new Date()): Promise<boolean> {
     try {
@@ -363,7 +534,8 @@ type KvInboxRecord = StaticDecode<typeof KvInboxRecordSchema>;
 
 export const KvOutboxRecordSchema = Type.Object({
   id: Type.String(),
-  event: Type.String(),
+  kind: Type.String(),
+  name: Type.String(),
   subject: Type.String(),
   payload: Type.String(),
   headers: Type.Record(Type.String(), Type.String()),
@@ -378,6 +550,7 @@ export const KvOutboxRecordSchema = Type.Object({
   updatedAt: Type.String(),
   nextAttemptAt: Type.Optional(Type.String()),
   lastError: Type.Optional(Type.String()),
+  outcome: Type.Optional(Type.String()),
 });
 
 export type KvOutboxRecord = StaticDecode<typeof KvOutboxRecordSchema>;
@@ -386,14 +559,15 @@ export type KvOutboxRecord = StaticDecode<typeof KvOutboxRecordSchema>;
 export class NatsKvOutboxRepository implements OutboxRepository {
   constructor(readonly kv: OutboxKvStore) {}
 
-  async enqueue(event: PreparedTrellisEvent): Promise<OutboxMessage> {
+  async enqueue(rec: PreparedOutboxRecord): Promise<OutboxMessage> {
     const now = new Date().toISOString();
     const record: KvOutboxRecord = {
-      id: messageId(event),
-      event: event.event,
-      subject: event.subject,
-      payload: event.encodedPayload,
-      headers: { ...event.headers },
+      id: rec.id,
+      kind: rec.kind,
+      name: rec.name,
+      subject: rec.subject,
+      payload: rec.payload,
+      headers: { ...rec.headers },
       state: "pending",
       attempts: 0,
       createdAt: now,
@@ -446,18 +620,26 @@ export class NatsKvOutboxRepository implements OutboxRepository {
     return claimed;
   }
 
-  async markDispatched(id: string, now: Date): Promise<void> {
+  async markDispatched(
+    id: string,
+    now: Date,
+    outcome?: unknown,
+  ): Promise<void> {
     const loaded = await this.kv.get(id).take();
     if (isErr(loaded)) {
       if (hasKvReason(loaded.error, "not found")) return;
       throw loaded.error;
     }
+    const outcomeStr = outcome !== undefined
+      ? JSON.stringify(outcome)
+      : undefined;
     const stored = await loaded.put({
       ...loaded.value,
       state: "dispatched",
       updatedAt: now.toISOString(),
       nextAttemptAt: undefined,
       lastError: undefined,
+      outcome: outcomeStr ?? loaded.value.outcome,
     }, true).take();
     if (isErr(stored)) throw stored.error;
   }
@@ -512,7 +694,7 @@ export class NatsKvInboxRepository implements InboxRepository {
  */
 export class OutboxDispatcher {
   readonly #repository: OutboxRepository;
-  readonly #runtime: Pick<Trellis, "publishPrepared">;
+  readonly #runtime: OutboxDispatchRuntime;
   readonly #options: OutboxDispatcherOptions;
   #wakeTimer: ReturnType<typeof setTimeout> | undefined;
   #retryTimer: ReturnType<typeof setTimeout> | undefined;
@@ -525,7 +707,7 @@ export class OutboxDispatcher {
   /** Creates a dispatcher over an existing outbox repository and runtime. */
   constructor(
     repository: OutboxRepository,
-    runtime: Pick<Trellis, "publishPrepared">,
+    runtime: OutboxDispatchRuntime,
     options: OutboxDispatcherOptions = {},
   ) {
     this.#repository = repository;
@@ -656,10 +838,10 @@ export class OutboxDispatcher {
   }
 }
 
-/** Dispatches due outbox messages through a Trellis runtime publisher. */
+/** Dispatches due outbox messages through a dispatch runtime. */
 export async function dispatchOutbox(
   repository: OutboxRepository,
-  runtime: Pick<Trellis, "publishPrepared">,
+  runtime: OutboxDispatchRuntime,
   options: { limit?: number; now?: Date; retryDelayMs?: number } = {},
 ): Promise<OutboxDispatchResult> {
   const now = options.now ?? new Date();
@@ -668,58 +850,128 @@ export async function dispatchOutbox(
   let dispatched = 0;
   let failed = 0;
   for (const message of messages) {
-    const result = await runtime.publishPrepared(
-      outboxMessageToPrepared(message),
-    );
-    const value = result.take();
-    if (isErr(value)) {
-      recordTrellisError(value.error, {
+    if (message.kind === "event.publish") {
+      const result = await runtime.publishPreparedEvent(
+        outboxMessageToPreparedEvent(message),
+      );
+      const value = result.take();
+      if (isErr(value)) {
+        recordTrellisError(value.error, {
+          surface: "outbox",
+          direction: "dispatcher",
+          operation: message.name,
+          phase: "publish",
+          messagingSystem: "nats",
+        });
+        failed += 1;
+        await repository.markFailed(message.id, {
+          error: value.error.message,
+          nextAttemptAt: new Date(now.getTime() + retryDelayMs),
+          now,
+        });
+        continue;
+      }
+      dispatched += 1;
+      await repository.markDispatched(message.id, now);
+    } else if (
+      message.kind === "job.create" || message.kind === "job.submit"
+    ) {
+      if (runtime.dispatchJobSubmission) {
+        const result = await runtime.dispatchJobSubmission(message);
+        const value = result.take();
+        if (isErr(value)) {
+          recordTrellisError(value.error, {
+            surface: "outbox",
+            direction: "dispatcher",
+            operation: message.name,
+            phase: "job.dispatch",
+          });
+          failed += 1;
+          await repository.markFailed(message.id, {
+            error: value.error.message,
+            nextAttemptAt: new Date(now.getTime() + retryDelayMs),
+            now,
+          });
+          continue;
+        }
+        dispatched += 1;
+        await repository.markDispatched(message.id, now);
+      } else {
+        recordTrellisError(new Error(`job dispatch not supported`), {
+          surface: "outbox",
+          direction: "dispatcher",
+          operation: message.name,
+          phase: "dispatch",
+        });
+        await repository.markDispatched(message.id, now, {
+          error: "job dispatch not supported",
+        });
+      }
+    } else {
+      const error = `Unknown outbox record kind: ${message.kind}`;
+      recordTrellisError(new Error(error), {
         surface: "outbox",
         direction: "dispatcher",
-        operation: message.event,
-        phase: "publish",
-        messagingSystem: "nats",
-      });
-      failed += 1;
-      await repository.markFailed(message.id, {
-        error: value.error.message,
-        nextAttemptAt: new Date(now.getTime() + retryDelayMs),
-        now,
+        operation: message.name,
+        phase: "dispatch",
       });
-      continue;
+      await repository.markDispatched(message.id, now, { error });
     }
-    dispatched += 1;
-    await repository.markDispatched(message.id, now);
   }
   return { dispatched, failed };
 }
 
-/** Rehydrates a persisted outbox row into a prepared event. */
-export function outboxMessageToPrepared(
+/** Rehydrates a persisted outbox event row into a prepared event. */
+export function outboxMessageToPreparedEvent(
   message: OutboxMessage,
 ): PreparedTrellisEvent {
+  if (message.kind !== "event.publish") {
+    throw new Error(
+      `Expected event.publish kind, got ${message.kind}`,
+    );
+  }
+  const payload = JSON.parse(message.payload) as Record<string, unknown>;
+  const header = eventHeaderFromMessage(message.headers);
   return Object.freeze({
-    event: message.event,
+    event: message.name,
     subject: message.subject,
-    payload: Object.freeze(
-      JSON.parse(message.payload) as Record<string, unknown> & {
-        header: { id: string; time: string };
-      },
-    ),
+    header: Object.freeze(header),
+    payload: Object.freeze(payload),
     encodedPayload: message.payload,
     headers: Object.freeze({ ...message.headers }),
   });
 }
 
-function messageId(event: PreparedTrellisEvent): string {
-  return event.headers["Nats-Msg-Id"] ?? event.headers["nats-msg-id"] ??
-    event.payload.header.id;
+/** Adapts a prepared Trellis event into a generic outbox record. */
+export function preparedTrellisEventToOutboxRecord(
+  event: PreparedTrellisEvent,
+): PreparedOutboxRecord {
+  return {
+    id: event.headers["Nats-Msg-Id"] ?? event.header.id,
+    kind: "event.publish",
+    name: event.event,
+    subject: event.subject,
+    payload: event.encodedPayload,
+    headers: event.headers,
+  };
+}
+
+function eventHeaderFromMessage(
+  headers: Record<string, string>,
+): { id: string; time: string } {
+  const id = headers["Nats-Msg-Id"] ?? headers["nats-msg-id"];
+  const time = headers["Trellis-Event-Time"] ?? headers["trellis-event-time"];
+  return {
+    id: typeof id === "string" ? id : "",
+    time: typeof time === "string" ? time : new Date(0).toISOString(),
+  };
 }
 
 function rowToOutboxMessage(row: SqlRow): OutboxMessage {
   return {
     id: stringField(row, "id"),
-    event: stringField(row, "event"),
+    kind: kindField(row, "kind"),
+    name: stringField(row, "name"),
     subject: stringField(row, "subject"),
     payload: stringField(row, "payload"),
     headers: parseHeaders(row["headers"]),
@@ -729,13 +981,15 @@ function rowToOutboxMessage(row: SqlRow): OutboxMessage {
     updatedAt: stringField(row, "updated_at"),
     nextAttemptAt: optionalStringField(row, "next_attempt_at"),
     lastError: optionalStringField(row, "last_error"),
+    outcome: optionalStringField(row, "outcome"),
   };
 }
 
 function kvRecordToOutboxMessage(record: KvOutboxRecord): OutboxMessage {
   return {
     id: record.id,
-    event: record.event,
+    kind: record.kind as OutboxRecordKind,
+    name: record.name,
     subject: record.subject,
     payload: record.payload,
     headers: { ...record.headers },
@@ -745,6 +999,7 @@ function kvRecordToOutboxMessage(record: KvOutboxRecord): OutboxMessage {
     updatedAt: record.updatedAt,
     nextAttemptAt: record.nextAttemptAt,
     lastError: record.lastError,
+    outcome: record.outcome,
   };
 }
 
@@ -810,6 +1065,17 @@ function numberField(row: SqlRow, field: string): number {
   return value;
 }
 
+function kindField(row: SqlRow, field: string): OutboxRecordKind {
+  const value = stringField(row, field);
+  if (
+    value === "event.publish" || value === "job.create" ||
+    value === "job.submit"
+  ) {
+    return value;
+  }
+  throw new Error(`Expected SQL field ${field} to be an outbox record kind`);
+}
+
 function stateField(row: SqlRow, field: string): OutboxMessageState {
   const value = stringField(row, field);
   if (value === "pending" || value === "dispatched" || value === "failed") {