@worca/app 1.3.0-rc.2 → 1.4.0-rc.1

package/src/shared/graph/agent-meta.mjs

@@ -4,6 +4,7 @@
 // and agent-gen's read-back check. Pure — shared code cannot import
 // claude-runner.mjs, so the mock-role vocabulary is INJECTED.
 import { PORT_TYPES, MAX_PORTS_PER_SIDE, PORT_ID_RE } from './constants.mjs';
+import { normalizeAskBlock } from '../forms/form-def.mjs';
 
 const AGENT_KEY_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 // PORT_ID_RE is P1's, NOT a local copy: spec §3 puts it in constants.mjs
@@ -64,6 +65,21 @@ export function validateMetaV2(raw, opts = {}) {
   return { errors: normalizeAgentMeta(raw, { ...opts, warn: () => {} }).errors };
 }
 
+/** money-saved design §5: `{ factor?: >=0, hours?: >=0 }`; anything else is dropped with a warning. */
+export function readHumanEffort(raw, warn = () => {}) {
+  if (raw === undefined) return null;
+  const ok = (v) => v === undefined || (typeof v === 'number' && Number.isFinite(v) && v >= 0);
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !ok(raw.factor) || !ok(raw.hours)
+      || (raw.factor === undefined && raw.hours === undefined)) {
+    warn(`humanEffort must be { factor?: number >= 0, hours?: number >= 0 }; ignored: ${JSON.stringify(raw)}`);
+    return null;
+  }
+  const out = {};
+  if (raw.factor !== undefined) out.factor = raw.factor;
+  if (raw.hours !== undefined) out.hours = raw.hours;
+  return out;
+}
+
 /**
  * @param {object} raw parsed sidecar
  * @param {{mockWriterRoles?:Set<string>, warn?:(msg:string)=>void}} [opts]
@@ -137,6 +153,19 @@ export function normalizeAgentMeta(raw, opts = {}) {
     else warn(`[agent-registry] ${key || '<unkeyed>'}.mockRole: unknown mock role "${role}"; ignored (the generic mock chain applies)`);
   }
 
+  // Sidecar ask forms (spec §3). Gate 1 lives in the shared forms core; a form
+  // that fails it is DROPPED, never fatal — the agent stays usable with generic
+  // questions (§5). The drop needs its OWN channel to the registry's diagnostics
+  // sink, because `warn`'s last line is how scanMetaLayer names the reason a
+  // WHOLE sidecar was skipped, and a dropped form skips nothing.
+  const askBlock = raw.ask === undefined ? null : normalizeAskBlock(raw.ask);
+  const onDropForm = typeof opts.onDropForm === 'function' ? opts.onDropForm : null;
+  for (const d of askBlock?.dropped || []) {
+    const message = `BAD_ASK_FORM: ${key || '<unkeyed>'}/${d.id}: ${d.reason}`;
+    if (onDropForm) onDropForm({ formId: d.id, reason: d.reason, message });
+    warn(`[agent-registry] ${message}`);
+  }
+
   const asksQuestions = !!raw.asksQuestions;
   const meta = {
     metaVersion: 2,
@@ -167,7 +196,13 @@ export function normalizeAgentMeta(raw, opts = {}) {
   // an absent field means "the default", so a v2 entry stays diffable against
   // the sidecar that produced it.
   if (verdict) meta.verdict = verdict;
+  // Absent when the agent declares no SURVIVING form, so a sidecar without forms
+  // round-trips byte-identically through the store (the fixed key set is what
+  // makes {...existing, ...raw} safe).
+  if (askBlock && Object.keys(askBlock.forms).length) meta.ask = { forms: askBlock.forms };
   if (SIDE_EFFECTS.has(raw.sideEffect)) meta.sideEffect = raw.sideEffect;
+  const humanEffort = readHumanEffort(raw.humanEffort, (m) => warn(`[agent-meta] "${key || '<unkeyed>'}": ${m}`));
+  if (humanEffort) meta.humanEffort = humanEffort;
   if (mockRole) meta.mockRole = mockRole;
   if (raw.wantsRequest) meta.wantsRequest = true;
   if (raw.workspaceFanOut) meta.workspaceFanOut = true;
@@ -177,7 +212,7 @@ export function normalizeAgentMeta(raw, opts = {}) {
   return { errors, meta };
 }
 
-function readVerdict(raw, err) {
+export function readVerdict(raw, err) {
   if (raw === undefined) return null;
   const filename = raw && typeof raw === 'object' && typeof raw.filename === 'string' ? raw.filename.trim() : '';
   if (!filename) { err('verdict must be an object with a filename'); return null; }
@@ -208,7 +243,11 @@ function readPortHead(raw, side, seen, err) {
   return port;
 }
 
-function readInputs(raw, err, warn) {
+/**
+ * @param {{noPromptFields?:boolean}} [opts] scripts: `as`, `directive` and `expands`
+ *  are prompt-side and REFUSED; no default `as` is stamped either.
+ */
+export function readInputs(raw, err, warn, opts = {}) {
   if (!Array.isArray(raw)) { err('inputs must be an array'); return []; }
   if (raw.length > MAX_PORTS_PER_SIDE) err(`inputs: at most ${MAX_PORTS_PER_SIDE} ports per side (got ${raw.length})`);
   const seen = new Set();
@@ -227,6 +266,13 @@ function readInputs(raw, err, warn) {
     }
     port.required = required;
     if (loop) port.loop = true;
+    if (opts.noPromptFields) {
+      for (const field of ['as', 'directive', 'expands']) {
+        if (p[field] !== undefined) err(`inputs.${port.id}: ${field} is a prompt-side field — a script input does not take it`);
+      }
+      out.push(port);
+      continue;
+    }
     if (p.expands) {
       if (port.type !== 'json') err(`inputs.${port.id}: expands is only legal on json inputs`);
       else port.expands = true;
@@ -244,9 +290,13 @@ function readInputs(raw, err, warn) {
   return out;
 }
 
-function readOutputs(raw, hasVerdict, err) {
+/**
+ * @param {{allowEmptyOutputs?:boolean, who?:string}} [opts] scripts may declare zero
+ *  outputs (a pure side effect); `who` names the declarer in the `when` error.
+ */
+export function readOutputs(raw, hasVerdict, err, opts = {}) {
   if (!Array.isArray(raw)) { err('outputs must be an array'); return []; }
-  if (raw.length === 0) err('at least one output port is required');
+  if (raw.length === 0 && !opts.allowEmptyOutputs) err('at least one output port is required');
   if (raw.length > MAX_PORTS_PER_SIDE) err(`outputs: at most ${MAX_PORTS_PER_SIDE} ports per side (got ${raw.length})`);
   const seen = new Set();
   const out = [];
@@ -257,7 +307,7 @@ function readOutputs(raw, hasVerdict, err) {
     if (!OUTPUT_WHEN.has(when)) err(`outputs.${port.id}: when must be one of ${[...OUTPUT_WHEN].join(', ')}`);
     else {
       if (when !== 'always' && !hasVerdict) {
-        err(`outputs.${port.id}: when "${when}" requires the agent to declare verdict: { filename }`);
+        err(`outputs.${port.id}: when "${when}" requires the ${opts.who || 'agent'} to declare verdict: { filename }`);
       }
       port.when = when;
     }

package/src/shared/graph/constants.mjs

@@ -8,12 +8,18 @@
 export const TEMPLATE_VERSION = 2;
 
 /** Every node kind a template may carry (palette order). */
-export const KINDS = Object.freeze(['agent', 'task', 'end', 'and', 'or', 'combine']);
+export const KINDS = Object.freeze(['agent', 'script', 'task', 'end', 'and', 'or', 'combine']);
 
-/** The flow cards: every kind that is not a spawned agent. They are pure engine
+/** The flow cards: every kind that is not a spawned card. They are pure engine
  *  executions — instant, $0, no spawn. */
 export const FLOW_KINDS = Object.freeze(['task', 'end', 'and', 'or', 'combine']);
 
+/** The kinds that carry a registry `key` — a placed sidecar, an agent's or a
+ *  script's. Every consumer that means "a keyed, ported card" tests THIS;
+ *  consumers that mean "spawns Claude" (tunables, the Ports prompt block) keep
+ *  `kind === 'agent'`. A script is not a flow kind: it spawns and it is not free. */
+export const KEYED_KINDS = Object.freeze(['agent', 'script']);
+
 /** The flow cards' DISPLAY names — one label per FLOW_KIND. The single copy:
  *  the run manifest (`manifest.mjs` cell labels), the run monitor and the
  *  New-pipeline loop caption all read this table, so a flow card can never be
@@ -38,6 +44,12 @@ export const DEFAULT_MAX_CYCLES = 3;
  *  sequencing: no file, no renderer, no directive, no mode effect. */
 export const AWAIT_PORT = Object.freeze({ id: 'await', type: 'any', required: false, synthetic: true });
 
+/** The engine-owned `params` input a placed SCRIPT card can opt into (`config.paramsPort`): a json
+ *  wire whose object overlays the card's params before the program runs. Deliberately NOT
+ *  `synthetic` — that flag means "the await gate" to geometry, the manifest and the view — so it
+ *  draws, wires and schedules as an ordinary input; `engine` only marks it as not the script's own. */
+export const PARAMS_PORT = Object.freeze({ id: 'params', type: 'json', required: false, engine: 'params' });
+
 /** Task card — the graph's single source: zero inputs, one always-firing md
  *  output carrying the rendered task md. */
 export const TASK_PORTS = Object.freeze({

package/src/shared/graph/flow-layout.mjs

@@ -9,6 +9,7 @@ import { NODE_W, nodeSize, portAnchor } from './geometry.mjs';
 import { rankNodes } from './layout.mjs';
 import { classifyLoops } from './loops.mjs';
 import { portsOf } from './ports.mjs';
+import { KEYED_KINDS } from './constants.mjs';
 
 export const FLOW_SCALE = 0.65;
 export const FLOW_PAD = 20;            // host padding on X, NOT scaled
@@ -42,7 +43,7 @@ export function flowOrder(tpl, portsFn, { agentOrder = null } = {}) {
     nonLoopIn.set(w.to.node, (nonLoopIn.get(w.to.node) || 0) + 1);
   }
   const given = new Map((Array.isArray(agentOrder) ? agentOrder : []).map((id, i) => [id, i]));
-  const cls = (n) => (n.kind === 'task' ? 0 : n.kind === 'end' ? 3 : (n.kind !== 'agent' && !nonLoopIn.get(n.id) ? 2 : 1));
+  const cls = (n) => (n.kind === 'task' ? 0 : n.kind === 'end' ? 3 : (!KEYED_KINDS.includes(n.kind) && !nonLoopIn.get(n.id) ? 2 : 1));
   const key = (n) => [cls(n), rank[n.id] ?? 0, given.has(n.id) ? given.get(n.id) : Number.MAX_SAFE_INTEGER, n.id];
   return nodes.map((n) => ({ n, k: key(n) })).sort((a, b) => {
     for (let i = 0; i < 4; i += 1) if (a.k[i] !== b.k[i]) return a.k[i] < b.k[i] ? -1 : 1;

package/src/shared/graph/isomorphic.mjs

@@ -4,17 +4,19 @@
 // when agents, wiring, gates, loops and their budgets are identical. Tunables
 // (model/effort/fanOut/askQuestions/subagentModel), positions, ids and names
 // are deliberately invisible — they are per-run tuning, not topology.
-// Pure, browser-safe, no imports.
+// Pure and browser-safe: its one import is the shared constants table.
+import { KEYED_KINDS } from './constants.mjs';
 
 /** The config keys that ARE topology, per kind (mirrors validate.mjs KNOWN_CONFIG minus the tunables). */
 const TOPOLOGY_CONFIG = Object.freeze({
-  task: ['planStoreSeed'], agent: ['awaitAll'], and: ['arity'], or: ['arity'], combine: ['arity'], end: [],
+  task: ['planStoreSeed'], agent: ['awaitAll'], script: ['awaitAll', 'ports', 'params'],
+  and: ['arity'], or: ['arity'], combine: ['arity'], end: [],
 });
 
 export function nodeLabel(node) {
   const kind = String(node?.kind ?? '');
   const cfg = node && typeof node.config === 'object' && node.config ? node.config : {};
-  const parts = [kind, kind === 'agent' ? String(node.key ?? '') : ''];
+  const parts = [kind, KEYED_KINDS.includes(kind) ? String(node.key ?? '') : ''];
   for (const k of TOPOLOGY_CONFIG[kind] || []) {
     const v = cfg[k];
     // A gate's arity defaults to 2; an absent flag equals an explicit false.

package/src/shared/graph/manifest.mjs

@@ -14,7 +14,7 @@
 // agent cell, and the sub_agents.ui_phase attribution column still needs it. The
 // workflows.mjs copy is gone (the v1 topology helpers went with the v1 engine),
 // so THIS is the only copy — shared code may not import workflows.mjs.
-import { TEMPLATE_VERSION, AWAIT_PORT, DEFAULT_MAX_CYCLES, FLOW_LABEL } from './constants.mjs';
+import { TEMPLATE_VERSION, AWAIT_PORT, DEFAULT_MAX_CYCLES, FLOW_LABEL, KEYED_KINDS } from './constants.mjs';
 import { portsFnFor, portsOf, resolveOrOutType } from './ports.mjs';
 import { classifyLoops } from './loops.mjs';
 import { rankNodes } from './layout.mjs';
@@ -89,13 +89,14 @@ const isWire = (w) => Boolean(w) && typeof w === 'object' && !Array.isArray(w)
 /**
  * @param {object} tpl resolved v2 template
  * @param {Record<string,object>} agentsByKey merged registry metas
- * @param {{overlays?:{nodes?:object, wires?:object}}} [opts] effective per-node config + per-wire budgets
+ * @param {{overlays?:{nodes?:object, wires?:object}, scripts?:Record<string,object>}} [opts] effective per-node config + per-wire budgets; the script registry slice
  */
 export function buildGraphManifest(tpl, agentsByKey, opts = {}) {
   const overlays = opts.overlays || {};
+  const scripts = opts.scripts || {};
   const nodeOverlays = overlays.nodes || {};
   const wireOverlays = overlays.wires || {};
-  const portsFn = portsFnFor(agentsByKey);
+  const portsFn = portsFnFor(agentsByKey, scripts);
   // Objects with real endpoints only. `filter(Boolean)` kept a truthy non-object
   // node and an endpoint-less wire, and `w.from.node` threw one map later — the
   // manifest is built from an ALREADY validated template, but it is also built
@@ -109,7 +110,9 @@ export function buildGraphManifest(tpl, agentsByKey, opts = {}) {
 
   const manifestNodes = nodes.map((node) => {
     const resolved = portsOf(portsFn, node);
-    const meta = node.kind === 'agent' ? (agentsByKey?.[node.key] || null) : null;
+    const keyed = KEYED_KINDS.includes(node.kind);
+    const meta = node.kind === 'agent' ? (agentsByKey?.[node.key] || null)
+      : node.kind === 'script' ? (scripts?.[node.key] || null) : null;
     const over = nodeOverlays[node.id] || {};
     const cfg = node.config || {};
     const outType = (port) => (node.kind === 'or' && (!port.type || port.type === 'any')
@@ -117,14 +120,12 @@ export function buildGraphManifest(tpl, agentsByKey, opts = {}) {
     const cell = {
       id: node.id,
       kind: node.kind,
-      key: node.kind === 'agent' ? node.key : null,
+      key: keyed ? node.key : null,
       x: Number(node.x) || 0,
       y: Number(node.y) || 0,
-      label: node.kind === 'agent' ? (meta?.displayName || node.key) : (FLOW_LABEL[node.kind] || node.kind),
-      // The v1 stepper bucket. UI_PHASE knows the 11 builtins; a custom agent
-      // buckets under its own key (the sidecar's `uiPhase` died with the v1
-      // vocabulary). The whole field goes with the phase shim in Task 16.
-      uiPhase: node.kind === 'agent' ? (UI_PHASE[node.key] || node.key) : node.kind,
+      label: keyed ? (meta?.displayName || node.key) : (FLOW_LABEL[node.kind] || node.kind),
+      // The v1 stepper bucket: the builtin map for agents, the bare key for every other keyed card.
+      uiPhase: node.kind === 'agent' ? (UI_PHASE[node.key] || node.key) : keyed ? node.key : node.kind,
       // The AUTHORED config, verbatim and complete (unknown keys included —
       // V17's "preserved and ignored" promise). The manifest is the ONLY
       // persisted copy of the topology: P4 rebuilds the template from it on a
@@ -133,7 +134,8 @@ export function buildGraphManifest(tpl, agentsByKey, opts = {}) {
       config: { ...(node.config || {}) },
       ports: {
         inputs: resolved.inputs.filter((p) => !p.synthetic).map((p) => ({
-          id: p.id, type: p.type, required: p.required !== false, loop: !!p.loop, expands: !!p.expands })),
+          id: p.id, type: p.type, required: p.required !== false, loop: !!p.loop, expands: !!p.expands,
+          ...(p.engine ? { engine: p.engine } : {}) })),
         outputs: resolved.outputs.map((p) => ({ id: p.id, type: outType(p), when: p.when || 'always' })),
         await: resolved.inputs.some((p) => p.synthetic),
       },
@@ -151,6 +153,12 @@ export function buildGraphManifest(tpl, agentsByKey, opts = {}) {
       // alone — the workflow row is never re-read after the run starts.
       cell.subagentModel = over.subagentModel ?? cfg.subagentModel ?? '';
     }
+    if (node.kind === 'script') {
+      cell.color = meta?.color || '';
+      cell.icon = sanitizeIcon(meta?.icon);
+      cell.runtime = meta?.runtime || '';
+      cell.awaitAll = !!(over.awaitAll ?? cfg.awaitAll ?? false);
+    }
     if (node.kind === 'and' || node.kind === 'or' || node.kind === 'combine') {
       cell.arity = Number.isInteger(cfg.arity) ? cfg.arity : 2;
     }
@@ -183,7 +191,7 @@ export function buildGraphManifest(tpl, agentsByKey, opts = {}) {
         uiPhase: n.uiPhase,
         label: n.label,
         color: n.color || '',
-        sub: (n.key && agentsByKey?.[n.key]?.description) || '',
+        sub: (n.key && (agentsByKey?.[n.key] || scripts?.[n.key])?.description) || '',
         cycles: n.ports.inputs.some((p) => p.loop && isWired.has(`${n.id}.${p.id}`)),
         model: n.model || '',
         effort: n.effort || '',
@@ -226,6 +234,7 @@ export function manifestPortsFn(manifest) {
       displayName: cell.label,
       color: cell.color,
       icon: cell.icon,
+      runtime: cell.runtime,
       // A verdict-bearing node is one with a conditional output — enough for V13
       // and firedOutputs; the filename itself never leaves the engine.
       verdict: cell.ports.outputs.some((p) => p.when && p.when !== 'always') ? { filename: '' } : undefined,
@@ -245,7 +254,7 @@ export function manifestTemplate(manifest) {
       // old `{arity, awaitAll}` reconstruction silently dropped everything else
       // (`planStoreSeed` on the Task card of `wf_provided-plan`, for one).
       const node = { id: n.id, kind: n.kind, x: n.x, y: n.y, config: { ...(n.config || {}) } };
-      if (n.kind === 'agent') node.key = n.key;
+      if (KEYED_KINDS.includes(n.kind)) node.key = n.key;
       return node;
     }),
     wires: (manifest?.graph?.wires || []).map((w) => {

package/src/shared/graph/ports.mjs

@@ -5,8 +5,9 @@
 // malformed template — an unknown agent key (V4), a dangling endpoint (V5) or
 // an unknown kind (V3) is an error for the validator to COLLECT, so every
 // lookup guards instead of crashing.
-import { AWAIT_PORT, FLOW_KINDS, gatePorts, TASK_PORTS, END_PORTS } from './constants.mjs';
+import { AWAIT_PORT, PARAMS_PORT, FLOW_KINDS, gatePorts, TASK_PORTS, END_PORTS } from './constants.mjs';
 import { hasBlocking } from './verdict.mjs';
+import { readConfigPorts, hasParamsPort } from './script-meta.mjs';
 
 /** Engine flow-card ports. `undefined` for an unknown kind — V3's error. */
 export function flowPorts(node) {
@@ -22,31 +23,56 @@ export function flowPorts(node) {
   return undefined;
 }
 
+const toIndex = (v) => (v instanceof Map ? v : new Map(Object.entries(v && typeof v === 'object' ? v : {})));
+
 /**
- * Build the ports function over the merged agent registry (an object or a Map
- * keyed by agent key). Agent nodes get their sidecar's typed ports PLUS the
- * engine-synthesized `await` gate appended LAST; flow cards get flowPorts.
- * Three outcomes, and V4 tells them apart:
- *   unknown key            -> undefined            (known:false)
- *   key without v2 ports   -> {known:true, ported:false}
- *   ported v2 sidecar      -> {known:true, ported:true, inputs:[...meta, await]}
+ * Build the ports function over the merged AGENT registry and the merged SCRIPT
+ * registry (objects or Maps keyed by key — the two namespaces never overlap, D16).
+ * Keyed nodes get their sidecar's typed ports PLUS the engine-synthesized `await`
+ * gate appended LAST; flow cards get flowPorts. Outcomes V4 tells apart:
+ *   unknown key                       -> undefined            (known:false)
+ *   agent key without v2 ports        -> {known:true, ported:false}
+ *   config-ported script, no config   -> {known:true, ported:false, configPortsMissing:true}
+ *   config-ported script, bad config  -> {known:true, ported:false, configPortsInvalid:true, configPortsErrors}
+ *   ported                            -> {known:true, ported:true, inputs:[...ports, params?, await], outputs}
  */
-export function portsFnFor(agentsByKey) {
-  const index = agentsByKey instanceof Map
-    ? agentsByKey
-    : new Map(Object.entries(agentsByKey && typeof agentsByKey === 'object' ? agentsByKey : {}));
+export function portsFnFor(agentsByKey, scriptsByKey = {}) {
+  const agents = toIndex(agentsByKey);
+  const scripts = toIndex(scriptsByKey);
   return (node) => {
     if (!node || typeof node !== 'object') return undefined;
-    if (node.kind !== 'agent') return flowPorts(node);
-    const meta = index.get(node.key);
-    if (!meta) return undefined;
-    if (!Array.isArray(meta.inputs) || !Array.isArray(meta.outputs)) {
-      return { ...meta, known: true, ported: false, inputs: [], outputs: [] };
-    }
-    return { ...meta, known: true, ported: true, inputs: [...meta.inputs, AWAIT_PORT], outputs: [...meta.outputs] };
+    if (node.kind === 'agent') return sidecarPorts(agents.get(node.key));
+    if (node.kind === 'script') return scriptPorts(scripts.get(node.key), node);
+    return flowPorts(node);
   };
 }
 
+function sidecarPorts(meta) {
+  if (!meta) return undefined;
+  if (!Array.isArray(meta.inputs) || !Array.isArray(meta.outputs)) {
+    return { ...meta, known: true, ported: false, inputs: [], outputs: [] };
+  }
+  return { ...meta, known: true, ported: true, inputs: [...meta.inputs, AWAIT_PORT], outputs: [...meta.outputs] };
+}
+
+/** A script card's engine inputs, after its own: the opt-in `params` port, then `await` LAST. */
+const engineInputs = (meta, node) => (hasParamsPort(meta, node?.config) ? [PARAMS_PORT, AWAIT_PORT] : [AWAIT_PORT]);
+
+/** Script ports: the sidecar's, or — for `ports: "config"` (D14) — the placed
+ *  node's `config.ports` through the shared readers. */
+function scriptPorts(meta, node) {
+  if (!meta) return undefined;
+  if (meta.ports !== 'config') {
+    const p = sidecarPorts(meta);
+    return p.ported ? { ...p, inputs: [...meta.inputs, ...engineInputs(meta, node)] } : p;
+  }
+  const cfg = node?.config?.ports;
+  if (cfg === undefined) return { ...meta, known: true, ported: false, configPortsMissing: true, inputs: [], outputs: [] };
+  const { ports, errors } = readConfigPorts(cfg, { hasVerdict: !!meta.verdict });
+  if (!ports) return { ...meta, known: true, ported: false, configPortsInvalid: true, configPortsErrors: errors, inputs: [], outputs: [] };
+  return { ...meta, known: true, ported: true, inputs: [...ports.inputs, ...engineInputs(meta, node)], outputs: [...ports.outputs] };
+}
+
 /**
  * Resolve one node's ports defensively. NEVER throws — a portsFn that throws,
  * a missing key and an unknown kind all collapse to `known:false`, and a

package/src/shared/graph/script-cases.mjs

@@ -0,0 +1,257 @@
+// src/shared/graph/script-cases.mjs
+// Saved test cases for a script (workbench spec §3.2). ONE normalizer behind the
+// store's hard 400, the plugin validator and the bench UI, so a case that saves
+// in the app is a case a plugin can ship and `worca script test` can run.
+// Cases live in `<key>.tests.json` beside the script — or, for a built-in or
+// plugin key, in the user layer with no meta beside it (W18: a tests file
+// without a meta is an OVERLAY, never a broken script).
+// Pure: no fs, no node: builtins, no DOM — the Scripts page imports it straight
+// from /src/shared (test/shared-graph-purity.test.mjs).
+import { readConfigPorts, paramValueError, MIN_TIMEOUT_MS } from './script-meta.mjs';
+
+export const CASES_VERSION = 1;
+export const MAX_CASES = 32;
+export const MAX_CASE_NAME = 80;
+export const MAX_CASE_INPUT_BYTES = 262144;        // W9: a case input is inline text
+/** Case ids are key-shaped (dashes and underscores allowed), not port-shaped. */
+export const CASE_ID_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+export const EXPECT_VERDICTS = Object.freeze(['clean', 'blocking', 'error']);
+
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** BYTES, not characters: the cap is a file-size cap (TextEncoder works in both hosts). */
+const byteLength = (s) => new TextEncoder().encode(String(s)).length;
+
+/**
+ * The port set a case runs against: the sidecar's own ports, or — for a
+ * `ports: "config"` script (D14) — the set the case carries, falling back to the
+ * sidecar's `defaultPorts`. The verdict is always the sidecar's.
+ * @param {object} meta a normalized script meta
+ * @param {{ports?: object}} [kase]
+ * @returns {{inputs: Array, outputs: Array, verdict: object|null}|{errors: string[]}}
+ */
+export function casePortSet(meta, kase) {
+  const verdict = meta && meta.verdict ? meta.verdict : null;
+  if (!meta || meta.ports !== 'config') {
+    return {
+      inputs: Array.isArray(meta && meta.inputs) ? meta.inputs : [],
+      outputs: Array.isArray(meta && meta.outputs) ? meta.outputs : [],
+      verdict,
+    };
+  }
+  const raw = kase && kase.ports !== undefined && kase.ports !== null ? kase.ports : meta.defaultPorts;
+  const { ports, errors } = readConfigPorts(raw, { hasVerdict: !!verdict });
+  if (!ports) return { errors };
+  return { inputs: ports.inputs, outputs: ports.outputs, verdict };
+}
+
+/**
+ * Normalize a `<key>.tests.json` document against its script.
+ * @param {object|undefined} raw the parsed file, or undefined (no cases)
+ * @param {object} meta a normalized script meta
+ * @param {{shipped?: boolean, lenient?: boolean}} [opts] shipped: a built-in or plugin
+ *   file — a project cwd cannot travel to another machine, so it is refused there.
+ *   lenient: the READ path. A case outlives an edit to its script's sidecar: a param,
+ *   an input port or an expected output the script NO LONGER declares — or no longer
+ *   declares the same WAY (an enum option dropped, a port retyped) — is skipped
+ *   instead of failing the case — a strict read would drop the whole case, and the
+ *   next write (the page sends the full list it was given) would delete it for good.
+ *   Every other rule still applies; the WRITE path is always strict.
+ * @returns {{cases: Array, errors: string[]}} a case that produced an error is
+ *   NOT returned: the store refuses the whole write, the UI lists the reasons.
+ */
+export function normalizeCases(raw, meta, { shipped = false, lenient = false } = {}) {
+  const errors = [];
+  const cases = [];
+  if (raw === undefined || raw === null) return { cases, errors };
+  if (!isObject(raw)) {
+    errors.push('cases file must be an object { version: 1, cases: [...] }');
+    return { cases, errors };
+  }
+  if (raw.version !== CASES_VERSION) errors.push(`cases file requires version ${CASES_VERSION}`);
+  if (!Array.isArray(raw.cases)) {
+    errors.push('cases must be an array');
+    return { cases, errors };
+  }
+  if (raw.cases.length > MAX_CASES) errors.push(`at most ${MAX_CASES} cases (got ${raw.cases.length})`);
+  const key = typeof (meta && meta.key) === 'string' ? meta.key : '';
+  const declared = new Map((Array.isArray(meta && meta.params) ? meta.params : []).filter(Boolean).map((p) => [p.id, p]));
+  const seen = new Set();
+
+  for (let i = 0; i < raw.cases.length && cases.length < MAX_CASES; i += 1) {
+    const kase = raw.cases[i];
+    if (!isObject(kase)) { errors.push(`cases[${i}]: each case must be an object`); continue; }
+    const id = typeof kase.id === 'string' ? kase.id.trim() : '';
+    if (!CASE_ID_RE.test(id)) { errors.push(`cases[${i}]: bad case id "${id}"`); continue; }
+    if (seen.has(id)) { errors.push(`cases[${i}]: duplicate case id "${id}"`); continue; }
+    seen.add(id);
+    const before = errors.length;
+    const bad = (msg) => errors.push(`case "${id}": ${msg}`);
+
+    let name = id;
+    if (kase.name !== undefined && kase.name !== null) {
+      if (typeof kase.name !== 'string') bad('name must be a string');
+      else if (kase.name.trim().length > MAX_CASE_NAME) bad(`name must be ${MAX_CASE_NAME} characters or fewer`);
+      else name = kase.name.trim() || id;
+    }
+
+    // Ports: a config-ported script carries its own set per case (W5); a
+    // sidecar-ported one must not carry one at all.
+    let ownPorts = null;
+    if (meta && meta.ports === 'config') {
+      if (kase.ports !== undefined && kase.ports !== null && !isObject(kase.ports)) {
+        bad('ports must be an object { inputs: [...], outputs: [...] }');
+      } else if (isObject(kase.ports)) ownPorts = kase.ports;
+    } else if (kase.ports !== undefined && kase.ports !== null && !lenient) {
+      // lenient: the script dropped `ports: "config"` after the case was saved.
+      // The stale set is ignored and the sidecar's own ports stand — dropping the
+      // case here would blank the list, and the page's next write deletes it.
+      bad('ports is only legal for a script that declares ports: "config"');
+    }
+    let set = casePortSet(meta, { ports: ownPorts });
+    // Same rule for a set that no longer validates (a cleared verdict makes a
+    // conditional output illegal): fall back to the script's default port set.
+    if (set.errors && lenient && ownPorts) set = casePortSet(meta, {});
+    if (set.errors) for (const e of set.errors) bad(e);
+    const inPorts = new Map((set.inputs || [])
+      .filter((p) => p && !p.synthetic && p.id !== 'await').map((p) => [p.id, p]));
+    const outIds = new Set((set.outputs || []).map((p) => p && p.id).filter(Boolean));
+
+    const params = {};
+    if (kase.params !== undefined && kase.params !== null) {
+      if (!isObject(kase.params)) bad('params must be an object');
+      else {
+        for (const [pid, value] of Object.entries(kase.params)) {
+          const d = declared.get(pid);
+          if (!d) {
+            if (lenient) continue;
+            bad(`unknown param "${pid}" — script "${key}" declares ${declared.size ? [...declared.keys()].join(', ') : 'no params'}`);
+            continue;
+          }
+          const why = paramValueError(d, value);
+          // lenient: the param is still declared but its SHAPE changed (an enum
+          // option dropped, a type swapped). Skipped like an undeclared one —
+          // dropping the case blanks the list just the same.
+          if (why) { if (!lenient) bad(`param "${pid}" ${why}`); }
+          else params[pid] = value;
+        }
+      }
+    }
+
+    const inputs = {};
+    if (kase.inputs !== undefined && kase.inputs !== null) {
+      if (!isObject(kase.inputs)) bad('inputs must be an object keyed by input port id');
+      else {
+        for (const [pid, spec] of Object.entries(kase.inputs)) {
+          const port = inPorts.get(pid);
+          if (!port) { if (!lenient) bad(`"${pid}" is not an input port of script "${key}"`); continue; }
+          if (!isObject(spec)) { bad(`input "${pid}" must be { text } or { fired: true }`); continue; }
+          // lenient: the port was RETYPED under the stored spec — skipped like a
+          // removed one, because a dropped case is a deleted case one save later.
+          if (port.type === 'void') {
+            if (spec.fired !== true) { if (!lenient) bad(`input "${pid}" is a void port — use { fired: true }`); }
+            else inputs[pid] = { fired: true };
+            continue;
+          }
+          if (typeof spec.text !== 'string') { if (!lenient) bad(`input "${pid}" must be { text }`); continue; }
+          if (byteLength(spec.text) > MAX_CASE_INPUT_BYTES) { bad(`input "${pid}" is over ${MAX_CASE_INPUT_BYTES} bytes`); continue; }
+          if (port.type === 'json') {
+            try { JSON.parse(spec.text); } catch { if (!lenient) bad(`input "${pid}" is not valid JSON`); continue; }
+          }
+          inputs[pid] = { text: spec.text };
+        }
+      }
+    }
+
+    // W1: the scratch folder or a REGISTERED project, never an absolute path —
+    // a case travels between machines inside a plugin.
+    let cwd = { kind: 'scratch' };
+    if (kase.cwd !== undefined && kase.cwd !== null) {
+      if (!isObject(kase.cwd) || (kase.cwd.kind !== 'scratch' && kase.cwd.kind !== 'project')) {
+        bad('cwd must be { kind: "scratch" } or { kind: "project", projectKey }');
+      } else if (kase.cwd.kind === 'project') {
+        const pk = typeof kase.cwd.projectKey === 'string' ? kase.cwd.projectKey.trim() : '';
+        if (!pk) bad('cwd: a project folder needs a projectKey');
+        else if (shipped) bad('a shipped case must run in the scratch folder');
+        else cwd = { kind: 'project', projectKey: pk };
+      }
+    }
+
+    let timeoutMs = null;
+    if (kase.timeoutMs !== undefined && kase.timeoutMs !== null) {
+      if (!Number.isInteger(kase.timeoutMs) || kase.timeoutMs < MIN_TIMEOUT_MS) {
+        bad(`timeoutMs must be an integer >= ${MIN_TIMEOUT_MS}`);
+      } else timeoutMs = kase.timeoutMs;
+    }
+
+    let expect = null;
+    if (kase.expect !== undefined && kase.expect !== null) {
+      if (!isObject(kase.expect)) bad('expect must be an object { verdict?, fired?, summaryIncludes? }');
+      else {
+        const e = {};
+        if (kase.expect.verdict !== undefined) {
+          if (!EXPECT_VERDICTS.includes(kase.expect.verdict)) bad(`expect.verdict must be one of ${EXPECT_VERDICTS.join(', ')}`);
+          else e.verdict = kase.expect.verdict;
+        }
+        if (kase.expect.fired !== undefined) {
+          const list = Array.isArray(kase.expect.fired) && kase.expect.fired.every((x) => typeof x === 'string')
+            ? kase.expect.fired : null;
+          if (!list) bad('expect.fired must be a list of output port ids');
+          else {
+            // lenient: an output the script no longer declares drops out of the expectation.
+            const kept = lenient ? list.filter((x) => outIds.has(x)) : list;
+            const unknown = kept.filter((x) => !outIds.has(x));
+            if (unknown.length) bad(`expect.fired names ${unknown.join(', ')}, which is not an output port`);
+            // An expectation filtered down to NOTHING is dropped, not kept as []: an empty
+            // list is a positive claim ("nothing may fire") the author never made.
+            else if (kept.length || kept.length === list.length) e.fired = [...kept];
+          }
+        }
+        if (kase.expect.summaryIncludes !== undefined) {
+          if (typeof kase.expect.summaryIncludes !== 'string' || !kase.expect.summaryIncludes) {
+            bad('expect.summaryIncludes must be a non-empty string');
+          } else e.summaryIncludes = kase.expect.summaryIncludes;
+        }
+        if (Object.keys(e).length) expect = e;
+      }
+    }
+
+    if (errors.length !== before) continue;
+    cases.push({
+      id,
+      name,
+      params,
+      ports: meta && meta.ports === 'config' ? { inputs: set.inputs, outputs: set.outputs } : null,
+      inputs,
+      cwd,
+      timeoutMs,
+      expect,
+    });
+  }
+  return { cases, errors };
+}
+
+/**
+ * Compare a bench result with a case's expectation (spec §3.2). Absent
+ * expectation -> null: the case reports its result and is never red.
+ * @param {object|null|undefined} expect
+ * @param {{status: string, fired: string[], summary: string}} result
+ * @returns {{pass: boolean, diffs: string[]}|null}
+ */
+export function evaluateExpect(expect, result) {
+  if (!isObject(expect)) return null;
+  const diffs = [];
+  const status = result && typeof result.status === 'string' ? result.status : 'nothing';
+  if (expect.verdict !== undefined && expect.verdict !== status) diffs.push(`expected ${expect.verdict}, got ${status}`);
+  if (Array.isArray(expect.fired)) {
+    const want = [...new Set(expect.fired)].sort();
+    const got = [...new Set(Array.isArray(result && result.fired) ? result.fired : [])].sort();
+    if (want.length !== got.length || want.some((x, n) => x !== got[n])) {
+      diffs.push(`expected fired ${want.join(', ') || '(none)'}, got ${got.join(', ') || '(none)'}`);
+    }
+  }
+  if (typeof expect.summaryIncludes === 'string' && expect.summaryIncludes) {
+    const summary = String((result && result.summary) || '');
+    if (!summary.includes(expect.summaryIncludes)) diffs.push(`expected the summary to contain "${expect.summaryIncludes}"`);
+  }
+  return { pass: diffs.length === 0, diffs };
+}