jev-devtools 0.5.4 → 0.5.5

package/lib/src/transport-validation.js

@@ -0,0 +1,45 @@
+export const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const text = (value) => typeof value === "string";
+export const id = (value) => text(value) && value.length > 0;
+export const finite = (value) => typeof value === "number" && Number.isFinite(value);
+export const nonnegative = (value) => finite(value) && value >= 0;
+export const integer = (value) => nonnegative(value) && Number.isSafeInteger(value);
+export const boolean = (value) => typeof value === "boolean";
+export const literal = (...values) => (value) => values.some((candidate) => candidate === value);
+export const optional = (check) => (value) => value === undefined || check(value);
+export const array = (check, max = Infinity) => (value) => Array.isArray(value) && value.length <= max && value.every(check);
+// Every protocol property, including optional ones, needs a compatible check.
+// Extra wire fields are retained for version-1 forward compatibility.
+export function shape(fields) {
+    const checks = fields;
+    return (value) => record(value) &&
+        Object.entries(checks).every(([key, check]) => check(value[key])) &&
+        // Unknown metadata remains visible in Raw, so it must also be safe JSON.
+        Object.entries(value).every(([key, extra]) => Object.hasOwn(checks, key) || json(extra));
+}
+export const strings = array(text);
+export const ids = (value) => array(id, 200)(value) && new Set(value).size === value.length;
+export const status = literal("pending", "success", "error", "cancelled");
+// capture() traverses through depth 12 and emits scalar markers at depth 13.
+// Image previews can exceed the ordinary 16,000-character string limit, so
+// validation does not impose that limit on all strings or invent a byte budget.
+export const json = (value) => {
+    const visit = (input, depth) => {
+        if (input === null || text(input) || boolean(input) || finite(input))
+            return true;
+        if (depth > 12)
+            return false;
+        if (Array.isArray(input))
+            return (input.length <= 150 &&
+                input.every((child) => visit(child, depth + 1)));
+        return (record(input) &&
+            Object.keys(input).length <= 256 &&
+            Object.values(input).every((child) => visit(child, depth + 1)));
+    };
+    return visit(value, 0);
+};
+export function parse(check, value, name) {
+    if (!check(value))
+        throw new Error(`Invalid ${name}`);
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-devtools",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "type": "module",
   "engines": {
     "node": ">=22.12"

package/skills/setup-jev-devtools/SKILL.md

@@ -19,7 +19,7 @@ Inspect the app's package manager/lockfile, React and Node versions, root compon
 
 Install `jev-devtools` using the app's existing package manager (npm: `npm install jev-devtools @typesafe-ai/sdk`; pnpm: `pnpm add jev-devtools @typesafe-ai/sdk`; Yarn: `yarn add jev-devtools @typesafe-ai/sdk`; Bun: `bun add jev-devtools @typesafe-ai/sdk`). `@typesafe-ai/sdk` is a peer dependency: keep the app's existing SDK version when it satisfies the peer range. Install in the workspace(s) that actually import it. It is a regular dependency when application modules import it, even though capture/display are development-only. Do not replace the app's framework or upgrade unrelated dependencies to force compatibility.
 
-### Consumer compatibility (0.5.4)
+### Consumer compatibility (0.5.5)
 
 | Requirement       | Contract                                                                                                                              |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
@@ -35,7 +35,7 @@ Import application APIs from `jev-devtools` (React and browser-safe capture help
 
 ## Optional connected flow API
 
-When asked to build or inspect connected calls, read [references/flows.md](references/flows.md) after the framework recipe. For 0.5.4 it covers requests, server function tasks, runtime request factories, parallel checks, terminal branches, returning conditionals, bounded collections, stateful loops, captured-answer replay, and fixture comparison. It includes sample verification, scope/execution rules, and privacy limits. For an older installation, use its bundled recipe and declarations rather than assuming these operations exist. Preserve existing application policies; do not convert unrelated calls just to install the drawer. Flow execution is server-only and continues even with the inspector disabled.
+When asked to build or inspect connected calls, read [references/flows.md](references/flows.md) after the framework recipe. For 0.5.5 it covers requests, server function tasks, runtime request factories, parallel checks, terminal branches, returning conditionals, bounded collections, stateful loops, captured-answer replay, and fixture comparison. It includes sample verification, scope/execution rules, and privacy limits. For an older installation, use its bundled recipe and declarations rather than assuming these operations exist. Preserve existing application policies; do not convert unrelated calls just to install the drawer. Flow execution is server-only and continues even with the inspector disabled.
 
 ## Integration invariants
 

package/skills/setup-jev-devtools/references/flows.md

@@ -1,6 +1,6 @@
 # Build and inspect a Jev flow
 
-For `jev-devtools` **0.5.4**. Check the [release notes](https://github.com/diegoag64/jev-devtools/releases/tag/v0.5.4) for verified publication status when installing from source. Read the installed package version and `lib/flow/index.d.ts` first; online `main` may describe newer APIs. Use this recipe when the user asks to connect multiple Jev requests, inspect branches, run server function steps, or visualize parallel checks, collections, and loops. Adding the inspector alone does not require converting existing calls to flows.
+For `jev-devtools` **0.5.5**. Check the [release notes](https://github.com/diegoag64/jev-devtools/releases/tag/v0.5.5) for verified publication status when installing from source. Read the installed package version and `lib/flow/index.d.ts` first; online `main` may describe newer APIs. Use this recipe when the user asks to connect multiple Jev requests, inspect branches, run server function steps, or visualize parallel checks, collections, and loops. Adding the inspector alone does not require converting existing calls to flows.
 
 ## Plan the integration
 
@@ -9,7 +9,7 @@ For `jev-devtools` **0.5.4**. Check the [release notes](https://github.com/diego
 3. Import `defineJevFlow` (and `all`, `any`, `not` when needed) from **server-only** `jev-devtools/flow`. Define the graph once at module scope and call `run()` from the existing Node handler/action. In Next.js, mark the module `server-only` and keep the executing route/segment on the Node runtime. No new client provider or root component is needed.
 4. A named output returns data and does not execute an action. Existing business actions can remain in the application after the returned outcome; use `task()` when the user wants application-owned server work included in the flow. Preserve authorization, idempotency, input validation, and error handling. Cancellation cannot undo side effects.
 
-If importing question helpers as below, install `@typesafe-ai/sdk` as a direct dependency in the server workspace using its package manager. Version 0.5.4 requires SDK `>=0.7.0 <0.8.0` and is verified with 0.7.0; preserve a compatible existing version rather than silently changing SDK semantics. The flow also accepts ordinary SDK question objects.
+If importing question helpers as below, install `@typesafe-ai/sdk` as a direct dependency in the server workspace using its package manager. Version 0.5.5 requires SDK `>=0.7.0 <0.8.0` and is verified with 0.7.0; preserve a compatible existing version rather than silently changing SDK semantics. The flow also accepts ordinary SDK question objects.
 
 ## Complete example: parallel checks, one decision, two outcomes
 
@@ -148,6 +148,8 @@ For custom server-derived sessions, use `await inspector.run(request, () => revi
 | `flow.output(name, value?, display?)`                                               | Terminal named result, optionally containing nested resolved expressions. Output names are globally unique node IDs. For metadata without a value, pass `undefined` second.                                          |
 | `definition.run(input, { client, devtools?, signal? })`                             | Returns `{ runId, outcome: string, value?: unknown }`. Narrow/validate values in application code; outcomes are not inferred as a discriminated union. A normal SDK client works without recording.                  |
 
+The bundled declarations reject array methods such as `.get("map")` and non-scalar `.eq()` receivers or operands. Equality supports strings, finite numbers, booleans, and null, including literal and branded types. Scalar unions still need matching resolved types. Array bounds and absent optional fields remain execution checks. Preserve generic field helpers by deriving their key constraint as `K extends keyof T & Parameters<FlowExpression<T>["get"]>[0]`; unrestricted `keyof T` also includes array methods. Older package declarations may accept these invalid operations, so check the installed version.
+
 Use the callback's current builder (`lane` or `path`) to add steps; do not call the outer builder inside it. References must belong to the same definition and be available on the current path. Reusing an earlier parent reference is allowed. IDs must be unique across all paths/lanes: 1–80 letters, digits, `_`, or `-`, starting with a letter or digit. Maximum 256 nodes including collection/iteration templates, 16 nested blocks, and 1,024 expanded steps per run. Version 0.4.0 includes tasks, factories, maps, returning conditionals and loops as described below. Plain templates are copied when defining; treat SDK assets as immutable. Define once to avoid a new definition identity on every request; hot reload can still create a new identity.
 
 **0.5.2:** expressions are bounded during construction to depth 80 (leaf depth 0), 4,096 expanded nodes, and 256 operands per operation. Reusing a child counts its complete size again: eleven `all(e, e)` doublings of Boolean `flow.input` fit (4,095 nodes), but twelve do not. Split larger logic into tasks or smaller steps. Legacy condition descriptions are capped at 4,096 UTF-16 code units including `[condition truncated]`; structured rules keep their 128-node projection budget. Display truncation never changes accepted expression evaluation.

package/skills/setup-jev-devtools/references/verify.md

@@ -7,30 +7,34 @@ Use the host app's typecheck/build commands. Do not run the Jev DevTools monorep
 Use this server-only fixture when live inference is not authorized or no key is configured. It exercises the real SDK and recorder with fixed sample data and no external inference call. Create it from the **same inspector** that serves the endpoints. Keep it visibly sample-only; never substitute it for the user's production inference path.
 
 ```ts
-const sampleJev = inspector.createClient({
-  apiKey: 'sample-only',
-  logLevel: 'off',
-  fetch: async () => Response.json({
-    model: 'jev-sample',
-    answers: {
-      category: {
-        type: 'choice',
-        choice: 'billing',
-        probabilities: { billing: 0.8, other: 0.2 },
-        confidence: 0.7,
-      },
-    },
-  }),
-}, { label: 'Setup verification', source: 'sample' });
+const sampleJev = inspector.createClient(
+  {
+    apiKey: "sample-only",
+    logLevel: "off",
+    fetch: async () =>
+      Response.json({
+        model: "jev-sample",
+        answers: {
+          category: {
+            type: "choice",
+            choice: "billing",
+            probabilities: { billing: 0.8, other: 0.2 },
+            confidence: 0.7,
+          },
+        },
+      }),
+  },
+  { label: "Setup verification", source: "sample" },
+);
 
 async function runSample() {
   return sampleJev.systemOne({
-    state: { message: 'I was charged twice.' },
+    state: { message: "I was charged twice." },
     questions: {
       category: {
-        type: 'choice',
-        instructions: 'Which team should handle this message?',
-        criteria: { billing: 'Payment issues', other: 'Everything else' },
+        type: "choice",
+        instructions: "Which team should handle this message?",
+        criteria: { billing: "Payment issues", other: "Everything else" },
       },
     },
   });
@@ -41,12 +45,14 @@ For a Vite/Connect dev plugin, register a temporary local handler after mounting
 
 ```ts
 server.middlewares.use(async (req, res, next) => {
-  if (req.url !== '/__jev-setup-sample' || req.method !== 'POST') return next();
+  if (req.url !== "/__jev-setup-sample" || req.method !== "POST") return next();
   try {
     await runSample();
-    res.writeHead(200, { 'content-type': 'application/json' }).end('{"ok":true}');
+    res
+      .writeHead(200, { "content-type": "application/json" })
+      .end('{"ok":true}');
   } catch {
-    res.writeHead(500).end('Sample failed');
+    res.writeHead(500).end("Sample failed");
   }
 });
 ```
@@ -66,16 +72,19 @@ Report HTTP/capture checks separately from visual browser checks, and sample ver
 
 ## Troubleshooting
 
-| Symptom | Check |
-| --- | --- |
-| No launcher | Mount once and explicitly enable in development. Styles load automatically; no CSS import is needed. It intentionally renders nothing on the server. |
-| Disconnected or HTML instead of config | Ensure base path **and** subpaths reach the adapter before the SPA fallback; check proxy and Next optional catch-all. |
-| 403 | Match scheme/hostname/port and Host exactly; preserve proxy Host, verify Origin and authorization. Don't disable guards. |
-| Connected but empty | Use the adapter's instrumented client, same adapter/key/process and session. Direct SDK clients are not intercepted. |
-| Clear fails | Browser/server endpoint agreement, same-origin DELETE, exact Origin, authorization and session. |
-| Missing key | SDK needs a server key even with recording off; use the labeled sample transport for offline verification. |
-| Next reload loses or ignores settings | Use a stable `getJevDevtools` key; restart after option changes. Don't dispose during hot reload. |
-| Server import/build errors | Keep `/server` outside client modules. In Next externalize the SDK only. Use a supported Node runtime. |
-| Production 404 | Expected when disabled; app inference remains independent. |
+| Symptom                                | Check                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| No launcher                            | Mount once and explicitly enable in development. Styles load automatically; no CSS import is needed. It intentionally renders nothing on the server.                                                                                                                                                                                                                           |
+| Disconnected or HTML instead of config | Ensure base path **and** subpaths reach the adapter before the SPA fallback; check proxy and Next optional catch-all.                                                                                                                                                                                                                                                          |
+| 403                                    | Match scheme/hostname/port and Host exactly; preserve proxy Host, verify Origin and authorization. Don't disable guards.                                                                                                                                                                                                                                                       |
+| Repeated resynchronization             | Inspect SSE records against the [wire contract](https://github.com/diegoag64/jev-devtools/blob/main/docs/stream-protocol.md#record-validation-and-compatibility). Malformed structural metadata rejects the whole event. Redacted content remains inspectable; use capture warnings to identify unavailable structured views. Restart both server and browser after upgrading. |
+| Connected but empty                    | Use the adapter's instrumented client, same adapter/key/process and session. Direct SDK clients are not intercepted.                                                                                                                                                                                                                                                           |
+| Clear fails                            | Browser/server endpoint agreement, same-origin DELETE, exact Origin, authorization and session.                                                                                                                                                                                                                                                                                |
+| Missing key                            | SDK needs a server key even with recording off; use the labeled sample transport for offline verification.                                                                                                                                                                                                                                                                     |
+| Next reload loses or ignores settings  | Use a stable `getJevDevtools` key; restart after option changes. Don't dispose during hot reload.                                                                                                                                                                                                                                                                              |
+| Server import/build errors             | Keep `/server` outside client modules. In Next externalize the SDK only. Use a supported Node runtime.                                                                                                                                                                                                                                                                         |
+| Production 404                         | Expected when disabled; app inference remains independent.                                                                                                                                                                                                                                                                                                                     |
 
 Capture is bounded to 50 calls in memory by default. Known credential fields are always redacted, including common API-key, client-secret and session-token aliases (case, hyphens and underscores are ignored). HTTP headers/options are not captured. The `redactAdditionalSensitiveData` component prop defaults to `true` and masks supported email, phone, postal address, SSN and card-number fields **only in DevTools views**. Set it to `false` to inspect those fields; changes apply immediately to existing captures, independently in each viewer, without server requests. These personal values remain in server/stream/browser memory even while masked. Custom server redaction always remains active, and neither credentials nor custom-redacted values can be recovered through the prop. See the [exact policy](https://github.com/diegoag64/jev-devtools/blob/main/docs/integration.md#redaction-policy). Arbitrary secrets in prose and unusual field names still need custom redaction. Verify both modes with synthetic sentinels and confirm SDK/runtime values remain unchanged. Diagrams show captured inputs/outputs, not hidden model reasoning. Routing decisions are recorded only for explicitly defined flows; see [flows.md](flows.md) for flow verification.
+
+When configuring a custom redactor, verify replacements that change a field type or the whole request root with synthetic values. The drawer must retain usable siblings beside field-level unavailable placeholders and warnings, retain bounded redacted JSON in `Trace.capture.request` or `Trace.capture.result`, and leave SDK results unchanged. Presence includes `null`; strings such as `[redacted]` remain ordinary content. On the wire, an incompatible request has an empty structured view, and an incompatible response omits `Trace.result`. The drawer can display usable fields from `Trace.capture`; it must not invent values or box overlays from redacted coordinates. Fixture export reports that response as missing and keeps its warnings.