@condition-sh/core 2026.9.2 → 2026.9.3

package/index.js

@@ -98,6 +98,74 @@ function validateInput(schema, value) {
   check(schema, value, "input", errors);
   return errors;
 }
+
+// packages/core/src/traits.ts
+var isList = (values) => Array.isArray(values);
+function describeValues(values) {
+  return isList(values) ? values.join(", ") : `an integer from ${values.minimum} to ${values.maximum}`;
+}
+function accepts(values, value) {
+  if (isList(values))
+    return values.includes(value);
+  return Number.isInteger(value) && value >= values.minimum && value <= values.maximum;
+}
+function requirementProblems(specs, resolved) {
+  const problems = [];
+  for (const [name, value] of Object.entries(resolved)) {
+    for (const [other, allowed] of Object.entries(specs[name].requires?.[String(value)] ?? {})) {
+      if (allowed.includes(resolved[other]))
+        continue;
+      const actual = other in resolved ? `, not "${resolved[other]}"` : "";
+      problems.push(`${name} "${value}" needs ${other} to be one of ${allowed.join(", ")}${actual}`);
+    }
+  }
+  return problems;
+}
+function resolveTraits(specs, requested = {}) {
+  if (requested === null || typeof requested !== "object" || Array.isArray(requested))
+    throw new Error("traits must be an object");
+  const asked = requested;
+  const available = specs ?? {};
+  const problems = [];
+  const resolved = {};
+  for (const name of Object.keys(asked)) {
+    if (!(name in available))
+      problems.push(`unknown trait "${name}"; choose from ${Object.keys(available).join(", ") || "none"}`);
+  }
+  for (const [name, spec] of Object.entries(available)) {
+    const value = name in asked ? asked[name] : spec.default;
+    if (value === undefined)
+      continue;
+    if (accepts(spec.values, value))
+      resolved[name] = value;
+    else
+      problems.push(`${name} can't be ${JSON.stringify(value)}; choose ${describeValues(spec.values)}`);
+  }
+  if (!problems.length)
+    problems.push(...requirementProblems(available, resolved));
+  if (problems.length)
+    throw new Error(`invalid traits: ${problems.join("; ")}`);
+  return resolved;
+}
+function summarizeTraits(specs) {
+  return Object.fromEntries(Object.entries(specs).map(([name, { description, values, default: fallback, requires }]) => [name, {
+    ...description ? { description } : {},
+    values,
+    ...fallback === undefined ? {} : { default: fallback },
+    ...requires ? { requires } : {}
+  }]));
+}
+async function buildState(prepare, specs, context) {
+  let output = await prepare(context);
+  for (const [name, spec] of Object.entries(specs ?? {})) {
+    if (!(name in context.traits))
+      continue;
+    const next = await spec.apply({ ...context, output, value: context.traits[name] });
+    if (next !== undefined)
+      output = next;
+  }
+  return output;
+}
 // packages/core/src/remote-inbox.ts
 import { createHash } from "node:crypto";
 var actorPattern = /^[a-z][a-z0-9-]{0,15}$/;
@@ -203,7 +271,8 @@ function describeProject(project) {
       name,
       description: scenario.description,
       ...scenario.input ? { input: scenario.input } : {},
-      ...scenario.actors ? { actors: scenario.actors } : {}
+      ...scenario.actors ? { actors: scenario.actors } : {},
+      ...scenario.traits ? { traits: summarizeTraits(scenario.traits) } : {}
     }))
   };
 }
@@ -213,6 +282,7 @@ function publicRun(run, project) {
     project,
     scenario: run.scenario,
     input: parse(run.presentedInput),
+    traits: JSON.parse(run.traits),
     output: parse(run.presentedOutput),
     status: run.status,
     leaseUntil: run.leaseUntil,
@@ -273,9 +343,17 @@ class Condition {
   }
   async start(name, input = {}, options = {}) {
     const scenario = this.scenario(name);
-    const problems = scenario.input ? validateInput(scenario.input, input) : [];
+    const inputProblems = scenario.input ? validateInput(scenario.input, input) : [];
+    const problems = inputProblems.length ? [`invalid input: ${inputProblems.join("; ")}`] : [];
+    let traits = {};
+    try {
+      traits = resolveTraits(scenario.traits, options.traits);
+    } catch (error) {
+      problems.push(message(error));
+    }
     if (problems.length)
-      throw new Error(`invalid input: ${problems.join("; ")}`);
+      throw new Error(problems.join("; "));
+    const traitsJson = JSON.stringify(traits);
     const wantsInbox = !scenario.actors || scenario.actors.some((actor) => actor.inbox);
     const minutes = options.leaseMinutes ?? 20;
     if (!Number.isInteger(minutes) || minutes < 1 || minutes > 1440)
@@ -290,6 +368,7 @@ class Condition {
       id: crypto.randomUUID(),
       scenario: name,
       input: inputJson,
+      traits: traitsJson,
       output: null,
       status: "preparing",
       leaseUntil: new Date(now.getTime() + minutes * 60000).toISOString(),
@@ -306,7 +385,7 @@ class Condition {
     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)
+    if (existing.scenario !== name || existing.input !== inputJson || existing.traits !== traitsJson)
       throw new Error("requestKey was used with different input");
     return { run: this.publicRun(existing), created: false };
   }
@@ -316,6 +395,7 @@ class Condition {
       throw new Error(`run ${id} is ${run.status}`);
     const scenario = this.scenario(run.scenario);
     const input = JSON.parse(run.input);
+    const traits = JSON.parse(run.traits);
     const inbox = this.project.inbox;
     let step = "prepare";
     try {
@@ -329,7 +409,7 @@ class Condition {
         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 output = await buildState(scenario.prepare, scenario.traits, { runId: id, input, traits, inbox: this.inboxFor(run) });
       const saved = await this.store.update(id, "preparing", {
         output: JSON.stringify(output ?? null),
         presentedOutput: await presentation(scenario.present, output ?? null)
@@ -337,7 +417,7 @@ class Condition {
       if (!saved)
         throw new Error(`run ${id} changed during preparation`);
       step = "verify";
-      await scenario.verify({ runId: id, input, output, inbox: this.inboxFor(run) });
+      await scenario.verify({ runId: id, input, traits, output, inbox: this.inboxFor(run) });
       if (!await this.store.update(id, "preparing", { status: "ready" }))
         throw new Error(`run ${id} changed during verification`);
     } catch (error) {
@@ -360,7 +440,7 @@ class Condition {
     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) });
+    return scenario.login({ runId: id, input: JSON.parse(run.input), traits: JSON.parse(run.traits), output: parse(run.output), actor, inbox: this.inboxFor(run) });
   }
   async inbox(id, actor) {
     const run = await this.read(id);
@@ -394,7 +474,7 @@ class Condition {
       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) });
+      await scenario.cleanup({ runId: id, input: JSON.parse(run.input), traits: JSON.parse(run.traits), 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`);
@@ -432,6 +512,8 @@ class Condition {
 }
 export {
   validateInput,
+  summarizeTraits,
+  resolveTraits,
   publicRun,
   loadProject,
   legacyInboxDomain,
@@ -439,6 +521,7 @@ export {
   inboxAddress,
   describeProject,
   defineProject,
+  buildState,
   RemoteInbox,
   Condition
 };

package/local.js

@@ -98,6 +98,74 @@ function validateInput(schema, value) {
   check(schema, value, "input", errors);
   return errors;
 }
+
+// packages/core/src/traits.ts
+var isList = (values) => Array.isArray(values);
+function describeValues(values) {
+  return isList(values) ? values.join(", ") : `an integer from ${values.minimum} to ${values.maximum}`;
+}
+function accepts(values, value) {
+  if (isList(values))
+    return values.includes(value);
+  return Number.isInteger(value) && value >= values.minimum && value <= values.maximum;
+}
+function requirementProblems(specs, resolved) {
+  const problems = [];
+  for (const [name, value] of Object.entries(resolved)) {
+    for (const [other, allowed] of Object.entries(specs[name].requires?.[String(value)] ?? {})) {
+      if (allowed.includes(resolved[other]))
+        continue;
+      const actual = other in resolved ? `, not "${resolved[other]}"` : "";
+      problems.push(`${name} "${value}" needs ${other} to be one of ${allowed.join(", ")}${actual}`);
+    }
+  }
+  return problems;
+}
+function resolveTraits(specs, requested = {}) {
+  if (requested === null || typeof requested !== "object" || Array.isArray(requested))
+    throw new Error("traits must be an object");
+  const asked = requested;
+  const available = specs ?? {};
+  const problems = [];
+  const resolved = {};
+  for (const name of Object.keys(asked)) {
+    if (!(name in available))
+      problems.push(`unknown trait "${name}"; choose from ${Object.keys(available).join(", ") || "none"}`);
+  }
+  for (const [name, spec] of Object.entries(available)) {
+    const value = name in asked ? asked[name] : spec.default;
+    if (value === undefined)
+      continue;
+    if (accepts(spec.values, value))
+      resolved[name] = value;
+    else
+      problems.push(`${name} can't be ${JSON.stringify(value)}; choose ${describeValues(spec.values)}`);
+  }
+  if (!problems.length)
+    problems.push(...requirementProblems(available, resolved));
+  if (problems.length)
+    throw new Error(`invalid traits: ${problems.join("; ")}`);
+  return resolved;
+}
+function summarizeTraits(specs) {
+  return Object.fromEntries(Object.entries(specs).map(([name, { description, values, default: fallback, requires }]) => [name, {
+    ...description ? { description } : {},
+    values,
+    ...fallback === undefined ? {} : { default: fallback },
+    ...requires ? { requires } : {}
+  }]));
+}
+async function buildState(prepare, specs, context) {
+  let output = await prepare(context);
+  for (const [name, spec] of Object.entries(specs ?? {})) {
+    if (!(name in context.traits))
+      continue;
+    const next = await spec.apply({ ...context, output, value: context.traits[name] });
+    if (next !== undefined)
+      output = next;
+  }
+  return output;
+}
 // packages/core/src/remote-inbox.ts
 import { createHash } from "node:crypto";
 var actorPattern = /^[a-z][a-z0-9-]{0,15}$/;
@@ -203,7 +271,8 @@ function describeProject(project) {
       name,
       description: scenario.description,
       ...scenario.input ? { input: scenario.input } : {},
-      ...scenario.actors ? { actors: scenario.actors } : {}
+      ...scenario.actors ? { actors: scenario.actors } : {},
+      ...scenario.traits ? { traits: summarizeTraits(scenario.traits) } : {}
     }))
   };
 }
@@ -213,6 +282,7 @@ function publicRun(run, project) {
     project,
     scenario: run.scenario,
     input: parse(run.presentedInput),
+    traits: JSON.parse(run.traits),
     output: parse(run.presentedOutput),
     status: run.status,
     leaseUntil: run.leaseUntil,
@@ -273,9 +343,17 @@ class Condition {
   }
   async start(name, input = {}, options = {}) {
     const scenario = this.scenario(name);
-    const problems = scenario.input ? validateInput(scenario.input, input) : [];
+    const inputProblems = scenario.input ? validateInput(scenario.input, input) : [];
+    const problems = inputProblems.length ? [`invalid input: ${inputProblems.join("; ")}`] : [];
+    let traits = {};
+    try {
+      traits = resolveTraits(scenario.traits, options.traits);
+    } catch (error) {
+      problems.push(message(error));
+    }
     if (problems.length)
-      throw new Error(`invalid input: ${problems.join("; ")}`);
+      throw new Error(problems.join("; "));
+    const traitsJson = JSON.stringify(traits);
     const wantsInbox = !scenario.actors || scenario.actors.some((actor) => actor.inbox);
     const minutes = options.leaseMinutes ?? 20;
     if (!Number.isInteger(minutes) || minutes < 1 || minutes > 1440)
@@ -290,6 +368,7 @@ class Condition {
       id: crypto.randomUUID(),
       scenario: name,
       input: inputJson,
+      traits: traitsJson,
       output: null,
       status: "preparing",
       leaseUntil: new Date(now.getTime() + minutes * 60000).toISOString(),
@@ -306,7 +385,7 @@ class Condition {
     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)
+    if (existing.scenario !== name || existing.input !== inputJson || existing.traits !== traitsJson)
       throw new Error("requestKey was used with different input");
     return { run: this.publicRun(existing), created: false };
   }
@@ -316,6 +395,7 @@ class Condition {
       throw new Error(`run ${id} is ${run.status}`);
     const scenario = this.scenario(run.scenario);
     const input = JSON.parse(run.input);
+    const traits = JSON.parse(run.traits);
     const inbox = this.project.inbox;
     let step = "prepare";
     try {
@@ -329,7 +409,7 @@ class Condition {
         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 output = await buildState(scenario.prepare, scenario.traits, { runId: id, input, traits, inbox: this.inboxFor(run) });
       const saved = await this.store.update(id, "preparing", {
         output: JSON.stringify(output ?? null),
         presentedOutput: await presentation(scenario.present, output ?? null)
@@ -337,7 +417,7 @@ class Condition {
       if (!saved)
         throw new Error(`run ${id} changed during preparation`);
       step = "verify";
-      await scenario.verify({ runId: id, input, output, inbox: this.inboxFor(run) });
+      await scenario.verify({ runId: id, input, traits, output, inbox: this.inboxFor(run) });
       if (!await this.store.update(id, "preparing", { status: "ready" }))
         throw new Error(`run ${id} changed during verification`);
     } catch (error) {
@@ -360,7 +440,7 @@ class Condition {
     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) });
+    return scenario.login({ runId: id, input: JSON.parse(run.input), traits: JSON.parse(run.traits), output: parse(run.output), actor, inbox: this.inboxFor(run) });
   }
   async inbox(id, actor) {
     const run = await this.read(id);
@@ -394,7 +474,7 @@ class Condition {
       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) });
+      await scenario.cleanup({ runId: id, input: JSON.parse(run.input), traits: JSON.parse(run.traits), 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`);
@@ -448,6 +528,7 @@ function fromRow(row) {
     id: row.id,
     scenario: row.scenario,
     input: row.input,
+    traits: row.traits,
     output: row.output,
     status: row.status,
     leaseUntil: row.lease_until,
@@ -476,7 +557,7 @@ class SqliteRunStore {
       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,
+      presented_input TEXT, presented_output TEXT, error_code TEXT, traits TEXT NOT NULL DEFAULT '{}',
       UNIQUE(project, request_key)
     )`);
     const existing = new Set(this.db.query("PRAGMA table_info(runs)").all().map((column) => column.name));
@@ -484,12 +565,14 @@ class SqliteRunStore {
       if (!existing.has(column))
         this.db.exec(`ALTER TABLE runs ADD COLUMN ${column} TEXT`);
     }
+    if (!existing.has("traits"))
+      this.db.exec("ALTER TABLE runs ADD COLUMN traits TEXT NOT NULL DEFAULT '{}'");
     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);
+    const inserted = this.db.query(`INSERT INTO runs (id, project, scenario, input, traits, 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.traits, 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@condition-sh/core",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "description": "The Condition scenario contract and run engine.",
   "type": "module",
   "license": "MIT",

package/types/index.d.ts

@@ -1,15 +1,19 @@
 import type { RunStatus, RunStore, StoredRun } from "./store.js";
 import type { InboxAdapter } from "./remote-inbox.js";
 import { type JsonSchema } from "./schema.js";
+import { type TraitSpec, type TraitSummary, type Traits } from "./traits.js";
 export type { ReadMessage } from "./extract.js";
 export { validateInput } from "./schema.js";
 export type { JsonSchema } from "./schema.js";
+export { resolveTraits, summarizeTraits, buildState } from "./traits.js";
+export type { TraitSpec, TraitSummary, TraitValue, TraitValues, Traits } from "./traits.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;
+    traits: Traits;
     inbox?: {
         address: (actor: string) => string;
     };
@@ -23,6 +27,9 @@ export type Scenario<Input = unknown, Output = unknown> = {
     description: string;
     input?: JsonSchema;
     actors?: ActorSpec[];
+    traits?: Record<string, TraitSpec<ScenarioContext<Input> & {
+        output: Output;
+    }>>;
     prepare: (context: ScenarioContext<Input>) => Promise<Output>;
     verify: (context: ScenarioContext<Input> & {
         output: Output;
@@ -49,6 +56,7 @@ export type Run = {
     project: string;
     scenario: string;
     input: unknown;
+    traits: Traits;
     output: unknown | null;
     status: RunStatus;
     leaseUntil: string;
@@ -61,11 +69,17 @@ export type ErrorCode = "inbox_unavailable" | "prepare_failed" | "verify_failed"
 export type ConditionOptions = {
     now?: () => Date;
 };
+export type StartOptions = {
+    leaseMinutes?: number;
+    requestKey?: string;
+    traits?: Record<string, unknown>;
+};
 export type ScenarioSummary = {
     name: string;
     description: string;
     input?: JsonSchema;
     actors?: ActorSpec[];
+    traits?: Record<string, TraitSummary>;
 };
 export declare function describeProject(project: Project): {
     project: string;
@@ -89,18 +103,12 @@ export declare class Condition {
     private inboxFor;
     private checkActor;
     private active;
-    start(name: string, input?: unknown, options?: {
-        leaseMinutes?: number;
-        requestKey?: string;
-    }): Promise<{
+    start(name: string, input?: unknown, options?: StartOptions): Promise<{
         run: Run;
         created: boolean;
     }>;
     prepare(id: string): Promise<Run>;
-    condition(name: string, input?: unknown, options?: {
-        leaseMinutes?: number;
-        requestKey?: string;
-    }): Promise<Run>;
+    condition(name: string, input?: unknown, options?: StartOptions): Promise<Run>;
     login(id: string, actor: string): Promise<unknown>;
     inbox(id: string, actor: string): Promise<{
         messages: import("./extract").ReadMessage[];

package/types/store.d.ts

@@ -3,6 +3,7 @@ export type StoredRun = {
     id: string;
     scenario: string;
     input: string;
+    traits: string;
     output: string | null;
     status: RunStatus;
     leaseUntil: string;

package/types/traits.d.ts

@@ -0,0 +1,25 @@
+export type TraitValue = string | number;
+export type Traits = Record<string, TraitValue>;
+export type TraitValues = readonly string[] | {
+    type: "integer";
+    minimum: number;
+    maximum: number;
+};
+export type TraitSummary = {
+    description?: string;
+    values: TraitValues;
+    default?: TraitValue;
+    requires?: Record<string, Record<string, readonly TraitValue[]>>;
+};
+export type TraitSpec<Context> = TraitSummary & {
+    apply: (context: Context & {
+        value: TraitValue;
+    }) => Promise<unknown>;
+};
+export declare function resolveTraits(specs: Record<string, TraitSummary> | undefined, requested?: unknown): Traits;
+export declare function summarizeTraits(specs: Record<string, TraitSummary>): Record<string, TraitSummary>;
+export declare function buildState<Context extends {
+    traits: Traits;
+}>(prepare: (context: Context) => Promise<unknown>, specs: Record<string, TraitSpec<Context & {
+    output: unknown;
+}>> | undefined, context: Context): Promise<unknown>;