@wopr-network/defcon 1.6.1 → 1.8.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;

package/dist/src/engine/engine.js

@@ -72,10 +72,13 @@ export class Engine {
         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);
+        if (entity.state === "cancelled") {
+            throw new ValidationError(`Entity "${entityId}" is cancelled and cannot be transitioned`);
+        }
+        // 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)
@@ -325,7 +328,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) {
@@ -466,6 +469,8 @@ export class Engine {
             const entity = entityMap.get(pending.entityId);
             if (!entity)
                 continue;
+            if (entity.state === "cancelled")
+                continue;
             // Guard: entity state must still match the invocation's stage — if another worker
             // transitioned the entity between candidate fetch and now, skip this candidate.
             if (entity.state !== pending.stage)
@@ -516,9 +521,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",
@@ -543,12 +550,18 @@ 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);
+                if (claimed.state === "cancelled") {
+                    await this.entityRepo.release(claimed.id, worker_id ?? `agent:${role}`);
+                    continue;
+                }
+                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);
@@ -647,7 +660,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/engine/event-types.d.ts

@@ -24,6 +24,14 @@ export type EngineEvent = {
     entityId: string;
     flowId: string;
     emittedAt: Date;
+} | {
+    type: "entity.cancelled";
+    entityId: string;
+    flowId: string;
+    cancelledBy: string;
+    reason: string | null;
+    cascade: boolean;
+    emittedAt: Date;
 } | {
     type: "invocation.created";
     entityId: string;

package/dist/src/engine/flow-spawner.js

@@ -11,7 +11,7 @@ export async function executeSpawn(transition, parentEntity, flowRepo, entityRep
     const flow = await flowRepo.getByName(transition.spawnFlow);
     if (!flow)
         throw new NotFoundError(`Spawn flow "${transition.spawnFlow}" not found`);
-    const childEntity = await entityRepo.create(flow.id, flow.initialState, parentEntity.refs ?? undefined);
+    const childEntity = await entityRepo.create(flow.id, flow.initialState, parentEntity.refs ?? undefined, undefined, parentEntity.id);
     try {
         await entityRepo.appendSpawnedChild(parentEntity.id, {
             childId: childEntity.id,

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

@@ -119,11 +119,16 @@ export declare const AdminFlowPauseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const AdminEntityCancelSchema: z.ZodObject<{
     entity_id: z.ZodString;
+    cascade: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 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

@@ -128,11 +128,16 @@ export const AdminFlowPauseSchema = z.object({
 });
 export const AdminEntityCancelSchema = z.object({
     entity_id: z.string().min(1),
+    cascade: z.boolean().optional().default(false),
+    reason: z.string().optional(),
 });
 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

@@ -184,6 +184,7 @@ program
         transitions: transitionLogRepo,
         eventRepo: new DrizzleEventRepository(db),
         engine,
+        withTransaction: (fn) => withTransaction(sqlite, fn),
     };
     const reaperInterval = parseInt(opts.reaperInterval, 10);
     if (Number.isNaN(reaperInterval) || reaperInterval < 1000) {

package/dist/src/execution/mcp-server.d.ts

@@ -11,6 +11,7 @@ export interface McpServerDeps {
     eventRepo: IEventRepository;
     engine?: Engine;
     logger?: Logger;
+    withTransaction?: <T>(fn: () => T | Promise<T>) => Promise<T>;
 }
 export interface McpServerOpts {
     /** DEFCON_ADMIN_TOKEN — if set, admin.* tools require this token */

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() {
@@ -350,8 +350,16 @@ const TOOL_DEFINITIONS = [
     },
     {
         name: "admin.entity.cancel",
-        description: "Cancel an entity — fails active invocation, moves to 'cancelled' terminal state.",
-        inputSchema: { type: "object", properties: { entity_id: { type: "string" } }, required: ["entity_id"] },
+        description: "Cancel an entity — fails active invocation, moves to 'cancelled' terminal state. Use cascade to cancel all descendant entities.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entity_id: { type: "string" },
+                cascade: { type: "boolean", description: "Recursively cancel all child entities" },
+                reason: { type: "string", description: "Cancellation reason" },
+            },
+            required: ["entity_id"],
+        },
     },
     {
         name: "admin.entity.reset",
@@ -362,6 +370,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 +478,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":
@@ -748,31 +763,67 @@ async function handleAdminEntityCancel(deps, args) {
     const v = validateInput(AdminEntityCancelSchema, args);
     if (!v.ok)
         return v.result;
-    const entity = await deps.entities.get(v.data.entity_id);
+    const { entity_id, cascade, reason } = v.data;
+    const entity = await deps.entities.get(entity_id);
     if (!entity)
-        return errorResult(`Entity not found: ${v.data.entity_id}`);
-    const flow = await deps.flows.get(entity.flowId);
-    if (!flow)
-        return errorResult(`Flow not found for entity: ${v.data.entity_id}`);
-    const cancelledState = flow.states.find((s) => s.name === "cancelled");
-    if (!cancelledState)
-        return errorResult(`State 'cancelled' not found in flow '${flow.name}'`);
-    const invocations = await deps.invocations.findByEntity(v.data.entity_id);
-    for (const inv of invocations) {
-        if (inv.completedAt === null && inv.failedAt === null) {
-            await deps.invocations.fail(inv.id, "Cancelled by admin");
+        return errorResult(`Entity not found: ${entity_id}`);
+    if (entity.state === "cancelled" && !cascade)
+        return errorResult(`Entity ${entity_id} is already cancelled`);
+    const cancelled = [];
+    const MAX_CANCEL_DEPTH = 100;
+    async function cancelOne(eid, depth, visited) {
+        if (visited.has(eid))
+            return;
+        visited.add(eid);
+        if (depth > MAX_CANCEL_DEPTH) {
+            throw new Error(`cancelOne exceeded maximum recursion depth of ${MAX_CANCEL_DEPTH} — possible cycle or pathologically deep entity tree`);
+        }
+        const e = await deps.entities.get(eid);
+        const alreadyCancelled = !e || e.state === "cancelled";
+        if (!alreadyCancelled) {
+            const invocations = await deps.invocations.findByEntity(eid);
+            for (const inv of invocations) {
+                if (inv.completedAt === null && inv.failedAt === null) {
+                    await deps.invocations.fail(inv.id, reason ?? "Cancelled by admin");
+                }
+            }
+            await deps.entities.cancelEntity(eid);
+            await deps.transitions.record({
+                entityId: eid,
+                fromState: e.state,
+                toState: "cancelled",
+                trigger: "admin.cancel",
+                invocationId: null,
+                timestamp: new Date(),
+            });
+            if (deps.engine) {
+                await deps.engine.emit({
+                    type: "entity.cancelled",
+                    entityId: eid,
+                    flowId: e.flowId,
+                    cancelledBy: "admin",
+                    reason: reason ?? null,
+                    cascade: cascade ?? false,
+                    emittedAt: new Date(),
+                });
+            }
+            cancelled.push(eid);
+        }
+        if (cascade) {
+            const children = await deps.entities.findByParentId(eid);
+            for (const child of children) {
+                await cancelOne(child.id, depth + 1, visited);
+            }
         }
     }
-    await deps.entities.cancelEntity(v.data.entity_id);
-    await deps.transitions.record({
-        entityId: v.data.entity_id,
-        fromState: entity.state,
-        toState: "cancelled",
-        trigger: "admin.cancel",
-        invocationId: null,
-        timestamp: new Date(),
-    });
-    return jsonResult({ cancelled: true, entity_id: v.data.entity_id });
+    const run = () => cancelOne(entity_id, 0, new Set());
+    if (deps.withTransaction) {
+        await deps.withTransaction(run);
+    }
+    else {
+        await run();
+    }
+    return jsonResult({ cancelled: true, entity_id, cancelled_count: cancelled.length, cancelled_ids: cancelled });
 }
 async function handleAdminEntityReset(deps, args) {
     const v = validateInput(AdminEntityResetSchema, args);
@@ -804,6 +855,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/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, parentEntityId?: string): Promise<Entity>;
     get(id: string): Promise<Entity | null>;
     findByFlowAndState(flowId: string, state: string, limit?: number): Promise<Entity[]>;
     hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
@@ -23,7 +23,9 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     reapExpired(ttlMs: number): Promise<string[]>;
     setAffinity(entityId: string, workerId: string, role: string, expiresAt: Date): Promise<void>;
     clearExpiredAffinity(): Promise<string[]>;
+    findByParentId(parentEntityId: string): Promise<Entity[]>;
     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

@@ -22,9 +22,10 @@ export class DrizzleEntityRepository {
             affinityWorkerId: row.affinityWorkerId ?? null,
             affinityRole: row.affinityRole ?? null,
             affinityExpiresAt: row.affinityExpiresAt ? new Date(row.affinityExpiresAt) : null,
+            parentEntityId: row.parentEntityId ?? null,
         };
     }
-    async create(flowId, initialState, refs) {
+    async create(flowId, initialState, refs, flowVersion, parentEntityId) {
         const now = Date.now();
         const id = crypto.randomUUID();
         const row = {
@@ -35,12 +36,13 @@ export class DrizzleEntityRepository {
             artifacts: null,
             claimedBy: null,
             claimedAt: null,
-            flowVersion: 1,
+            flowVersion: flowVersion ?? 1,
             createdAt: now,
             updatedAt: now,
             affinityWorkerId: null,
             affinityRole: null,
             affinityExpiresAt: null,
+            parentEntityId: parentEntityId ?? null,
         };
         await this.db.insert(entities).values(row);
         return this.toEntity(row);
@@ -188,6 +190,10 @@ export class DrizzleEntityRepository {
             .all();
         return rows.map((r) => r.id);
     }
+    async findByParentId(parentEntityId) {
+        const rows = await this.db.select().from(entities).where(eq(entities.parentEntityId, parentEntityId));
+        return rows.map((r) => this.toEntity(r));
+    }
     async cancelEntity(entityId) {
         await this.db
             .update(entities)
@@ -205,4 +211,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/drizzle/schema.d.ts

@@ -1326,6 +1326,25 @@ export declare const entities: import("drizzle-orm/sqlite-core").SQLiteTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        parentEntityId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "parent_entity_id";
+            tableName: "entities";
+            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

@@ -95,10 +95,12 @@ export const entities = sqliteTable("entities", {
     affinityWorkerId: text("affinity_worker_id"),
     affinityRole: text("affinity_role"),
     affinityExpiresAt: integer("affinity_expires_at"),
+    parentEntityId: text("parent_entity_id"),
 }, (table) => ({
     flowStateIdx: index("entities_flow_state_idx").on(table.flowId, table.state),
     claimIdx: index("entities_claim_idx").on(table.flowId, table.state, table.claimedBy),
     affinityIdx: index("entities_affinity_idx").on(table.affinityWorkerId, table.affinityRole, table.affinityExpiresAt),
+    parentIdx: index("entities_parent_idx").on(table.parentEntityId),
 }));
 export const invocations = sqliteTable("invocations", {
     id: text("id").primaryKey(),

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

@@ -35,6 +35,7 @@ export interface Entity {
     affinityWorkerId: string | null;
     affinityRole: string | null;
     affinityExpiresAt: Date | null;
+    parentEntityId: string | null;
 }
 /** A single agent invocation tied to an entity */
 export interface Invocation {
@@ -224,7 +225,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, parentEntityId?: string): 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. */
@@ -255,10 +256,14 @@ export interface IEntityRepository {
         childFlow: string;
         spawnedAt: string;
     }): Promise<void>;
+    /** Find all direct children of a parent entity. */
+    findByParentId(parentEntityId: string): Promise<Entity[]>;
     /** Move entity to 'cancelled' terminal state and clear claimedBy/claimedAt. */
     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 +281,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/drizzle/0015_add_parent_entity_id.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `entities` ADD `parent_entity_id` text;--> statement-breakpoint
+CREATE INDEX `entities_parent_idx` ON `entities` (`parent_entity_id`);

package/drizzle/meta/_journal.json

@@ -106,6 +106,13 @@
       "when": 1773031139526,
       "tag": "0014_smiling_crusher_hogan",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1773200000001,
+      "tag": "0015_add_parent_entity_id",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

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