@nikelyh/offscript 0.0.0-stage → 1.0.0

package/dist/packages/contracts/investigation-events.js

@@ -0,0 +1,43 @@
+import { ContractValidationError } from "./errors.js";
+import { parseEventEnvelope } from "./event-envelope.js";
+import { parseInvestigationSummary } from "./investigation-summary.js";
+import { record } from "./validation.js";
+export function parseInvestigationEvent(value) {
+    const { input, base } = parseEventEnvelope(value);
+    const payload = record(input.payload, "event.payload", ["investigation"]);
+    const investigation = parseInvestigationSummary(payload.investigation);
+    if (investigation.simulationId !== base.simulationId) {
+        throw new ContractValidationError("event.payload.investigation.simulationId", "Simulation ID does not match the envelope.");
+    }
+    const state = investigation.lifecycle;
+    switch (input.type) {
+        case "investigation.requested":
+            if (state.status !== "requested")
+                break;
+            if (base.origin.kind === "agent" && base.origin.agentId !== investigation.requestedBy) {
+                throw new ContractValidationError("event.origin.agentId", "Origin must match the requesting agent.");
+            }
+            return Object.freeze({ ...base, type: input.type, payload: Object.freeze({
+                    investigation: Object.freeze({ ...investigation, lifecycle: state }),
+                }) });
+        case "investigation.assigned":
+            if (state.status !== "assigned")
+                break;
+            // The assigning origin need not be an assignee. Authorization is external.
+            return Object.freeze({ ...base, type: input.type, payload: Object.freeze({
+                    investigation: Object.freeze({ ...investigation, lifecycle: state }),
+                }) });
+        case "investigation.completed":
+            if (state.status !== "completed")
+                break;
+            if (base.origin.kind === "agent" && base.origin.agentId !== state.completedBy) {
+                throw new ContractValidationError("event.origin.agentId", "Origin must match the result author.");
+            }
+            return Object.freeze({ ...base, type: input.type, payload: Object.freeze({
+                    investigation: Object.freeze({ ...investigation, lifecycle: state }),
+                }) });
+        default:
+            throw new ContractValidationError("event.type", "Unknown investigation event type.");
+    }
+    throw new ContractValidationError("event.payload.investigation.lifecycle.status", "Lifecycle does not match event type.");
+}

package/dist/packages/contracts/investigation-summary.js

@@ -0,0 +1,60 @@
+import { createInvestigationResult, evidenceId, investigationId, observationId } from "../domain/index.js";
+import { ContractValidationError } from "./errors.js";
+import { oneOf, readAgentId, readSimulationId, record, text, timestamp } from "./validation.js";
+function references(value, path, read, required) {
+    if (!Array.isArray(value))
+        throw new ContractValidationError(path, "Expected an array.");
+    const values = Array.from(value, (entry, index) => read(text(entry, `${path}[${index}]`)));
+    if (new Set(values).size !== values.length || (required && values.length === 0)) {
+        throw new ContractValidationError(path, "References must be unique and the required list must not be empty.");
+    }
+    return Object.freeze(values);
+}
+export function parseInvestigationResult(value) {
+    const path = "investigation.lifecycle.result";
+    const input = record(value, path, ["outcome", "explanation", "evidenceIds"]);
+    const outcome = oneOf(input.outcome, ["supported", "contradicted", "inconclusive"], `${path}.outcome`);
+    return createInvestigationResult({
+        outcome, explanation: text(input.explanation, `${path}.explanation`),
+        evidenceIds: references(input.evidenceIds, `${path}.evidenceIds`, evidenceId, outcome !== "inconclusive"),
+    });
+}
+function lifecycle(value, requestedAt) {
+    const path = "investigation.lifecycle";
+    const shape = record(value, path, ["status", "agentIds", "assignedAt", "completedAt", "completedBy", "result"]);
+    const status = oneOf(shape.status, ["requested", "assigned", "completed"], `${path}.status`);
+    if (status === "requested") {
+        record(value, path, ["status"]);
+        return Object.freeze({ status });
+    }
+    if (status === "assigned")
+        record(value, path, ["status", "agentIds", "assignedAt"]);
+    const agentIds = references(shape.agentIds, `${path}.agentIds`, (id) => readAgentId(id, `${path}.agentIds`), true);
+    const assignedAt = timestamp(shape.assignedAt, `${path}.assignedAt`);
+    if (assignedAt < requestedAt)
+        throw new ContractValidationError(`${path}.assignedAt`, "Assignment precedes request.");
+    if (status === "assigned")
+        return Object.freeze({ status, agentIds, assignedAt });
+    const completedBy = readAgentId(shape.completedBy, `${path}.completedBy`);
+    const completedAt = timestamp(shape.completedAt, `${path}.completedAt`);
+    if (!agentIds.includes(completedBy)) {
+        throw new ContractValidationError(`${path}.completedBy`, "Result author must be an assigned agent.");
+    }
+    if (completedAt < assignedAt)
+        throw new ContractValidationError(`${path}.completedAt`, "Completion precedes assignment.");
+    return Object.freeze({ status, agentIds, assignedAt, completedBy, completedAt, result: parseInvestigationResult(shape.result) });
+}
+export function parseInvestigationSummary(value) {
+    const input = record(value, "investigation", [
+        "id", "simulationId", "requestedBy", "hypothesis", "requestedAt", "observationIds", "lifecycle",
+    ]);
+    const requestedAt = timestamp(input.requestedAt, "investigation.requestedAt");
+    return Object.freeze({
+        id: investigationId(text(input.id, "investigation.id")),
+        simulationId: readSimulationId(input.simulationId, "investigation.simulationId"),
+        requestedBy: readAgentId(input.requestedBy, "investigation.requestedBy"),
+        hypothesis: text(input.hypothesis, "investigation.hypothesis"), requestedAt,
+        observationIds: references(input.observationIds, "investigation.observationIds", observationId, true),
+        lifecycle: lifecycle(input.lifecycle, requestedAt),
+    });
+}

package/dist/packages/contracts/mappers.js

@@ -0,0 +1,17 @@
+import { parseAgentSummary, parseSimulationSummary } from "./summaries.js";
+export function toAgentSummary(simulationId, agent) {
+    return parseAgentSummary({
+        id: agent.id,
+        simulationId,
+        name: agent.profile.name,
+        lifecycle: agent.lifecycle,
+    });
+}
+export function toSimulationSummary(simulation) {
+    return parseSimulationSummary({
+        id: simulation.id,
+        environment: simulation.environment,
+        lifecycle: simulation.lifecycle,
+        agentIds: simulation.agents.map((agent) => agent.id),
+    });
+}

package/dist/packages/contracts/observation-summary.js

@@ -0,0 +1,25 @@
+import { createObservation, evidenceId, observationId } from "../domain/index.js";
+import { ContractValidationError } from "./errors.js";
+import { readAgentId, readSimulationId, record, text, timestamp } from "./validation.js";
+export function parseObservationSummary(value) {
+    const input = record(value, "observation", [
+        "id", "simulationId", "agentId", "observedAt", "description", "context", "evidenceIds",
+    ]);
+    const context = record(input.context, "observation.context", ["location"]);
+    if (!Array.isArray(input.evidenceIds)) {
+        throw new ContractValidationError("observation.evidenceIds", "Expected an array.");
+    }
+    const evidenceIds = Array.from(input.evidenceIds, (id, index) => evidenceId(text(id, `observation.evidenceIds[${index}]`)));
+    if (new Set(evidenceIds).size !== evidenceIds.length) {
+        throw new ContractValidationError("observation.evidenceIds", "Evidence references must be unique.");
+    }
+    return createObservation({
+        id: observationId(text(input.id, "observation.id")),
+        simulationId: readSimulationId(input.simulationId, "observation.simulationId"),
+        agentId: readAgentId(input.agentId, "observation.agentId"),
+        observedAt: timestamp(input.observedAt, "observation.observedAt"),
+        description: text(input.description, "observation.description"),
+        context: { location: text(context.location, "observation.context.location") },
+        evidenceIds,
+    });
+}

package/dist/packages/contracts/semantic-events.js

@@ -0,0 +1,41 @@
+import { ContractValidationError } from "./errors.js";
+import { parseEventEnvelope } from "./event-envelope.js";
+import { parseLifecycleEvent } from "./event-validation.js";
+import { parseObservationSummary } from "./observation-summary.js";
+import { record } from "./validation.js";
+import { parseInvestigationEvent } from "./investigation-events.js";
+export function parseSemanticEvent(value) {
+    const { input, base } = parseEventEnvelope(value);
+    if (input.type === "investigation.requested" || input.type === "investigation.assigned" || input.type === "investigation.completed") {
+        return parseInvestigationEvent(value);
+    }
+    if (input.type !== "observation.created")
+        return parseLifecycleEvent(value);
+    const payload = record(input.payload, "event.payload", ["observation"]);
+    const observation = parseObservationSummary(payload.observation);
+    if (observation.simulationId !== base.simulationId) {
+        throw new ContractValidationError("event.payload.observation.simulationId", "Simulation ID does not match the envelope.");
+    }
+    // A system may record an agent's observation. An agent-originated event must
+    // attribute it to that same agent; this checks consistency, not authenticity.
+    if (base.origin.kind === "agent" && base.origin.agentId !== observation.agentId) {
+        throw new ContractValidationError("event.payload.observation.agentId", "Author does not match the originating agent.");
+    }
+    return Object.freeze({ ...base, type: "observation.created", payload: Object.freeze({ observation }) });
+}
+export function createSemanticEvent(input) {
+    return parseSemanticEvent(input);
+}
+export function serializeSemanticEvent(event) {
+    return JSON.stringify(parseSemanticEvent(event));
+}
+export function deserializeSemanticEvent(json) {
+    let input;
+    try {
+        input = JSON.parse(json);
+    }
+    catch {
+        throw new ContractValidationError("event", "Invalid JSON.");
+    }
+    return parseSemanticEvent(input);
+}

package/dist/packages/contracts/serialization.js

@@ -0,0 +1,18 @@
+import { ContractValidationError } from "./errors.js";
+import { parseLifecycleEvent } from "./event-validation.js";
+export function createLifecycleEvent(input) {
+    return parseLifecycleEvent(input);
+}
+export function serializeLifecycleEvent(event) {
+    return JSON.stringify(parseLifecycleEvent(event));
+}
+export function deserializeLifecycleEvent(json) {
+    let input;
+    try {
+        input = JSON.parse(json);
+    }
+    catch {
+        throw new ContractValidationError("event", "Invalid JSON.");
+    }
+    return parseLifecycleEvent(input);
+}

package/dist/packages/contracts/simulation-configuration.js

@@ -0,0 +1,17 @@
+import { parseExecutionLimits, parseSimulationSetup } from "./simulation-setup.js";
+import { oneOf, readSimulationId, record, text } from "./validation.js";
+import { parseTargetSuggestion } from "./target-connection.js";
+export function parseProjectDescriptor(value) {
+    const input = record(value, "project", ["rootPath", "suggestedName", "nameSource", "targetSuggestion"]);
+    return Object.freeze({ rootPath: text(input.rootPath, "project.rootPath"), suggestedName: text(input.suggestedName, "project.suggestedName"),
+        nameSource: oneOf(input.nameSource, ["package", "directory"], "project.nameSource"),
+        ...(input.targetSuggestion === undefined ? {} : { targetSuggestion: parseTargetSuggestion(input.targetSuggestion) }) });
+}
+export function parseSimulationConfiguration(value) {
+    const input = record(value, "configuration", ["simulationId", "projectRoot", "name", "targetUrl", "environment", "goal", "userProfileIds", "limits"]);
+    const setup = parseSimulationSetup({ name: text(input.name, "configuration.name"),
+        targetUrl: input.targetUrl, environment: input.environment, goal: input.goal,
+        userProfileIds: input.userProfileIds, limits: parseExecutionLimits(input.limits) });
+    return Object.freeze({ ...setup, simulationId: readSimulationId(input.simulationId, "configuration.simulationId"),
+        projectRoot: text(input.projectRoot, "configuration.projectRoot"), name: text(setup.name, "configuration.name") });
+}

package/dist/packages/contracts/simulation-execution.js

@@ -0,0 +1,62 @@
+import { simulationId } from "../domain/index.js";
+import { ContractValidationError } from "./errors.js";
+import { oneOf, record, text } from "./validation.js";
+export const simulationExecutionModes = ["controlled-demo", "browser-exploration"];
+export const simulationExecutionPhases = [
+    "idle",
+    "starting",
+    "running",
+    "stopping",
+    "completed",
+    "failed",
+    "cancelled",
+    "interrupted",
+];
+export function parseStartSimulationRequest(value) {
+    const input = record(value, "startRequest", ["mode"]);
+    const mode = oneOf(input.mode, simulationExecutionModes, "startRequest.mode");
+    return Object.freeze({ mode });
+}
+export function parseSimulationExecutionStatus(value) {
+    const input = record(value, "executionStatus", [
+        "simulationId", "phase", "mode", "turnsCount", "activeAgents", "failureReason", "startedAt", "stoppedAt", "recentActivity",
+    ]);
+    const id = simulationId(text(input.simulationId, "executionStatus.simulationId"));
+    const phase = oneOf(input.phase, simulationExecutionPhases, "executionStatus.phase");
+    const mode = input.mode !== undefined ? oneOf(input.mode, simulationExecutionModes, "executionStatus.mode") : undefined;
+    if (typeof input.turnsCount !== "number" || !Number.isSafeInteger(input.turnsCount) || input.turnsCount < 0) {
+        throw new ContractValidationError("executionStatus.turnsCount", "Expected a non-negative integer.");
+    }
+    if (!Array.isArray(input.activeAgents) || input.activeAgents.some((item) => typeof item !== "string")) {
+        throw new ContractValidationError("executionStatus.activeAgents", "Expected an array of agent identifiers.");
+    }
+    const failureReason = input.failureReason !== undefined ? text(input.failureReason, "executionStatus.failureReason") : undefined;
+    const startedAt = input.startedAt !== undefined ? text(input.startedAt, "executionStatus.startedAt") : undefined;
+    const stoppedAt = input.stoppedAt !== undefined ? text(input.stoppedAt, "executionStatus.stoppedAt") : undefined;
+    let recentActivity;
+    if (input.recentActivity !== undefined) {
+        if (!Array.isArray(input.recentActivity)) {
+            throw new ContractValidationError("executionStatus.recentActivity", "Expected an array.");
+        }
+        recentActivity = Object.freeze(input.recentActivity.map((item, i) => {
+            const act = record(item, `executionStatus.recentActivity[${i}]`, ["agentId", "action", "location", "timestamp"]);
+            return Object.freeze({
+                agentId: text(act.agentId, `executionStatus.recentActivity[${i}].agentId`),
+                action: text(act.action, `executionStatus.recentActivity[${i}].action`),
+                timestamp: text(act.timestamp, `executionStatus.recentActivity[${i}].timestamp`),
+                ...(act.location !== undefined ? { location: text(act.location, `executionStatus.recentActivity[${i}].location`) } : {}),
+            });
+        }));
+    }
+    return Object.freeze({
+        simulationId: id,
+        phase,
+        ...(mode !== undefined ? { mode } : {}),
+        turnsCount: input.turnsCount,
+        activeAgents: Object.freeze([...input.activeAgents]),
+        ...(failureReason ? { failureReason } : {}),
+        ...(startedAt ? { startedAt } : {}),
+        ...(stoppedAt ? { stoppedAt } : {}),
+        ...(recentActivity ? { recentActivity } : {}),
+    });
+}

package/dist/packages/contracts/simulation-results.js

@@ -0,0 +1,52 @@
+import { parseObservationSummary } from "./observation-summary.js";
+import { parseInvestigationSummary } from "./investigation-summary.js";
+import { oneOf, readSimulationId, record, text } from "./validation.js";
+import { ContractValidationError } from "./errors.js";
+function parseFindingAssessment(value, path) {
+    const item = record(value, path, [
+        "investigationId", "hypothesis", "outcome", "confidence", "explanation", "isConfirmedFinding", "participatingAgents", "evidenceIds",
+    ]);
+    const outcome = oneOf(item.outcome, ["supported", "contradicted", "inconclusive"], `${path}.outcome`);
+    const confidence = oneOf(item.confidence, ["provisional", "corroborated", "inconclusive", "refuted"], `${path}.confidence`);
+    if (typeof item.isConfirmedFinding !== "boolean") {
+        throw new ContractValidationError(`${path}.isConfirmedFinding`, "Expected a boolean.");
+    }
+    if (!Array.isArray(item.participatingAgents)) {
+        throw new ContractValidationError(`${path}.participatingAgents`, "Expected an array.");
+    }
+    if (!Array.isArray(item.evidenceIds)) {
+        throw new ContractValidationError(`${path}.evidenceIds`, "Expected an array.");
+    }
+    return Object.freeze({
+        investigationId: text(item.investigationId, `${path}.investigationId`),
+        hypothesis: text(item.hypothesis, `${path}.hypothesis`),
+        outcome,
+        confidence,
+        explanation: text(item.explanation, `${path}.explanation`),
+        isConfirmedFinding: item.isConfirmedFinding,
+        participatingAgents: Object.freeze(item.participatingAgents.map((a, i) => text(a, `${path}.participatingAgents[${i}]`))),
+        evidenceIds: Object.freeze(item.evidenceIds.map((e, i) => text(e, `${path}.evidenceIds[${i}]`))),
+        ...("uncertaintyReason" in item && typeof item.uncertaintyReason === "string" ? { uncertaintyReason: item.uncertaintyReason } : {}),
+    });
+}
+export function parseSimulationResults(value) {
+    const input = record(value, "simulationResults", [
+        "simulationId", "observations", "investigations", "findings",
+    ]);
+    const simulationId = readSimulationId(input.simulationId, "simulationResults.simulationId");
+    if (!Array.isArray(input.observations)) {
+        throw new ContractValidationError("simulationResults.observations", "Expected an array.");
+    }
+    if (!Array.isArray(input.investigations)) {
+        throw new ContractValidationError("simulationResults.investigations", "Expected an array.");
+    }
+    if (!Array.isArray(input.findings)) {
+        throw new ContractValidationError("simulationResults.findings", "Expected an array.");
+    }
+    return Object.freeze({
+        simulationId,
+        observations: Object.freeze(input.observations.map(obs => parseObservationSummary(obs))),
+        investigations: Object.freeze(input.investigations.map(inv => parseInvestigationSummary(inv))),
+        findings: Object.freeze(input.findings.map((f, i) => parseFindingAssessment(f, `simulationResults.findings[${i}]`))),
+    });
+}

package/dist/packages/contracts/simulation-setup.js

@@ -0,0 +1,60 @@
+import { ContractValidationError } from "./errors.js";
+import { oneOf, record, text } from "./validation.js";
+export const userProfileIds = [
+    "explorer",
+    "impatient",
+    "beginner",
+    "regular",
+    "meticulous",
+    "distrustful",
+];
+export const defaultExecutionLimits = Object.freeze({
+    maxTurnsPerAgent: 3, maxInferenceCallsPerTurn: 12, inferenceTimeoutMs: 15_000, durationMs: 30_000,
+});
+export function parseExecutionLimits(value) {
+    const input = record(value, "setup.limits", Object.keys(defaultExecutionLimits));
+    function positive(key, maximum) {
+        const result = input[key];
+        if (typeof result !== "number" || !Number.isSafeInteger(result) || result < 1 || result > maximum) {
+            throw new ContractValidationError(`setup.limits.${key}`, `Expected an integer from 1 to ${maximum}.`);
+        }
+        return result;
+    }
+    const limits = Object.freeze({ maxTurnsPerAgent: positive("maxTurnsPerAgent", 100),
+        maxInferenceCallsPerTurn: positive("maxInferenceCallsPerTurn", 100),
+        inferenceTimeoutMs: positive("inferenceTimeoutMs", 2_147_483_647), durationMs: positive("durationMs", 2_147_483_647) });
+    if (limits.inferenceTimeoutMs > limits.durationMs) {
+        throw new ContractValidationError("setup.limits.inferenceTimeoutMs", "Inference timeout must not exceed the session duration.");
+    }
+    return limits;
+}
+function targetUrl(value) {
+    const input = text(value, "setup.targetUrl").trim();
+    try {
+        if (!/^https?:\/\//i.test(input))
+            throw new Error("Expected an absolute HTTP address.");
+        const parsed = new URL(input);
+        if (!parsed.hostname || parsed.username || parsed.password)
+            throw new Error("Invalid or credential-bearing address.");
+        return parsed.href;
+    }
+    catch {
+        throw new ContractValidationError("setup.targetUrl", "Expected an absolute HTTP(S) URL without embedded credentials.");
+    }
+}
+export function parseSimulationSetup(value) {
+    const input = record(value, "setup", ["name", "targetUrl", "environment", "goal", "userProfileIds", "limits"]);
+    const environment = record(input.environment, "setup.environment", ["kind", "deployment"]);
+    if (!Array.isArray(input.userProfileIds) || !input.userProfileIds.length) {
+        throw new ContractValidationError("setup.userProfileIds", "Select at least one behavioral profile.");
+    }
+    const profiles = Array.from(input.userProfileIds, (id) => oneOf(id, userProfileIds, "setup.userProfileIds"));
+    if (new Set(profiles).size !== profiles.length)
+        throw new ContractValidationError("setup.userProfileIds", "Profiles must be unique.");
+    return Object.freeze({ ...(input.name === undefined ? {} : { name: text(input.name, "setup.name").trim() }),
+        targetUrl: targetUrl(input.targetUrl), goal: text(input.goal, "setup.goal"),
+        environment: Object.freeze({ kind: oneOf(environment.kind, ["web"], "setup.environment.kind"),
+            deployment: oneOf(environment.deployment, ["local", "development", "test", "staging", "production"], "setup.environment.deployment") }),
+        userProfileIds: Object.freeze(profiles),
+        limits: parseExecutionLimits(input.limits === undefined ? defaultExecutionLimits : input.limits), });
+}

package/dist/packages/contracts/summaries.js

@@ -0,0 +1,42 @@
+import { ContractValidationError } from "./errors.js";
+import { oneOf, readAgentId, readSimulationId, record, text } from "./validation.js";
+function lifecycle(value, statuses, path) {
+    const input = record(value, path, ["status", "reason"]);
+    const status = oneOf(input.status, statuses, `${path}.status`);
+    if (status === "failed") {
+        return Object.freeze({ status: "failed", reason: text(input.reason, `${path}.reason`) });
+    }
+    if (Object.hasOwn(input, "reason")) {
+        throw new ContractValidationError(`${path}.reason`, "Only a failed lifecycle carries a reason.");
+    }
+    return Object.freeze({ status: status });
+}
+export function parseAgentSummary(value) {
+    const input = record(value, "agent", ["id", "simulationId", "name", "lifecycle"]);
+    return Object.freeze({
+        id: readAgentId(input.id, "agent.id"),
+        simulationId: readSimulationId(input.simulationId, "agent.simulationId"),
+        name: text(input.name, "agent.name"),
+        lifecycle: lifecycle(input.lifecycle, ["ready", "running", "completed", "failed", "cancelled"], "agent.lifecycle"),
+    });
+}
+export function parseSimulationSummary(value) {
+    const input = record(value, "simulation", ["id", "environment", "lifecycle", "agentIds"]);
+    const environment = record(input.environment, "simulation.environment", ["kind", "deployment"]);
+    if (!Array.isArray(input.agentIds)) {
+        throw new ContractValidationError("simulation.agentIds", "Expected an array.");
+    }
+    const agentIds = Array.from(input.agentIds, (id, index) => readAgentId(id, `simulation.agentIds[${index}]`));
+    if (new Set(agentIds).size !== agentIds.length) {
+        throw new ContractValidationError("simulation.agentIds", "Agent IDs must be unique.");
+    }
+    return Object.freeze({
+        id: readSimulationId(input.id, "simulation.id"),
+        environment: Object.freeze({
+            kind: oneOf(environment.kind, ["web"], "simulation.environment.kind"),
+            deployment: oneOf(environment.deployment, ["local", "development", "test", "staging", "production"], "simulation.environment.deployment"),
+        }),
+        lifecycle: lifecycle(input.lifecycle, ["created", "running", "completed", "failed", "cancelled"], "simulation.lifecycle"),
+        agentIds: Object.freeze(agentIds),
+    });
+}

package/dist/packages/contracts/target-connection.js

@@ -0,0 +1,36 @@
+import { ContractValidationError } from "./errors.js";
+import { oneOf, record, text } from "./validation.js";
+/** Restrict explicit connection checks to local HTTP services, without DNS. */
+export function parseLocalTargetUrl(value) {
+    const input = text(value, "target.url").trim();
+    try {
+        const url = new URL(input);
+        if (input.length > 2048 || !/^https?:\/\//i.test(input) || url.username || url.password ||
+            !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+            throw new Error();
+        url.hash = "";
+        return url.href;
+    }
+    catch {
+        throw new ContractValidationError("target.url", "Use a local HTTP(S) URL with localhost, 127.0.0.1, or [::1], without credentials.");
+    }
+}
+export function parseTargetSuggestion(value) {
+    const input = record(value, "targetSuggestion", ["url", "source", "scriptName"]);
+    return Object.freeze({ url: parseLocalTargetUrl(input.url), source: oneOf(input.source, ["vite-default", "vite-script"], "targetSuggestion.source"),
+        scriptName: text(input.scriptName, "targetSuggestion.scriptName") });
+}
+export function parseTargetConnection(value) {
+    const input = record(value, "connection", ["url", "kind", "statusCode"]);
+    const url = parseLocalTargetUrl(input.url);
+    const kind = oneOf(input.kind, ["response", "unreachable", "timeout", "tls-error", "busy"], "connection.kind");
+    if (kind === "response") {
+        if (typeof input.statusCode !== "number" || !Number.isInteger(input.statusCode) || input.statusCode < 100 || input.statusCode > 599) {
+            throw new ContractValidationError("connection.statusCode", "Expected an HTTP status code.");
+        }
+        return Object.freeze({ url, kind, statusCode: input.statusCode });
+    }
+    if (input.statusCode !== undefined)
+        throw new ContractValidationError("connection.statusCode", "Only HTTP responses have a status code.");
+    return Object.freeze({ url, kind });
+}

package/dist/packages/contracts/validation.js

@@ -0,0 +1,42 @@
+import { agentId, simulationId } from "../domain/index.js";
+import { ContractValidationError } from "./errors.js";
+export function record(value, path, keys) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ContractValidationError(path, "Expected a plain object.");
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new ContractValidationError(path, "Expected a plain object.");
+    }
+    if (Reflect.ownKeys(value).some((key) => typeof key !== "string" || !keys.includes(key))) {
+        throw new ContractValidationError(path, "Unknown fields are not supported by this schema.");
+    }
+    return value;
+}
+export function text(value, path) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new ContractValidationError(path, "Expected a nonblank string.");
+    }
+    return value;
+}
+export function oneOf(value, values, path) {
+    if (typeof value !== "string" || !values.includes(value)) {
+        throw new ContractValidationError(path, "Unsupported value.");
+    }
+    return value;
+}
+export function readAgentId(value, path) {
+    return agentId(text(value, path));
+}
+export function readSimulationId(value, path) {
+    return simulationId(text(value, path));
+}
+export function timestamp(value, path) {
+    const result = text(value, path);
+    const date = new Date(result);
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(result) ||
+        !Number.isFinite(date.getTime()) || date.toISOString() !== result) {
+        throw new ContractValidationError(path, "Expected a valid UTC timestamp in YYYY-MM-DDTHH:mm:ss.sssZ format.");
+    }
+    return result;
+}

package/dist/packages/domain/agent.js

@@ -0,0 +1,23 @@
+import { DomainError, nonBlank } from "./errors.js";
+import { agentId } from "./identity.js";
+import { createAgentProfile } from "./profile.js";
+export function createAgent(id, profile) {
+    return Object.freeze({
+        id: agentId(id),
+        profile: createAgentProfile(profile),
+        lifecycle: Object.freeze({ status: "ready" }),
+    });
+}
+export function transitionAgent(agent, next) {
+    const current = agent.lifecycle.status;
+    const allowed = current === "ready"
+        ? next.status === "running" || next.status === "cancelled"
+        : current === "running" && ["completed", "failed", "cancelled"].includes(next.status);
+    if (!allowed) {
+        throw new DomainError("INVALID_TRANSITION", `Agent cannot move from ${current} to ${next.status}.`);
+    }
+    const lifecycle = next.status === "failed"
+        ? Object.freeze({ status: "failed", reason: nonBlank(next.reason, "Failure reason") })
+        : Object.freeze({ status: next.status });
+    return Object.freeze({ ...agent, lifecycle });
+}

package/dist/packages/domain/environment.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/domain/errors.js

@@ -0,0 +1,14 @@
+export class DomainError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "DomainError";
+        this.code = code;
+    }
+}
+export function nonBlank(value, field) {
+    if (value.trim().length === 0) {
+        throw new DomainError("INVALID_VALUE", `${field} must not be blank.`);
+    }
+    return value;
+}

package/dist/packages/domain/identity.js

@@ -0,0 +1,16 @@
+import { nonBlank } from "./errors.js";
+export function simulationId(value) {
+    return nonBlank(value, "Simulation ID");
+}
+export function agentId(value) {
+    return nonBlank(value, "Agent ID");
+}
+export function observationId(value) {
+    return nonBlank(value, "Observation ID");
+}
+export function evidenceId(value) {
+    return nonBlank(value, "Evidence ID");
+}
+export function investigationId(value) {
+    return nonBlank(value, "Investigation ID");
+}

package/dist/packages/domain/index.js

@@ -0,0 +1,10 @@
+export { DomainError } from "./errors.js";
+export { agentId, simulationId } from "./identity.js";
+export { observationId, evidenceId } from "./identity.js";
+export { createObservation } from "./observation.js";
+export { investigationId } from "./identity.js";
+export { createInvestigationResult } from "./investigation-result.js";
+export { requestInvestigation, assignInvestigation, completeInvestigation } from "./investigation.js";
+export { createAgentProfile } from "./profile.js";
+export { createAgent, transitionAgent } from "./agent.js";
+export { createSimulation, transitionSimulation, updateSimulationAgent } from "./simulation.js";

package/dist/packages/domain/investigation-result.js

@@ -0,0 +1,19 @@
+import { DomainError, nonBlank } from "./errors.js";
+import { evidenceId } from "./identity.js";
+export function createInvestigationResult(input) {
+    if (!["supported", "contradicted", "inconclusive"].includes(input.outcome)) {
+        throw new DomainError("INVALID_VALUE", "Unknown investigation outcome.");
+    }
+    const evidenceIds = input.evidenceIds.map(evidenceId);
+    if (new Set(evidenceIds).size !== evidenceIds.length) {
+        throw new DomainError("INVALID_VALUE", "Result evidence references must be unique.");
+    }
+    if (input.outcome !== "inconclusive" && evidenceIds.length === 0) {
+        throw new DomainError("INVALID_VALUE", "A supported or contradicted hypothesis requires evidence references.");
+    }
+    return Object.freeze({
+        outcome: input.outcome,
+        explanation: nonBlank(input.explanation, "Result explanation"),
+        evidenceIds: Object.freeze(evidenceIds),
+    });
+}