@kronos-ts/app 0.1.0

package/src/components.ts

@@ -0,0 +1,48 @@
+import type { EventStore, SnapshotStore, TagResolver } from "@kronos-ts/eventsourcing"
+import type {
+  CommandBus,
+  QueryBus,
+  EventBus,
+  UoWRunner,
+  TokenStore,
+  TransactionManager,
+} from "@kronos-ts/messaging"
+import type { Serializer } from "@kronos-ts/common"
+
+/**
+ * Fixed slot interface. SLT-01: enumerates ALL 10 framework slots.
+ * No declaration merging, no string tokens — closed contract.
+ *
+ * Plan 09-01 (D-84): tokenStore + transactionManager added so persistence
+ * extensions (KronosDB, etc.) replace typed slots instead of routing through
+ * the deleted configurer's componentRegistry.
+ */
+export interface KronosComponents {
+  eventStore: EventStore
+  snapshotStore: SnapshotStore
+  commandBus: CommandBus
+  queryBus: QueryBus
+  eventBus: EventBus
+  serializer: Serializer
+  unitOfWorkFactory: UoWRunner
+  tagResolver: TagResolver
+  tokenStore: TokenStore
+  transactionManager: TransactionManager
+}
+
+/** Type-level: keyof KronosComponents — for verb signatures. */
+export type SlotName = keyof KronosComponents
+
+/** Sentinel listing every slot name; used by .start() to iterate slots and emit startup warnings. Order is stable for deterministic warning emission. */
+export const ALL_SLOTS: readonly SlotName[] = [
+  "eventStore",
+  "snapshotStore",
+  "commandBus",
+  "queryBus",
+  "eventBus",
+  "serializer",
+  "unitOfWorkFactory",
+  "tagResolver",
+  "tokenStore",
+  "transactionManager",
+] as const

package/src/decorator.ts

@@ -0,0 +1,88 @@
+import type { Resolved } from "./resolved.js"
+import type { KronosComponents, SlotName } from "./components.js"
+
+/**
+ * Slot-typed handle returned by `app.decorate()`. The `__slot` brand prevents
+ * cross-slot removal at compile time (DEC-03). `__id` is the runtime identity
+ * key used by `removeDecorator()` to locate the registration.
+ *
+ * Framework defaults expose pre-allocated handle constants on `Defaults` so
+ * users can write `app.removeDecorator(Defaults.commandBus.intercepting)`.
+ */
+export interface DecoratorHandle<K extends SlotName> {
+  readonly __slot: K
+  readonly __id: symbol
+  readonly __name: string
+}
+
+/**
+ * A decorator factory wraps the slot's resolved value. Polymorphic over the
+ * slot interface (DEC-04) — receives `KronosComponents[K]` and returns
+ * `KronosComponents[K]`. The `resolved` proxy is the same lazy proxy passed
+ * to slot factories (Phase 5 D-52); decorators may pull sibling slots through
+ * it (cycle detection covers this).
+ */
+export type DecoratorFactory<K extends SlotName> = (
+  inner: KronosComponents[K],
+  resolved: Resolved,
+) => KronosComponents[K]
+
+/**
+ * Internal accumulator entry. Stored on `AppState.decoratorRegistrations` in
+ * registration order — pipeline order at `.start()` is left-to-right
+ * (last registered = outermost wrap, per D-61 / DESIGN.md §8).
+ *
+ * `frameworkDefault` distinguishes framework-registered defaults (Plan 02)
+ * from user-registered decorators (D-62 — user decorators wrap OUTSIDE
+ * framework defaults). The `.start()` decoration step partitions on this
+ * field and applies framework defaults first (innermost), then user
+ * decorators (outermost).
+ */
+export interface DecoratorEntry<K extends SlotName = SlotName> {
+  readonly handle: DecoratorHandle<K>
+  readonly factory: DecoratorFactory<K>
+  readonly frameworkDefault: boolean
+}
+
+/**
+ * @internal — used by `Defaults` and by `kronos()` bootstrap (Plan 02) to
+ * mint pre-allocated framework-default handles with stable identity.
+ */
+export function makeFrameworkHandle<K extends SlotName>(
+  slot: K,
+  name: string,
+): DecoratorHandle<K> {
+  return Object.freeze({
+    __slot: slot,
+    __id: Symbol(`${slot}.${name}`),
+    __name: name,
+  }) as DecoratorHandle<K>
+}
+
+/**
+ * Apply all decorator registrations for a given slot in two passes:
+ * 1. Framework defaults first (innermost, handler-adjacent)
+ * 2. User decorators after (outer; last .decorate() = outermost wrap)
+ *
+ * Both passes iterate `registrations` in registration order so a
+ * left-to-right reduce composes correctly (each factory wraps the current value).
+ */
+export function applyDecorators<K extends SlotName>(
+  slot: K,
+  base: KronosComponents[K],
+  registrations: ReadonlyArray<DecoratorEntry>,
+  resolved: Resolved,
+): KronosComponents[K] {
+  let current = base
+  // Pass 1: framework defaults (innermost)
+  for (const reg of registrations) {
+    if (reg.handle.__slot !== slot || !reg.frameworkDefault) continue
+    current = (reg.factory as unknown as DecoratorFactory<K>)(current, resolved)
+  }
+  // Pass 2: user decorators (outer)
+  for (const reg of registrations) {
+    if (reg.handle.__slot !== slot || reg.frameworkDefault) continue
+    current = (reg.factory as unknown as DecoratorFactory<K>)(current, resolved)
+  }
+  return current
+}

package/src/defaults-handles.ts

@@ -0,0 +1,29 @@
+import { makeFrameworkHandle, type DecoratorHandle } from "./decorator.js"
+
+/**
+ * Global static module export — frozen handle identities for framework-default
+ * decorators (D-54). Per-app decorator state lives on `AppState`; `Defaults`
+ * only carries handle *identities*.
+ *
+ * Plan 02 wires the actual factories in `kronos()` bootstrap, keyed by these
+ * handles. Plan 01 ships the handle constants only — having them in place
+ * lets users write `app.removeDecorator(Defaults.commandBus.intercepting)`
+ * even before Plan 02 registers the factories (the call will throw
+ * `UnknownDecoratorHandleError` until Plan 02 lands, which is correct
+ * behavior for now and ratchets to the real removal once Plan 02 ships).
+ */
+export const Defaults = Object.freeze({
+  commandBus: Object.freeze({
+    intercepting: makeFrameworkHandle("commandBus", "intercepting"),
+  }),
+  queryBus: Object.freeze({
+    intercepting: makeFrameworkHandle("queryBus", "intercepting"),
+  }),
+  eventBus: Object.freeze({
+    intercepting: makeFrameworkHandle("eventBus", "intercepting"),
+  }),
+}) as {
+  readonly commandBus: { readonly intercepting: DecoratorHandle<"commandBus"> }
+  readonly queryBus: { readonly intercepting: DecoratorHandle<"queryBus"> }
+  readonly eventBus: { readonly intercepting: DecoratorHandle<"eventBus"> }
+}

package/src/defaults.ts

@@ -0,0 +1,64 @@
+import type { App } from "./app.js"
+import type { EventBus } from "@kronos-ts/messaging"
+import {
+  createInMemoryEventStore,
+  createInMemorySnapshotStore,
+  descriptorBasedTagResolver,
+} from "@kronos-ts/eventsourcing"
+import {
+  createSimpleCommandBus,
+  createSimpleQueryBus,
+  jsonSerializer,
+  runInNewUoW,
+  createInMemoryTokenStore,
+  noTransactionManager,
+} from "@kronos-ts/messaging"
+
+/**
+ * Register the 8 in-memory defaults (SLT-04, D-51).
+ * Slots flagged inMemory:true emit a startup warning at .start() unless the slot
+ * was overridden via .set/.forceSet (or another .setDefault won — but setDefault
+ * is ifAbsent, so only the FIRST setDefault wins; user setDefault calls on already-defaulted
+ * slots are no-ops, which is the intended SLT-02 semantics).
+ */
+export function registerInMemoryDefaults(app: App): void {
+  // Durability-flagged defaults (SLT-04 warning fires unless overridden):
+  app.setDefault("eventStore", () => createInMemoryEventStore(), {
+    inMemory: true,
+    warning: "[kronos] eventStore: in-memory — not durable, configure an extension for production",
+  })
+  app.setDefault("snapshotStore", () => createInMemorySnapshotStore(), {
+    inMemory: true,
+    warning: "[kronos] snapshotStore: in-memory — not durable, configure an extension for production",
+  })
+  app.setDefault("commandBus", () => createSimpleCommandBus(), {
+    inMemory: true,
+    warning: "[kronos] commandBus: in-memory — single-process only, configure an extension for distribution",
+  })
+  app.setDefault("queryBus", () => createSimpleQueryBus(), {
+    inMemory: true,
+    warning: "[kronos] queryBus: in-memory — single-process only, configure an extension for distribution",
+  })
+  // EventBus default: in ES setups EventStore IS the EventBus (configurer mirrors this at line 796)
+  app.setDefault("eventBus", ({ eventStore }) => eventStore as unknown as EventBus, {
+    inMemory: true,
+    warning: "[kronos] eventBus: in-memory — single-process only",
+  })
+
+  // Stateless / non-durability-implied defaults — NO inMemory flag, no warning emission:
+  app.setDefault("serializer", () => jsonSerializer())
+  app.setDefault("unitOfWorkFactory", () => runInNewUoW)
+  app.setDefault("tagResolver", () => descriptorBasedTagResolver())
+
+  // Plan 09-01 (D-84): typed slots for token persistence + transactional wrapping.
+  // Both default to in-memory — extensions (KronosDB, Drizzle/Knex/Kysely token stores,
+  // user-supplied TransactionManagers) override via app.set('tokenStore', ...) etc.
+  app.setDefault("tokenStore", () => createInMemoryTokenStore(), {
+    inMemory: true,
+    warning: "[kronos] tokenStore: in-memory — not durable, configure a persistence extension for production",
+  })
+  app.setDefault("transactionManager", () => noTransactionManager(), {
+    inMemory: true,
+    warning: "[kronos] transactionManager: in-memory — pass-through, configure a transactional extension for production",
+  })
+}

package/src/errors.ts

@@ -0,0 +1,62 @@
+import type { SlotName } from "./components.js"
+import type { DecoratorHandle } from "./decorator.js"
+
+/**
+ * Thrown when buildResolved detects a cycle: a factory's getter on Resolved re-enters
+ * a slot that is currently being resolved. (D-52 cycle-detection contract.)
+ */
+export class CircularSlotDependencyError extends Error {
+  readonly slot: SlotName
+  readonly chain: readonly SlotName[]
+  constructor(slot: SlotName, chain: readonly SlotName[]) {
+    super(`[kronos] Circular slot dependency: "${slot}" via [${chain.join(" → ")}]`)
+    this.name = "CircularSlotDependencyError"
+    this.slot = slot
+    this.chain = chain
+  }
+}
+
+/** Thrown when a Resolved getter touches a slot that has no registered factory. */
+export class SlotNotRegisteredError extends Error {
+  readonly slot: SlotName
+  constructor(slot: SlotName) {
+    super(`[kronos] Slot "${slot}" has no registered factory.`)
+    this.name = "SlotNotRegisteredError"
+    this.slot = slot
+  }
+}
+
+/**
+ * Thrown when `app.commandGateway` or `app.queryGateway` is accessed before
+ * the `register` lifecycle stage completes during `.start()`. Available inside
+ * `onStart('warmup'|'register'|'processors'|'serve', fn)` hooks AFTER register
+ * completes, and after `.start()` resolves. (Plan 08-01.)
+ */
+export class AppNotStartedError extends Error {
+  constructor(accessor: string) {
+    super(
+      `[kronos] App not started: ${accessor} is only accessible after register-stage completes during .start().`,
+    )
+    this.name = "AppNotStartedError"
+  }
+}
+
+/**
+ * Thrown by `app.removeDecorator(handle)` when the handle is not found in the
+ * app's registration list (D-59). Catches typos like
+ * `Defaults.commandBus.interceptingg` and removal of a handle that was never
+ * registered (e.g., framework default whose factory hasn't been wired yet).
+ */
+export class UnknownDecoratorHandleError extends Error {
+  readonly slot: SlotName
+  readonly handleName: string
+  constructor(handle: DecoratorHandle<SlotName>) {
+    super(
+      `[kronos] Unknown decorator handle "${handle.__name}" for slot "${handle.__slot}". ` +
+        `Either it was never registered or it was already removed.`,
+    )
+    this.name = "UnknownDecoratorHandleError"
+    this.slot = handle.__slot
+    this.handleName = handle.__name
+  }
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export type { KronosComponents, SlotName } from "./components.js"
+export { ALL_SLOTS } from "./components.js"
+export { CircularSlotDependencyError, SlotNotRegisteredError } from "./errors.js"
+export { SlotRegistry, type SlotMeta, type SlotEntry, type SlotFactory } from "./slot-registry.js"
+export { buildResolved, type Resolved } from "./resolved.js"
+export {
+  createWarningChannel,
+  type WarningLogger,
+  type WarningChannelOptions,
+  type WarningChannel,
+} from "./warnings.js"
+export {
+  AppImpl,
+  AppAlreadyStartedError,
+  type App,
+  type RunningApp,
+  type Extension,
+  type AppState,
+  type AppImplOptions,
+  type KronosIdentity,
+} from "./app.js"
+export { registerInMemoryDefaults } from "./defaults.js"
+export { kronos, type KronosPartialConfig } from "./kronos.js"
+export {
+  type DecoratorHandle,
+  type DecoratorFactory,
+  type DecoratorEntry,
+  applyDecorators,
+} from "./decorator.js"
+export { Defaults } from "./defaults-handles.js"
+export { UnknownDecoratorHandleError, AppNotStartedError } from "./errors.js"
+export type { LifecycleStage, LifecycleHook } from "./lifecycle.js"
+// Plan 09-01 Task 1: re-export of typed-slot interfaces so extension packages don't
+// need to deep-import from @kronos-ts/messaging just to set/replace slots.
+export type { TokenStore, TransactionManager } from "@kronos-ts/messaging"
+// Plan 09-01 Task 2: handler enhancer + entities() tuple-shape types.
+export type { HandlerEnhancerDefinition } from "@kronos-ts/messaging"
+export type { StateOptions, StatesArg } from "./app.js"

package/src/kronos.ts

@@ -0,0 +1,117 @@
+import type { StateModule } from "@kronos-ts/modelling"
+import type {
+  CommandHandlerDefinition,
+  QueryHandlerDefinition,
+  EventProcessorModule,
+} from "@kronos-ts/messaging"
+import {
+  createInterceptingCommandBus,
+  createInterceptingQueryBus,
+  createInterceptingEventBus,
+} from "@kronos-ts/messaging"
+import { AppImpl, type App } from "./app.js"
+import { registerInMemoryDefaults } from "./defaults.js"
+import { createWarningChannel, type WarningLogger } from "./warnings.js"
+import { Defaults } from "./defaults-handles.js"
+
+/**
+ * Partial-config shorthand options for kronos(). APP-02.
+ *
+ * Domain registrations passed here are appended to the same internal accumulators
+ * as fluent .states()/.commands()/etc. calls. quiet/logger configure the warning
+ * channel BEFORE in-memory defaults are registered.
+ */
+export interface KronosPartialConfig {
+  states?: StateModule[]
+  commands?: CommandHandlerDefinition<any, any>[]
+  queries?: QueryHandlerDefinition[]
+  processors?: EventProcessorModule[]
+  quiet?: boolean
+  logger?: WarningLogger
+  /** Stable logical service/application name. Same across replicas. */
+  serviceName?: string
+  /** Unique physical runtime instance id. Different per process/pod. */
+  instanceId?: string
+  /**
+   * Per-stage timeout (ms) for native lifecycle execution (D-77).
+   * If a single stage exceeds this, AppImpl emits a warning and continues
+   * to the next stage WITHOUT cancelling the slow hooks (warn-then-continue).
+   *
+   * Default: 5000.
+   */
+  stageTimeoutMs?: number
+}
+
+/**
+ * Create a new Kronos App.
+ *
+ * ```typescript
+ * const app = await kronos()
+ *   .states(Course)
+ *   .commands(createCourseHandler)
+ *   .start()
+ *
+ * await app.commandGateway.send(CreateCourse, { courseId: "cs-101", name: "Intro" }, emptyMetadata())
+ * ```
+ *
+ * Or with a partial config (APP-02):
+ *
+ * ```typescript
+ * const app = await kronos({ states: [Course], commands: [createCourseHandler], quiet: true }).start()
+ * ```
+ */
+export function kronos(partial?: KronosPartialConfig): App {
+  const warningChannel = createWarningChannel({ quiet: partial?.quiet, logger: partial?.logger })
+  const app = new AppImpl({
+    warningChannel,
+    stageTimeoutMs: partial?.stageTimeoutMs,
+    serviceName: partial?.serviceName,
+    instanceId: partial?.instanceId,
+  })
+
+  // Register in-memory defaults FIRST so user partial-config / fluent calls override them
+  // via set/forceSet (setDefault is ifAbsent — first registration wins).
+  registerInMemoryDefaults(app)
+
+  // Register framework-default `intercepting` decorators for the 3 buses (DEC-02, D-57).
+  // Each closure reads `app._state.{bus}DispatchInterceptors` + `app._state.handlerInterceptors`
+  // at decoration time (i.e., during .start()) — extensions and user code populate these
+  // arrays before .start() runs, so the snapshot is complete by the time the closure fires.
+  // Removable via `removeDecorator(Defaults.{bus}.intercepting)`.
+  app._registerFrameworkDefaultDecorator(
+    Defaults.commandBus.intercepting,
+    (inner, _resolved) => {
+      const wrapped = createInterceptingCommandBus(inner)
+      for (const fn of app._state.commandDispatchInterceptors) wrapped.registerDispatchInterceptor(fn)
+      for (const fn of app._state.handlerInterceptors) wrapped.registerHandlerInterceptor(fn)
+      return wrapped
+    },
+  )
+  app._registerFrameworkDefaultDecorator(
+    Defaults.queryBus.intercepting,
+    (inner, _resolved) => {
+      const wrapped = createInterceptingQueryBus(inner)
+      for (const fn of app._state.queryDispatchInterceptors) wrapped.registerDispatchInterceptor(fn)
+      for (const fn of app._state.handlerInterceptors) wrapped.registerHandlerInterceptor(fn)
+      return wrapped
+    },
+  )
+  app._registerFrameworkDefaultDecorator(
+    Defaults.eventBus.intercepting,
+    (inner, _resolved) => {
+      // EventBus intercepting wrapper takes its dispatch interceptors at construction time;
+      // it has no register* methods and no handler interceptor concept (verified
+      // packages/messaging/src/intercepting-event-bus.ts — no handlerInterceptors field).
+      // Snapshot the array at decoration time; mutations after .start() are blocked
+      // by the AppAlreadyStartedError guard on `eventDispatchInterceptor()`.
+      return createInterceptingEventBus(inner, [...app._state.eventDispatchInterceptors])
+    },
+  )
+
+  if (partial?.states) app.states(...partial.states)
+  if (partial?.commands) app.commands(...partial.commands)
+  if (partial?.queries) app.queries(...partial.queries)
+  if (partial?.processors) app.processors(...partial.processors)
+
+  return app
+}

package/src/lifecycle.ts

@@ -0,0 +1,33 @@
+/**
+ * Typed lifecycle stages for app-level startup/shutdown hooks (LIF-01).
+ *
+ * Forward order on `.start()`: connect → warmup → register → processors → serve.
+ * Reverse order on `.stop()`:  serve → processors → register → warmup → connect.
+ *
+ * Within a single stage, hooks execute in registration order (no `{stage, order}`
+ * tiebreaker — D-70 defers it until a real consumer asks).
+ *
+ * Closed string union by design (LIF-01). NOT extensible via declaration merging.
+ */
+export type LifecycleStage = "connect" | "register" | "warmup" | "processors" | "serve"
+
+/**
+ * Hook signature for `app.onStart(stage, fn)` / `app.onStop(stage, fn)` (LIF-02, D-69).
+ *
+ * Bare zero-arg shape. Extensions close over their own state from the enclosing
+ * `(app: App) => void` extension scope (see DESIGN.md §12 KronosDB pattern).
+ *
+ * Why no `Resolved` arg: the Resolved proxy exists for slot-factory composition
+ * (Phase 5 D-52); lifecycle hooks are a different concern.
+ *
+ * Why no `Configuration` arg: matching the legacy `LifecycleHandler(config?: any)`
+ * signature would couple this public type to the configurer's `Configuration` —
+ * a Phase 8 deletion target.
+ */
+export type LifecycleHook = () => void | Promise<void>
+
+// Plan 08-03a (D-77): the legacy numeric-phase mapping is deleted. Native
+// AppImpl.start() executes typed-stage hooks directly off
+// AppState.startHooks/stopHooks — no numeric-phase bridge to the legacy
+// LifecycleRegistry. Plan 03b's enhancer-bridge keeps a private inverted copy
+// locally for the D-81 fallback path.

package/src/resolved.ts

@@ -0,0 +1,54 @@
+import type { KronosComponents, SlotName } from "./components.js"
+import { CircularSlotDependencyError, SlotNotRegisteredError } from "./errors.js"
+import type { SlotRegistry } from "./slot-registry.js"
+
+/**
+ * Resolved is structurally identical to KronosComponents — the destructured arg
+ * passed to factories. We re-export the alias so user code reads `Resolved` not `KronosComponents`.
+ */
+export type Resolved = KronosComponents
+
+/**
+ * Build a lazy + memoized Resolved Proxy backed by the registry. (D-52.)
+ *
+ * - Each property access invokes the slot's factory once and memoizes
+ * - Factories receive the same proxy as their argument so dependency chains compose
+ * - A `resolving` Set detects cycles: if a getter is hit while its slot is mid-resolution,
+ *   throw CircularSlotDependencyError with the offending chain
+ * - try/finally ensures `resolving` is cleaned even after errors so subsequent accesses still work
+ */
+export function buildResolved(registry: SlotRegistry): Resolved {
+  const cache = new Map<SlotName, unknown>()
+  const resolving = new Set<SlotName>()
+  const resolvingOrder: SlotName[] = []
+
+  const handler: ProxyHandler<object> = {
+    get(_target, prop) {
+      const slot = prop as SlotName
+      if (cache.has(slot)) return cache.get(slot)
+
+      if (resolving.has(slot)) {
+        throw new CircularSlotDependencyError(slot, [...resolvingOrder, slot])
+      }
+
+      const entry = registry.getEntry(slot)
+      if (!entry) {
+        throw new SlotNotRegisteredError(slot)
+      }
+
+      resolving.add(slot)
+      resolvingOrder.push(slot)
+      try {
+        const value = entry.factory(proxy as Resolved)
+        cache.set(slot, value)
+        return value
+      } finally {
+        resolving.delete(slot)
+        resolvingOrder.pop()
+      }
+    },
+  }
+
+  const proxy = new Proxy({}, handler) as Resolved
+  return proxy
+}

package/src/slot-registry.ts

@@ -0,0 +1,89 @@
+import type { KronosComponents, SlotName } from "./components.js"
+
+/**
+ * Optional metadata attached to a slot entry. Today the only field is
+ * `inMemory` + `warning` (D-51) — used by Plan 02 to emit startup warnings
+ * for any slot still using a flagged in-memory default at .start() time.
+ */
+export interface SlotMeta {
+  inMemory?: true
+  warning?: string
+}
+
+/** Each slot's resolution callable: a factory that takes the destructured Resolved and returns the component. */
+export type SlotFactory<K extends SlotName> = (resolved: KronosComponents) => KronosComponents[K]
+
+/** A registered slot entry: normalized factory + optional meta. */
+export interface SlotEntry<K extends SlotName = SlotName> {
+  factory: SlotFactory<K>
+  meta?: SlotMeta
+}
+
+/**
+ * Normalize a factory-or-instance argument into a SlotFactory.
+ * SLT-03: plain instances (non-function values) become `() => instance` internally.
+ */
+function normalizeFactory<K extends SlotName>(
+  factoryOrInstance: SlotFactory<K> | KronosComponents[K],
+): SlotFactory<K> {
+  if (typeof factoryOrInstance === "function") {
+    return factoryOrInstance as SlotFactory<K>
+  }
+  const instance = factoryOrInstance
+  return () => instance
+}
+
+/**
+ * SlotRegistry — the storage backing the App's three verbs.
+ * setDefault: ifAbsent (no-op if occupied)
+ * set:        warn on double-set
+ * forceSet:   silent overwrite
+ * (DESIGN.md §6, REQUIREMENTS.md SLT-02.)
+ */
+export class SlotRegistry {
+  private readonly slots = new Map<SlotName, SlotEntry>()
+
+  setDefault<K extends SlotName>(
+    slot: K,
+    factoryOrInstance: SlotFactory<K> | KronosComponents[K],
+    meta?: SlotMeta,
+  ): void {
+    if (this.slots.has(slot)) return
+    this.slots.set(slot, { factory: normalizeFactory(factoryOrInstance) as SlotFactory<SlotName>, meta })
+  }
+
+  set<K extends SlotName>(
+    slot: K,
+    factoryOrInstance: SlotFactory<K> | KronosComponents[K],
+  ): void {
+    const existing = this.slots.get(slot)
+    // Provenance check: setDefault always writes a `meta` key (even when its value
+    // is undefined for stateless defaults like serializer / unitOfWorkFactory / tagResolver);
+    // set / forceSet never write the key at all. So `"meta" in existing` identifies a prior
+    // setDefault — those overrides are the expected "extension overrides in-memory default" path
+    // and should NOT warn. Genuine collisions (two set/forceSet calls on the same slot) DO warn.
+    if (existing && !("meta" in existing)) {
+      console.warn(
+        `[kronos] slot "${slot}" override: already set. Use forceSet() to suppress this warning.`,
+      )
+    }
+    this.slots.set(slot, { factory: normalizeFactory(factoryOrInstance) as SlotFactory<SlotName> })
+  }
+
+  forceSet<K extends SlotName>(
+    slot: K,
+    factoryOrInstance: SlotFactory<K> | KronosComponents[K],
+  ): void {
+    this.slots.set(slot, { factory: normalizeFactory(factoryOrInstance) as SlotFactory<SlotName> })
+  }
+
+  /** @internal — used by buildResolved and by Plan 02's warning emitter. */
+  getEntry<K extends SlotName>(slot: K): SlotEntry<K> | undefined {
+    return this.slots.get(slot) as SlotEntry<K> | undefined
+  }
+
+  /** @internal — used by Plan 02 to iterate registered slots for startup warnings. */
+  has(slot: SlotName): boolean {
+    return this.slots.has(slot)
+  }
+}

package/src/warnings.ts

@@ -0,0 +1,32 @@
+/**
+ * Smallest viable logger interface (D-51) — just `warn(msg: string)`.
+ * Phase 5 only emits startup warnings for in-memory defaults; richer levels
+ * are intentionally NOT in scope.
+ */
+export interface WarningLogger {
+  warn(msg: string): void
+}
+
+export interface WarningChannelOptions {
+  /** When true, suppress all warnings (kronos({ quiet: true })). */
+  quiet?: boolean
+  /** When set, route warnings here instead of console.warn. `quiet` takes precedence over `logger`. */
+  logger?: WarningLogger
+}
+
+export interface WarningChannel {
+  emit(msg: string): void
+}
+
+export function createWarningChannel(options: WarningChannelOptions = {}): WarningChannel {
+  return {
+    emit(msg: string): void {
+      if (options.quiet) return
+      if (options.logger) {
+        options.logger.warn(msg)
+        return
+      }
+      console.warn(msg)
+    },
+  }
+}