@wopr-network/defcon 1.6.0 → 1.7.0

package/dist/src/engine/engine.d.ts

@@ -28,6 +28,7 @@ export interface EngineStatus {
     flows: Record<string, Record<string, number>>;
     activeInvocations: number;
     pendingClaims: number;
+    versionDistribution: Record<string, Record<string, number>>;
 }
 export interface EngineDeps {
     entityRepo: IEntityRepository;
@@ -38,6 +39,8 @@ export interface EngineDeps {
     adapters: Map<string, unknown>;
     eventEmitter: IEventBusAdapter;
     logger?: Logger;
+    /** Optional transaction wrapper from the database layer. When provided, processSignal runs inside a single transaction and events are flushed only after successful commit. */
+    withTransaction?: <T>(fn: () => T | Promise<T>) => Promise<T>;
 }
 export declare class Engine {
     private entityRepo;
@@ -48,6 +51,7 @@ export declare class Engine {
     readonly adapters: Map<string, unknown>;
     private eventEmitter;
     private readonly logger;
+    private readonly withTransactionFn;
     private drainingWorkers;
     constructor(deps: EngineDeps);
     drainWorker(workerId: string): void;
@@ -56,6 +60,7 @@ export declare class Engine {
     listDrainingWorkers(): string[];
     emit(event: import("./event-types.js").EngineEvent): Promise<void>;
     processSignal(entityId: string, signal: string, artifacts?: Artifacts, triggeringInvocationId?: string): Promise<ProcessSignalResult>;
+    private _processSignalInner;
     /**
      * Evaluate a gate and return a routing decision:
      * - `proceed`  — gate passed, continue to transition.toState

package/dist/src/engine/engine.js

@@ -17,6 +17,7 @@ export class Engine {
     adapters;
     eventEmitter;
     logger;
+    withTransactionFn;
     drainingWorkers = new Set();
     constructor(deps) {
         this.entityRepo = deps.entityRepo;
@@ -27,6 +28,7 @@ export class Engine {
         this.adapters = deps.adapters;
         this.eventEmitter = deps.eventEmitter;
         this.logger = deps.logger ?? consoleLogger;
+        this.withTransactionFn = deps.withTransaction ?? null;
     }
     drainWorker(workerId) {
         this.drainingWorkers.add(workerId);
@@ -44,14 +46,36 @@ export class Engine {
         await this.eventEmitter.emit(event);
     }
     async processSignal(entityId, signal, artifacts, triggeringInvocationId) {
+        const pendingEvents = [];
+        const bufferingEmitter = {
+            emit: async (event) => {
+                pendingEvents.push(event);
+            },
+        };
+        if (this.withTransactionFn) {
+            // Run DB writes inside a transaction; events are buffered and only
+            // flushed to real subscribers after successful COMMIT.
+            const result = await this.withTransactionFn(() => this._processSignalInner(entityId, signal, artifacts, triggeringInvocationId, bufferingEmitter));
+            for (const event of pendingEvents) {
+                await this.eventEmitter.emit(event);
+            }
+            return result;
+        }
+        const result = await this._processSignalInner(entityId, signal, artifacts, triggeringInvocationId, bufferingEmitter);
+        for (const event of pendingEvents) {
+            await this.eventEmitter.emit(event);
+        }
+        return result;
+    }
+    async _processSignalInner(entityId, signal, artifacts, triggeringInvocationId, emitter = this.eventEmitter) {
         // 1. Load entity
         const entity = await this.entityRepo.get(entityId);
         if (!entity)
             throw new NotFoundError(`Entity "${entityId}" not found`);
-        // 2. Load flow
-        const flow = await this.flowRepo.get(entity.flowId);
+        // 2. Load flow at entity's pinned version
+        const flow = await this.flowRepo.getAtVersion(entity.flowId, entity.flowVersion);
         if (!flow)
-            throw new NotFoundError(`Flow "${entity.flowId}" not found`);
+            throw new NotFoundError(`Flow "${entity.flowId}" version ${entity.flowVersion} not found`);
         // 3. Find transition
         const transition = findTransition(flow, entity.state, signal, { entity }, true, this.logger);
         if (!transition)
@@ -98,7 +122,7 @@ export class Engine {
         // Keep the in-memory entity in sync so buildInvocation sees the cleared failures
         updated = { ...updated, artifacts: { ...updated.artifacts, gate_failures: [] } };
         // 6. Emit transition event
-        await this.eventEmitter.emit({
+        await emitter.emit({
             type: "entity.transitioned",
             entityId,
             flowId: flow.id,
@@ -118,7 +142,7 @@ export class Engine {
         if (newStateDef?.onEnter) {
             const onEnterResult = await executeOnEnter(newStateDef.onEnter, updated, this.entityRepo);
             if (onEnterResult.skipped) {
-                await this.eventEmitter.emit({
+                await emitter.emit({
                     type: "onEnter.skipped",
                     entityId,
                     state: toState,
@@ -126,7 +150,7 @@ export class Engine {
                 });
             }
             else if (onEnterResult.error) {
-                await this.eventEmitter.emit({
+                await emitter.emit({
                     type: "onEnter.failed",
                     entityId,
                     state: toState,
@@ -151,7 +175,7 @@ export class Engine {
                 };
             }
             else {
-                await this.eventEmitter.emit({
+                await emitter.emit({
                     type: "onEnter.completed",
                     entityId,
                     state: toState,
@@ -179,7 +203,7 @@ export class Engine {
                     ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
                     : undefined, newStateDef.agentRole ?? null);
                 result.invocationId = invocation.id;
-                await this.eventEmitter.emit({
+                await emitter.emit({
                     type: "invocation.created",
                     entityId,
                     invocationId: invocation.id,
@@ -202,7 +226,7 @@ export class Engine {
         const spawned = await executeSpawn({ spawnFlow }, updated, this.flowRepo, this.entityRepo, this.logger);
         if (spawned) {
             result.spawned = [spawned.id];
-            await this.eventEmitter.emit({
+            await emitter.emit({
                 type: "flow.spawned",
                 entityId,
                 flowId: flow.id,
@@ -301,7 +325,7 @@ export class Engine {
         const flow = await this.flowRepo.getByName(flowName);
         if (!flow)
             throw new NotFoundError(`Flow "${flowName}" not found`);
-        let entity = await this.entityRepo.create(flow.id, flow.initialState, refs);
+        let entity = await this.entityRepo.create(flow.id, flow.initialState, refs, flow.version);
         // Store any caller-supplied payload as initial artifacts so prompt templates
         // can access refs like {{entity.artifacts.refs.linear.id}}.
         if (payload && Object.keys(payload).length > 0) {
@@ -492,9 +516,11 @@ export class Engine {
                     this.logger.warn(`[engine] setAffinity failed for entity ${claimed.id} worker ${worker_id} — continuing:`, err);
                 }
             }
-            const state = flow.states.find((s) => s.name === pending.stage);
+            const versionedFlow = await this.flowRepo.getAtVersion(claimed.flowId, claimed.flowVersion);
+            const effectiveFlow = versionedFlow ?? flow;
+            const state = effectiveFlow.states.find((s) => s.name === pending.stage);
             const build = state
-                ? await this.buildPromptForEntity(state, claimed, flow)
+                ? await this.buildPromptForEntity(state, claimed, effectiveFlow)
                 : { prompt: pending.prompt, context: null };
             await this.eventEmitter.emit({
                 type: "entity.claimed",
@@ -519,12 +545,14 @@ export class Engine {
                 const claimed = await this.entityRepo.claim(flow.id, state.name, worker_id ?? `agent:${role}`);
                 if (!claimed)
                     continue;
-                const canCreate = await this.checkConcurrency(flow, claimed);
+                const claimedVersionedFlow = await this.flowRepo.getAtVersion(claimed.flowId, claimed.flowVersion);
+                const claimedEffectiveFlow = claimedVersionedFlow ?? flow;
+                const canCreate = await this.checkConcurrency(claimedEffectiveFlow, claimed);
                 if (!canCreate) {
                     await this.entityRepo.release(claimed.id, worker_id ?? `agent:${role}`);
                     continue;
                 }
-                const build = await this.buildPromptForEntity(state, claimed, flow);
+                const build = await this.buildPromptForEntity(state, claimed, claimedEffectiveFlow);
                 const invocation = await this.invocationRepo.create(claimed.id, state.name, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
                     ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
                     : undefined, state.agentRole ?? null);
@@ -623,7 +651,21 @@ export class Engine {
             activeInvocations += active;
             pendingClaims += pending;
         }
-        return { flows: statusData, activeInvocations, pendingClaims };
+        const versionDistribution = {};
+        for (const flow of allFlows) {
+            const versionCounts = {};
+            for (const state of flow.states) {
+                const stateEntities = await this.entityRepo.findByFlowAndState(flow.id, state.name);
+                for (const e of stateEntities) {
+                    const vKey = String(e.flowVersion);
+                    versionCounts[vKey] = (versionCounts[vKey] ?? 0) + 1;
+                }
+            }
+            if (Object.keys(versionCounts).length > 0) {
+                versionDistribution[flow.id] = versionCounts;
+            }
+        }
+        return { flows: statusData, activeInvocations, pendingClaims, versionDistribution };
     }
     startReaper(intervalMs, entityTtlMs = 60_000) {
         let tickInFlight = false;

package/dist/src/execution/admin-schemas.d.ts

@@ -124,6 +124,9 @@ export declare const AdminEntityResetSchema: z.ZodObject<{
     entity_id: z.ZodString;
     target_state: z.ZodString;
 }, z.core.$strip>;
+export declare const AdminEntityMigrateSchema: z.ZodObject<{
+    entity_id: z.ZodString;
+}, z.core.$strip>;
 export declare const AdminWorkerDrainSchema: z.ZodObject<{
     worker_id: z.ZodString;
 }, z.core.$strip>;

package/dist/src/execution/admin-schemas.js

@@ -133,6 +133,9 @@ export const AdminEntityResetSchema = z.object({
     entity_id: z.string().min(1),
     target_state: z.string().min(1),
 });
+export const AdminEntityMigrateSchema = z.object({
+    entity_id: z.string().min(1),
+});
 export const AdminWorkerDrainSchema = z.object({
     worker_id: z.string().min(1),
 });

package/dist/src/execution/cli.js

@@ -14,6 +14,7 @@ import { loadSeed } from "../config/seed-loader.js";
 import { resolveCorsOrigin } from "../cors.js";
 import { Engine } from "../engine/engine.js";
 import { EventEmitter } from "../engine/event-emitter.js";
+import { withTransaction } from "../main.js";
 import { DrizzleEntityRepository } from "../repositories/drizzle/entity.repo.js";
 import { DrizzleEventRepository } from "../repositories/drizzle/event.repo.js";
 import { DrizzleFlowRepository } from "../repositories/drizzle/flow.repo.js";
@@ -173,6 +174,7 @@ program
         transitionLogRepo,
         adapters: new Map(),
         eventEmitter,
+        withTransaction: (fn) => withTransaction(sqlite, fn),
     });
     const deps = {
         entities: entityRepo,

package/dist/src/execution/mcp-server.js

@@ -6,7 +6,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { DEFAULT_TIMEOUT_PROMPT } from "../engine/constants.js";
 import { isTerminal } from "../engine/state-machine.js";
 import { consoleLogger } from "../logger.js";
-import { AdminEntityCancelSchema, AdminEntityResetSchema, AdminFlowCreateSchema, AdminFlowPauseSchema, AdminFlowRestoreSchema, AdminFlowSnapshotSchema, AdminFlowUpdateSchema, AdminGateAttachSchema, AdminGateCreateSchema, AdminGateRerunSchema, AdminStateCreateSchema, AdminStateUpdateSchema, AdminTransitionCreateSchema, AdminTransitionUpdateSchema, AdminWorkerDrainSchema, } from "./admin-schemas.js";
+import { AdminEntityCancelSchema, AdminEntityMigrateSchema, AdminEntityResetSchema, AdminFlowCreateSchema, AdminFlowPauseSchema, AdminFlowRestoreSchema, AdminFlowSnapshotSchema, AdminFlowUpdateSchema, AdminGateAttachSchema, AdminGateCreateSchema, AdminGateRerunSchema, AdminStateCreateSchema, AdminStateUpdateSchema, AdminTransitionCreateSchema, AdminTransitionUpdateSchema, AdminWorkerDrainSchema, } from "./admin-schemas.js";
 import { handleFlowClaim } from "./handlers/flow.js";
 import { FlowFailSchema, FlowGetPromptSchema, FlowReportSchema, FlowSeedSchema, QueryEntitiesSchema, QueryEntitySchema, QueryFlowSchema, QueryInvocationsSchema, } from "./tool-schemas.js";
 function getSystemDefaultGateTimeoutMs() {
@@ -362,6 +362,11 @@ const TOOL_DEFINITIONS = [
             required: ["entity_id", "target_state"],
         },
     },
+    {
+        name: "admin.entity.migrate",
+        description: "Migrate an entity to the latest flow version. Validates that the entity's current state exists in the new version.",
+        inputSchema: { type: "object", properties: { entity_id: { type: "string" } }, required: ["entity_id"] },
+    },
     {
         name: "admin.worker.drain",
         description: "Mark a worker as draining — claimWork() will skip it.",
@@ -465,6 +470,8 @@ export async function callToolHandler(deps, name, safeArgs, opts) {
                 return await handleAdminEntityCancel(deps, safeArgs);
             case "admin.entity.reset":
                 return await handleAdminEntityReset(deps, safeArgs);
+            case "admin.entity.migrate":
+                return await handleAdminEntityMigrate(deps, safeArgs);
             case "admin.worker.drain":
                 return await handleAdminWorkerDrain(deps, safeArgs);
             case "admin.worker.undrain":
@@ -804,6 +811,32 @@ async function handleAdminEntityReset(deps, args) {
     });
     return jsonResult({ reset: true, entity_id: v.data.entity_id, state: updated.state });
 }
+async function handleAdminEntityMigrate(deps, args) {
+    const v = validateInput(AdminEntityMigrateSchema, args);
+    if (!v.ok)
+        return v.result;
+    const { entity_id: entityId } = v.data;
+    const entity = await deps.entities.get(entityId);
+    if (!entity)
+        return errorResult(`Entity not found: ${entityId}`);
+    const flow = await deps.flows.get(entity.flowId);
+    if (!flow)
+        return errorResult(`Flow not found: ${entity.flowId}`);
+    if (entity.flowVersion === flow.version) {
+        return jsonResult({
+            migrated: false,
+            message: "Entity is already on the latest version",
+            flowVersion: flow.version,
+        });
+    }
+    const stateExists = flow.states.some((s) => s.name === entity.state);
+    if (!stateExists) {
+        return errorResult(`Cannot migrate entity ${entityId}: current state '${entity.state}' does not exist in flow '${flow.name}' version ${flow.version}`);
+    }
+    await deps.entities.updateFlowVersion(entityId, flow.version);
+    const updated = await deps.entities.get(entityId);
+    return jsonResult(updated);
+}
 async function handleAdminWorkerDrain(deps, args) {
     const v = validateInput(AdminWorkerDrainSchema, args);
     if (!v.ok)

package/dist/src/main.d.ts

@@ -5,6 +5,12 @@ export declare function createDatabase(dbPath?: string): {
     db: ReturnType<typeof drizzle<typeof schema>>;
     sqlite: Database.Database;
 };
+/**
+ * Wraps `fn` in a BEGIN/COMMIT/ROLLBACK transaction on `sqlite`.
+ * If already inside a transaction, runs `fn` directly (allows nested calls).
+ * Supports both synchronous and Promise-returning `fn`.
+ */
+export declare function withTransaction<T>(sqlite: Database.Database, fn: () => T | Promise<T>): Promise<T>;
 export declare function runMigrations(db: ReturnType<typeof drizzle>, migrationsFolder?: string): void;
 export declare function bootstrap(dbPath?: string): {
     db: ReturnType<typeof drizzle>;

package/dist/src/main.js

@@ -10,6 +10,26 @@ export function createDatabase(dbPath = DB_PATH) {
     const db = drizzle(sqlite, { schema });
     return { db, sqlite };
 }
+/**
+ * Wraps `fn` in a BEGIN/COMMIT/ROLLBACK transaction on `sqlite`.
+ * If already inside a transaction, runs `fn` directly (allows nested calls).
+ * Supports both synchronous and Promise-returning `fn`.
+ */
+export async function withTransaction(sqlite, fn) {
+    if (sqlite.inTransaction) {
+        return fn();
+    }
+    sqlite.exec("BEGIN");
+    try {
+        const result = await fn();
+        sqlite.exec("COMMIT");
+        return result;
+    }
+    catch (err) {
+        sqlite.exec("ROLLBACK");
+        throw err;
+    }
+}
 export function runMigrations(db, migrationsFolder = "./drizzle") {
     migrate(db, { migrationsFolder });
 }

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

@@ -6,7 +6,7 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     private db;
     constructor(db: Db);
     private toEntity;
-    create(flowId: string, initialState: string, refs?: Refs): Promise<Entity>;
+    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>;
@@ -25,5 +25,6 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     clearExpiredAffinity(): Promise<string[]>;
     cancelEntity(entityId: string): Promise<void>;
     resetEntity(entityId: string, targetState: string): Promise<Entity>;
+    updateFlowVersion(entityId: string, version: number): Promise<void>;
 }
 export {};

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

@@ -24,7 +24,7 @@ export class DrizzleEntityRepository {
             affinityExpiresAt: row.affinityExpiresAt ? new Date(row.affinityExpiresAt) : null,
         };
     }
-    async create(flowId, initialState, refs) {
+    async create(flowId, initialState, refs, flowVersion) {
         const now = Date.now();
         const id = crypto.randomUUID();
         const row = {
@@ -35,7 +35,7 @@ export class DrizzleEntityRepository {
             artifacts: null,
             claimedBy: null,
             claimedAt: null,
-            flowVersion: 1,
+            flowVersion: flowVersion ?? 1,
             createdAt: now,
             updatedAt: now,
             affinityWorkerId: null,
@@ -205,4 +205,10 @@ export class DrizzleEntityRepository {
             throw new NotFoundError(`Entity not found: ${entityId}`);
         return this.toEntity(rows[0]);
     }
+    async updateFlowVersion(entityId, version) {
+        await this.db
+            .update(entities)
+            .set({ flowVersion: version, updatedAt: Date.now() })
+            .where(eq(entities.id, entityId));
+    }
 }

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

@@ -9,6 +9,7 @@ export declare class DrizzleFlowRepository implements IFlowRepository {
     create(input: CreateFlowInput): Promise<Flow>;
     get(id: string): Promise<Flow | null>;
     getByName(name: string): Promise<Flow | null>;
+    getAtVersion(flowId: string, version: number): Promise<Flow | null>;
     list(): Promise<Flow[]>;
     listAll(): Promise<Flow[]>;
     update(id: string, changes: UpdateFlowInput): Promise<Flow>;

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

@@ -116,6 +116,67 @@ export class DrizzleFlowRepository {
             return null;
         return this.hydrateFlow(rows[0]);
     }
+    async getAtVersion(flowId, version) {
+        const current = await this.get(flowId);
+        if (!current)
+            return null;
+        if (current.version === version)
+            return current;
+        const rows = this.db
+            .select()
+            .from(flowVersions)
+            .where(and(eq(flowVersions.flowId, flowId), eq(flowVersions.version, version)))
+            .all();
+        if (rows.length === 0)
+            return null;
+        const snap = rows[0].snapshot;
+        return {
+            id: flowId,
+            name: snap.name ?? current.name,
+            description: snap.description ?? null,
+            entitySchema: snap.entitySchema ?? null,
+            initialState: snap.initialState ?? current.initialState,
+            maxConcurrent: snap.maxConcurrent ?? 0,
+            maxConcurrentPerRepo: snap.maxConcurrentPerRepo ?? 0,
+            affinityWindowMs: snap.affinityWindowMs ?? 300000,
+            claimRetryAfterMs: snap.claimRetryAfterMs ?? null,
+            gateTimeoutMs: snap.gateTimeoutMs ?? null,
+            version,
+            createdBy: snap.createdBy ?? null,
+            discipline: snap.discipline ?? null,
+            defaultModelTier: snap.defaultModelTier ?? null,
+            timeoutPrompt: snap.timeoutPrompt ?? null,
+            paused: current.paused,
+            createdAt: snap.createdAt ? new Date(snap.createdAt) : null,
+            updatedAt: snap.updatedAt ? new Date(snap.updatedAt) : null,
+            states: (snap.states ?? []).map((s) => ({
+                id: s.id,
+                flowId,
+                name: s.name,
+                agentRole: s.agentRole ?? null,
+                modelTier: s.modelTier ?? null,
+                mode: s.mode ?? "passive",
+                promptTemplate: s.promptTemplate ?? null,
+                constraints: s.constraints ?? null,
+                onEnter: s.onEnter ?? null,
+                onExit: s.onExit ?? null,
+                retryAfterMs: s.retryAfterMs ?? null,
+            })),
+            transitions: (snap.transitions ?? []).map((t) => ({
+                id: t.id,
+                flowId,
+                fromState: t.fromState,
+                toState: t.toState,
+                trigger: t.trigger,
+                gateId: t.gateId ?? null,
+                condition: t.condition ?? null,
+                priority: t.priority ?? 0,
+                spawnFlow: t.spawnFlow ?? null,
+                spawnTemplate: t.spawnTemplate ?? null,
+                createdAt: t.createdAt ? new Date(t.createdAt) : null,
+            })),
+        };
+    }
     async list() {
         const rows = this.db.select().from(flowDefinitions).all();
         return rows.map((row) => this.hydrateFlow(row));
@@ -306,6 +367,10 @@ export class DrizzleFlowRepository {
                 createdAt: now,
             })
                 .run();
+            tx.update(flowDefinitions)
+                .set({ version: version + 1, updatedAt: now })
+                .where(eq(flowDefinitions.id, flowId))
+                .run();
             return version;
         });
         return {

package/dist/src/repositories/interfaces.d.ts

@@ -224,7 +224,7 @@ export interface CreateGateInput {
 /** Data-access contract for entity lifecycle operations. */
 export interface IEntityRepository {
     /** Create a new entity in the given flow's initial state. */
-    create(flowId: string, initialState: string, refs?: Refs): Promise<Entity>;
+    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number): Promise<Entity>;
     /** Get an entity by ID, or null if not found. */
     get(id: string): Promise<Entity | null>;
     /** Find entities in a given flow and state, up to an optional limit. */
@@ -259,6 +259,8 @@ export interface IEntityRepository {
     cancelEntity(entityId: string): Promise<void>;
     /** Move entity to targetState and clear claimedBy/claimedAt. Returns the updated entity. */
     resetEntity(entityId: string, targetState: string): Promise<Entity>;
+    /** Update an entity's pinned flow version. */
+    updateFlowVersion(entityId: string, version: number): Promise<void>;
 }
 /** Fields that can be updated on a flow's top-level definition */
 export type UpdateFlowInput = Partial<Omit<Flow, "id" | "states" | "transitions" | "createdAt" | "updatedAt">>;
@@ -276,6 +278,8 @@ export interface IFlowRepository {
     get(id: string): Promise<Flow | null>;
     /** Get a flow by unique name. Returns null if not found. */
     getByName(name: string): Promise<Flow | null>;
+    /** Load a flow definition at a specific version. Returns the snapshot if version < current, or live flow if version === current. */
+    getAtVersion(flowId: string, version: number): Promise<Flow | null>;
     /** Update a flow's top-level fields. */
     update(id: string, changes: UpdateFlowInput): Promise<Flow>;
     /** Add a state definition to a flow. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/defcon",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "engines": {