@wopr-network/defcon 1.9.0 → 1.11.0

package/dist/src/engine/domain-event-adapter.d.ts

@@ -0,0 +1,8 @@
+import type { IDomainEventRepository } from "../repositories/interfaces.js";
+import type { EngineEvent, IEventBusAdapter } from "./event-types.js";
+/** IEventBusAdapter that persists every engine event (except definition.changed) to the domain_events table. */
+export declare class DomainEventPersistAdapter implements IEventBusAdapter {
+    private readonly repo;
+    constructor(repo: IDomainEventRepository);
+    emit(event: EngineEvent): Promise<void>;
+}

package/dist/src/engine/domain-event-adapter.js

@@ -0,0 +1,14 @@
+/** IEventBusAdapter that persists every engine event (except definition.changed) to the domain_events table. */
+export class DomainEventPersistAdapter {
+    repo;
+    constructor(repo) {
+        this.repo = repo;
+    }
+    async emit(event) {
+        // Skip events that have no entityId (e.g. definition.changed)
+        if (!("entityId" in event) || !event.entityId)
+            return;
+        const { type, entityId, emittedAt, ...rest } = event;
+        await this.repo.append(type, entityId, rest);
+    }
+}

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

@@ -1,5 +1,5 @@
 import type { Logger } from "../logger.js";
-import type { Artifacts, Entity, IEntityRepository, IFlowRepository, IGateRepository, IInvocationRepository, ITransitionLogRepository } from "../repositories/interfaces.js";
+import type { Artifacts, Entity, IDomainEventRepository, IEntityRepository, IFlowRepository, IGateRepository, IInvocationRepository, ITransitionLogRepository } from "../repositories/interfaces.js";
 import type { IEventBusAdapter } from "./event-types.js";
 export interface ProcessSignalResult {
     newState?: string;
@@ -41,6 +41,8 @@ export interface EngineDeps {
     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>;
+    /** Optional domain event repository. When provided, claimWork uses CAS on the event log to prevent concurrent claim races. */
+    domainEvents?: IDomainEventRepository;
 }
 export declare class Engine {
     private entityRepo;
@@ -52,6 +54,7 @@ export declare class Engine {
     private eventEmitter;
     private readonly logger;
     private readonly withTransactionFn;
+    private readonly domainEventRepo;
     private drainingWorkers;
     constructor(deps: EngineDeps);
     drainWorker(workerId: string): void;

package/dist/src/engine/engine.js

@@ -18,6 +18,7 @@ export class Engine {
     eventEmitter;
     logger;
     withTransactionFn;
+    domainEventRepo;
     drainingWorkers = new Set();
     constructor(deps) {
         this.entityRepo = deps.entityRepo;
@@ -29,6 +30,7 @@ export class Engine {
         this.eventEmitter = deps.eventEmitter;
         this.logger = deps.logger ?? consoleLogger;
         this.withTransactionFn = deps.withTransaction ?? null;
+        this.domainEventRepo = deps.domainEvents ?? null;
     }
     drainWorker(workerId) {
         this.drainingWorkers.add(workerId);
@@ -476,9 +478,30 @@ export class Engine {
             if (entity.state !== pending.stage)
                 continue;
             const entityClaimToken = worker_id ?? `agent:${role}`;
+            // CAS guard: atomically append an invocation.claimed event using optimistic concurrency.
+            // Only one writer wins the unique (entityId, sequence) constraint — losers move to the next candidate.
+            if (this.domainEventRepo) {
+                const lastSeq = await this.domainEventRepo.getLastSequence(entity.id);
+                const casResult = await this.domainEventRepo.appendCas("invocation.claim_attempted", entity.id, { agentId: entityClaimToken, invocationId: pending.id, stage: pending.stage }, lastSeq);
+                if (!casResult)
+                    continue; // Another agent won the race
+            }
             const claimed = await this.entityRepo.claimById(entity.id, entityClaimToken);
-            if (!claimed)
+            if (!claimed) {
+                // claimById failed after CAS success — record rollback event for observability
+                if (this.domainEventRepo) {
+                    try {
+                        await this.domainEventRepo.append("invocation.claim_released", entity.id, {
+                            agentId: entityClaimToken,
+                            reason: "claimById_failed",
+                        });
+                    }
+                    catch (err) {
+                        this.logger.warn("[engine] CAS claim rollback event failed", { err });
+                    }
+                }
                 continue;
+            }
             // Post-claim state validation — entity may have transitioned between guard check and claim
             if (claimed.state !== pending.stage) {
                 try {

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

@@ -136,3 +136,8 @@ export declare const AdminGateRerunSchema: z.ZodObject<{
     entity_id: z.ZodString;
     gate_name: z.ZodString;
 }, z.core.$strip>;
+export declare const AdminEventsListSchema: z.ZodObject<{
+    entity_id: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;

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

@@ -145,3 +145,8 @@ export const AdminGateRerunSchema = z.object({
     entity_id: z.string().min(1),
     gate_name: z.string().min(1),
 });
+export const AdminEventsListSchema = z.object({
+    entity_id: z.string().min(1),
+    type: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(500).default(100),
+});

package/dist/src/execution/cli.js

@@ -12,9 +12,11 @@ import { createHttpServer } from "../api/server.js";
 import { exportSeed } from "../config/exporter.js";
 import { loadSeed } from "../config/seed-loader.js";
 import { resolveCorsOrigin } from "../cors.js";
+import { DomainEventPersistAdapter } from "../engine/domain-event-adapter.js";
 import { Engine } from "../engine/engine.js";
 import { EventEmitter } from "../engine/event-emitter.js";
 import { withTransaction } from "../main.js";
+import { DrizzleDomainEventRepository } from "../repositories/drizzle/domain-event.repo.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";
@@ -162,12 +164,14 @@ program
     const invocationRepo = new DrizzleInvocationRepository(db);
     const gateRepo = new DrizzleGateRepository(db);
     const transitionLogRepo = new DrizzleTransitionLogRepository(db);
+    const domainEventRepo = new DrizzleDomainEventRepository(db);
     const eventEmitter = new EventEmitter();
     eventEmitter.register({
         emit: async (event) => {
             process.stderr.write(`[event] ${event.type} ${JSON.stringify(event)}\n`);
         },
     });
+    eventEmitter.register(new DomainEventPersistAdapter(domainEventRepo));
     const engine = new Engine({
         entityRepo,
         flowRepo,
@@ -177,6 +181,7 @@ program
         adapters: new Map(),
         eventEmitter,
         withTransaction: (fn) => withTransaction(sqlite, fn),
+        domainEvents: domainEventRepo,
     });
     const deps = {
         entities: entityRepo,
@@ -185,6 +190,7 @@ program
         gates: gateRepo,
         transitions: transitionLogRepo,
         eventRepo: new DrizzleEventRepository(db),
+        domainEvents: domainEventRepo,
         engine,
         withTransaction: (fn) => withTransaction(sqlite, fn),
     };

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

@@ -1,7 +1,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { Engine } from "../engine/engine.js";
 import type { Logger } from "../logger.js";
-import type { IEntityRepository, IEventRepository, IFlowRepository, IGateRepository, IInvocationRepository, ITransitionLogRepository } from "../repositories/interfaces.js";
+import type { IDomainEventRepository, IEntityRepository, IEventRepository, IFlowRepository, IGateRepository, IInvocationRepository, ITransitionLogRepository } from "../repositories/interfaces.js";
 export interface McpServerDeps {
     entities: IEntityRepository;
     flows: IFlowRepository;
@@ -9,6 +9,7 @@ export interface McpServerDeps {
     gates: IGateRepository;
     transitions: ITransitionLogRepository;
     eventRepo: IEventRepository;
+    domainEvents?: IDomainEventRepository;
     engine?: Engine;
     logger?: Logger;
     withTransaction?: <T>(fn: () => T | Promise<T>) => Promise<T>;

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, AdminEntityMigrateSchema, AdminEntityResetSchema, AdminFlowCreateSchema, AdminFlowPauseSchema, AdminFlowRestoreSchema, AdminFlowSnapshotSchema, AdminFlowUpdateSchema, AdminGateAttachSchema, AdminGateCreateSchema, AdminGateRerunSchema, AdminStateCreateSchema, AdminStateUpdateSchema, AdminTransitionCreateSchema, AdminTransitionUpdateSchema, AdminWorkerDrainSchema, } from "./admin-schemas.js";
+import { AdminEntityCancelSchema, AdminEntityMigrateSchema, AdminEntityResetSchema, AdminEventsListSchema, 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() {
@@ -394,6 +394,19 @@ const TOOL_DEFINITIONS = [
             required: ["entity_id", "gate_name"],
         },
     },
+    {
+        name: "admin.events.list",
+        description: "List domain events for an entity. Returns append-only audit log entries ordered by sequence.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entity_id: { type: "string", description: "Entity ID to list events for" },
+                type: { type: "string", description: "Optional event type filter (e.g. 'entity.transitioned')" },
+                limit: { type: "number", description: "Max events to return (default 100, max 500)" },
+            },
+            required: ["entity_id"],
+        },
+    },
 ];
 export function createMcpServer(deps, opts) {
     const server = new Server({ name: "defcon", version: "0.1.0" }, { capabilities: { tools: {} } });
@@ -486,6 +499,8 @@ export async function callToolHandler(deps, name, safeArgs, opts) {
                 return await handleAdminWorkerUndrain(deps, safeArgs);
             case "admin.gate.rerun":
                 return await handleAdminGateRerun(deps, safeArgs);
+            case "admin.events.list":
+                return await handleAdminEventsList(deps, safeArgs);
             default:
                 return errorResult(`Unknown tool: ${name}`);
         }
@@ -1121,3 +1136,16 @@ async function handleAdminFlowRestore(deps, args) {
     emitDefinitionChanged(deps.eventRepo, flow.id, "admin.flow.restore", { version: v.data.version });
     return jsonResult({ restored: true, version: v.data.version });
 }
+async function handleAdminEventsList(deps, args) {
+    if (!deps.domainEvents) {
+        return errorResult("Domain events repository not available");
+    }
+    const parsed = validateInput(AdminEventsListSchema, args);
+    if (!parsed.ok)
+        return parsed.result;
+    const events = await deps.domainEvents.list(parsed.data.entity_id, {
+        type: parsed.data.type,
+        limit: parsed.data.limit,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(events, null, 2) }] };
+}

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

@@ -0,0 +1,16 @@
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import type { DomainEvent, IDomainEventRepository } from "../interfaces.js";
+import type * as schema from "./schema.js";
+type Db = BetterSQLite3Database<typeof schema>;
+export declare class DrizzleDomainEventRepository implements IDomainEventRepository {
+    private readonly db;
+    constructor(db: Db);
+    append(type: string, entityId: string, payload: Record<string, unknown>): Promise<DomainEvent>;
+    getLastSequence(entityId: string): Promise<number>;
+    appendCas(type: string, entityId: string, payload: Record<string, unknown>, expectedSequence: number): Promise<DomainEvent | null>;
+    list(entityId: string, opts?: {
+        type?: string;
+        limit?: number;
+    }): Promise<DomainEvent[]>;
+}
+export {};

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

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { and, eq, sql } from "drizzle-orm";
+import { domainEvents } from "./schema.js";
+export class DrizzleDomainEventRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async append(type, entityId, payload) {
+        return this.db.transaction((tx) => {
+            const maxRow = tx
+                .select({ maxSeq: sql `coalesce(max(${domainEvents.sequence}), 0)` })
+                .from(domainEvents)
+                .where(eq(domainEvents.entityId, entityId))
+                .get();
+            const sequence = (maxRow?.maxSeq ?? 0) + 1;
+            const id = randomUUID();
+            const emittedAt = Date.now();
+            tx.insert(domainEvents).values({ id, type, entityId, payload, sequence, emittedAt }).run();
+            return { id, type, entityId, payload, sequence, emittedAt };
+        });
+    }
+    async getLastSequence(entityId) {
+        const row = this.db
+            .select({ maxSeq: sql `coalesce(max(${domainEvents.sequence}), 0)` })
+            .from(domainEvents)
+            .where(eq(domainEvents.entityId, entityId))
+            .get();
+        return row?.maxSeq ?? 0;
+    }
+    async appendCas(type, entityId, payload, expectedSequence) {
+        try {
+            return this.db.transaction((tx) => {
+                const currentRow = tx
+                    .select({ maxSeq: sql `coalesce(max(${domainEvents.sequence}), 0)` })
+                    .from(domainEvents)
+                    .where(eq(domainEvents.entityId, entityId))
+                    .get();
+                const currentSeq = currentRow?.maxSeq ?? 0;
+                if (currentSeq !== expectedSequence) {
+                    return null;
+                }
+                const newSequence = expectedSequence + 1;
+                const id = randomUUID();
+                const emittedAt = Date.now();
+                tx.insert(domainEvents).values({ id, type, entityId, payload, sequence: newSequence, emittedAt }).run();
+                return { id, type, entityId, payload, sequence: newSequence, emittedAt };
+            });
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                (("code" in err && err.code === "SQLITE_CONSTRAINT_UNIQUE") ||
+                    ("code" in err && err.code === "23505") ||
+                    err.message.includes("UNIQUE constraint failed"))) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    async list(entityId, opts) {
+        const conditions = [eq(domainEvents.entityId, entityId)];
+        if (opts?.type) {
+            conditions.push(eq(domainEvents.type, opts.type));
+        }
+        const rows = this.db
+            .select()
+            .from(domainEvents)
+            .where(and(...conditions))
+            .orderBy(domainEvents.sequence)
+            .limit(opts?.limit ?? 100)
+            .all();
+        return rows.map((r) => ({
+            id: r.id,
+            type: r.type,
+            entityId: r.entityId,
+            payload: r.payload,
+            sequence: r.sequence,
+            emittedAt: r.emittedAt,
+        }));
+    }
+}

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

@@ -1,3 +1,4 @@
+export { DrizzleDomainEventRepository } from "./domain-event.repo.js";
 export { DrizzleEntityRepository } from "./entity.repo.js";
 export { DrizzleEventRepository } from "./event.repo.js";
 export { DrizzleFlowRepository } from "./flow.repo.js";

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

@@ -1,4 +1,5 @@
 // Drizzle ORM implementations of repository interfaces
+export { DrizzleDomainEventRepository } from "./domain-event.repo.js";
 export { DrizzleEntityRepository } from "./entity.repo.js";
 export { DrizzleEventRepository } from "./event.repo.js";
 export { DrizzleFlowRepository } from "./flow.repo.js";

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

@@ -2034,3 +2034,118 @@ export declare const events: import("drizzle-orm/sqlite-core").SQLiteTableWithCo
     };
     dialect: "sqlite";
 }>;
+export declare const domainEvents: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "domain_events";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "domain_events";
+            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;
+        }>;
+        type: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "type";
+            tableName: "domain_events";
+            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;
+        }>;
+        entityId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "entity_id";
+            tableName: "domain_events";
+            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;
+        }>;
+        payload: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "payload";
+            tableName: "domain_events";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sequence: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "sequence";
+            tableName: "domain_events";
+            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;
+        }, {}, {}>;
+        emittedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "emitted_at";
+            tableName: "domain_events";
+            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;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;

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

@@ -162,3 +162,14 @@ export const events = sqliteTable("events", {
     entityIdIdx: index("events_entity_id_idx").on(table.entityId),
     emittedAtIdx: index("events_emitted_at_idx").on(table.emittedAt),
 }));
+export const domainEvents = sqliteTable("domain_events", {
+    id: text("id").primaryKey(),
+    type: text("type").notNull(),
+    entityId: text("entity_id").notNull(),
+    payload: text("payload", { mode: "json" }).notNull(),
+    sequence: integer("sequence").notNull(),
+    emittedAt: integer("emitted_at").notNull(),
+}, (table) => ({
+    entitySeqIdx: uniqueIndex("domain_events_entity_seq_idx").on(table.entityId, table.sequence),
+    typeIdx: index("domain_events_type_idx").on(table.type, table.emittedAt),
+}));

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

@@ -356,6 +356,30 @@ export interface IEventRepository {
     /** Get the most recent events across all entities, ordered by emittedAt descending. */
     findRecent(limit?: number): Promise<EventRow[]>;
 }
+/** A persisted domain event from the append-only audit log. */
+export interface DomainEvent {
+    id: string;
+    type: string;
+    entityId: string;
+    payload: Record<string, unknown>;
+    sequence: number;
+    emittedAt: number;
+}
+/** Data-access contract for the append-only domain_events table. */
+export interface IDomainEventRepository {
+    /** Append a domain event. Sequence is computed as max(sequence)+1 for the entity. */
+    append(type: string, entityId: string, payload: Record<string, unknown>): Promise<DomainEvent>;
+    /** List domain events for an entity, optionally filtered by type, ordered by sequence ascending. */
+    list(entityId: string, opts?: {
+        type?: string;
+        limit?: number;
+    }): Promise<DomainEvent[]>;
+    /** Get the current max sequence number for an entity (0 if no events exist). */
+    getLastSequence(entityId: string): Promise<number>;
+    /** Append a domain event only if the entity's current max sequence equals expectedSequence.
+     *  Returns the event on success, or null if another writer won (unique constraint violation). */
+    appendCas(type: string, entityId: string, payload: Record<string, unknown>, expectedSequence: number): Promise<DomainEvent | null>;
+}
 /** Data-access contract for gate definitions and result recording. */
 export interface IGateRepository {
     /** Create a new gate definition. */

package/drizzle/0016_domain_events.sql

@@ -0,0 +1,11 @@
+CREATE TABLE `domain_events` (
+	`id` text PRIMARY KEY NOT NULL,
+	`type` text NOT NULL,
+	`entity_id` text NOT NULL,
+	`payload` text NOT NULL,
+	`sequence` integer NOT NULL,
+	`emitted_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `domain_events_entity_seq_idx` ON `domain_events` (`entity_id`,`sequence`);--> statement-breakpoint
+CREATE INDEX `domain_events_type_idx` ON `domain_events` (`type`,`emitted_at`);