@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/entity/define-entity.ts

@@ -0,0 +1,157 @@
+import type { z } from "zod";
+import type { Actor } from "@checkstack/common";
+
+/**
+ * Plugin-owned read accessor (Model B). A kind declares where its CURRENT
+ * state lives by supplying a batched reader: given a set of ids, return the
+ * current state for each (missing ids omitted). The state may come from the
+ * plugin's own table, an in-memory map, or a computed value. `defineEntity`
+ * NEVER stores a copy of its own — it only makes the plugin's state reactive.
+ *
+ * This is the single source of truth for `get` / `getMany`, scope
+ * enrichment, the reactive `wait_until` wake re-eval, and the prev-snapshot
+ * taken by `handle.mutate` before each write.
+ */
+export type EntityRead<TState extends Record<string, unknown>> = (
+  ids: ReadonlyArray<string>,
+) => Promise<Record<string, TState>>;
+
+export interface DefineEntityInput<TState extends Record<string, unknown>> {
+  /** Globally-unique entity kind (e.g. "incident", "maintenance", "health"). */
+  kind: string;
+  /**
+   * zod = single source of truth: typing, validation, scope projection,
+   * UI/editor introspection, change-event shape. MUST be a z.object.
+   */
+  state: z.ZodObject<z.ZodRawShape> & z.ZodType<TState>;
+  /**
+   * Plugin-owned current-state accessor (Model B). REQUIRED: `defineEntity`
+   * owns NO current-state storage; this reader is the only path to current
+   * state and the prev-snapshot for diffs.
+   */
+  read: EntityRead<TState>;
+}
+
+/** Mutation context so change events carry the causing actor (§3.1). */
+export interface EntityMutationOpts {
+  /** Defaults to the system actor when omitted. */
+  actor?: Actor;
+  /** Run id, when the mutation originates inside a dispatch run (masking). */
+  runId?: string;
+}
+
+/**
+ * The single driven mutation entry point (Model B). The handle:
+ *
+ *   1. snapshots `prev` via the kind's `read` accessor BEFORE the write
+ *      (so a change is structurally impossible to miss),
+ *   2. runs `apply()` — the plugin's ACTUAL write against ITS OWN storage,
+ *      committed in the PLUGIN's own transaction. `apply` returns the
+ *      resulting current state (`next`),
+ *   3. AFTER the plugin write has committed, diffs prev → next and, on a real
+ *      diff, appends the field-level transition rows to `entity_transitions`
+ *      in the FRAMEWORK's own transaction (a separate db/client),
+ *   4. emits `ENTITY_CHANGED` AFTER the plugin write has committed (never on a
+ *      rolled-back / throwing write).
+ *
+ * Cross-plugin transaction boundary (the deliberate Model B tradeoff): a
+ * plugin-backed kind keeps its state in its OWN schema, behind its OWN drizzle
+ * client — a DIFFERENT client than automation-backend's `entity_transitions`.
+ * Two different clients cannot share one transaction, so `apply` does NOT
+ * receive the framework tx; it owns its own. The framework appends the
+ * transition log in a SEPARATE transaction AFTER the plugin write commits.
+ *
+ * Consequences, by design:
+ *   - The plugin write is the source of truth. If it throws, NOTHING is
+ *     appended and NOTHING is emitted (the change never happened).
+ *   - `prev` is snapshotted BEFORE `apply`, so the diff is always correct even
+ *     when `read` and `apply` touch the same rows.
+ *   - The transition-log append is best-effort-after-commit: if the framework
+ *     append throws after a committed plugin write, the plugin state is still
+ *     correct but that one transition row is missing (a history gap, never a
+ *     state corruption). This is the accepted cost of decoupling plugin writes
+ *     from framework-internal tables — a plugin platform must NOT couple a
+ *     plugin's storage to a framework table's transaction.
+ */
+export interface MutateInput<TState extends Record<string, unknown>> {
+  id: string;
+  opts?: EntityMutationOpts;
+  /**
+   * The plugin's write, committed in the PLUGIN's own transaction. Takes no
+   * arguments: the plugin owns its db/tx and must NOT receive the framework
+   * tx (different client). MUST return the resulting current state (`next`)
+   * so the handle can diff without a second read.
+   */
+  apply: () => Promise<TState>;
+}
+
+/**
+ * Driven tombstone entry point. Same orchestration as {@link MutateInput},
+ * but `next` is `null` (the entity is removed). `apply` performs the plugin's
+ * delete in the plugin's own transaction; the handle records the tombstone
+ * transition (framework tx) and emits the tombstone change AFTER the delete
+ * has committed.
+ */
+export interface RemoveInput {
+  id: string;
+  opts?: EntityMutationOpts;
+  /** The plugin's delete, committed in the plugin's own transaction. */
+  apply: () => Promise<void>;
+}
+
+export interface EntityHandle<TState extends Record<string, unknown>> {
+  readonly kind: string;
+  /**
+   * The single driven mutation entry point (Model B). Snapshots prev via
+   * `read`, runs `apply()` (the plugin's own write, committed in the plugin's
+   * own tx), then appends transitions in the framework's own tx and emits
+   * `ENTITY_CHANGED` — both AFTER the plugin write commits. No-op (no emit,
+   * no transition) when `apply` returns a structurally-equal state. Returns
+   * the resulting state.
+   */
+  mutate(input: MutateInput<TState>): Promise<TState>;
+  /**
+   * Driven tombstone (Model B). Snapshots prev via `read`, runs `apply()`
+   * (the plugin delete, committed in the plugin's own tx), records the
+   * tombstone transition (framework tx), emits a tombstone `ENTITY_CHANGED`
+   * (next = null) after the delete commits. No-op when the entity was already
+   * absent.
+   */
+  remove(input: RemoveInput): Promise<void>;
+  /** Current state by id (routes to `read`). */
+  get(id: string): Promise<TState | undefined>;
+  /** Batched current-state read (routes to `read`). Missing ids omitted. */
+  getMany(ids: ReadonlyArray<string>): Promise<Record<string, TState>>;
+  /** Transition helpers — generalize Phase 13's health transitions to any entity. */
+  inStateSince(id: string, field: keyof TState & string): Promise<Date | null>;
+  inStateForMs(id: string, field: keyof TState & string): Promise<number>;
+  transitionCount(args: {
+    id: string;
+    field: keyof TState & string;
+    windowMs: number;
+  }): Promise<number>;
+}
+
+export type DefineEntity = <TState extends Record<string, unknown>>(
+  input: DefineEntityInput<TState>,
+) => EntityHandle<TState>;
+
+/**
+ * Escape-hatch declaration — data that looks like state but is
+ * intentionally NOT a reactive entity (reactive automation engine §5,
+ * §15.6). Recorded in a registry; the lint rule (a later phase) consumes
+ * these declarations to suppress false positives on declared-non-reactive
+ * tables.
+ */
+export interface DeclareNonReactiveStateInput {
+  /** Drizzle table object name or table name the data lives in. */
+  table: string;
+  /** One of the §5 classes — forces the author to pick a reason. */
+  reason: "raw-sample" | "sensitive" | "externally-owned" | "bookkeeping";
+  /** Free-text justification surfaced in the lint message + docs. */
+  note: string;
+}
+
+export type DeclareNonReactiveState = (
+  input: DeclareNonReactiveStateInput,
+) => void;

package/src/entity/diff.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "bun:test";
+import { diffEntityState } from "./diff";
+
+describe("diffEntityState", () => {
+  it("reports added fields on create (prev null)", () => {
+    const { changedFields, delta } = diffEntityState({
+      prev: null,
+      next: { status: "open", severity: "high" },
+    });
+    expect(changedFields).toEqual(["severity", "status"]);
+    expect(delta).toEqual({ status: "open", severity: "high" });
+  });
+
+  it("reports only the changed field on a value change", () => {
+    const { changedFields, delta } = diffEntityState({
+      prev: { status: "open", severity: "high" },
+      next: { status: "resolved", severity: "high" },
+    });
+    expect(changedFields).toEqual(["status"]);
+    expect(delta).toEqual({ status: "resolved" });
+  });
+
+  it("reports a dropped field as null in the delta", () => {
+    const { changedFields, delta } = diffEntityState({
+      prev: { status: "open", note: "x" },
+      next: { status: "open" },
+    });
+    expect(changedFields).toEqual(["note"]);
+    expect(delta).toEqual({ note: null });
+  });
+
+  it("returns empty when structurally unchanged (key order, nesting)", () => {
+    const { changedFields, delta } = diffEntityState({
+      prev: { a: 1, nested: { x: 1, y: 2 } },
+      next: { nested: { y: 2, x: 1 }, a: 1 },
+    });
+    expect(changedFields).toEqual([]);
+    expect(delta).toEqual({});
+  });
+
+  it("detects nested object changes", () => {
+    const { changedFields, delta } = diffEntityState({
+      prev: { window: { startAt: "1", endAt: "2" } },
+      next: { window: { startAt: "1", endAt: "3" } },
+    });
+    expect(changedFields).toEqual(["window"]);
+    expect(delta).toEqual({ window: { startAt: "1", endAt: "3" } });
+  });
+
+  it("detects array changes", () => {
+    const { changedFields } = diffEntityState({
+      prev: { systemIds: ["a", "b"] },
+      next: { systemIds: ["a", "b", "c"] },
+    });
+    expect(changedFields).toEqual(["systemIds"]);
+  });
+});

package/src/entity/diff.ts

@@ -0,0 +1,54 @@
+import { structurallyEqual } from "./stable-stringify";
+
+/**
+ * Per-field structural diff between a prior and next entity state.
+ *
+ * Fields are the top-level keys of the (zod-object) state. A field is
+ * "changed" when its value is not structurally equal across prev/next —
+ * this covers added keys (prev absent), removed keys (next absent, value
+ * becomes `null` in the delta), and value changes (including nested object
+ * / array mutations compared structurally).
+ *
+ * `delta` carries only the changed fields' NEXT values (or `null` for a
+ * field that was dropped), mirroring the `EntityChangedSchema.delta` shape
+ * ("changed fields only").
+ */
+export interface EntityDiff {
+  /** Sorted list of changed top-level field names. */
+  changedFields: string[];
+  /** Changed fields only → their next value (or `null` when removed). */
+  delta: Record<string, unknown>;
+}
+
+export function diffEntityState(args: {
+  prev: Record<string, unknown> | null;
+  next: Record<string, unknown> | null;
+}): EntityDiff {
+  const { prev, next } = args;
+  const prevObj = prev ?? {};
+  const nextObj = next ?? {};
+
+  const keys = new Set<string>([
+    ...Object.keys(prevObj),
+    ...Object.keys(nextObj),
+  ]);
+
+  const changedFields: string[] = [];
+  const delta: Record<string, unknown> = {};
+
+  for (const key of keys) {
+    const prevHas = Object.prototype.hasOwnProperty.call(prevObj, key);
+    const nextHas = Object.prototype.hasOwnProperty.call(nextObj, key);
+    const prevVal = prevHas ? prevObj[key] : undefined;
+    const nextVal = nextHas ? nextObj[key] : undefined;
+
+    if (structurallyEqual(prevVal, nextVal)) continue;
+
+    changedFields.push(key);
+    // A dropped field surfaces as `null` so the delta is JSON-serializable
+    // and the change event records the removal explicitly.
+    delta[key] = nextHas ? nextVal : null;
+  }
+
+  return { changedFields: changedFields.toSorted(), delta };
+}

package/src/entity/entity-store.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "bun:test";
+import { serializeFieldValue } from "./entity-store";
+
+// The drizzle-backed `createEntityStore` is thin glue over the query
+// builder (each method maps ~1:1 to a statement); its observable behavior
+// is exercised end-to-end through the in-memory `FakeEntityStore` + handle
+// tests, and pinned against real Postgres by the Phase-1 integration lane.
+// `serializeFieldValue` carries the only standalone logic — the transition
+// log's value normalization — so it is tested directly here.
+describe("serializeFieldValue", () => {
+  it("passes strings through verbatim (no JSON quotes)", () => {
+    expect(serializeFieldValue("open")).toBe("open");
+  });
+
+  it("renders null / undefined as the literal 'null'", () => {
+    expect(serializeFieldValue(null)).toBe("null");
+    expect(serializeFieldValue(undefined)).toBe("null");
+  });
+
+  it("JSON-encodes non-string scalars and structures", () => {
+    expect(serializeFieldValue(42)).toBe("42");
+    expect(serializeFieldValue(true)).toBe("true");
+    expect(serializeFieldValue(["a", "b"])).toBe('["a","b"]');
+    expect(serializeFieldValue({ x: 1 })).toBe('{"x":1}');
+  });
+
+  it("is stable for the same string value (powers inStateSince matching)", () => {
+    expect(serializeFieldValue("resolved")).toBe(serializeFieldValue("resolved"));
+  });
+});

package/src/entity/entity-store.ts

@@ -0,0 +1,171 @@
+/**
+ * Framework transition store — the kind-agnostic, plugin-storage-agnostic
+ * persistence layer behind every `defineEntity` handle (Model B, reactive
+ * automation engine §15.1 reshaped).
+ *
+ * In Model B `defineEntity` owns NO current-state storage of its own. The
+ * plugin owns its state and reads it through a `read` accessor; this store
+ * owns only two universal concerns:
+ *
+ *   1. The framework TRANSACTION used to append the `entity_transitions`
+ *      rows. This wraps ONLY the post-commit transition append — the plugin's
+ *      `apply` write is NOT driven inside it. The plugin's reactive-state
+ *      write is a different schema behind a different drizzle client, so it
+ *      cannot share this transaction; the handle runs `apply` FIRST (it
+ *      commits in the plugin's own tx), then opens this framework tx solely to
+ *      append the transition rows. The plugin write and the transition append
+ *      therefore do NOT commit atomically together — a deliberate cross-plugin
+ *      non-atomic boundary: the plugin write is authoritative, and a failure
+ *      between the two leaves correct plugin state with at most a missing
+ *      history row (a gap, never a corruption). Full rationale in
+ *      `define-entity.ts` (the "Cross-plugin transaction boundary" note).
+ *   2. The transition-LOG read helpers (`inStateSince` / `transitionCount`)
+ *      that power `inStateSince` / `inStateForMs` / `transitionCount`.
+ *
+ * Every kind owns its current-state storage and exposes it through a `read`
+ * accessor; this store touches only `entity_transitions`.
+ */
+import { and, desc, eq, gte, sql } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+
+import { entityTransitions } from "../schema";
+
+type Schema = {
+  entityTransitions: typeof entityTransitions;
+};
+
+/**
+ * The transaction handle the store opens for the framework's transition
+ * append. It is the drizzle transaction object for the automation-backend
+ * schema, used ONLY to append `entity_transitions` rows after the plugin's
+ * `apply` has already committed (Model B). It is NOT passed to the plugin's
+ * `apply`; the plugin write runs in its own client/tx and does not share this
+ * one.
+ */
+export type EntityTx = Parameters<
+  Parameters<SafeDatabase<Schema>["transaction"]>[0]
+>[0];
+
+/** A transition row to append when a tracked field changes. */
+export interface TransitionAppend {
+  field: string;
+  fromValue: string | null;
+  toValue: string;
+}
+
+/**
+ * The kind-agnostic transition store. A `defineEntity` handle binds a single
+ * `kind` and forwards to these methods.
+ */
+export interface EntityStore {
+  /**
+   * Run `fn` inside ONE framework database transaction, passing it the
+   * transaction handle. The handle uses this ONLY to append the
+   * `entity_transitions` rows AFTER the plugin's `apply` has already committed
+   * (in the plugin's own tx). The plugin write is NOT driven inside this
+   * transaction — it cannot be, since it lives behind a different client (the
+   * non-atomic cross-plugin boundary; see the file docblock and
+   * `define-entity.ts`). The post-commit change emit is done by the handle
+   * AFTER this resolves.
+   */
+  runInTransaction<R>(fn: (tx: EntityTx) => Promise<R>): Promise<R>;
+
+  /**
+   * Append transition rows on the framework transaction opened by
+   * `runInTransaction`. This is a post-commit framework write: the plugin's
+   * reactive-state write has ALREADY committed separately, so these rows do
+   * NOT commit atomically with it (the deliberate non-atomic boundary above).
+   */
+  appendTransitions(args: {
+    tx: EntityTx;
+    kind: string;
+    entityId: string;
+    transitions: ReadonlyArray<TransitionAppend>;
+  }): Promise<void>;
+
+  /**
+   * Most-recent transition INTO `currentValue` for `field`, i.e. "in this
+   * value since" — the timestamp of the latest row whose `toValue` matches
+   * the entity's CURRENT field value (resolved by the handle via `read`).
+   * Null when there is no such transition (e.g. the field never changed
+   * since creation, or the entity is absent and the handle passes no value).
+   */
+  inStateSince(args: {
+    kind: string;
+    entityId: string;
+    field: string;
+    /** The entity's current value of `field`, resolved by the handle. */
+    currentValue: unknown;
+  }): Promise<Date | null>;
+
+  /** Count transitions of `field` within the trailing `windowMs`. */
+  transitionCount(args: {
+    kind: string;
+    entityId: string;
+    field: string;
+    windowMs: number;
+    now: Date;
+  }): Promise<number>;
+}
+
+/** Serialize a state field value to the transition log's text column. */
+export function serializeFieldValue(value: unknown): string {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+
+export function createEntityStore(db: SafeDatabase<Schema>): EntityStore {
+  return {
+    async runInTransaction(fn) {
+      return db.transaction(async (tx) => fn(tx));
+    },
+
+    async appendTransitions({ tx, kind, entityId, transitions }) {
+      if (transitions.length === 0) return;
+      await tx.insert(entityTransitions).values(
+        transitions.map((t) => ({
+          kind,
+          entityId,
+          field: t.field,
+          fromValue: t.fromValue,
+          toValue: t.toValue,
+        })),
+      );
+    },
+
+    async inStateSince({ kind, entityId, field, currentValue }) {
+      const value = serializeFieldValue(currentValue);
+      const [row] = await db
+        .select({ transitionedAt: entityTransitions.transitionedAt })
+        .from(entityTransitions)
+        .where(
+          and(
+            eq(entityTransitions.kind, kind),
+            eq(entityTransitions.entityId, entityId),
+            eq(entityTransitions.field, field),
+            eq(entityTransitions.toValue, value),
+          ),
+        )
+        .orderBy(desc(entityTransitions.transitionedAt))
+        .limit(1);
+      return row?.transitionedAt ?? null;
+    },
+
+    async transitionCount({ kind, entityId, field, windowMs, now }) {
+      const since = new Date(now.getTime() - windowMs);
+      const [row] = await db
+        .select({ count: sql<number>`count(*)::int` })
+        .from(entityTransitions)
+        .where(
+          and(
+            eq(entityTransitions.kind, kind),
+            eq(entityTransitions.entityId, entityId),
+            eq(entityTransitions.field, field),
+            gte(entityTransitions.transitionedAt, since),
+          ),
+        );
+      return row?.count ?? 0;
+    },
+  };
+}

package/src/entity/extension-point.ts

@@ -0,0 +1,56 @@
+import { createExtensionPoint } from "@checkstack/backend-api";
+
+import type { DeclareNonReactiveState, DefineEntity } from "./define-entity";
+import type {
+  EntityChangeDeriver,
+  EntityChangePayloadMapper,
+} from "./change-derivers";
+import type { OnEntityChanged } from "./on-entity-changed";
+
+/**
+ * Register a per-kind trigger-event deriver (reactive automation engine §7,
+ * Stage-1 routing). A domain (Phase 4) maps "this entity kind changed like
+ * THIS" → the qualified trigger event id(s) it should fire; Stage 1 unions
+ * the results and fans out to the enabled automations referencing them.
+ *
+ * `toPayload`, when supplied, maps a change of this kind to the DOMAIN-named
+ * `trigger.payload` shape the kind's triggers declare via `payloadSchema`
+ * (incident `incidentId`, health `systemId` / `previousStatus`, …). Stage-2
+ * uses it so operator filters/templates reading `trigger.payload.incidentId`
+ * etc. resolve correctly; without it Stage-2 falls back to the generic
+ * `{ kind, id, prev, next, delta, ...next }` shape. At most one mapper per
+ * kind (a second distinct mapper throws).
+ */
+export type RegisterChangeDeriver = (input: {
+  kind: string;
+  derive: EntityChangeDeriver;
+  toPayload?: EntityChangePayloadMapper;
+}) => void;
+
+/**
+ * The `automation.entity` extension point — the single typed path to
+ * reactive entity state (reactive automation engine §4.2). automation-
+ * backend owns the entity store, scope projection, and wake-index, so it
+ * registers this impl in Phase 1 (`register`); other plugins resolve it via
+ * `env.getExtensionPoint(entityExtensionPoint)` and call `defineEntity` in
+ * their own `register`/`init`. Cross-plugin calls are Proxy-buffered until
+ * automation-backend registers the impl.
+ *
+ * - `defineEntity` — declare an entity kind + get its typed mutation handle.
+ * - `declareNonReactiveState` — annotate intentionally non-reactive data
+ *   (§5, §15.6) so enforcement can be strict on everything unmarked.
+ * - `onEntityChanged` — subscribe to ANOTHER domain's entity changes without
+ *   touching the internal `ENTITY_CHANGED` hook (§6.1 design decision).
+ * - `registerChangeDeriver` — map a kind's change to the trigger event id(s)
+ *   Stage-1 routing fans out (Phase 4 supplies the per-domain derivers).
+ */
+export interface EntityExtensionPoint {
+  defineEntity: DefineEntity;
+  declareNonReactiveState: DeclareNonReactiveState;
+  onEntityChanged: OnEntityChanged;
+  registerChangeDeriver: RegisterChangeDeriver;
+}
+
+export const entityExtensionPoint = createExtensionPoint<EntityExtensionPoint>(
+  "automation.entity",
+);

package/src/entity/fake-entity-store.ts

@@ -0,0 +1,130 @@
+/**
+ * In-memory test doubles for the Model B entity machine.
+ *
+ * `createFakeEntityStore()` returns a combined fake that plays two roles a
+ * unit test needs:
+ *
+ *   - the framework TRANSITION store (`EntityStore`): a fake transaction +
+ *     an in-memory transition log + the `inStateSince` / `transitionCount`
+ *     reads. The fake `runInTransaction` just runs the callback (no real tx);
+ *     `tx` is a sentinel `appendTransitions` recognizes.
+ *   - a plugin `read` accessor over `rows` (`readFor`), so a test can drive a
+ *     kind end-to-end via `handle.mutate` and keep `rows` inspectable.
+ *
+ * For PLUGIN-BACKED kinds a test supplies its OWN `read` + `apply` (e.g. an
+ * in-memory domain map) and only uses this fake for the transition store; see
+ * `mutate-handle.test.ts`.
+ */
+import type { EntityStore, EntityTx, TransitionAppend } from "./entity-store";
+import { serializeFieldValue } from "./entity-store";
+
+interface TransitionRow {
+  kind: string;
+  entityId: string;
+  field: string;
+  fromValue: string | null;
+  toValue: string;
+  transitionedAt: Date;
+}
+
+/** A sentinel "transaction" the fake passes to `apply` / `appendTransitions`. */
+export const FAKE_TX: EntityTx = {} as unknown as EntityTx;
+
+export interface FakeEntityStore extends EntityStore {
+  /** Direct access to the persisted state rows (kind:id -> state). */
+  readonly rows: Map<string, Record<string, unknown>>;
+  /** Direct access to the transition log. */
+  readonly transitions: TransitionRow[];
+  /** Override the clock used for transition timestamps (defaults to Date.now). */
+  setClock(fn: () => Date): void;
+  /**
+   * Register an observer invoked each time `runInTransaction` opens the fake
+   * framework transaction. Lets a test assert the cross-plugin ordering: the
+   * plugin-backed path opens the framework (transition-append) tx ONLY after
+   * the plugin write has committed.
+   */
+  onTransaction(fn: () => void): void;
+  /** A plugin `read` accessor over `rows` for a given kind. */
+  readFor<TState extends Record<string, unknown>>(
+    kind: string,
+  ): (ids: ReadonlyArray<string>) => Promise<Record<string, TState>>;
+}
+
+const key = (kind: string, id: string) => `${kind}:${id}`;
+const defaultClock = (): Date => new Date();
+
+export function createFakeEntityStore(): FakeEntityStore {
+  const rows = new Map<string, Record<string, unknown>>();
+  const transitions: TransitionRow[] = [];
+  let clock: () => Date = defaultClock;
+  let onTx: (() => void) | undefined;
+
+  return {
+    rows,
+    transitions,
+    setClock(fn) {
+      clock = fn;
+    },
+    onTransaction(fn) {
+      onTx = fn;
+    },
+
+    async runInTransaction(fn) {
+      // No real transaction in the fake — just run with the sentinel tx.
+      onTx?.();
+      return fn(FAKE_TX);
+    },
+
+    async appendTransitions({ kind, entityId, transitions: appends }) {
+      const at = clock();
+      for (const t of appends as ReadonlyArray<TransitionAppend>) {
+        transitions.push({
+          kind,
+          entityId,
+          field: t.field,
+          fromValue: t.fromValue,
+          toValue: t.toValue,
+          transitionedAt: at,
+        });
+      }
+    },
+
+    async inStateSince({ kind, entityId, field, currentValue }) {
+      const value = serializeFieldValue(currentValue);
+      const matching = transitions
+        .filter(
+          (t) =>
+            t.kind === kind &&
+            t.entityId === entityId &&
+            t.field === field &&
+            t.toValue === value,
+        )
+        .toSorted(
+          (a, b) => b.transitionedAt.getTime() - a.transitionedAt.getTime(),
+        );
+      return matching[0]?.transitionedAt ?? null;
+    },
+
+    async transitionCount({ kind, entityId, field, windowMs, now }) {
+      const since = now.getTime() - windowMs;
+      return transitions.filter(
+        (t) =>
+          t.kind === kind &&
+          t.entityId === entityId &&
+          t.field === field &&
+          t.transitionedAt.getTime() >= since,
+      ).length;
+    },
+
+    readFor<TState extends Record<string, unknown>>(kind: string) {
+      return async (ids: ReadonlyArray<string>) => {
+        const out: Record<string, TState> = {};
+        for (const id of ids) {
+          const row = rows.get(key(kind, id));
+          if (row) out[id] = row as TState;
+        }
+        return out;
+      };
+    },
+  };
+}

package/src/entity/hook.ts

@@ -0,0 +1,19 @@
+import { createHook } from "@checkstack/backend-api";
+import type { EntityChanged } from "@checkstack/automation-common";
+
+/**
+ * INTERNAL entity-change hook (reactive automation engine §6.1).
+ *
+ * Created and emitted ONLY inside automation-backend; it is deliberately
+ * NOT re-exported from the package's public surface so the only typed path
+ * that emits an entity-change event is `defineEntity`. Off-pattern entity
+ * state is non-reactive by construction — Stage-1 routing and scope
+ * projection only ever read the framework store / this hook.
+ *
+ * Payload is the `EntityChangedSchema` shape (zod source of truth lives in
+ * `@checkstack/automation-common`). Emitted in `mode: "work-queue"` for
+ * Stage-1 routing in a later phase; this phase only emits it.
+ */
+export const ENTITY_CHANGED_HOOK = createHook<EntityChanged>(
+  "automation.entity.changed",
+);