@volter/twin-standard 1.0.149 → 1.0.151

package/src/verdict.ts

@@ -7,7 +7,7 @@
 /** Committed attribution names people or author roles, never execution identities. */
 export function attributionName(name: string | undefined): string | undefined {
   if (name === undefined) return undefined;
-  if (/\bcx-|\bt_[0-9a-f]{8}|wt\/|\/root(?:\/|$|[: )])|\b(?:pane|session)[ -:]|[0-9a-f]{8}-[0-9a-f-]{27}|\b[0-9a-f]{16,64}\b/i.test(name)) throw new Error('attribution must use an author name, not an execution identifier');
+  if (/\bcx-|\bt_[0-9a-f]{8}|wt\/|\/root(?:\/|$|[: )])|\b(?:pane|session)[ :-]|[0-9a-f]{8}-[0-9a-f-]{27}|\b[0-9a-f]{16,64}\b/i.test(name)) throw new Error('attribution must use an author name, not an execution identifier');
   return name;
 }
 export type Verdict = { judge?: { agent?: string; name?: string; session?: string; review?: string }; authors?: string[] };

package/src/walk/behavior-journey.ts

@@ -142,7 +142,7 @@ export type Failure = { step: string; beat: string; detail: string };
  *  reads (an event's delivery, a socket frame), the kernel's own `updatedAt`, which a raw row filtered on `_` alone
  *  carries (Slack's message events once did). The kernel's `deleted` is not read there: vendors send their own
  *  (Stripe's deleted customer's `deleted: true`). */
-function leaked(v: unknown, vendorFields: Set<string>, at = '', unshaped = false): string[] {
+export function leaked(v: unknown, vendorFields: Set<string>, at = '', unshaped = false): string[] {
   if (Array.isArray(v)) return v.flatMap((x, i) => leaked(x, vendorFields, `${at}[${i}]`, unshaped)).slice(0, 5);
   if (!v || typeof v !== 'object') return [];
   return Object.entries(v).flatMap(([k, x]) => ((k.startsWith('_') || (unshaped && k === 'updatedAt')) && !vendorFields.has(k) ? [`${at}${at ? '.' : ''}${k}`] : leaked(x, vendorFields, `${at}${at ? '.' : ''}${k}`, unshaped))).slice(0, 5);
@@ -823,7 +823,11 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
     let res: Answer;
     if (deferred) {
       pending.delete(step.await!);
-      try { res = await deferred.answer; } catch (error) { collect.push({ step: step.name, beat: 'PENDING', detail: String(error) }); continue; }
+      const got = await deferred.answer.then((a) => ({ a }), (error: unknown) => ({ error }));
+      // a body the vendor broke off, as the collect expects (`breaks`): its words are the answer
+      if ('error' in got) { if (step.breaks === undefined || !String(got.error).includes(step.breaks)) collect.push({ step: step.name, beat: 'PENDING', detail: String(got.error) }); continue; }
+      // over a listener, which ends a broken stream as a short body, the ordinary checks hold the part that arrived
+      res = got.a;
     } else res = await send({ ...step, body, headers, ...(formed ? { formed } : {}) }, path);
     answered = { status: res.status, body: res.body, headers: res.headers };
     if (opts.verbose) console.log(`  ${String(res.status).padEnd(4)} ${step.method.padEnd(6)} ${path.slice(0, 70).padEnd(70)} ${step.name}`);

package/src/walk/journey-kit.ts

@@ -52,6 +52,8 @@ export type JourneyStep = {
   defer?: string;
   /** Collect a previously deferred request once, with all ordinary response checks. */
   await?: string;
+  /** A collect whose answer's body breaks off with these words (a stream the vendor ends in an error), not arriving whole. */
+  breaks?: string;
   body?: unknown;
   /** A body of raw bytes (a gzip'd package, an image, an audio file), base64 in the journey and sent decoded: a
    *  string body is sent as UTF-8, which no binary format survives. A step carries `body` or `bodyBase64`, never both. */
@@ -215,7 +217,8 @@ export function expectFailures(expect: NonNullable<JourneyStep['expect']>, body:
     if (e.contains !== undefined) {
       const want = fill(e.contains, captured);
       const text = typeof v === 'string' ? v : JSON.stringify(v ?? '');
-      if (!text.includes(want)) out.push(`${e.path || 'the answer'} does not contain ${JSON.stringify(want)}`);
+      // what it holds instead, its first characters, so a failure says what the twin answered
+      if (!text.includes(want)) out.push(`${e.path || 'the answer'} does not contain ${JSON.stringify(want)} (it begins ${JSON.stringify(text.replace(/\s+/g, ' ').slice(0, 160))})`);
     }
     // `notContains`: the value does not hold the text (a list that omits what the caller may not see)
     if (e.notContains !== undefined) {
@@ -543,7 +546,9 @@ export function fill(template: string, captured: Captured, graphqlDocument = fal
   }
   // a doubled brace is the vendor's own template syntax ({{sample.output_text}} in an OpenAI grader), not a capture; a
   // capture's name starts with a letter, so a pattern's count (`[A-Za-z0-9]{40}` in an expectation) is no capture
-  return encoded.replace(/\{\{[^{}]*\}\}|\{([A-Za-z_][A-Za-z0-9_.]*)\}/g, (m, key: string | undefined, offset: number) => {
+  // `{literal:word}` is `{word}` as the vendor's page prints it (a Redis hash tag, `{queue}`), never a capture
+  return encoded.replace(/\{literal:([^{}]*)\}|\{\{[^{}]*\}\}|\{([A-Za-z_][A-Za-z0-9_.]*)\}/g, (m, literal: string | undefined, key: string | undefined, offset: number) => {
+    if (literal !== undefined) return `{${literal}}`;
     if (selections.has(offset)) return m;
     if (key === undefined) return m;
     const v = captured[key];

package/src/walk/rendered-scalar.ts

@@ -0,0 +1,17 @@
+/** Unfilled scalar type words in schema-rendered examples. Real values and enum words remain literal. */
+const BOOLEAN = Symbol('rendered boolean');
+const INTEGER = Symbol('rendered integer');
+const NUMBER = Symbol('rendered number');
+export function renderedScalar(value: unknown, types: unknown[], enumerated: boolean): symbol | undefined {
+  if (enumerated || typeof value !== 'string') return undefined;
+  if (value === 'boolean' && types.includes('boolean')) return BOOLEAN;
+  if (value === 'integer' && types.includes('integer')) return INTEGER;
+  if (value === 'number' && types.includes('number')) return NUMBER;
+  return undefined;
+}
+export function isRenderedScalar(value: unknown): boolean { return value === BOOLEAN || value === INTEGER || value === NUMBER; }
+export function matchesRenderedScalar(marker: unknown, value: unknown): boolean {
+  if (marker === BOOLEAN) return typeof value === 'boolean';
+  if (marker === INTEGER) return typeof value === 'bigint' || (typeof value === 'number' && Number.isInteger(value));
+  return marker === NUMBER && typeof value === 'number' && Number.isFinite(value);
+}

package/src/walk/sse-example.ts

@@ -1,6 +1,7 @@
 import { parseExactJson } from '@volter/world-core/exact-json';
 /** Match a published SDK-decoded SSE sample to a real HTTP frame; preserve non-SSE answers and mismatches. */
 export function sseExampleAnswer(example: unknown, answer: unknown, matches: (frame: unknown) => boolean): unknown {
+  if (typeof example === 'string' && typeof answer === 'string') return streamSample(example, answer);
   if (typeof answer !== 'string' || !example || typeof example !== 'object') return answer;
   const wrapped = 'data' in example;
   if (!wrapped && !('type' in example) && !('object' in example)) return answer;
@@ -23,3 +24,39 @@ export function sseExampleAnswer(example: unknown, answer: unknown, matches: (fr
   const candidates = relevant.map((frame) => wrapped ? frame : frame.data);
   return candidates.find(matches) ?? candidates[0] ?? answer;
 }
+
+type Frame = { data: unknown; event?: string };
+/** A stream's frames: each block's `event:` and joined `data:` lines, or a block that is JSON alone (a page printing the
+ *  chunks without their framing); `[DONE]`, an elision (`...`, `....`) and anything else not JSON are no frame. */
+function framesOf(text: string): Frame[] {
+  const frames: Frame[] = [];
+  for (const block of text.replace(/\r\n/g, '\n').split(/\n\s*\n/)) {
+    const lines = block.split('\n').map((l) => l.trim()).filter(Boolean);
+    const framed = lines.some((l) => l.startsWith('data:'));
+    const data = framed ? lines.filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).join('\n') : lines.join('\n');
+    if (!data || data === '[DONE]' || /^\.{3,}$/.test(data)) continue;
+    const event = lines.find((l) => l.startsWith('event:'))?.slice(6).trim();
+    try { frames.push({ data: parseExactJson(data), ...(event ? { event } : {}) }); } catch { /* not a JSON frame */ }
+  }
+  return frames;
+}
+const kindOf = (v: unknown): string => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v);
+/** Whether an answer's frame holds a published frame's keys with the same kinds of value (a null published value admits
+ *  any), its type or object the same. */
+function holds(published: unknown, got: unknown): boolean {
+  if (!published || typeof published !== 'object' || Array.isArray(published)) return kindOf(published) === kindOf(got) || published === null;
+  if (!got || typeof got !== 'object' || Array.isArray(got)) return false;
+  const p = published as Record<string, unknown>, g = got as Record<string, unknown>;
+  for (const key of ['type', 'object']) if (typeof p[key] === 'string' && p[key] !== g[key]) return false;
+  return Object.entries(p).every(([k, v]) => k in g && (v === null || kindOf(v) === kindOf(g[k]) || (kindOf(v) === 'object' && holds(v, g[k]))));
+}
+/** A published stream printed as text (a page's sample of a stream, its middle elided): each frame it shows has a frame
+ *  of the answer holding it, the answer then standing for the sample; else the answer, unchanged, which the literal
+ *  comparison reports. */
+function streamSample(example: string, answer: string): unknown {
+  const published = framesOf(example);
+  if (published.length < 2) return answer;
+  const frames = framesOf(answer);
+  const held = published.every((p) => frames.some((f) => (!p.event || p.event === f.event) && holds(p.data, f.data)));
+  return held ? example : answer;
+}