@wopr-network/defcon 1.10.0 → 1.11.0

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/cli.js

@@ -181,6 +181,7 @@ program
         adapters: new Map(),
         eventEmitter,
         withTransaction: (fn) => withTransaction(sqlite, fn),
+        domainEvents: domainEventRepo,
     });
     const deps = {
         entities: entityRepo,

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

@@ -6,6 +6,8 @@ export declare class DrizzleDomainEventRepository implements IDomainEventReposit
     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;

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

@@ -20,6 +20,43 @@ export class DrizzleDomainEventRepository {
             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) {

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

@@ -374,6 +374,11 @@ export interface IDomainEventRepository {
         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 {

package/package.json

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