@wopr-network/defcon 1.12.0 → 1.14.0

package/README.md

@@ -204,6 +204,50 @@ npx defcon run --flow my-pipeline
 
 Same flow. Same gates. Same escalation. The only difference is who's turning the crank — your agent or DEFCON's runner. Either way, the work doesn't advance until the evidence says it should.
 
+## The Deeper Truth: Defcon Is a Prompt Engineering State Machine
+
+The manifesto above tells you why gates matter. Here's the insight that changes how you think about everything else.
+
+Defcon is not an orchestration engine that happens to give prompts to agents. **Defcon is a prompt engineering state machine.** Every state is a prompt. Every transition is a context transformation. Every gate is a deterministic filter that decides what prompt the agent gets next — or whether it gets one at all.
+
+The flow definition is the engineering artifact. Not the agent code. Not the model selection. The flow.
+
+### Context Assembly Is the Contract
+
+An agent invocation is expensive. An agent invocation where the agent spends tool calls reading its own issue, checking CI status, or finding the PR it's supposed to review — that is a flow engineering defect. The onEnter hook should have assembled that context before the agent fired.
+
+**Every tool call an agent makes to gather context is a failure of the flow definition to provide it.**
+
+When the architect calls Linear to read the issue description — that's already in `entity.refs.linear.description`. Put it in the prompt template. When the coder calls `gh pr list` — that's a missing onEnter hook. When the reviewer runs `gh pr checks` — the gate already verified this.
+
+The measure of a well-engineered state is: **can the agent complete its job with zero context-gathering tool calls?** Every tool call should be *work* — writing code, posting comments, running tests — never reconnaissance.
+
+### Gates Are Prompt Qualification
+
+A gate doesn't just verify that work is done. A gate verifies that **the next state's context can be assembled completely**.
+
+`review-bots-ready` waiting for CI and bot comments isn't patience. It ensures the reviewer's prompt will contain: green CI, all bot findings, full diff. Without the gate, the reviewer either polls (burning tokens) or reviews without full information (wrong answer, another loop).
+
+The cost of a gate is milliseconds of shell execution. The cost of a skipped gate is a full review/fix cycle — potentially minutes and dollars.
+
+### The 1:2.8 Ratio Is Physics
+
+For every 1 coder invocation, there are approximately 2.8 reviewer/fixer invocations. This is not a pipeline inefficiency. It is the actual shape of software.
+
+The coder produces a first approximation. Reality pushes back: CI failures, static analysis findings, edge cases the spec didn't anticipate, style violations the linter catches. 70% of the engineering work happens after the code is written. You cannot prompt-engineer your way out of this. You cannot pre-load enough context to get one-shot correctness. The iteration is load-bearing.
+
+The design question is not "how do we reduce the review/fix loop." It is: **given that ~2.8 cycles is the physics, how do we make each cycle as cheap and fast as possible?**
+
+Every gate that catches a problem before an agent runs saves a full cycle. Every onEnter hook that assembles complete context means the agent spends its tokens on reasoning instead of discovery. Every failure prompt that tells the agent exactly what went wrong reduces the chance of another loop.
+
+### Flow Engineering Is 90% of the Work
+
+The promise is big: software that ships with 100% overhead reduction. But 90% of the engineering work to get there is flow engineering — designing states, writing hooks, placing gates, and crafting prompts. The agent is the easy part. The agent is a commodity. The flow is the competitive advantage.
+
+A poorly written failure prompt extends the loop. A gate that fires too early sends an under-qualified prompt to the reviewer. A missing onEnter hook makes the agent reconstruct context with tool calls instead of reasoning. The flow definition IS the quality of the system.
+
+---
+
 ## The Engine
 
 A **flow** is a state machine. Entities enter it and move through states. At each state an agent does work. At each boundary a deterministic gate verifies the output. Transitions fire on signals — not parsed natural language, not regex, but typed strings agents emit via tool call. The entire definition lives in a database and can be mutated at runtime.

package/dist/src/engine/engine.js

@@ -145,6 +145,18 @@ export class Engine {
         // 6b. Execute onEnter hook if defined on the new state
         const newStateDef = flow.states.find((s) => s.name === toState);
         if (newStateDef?.onEnter) {
+            // Clear stale onEnter artifact keys so the hook re-runs on state re-entry.
+            // Only the keys belonging to THIS state's onEnter are removed; other artifacts are preserved.
+            const keysToRemove = [...newStateDef.onEnter.artifacts, "onEnter_error"];
+            const currentArtifacts = updated.artifacts ?? {};
+            const hasStaleKeys = keysToRemove.some((k) => currentArtifacts[k] !== undefined);
+            if (hasStaleKeys) {
+                await this.entityRepo.removeArtifactKeys(entityId, keysToRemove);
+                // Refresh in-memory entity so executeOnEnter sees cleared artifacts
+                const refreshed = await this.entityRepo.get(entityId);
+                if (refreshed)
+                    updated = refreshed;
+            }
             const onEnterResult = await executeOnEnter(newStateDef.onEnter, updated, this.entityRepo);
             if (onEnterResult.skipped) {
                 await emitter.emit({

package/dist/src/execution/cli.js

@@ -19,6 +19,7 @@ import { buildConfigFromEnv, isLitestreamEnabled, LitestreamManager } from "../l
 import { withTransaction } from "../main.js";
 import { DrizzleDomainEventRepository } from "../repositories/drizzle/domain-event.repo.js";
 import { DrizzleEntityRepository } from "../repositories/drizzle/entity.repo.js";
+import { DrizzleEntitySnapshotRepository } from "../repositories/drizzle/entity-snapshot.repo.js";
 import { DrizzleEventRepository } from "../repositories/drizzle/event.repo.js";
 import { DrizzleFlowRepository } from "../repositories/drizzle/flow.repo.js";
 import { DrizzleGateRepository } from "../repositories/drizzle/gate.repo.js";
@@ -26,6 +27,8 @@ import { DrizzleInvocationRepository } from "../repositories/drizzle/invocation.
 import * as schema from "../repositories/drizzle/schema.js";
 import { entities, entityHistory, flowDefinitions, flowVersions, gateDefinitions, gateResults, invocations, stateDefinitions, transitionRules, } from "../repositories/drizzle/schema.js";
 import { DrizzleTransitionLogRepository } from "../repositories/drizzle/transition-log.repo.js";
+import { EventSourcedEntityRepository } from "../repositories/event-sourced/entity.repo.js";
+import { EventSourcedInvocationRepository } from "../repositories/event-sourced/invocation.repo.js";
 import { UiSseAdapter } from "../ui/sse.js";
 import { WebSocketBroadcaster } from "../ws/broadcast.js";
 import { createMcpServer, startStdioServer } from "./mcp-server.js";
@@ -171,12 +174,26 @@ program
     if (litestreamMgr) {
         litestreamMgr.start();
     }
-    const entityRepo = new DrizzleEntityRepository(db);
+    const mutableEntityRepo = new DrizzleEntityRepository(db);
     const flowRepo = new DrizzleFlowRepository(db);
-    const invocationRepo = new DrizzleInvocationRepository(db);
+    const mutableInvocationRepo = new DrizzleInvocationRepository(db);
     const gateRepo = new DrizzleGateRepository(db);
     const transitionLogRepo = new DrizzleTransitionLogRepository(db);
     const domainEventRepo = new DrizzleDomainEventRepository(db);
+    const useEventSourced = process.env.DEFCON_EVENT_SOURCED === "true";
+    const snapshotInterval = parseInt(process.env.DEFCON_SNAPSHOT_INTERVAL ?? "10", 10);
+    let entityRepo;
+    let invocationRepo;
+    if (useEventSourced) {
+        const snapshotRepo = new DrizzleEntitySnapshotRepository(db);
+        entityRepo = new EventSourcedEntityRepository(mutableEntityRepo, domainEventRepo, snapshotRepo, snapshotInterval);
+        invocationRepo = new EventSourcedInvocationRepository(mutableInvocationRepo, domainEventRepo);
+        process.stderr.write("[defcon] Event-sourced repositories enabled\n");
+    }
+    else {
+        entityRepo = mutableEntityRepo;
+        invocationRepo = mutableInvocationRepo;
+    }
     const eventEmitter = new EventEmitter();
     eventEmitter.register({
         emit: async (event) => {

package/dist/src/repositories/drizzle/domain-event.repo.d.ts

@@ -11,6 +11,7 @@ export declare class DrizzleDomainEventRepository implements IDomainEventReposit
     list(entityId: string, opts?: {
         type?: string;
         limit?: number;
+        minSequence?: number;
     }): Promise<DomainEvent[]>;
 }
 export {};

package/dist/src/repositories/drizzle/domain-event.repo.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { and, eq, sql } from "drizzle-orm";
+import { and, eq, gt, sql } from "drizzle-orm";
 import { domainEvents } from "./schema.js";
 export class DrizzleDomainEventRepository {
     db;
@@ -62,6 +62,9 @@ export class DrizzleDomainEventRepository {
         if (opts?.type) {
             conditions.push(eq(domainEvents.type, opts.type));
         }
+        if (opts?.minSequence !== undefined) {
+            conditions.push(gt(domainEvents.sequence, opts.minSequence));
+        }
         const rows = this.db
             .select()
             .from(domainEvents)

package/dist/src/repositories/drizzle/entity-snapshot.repo.d.ts

@@ -0,0 +1,14 @@
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import type { Entity, IEntitySnapshotRepository } from "../interfaces.js";
+import type * as schema from "./schema.js";
+type Db = BetterSQLite3Database<typeof schema>;
+export declare class DrizzleEntitySnapshotRepository implements IEntitySnapshotRepository {
+    private readonly db;
+    constructor(db: Db);
+    save(entityId: string, sequence: number, state: Entity): Promise<void>;
+    loadLatest(entityId: string): Promise<{
+        sequence: number;
+        state: Entity;
+    } | null>;
+}
+export {};

package/dist/src/repositories/drizzle/entity-snapshot.repo.js

@@ -0,0 +1,68 @@
+import { randomUUID } from "node:crypto";
+import { desc, eq } from "drizzle-orm";
+import { entitySnapshots } from "./schema.js";
+export class DrizzleEntitySnapshotRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async save(entityId, sequence, state) {
+        const id = randomUUID();
+        this.db
+            .insert(entitySnapshots)
+            .values({
+            id,
+            entityId,
+            sequence,
+            state: state.state,
+            flowId: state.flowId,
+            refs: state.refs,
+            artifacts: state.artifacts,
+            claimedBy: state.claimedBy,
+            claimedAt: state.claimedAt?.getTime() ?? null,
+            flowVersion: state.flowVersion,
+            priority: state.priority,
+            affinityWorkerId: state.affinityWorkerId,
+            affinityRole: state.affinityRole,
+            affinityExpiresAt: state.affinityExpiresAt?.getTime() ?? null,
+            createdAt: state.createdAt.getTime(),
+            updatedAt: state.updatedAt.getTime(),
+            snapshotAt: Date.now(),
+            parentEntityId: state.parentEntityId,
+        })
+            .onConflictDoNothing()
+            .run();
+    }
+    async loadLatest(entityId) {
+        const rows = this.db
+            .select()
+            .from(entitySnapshots)
+            .where(eq(entitySnapshots.entityId, entityId))
+            .orderBy(desc(entitySnapshots.sequence))
+            .limit(1)
+            .all();
+        if (rows.length === 0)
+            return null;
+        const row = rows[0];
+        return {
+            sequence: row.sequence,
+            state: {
+                id: entityId,
+                flowId: row.flowId,
+                state: row.state,
+                refs: row.refs,
+                artifacts: row.artifacts,
+                claimedBy: row.claimedBy,
+                claimedAt: row.claimedAt ? new Date(row.claimedAt) : null,
+                flowVersion: row.flowVersion ?? 1,
+                priority: row.priority ?? 0,
+                createdAt: new Date(row.createdAt ?? 0),
+                updatedAt: new Date(row.updatedAt ?? 0),
+                affinityWorkerId: row.affinityWorkerId ?? null,
+                affinityRole: row.affinityRole ?? null,
+                affinityExpiresAt: row.affinityExpiresAt ? new Date(row.affinityExpiresAt) : null,
+                parentEntityId: row.parentEntityId ?? null,
+            },
+        };
+    }
+}

package/dist/src/repositories/drizzle/entity.repo.d.ts

@@ -12,6 +12,7 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
     transition(id: string, toState: string, _trigger: string, artifacts?: Partial<Artifacts>, _invocationId?: string | null): Promise<Entity>;
     updateArtifacts(id: string, artifacts: Partial<Artifacts>): Promise<void>;
+    removeArtifactKeys(id: string, keys: string[]): Promise<void>;
     claim(flowId: string, state: string, agentId: string): Promise<Entity | null>;
     claimById(entityId: string, agentId: string): Promise<Entity | null>;
     release(entityId: string, agentId: string): Promise<void>;

package/dist/src/repositories/drizzle/entity.repo.js

@@ -101,6 +101,19 @@ export class DrizzleEntityRepository {
             .set({ artifacts: { ...existing, ...artifacts }, updatedAt: Date.now() })
             .where(eq(entities.id, id));
     }
+    async removeArtifactKeys(id, keys) {
+        if (keys.length === 0)
+            return;
+        const rows = await this.db.select().from(entities).where(eq(entities.id, id)).limit(1);
+        if (rows.length === 0)
+            throw new NotFoundError(`Entity not found: ${id}`);
+        const existing = rows[0].artifacts ?? {};
+        const cleaned = { ...existing };
+        for (const key of keys) {
+            delete cleaned[key];
+        }
+        await this.db.update(entities).set({ artifacts: cleaned, updatedAt: Date.now() }).where(eq(entities.id, id));
+    }
     async claim(flowId, state, agentId) {
         return this.db.transaction((tx) => {
             const rows = tx

package/dist/src/repositories/drizzle/index.d.ts

@@ -1,5 +1,6 @@
 export { DrizzleDomainEventRepository } from "./domain-event.repo.js";
 export { DrizzleEntityRepository } from "./entity.repo.js";
+export { DrizzleEntitySnapshotRepository } from "./entity-snapshot.repo.js";
 export { DrizzleEventRepository } from "./event.repo.js";
 export { DrizzleFlowRepository } from "./flow.repo.js";
 export { DrizzleGateRepository } from "./gate.repo.js";

package/dist/src/repositories/drizzle/index.js

@@ -1,6 +1,7 @@
 // Drizzle ORM implementations of repository interfaces
 export { DrizzleDomainEventRepository } from "./domain-event.repo.js";
 export { DrizzleEntityRepository } from "./entity.repo.js";
+export { DrizzleEntitySnapshotRepository } from "./entity-snapshot.repo.js";
 export { DrizzleEventRepository } from "./event.repo.js";
 export { DrizzleFlowRepository } from "./flow.repo.js";
 export { DrizzleGateRepository } from "./gate.repo.js";

package/dist/src/repositories/drizzle/schema.d.ts

@@ -2149,3 +2149,332 @@ export declare const domainEvents: import("drizzle-orm/sqlite-core").SQLiteTable
     };
     dialect: "sqlite";
 }>;
+export declare const entitySnapshots: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "entity_snapshots";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "entity_snapshots";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        entityId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "entity_id";
+            tableName: "entity_snapshots";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        sequence: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "sequence";
+            tableName: "entity_snapshots";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        state: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "state";
+            tableName: "entity_snapshots";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        flowId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "flow_id";
+            tableName: "entity_snapshots";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        refs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "refs";
+            tableName: "entity_snapshots";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        artifacts: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "artifacts";
+            tableName: "entity_snapshots";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        claimedBy: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "claimed_by";
+            tableName: "entity_snapshots";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        claimedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "claimed_at";
+            tableName: "entity_snapshots";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        flowVersion: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "flow_version";
+            tableName: "entity_snapshots";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        priority: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "priority";
+            tableName: "entity_snapshots";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        affinityWorkerId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "affinity_worker_id";
+            tableName: "entity_snapshots";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        affinityRole: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "affinity_role";
+            tableName: "entity_snapshots";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        affinityExpiresAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "affinity_expires_at";
+            tableName: "entity_snapshots";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "entity_snapshots";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updated_at";
+            tableName: "entity_snapshots";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        snapshotAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "snapshot_at";
+            tableName: "entity_snapshots";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        parentEntityId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "parent_entity_id";
+            tableName: "entity_snapshots";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: "sqlite";
+}>;

package/dist/src/repositories/drizzle/schema.js

@@ -173,3 +173,26 @@ export const domainEvents = sqliteTable("domain_events", {
     entitySeqIdx: uniqueIndex("domain_events_entity_seq_idx").on(table.entityId, table.sequence),
     typeIdx: index("domain_events_type_idx").on(table.type, table.emittedAt),
 }));
+export const entitySnapshots = sqliteTable("entity_snapshots", {
+    id: text("id").primaryKey(),
+    entityId: text("entity_id").notNull(),
+    sequence: integer("sequence").notNull(),
+    state: text("state").notNull(),
+    flowId: text("flow_id").notNull(),
+    refs: text("refs", { mode: "json" }),
+    artifacts: text("artifacts", { mode: "json" }),
+    claimedBy: text("claimed_by"),
+    claimedAt: integer("claimed_at"),
+    flowVersion: integer("flow_version"),
+    priority: integer("priority").default(0),
+    affinityWorkerId: text("affinity_worker_id"),
+    affinityRole: text("affinity_role"),
+    affinityExpiresAt: integer("affinity_expires_at"),
+    createdAt: integer("created_at"),
+    updatedAt: integer("updated_at"),
+    snapshotAt: integer("snapshot_at").notNull(),
+    parentEntityId: text("parent_entity_id"),
+}, (table) => ({
+    entitySeqUnique: uniqueIndex("entity_snapshots_entity_seq_idx").on(table.entityId, table.sequence),
+    entityLatestIdx: index("entity_snapshots_entity_latest_idx").on(table.entityId, table.snapshotAt),
+}));

package/dist/src/repositories/event-sourced/entity.repo.d.ts

@@ -0,0 +1,30 @@
+import type { Artifacts, Entity, IDomainEventRepository, IEntityRepository, IEntitySnapshotRepository, Refs } from "../interfaces.js";
+export declare class EventSourcedEntityRepository implements IEntityRepository {
+    private readonly mutable;
+    private readonly domainEvents;
+    private readonly snapshots;
+    private readonly snapshotInterval;
+    constructor(mutable: IEntityRepository, domainEvents: IDomainEventRepository, snapshots: IEntitySnapshotRepository, snapshotInterval?: number);
+    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number): Promise<Entity>;
+    get(id: string): Promise<Entity | null>;
+    findByFlowAndState(flowId: string, state: string, limit?: number): Promise<Entity[]>;
+    hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
+    transition(id: string, toState: string, trigger: string, artifacts?: Partial<Artifacts>): Promise<Entity>;
+    updateArtifacts(id: string, artifacts: Partial<Artifacts>): Promise<void>;
+    removeArtifactKeys(id: string, keys: string[]): Promise<void>;
+    claim(flowId: string, state: string, agentId: string): Promise<Entity | null>;
+    claimById(entityId: string, agentId: string): Promise<Entity | null>;
+    release(entityId: string, agentId: string): Promise<void>;
+    reapExpired(ttlMs: number): Promise<string[]>;
+    setAffinity(entityId: string, workerId: string, role: string, expiresAt: Date): Promise<void>;
+    clearExpiredAffinity(): Promise<string[]>;
+    appendSpawnedChild(parentId: string, entry: {
+        childId: string;
+        childFlow: string;
+        spawnedAt: string;
+    }): Promise<void>;
+    findByParentId(parentEntityId: string): Promise<Entity[]>;
+    cancelEntity(entityId: string): Promise<void>;
+    resetEntity(entityId: string, targetState: string): Promise<Entity>;
+    updateFlowVersion(entityId: string, version: number): Promise<void>;
+}