@condition-sh/core 2026.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rad Soft, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @condition-sh/core
+
+The Condition scenario contract and run engine.
+
+Docs at https://condition.sh.

package/index.js

@@ -0,0 +1,444 @@
+// packages/core/src/index.ts
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// packages/core/src/extract.ts
+var linkPattern = /https?:\/\/[^\s"'<>)\]]+/g;
+var codePattern = /(?<![\d-])\d{4,8}(?![\d-])/g;
+var unique = (values, limit) => [...new Set(values)].slice(0, limit);
+function trimPunctuation(link) {
+  let end = link.length;
+  while (end > 0 && ".,;:".includes(link[end - 1]))
+    end--;
+  return link.slice(0, end);
+}
+function stripTags(html) {
+  let out = "";
+  let inTag = false;
+  for (const character of html) {
+    if (character === "<")
+      inTag = true;
+    else if (character === ">") {
+      inTag = false;
+      out += " ";
+    } else if (!inTag)
+      out += character;
+  }
+  return out;
+}
+function decodeEntities(value) {
+  return value.replaceAll("&amp;", "&").replaceAll("&quot;", '"').replaceAll("&#39;", "'");
+}
+function extract(message) {
+  const text = `${message.bodyText}
+${decodeEntities(message.bodyHtml)}`;
+  const links = unique((text.match(linkPattern) ?? []).map(trimPunctuation), 20);
+  const visible = `${message.subject}
+${message.bodyText || stripTags(message.bodyHtml)}`;
+  const codes = unique((visible.replace(linkPattern, " ").match(codePattern) ?? []).filter((code) => !/^(19|20)\d{2}$/.test(code)), 10);
+  return { ...message, links, codes };
+}
+
+// packages/core/src/schema.ts
+function typeOf(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  if (typeof value === "number" && Number.isInteger(value))
+    return "integer";
+  return typeof value;
+}
+function matchesType(expected, value) {
+  const actual = typeOf(value);
+  return expected === actual || expected === "number" && actual === "integer";
+}
+function checkBounds(schema, value, path, errors) {
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum)
+      errors.push(`${path} must be at least ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum)
+      errors.push(`${path} must be at most ${schema.maximum}`);
+  }
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength)
+      errors.push(`${path} is shorter than ${schema.minLength}`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength)
+      errors.push(`${path} is longer than ${schema.maxLength}`);
+  }
+}
+function checkObject(schema, value, path, errors) {
+  for (const key of schema.required ?? [])
+    if (!(key in value))
+      errors.push(`${path}.${key} is required`);
+  for (const [key, child] of Object.entries(value)) {
+    const property = schema.properties?.[key];
+    if (property)
+      check(property, child, `${path}.${key}`, errors);
+    else if (schema.additionalProperties === false)
+      errors.push(`${path}.${key} is not allowed`);
+  }
+}
+function check(schema, value, path, errors) {
+  if (schema.type && !matchesType(schema.type, value)) {
+    errors.push(`${path} must be ${schema.type}`);
+    return;
+  }
+  if (schema.enum && !schema.enum.some((option) => JSON.stringify(option) === JSON.stringify(value))) {
+    errors.push(`${path} must be one of ${schema.enum.map((option) => JSON.stringify(option)).join(", ")}`);
+  }
+  checkBounds(schema, value, path, errors);
+  if (typeOf(value) === "object")
+    checkObject(schema, value, path, errors);
+  if (Array.isArray(value) && schema.items)
+    value.forEach((item, index) => check(schema.items, item, `${path}[${index}]`, errors));
+}
+function validateInput(schema, value) {
+  const errors = [];
+  check(schema, value, "input", errors);
+  return errors;
+}
+// packages/core/src/remote-inbox.ts
+import { createHash } from "node:crypto";
+var actorPattern = /^[a-z][a-z0-9-]{0,15}$/;
+var legacyInboxDomain = "inbox.condition.sh";
+function inboxAlias(runId) {
+  const hex = createHash("sha256").update(runId).digest("hex").slice(0, 12);
+  return (parseInt(hex, 16) % 36 ** 6).toString(36).padStart(6, "0");
+}
+function inboxAddress(actor, runId, domain) {
+  if (!actorPattern.test(actor))
+    throw new Error(`invalid inbox actor ${actor}`);
+  return `${actor}.${domain === legacyInboxDomain ? runId : inboxAlias(runId)}@${domain}`;
+}
+
+class RemoteInbox {
+  token;
+  domain;
+  tenant;
+  base;
+  constructor(url, token, domain = "cndx.dev", tenant) {
+    this.token = token;
+    this.domain = domain;
+    this.tenant = tenant;
+    this.base = new URL(url);
+    if (this.base.protocol !== "https:" && this.base.hostname !== "localhost" && this.base.hostname !== "127.0.0.1") {
+      throw new Error("inbox API requires HTTPS");
+    }
+    if (!token)
+      throw new Error("inbox control token is required");
+  }
+  get identity() {
+    return `${this.base.origin}${this.base.pathname}|${this.domain}`;
+  }
+  address(runId, actor) {
+    return inboxAddress(actor, runId, this.domain);
+  }
+  async request(method, path, body) {
+    const response = await fetch(new URL(path, this.base), {
+      method,
+      redirect: "error",
+      headers: { authorization: `Bearer ${this.token}`, "content-type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+    const result = await response.json();
+    if (!response.ok)
+      throw new Error(`inbox ${method} ${path}: ${response.status} ${result.error ?? "request failed"}`);
+    return result;
+  }
+  async reserve(details) {
+    const body = { ...details, domain: this.domain, ...this.tenant ? { tenant: this.tenant } : {} };
+    const reserved = await this.request("POST", "/v1/leases", body);
+    if (reserved.domain !== this.domain)
+      throw new Error(`inbox domain mismatch: ${reserved.domain}`);
+  }
+  list(runId, actor) {
+    this.address(runId, actor);
+    return this.request("GET", `/v1/runs/${runId}/inbox/${actor}`);
+  }
+  async release(runId) {
+    await this.request("DELETE", `/v1/leases/${runId}`);
+  }
+}
+
+// packages/core/src/index.ts
+var control = (value) => [...value].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+function defineProject(project) {
+  if (typeof project.name !== "string" || !project.name.trim() || project.name.length > 200 || control(project.name) || !Object.keys(project.scenarios).length) {
+    throw new Error("project needs a valid name and at least one scenario");
+  }
+  if (project.inbox && (typeof project.inbox.identity !== "string" || !project.inbox.identity.trim())) {
+    throw new Error("inbox needs a stable identity");
+  }
+  return project;
+}
+async function loadProject(path = process.env.CONDITION_PROJECT ?? "condition.config.ts") {
+  const module = await import(pathToFileURL(resolve(path)).href);
+  if (!module.default)
+    throw new Error(`${path} must export a default project`);
+  return defineProject(module.default);
+}
+function errorCode(error, step) {
+  if (/runner unreachable/.test(message(error)))
+    return "runner_unreachable";
+  if (step === "inbox")
+    return "inbox_unavailable";
+  return `${step}_failed`;
+}
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function parse(json) {
+  return json === null ? null : JSON.parse(json);
+}
+async function presentation(hook, value) {
+  if (!hook)
+    return null;
+  return JSON.stringify(await hook(value)) ?? null;
+}
+function describeProject(project) {
+  return {
+    project: project.name,
+    scenarios: Object.entries(project.scenarios).map(([name, scenario]) => ({
+      name,
+      description: scenario.description,
+      ...scenario.input ? { input: scenario.input } : {},
+      ...scenario.actors ? { actors: scenario.actors } : {}
+    }))
+  };
+}
+function publicRun(run, project) {
+  return {
+    id: run.id,
+    project,
+    scenario: run.scenario,
+    input: parse(run.presentedInput),
+    output: parse(run.presentedOutput),
+    status: run.status,
+    leaseUntil: run.leaseUntil,
+    createdAt: run.createdAt,
+    error: run.error,
+    errorCode: run.errorCode,
+    hasInbox: run.inboxRef !== null
+  };
+}
+
+class Condition {
+  project;
+  store;
+  now;
+  constructor(project, store, options = {}) {
+    this.project = project;
+    this.store = store;
+    this.now = options.now ?? (() => new Date);
+  }
+  describe() {
+    return describeProject(this.project);
+  }
+  async get(id) {
+    return this.publicRun(await this.read(id));
+  }
+  async list() {
+    return (await this.store.list()).map((run) => this.publicRun(run));
+  }
+  async read(id) {
+    const run = await this.store.find(id);
+    if (!run)
+      throw new Error(`run ${id} not found`);
+    return run;
+  }
+  publicRun(run) {
+    return publicRun(run, this.project.name);
+  }
+  scenario(name) {
+    const scenario = this.project.scenarios[name];
+    if (!scenario)
+      throw new Error(`unknown scenario ${name}`);
+    return scenario;
+  }
+  inboxFor(run) {
+    const inbox = this.project.inbox;
+    if (!run.inboxRef || !inbox || inbox.identity !== run.inboxRef)
+      return;
+    return { address: (actor) => inbox.address(run.id, actor) };
+  }
+  checkActor(run, actor, capability) {
+    const actors = this.scenario(run.scenario).actors;
+    if (actors && !actors.some((spec) => spec.name === actor && spec[capability])) {
+      throw new Error(`actor ${actor} has no ${capability} in ${run.scenario}`);
+    }
+  }
+  active(run) {
+    return run.status === "ready" && run.leaseUntil > this.now().toISOString();
+  }
+  async start(name, input = {}, options = {}) {
+    const scenario = this.scenario(name);
+    const problems = scenario.input ? validateInput(scenario.input, input) : [];
+    if (problems.length)
+      throw new Error(`invalid input: ${problems.join("; ")}`);
+    const wantsInbox = !scenario.actors || scenario.actors.some((actor) => actor.inbox);
+    const minutes = options.leaseMinutes ?? 20;
+    if (!Number.isInteger(minutes) || minutes < 1 || minutes > 1440)
+      throw new Error("leaseMinutes must be 1–1440");
+    if (options.requestKey && options.requestKey.length > 200)
+      throw new Error("requestKey is too long");
+    const inputJson = JSON.stringify(input);
+    if (inputJson === undefined)
+      throw new Error("input must be JSON serializable");
+    const now = this.now();
+    const run = {
+      id: crypto.randomUUID(),
+      scenario: name,
+      input: inputJson,
+      output: null,
+      status: "preparing",
+      leaseUntil: new Date(now.getTime() + minutes * 60000).toISOString(),
+      createdAt: now.toISOString(),
+      error: null,
+      errorCode: null,
+      requestKey: options.requestKey ?? null,
+      inboxRef: wantsInbox ? this.project.inbox?.identity ?? null : null,
+      presentedInput: null,
+      presentedOutput: null
+    };
+    if (await this.store.insert(run))
+      return { run: this.publicRun(run), created: true };
+    const existing = run.requestKey ? await this.store.findByRequestKey(run.requestKey) : null;
+    if (!existing)
+      throw new Error("run conflict");
+    if (existing.scenario !== name || existing.input !== inputJson)
+      throw new Error("requestKey was used with different input");
+    return { run: this.publicRun(existing), created: false };
+  }
+  async prepare(id) {
+    const run = await this.read(id);
+    if (run.status !== "preparing")
+      throw new Error(`run ${id} is ${run.status}`);
+    const scenario = this.scenario(run.scenario);
+    const input = JSON.parse(run.input);
+    const inbox = this.project.inbox;
+    let step = "prepare";
+    try {
+      if (!await this.store.update(id, "preparing", { presentedInput: await presentation(scenario.presentInput, input) })) {
+        throw new Error(`run ${id} changed during preparation`);
+      }
+      if (run.inboxRef) {
+        step = "inbox";
+        if (!inbox || inbox.identity !== run.inboxRef)
+          throw new Error(`inbox configuration for run ${id} is unavailable or changed`);
+        await inbox.reserve({ runId: id, project: this.project.name, leaseUntil: run.leaseUntil });
+        step = "prepare";
+      }
+      const output = await scenario.prepare({ runId: id, input, inbox: this.inboxFor(run) });
+      const saved = await this.store.update(id, "preparing", {
+        output: JSON.stringify(output ?? null),
+        presentedOutput: await presentation(scenario.present, output ?? null)
+      });
+      if (!saved)
+        throw new Error(`run ${id} changed during preparation`);
+      step = "verify";
+      await scenario.verify({ runId: id, input, output, inbox: this.inboxFor(run) });
+      if (!await this.store.update(id, "preparing", { status: "ready" }))
+        throw new Error(`run ${id} changed during verification`);
+    } catch (error) {
+      await this.store.update(id, "preparing", { status: "failed", error: message(error), errorCode: errorCode(error, step) });
+      throw new Error(`run ${id} failed: ${message(error)}`, { cause: error });
+    }
+    return this.get(id);
+  }
+  async condition(name, input = {}, options = {}) {
+    const { run, created } = await this.start(name, input, options);
+    return created ? this.prepare(run.id) : run;
+  }
+  async login(id, actor) {
+    const run = await this.read(id);
+    if (run.status !== "ready")
+      throw new Error(`run ${id} is ${run.status}`);
+    if (!this.active(run))
+      throw new Error(`run ${id} lease expired`);
+    const scenario = this.scenario(run.scenario);
+    if (!scenario.login)
+      throw new Error(`scenario ${run.scenario} does not provide login`);
+    this.checkActor(run, actor, "login");
+    return scenario.login({ runId: id, input: JSON.parse(run.input), output: parse(run.output), actor, inbox: this.inboxFor(run) });
+  }
+  async inbox(id, actor) {
+    const run = await this.read(id);
+    if (!this.active(run))
+      throw new Error(`run ${id} is not active`);
+    if (!run.inboxRef)
+      throw new Error(`run ${id} has no inbox`);
+    if (!this.project.inbox || this.project.inbox.identity !== run.inboxRef) {
+      throw new Error(`inbox configuration for run ${id} is unavailable or changed`);
+    }
+    this.checkActor(run, actor, "inbox");
+    const inbox = await this.project.inbox.list(id, actor);
+    return { ...inbox, messages: inbox.messages.map(extract) };
+  }
+  async claimReset(id) {
+    const run = await this.read(id);
+    if (run.status === "released")
+      return false;
+    if (run.status === "preparing")
+      throw new Error(`run ${id} is still preparing`);
+    if (run.status === "cleaning")
+      throw new Error(`run ${id} is already cleaning`);
+    this.scenario(run.scenario);
+    if (!await this.store.update(id, run.status, { status: "cleaning" }))
+      throw new Error(`run ${id} changed while cleanup started`);
+    return true;
+  }
+  async finishReset(id) {
+    const run = await this.read(id);
+    if (run.status !== "cleaning")
+      throw new Error(`run ${id} is ${run.status}`);
+    const scenario = this.scenario(run.scenario);
+    try {
+      await scenario.cleanup({ runId: id, input: JSON.parse(run.input), output: parse(run.output), inbox: this.inboxFor(run) });
+      if (run.inboxRef) {
+        if (!this.project.inbox || this.project.inbox.identity !== run.inboxRef) {
+          throw new Error(`inbox configuration for run ${id} is unavailable or changed`);
+        }
+        await this.project.inbox.release(id);
+      }
+      await this.store.update(id, "cleaning", { status: "released", error: null, errorCode: null });
+    } catch (error) {
+      await this.store.update(id, "cleaning", { status: "cleanup_failed", error: message(error), errorCode: errorCode(error, "cleanup") });
+      throw new Error(`cleanup for ${id} failed: ${message(error)}`, { cause: error });
+    }
+    return this.get(id);
+  }
+  async reset(id) {
+    return await this.claimReset(id) ? this.finishReset(id) : this.get(id);
+  }
+  async cleanupExpired() {
+    const released = [];
+    const failures = [];
+    for (const id of await this.store.expired(this.now().toISOString())) {
+      try {
+        released.push(await this.reset(id));
+      } catch (error) {
+        failures.push({ id, error });
+      }
+    }
+    if (failures.length) {
+      throw new AggregateError(failures.map(({ error }) => error), `cleanup failed for ${failures.map(({ id }) => id).join(", ")}`);
+    }
+    return released;
+  }
+  close() {
+    return this.store.close();
+  }
+}
+export {
+  validateInput,
+  publicRun,
+  loadProject,
+  legacyInboxDomain,
+  inboxAlias,
+  inboxAddress,
+  describeProject,
+  defineProject,
+  RemoteInbox,
+  Condition
+};

package/local.js

@@ -0,0 +1,529 @@
+// packages/core/src/index.ts
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// packages/core/src/extract.ts
+var linkPattern = /https?:\/\/[^\s"'<>)\]]+/g;
+var codePattern = /(?<![\d-])\d{4,8}(?![\d-])/g;
+var unique = (values, limit) => [...new Set(values)].slice(0, limit);
+function trimPunctuation(link) {
+  let end = link.length;
+  while (end > 0 && ".,;:".includes(link[end - 1]))
+    end--;
+  return link.slice(0, end);
+}
+function stripTags(html) {
+  let out = "";
+  let inTag = false;
+  for (const character of html) {
+    if (character === "<")
+      inTag = true;
+    else if (character === ">") {
+      inTag = false;
+      out += " ";
+    } else if (!inTag)
+      out += character;
+  }
+  return out;
+}
+function decodeEntities(value) {
+  return value.replaceAll("&amp;", "&").replaceAll("&quot;", '"').replaceAll("&#39;", "'");
+}
+function extract(message) {
+  const text = `${message.bodyText}
+${decodeEntities(message.bodyHtml)}`;
+  const links = unique((text.match(linkPattern) ?? []).map(trimPunctuation), 20);
+  const visible = `${message.subject}
+${message.bodyText || stripTags(message.bodyHtml)}`;
+  const codes = unique((visible.replace(linkPattern, " ").match(codePattern) ?? []).filter((code) => !/^(19|20)\d{2}$/.test(code)), 10);
+  return { ...message, links, codes };
+}
+
+// packages/core/src/schema.ts
+function typeOf(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  if (typeof value === "number" && Number.isInteger(value))
+    return "integer";
+  return typeof value;
+}
+function matchesType(expected, value) {
+  const actual = typeOf(value);
+  return expected === actual || expected === "number" && actual === "integer";
+}
+function checkBounds(schema, value, path, errors) {
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum)
+      errors.push(`${path} must be at least ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum)
+      errors.push(`${path} must be at most ${schema.maximum}`);
+  }
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength)
+      errors.push(`${path} is shorter than ${schema.minLength}`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength)
+      errors.push(`${path} is longer than ${schema.maxLength}`);
+  }
+}
+function checkObject(schema, value, path, errors) {
+  for (const key of schema.required ?? [])
+    if (!(key in value))
+      errors.push(`${path}.${key} is required`);
+  for (const [key, child] of Object.entries(value)) {
+    const property = schema.properties?.[key];
+    if (property)
+      check(property, child, `${path}.${key}`, errors);
+    else if (schema.additionalProperties === false)
+      errors.push(`${path}.${key} is not allowed`);
+  }
+}
+function check(schema, value, path, errors) {
+  if (schema.type && !matchesType(schema.type, value)) {
+    errors.push(`${path} must be ${schema.type}`);
+    return;
+  }
+  if (schema.enum && !schema.enum.some((option) => JSON.stringify(option) === JSON.stringify(value))) {
+    errors.push(`${path} must be one of ${schema.enum.map((option) => JSON.stringify(option)).join(", ")}`);
+  }
+  checkBounds(schema, value, path, errors);
+  if (typeOf(value) === "object")
+    checkObject(schema, value, path, errors);
+  if (Array.isArray(value) && schema.items)
+    value.forEach((item, index) => check(schema.items, item, `${path}[${index}]`, errors));
+}
+function validateInput(schema, value) {
+  const errors = [];
+  check(schema, value, "input", errors);
+  return errors;
+}
+// packages/core/src/remote-inbox.ts
+import { createHash } from "node:crypto";
+var actorPattern = /^[a-z][a-z0-9-]{0,15}$/;
+var legacyInboxDomain = "inbox.condition.sh";
+function inboxAlias(runId) {
+  const hex = createHash("sha256").update(runId).digest("hex").slice(0, 12);
+  return (parseInt(hex, 16) % 36 ** 6).toString(36).padStart(6, "0");
+}
+function inboxAddress(actor, runId, domain) {
+  if (!actorPattern.test(actor))
+    throw new Error(`invalid inbox actor ${actor}`);
+  return `${actor}.${domain === legacyInboxDomain ? runId : inboxAlias(runId)}@${domain}`;
+}
+
+class RemoteInbox {
+  token;
+  domain;
+  tenant;
+  base;
+  constructor(url, token, domain = "cndx.dev", tenant) {
+    this.token = token;
+    this.domain = domain;
+    this.tenant = tenant;
+    this.base = new URL(url);
+    if (this.base.protocol !== "https:" && this.base.hostname !== "localhost" && this.base.hostname !== "127.0.0.1") {
+      throw new Error("inbox API requires HTTPS");
+    }
+    if (!token)
+      throw new Error("inbox control token is required");
+  }
+  get identity() {
+    return `${this.base.origin}${this.base.pathname}|${this.domain}`;
+  }
+  address(runId, actor) {
+    return inboxAddress(actor, runId, this.domain);
+  }
+  async request(method, path, body) {
+    const response = await fetch(new URL(path, this.base), {
+      method,
+      redirect: "error",
+      headers: { authorization: `Bearer ${this.token}`, "content-type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+    const result = await response.json();
+    if (!response.ok)
+      throw new Error(`inbox ${method} ${path}: ${response.status} ${result.error ?? "request failed"}`);
+    return result;
+  }
+  async reserve(details) {
+    const body = { ...details, domain: this.domain, ...this.tenant ? { tenant: this.tenant } : {} };
+    const reserved = await this.request("POST", "/v1/leases", body);
+    if (reserved.domain !== this.domain)
+      throw new Error(`inbox domain mismatch: ${reserved.domain}`);
+  }
+  list(runId, actor) {
+    this.address(runId, actor);
+    return this.request("GET", `/v1/runs/${runId}/inbox/${actor}`);
+  }
+  async release(runId) {
+    await this.request("DELETE", `/v1/leases/${runId}`);
+  }
+}
+
+// packages/core/src/index.ts
+var control = (value) => [...value].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+function defineProject(project) {
+  if (typeof project.name !== "string" || !project.name.trim() || project.name.length > 200 || control(project.name) || !Object.keys(project.scenarios).length) {
+    throw new Error("project needs a valid name and at least one scenario");
+  }
+  if (project.inbox && (typeof project.inbox.identity !== "string" || !project.inbox.identity.trim())) {
+    throw new Error("inbox needs a stable identity");
+  }
+  return project;
+}
+async function loadProject(path = process.env.CONDITION_PROJECT ?? "condition.config.ts") {
+  const module = await import(pathToFileURL(resolve(path)).href);
+  if (!module.default)
+    throw new Error(`${path} must export a default project`);
+  return defineProject(module.default);
+}
+function errorCode(error, step) {
+  if (/runner unreachable/.test(message(error)))
+    return "runner_unreachable";
+  if (step === "inbox")
+    return "inbox_unavailable";
+  return `${step}_failed`;
+}
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function parse(json) {
+  return json === null ? null : JSON.parse(json);
+}
+async function presentation(hook, value) {
+  if (!hook)
+    return null;
+  return JSON.stringify(await hook(value)) ?? null;
+}
+function describeProject(project) {
+  return {
+    project: project.name,
+    scenarios: Object.entries(project.scenarios).map(([name, scenario]) => ({
+      name,
+      description: scenario.description,
+      ...scenario.input ? { input: scenario.input } : {},
+      ...scenario.actors ? { actors: scenario.actors } : {}
+    }))
+  };
+}
+function publicRun(run, project) {
+  return {
+    id: run.id,
+    project,
+    scenario: run.scenario,
+    input: parse(run.presentedInput),
+    output: parse(run.presentedOutput),
+    status: run.status,
+    leaseUntil: run.leaseUntil,
+    createdAt: run.createdAt,
+    error: run.error,
+    errorCode: run.errorCode,
+    hasInbox: run.inboxRef !== null
+  };
+}
+
+class Condition {
+  project;
+  store;
+  now;
+  constructor(project, store, options = {}) {
+    this.project = project;
+    this.store = store;
+    this.now = options.now ?? (() => new Date);
+  }
+  describe() {
+    return describeProject(this.project);
+  }
+  async get(id) {
+    return this.publicRun(await this.read(id));
+  }
+  async list() {
+    return (await this.store.list()).map((run) => this.publicRun(run));
+  }
+  async read(id) {
+    const run = await this.store.find(id);
+    if (!run)
+      throw new Error(`run ${id} not found`);
+    return run;
+  }
+  publicRun(run) {
+    return publicRun(run, this.project.name);
+  }
+  scenario(name) {
+    const scenario = this.project.scenarios[name];
+    if (!scenario)
+      throw new Error(`unknown scenario ${name}`);
+    return scenario;
+  }
+  inboxFor(run) {
+    const inbox = this.project.inbox;
+    if (!run.inboxRef || !inbox || inbox.identity !== run.inboxRef)
+      return;
+    return { address: (actor) => inbox.address(run.id, actor) };
+  }
+  checkActor(run, actor, capability) {
+    const actors = this.scenario(run.scenario).actors;
+    if (actors && !actors.some((spec) => spec.name === actor && spec[capability])) {
+      throw new Error(`actor ${actor} has no ${capability} in ${run.scenario}`);
+    }
+  }
+  active(run) {
+    return run.status === "ready" && run.leaseUntil > this.now().toISOString();
+  }
+  async start(name, input = {}, options = {}) {
+    const scenario = this.scenario(name);
+    const problems = scenario.input ? validateInput(scenario.input, input) : [];
+    if (problems.length)
+      throw new Error(`invalid input: ${problems.join("; ")}`);
+    const wantsInbox = !scenario.actors || scenario.actors.some((actor) => actor.inbox);
+    const minutes = options.leaseMinutes ?? 20;
+    if (!Number.isInteger(minutes) || minutes < 1 || minutes > 1440)
+      throw new Error("leaseMinutes must be 1–1440");
+    if (options.requestKey && options.requestKey.length > 200)
+      throw new Error("requestKey is too long");
+    const inputJson = JSON.stringify(input);
+    if (inputJson === undefined)
+      throw new Error("input must be JSON serializable");
+    const now = this.now();
+    const run = {
+      id: crypto.randomUUID(),
+      scenario: name,
+      input: inputJson,
+      output: null,
+      status: "preparing",
+      leaseUntil: new Date(now.getTime() + minutes * 60000).toISOString(),
+      createdAt: now.toISOString(),
+      error: null,
+      errorCode: null,
+      requestKey: options.requestKey ?? null,
+      inboxRef: wantsInbox ? this.project.inbox?.identity ?? null : null,
+      presentedInput: null,
+      presentedOutput: null
+    };
+    if (await this.store.insert(run))
+      return { run: this.publicRun(run), created: true };
+    const existing = run.requestKey ? await this.store.findByRequestKey(run.requestKey) : null;
+    if (!existing)
+      throw new Error("run conflict");
+    if (existing.scenario !== name || existing.input !== inputJson)
+      throw new Error("requestKey was used with different input");
+    return { run: this.publicRun(existing), created: false };
+  }
+  async prepare(id) {
+    const run = await this.read(id);
+    if (run.status !== "preparing")
+      throw new Error(`run ${id} is ${run.status}`);
+    const scenario = this.scenario(run.scenario);
+    const input = JSON.parse(run.input);
+    const inbox = this.project.inbox;
+    let step = "prepare";
+    try {
+      if (!await this.store.update(id, "preparing", { presentedInput: await presentation(scenario.presentInput, input) })) {
+        throw new Error(`run ${id} changed during preparation`);
+      }
+      if (run.inboxRef) {
+        step = "inbox";
+        if (!inbox || inbox.identity !== run.inboxRef)
+          throw new Error(`inbox configuration for run ${id} is unavailable or changed`);
+        await inbox.reserve({ runId: id, project: this.project.name, leaseUntil: run.leaseUntil });
+        step = "prepare";
+      }
+      const output = await scenario.prepare({ runId: id, input, inbox: this.inboxFor(run) });
+      const saved = await this.store.update(id, "preparing", {
+        output: JSON.stringify(output ?? null),
+        presentedOutput: await presentation(scenario.present, output ?? null)
+      });
+      if (!saved)
+        throw new Error(`run ${id} changed during preparation`);
+      step = "verify";
+      await scenario.verify({ runId: id, input, output, inbox: this.inboxFor(run) });
+      if (!await this.store.update(id, "preparing", { status: "ready" }))
+        throw new Error(`run ${id} changed during verification`);
+    } catch (error) {
+      await this.store.update(id, "preparing", { status: "failed", error: message(error), errorCode: errorCode(error, step) });
+      throw new Error(`run ${id} failed: ${message(error)}`, { cause: error });
+    }
+    return this.get(id);
+  }
+  async condition(name, input = {}, options = {}) {
+    const { run, created } = await this.start(name, input, options);
+    return created ? this.prepare(run.id) : run;
+  }
+  async login(id, actor) {
+    const run = await this.read(id);
+    if (run.status !== "ready")
+      throw new Error(`run ${id} is ${run.status}`);
+    if (!this.active(run))
+      throw new Error(`run ${id} lease expired`);
+    const scenario = this.scenario(run.scenario);
+    if (!scenario.login)
+      throw new Error(`scenario ${run.scenario} does not provide login`);
+    this.checkActor(run, actor, "login");
+    return scenario.login({ runId: id, input: JSON.parse(run.input), output: parse(run.output), actor, inbox: this.inboxFor(run) });
+  }
+  async inbox(id, actor) {
+    const run = await this.read(id);
+    if (!this.active(run))
+      throw new Error(`run ${id} is not active`);
+    if (!run.inboxRef)
+      throw new Error(`run ${id} has no inbox`);
+    if (!this.project.inbox || this.project.inbox.identity !== run.inboxRef) {
+      throw new Error(`inbox configuration for run ${id} is unavailable or changed`);
+    }
+    this.checkActor(run, actor, "inbox");
+    const inbox = await this.project.inbox.list(id, actor);
+    return { ...inbox, messages: inbox.messages.map(extract) };
+  }
+  async claimReset(id) {
+    const run = await this.read(id);
+    if (run.status === "released")
+      return false;
+    if (run.status === "preparing")
+      throw new Error(`run ${id} is still preparing`);
+    if (run.status === "cleaning")
+      throw new Error(`run ${id} is already cleaning`);
+    this.scenario(run.scenario);
+    if (!await this.store.update(id, run.status, { status: "cleaning" }))
+      throw new Error(`run ${id} changed while cleanup started`);
+    return true;
+  }
+  async finishReset(id) {
+    const run = await this.read(id);
+    if (run.status !== "cleaning")
+      throw new Error(`run ${id} is ${run.status}`);
+    const scenario = this.scenario(run.scenario);
+    try {
+      await scenario.cleanup({ runId: id, input: JSON.parse(run.input), output: parse(run.output), inbox: this.inboxFor(run) });
+      if (run.inboxRef) {
+        if (!this.project.inbox || this.project.inbox.identity !== run.inboxRef) {
+          throw new Error(`inbox configuration for run ${id} is unavailable or changed`);
+        }
+        await this.project.inbox.release(id);
+      }
+      await this.store.update(id, "cleaning", { status: "released", error: null, errorCode: null });
+    } catch (error) {
+      await this.store.update(id, "cleaning", { status: "cleanup_failed", error: message(error), errorCode: errorCode(error, "cleanup") });
+      throw new Error(`cleanup for ${id} failed: ${message(error)}`, { cause: error });
+    }
+    return this.get(id);
+  }
+  async reset(id) {
+    return await this.claimReset(id) ? this.finishReset(id) : this.get(id);
+  }
+  async cleanupExpired() {
+    const released = [];
+    const failures = [];
+    for (const id of await this.store.expired(this.now().toISOString())) {
+      try {
+        released.push(await this.reset(id));
+      } catch (error) {
+        failures.push({ id, error });
+      }
+    }
+    if (failures.length) {
+      throw new AggregateError(failures.map(({ error }) => error), `cleanup failed for ${failures.map(({ id }) => id).join(", ")}`);
+    }
+    return released;
+  }
+  close() {
+    return this.store.close();
+  }
+}
+
+// packages/core/src/store.ts
+import { Database } from "bun:sqlite";
+import { mkdirSync, chmodSync } from "node:fs";
+import { dirname, resolve as resolve2 } from "node:path";
+var columns = {
+  status: "status",
+  output: "output",
+  error: "error",
+  errorCode: "error_code",
+  presentedInput: "presented_input",
+  presentedOutput: "presented_output"
+};
+function fromRow(row) {
+  return {
+    id: row.id,
+    scenario: row.scenario,
+    input: row.input,
+    output: row.output,
+    status: row.status,
+    leaseUntil: row.lease_until,
+    createdAt: row.created_at,
+    error: row.error,
+    errorCode: row.error_code,
+    requestKey: row.request_key,
+    inboxRef: row.inbox_ref,
+    presentedInput: row.presented_input,
+    presentedOutput: row.presented_output
+  };
+}
+
+class SqliteRunStore {
+  project;
+  db;
+  constructor(databasePath, project) {
+    this.project = project;
+    const path = resolve2(databasePath);
+    mkdirSync(dirname(path), { recursive: true, mode: 448 });
+    this.db = new Database(path, { create: true });
+    chmodSync(path, 384);
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(`CREATE TABLE IF NOT EXISTS runs (
+      id TEXT PRIMARY KEY, project TEXT NOT NULL, scenario TEXT NOT NULL,
+      input TEXT NOT NULL, output TEXT, status TEXT NOT NULL,
+      lease_until TEXT NOT NULL, created_at TEXT NOT NULL,
+      error TEXT, request_key TEXT, inbox_ref TEXT,
+      presented_input TEXT, presented_output TEXT, error_code TEXT,
+      UNIQUE(project, request_key)
+    )`);
+    const existing = new Set(this.db.query("PRAGMA table_info(runs)").all().map((column) => column.name));
+    for (const column of ["inbox_ref", "presented_input", "presented_output", "error_code"]) {
+      if (!existing.has(column))
+        this.db.exec(`ALTER TABLE runs ADD COLUMN ${column} TEXT`);
+    }
+    this.db.exec("CREATE INDEX IF NOT EXISTS runs_lease_idx ON runs(status, lease_until)");
+  }
+  async insert(run) {
+    const inserted = this.db.query(`INSERT INTO runs (id, project, scenario, input, output, status, lease_until, created_at, error, error_code, request_key, inbox_ref, presented_input, presented_output)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(project, request_key) DO NOTHING RETURNING id`).get(run.id, this.project, run.scenario, run.input, run.output, run.status, run.leaseUntil, run.createdAt, run.error, run.errorCode, run.requestKey, run.inboxRef, run.presentedInput, run.presentedOutput);
+    return inserted !== null;
+  }
+  async find(id) {
+    const row = this.db.query("SELECT * FROM runs WHERE id = ? AND project = ?").get(id, this.project);
+    return row ? fromRow(row) : null;
+  }
+  async findByRequestKey(requestKey) {
+    const row = this.db.query("SELECT * FROM runs WHERE project = ? AND request_key = ?").get(this.project, requestKey);
+    return row ? fromRow(row) : null;
+  }
+  async list() {
+    return this.db.query("SELECT * FROM runs WHERE project = ? ORDER BY created_at DESC").all(this.project).map(fromRow);
+  }
+  async update(id, from, patch) {
+    const entries = Object.entries(patch);
+    if (!entries.length)
+      return true;
+    const assignments = entries.map(([key]) => `${columns[key]} = ?`).join(", ");
+    const result = this.db.query(`UPDATE runs SET ${assignments} WHERE id = ? AND project = ? AND status = ?`).run(...entries.map(([, value]) => value), id, this.project, from);
+    return result.changes === 1;
+  }
+  async expired(now) {
+    return this.db.query("SELECT id FROM runs WHERE project = ? AND lease_until <= ? AND status IN ('ready', 'failed', 'cleanup_failed')").all(this.project, now).map((row) => row.id);
+  }
+  close() {
+    this.db.close();
+  }
+}
+
+// packages/core/src/local.ts
+function localCondition(project, path = ".condition/runs.sqlite", options = {}) {
+  return new Condition(project, new SqliteRunStore(path, project.name), options);
+}
+export {
+  localCondition,
+  SqliteRunStore
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@condition-sh/core",
+  "version": "2026.9.1",
+  "description": "The Condition scenario contract and run engine.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rad-Soft/condition.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://condition.sh",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.js"
+    },
+    "./local": {
+      "types": "./types/local.d.ts",
+      "default": "./local.js"
+    }
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types/extract.d.ts

@@ -0,0 +1,6 @@
+import type { InboxMessage } from "./remote-inbox.js";
+export type ReadMessage = InboxMessage & {
+    links: string[];
+    codes: string[];
+};
+export declare function extract(message: InboxMessage): ReadMessage;

package/types/index.d.ts

@@ -0,0 +1,114 @@
+import type { RunStatus, RunStore, StoredRun } from "./store.js";
+import type { InboxAdapter } from "./remote-inbox.js";
+import { type JsonSchema } from "./schema.js";
+export type { ReadMessage } from "./extract.js";
+export { validateInput } from "./schema.js";
+export type { JsonSchema } from "./schema.js";
+export { RemoteInbox, inboxAddress, inboxAlias, legacyInboxDomain } from "./remote-inbox.js";
+export type { InboxAdapter, InboxMessage } from "./remote-inbox.js";
+export type { RunPatch, RunStatus, RunStore, StoredRun } from "./store.js";
+export type ScenarioContext<Input> = {
+    runId: string;
+    input: Input;
+    inbox?: {
+        address: (actor: string) => string;
+    };
+};
+export type ActorSpec = {
+    name: string;
+    login?: boolean;
+    inbox?: boolean;
+};
+export type Scenario<Input = unknown, Output = unknown> = {
+    description: string;
+    input?: JsonSchema;
+    actors?: ActorSpec[];
+    prepare: (context: ScenarioContext<Input>) => Promise<Output>;
+    verify: (context: ScenarioContext<Input> & {
+        output: Output;
+    }) => Promise<void>;
+    cleanup: (context: ScenarioContext<Input> & {
+        output: Output | null;
+    }) => Promise<void>;
+    login?: (context: ScenarioContext<Input> & {
+        output: Output;
+        actor: string;
+    }) => Promise<unknown>;
+    present?: (output: Output) => unknown;
+    presentInput?: (input: Input) => unknown;
+};
+export type Project = {
+    name: string;
+    scenarios: Record<string, Scenario<any, any>>;
+    inbox?: InboxAdapter;
+};
+export declare function defineProject<T extends Project>(project: T): T;
+export declare function loadProject(path?: string): Promise<Project>;
+export type Run = {
+    id: string;
+    project: string;
+    scenario: string;
+    input: unknown;
+    output: unknown | null;
+    status: RunStatus;
+    leaseUntil: string;
+    createdAt: string;
+    error: string | null;
+    errorCode: string | null;
+    hasInbox: boolean;
+};
+export type ErrorCode = "inbox_unavailable" | "prepare_failed" | "verify_failed" | "runner_unreachable" | "cleanup_failed" | "worker_lost";
+export type ConditionOptions = {
+    now?: () => Date;
+};
+export type ScenarioSummary = {
+    name: string;
+    description: string;
+    input?: JsonSchema;
+    actors?: ActorSpec[];
+};
+export declare function describeProject(project: Project): {
+    project: string;
+    scenarios: ScenarioSummary[];
+};
+export declare function publicRun(run: StoredRun, project: string): Run;
+export declare class Condition {
+    readonly project: Project;
+    private readonly store;
+    private readonly now;
+    constructor(project: Project, store: RunStore, options?: ConditionOptions);
+    describe(): {
+        project: string;
+        scenarios: ScenarioSummary[];
+    };
+    get(id: string): Promise<Run>;
+    list(): Promise<Run[]>;
+    private read;
+    private publicRun;
+    private scenario;
+    private inboxFor;
+    private checkActor;
+    private active;
+    start(name: string, input?: unknown, options?: {
+        leaseMinutes?: number;
+        requestKey?: string;
+    }): Promise<{
+        run: Run;
+        created: boolean;
+    }>;
+    prepare(id: string): Promise<Run>;
+    condition(name: string, input?: unknown, options?: {
+        leaseMinutes?: number;
+        requestKey?: string;
+    }): Promise<Run>;
+    login(id: string, actor: string): Promise<unknown>;
+    inbox(id: string, actor: string): Promise<{
+        messages: import("./extract").ReadMessage[];
+        address: string;
+    }>;
+    claimReset(id: string): Promise<boolean>;
+    finishReset(id: string): Promise<Run>;
+    reset(id: string): Promise<Run>;
+    cleanupExpired(): Promise<Run[]>;
+    close(): void | Promise<void>;
+}

package/types/local.d.ts

@@ -0,0 +1,3 @@
+import { Condition, type ConditionOptions, type Project } from "./index.js";
+export { SqliteRunStore } from "./store.js";
+export declare function localCondition(project: Project, path?: string, options?: ConditionOptions): Condition;

package/types/remote-inbox.d.ts

@@ -0,0 +1,46 @@
+export type InboxMessage = {
+    id: string;
+    sender: string;
+    recipient: string;
+    subject: string;
+    bodyText: string;
+    bodyHtml: string;
+    receivedAt: number;
+};
+export type InboxAdapter = {
+    readonly identity: string;
+    address(runId: string, actor: string): string;
+    reserve(details: {
+        runId: string;
+        project: string;
+        leaseUntil: string;
+    }): Promise<void>;
+    list(runId: string, actor: string): Promise<{
+        address: string;
+        messages: InboxMessage[];
+    }>;
+    release(runId: string): Promise<void>;
+};
+export declare const legacyInboxDomain = "inbox.condition.sh";
+export declare function inboxAlias(runId: string): string;
+export declare function inboxAddress(actor: string, runId: string, domain: string): string;
+export declare class RemoteInbox implements InboxAdapter {
+    private readonly token;
+    readonly domain: string;
+    private readonly tenant?;
+    private readonly base;
+    constructor(url: string, token: string, domain?: string, tenant?: string | undefined);
+    get identity(): string;
+    address(runId: string, actor: string): string;
+    private request;
+    reserve(details: {
+        runId: string;
+        project: string;
+        leaseUntil: string;
+    }): Promise<void>;
+    list(runId: string, actor: string): Promise<{
+        address: string;
+        messages: InboxMessage[];
+    }>;
+    release(runId: string): Promise<void>;
+}

package/types/schema.d.ts

@@ -0,0 +1,15 @@
+export type JsonSchema = {
+    type?: "object" | "string" | "number" | "integer" | "boolean" | "array" | "null";
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    enum?: unknown[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    items?: JsonSchema;
+    default?: unknown;
+};
+export declare function validateInput(schema: JsonSchema, value: unknown): string[];

package/types/store.d.ts

@@ -0,0 +1,38 @@
+export type RunStatus = "preparing" | "ready" | "failed" | "cleaning" | "cleanup_failed" | "released";
+export type StoredRun = {
+    id: string;
+    scenario: string;
+    input: string;
+    output: string | null;
+    status: RunStatus;
+    leaseUntil: string;
+    createdAt: string;
+    error: string | null;
+    errorCode: string | null;
+    requestKey: string | null;
+    inboxRef: string | null;
+    presentedInput: string | null;
+    presentedOutput: string | null;
+};
+export type RunPatch = Partial<Pick<StoredRun, "status" | "output" | "error" | "errorCode" | "presentedInput" | "presentedOutput">>;
+export interface RunStore {
+    insert(run: StoredRun): Promise<boolean>;
+    find(id: string): Promise<StoredRun | null>;
+    findByRequestKey(requestKey: string): Promise<StoredRun | null>;
+    list(): Promise<StoredRun[]>;
+    update(id: string, from: RunStatus, patch: RunPatch): Promise<boolean>;
+    expired(now: string): Promise<string[]>;
+    close(): void | Promise<void>;
+}
+export declare class SqliteRunStore implements RunStore {
+    private readonly project;
+    private readonly db;
+    constructor(databasePath: string, project: string);
+    insert(run: StoredRun): Promise<boolean>;
+    find(id: string): Promise<StoredRun | null>;
+    findByRequestKey(requestKey: string): Promise<StoredRun | null>;
+    list(): Promise<StoredRun[]>;
+    update(id: string, from: RunStatus, patch: RunPatch): Promise<boolean>;
+    expired(now: string): Promise<string[]>;
+    close(): void;
+}