@wopr-network/defcon 1.8.0 → 1.10.0

package/dist/src/api/router.d.ts

@@ -6,7 +6,8 @@ export interface ParsedRequest {
 }
 export interface ApiResponse {
     status: number;
-    body: unknown;
+    body?: unknown;
+    html?: string;
 }
 type Handler = (req: ParsedRequest) => Promise<ApiResponse>;
 interface MatchResult {

package/dist/src/api/server.d.ts

@@ -2,6 +2,7 @@ import http from "node:http";
 import type { Engine } from "../engine/engine.js";
 import type { McpServerDeps } from "../execution/mcp-server.js";
 import type { Logger } from "../logger.js";
+import type { UiSseAdapter } from "../ui/sse.js";
 export interface HttpServerDeps {
     engine: Engine;
     mcpDeps: McpServerDeps;
@@ -9,5 +10,7 @@ export interface HttpServerDeps {
     workerToken?: string;
     corsOrigins?: string[];
     logger?: Logger;
+    enableUi?: boolean;
+    uiSseAdapter?: UiSseAdapter;
 }
 export declare function createHttpServer(deps: HttpServerDeps): http.Server;

package/dist/src/api/server.js

@@ -2,6 +2,7 @@ import { createHash, timingSafeEqual } from "node:crypto";
 import http from "node:http";
 import { callToolHandler } from "../execution/mcp-server.js";
 import { consoleLogger } from "../logger.js";
+import { UI_HTML } from "../ui/index.html.js";
 import { Router } from "./router.js";
 function extractBearerToken(header) {
     if (!header)
@@ -274,6 +275,52 @@ export function createHttpServer(deps) {
         const result = await callToolHandler(deps.mcpDeps, "admin.gate.rerun", { entity_id: req.params.id, gate_name: req.params.gateName }, { adminToken: deps.adminToken, callerToken });
         return mcpResultToApi(result);
     });
+    // --- UI routes (optional, enabled via enableUi) ---
+    if (deps.enableUi) {
+        router.add("GET", "/ui", async () => {
+            // No auth here: browsers navigating to /ui can't send Authorization headers.
+            // Auth is handled in the browser (token prompt) and enforced on API calls.
+            return { status: 200, html: "UI" };
+        });
+        router.add("GET", "/api/ui/entity/:id/events", async (req) => {
+            const authErr = requireAdminToken(deps, req);
+            if (authErr)
+                return authErr;
+            const limitStr = req.query.get("limit");
+            const limit = limitStr !== null ? parseInt(limitStr, 10) : 100;
+            if (limitStr !== null && (!Number.isFinite(limit) || limit <= 0)) {
+                return { status: 400, body: { error: "invalid limit parameter" } };
+            }
+            const evts = await deps.mcpDeps.eventRepo.findByEntity(req.params.id, limit);
+            return { status: 200, body: evts };
+        });
+        router.add("GET", "/api/ui/entity/:id/invocations", async (req) => {
+            const authErr = requireAdminToken(deps, req);
+            if (authErr)
+                return authErr;
+            const invocations = await deps.mcpDeps.invocations.findByEntity(req.params.id);
+            return { status: 200, body: invocations };
+        });
+        router.add("GET", "/api/ui/entity/:id/gates", async (req) => {
+            const authErr = requireAdminToken(deps, req);
+            if (authErr)
+                return authErr;
+            const results = await deps.mcpDeps.gates.resultsFor(req.params.id);
+            return { status: 200, body: results };
+        });
+        router.add("GET", "/api/ui/events/recent", async (req) => {
+            const authErr = requireAdminToken(deps, req);
+            if (authErr)
+                return authErr;
+            const limitStr = req.query.get("limit");
+            const limit = limitStr !== null ? parseInt(limitStr, 10) : 200;
+            if (limitStr !== null && (!Number.isFinite(limit) || limit <= 0)) {
+                return { status: 400, body: { error: "invalid limit parameter" } };
+            }
+            const evts = await deps.mcpDeps.eventRepo.findRecent(limit);
+            return { status: 200, body: evts };
+        });
+    }
     // --- HTTP server ---
     const server = http.createServer(async (req, res) => {
         // CORS
@@ -297,6 +344,35 @@ export function createHttpServer(deps) {
             return;
         }
         const url = new URL(req.url ?? "/", `http://localhost`);
+        // SSE endpoint — handled before router (holds connection open)
+        if (deps.enableUi && url.pathname === "/api/ui/events" && req.method === "GET") {
+            const queryToken = url.searchParams.get("token") ?? undefined;
+            const headerToken = extractBearerToken(req.headers.authorization);
+            const callerToken = headerToken ?? queryToken;
+            const configuredToken = deps.adminToken?.trim() || undefined;
+            if (configuredToken) {
+                if (!callerToken) {
+                    res.writeHead(401, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Unauthorized" }));
+                    return;
+                }
+                const hashA = createHash("sha256").update(configuredToken).digest();
+                const hashB = createHash("sha256").update(callerToken).digest();
+                if (!timingSafeEqual(hashA, hashB)) {
+                    res.writeHead(401, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Unauthorized" }));
+                    return;
+                }
+            }
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            });
+            res.write(":\n\n"); // SSE comment to establish connection
+            deps.uiSseAdapter?.addClient(res);
+            return;
+        }
         const match = router.match(req.method ?? "GET", url.pathname);
         if (!match) {
             res.writeHead(404, { "Content-Type": "application/json" });
@@ -337,6 +413,10 @@ export function createHttpServer(deps) {
             if (apiRes.status === 204) {
                 res.writeHead(204).end();
             }
+            else if (apiRes.html !== undefined) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(UI_HTML);
+            }
             else {
                 res.writeHead(apiRes.status, { "Content-Type": "application/json" });
                 res.end(JSON.stringify(apiRes.body));

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/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";
@@ -23,6 +25,7 @@ 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 { UiSseAdapter } from "../ui/sse.js";
 import { WebSocketBroadcaster } from "../ws/broadcast.js";
 import { createMcpServer, startStdioServer } from "./mcp-server.js";
 import { provisionWorktree } from "./provision-worktree.js";
@@ -153,6 +156,7 @@ program
     .option("--mcp-only", "Start MCP stdio only (no HTTP REST server)")
     .option("--http-port <number>", "Port for HTTP REST API", "3000")
     .option("--http-host <address>", "Host for HTTP REST API", "127.0.0.1")
+    .option("--ui", "Enable built-in web UI at /ui")
     .action(async (opts) => {
     const { db, sqlite } = openDb(opts.db);
     const entityRepo = new DrizzleEntityRepository(db);
@@ -160,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,
@@ -183,6 +189,7 @@ program
         gates: gateRepo,
         transitions: transitionLogRepo,
         eventRepo: new DrizzleEventRepository(db),
+        domainEvents: domainEventRepo,
         engine,
         withTransaction: (fn) => withTransaction(sqlite, fn),
     };
@@ -209,6 +216,9 @@ program
     const workerToken = process.env.DEFCON_WORKER_TOKEN || undefined;
     const startHttp = !opts.mcpOnly;
     const startMcp = !opts.httpOnly;
+    if (opts.mcpOnly && opts.ui) {
+        console.warn("Warning: --ui is ignored when --mcp-only is set (HTTP server is disabled)");
+    }
     try {
         validateAdminToken({ adminToken, startHttp, transport: opts.transport });
     }
@@ -241,13 +251,19 @@ program
             sqlite.close();
             process.exit(1);
         }
+        const uiSseAdapter = opts.ui ? new UiSseAdapter() : undefined;
         restHttpServer = createHttpServer({
             engine,
             mcpDeps: deps,
             adminToken,
             workerToken,
             corsOrigins: restCorsResult.origins ?? undefined,
+            enableUi: !!opts.ui,
+            uiSseAdapter,
         });
+        if (uiSseAdapter) {
+            eventEmitter.register(uiSseAdapter);
+        }
         if (adminToken) {
             const wsBroadcaster = new WebSocketBroadcaster({
                 server: restHttpServer,

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,14 @@
+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>;
+    list(entityId: string, opts?: {
+        type?: string;
+        limit?: number;
+    }): Promise<DomainEvent[]>;
+}
+export {};

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

@@ -0,0 +1,44 @@
+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 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/event.repo.d.ts

@@ -1,5 +1,5 @@
 import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
-import type { IEventRepository } from "../interfaces.js";
+import type { EventRow, IEventRepository } from "../interfaces.js";
 import type * as schema from "./schema.js";
 import { events } from "./schema.js";
 type Db = BetterSQLite3Database<typeof schema>;
@@ -8,5 +8,7 @@ export declare class DrizzleEventRepository implements IEventRepository {
     constructor(db: Db);
     emitDefinitionChanged(flowId: string | null, tool: string, payload: Record<string, unknown>): Promise<void>;
     findAll(): (typeof events.$inferSelect)[];
+    findByEntity(entityId: string, limit?: number): Promise<EventRow[]>;
+    findRecent(limit?: number): Promise<EventRow[]>;
 }
 export {};

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

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { desc, eq } from "drizzle-orm";
 import { events } from "./schema.js";
 export class DrizzleEventRepository {
     db;
@@ -21,4 +22,16 @@ export class DrizzleEventRepository {
     findAll() {
         return this.db.select().from(events).all();
     }
+    findByEntity(entityId, limit = 100) {
+        return Promise.resolve(this.db
+            .select()
+            .from(events)
+            .where(eq(events.entityId, entityId))
+            .orderBy(desc(events.emittedAt))
+            .limit(limit)
+            .all());
+    }
+    findRecent(limit = 100) {
+        return Promise.resolve(this.db.select().from(events).orderBy(desc(events.emittedAt)).limit(limit).all());
+    }
 }

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

@@ -159,4 +159,17 @@ export const events = sqliteTable("events", {
     emittedAt: integer("emitted_at").notNull(),
 }, (table) => ({
     typeEmittedIdx: index("events_type_emitted_idx").on(table.type, table.emittedAt),
+    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

@@ -338,10 +338,42 @@ export interface ITransitionLogRepository {
     /** Get full transition history for an entity, ordered by timestamp. */
     historyFor(entityId: string): Promise<TransitionLog[]>;
 }
+/** A raw row from the events table. */
+export interface EventRow {
+    id: string;
+    type: string;
+    entityId: string | null;
+    flowId: string | null;
+    payload: Record<string, unknown> | null;
+    emittedAt: number;
+}
 /** Data-access contract for emitting definition-change events. */
 export interface IEventRepository {
     /** Emit a definition change event for a tool action. */
     emitDefinitionChanged(flowId: string | null, tool: string, payload: Record<string, unknown>): Promise<void>;
+    /** Get events for a specific entity, ordered by emittedAt descending. */
+    findByEntity(entityId: string, limit?: number): Promise<EventRow[]>;
+    /** 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[]>;
 }
 /** Data-access contract for gate definitions and result recording. */
 export interface IGateRepository {