@nikelyh/offscript 0.0.0-stage → 1.1.0

package/dist/packages/persistence/migrations/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1793384398605,
+      "tag": "0000_initial_domain_storage",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1793386421172,
+      "tag": "0001_transactional_outbox",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1793402853622,
+      "tag": "0002_simulation_configuration",
+      "breakpoints": true
+    }
+  ]
+}

package/dist/packages/persistence/outbox/committer.js

@@ -0,0 +1,54 @@
+import { eq } from "drizzle-orm";
+import { parseInvestigationEvent, serializeSemanticEvent } from "../../contracts/index.js";
+import { outbox as eventOutbox } from "../schema/index.js";
+import { readInvestigation } from "../codecs/investigation.js";
+import { writeRequest, writeAssignment, writeCompletion } from "../repositories/investigation-writes.js";
+export function investigationCommitter(db) {
+    function commit(input, expected) {
+        if (expected !== undefined && (!Number.isSafeInteger(expected) || expected < 0 || expected >= Number.MAX_SAFE_INTEGER))
+            throw new Error("Invalid revision.");
+        const event = parseInvestigationEvent(input);
+        const eventJson = serializeSemanticEvent(event);
+        const revision = expected === undefined ? 0 : expected + 1;
+        return db.transaction(tx => {
+            const previous = tx.select().from(eventOutbox).where(eq(eventOutbox.eventId, event.eventId)).get();
+            if (previous)
+                return previous.eventJson === eventJson && previous.revision === revision ? "duplicate" : "event-conflict";
+            let result;
+            if (event.type === "investigation.requested" && expected === undefined)
+                result = writeRequest(tx, event.payload.investigation);
+            else if (event.type === "investigation.assigned" && expected !== undefined)
+                result = writeAssignment(tx, event.payload.investigation, expected);
+            else if (event.type === "investigation.completed" && expected !== undefined)
+                result = writeCompletion(tx, event.payload.investigation, expected);
+            else
+                throw new Error("Invalid investigation commit type.");
+            if (result !== "created" && result !== "saved")
+                return result;
+            tx.insert(eventOutbox).values({ eventId: event.eventId, eventJson, simulationId: event.simulationId,
+                investigationId: event.payload.investigation.id, revision }).run();
+            return result;
+        }, { behavior: "immediate" });
+    }
+    return {
+        async findInvestigation(id) { return db.transaction(tx => readInvestigation(tx, id)); },
+        async commitRequest(event) {
+            const result = commit(event);
+            if (result === "saved" || result === "not-found" || result === "conflict")
+                throw new Error("Invalid request commit result.");
+            return result;
+        },
+        async commitAssignment(event, revision) {
+            const result = commit(event, revision);
+            if (result === "created" || result === "already-exists")
+                throw new Error("Invalid assignment commit result.");
+            return result;
+        },
+        async commitCompletion(event, revision) {
+            const result = commit(event, revision);
+            if (result === "created" || result === "already-exists")
+                throw new Error("Invalid completion commit result.");
+            return result;
+        },
+    };
+}

package/dist/packages/persistence/outbox/store.js

@@ -0,0 +1,66 @@
+import { and, eq, gt, inArray, sql } from "drizzle-orm";
+import { randomUUID } from "node:crypto";
+import { validateClaim } from "../../application/index.js";
+import { outbox } from "../schema/index.js";
+export function outboxStore(db) {
+    function fence(id, token, now) {
+        if (!Number.isSafeInteger(now) || now < 0)
+            throw new Error("Invalid outbox time.");
+        return and(eq(outbox.eventId, id), eq(outbox.status, "leased"), eq(outbox.leaseToken, token), gt(outbox.leaseUntil, now));
+    }
+    function availability(now, at) {
+        if (!Number.isSafeInteger(at) || at < now)
+            throw new Error("Invalid retry availability.");
+    }
+    return {
+        async claim(options) {
+            validateClaim(options);
+            return db.transaction(tx => {
+                const candidates = tx.select().from(outbox).where(sql `
+          ((${outbox.status} = 'pending' and ${outbox.availableAt} <= ${options.now})
+            or (${outbox.status} = 'leased' and ${outbox.leaseUntil} <= ${options.now}))
+          and not exists (select 1 from event_outbox older
+            where older.investigation_id = ${outbox.investigationId}
+              and older.sequence < ${outbox.sequence} and older.status != 'accepted')
+        `).orderBy(outbox.sequence).limit(options.limit).all();
+                const leases = [];
+                for (const row of candidates) {
+                    if (row.attempts >= options.maxAttempts) {
+                        tx.update(outbox).set({ status: "failed", leaseToken: null, leaseUntil: null, lastError: "ATTEMPTS_EXHAUSTED" })
+                            .where(eq(outbox.sequence, row.sequence)).run();
+                        continue;
+                    }
+                    const lease = { ...row, status: "leased", attempts: row.attempts + 1,
+                        leaseToken: `${options.token}:${randomUUID()}`, leaseUntil: options.now + options.leaseMs };
+                    tx.update(outbox).set({ status: lease.status, attempts: lease.attempts,
+                        leaseToken: lease.leaseToken, leaseUntil: lease.leaseUntil }).where(eq(outbox.sequence, row.sequence)).run();
+                    leases.push(Object.freeze(lease));
+                }
+                return Object.freeze(leases);
+            }, { behavior: "immediate" });
+        },
+        async accept(id, token, now) {
+            return db.update(outbox).set({ status: "accepted", acceptedAt: now, leaseToken: null, leaseUntil: null, lastError: null })
+                .where(fence(id, token, now)).run().changes === 1;
+        },
+        async defer(id, token, now, at) {
+            availability(now, at);
+            return db.update(outbox).set({ status: "pending", availableAt: at, leaseToken: null, leaseUntil: null,
+                attempts: sql `${outbox.attempts} - 1` }).where(fence(id, token, now)).run().changes === 1;
+        },
+        async reject(id, token, now, error, retryAt) {
+            if (retryAt !== null)
+                availability(now, retryAt);
+            return db.update(outbox).set({ status: retryAt === null ? "failed" : "pending", availableAt: retryAt ?? now,
+                leaseToken: null, leaseUntil: null, lastError: error }).where(fence(id, token, now)).run().changes === 1;
+        },
+        async inspect(id) {
+            const row = db.select().from(outbox).where(eq(outbox.eventId, id)).get();
+            return row && Object.freeze(row);
+        },
+        async hasPending(id) {
+            return !!db.select({ sequence: outbox.sequence }).from(outbox)
+                .where(and(eq(outbox.simulationId, id), inArray(outbox.status, ["pending", "leased"]))).limit(1).get();
+        },
+    };
+}

package/dist/packages/persistence/repositories/configurations.js

@@ -0,0 +1,41 @@
+import { eq, sql } from "drizzle-orm";
+import { configuredSimulation } from "../../application/index.js";
+import { parseSimulationConfiguration } from "../../contracts/index.js";
+import { simulationConfigurations } from "../schema/index.js";
+import { PersistenceError } from "../errors.js";
+import { json, stored } from "../codecs/values.js";
+import { writeSimulation } from "./simulation-writes.js";
+import { deleteConfiguration } from "./delete-configuration.js";
+export function configurationRepository(db) {
+    return {
+        async deleteConfiguredSimulation(id) { return deleteConfiguration(db, id); },
+        async listConfigurations() {
+            const rows = db.select().from(simulationConfigurations).orderBy(sql `rowid desc`).limit(50).all();
+            return stored(() => Object.freeze(rows.map(row => parseSimulationConfiguration(json(row.configuration)))));
+        },
+        async createConfiguredSimulation(input, simulation) {
+            const configuration = parseSimulationConfiguration(input);
+            if (JSON.stringify(configuredSimulation(configuration)) !== JSON.stringify(simulation)) {
+                throw new PersistenceError("INVALID_WRITE", "Configuration must match a created simulation with ready users.");
+            }
+            return db.transaction(tx => {
+                const created = writeSimulation(tx, simulation);
+                if (created !== "created")
+                    return created;
+                tx.insert(simulationConfigurations).values({ simulationId: configuration.simulationId, configuration: JSON.stringify(configuration) }).run();
+                return "created";
+            }, { behavior: "immediate" });
+        },
+        async findConfiguration(id) {
+            const row = db.select().from(simulationConfigurations).where(eq(simulationConfigurations.simulationId, id)).get();
+            if (!row)
+                return undefined;
+            return stored(() => {
+                const configuration = parseSimulationConfiguration(json(row.configuration));
+                if (configuration.simulationId !== id)
+                    throw new PersistenceError("INVALID_STORED_DATA", "Configuration identity does not match its row.");
+                return configuration;
+            });
+        },
+    };
+}

package/dist/packages/persistence/repositories/delete-configuration.js

@@ -0,0 +1,20 @@
+import { eq } from "drizzle-orm";
+import { agents, simulations, simulationConfigurations, observations, investigations, outbox } from "../schema/index.js";
+export function deleteConfiguration(db, id) {
+    return db.transaction(tx => {
+        if (!tx.select({ id: simulationConfigurations.simulationId }).from(simulationConfigurations).where(eq(simulationConfigurations.simulationId, id)).get())
+            return "not-found";
+        const simulation = tx.select().from(simulations).where(eq(simulations.id, id)).get();
+        const members = tx.select({ status: agents.status }).from(agents).where(eq(agents.simulationId, id)).all();
+        if (simulation?.status !== "created" || members.some(member => member.status !== "ready"))
+            return "not-allowed";
+        if (tx.select({ id: observations.id }).from(observations).where(eq(observations.simulationId, id)).limit(1).get() ||
+            tx.select({ id: investigations.id }).from(investigations).where(eq(investigations.simulationId, id)).limit(1).get() ||
+            tx.select({ id: outbox.eventId }).from(outbox).where(eq(outbox.simulationId, id)).limit(1).get())
+            return "not-allowed";
+        tx.delete(simulationConfigurations).where(eq(simulationConfigurations.simulationId, id)).run();
+        tx.delete(agents).where(eq(agents.simulationId, id)).run();
+        tx.delete(simulations).where(eq(simulations.id, id)).run();
+        return "deleted";
+    }, { behavior: "immediate" });
+}

package/dist/packages/persistence/repositories/investigation-writes.js

@@ -0,0 +1,72 @@
+import { and, eq } from "drizzle-orm";
+import { assignInvestigation, completeInvestigation } from "../../domain/index.js";
+import { parseInvestigationSummary } from "../../contracts/index.js";
+import { investigations, investigationAgents, investigationObservations } from "../schema/index.js";
+import { readInvestigation } from "../codecs/investigation.js";
+import { PersistenceError } from "../errors.js";
+export function writeRequest(tx, input) {
+    const value = parseInvestigationSummary(input);
+    if (value.lifecycle.status !== "requested")
+        throw new PersistenceError("INVALID_WRITE", "Expected requested investigation.");
+    const result = tx.insert(investigations).values({
+        id: value.id, simulationId: value.simulationId, requestedBy: value.requestedBy,
+        hypothesis: value.hypothesis, requestedAt: value.requestedAt, status: "requested", revision: 0,
+    }).onConflictDoNothing({ target: investigations.id }).run();
+    if (!result.changes)
+        return "already-exists";
+    tx.insert(investigationObservations).values(value.observationIds.map((id, position) => ({
+        investigationId: value.id, simulationId: value.simulationId, observationId: id, position,
+    }))).run();
+    return "created";
+}
+export function writeAssignment(tx, input, expectedRevision) {
+    if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0 || expectedRevision === Number.MAX_SAFE_INTEGER)
+        throw new PersistenceError("INVALID_WRITE", "Invalid revision.");
+    const value = parseInvestigationSummary(input);
+    if (value.lifecycle.status !== "assigned")
+        throw new PersistenceError("INVALID_WRITE", "Expected assigned investigation.");
+    const lifecycle = value.lifecycle;
+    const current = readInvestigation(tx, value.id);
+    if (!current)
+        return "not-found";
+    if (current.revision !== expectedRevision)
+        return "conflict";
+    const existing = current.investigation.lifecycle.status === "requested" ? [] : current.investigation.lifecycle.agentIds;
+    const expected = assignInvestigation(current.investigation, lifecycle.agentIds.filter((id) => !existing.includes(id)), lifecycle.assignedAt);
+    if (JSON.stringify(parseInvestigationSummary(expected)) !== JSON.stringify(value)) {
+        throw new PersistenceError("INVALID_WRITE", "Assignment must preserve the investigation and existing collaborators.");
+    }
+    const result = tx.update(investigations).set({ status: "assigned", assignedAt: lifecycle.assignedAt, revision: expectedRevision + 1 })
+        .where(and(eq(investigations.id, value.id), eq(investigations.revision, expectedRevision))).run();
+    if (!result.changes)
+        return "conflict";
+    tx.delete(investigationAgents).where(eq(investigationAgents.investigationId, value.id)).run();
+    tx.insert(investigationAgents).values(lifecycle.agentIds.map((id, position) => ({
+        investigationId: value.id, simulationId: value.simulationId, agentId: id, position,
+    }))).run();
+    return "saved";
+}
+export function writeCompletion(tx, input, expectedRevision) {
+    if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0 || expectedRevision === Number.MAX_SAFE_INTEGER)
+        throw new PersistenceError("INVALID_WRITE", "Invalid revision.");
+    const value = parseInvestigationSummary(input);
+    if (value.lifecycle.status !== "completed")
+        throw new PersistenceError("INVALID_WRITE", "Expected completed investigation.");
+    const lifecycle = value.lifecycle;
+    const current = readInvestigation(tx, value.id);
+    if (!current)
+        return "not-found";
+    if (current.revision !== expectedRevision)
+        return "conflict";
+    const expected = completeInvestigation(current.investigation, lifecycle.result, lifecycle.completedBy, lifecycle.completedAt);
+    if (JSON.stringify(parseInvestigationSummary(expected)) !== JSON.stringify(value)) {
+        throw new PersistenceError("INVALID_WRITE", "Completion must match domain transition from assigned state.");
+    }
+    const result = tx.update(investigations).set({
+        status: "completed", completedAt: lifecycle.completedAt, completedBy: lifecycle.completedBy,
+        result: JSON.stringify(lifecycle.result), revision: expectedRevision + 1,
+    }).where(and(eq(investigations.id, value.id), eq(investigations.revision, expectedRevision))).run();
+    if (!result.changes)
+        return "conflict";
+    return "saved";
+}

package/dist/packages/persistence/repositories/investigations.js

@@ -0,0 +1,27 @@
+import { asc, eq } from "drizzle-orm";
+import { readInvestigation } from "../codecs/investigation.js";
+import { writeRequest, writeAssignment } from "./investigation-writes.js";
+import { investigations } from "../schema/index.js";
+import { PersistenceError } from "../errors.js";
+export function investigationRepository(db) {
+    return {
+        async createInvestigation(input) { return db.transaction(tx => writeRequest(tx, input), { behavior: "immediate" }); },
+        async findInvestigation(id) { return db.transaction(tx => readInvestigation(tx, id)); },
+        async saveAssignment(input, revision) { return db.transaction(tx => writeAssignment(tx, input, revision), { behavior: "immediate" }); },
+        async listInvestigations(simulationId) {
+            return db.transaction(tx => {
+                const rows = tx.select({ id: investigations.id })
+                    .from(investigations)
+                    .where(eq(investigations.simulationId, simulationId))
+                    .orderBy(asc(investigations.requestedAt))
+                    .all();
+                return Object.freeze(rows.map(row => {
+                    const loaded = readInvestigation(tx, row.id);
+                    if (!loaded)
+                        throw new PersistenceError("INVALID_STORED_DATA", "Investigation missing during list.");
+                    return loaded.investigation;
+                }));
+            });
+        },
+    };
+}

package/dist/packages/persistence/repositories/observations.js

@@ -0,0 +1,36 @@
+import { asc, eq } from "drizzle-orm";
+import { parseObservationSummary } from "../../contracts/index.js";
+import { observations } from "../schema/index.js";
+import { json, stored } from "../codecs/values.js";
+export function observationRepository(db) {
+    return {
+        async createObservation(input) {
+            const observation = parseObservationSummary(input);
+            const result = db.insert(observations).values({
+                id: observation.id, simulationId: observation.simulationId, agentId: observation.agentId,
+                observedAt: observation.observedAt, description: observation.description, location: observation.context.location,
+                evidenceIds: JSON.stringify(observation.evidenceIds),
+            }).onConflictDoNothing({ target: observations.id }).run();
+            return result.changes ? "created" : "already-exists";
+        },
+        async findObservation(id) {
+            const row = db.select().from(observations).where(eq(observations.id, id)).get();
+            if (!row)
+                return undefined;
+            return stored(() => parseObservationSummary({
+                id: row.id, simulationId: row.simulationId, agentId: row.agentId, observedAt: row.observedAt,
+                description: row.description, context: { location: row.location }, evidenceIds: json(row.evidenceIds),
+            }));
+        },
+        async listObservations(simulationId) {
+            const rows = db.select().from(observations)
+                .where(eq(observations.simulationId, simulationId))
+                .orderBy(asc(observations.observedAt))
+                .all();
+            return Object.freeze(rows.map(row => stored(() => parseObservationSummary({
+                id: row.id, simulationId: row.simulationId, agentId: row.agentId, observedAt: row.observedAt,
+                description: row.description, context: { location: row.location }, evidenceIds: json(row.evidenceIds),
+            }))));
+        },
+    };
+}

package/dist/packages/persistence/repositories/simulation-writes.js

@@ -0,0 +1,39 @@
+import { and, eq } from "drizzle-orm";
+import { agents, simulations } from "../schema/index.js";
+import { simulationRows } from "../codecs/simulation.js";
+export function writeSimulation(tx, simulation) {
+    const { row, members } = simulationRows(simulation);
+    const created = tx.insert(simulations).values(row).onConflictDoNothing({ target: simulations.id }).run();
+    if (!created.changes)
+        return "already-exists";
+    if (members.length)
+        tx.insert(agents).values(members).run();
+    return "created";
+}
+export function updateSimulationAggregate(tx, simulation, expected) {
+    const current = tx.select().from(simulations).where(eq(simulations.id, simulation.id)).get();
+    if (!current)
+        return "not-found";
+    if (current.status !== expected.status)
+        return "conflict";
+    const members = tx.select().from(agents).where(eq(agents.simulationId, simulation.id)).all();
+    if (expected.agentStatuses) {
+        for (const [agentId, expectedStatus] of expected.agentStatuses) {
+            const member = members.find((entry) => entry.id === agentId);
+            if (!member || member.status !== expectedStatus)
+                return "conflict";
+        }
+    }
+    const { row, members: nextMembers } = simulationRows(simulation);
+    tx.update(simulations)
+        .set({ status: row.status, reason: row.reason })
+        .where(eq(simulations.id, simulation.id))
+        .run();
+    for (const member of nextMembers) {
+        tx.update(agents)
+            .set({ status: member.status, reason: member.reason })
+            .where(and(eq(agents.simulationId, simulation.id), eq(agents.id, member.id)))
+            .run();
+    }
+    return "updated";
+}

package/dist/packages/persistence/repositories/simulations.js

@@ -0,0 +1,23 @@
+import { asc, eq } from "drizzle-orm";
+import { agents, simulations } from "../schema/index.js";
+import { restoreSimulation } from "../codecs/simulation.js";
+import { writeSimulation, updateSimulationAggregate } from "./simulation-writes.js";
+export function simulationRepository(db) {
+    return {
+        async createSimulation(simulation) {
+            return db.transaction(tx => writeSimulation(tx, simulation), { behavior: "immediate" });
+        },
+        async updateSimulationAggregate(simulation, expected) {
+            return db.transaction(tx => updateSimulationAggregate(tx, simulation, expected), { behavior: "immediate" });
+        },
+        async findSimulation(id) {
+            return db.transaction((tx) => {
+                const row = tx.select().from(simulations).where(eq(simulations.id, id)).get();
+                if (!row)
+                    return undefined;
+                const members = tx.select().from(agents).where(eq(agents.simulationId, id)).orderBy(asc(agents.position)).all();
+                return restoreSimulation(row, members);
+            });
+        },
+    };
+}

package/dist/packages/persistence/schema/configurations.js

@@ -0,0 +1,10 @@
+import { sql } from "drizzle-orm";
+import { check, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { simulations } from "./simulations.js";
+export const simulationConfigurations = sqliteTable("simulation_configurations", {
+    simulationId: text("simulation_id").primaryKey().references(() => simulations.id),
+    configuration: text("configuration").notNull(),
+}, table => [
+    check("configuration_json", sql `json_valid(${table.configuration}) and json_type(${table.configuration}) = 'object'`),
+    check("configuration_identity", sql `json_type(${table.configuration}, '$.simulationId') is 'text' and json_extract(${table.configuration}, '$.simulationId') = ${table.simulationId}`),
+]);

package/dist/packages/persistence/schema/index.js

@@ -0,0 +1,5 @@
+export { simulations, agents } from "./simulations.js";
+export { observations } from "./observations.js";
+export { investigations, investigationObservations, investigationAgents } from "./investigations.js";
+export { outbox } from "./outbox.js";
+export { simulationConfigurations } from "./configurations.js";

package/dist/packages/persistence/schema/investigations.js

@@ -0,0 +1,53 @@
+import { sql } from "drizzle-orm";
+import { check, foreignKey, index, integer, primaryKey, sqliteTable, text, unique } from "drizzle-orm/sqlite-core";
+import { agents, simulations } from "./simulations.js";
+import { observations } from "./observations.js";
+export const investigations = sqliteTable("investigations", {
+    id: text("id").primaryKey(),
+    simulationId: text("simulation_id").notNull().references(() => simulations.id),
+    requestedBy: text("requested_by").notNull(),
+    hypothesis: text("hypothesis").notNull(),
+    requestedAt: text("requested_at").notNull(),
+    status: text("status").notNull(),
+    assignedAt: text("assigned_at"),
+    completedAt: text("completed_at"),
+    completedBy: text("completed_by"),
+    result: text("result"),
+    revision: integer("revision").notNull().default(0),
+}, (table) => [
+    unique("investigation_scope").on(table.id, table.simulationId),
+    foreignKey({ columns: [table.simulationId, table.requestedBy], foreignColumns: [agents.simulationId, agents.id] }),
+    foreignKey({ columns: [table.simulationId, table.completedBy], foreignColumns: [agents.simulationId, agents.id] }),
+    index("investigation_simulation_status").on(table.simulationId, table.status, table.requestedAt, table.id),
+    check("investigation_revision", sql `${table.revision} >= 0 and ${table.revision} <= 9007199254740991`),
+    check("investigation_state", sql `(
+    (${table.status} = 'requested' and ${table.assignedAt} is null and ${table.completedAt} is null and ${table.completedBy} is null and ${table.result} is null)
+    or (${table.status} = 'assigned' and ${table.assignedAt} is not null and ${table.completedAt} is null and ${table.completedBy} is null and ${table.result} is null)
+    or (${table.status} = 'completed' and ${table.assignedAt} is not null and ${table.completedAt} is not null and ${table.completedBy} is not null and ${table.result} is not null)
+  )`),
+    check("investigation_result_json", sql `${table.result} is null or json_valid(${table.result})`),
+]);
+export const investigationObservations = sqliteTable("investigation_observations", {
+    investigationId: text("investigation_id").notNull(),
+    simulationId: text("simulation_id").notNull(),
+    observationId: text("observation_id").notNull(),
+    position: integer("position").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.investigationId, table.observationId] }),
+    unique("investigation_observation_position").on(table.investigationId, table.position),
+    foreignKey({ columns: [table.investigationId, table.simulationId], foreignColumns: [investigations.id, investigations.simulationId] }),
+    foreignKey({ columns: [table.observationId, table.simulationId], foreignColumns: [observations.id, observations.simulationId] }),
+    check("investigation_observation_nonnegative_position", sql `${table.position} >= 0`),
+]);
+export const investigationAgents = sqliteTable("investigation_agents", {
+    investigationId: text("investigation_id").notNull(),
+    simulationId: text("simulation_id").notNull(),
+    agentId: text("agent_id").notNull(),
+    position: integer("position").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.investigationId, table.agentId] }),
+    unique("investigation_agent_position").on(table.investigationId, table.position),
+    foreignKey({ columns: [table.investigationId, table.simulationId], foreignColumns: [investigations.id, investigations.simulationId] }),
+    foreignKey({ columns: [table.simulationId, table.agentId], foreignColumns: [agents.simulationId, agents.id] }),
+    check("investigation_agent_nonnegative_position", sql `${table.position} >= 0`),
+]);

package/dist/packages/persistence/schema/observations.js

@@ -0,0 +1,17 @@
+import { sql } from "drizzle-orm";
+import { check, foreignKey, index, sqliteTable, text, unique } from "drizzle-orm/sqlite-core";
+import { agents, simulations } from "./simulations.js";
+export const observations = sqliteTable("observations", {
+    id: text("id").primaryKey(),
+    simulationId: text("simulation_id").notNull().references(() => simulations.id),
+    agentId: text("agent_id").notNull(),
+    observedAt: text("observed_at").notNull(),
+    description: text("description").notNull(),
+    location: text("location").notNull(),
+    evidenceIds: text("evidence_ids").notNull(),
+}, (table) => [
+    unique("observation_scope").on(table.id, table.simulationId),
+    foreignKey({ columns: [table.simulationId, table.agentId], foreignColumns: [agents.simulationId, agents.id] }),
+    index("observation_simulation_time").on(table.simulationId, table.observedAt, table.id),
+    check("observation_evidence_json", sql `json_valid(${table.evidenceIds})`),
+]);

package/dist/packages/persistence/schema/outbox.js

@@ -0,0 +1,26 @@
+import { sql } from "drizzle-orm";
+import { check, foreignKey, index, integer, sqliteTable, text, unique } from "drizzle-orm/sqlite-core";
+import { investigations } from "./investigations.js";
+export const outbox = sqliteTable("event_outbox", {
+    sequence: integer("sequence").primaryKey({ autoIncrement: true }),
+    eventId: text("event_id").notNull().unique(),
+    simulationId: text("simulation_id").notNull(),
+    investigationId: text("investigation_id").notNull(),
+    revision: integer("revision").notNull(),
+    eventJson: text("event_json").notNull(),
+    status: text("status", { enum: ["pending", "leased", "accepted", "failed"] }).notNull().default("pending"),
+    attempts: integer("attempts").notNull().default(0),
+    availableAt: integer("available_at").notNull().default(0),
+    leaseToken: text("lease_token"), leaseUntil: integer("lease_until"), acceptedAt: integer("accepted_at"),
+    lastError: text("last_error", { enum: ["PUBLISH_REJECTED", "INVALID_EVENT", "ATTEMPTS_EXHAUSTED"] }),
+}, (table) => [
+    foreignKey({ columns: [table.investigationId, table.simulationId], foreignColumns: [investigations.id, investigations.simulationId] }),
+    unique("outbox_investigation_revision").on(table.investigationId, table.revision),
+    index("outbox_ready").on(table.status, table.availableAt, table.sequence),
+    index("outbox_aggregate_order").on(table.investigationId, table.sequence, table.status),
+    check("outbox_json", sql `json_valid(${table.eventJson})`),
+    check("outbox_numbers", sql `${table.revision} >= 0 and ${table.attempts} >= 0 and ${table.availableAt} >= 0`),
+    check("outbox_status", sql `${table.status} in ('pending','leased','accepted','failed')`),
+    check("outbox_lease", sql `(${table.status} = 'leased' and ${table.leaseToken} is not null and ${table.leaseUntil} is not null) or (${table.status} != 'leased' and ${table.leaseToken} is null and ${table.leaseUntil} is null)`),
+    check("outbox_acceptance", sql `(${table.status} = 'accepted' and ${table.acceptedAt} is not null) or (${table.status} != 'accepted' and ${table.acceptedAt} is null)`),
+]);

package/dist/packages/persistence/schema/simulations.js

@@ -0,0 +1,29 @@
+import { sql } from "drizzle-orm";
+import { check, integer, primaryKey, sqliteTable, text, unique } from "drizzle-orm/sqlite-core";
+export const simulations = sqliteTable("simulations", {
+    id: text("id").primaryKey(),
+    environment: text("environment").notNull(),
+    deployment: text("deployment").notNull(),
+    status: text("status").notNull(),
+    reason: text("reason"),
+}, (table) => [
+    check("simulation_environment", sql `${table.environment} = 'web'`),
+    check("simulation_deployment", sql `${table.deployment} in ('local','development','test','staging','production')`),
+    check("simulation_status", sql `${table.status} in ('created','running','completed','failed','cancelled')`),
+    check("simulation_reason", sql `(${table.status} = 'failed' and ${table.reason} is not null and length(trim(${table.reason})) > 0) or (${table.status} != 'failed' and ${table.reason} is null)`),
+]);
+export const agents = sqliteTable("agents", {
+    simulationId: text("simulation_id").notNull().references(() => simulations.id),
+    id: text("id").notNull(),
+    position: integer("position").notNull(),
+    profile: text("profile").notNull(),
+    status: text("status").notNull(),
+    reason: text("reason"),
+}, (table) => [
+    primaryKey({ columns: [table.simulationId, table.id] }),
+    unique("agent_position").on(table.simulationId, table.position),
+    check("agent_nonnegative_position", sql `${table.position} >= 0`),
+    check("agent_profile_json", sql `json_valid(${table.profile})`),
+    check("agent_status", sql `${table.status} in ('ready','running','completed','failed','cancelled')`),
+    check("agent_reason", sql `(${table.status} = 'failed' and ${table.reason} is not null and length(trim(${table.reason})) > 0) or (${table.status} != 'failed' and ${table.reason} is null)`),
+]);

package/dist/packages/projects/index.js

@@ -0,0 +1,2 @@
+export { inspectProject, ProjectInspectionError } from "./inspect.js";
+export { createTargetProbe } from "./target-probe.js";

package/dist/packages/projects/inspect.js

@@ -0,0 +1,45 @@
+import { open, realpath, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { suggestTarget } from "./suggest-target.js";
+export class ProjectInspectionError extends Error {
+    constructor(message, options) { super(message, options); this.name = "ProjectInspectionError"; }
+}
+export async function inspectProject(projectRoot) {
+    try {
+        if (!projectRoot.trim())
+            throw new ProjectInspectionError("An explicit project path is required.");
+        const rootPath = await realpath(resolve(projectRoot));
+        if (!(await stat(rootPath)).isDirectory())
+            throw new ProjectInspectionError("The project path must be a directory.");
+        const fallback = Object.freeze({ rootPath, suggestedName: basename(rootPath) || "Project", nameSource: "directory" });
+        let file;
+        try {
+            file = await open(join(rootPath, "package.json"), "r");
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return fallback;
+            throw error;
+        }
+        try {
+            const info = await file.stat();
+            if (!info.isFile() || info.size > 1_048_576)
+                throw new ProjectInspectionError("Project manifest must be a regular file of at most 1 MiB.");
+            const parsed = JSON.parse(await file.readFile({ encoding: "utf8" }));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new ProjectInspectionError("Project manifest must contain a JSON object.");
+            const name = "name" in parsed ? parsed.name : undefined;
+            const targetSuggestion = suggestTarget(parsed);
+            return Object.freeze({ ...(typeof name === "string" && name.trim() ? { rootPath, suggestedName: name.trim(), nameSource: "package" } : fallback),
+                ...(targetSuggestion ? { targetSuggestion } : {}) });
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (cause) {
+        if (cause instanceof ProjectInspectionError)
+            throw cause;
+        throw new ProjectInspectionError("Could not read the selected project.", { cause });
+    }
+}