better-ship 0.5.0 → 0.6.0

package/dist/unit-of-work-context-DToDpAkv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-of-work-context-DToDpAkv.js","names":[],"sources":["../src/infrastructure/unit-of-work-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\n\nimport { panic } from 'better-result'\nimport type { BatchItem } from 'drizzle-orm/batch'\n\nimport { UnitOfWorkAlreadyActiveError, type IEventCollector } from '@/application'\nimport type { DomainEvent } from '@/core'\n\ntype UnitOfWorkContext = { readonly events: DomainEvent[] } & (\n  | { readonly database: 'd1'; readonly statements: BatchItem<'sqlite'>[] }\n  | { readonly database: 'postgres' }\n)\n\n// One async scope isolates events and D1 statements and rejects nesting across both adapters.\nconst storage = new AsyncLocalStorage<UnitOfWorkContext>()\n\n/** Reject nested transactions before database work starts; preserve independent concurrent execution. */\nexport async function runWithUnitOfWorkContext<T>(\n  database: UnitOfWorkContext['database'],\n  work: () => Promise<T>,\n): Promise<T> {\n  if (storage.getStore() !== undefined) throw new UnitOfWorkAlreadyActiveError()\n  const context: UnitOfWorkContext =\n    database === 'd1' ? { database, events: [], statements: [] } : { database, events: [] }\n  return storage.run(context, work)\n}\n\n/** Inject this shared scope into the unit of work and expose its emitter to application handlers. */\nexport const eventCollector: IEventCollector = {\n  emit(event) {\n    currentContext().events.push(event)\n  },\n  collect() {\n    return [...currentContext().events]\n  },\n}\n\n/** Queue one native D1 statement for the active batch; other contexts cannot accept D1 writes. */\nexport function stageD1Statement(statement: BatchItem<'sqlite'>): void {\n  d1Context().statements.push(statement)\n}\n\n/** Read the active D1 batch in staging order for commit. */\nexport function collectD1Statements(): ReadonlyArray<BatchItem<'sqlite'>> {\n  return [...d1Context().statements]\n}\n\nfunction d1Context(): Extract<UnitOfWorkContext, { database: 'd1' }> {\n  const context = currentContext()\n  if (context.database !== 'd1') return panic('D1 statements require a D1 unit of work')\n  return context\n}\n\nfunction currentContext(): UnitOfWorkContext {\n  return storage.getStore() ?? panic('operation requires an active unit of work')\n}\n"],"mappings":";;;;;AAcA,MAAM,UAAU,IAAI,kBAAqC;;AAGzD,eAAsB,yBACpB,UACA,MACY;CACZ,IAAI,QAAQ,SAAS,MAAM,QAAW,MAAM,IAAI,6BAA6B;CAC7E,MAAM,UACJ,aAAa,OAAO;EAAE;EAAU,QAAQ,CAAC;EAAG,YAAY,CAAC;CAAE,IAAI;EAAE;EAAU,QAAQ,CAAC;CAAE;CACxF,OAAO,QAAQ,IAAI,SAAS,IAAI;AAClC;;AAGA,MAAa,iBAAkC;CAC7C,KAAK,OAAO;EACV,eAAe,CAAC,CAAC,OAAO,KAAK,KAAK;CACpC;CACA,UAAU;EACR,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC,MAAM;CACpC;AACF;;AAGA,SAAgB,iBAAiB,WAAsC;CACrE,UAAU,CAAC,CAAC,WAAW,KAAK,SAAS;AACvC;;AAGA,SAAgB,sBAA0D;CACxE,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,UAAU;AACnC;AAEA,SAAS,YAA4D;CACnE,MAAM,UAAU,eAAe;CAC/B,IAAI,QAAQ,aAAa,MAAM,OAAO,MAAM,yCAAyC;CACrF,OAAO;AACT;AAEA,SAAS,iBAAoC;CAC3C,OAAO,QAAQ,SAAS,KAAK,MAAM,2CAA2C;AAChF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {

package/src/application/event-collector.ts

@@ -1,7 +1,7 @@
-import type { Event } from './messages.ts'
+import type { DomainEvent } from '@/core'
 
 /** Records events in the current unit of work; the unit of work collects a snapshot for outbox persistence. */
 export interface IEventCollector {
-  emit(event: Event): void
-  collect(): ReadonlyArray<Event>
+  emit(event: DomainEvent): void
+  collect(): ReadonlyArray<DomainEvent>
 }

package/src/application/handlers.ts

@@ -1,10 +1,10 @@
-import type { Command, Event, Query } from './messages.ts'
+import type { DomainCommand, DomainEvent, DomainQuery } from '@/core'
 
 /**
  * Handles one command with the dependency container and returns the caller's value.
  * A handler that writes inside a transaction opens the unit of work itself. Failures throw.
  */
-export type CommandHandler<TCommand extends Command, Deps, Value> = (
+export type CommandHandler<TCommand extends DomainCommand, Deps, Value> = (
   command: TCommand,
   deps: Deps,
 ) => Promise<Value>
@@ -13,10 +13,13 @@ export type CommandHandler<TCommand extends Command, Deps, Value> = (
  * Handles one query with the read-only view of the container.
  * The view is a type over the same object, so a query cannot name a write capability.
  */
-export type QueryHandler<TQuery extends Query, QueryDeps, Value> = (
+export type QueryHandler<TQuery extends DomainQuery, QueryDeps, Value> = (
   query: TQuery,
   deps: QueryDeps,
 ) => Promise<Value>
 
 /** Completes one subscriber's work for an event. Failures throw. */
-export type EventHandler<TEvent extends Event, Deps> = (event: TEvent, deps: Deps) => Promise<void>
+export type EventHandler<TEvent extends DomainEvent, Deps> = (
+  event: TEvent,
+  deps: Deps,
+) => Promise<void>

package/src/application/index.ts

@@ -1,6 +1,6 @@
 export type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
 export type { IMessageStore } from './message-store.ts'
-export type { Command, Event, Message, MessageId, Query } from './messages.ts'
+export type { DomainCommand, DomainEvent, DomainMessage, DomainQuery, MessageId } from '@/core'
 export { MessageBus, type IMessageBus } from './message-bus.ts'
 export type { IOutboxRelay } from './outbox-relay.ts'
 export type {

package/src/application/message-already-processed.error.ts

@@ -1,6 +1,4 @@
-import { AppError, DatabaseError } from '@/core'
-
-import type { MessageId } from './messages.ts'
+import { AppError, DatabaseError, type MessageId } from '@/core'
 
 /** The message's effects already committed. A caller can skip duplicate delivery without repeating those effects. */
 export class MessageAlreadyProcessedError extends AppError {

package/src/application/message-bus.ts

@@ -1,16 +1,22 @@
 import { panic } from 'better-result'
 
-import { createLogger, unreachable } from '@/core'
+import {
+  createLogger,
+  unreachable,
+  type DomainCommand,
+  type DomainEvent,
+  type DomainMessage,
+  type DomainQuery,
+} from '@/core'
 
 import { MessageAlreadyProcessedError } from './message-already-processed.error.ts'
-import type { Command, Event, Message, Query } from './messages.ts'
 import type { Handlers, MessageResult, RegistryMessage } from './registry.ts'
 
 const logger = createLogger('message-bus')
 
 /** The port an entrypoint dispatches through. `AppDeps` names this as `IMessageBus<typeof registry>`. */
 export interface IMessageBus<TRegistry extends Handlers<never>> {
-  handle<TMessage extends Message & RegistryMessage<TRegistry>>(
+  handle<TMessage extends DomainMessage & RegistryMessage<TRegistry>>(
     message: TMessage,
   ): Promise<MessageResult<TMessage, TRegistry>>
 }
@@ -26,7 +32,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
   ) {}
 
   /** Resolves to the handler's own value for a command or query, and to void for an event. */
-  async handle<TMessage extends Message & RegistryMessage<TRegistry>>(
+  async handle<TMessage extends DomainMessage & RegistryMessage<TRegistry>>(
     message: TMessage,
   ): Promise<MessageResult<TMessage, TRegistry>> {
     // SAFETY: the slot for this name is what `MessageResult` names, and dispatch returns its value.
@@ -34,7 +40,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
   }
 
   // oxlint-disable-next-line anti-slop/no-unknown-returns -- one table holds every slot's value; `handle` names it.
-  private dispatch(message: Message): Promise<unknown> {
+  private dispatch(message: DomainMessage): Promise<unknown> {
     if (message.type === 'command') return this.handleCommand(message)
     if (message.type === 'query') return this.handleQuery(message)
     if (message.type === 'event') return this.handleEvent(message)
@@ -43,7 +49,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
   }
 
   // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.
-  private handleCommand(command: Command): Promise<unknown> {
+  private handleCommand(command: DomainCommand): Promise<unknown> {
     // `satisfies` proved the registry complete, so a missing slot is a broken registry object.
     const handler = this.registry.commands[command.name]
     if (handler === undefined) return panic(`No handler for command ${command.name}`)
@@ -52,7 +58,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
   }
 
   // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.
-  private handleQuery(query: Query): Promise<unknown> {
+  private handleQuery(query: DomainQuery): Promise<unknown> {
     const handler = this.registry.queries[query.name]
     if (handler === undefined) return panic(`No handler for query ${query.name}`)
     return handler(query, this.deps)
@@ -63,7 +69,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
    * one `AggregateError`. A `MessageAlreadyProcessedError` means that subscriber already committed on
    * an earlier delivery, so it counts as delivered.
    */
-  private async handleEvent(event: Event): Promise<void> {
+  private async handleEvent(event: DomainEvent): Promise<void> {
     const subscriptions = this.registry.events[event.name] ?? []
     const outcomes = await Promise.allSettled(
       subscriptions.map((subscription) => subscription(event, this.deps)),

package/src/application/message-store.ts

@@ -1,4 +1,4 @@
-import type { Event, MessageId } from './messages.ts'
+import type { DomainEvent, MessageId } from '@/core'
 
 /**
  * Stores processed messages and outgoing events in the same transaction as application writes.
@@ -8,5 +8,5 @@ export interface IMessageStore {
   /** Record this message in the transaction; reject an existing record with `MessageAlreadyProcessedError`. */
   claim(messageId: MessageId): Promise<void>
   /** Write the events to the outbox, inside the same boundary as the state change. */
-  persistEvents(events: ReadonlyArray<Event>): Promise<void>
+  persistEvents(events: ReadonlyArray<DomainEvent>): Promise<void>
 }

package/src/application/registry.ts

@@ -1,13 +1,14 @@
+import type { DomainCommand, DomainEvent, DomainMessage, DomainQuery } from '@/core'
+
 import type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
-import type { Command, Event, Message, Query } from './messages.ts'
 
 /** One slot per command. `unknown` keeps the slot covariant; `MessageResult` recovers the value. */
-export type CommandRegistry<TCommand extends Command, Deps> = {
+export type CommandRegistry<TCommand extends DomainCommand, Deps> = {
   readonly [M in TCommand as M['name']]: CommandHandler<M, Deps, unknown>
 }
 
 /** One slot per query, typed with the read-only view of the container. */
-export type QueryRegistry<TQuery extends Query, QueryDeps> = {
+export type QueryRegistry<TQuery extends DomainQuery, QueryDeps> = {
   readonly [M in TQuery as M['name']]: QueryHandler<M, QueryDeps, unknown>
 }
 
@@ -15,7 +16,7 @@ export type QueryRegistry<TQuery extends Query, QueryDeps> = {
  * Zero or more subscribers per event. Annotate the object with this type rather than
  * `satisfies`, so an event with no subscribers is still a message the bus accepts.
  */
-export type EventRegistry<TEvent extends Event, Deps> = {
+export type EventRegistry<TEvent extends DomainEvent, Deps> = {
   readonly [M in TEvent as M['name']]?: ReadonlyArray<EventHandler<M, Deps>>
 }
 
@@ -24,16 +25,16 @@ export type EventRegistry<TEvent extends Event, Deps> = {
  * makes a missing handler a compile error. `Deps extends QueryDeps` is checked here, the one
  * place both types meet: the read view must be a subset of the container.
  */
-export type MessageRegistry<TMessage extends Message, Deps extends QueryDeps, QueryDeps> = {
-  readonly commands: CommandRegistry<Extract<TMessage, Command>, Deps>
-  readonly queries: QueryRegistry<Extract<TMessage, Query>, QueryDeps>
-  readonly events: EventRegistry<Extract<TMessage, Event>, Deps>
+export type MessageRegistry<TMessage extends DomainMessage, Deps extends QueryDeps, QueryDeps> = {
+  readonly commands: CommandRegistry<Extract<TMessage, DomainCommand>, Deps>
+  readonly queries: QueryRegistry<Extract<TMessage, DomainQuery>, QueryDeps>
+  readonly events: EventRegistry<Extract<TMessage, DomainEvent>, Deps>
 }
 
 // Method syntax makes the parameters bivariant, so an app's slot, typed for one message, fits.
 // oxlint-disable-next-line anti-slop/no-unknown-returns -- one table holds every slot's value; `MessageResult` names it.
-type Slot<Deps> = { handle(message: Message, deps: Deps): Promise<unknown> }['handle']
-type Subscription<Deps> = { handle(event: Event, deps: Deps): Promise<void> }['handle']
+type Slot<Deps> = { handle(message: DomainMessage, deps: Deps): Promise<unknown> }['handle']
+type Subscription<Deps> = { handle(event: DomainEvent, deps: Deps): Promise<void> }['handle']
 
 /**
  * The registry as the bus routes it: each table keyed by name. The app's names are unknown
@@ -64,10 +65,10 @@ type SlotValue<TSlots, TName extends string> = TName extends keyof TSlots
 
 /** The value `bus.handle(message)` resolves to: the slot's own return type, or void for an event. */
 export type MessageResult<
-  TMessage extends Message,
+  TMessage extends DomainMessage,
   TRegistry extends Handlers<never>,
-> = TMessage extends Command
+> = TMessage extends DomainCommand
   ? SlotValue<TRegistry['commands'], TMessage['name']>
-  : TMessage extends Query
+  : TMessage extends DomainQuery
     ? SlotValue<TRegistry['queries'], TMessage['name']>
     : void

package/src/application/unit-of-work.ts

@@ -1,7 +1,8 @@
+import type { MessageId } from '@/core'
+
 import type { IEventCollector } from './event-collector.ts'
 import { MessageAlreadyProcessedError } from './message-already-processed.error.ts'
 import type { IMessageStore } from './message-store.ts'
-import type { MessageId } from './messages.ts'
 import type { IOutboxRelay } from './outbox-relay.ts'
 import type { ITransaction } from './transaction.ts'
 

package/src/core/define-messages.ts

@@ -0,0 +1,136 @@
+import { v7 as uuidv7 } from 'uuid'
+import { z } from 'zod'
+
+import type { DomainCommand, DomainEvent, DomainQuery, MessageId } from './messages.ts'
+
+/** Payload schemas keyed by message name. A payload never carries `type`, `name`, or `id`. */
+export type PayloadSchemas = Readonly<Record<string, z.ZodType<object>>>
+
+/** An application's messages: one list of payload schemas per kind. */
+export type MessageDefinition = {
+  readonly commands: PayloadSchemas
+  readonly events: PayloadSchemas
+  readonly queries: PayloadSchemas
+}
+
+type AnyMessages = { readonly definition: MessageDefinition }
+type Def<Messages extends AnyMessages> = Messages['definition']
+type Payload<Schemas extends PayloadSchemas, Name extends keyof Schemas> = z.output<Schemas[Name]>
+
+/** Every command of an application: `CommandOf<typeof messages>`. */
+export type CommandOf<Messages extends AnyMessages> = {
+  [Name in keyof Def<Messages>['commands'] & string]: DomainCommand<Name> &
+    Payload<Def<Messages>['commands'], Name>
+}[keyof Def<Messages>['commands'] & string]
+
+/** Every event of an application: `EventOf<typeof messages>`. */
+export type EventOf<Messages extends AnyMessages> = {
+  [Name in keyof Def<Messages>['events'] & string]: DomainEvent<Name> &
+    Payload<Def<Messages>['events'], Name>
+}[keyof Def<Messages>['events'] & string]
+
+/** Every query of an application: `QueryOf<typeof messages>`. */
+export type QueryOf<Messages extends AnyMessages> = {
+  [Name in keyof Def<Messages>['queries'] & string]: DomainQuery<Name> &
+    Payload<Def<Messages>['queries'], Name>
+}[keyof Def<Messages>['queries'] & string]
+
+/** Every message of an application: what the registry and the bus are typed with. */
+export type MessageOf<Messages extends AnyMessages> =
+  | CommandOf<Messages>
+  | EventOf<Messages>
+  | QueryOf<Messages>
+
+/**
+ * What `defineMessages` returns. The factories build messages for in-process dispatch without
+ * parsing; the data is already typed. The schemas parse untrusted input at a boundary.
+ */
+export type AppMessages<Definition extends MessageDefinition> = {
+  readonly definition: Definition
+  /** Build a command. `id` defaults to a uuid v7; a webhook passes the provider's key, `stripe:event:evt_123`. */
+  createCommand<Name extends keyof Definition['commands'] & string>(
+    name: Name,
+    payload: Payload<Definition['commands'], Name>,
+    id?: MessageId,
+  ): DomainCommand<Name> & Payload<Definition['commands'], Name>
+  /** Build an event. `id` defaults to a uuid v7, which also orders it in time. */
+  createEvent<Name extends keyof Definition['events'] & string>(
+    name: Name,
+    payload: Payload<Definition['events'], Name>,
+    id?: MessageId,
+  ): DomainEvent<Name> & Payload<Definition['events'], Name>
+  /** Build a query. No id: nothing claims a read. */
+  createQuery<Name extends keyof Definition['queries'] & string>(
+    name: Name,
+    payload: Payload<Definition['queries'], Name>,
+  ): DomainQuery<Name> & Payload<Definition['queries'], Name>
+  readonly commandSchema: z.ZodType<CommandOf<AppMessages<Definition>>>
+  readonly eventSchema: z.ZodType<EventOf<AppMessages<Definition>>>
+  readonly querySchema: z.ZodType<QueryOf<AppMessages<Definition>>>
+  /** What a queue body may be: a command or an event. Queries never cross a queue. */
+  readonly queueSchema: z.ZodType<
+    CommandOf<AppMessages<Definition>> | EventOf<AppMessages<Definition>>
+  >
+}
+
+type RoutingField = 'type' | 'name' | 'id'
+
+/** A payload that declares a routing field maps to `never`, so `defineMessages` rejects it. */
+type WithoutRoutingFields<Schemas extends PayloadSchemas> = {
+  readonly [Name in keyof Schemas]: keyof z.output<Schemas[Name]> & RoutingField extends never
+    ? Schemas[Name]
+    : never
+}
+
+/** The compile-time rule: no payload of any kind declares `type`, `name`, or `id`. */
+type ValidDefinition<Definition extends MessageDefinition> = {
+  readonly commands: WithoutRoutingFields<Definition['commands']>
+  readonly events: WithoutRoutingFields<Definition['events']>
+  readonly queries: WithoutRoutingFields<Definition['queries']>
+}
+
+const MessageIdSchema = z.string().min(1)
+
+/** One full message schema: the routing fields joined to the payload. */
+function messageSchema(
+  type: 'command' | 'event' | 'query',
+  name: string,
+  payload: z.ZodType<object>,
+) {
+  const routing =
+    type === 'query'
+      ? z.object({ type: z.literal(type), name: z.literal(name) })
+      : z.object({ type: z.literal(type), name: z.literal(name), id: MessageIdSchema })
+  return routing.and(payload)
+}
+
+/** A union over every message of one kind. Empty when the application has none of that kind. */
+function unionOf(type: 'command' | 'event' | 'query', schemas: PayloadSchemas) {
+  return z.union(
+    Object.entries(schemas).map(([name, payload]) => messageSchema(type, name, payload)),
+  )
+}
+
+/**
+ * Define an application's messages once. The key is the name; the factories add the routing
+ * fields `type`, `name`, and `id`. A payload that declares one of them is a compile error.
+ */
+export function defineMessages<const Definition extends MessageDefinition>(
+  definition: Definition & ValidDefinition<Definition>,
+): AppMessages<Definition> {
+  const commandSchema = unionOf('command', definition.commands)
+  const eventSchema = unionOf('event', definition.events)
+  const querySchema = unionOf('query', definition.queries)
+  return {
+    definition,
+    createCommand: (name, payload, id = uuidv7()) => ({ ...payload, type: 'command', name, id }),
+    createEvent: (name, payload, id = uuidv7()) => ({ ...payload, type: 'event', name, id }),
+    createQuery: (name, payload) => ({ ...payload, type: 'query', name }),
+    commandSchema: commandSchema.pipe(z.custom<CommandOf<AppMessages<Definition>>>()),
+    eventSchema: eventSchema.pipe(z.custom<EventOf<AppMessages<Definition>>>()),
+    querySchema: querySchema.pipe(z.custom<QueryOf<AppMessages<Definition>>>()),
+    queueSchema: z
+      .union([commandSchema, eventSchema])
+      .pipe(z.custom<CommandOf<AppMessages<Definition>> | EventOf<AppMessages<Definition>>>()),
+  }
+}

package/src/core/entity.ts

@@ -0,0 +1,33 @@
+import type { DomainEvent } from './messages.ts'
+
+/** What an aggregate's plain data must have: an identity. A branded id keeps its brand. */
+export type EntityData = { readonly id: string }
+
+/**
+ * The base of an aggregate: its identity, the events it raised, and the plain data a repository
+ * stores. The subclass keeps its constructor private and declares `static restore(data: Data)`,
+ * the one door a repository rebuilds it through. A repository drains the events after `save`.
+ */
+export abstract class Entity<Data extends EntityData, TEvent extends DomainEvent = DomainEvent> {
+  private events: TEvent[] = []
+
+  abstract readonly id: Data['id']
+
+  /** Record one event with the state change that caused it. The unit of work commits both. */
+  protected addEvent(event: TEvent): void {
+    this.events.push(event)
+  }
+
+  /** A copy of the events raised since the last `clearEvents`. */
+  collectEvents(): ReadonlyArray<TEvent> {
+    return [...this.events]
+  }
+
+  /** Forget the raised events once the boundary has taken them. */
+  clearEvents(): void {
+    this.events = []
+  }
+
+  /** Plain data for the repository. The subclass's `restore(data)` accepts exactly this. */
+  abstract toPlainObject(): Data
+}

package/src/core/identity.ts

@@ -0,0 +1,29 @@
+import { v7 as uuidv7 } from 'uuid'
+import { z } from 'zod'
+
+/** A string only `create()` or `schema.parse()` of the same kind can produce. */
+export type Id<Brand extends string> = string & z.core.$brand<Brand>
+
+/** One id kind the application mints. `schema` parses untrusted input; `create` mints a uuid v7. */
+export type IdDefinition<Brand extends string> = {
+  readonly schema: z.core.$ZodBranded<z.ZodUUID, Brand>
+  /** Mint a new time-ordered id. No parse: we produced it, so it is valid by construction. */
+  create(): Id<Brand>
+}
+
+/** The id type of a definition: `type CallId = IdOf<typeof CallId>`. */
+export type IdOf<Definition extends IdDefinition<string>> = z.output<Definition['schema']>
+
+/**
+ * Define an id kind the application mints: `export const CallId = defineId('CallId')`.
+ * An id another system mints, such as a provider's call id, stays a plain branded schema.
+ */
+export function defineId<const Brand extends string>(brand: Brand): IdDefinition<Brand> {
+  const schema = z.uuidv7({ error: `Invalid ${brand}` })
+  return {
+    // SAFETY: `brand()` is type-only and returns a conditional TypeScript cannot reduce for a generic brand; for every literal it is this branded schema.
+    schema: schema.brand<Brand>() as z.core.$ZodBranded<z.ZodUUID, Brand>,
+    // SAFETY: uuidv7() always yields a valid v7 uuid, and the brand is a compile-time mark only.
+    create: () => uuidv7() as Id<Brand>,
+  }
+}

package/src/core/index.ts

@@ -32,6 +32,25 @@ export {
 } from './problem-details.ts'
 export { DatabaseError, type DatabaseFailure, type D1ConstraintKind } from './database.error.ts'
 export { notImplemented, unreachable } from './defects.ts'
+export { defineId, type Id, type IdDefinition, type IdOf } from './identity.ts'
+export {
+  defineMessages,
+  type AppMessages,
+  type CommandOf,
+  type EventOf,
+  type MessageDefinition,
+  type MessageOf,
+  type PayloadSchemas,
+  type QueryOf,
+} from './define-messages.ts'
+export type {
+  DomainCommand,
+  DomainEvent,
+  DomainMessage,
+  DomainQuery,
+  MessageId,
+} from './messages.ts'
+export { Entity, type EntityData } from './entity.ts'
 export {
   shouldRetryFailure,
   type FailureClassification,

package/src/{application → core}/messages.ts

@@ -8,24 +8,24 @@
 export type MessageId = string
 
 /** An action to perform. One handler, returns a value. The product adds its payload. */
-export type Command<Name extends string = string> = {
+export type DomainCommand<Name extends string = string> = {
   readonly type: 'command'
   readonly name: Name
   readonly id: MessageId
 }
 
 /** A request for data. One handler, returns a value. No id: nothing claims a read. */
-export type Query<Name extends string = string> = {
+export type DomainQuery<Name extends string = string> = {
   readonly type: 'query'
   readonly name: Name
 }
 
 /** A fact that happened. Zero or more subscribers, returns nothing. The product adds its payload. */
-export type Event<Name extends string = string> = {
+export type DomainEvent<Name extends string = string> = {
   readonly type: 'event'
   readonly name: Name
   readonly id: MessageId
 }
 
 /** The routing fields the bus reads. `type` selects the table, `name` selects the slot. */
-export type Message = Command | Event | Query
+export type DomainMessage = DomainCommand | DomainEvent | DomainQuery

package/src/infrastructure/cloudflare/base-d1-repository.ts

@@ -1,6 +1,6 @@
 import type { BatchItem } from 'drizzle-orm/batch'
 
-import type { Event } from '@/application'
+import type { DomainEvent } from '@/core'
 
 import type { DrizzleSchema } from '../drizzle-schema.ts'
 import { eventCollector, stageD1Statement } from '../unit-of-work-context.ts'
@@ -9,7 +9,7 @@ import type { D1Db } from './d1-database-types.ts'
 
 /** A domain aggregate that accumulates events for the unit of work to drain. */
 export interface AggregateEvents {
-  collectEvents(): ReadonlyArray<Event>
+  collectEvents(): ReadonlyArray<DomainEvent>
   clearEvents(): void
 }
 

package/src/infrastructure/cloudflare/d1-message-store.ts

@@ -1,11 +1,7 @@
 import { eq } from 'drizzle-orm'
 
-import {
-  MessageAlreadyProcessedError,
-  type Event,
-  type IMessageStore,
-  type MessageId,
-} from '@/application'
+import { MessageAlreadyProcessedError, type IMessageStore, type MessageId } from '@/application'
+import type { DomainEvent } from '@/core'
 
 import type { DrizzleSchema } from '../drizzle-schema.ts'
 import { BaseD1Repository } from './base-d1-repository.ts'
@@ -30,7 +26,7 @@ export class D1MessageStore<Schema extends DrizzleSchema>
     this.stage(this.db.insert(processedMessages).values({ messageId }))
   }
 
-  async persistEvents(events: ReadonlyArray<Event>): Promise<void> {
+  async persistEvents(events: ReadonlyArray<DomainEvent>): Promise<void> {
     if (events.length === 0) return
     this.stage(
       this.db

package/src/infrastructure/cloudflare/d1-schema.ts

@@ -1,7 +1,7 @@
 import { sql } from 'drizzle-orm'
 import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
 
-import type { Event } from '@/application'
+import type { DomainEvent } from '@/core'
 
 /** One row per committed message. The primary key is the idempotency claim. */
 export const processedMessages = sqliteTable(
@@ -20,7 +20,7 @@ export const messageOutbox = sqliteTable(
   'message_outbox',
   {
     id: text('id').primaryKey(),
-    payload: text('payload', { mode: 'json' }).$type<Event>().notNull(),
+    payload: text('payload', { mode: 'json' }).$type<DomainEvent>().notNull(),
     createdAt: integer('created_at', { mode: 'timestamp' })
       .notNull()
       .$defaultFn(() => new Date()),

package/src/infrastructure/postgres/base-postgres-repository.ts

@@ -1,4 +1,4 @@
-import type { Event } from '@/application'
+import type { DomainEvent } from '@/core'
 
 import type { DrizzleSchema } from '../drizzle-schema.ts'
 import { eventCollector } from '../unit-of-work-context.ts'
@@ -7,7 +7,7 @@ import type { PostgresDbTransaction } from './postgres-database-types.ts'
 
 /** A domain aggregate that accumulates events for the unit of work to drain. */
 export interface AggregateEvents {
-  collectEvents(): ReadonlyArray<Event>
+  collectEvents(): ReadonlyArray<DomainEvent>
   clearEvents(): void
 }
 

package/src/infrastructure/postgres/postgres-message-store.ts

@@ -1,9 +1,5 @@
-import {
-  MessageAlreadyProcessedError,
-  type Event,
-  type IMessageStore,
-  type MessageId,
-} from '@/application'
+import { MessageAlreadyProcessedError, type IMessageStore, type MessageId } from '@/application'
+import type { DomainEvent } from '@/core'
 
 import type { DrizzleSchema } from '../drizzle-schema.ts'
 import type { PostgresDbTransaction } from './postgres-database-types.ts'
@@ -23,7 +19,7 @@ export class PostgresMessageStore<Schema extends DrizzleSchema> implements IMess
     if (claimed.length === 0) throw new MessageAlreadyProcessedError(messageId)
   }
 
-  async persistEvents(events: ReadonlyArray<Event>): Promise<void> {
+  async persistEvents(events: ReadonlyArray<DomainEvent>): Promise<void> {
     if (events.length === 0) return
     await this.db
       .insert(messageOutbox)

package/src/infrastructure/postgres/postgres-schema.ts

@@ -1,7 +1,7 @@
 import { isNull } from 'drizzle-orm'
 import { index, integer, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core'
 
-import type { Event } from '@/application'
+import type { DomainEvent } from '@/core'
 
 /** One row per committed message. The primary key is the idempotency claim. */
 export const processedMessages = pgTable('processed_messages', {
@@ -14,7 +14,7 @@ export const messageOutbox = pgTable(
   'message_outbox',
   {
     id: text('id').primaryKey(),
-    payload: jsonb('payload').$type<Event>().notNull(),
+    payload: jsonb('payload').$type<DomainEvent>().notNull(),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     availableAt: timestamp('available_at', { withTimezone: true }).notNull().defaultNow(),
     attempts: integer('attempts').notNull().default(0),

package/src/infrastructure/tanstack/index.ts

@@ -10,3 +10,4 @@ export {
   type AuthCookieSource,
   type ErrorMiddlewareOptions,
 } from './error.middleware.ts'
+export { getLastUsedLoginMethod } from './last-login-method.ts'

package/src/infrastructure/tanstack/last-login-method.ts

@@ -0,0 +1,13 @@
+import { getRequestHeaders } from '@tanstack/react-start/server'
+import { parseCookies } from 'better-auth/cookies'
+
+// Better Auth keeps the plugin default private; this is the value LastLoginMethodOptions.cookieName documents.
+const DEFAULT_COOKIE_NAME = 'better-auth.last_used_login_method'
+
+/**
+ * Read the method this browser last signed in with from the current request, for the sign-in loader on the server.
+ * Pass `cookieName` only when `integrations.lastLoginMethod.cookieName` is set. Returns `null` when the cookie is absent.
+ */
+export function getLastUsedLoginMethod(cookieName = DEFAULT_COOKIE_NAME): string | null {
+  return parseCookies(getRequestHeaders().get('cookie') ?? '').get(cookieName) ?? null
+}

package/src/infrastructure/unit-of-work-context.ts

@@ -3,9 +3,10 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 import { panic } from 'better-result'
 import type { BatchItem } from 'drizzle-orm/batch'
 
-import { UnitOfWorkAlreadyActiveError, type Event, type IEventCollector } from '@/application'
+import { UnitOfWorkAlreadyActiveError, type IEventCollector } from '@/application'
+import type { DomainEvent } from '@/core'
 
-type UnitOfWorkContext = { readonly events: Event[] } & (
+type UnitOfWorkContext = { readonly events: DomainEvent[] } & (
   | { readonly database: 'd1'; readonly statements: BatchItem<'sqlite'>[] }
   | { readonly database: 'postgres' }
 )