@roarkanalytics/sdk 3.16.0 → 3.18.0

package/resources/simulation-template.d.mts

@@ -79,6 +79,19 @@ export declare namespace SimulationTemplateListResponse {
          * Stable identifier. Name this in a run request.
          */
         slug: string;
+        /**
+         * Set when this template is a property sweep: it runs ONE flow once per value of a
+         * single caller or environment property, and the report compares the values
+         * against `baseline`.
+         *
+         * This is what decides the size of the run. A sweep attaches the flow once per
+         * entry in `values`, so a plan built from it costs `values.length` times the calls
+         * a normal template would, before iterations. Read it before creating a plan you
+         * have to pay for.
+         *
+         * `null` for every other template.
+         */
+        sweep: Data.Sweep | null;
         /**
          * The Pass/Fail checks this template attaches alongside its metrics.
          */
@@ -154,6 +167,34 @@ export declare namespace SimulationTemplateListResponse {
              */
             slug: string;
         }
+        /**
+         * Set when this template is a property sweep: it runs ONE flow once per value of a
+         * single caller or environment property, and the report compares the values
+         * against `baseline`.
+         *
+         * This is what decides the size of the run. A sweep attaches the flow once per
+         * entry in `values`, so a plan built from it costs `values.length` times the calls
+         * a normal template would, before iterations. Read it before creating a plan you
+         * have to pay for.
+         *
+         * `null` for every other template.
+         */
+        interface Sweep {
+            /**
+             * The value the others are measured against, resolved to what a plan built from
+             * this template will actually record. `null` when the property has no obvious
+             * norm, and the report then compares against the best-performing value instead.
+             */
+            baseline: string | null;
+            /**
+             * The property this template varies across the flow it runs.
+             */
+            property: 'ACCENT' | 'AGE' | 'BACKGROUND_NOISE' | 'BACKGROUND_NOISE_VOLUME' | 'BASE_EMOTION' | 'CONFIRMATION_STYLE' | 'GENDER' | 'INTENT_CLARITY' | 'LANGUAGE' | 'MEMORY_RELIABILITY' | 'RESPONSE_TIMING' | 'SPEECH_CLARITY' | 'SPEECH_PACE';
+            /**
+             * Every value the template sweeps, in the order the plan attaches them.
+             */
+            values: Array<string>;
+        }
         interface Threshold {
             /**
              * Metric definition ID

package/resources/simulation-template.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"simulation-template.d.mts","sourceRoot":"","sources":["../src/resources/simulation-template.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAC/C,OAAO,EAAE,UAAU,EAAE,gCAA4B;AACjD,OAAO,EAAE,cAAc,EAAE,wCAAoC;AAE7D,qBAAa,kBAAmB,SAAQ,WAAW;IACjD;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,8BAA8B,CAAC;CAG3E;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,KAAK,CAAC,8BAA8B,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,yBAAiB,8BAA8B,CAAC;IAC9C;;;OAGG;IACH,UAAiB,IAAI;QACnB;;WAEG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;;;;;;;WAQG;QACH,qBAAqB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAErC;;;WAGG;QACH,mCAAmC,EAAE,MAAM,CAAC;QAE5C;;WAEG;QACH,WAAW,EAAE,MAAM,CAAC;QAEpB;;;;;;WAMG;QACH,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAExB;;;WAGG;QACH,kBAAkB,EAAE,OAAO,CAAC;QAE5B;;WAEG;QACH,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE5B;;WAEG;QACH,IAAI,EAAE,MAAM,CAAC;QAEb;;WAEG;QACH,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAElC;;WAEG;QACH,KAAK,EAAE,MAAM,CAAC;KACf;IAED,UAAiB,IAAI,CAAC;QACpB,UAAiB,IAAI;YACnB;;eAEG;YACH,EAAE,EAAE,MAAM,CAAC;YAEX;;eAEG;YACH,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAEhC;;;eAGG;YACH,SAAS,EAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YAEjC;;;;;;;eAOG;YACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;YAEpB;;eAEG;YACH,KAAK,EAAE,MAAM,CAAC;SACf;QAED,UAAiB,IAAI,CAAC;YACpB,UAAiB,QAAQ;gBACvB;;mBAEG;gBACH,EAAE,EAAE,MAAM,CAAC;gBAEX;;;;;;mBAMG;gBACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEpB;;mBAEG;gBACH,KAAK,EAAE,MAAM,CAAC;aACf;YAED;;;eAGG;YACH,UAAiB,SAAS;gBACxB,KAAK,EAAE,MAAM,CAAC;aACf;SACF;QAED,UAAiB,MAAM;YACrB;;eAEG;YACH,EAAE,EAAE,MAAM,CAAC;YAEX;;eAEG;YACH,IAAI,EAAE,MAAM,CAAC;SACd;QAED,UAAiB,SAAS;YACxB;;eAEG;YACH,EAAE,EAAE,MAAM,CAAC;YAEX;;eAEG;YACH,IAAI,EAAE,MAAM,CAAC;SACd;KACF;CACF;AAED,MAAM,CAAC,OAAO,WAAW,kBAAkB,CAAC;IAC1C,OAAO,EAAE,KAAK,8BAA8B,IAAI,8BAA8B,EAAE,CAAC;CAClF"}
+{"version":3,"file":"simulation-template.d.mts","sourceRoot":"","sources":["../src/resources/simulation-template.ts"],"names":[],"mappings":"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"}

package/resources/simulation-template.d.ts

@@ -79,6 +79,19 @@ export declare namespace SimulationTemplateListResponse {
          * Stable identifier. Name this in a run request.
          */
         slug: string;
+        /**
+         * Set when this template is a property sweep: it runs ONE flow once per value of a
+         * single caller or environment property, and the report compares the values
+         * against `baseline`.
+         *
+         * This is what decides the size of the run. A sweep attaches the flow once per
+         * entry in `values`, so a plan built from it costs `values.length` times the calls
+         * a normal template would, before iterations. Read it before creating a plan you
+         * have to pay for.
+         *
+         * `null` for every other template.
+         */
+        sweep: Data.Sweep | null;
         /**
          * The Pass/Fail checks this template attaches alongside its metrics.
          */
@@ -154,6 +167,34 @@ export declare namespace SimulationTemplateListResponse {
              */
             slug: string;
         }
+        /**
+         * Set when this template is a property sweep: it runs ONE flow once per value of a
+         * single caller or environment property, and the report compares the values
+         * against `baseline`.
+         *
+         * This is what decides the size of the run. A sweep attaches the flow once per
+         * entry in `values`, so a plan built from it costs `values.length` times the calls
+         * a normal template would, before iterations. Read it before creating a plan you
+         * have to pay for.
+         *
+         * `null` for every other template.
+         */
+        interface Sweep {
+            /**
+             * The value the others are measured against, resolved to what a plan built from
+             * this template will actually record. `null` when the property has no obvious
+             * norm, and the report then compares against the best-performing value instead.
+             */
+            baseline: string | null;
+            /**
+             * The property this template varies across the flow it runs.
+             */
+            property: 'ACCENT' | 'AGE' | 'BACKGROUND_NOISE' | 'BACKGROUND_NOISE_VOLUME' | 'BASE_EMOTION' | 'CONFIRMATION_STYLE' | 'GENDER' | 'INTENT_CLARITY' | 'LANGUAGE' | 'MEMORY_RELIABILITY' | 'RESPONSE_TIMING' | 'SPEECH_CLARITY' | 'SPEECH_PACE';
+            /**
+             * Every value the template sweeps, in the order the plan attaches them.
+             */
+            values: Array<string>;
+        }
         interface Threshold {
             /**
              * Metric definition ID

package/resources/simulation-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simulation-template.d.ts","sourceRoot":"","sources":["../src/resources/simulation-template.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,4BAAyB;AAC/C,OAAO,EAAE,UAAU,EAAE,+BAA4B;AACjD,OAAO,EAAE,cAAc,EAAE,uCAAoC;AAE7D,qBAAa,kBAAmB,SAAQ,WAAW;IACjD;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,8BAA8B,CAAC;CAG3E;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,KAAK,CAAC,8BAA8B,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,yBAAiB,8BAA8B,CAAC;IAC9C;;;OAGG;IACH,UAAiB,IAAI;QACnB;;WAEG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;;;;;;;WAQG;QACH,qBAAqB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAErC;;;WAGG;QACH,mCAAmC,EAAE,MAAM,CAAC;QAE5C;;WAEG;QACH,WAAW,EAAE,MAAM,CAAC;QAEpB;;;;;;WAMG;QACH,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAExB;;;WAGG;QACH,kBAAkB,EAAE,OAAO,CAAC;QAE5B;;WAEG;QACH,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE5B;;WAEG;QACH,IAAI,EAAE,MAAM,CAAC;QAEb;;WAEG;QACH,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAElC;;WAEG;QACH,KAAK,EAAE,MAAM,CAAC;KACf;IAED,UAAiB,IAAI,CAAC;QACpB,UAAiB,IAAI;YACnB;;eAEG;YACH,EAAE,EAAE,MAAM,CAAC;YAEX;;eAEG;YACH,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAEhC;;;eAGG;YACH,SAAS,EAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YAEjC;;;;;;;eAOG;YACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;YAEpB;;eAEG;YACH,KAAK,EAAE,MAAM,CAAC;SACf;QAED,UAAiB,IAAI,CAAC;YACpB,UAAiB,QAAQ;gBACvB;;mBAEG;gBACH,EAAE,EAAE,MAAM,CAAC;gBAEX;;;;;;mBAMG;gBACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEpB;;mBAEG;gBACH,KAAK,EAAE,MAAM,CAAC;aACf;YAED;;;eAGG;YACH,UAAiB,SAAS;gBACxB,KAAK,EAAE,MAAM,CAAC;aACf;SACF;QAED,UAAiB,MAAM;YACrB;;eAEG;YACH,EAAE,EAAE,MAAM,CAAC;YAEX;;eAEG;YACH,IAAI,EAAE,MAAM,CAAC;SACd;QAED,UAAiB,SAAS;YACxB;;eAEG;YACH,EAAE,EAAE,MAAM,CAAC;YAEX;;eAEG;YACH,IAAI,EAAE,MAAM,CAAC;SACd;KACF;CACF;AAED,MAAM,CAAC,OAAO,WAAW,kBAAkB,CAAC;IAC1C,OAAO,EAAE,KAAK,8BAA8B,IAAI,8BAA8B,EAAE,CAAC;CAClF"}
+{"version":3,"file":"simulation-template.d.ts","sourceRoot":"","sources":["../src/resources/simulation-template.ts"],"names":[],"mappings":"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"}

package/resources/simulation.d.mts

@@ -139,6 +139,43 @@ export declare namespace SimulationRunParams {
              * `slug`.
              */
             metrics: Array<Plan.Metric>;
+            /**
+             * The value of `comparisonProperty` every other value is measured against, for
+             * example `NONE` for `BACKGROUND_NOISE` or `NORMAL` for `SPEECH_PACE`. Must be a
+             * value that property can take.
+             *
+             * Stored rather than assumed, so the report can say "compared against US accent"
+             * instead of implying Roark decided which value is normal. Most properties have an
+             * obvious baseline and the dashboard prefills it; `GENDER` has none, so choose the
+             * one you are testing against.
+             */
+            comparisonBaseline?: string | null;
+            /**
+             * The property this run plan investigates: the one thing its arms differ by.
+             *
+             * Set it and the run report compares the arms on that property, so a run answers
+             * "what did background noise cost" rather than just "what did each arm score".
+             * Every value is a field already recorded on each call, so the report can label an
+             * arm `CRYING_BABY` rather than repeating a flow variant's title.
+             *
+             * Omit it and the report still compares when it can: it detects which property
+             * varies across the arms. Setting it is what tells the written summary what you
+             * were trying to find out, which detection cannot infer.
+             */
+            comparisonProperty?: 'ACCENT' | 'AGE' | 'BACKGROUND_NOISE' | 'BACKGROUND_NOISE_VOLUME' | 'BASE_EMOTION' | 'CONFIRMATION_STYLE' | 'GENDER' | 'INTENT_CLARITY' | 'LANGUAGE' | 'MEMORY_RELIABILITY' | 'RESPONSE_TIMING' | 'SPEECH_CLARITY' | 'SPEECH_PACE' | null;
+            /**
+             * Which values of `comparisonProperty` to run. This is what the plan costs: the
+             * flow is attached once per value, so ten values is ten times the calls of one.
+             *
+             * Omit it to run every value the property has, which for `ACCENT` is more than
+             * twenty. Send a subset to narrow the sweep, for example three accents you
+             * actually serve. A `comparisonBaseline` outside this set is rejected, because it
+             * would anchor every difference to an arm the run never made.
+             *
+             * Not stored as a field: the arms are the values. Reading the plan back returns
+             * them as its flow attachments.
+             */
+            comparisonValues?: Array<string>;
             /**
              * Description of the run plan
              */
@@ -222,20 +259,6 @@ export declare namespace SimulationRunParams {
              * `flows`, where each variant carries its own persona.
              */
             personas?: Array<Plan.Persona>;
-            /**
-             * Name one flow variant as this run plan's REFERENCE arm.
-             *
-             * Every other flow variant the plan runs is then reported as a difference from
-             * this one, which is how a run answers "what did the change cost" rather than just
-             * "what did it score". The usual shape is one flow whose default variant is the
-             * control (say, a silent environment) plus one edge-case variant per condition
-             * under test.
-             *
-             * The variant must be one this plan actually runs: it has to belong to a flow in
-             * `flows`, and that flow's variant selection has to resolve to it. Omit or set
-             * null for a plan that is a general health check rather than an experiment.
-             */
-            referenceCustomerFlowVariantId?: string | null;
             /**
              * @deprecated Deprecated: use `flows` instead. Scenarios to include in this run
              * plan. The same scenario ID can appear multiple times with different variables.

package/resources/simulation.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"simulation.d.mts","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"simulation.d.mts","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"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"}

package/resources/simulation.d.ts

@@ -139,6 +139,43 @@ export declare namespace SimulationRunParams {
              * `slug`.
              */
             metrics: Array<Plan.Metric>;
+            /**
+             * The value of `comparisonProperty` every other value is measured against, for
+             * example `NONE` for `BACKGROUND_NOISE` or `NORMAL` for `SPEECH_PACE`. Must be a
+             * value that property can take.
+             *
+             * Stored rather than assumed, so the report can say "compared against US accent"
+             * instead of implying Roark decided which value is normal. Most properties have an
+             * obvious baseline and the dashboard prefills it; `GENDER` has none, so choose the
+             * one you are testing against.
+             */
+            comparisonBaseline?: string | null;
+            /**
+             * The property this run plan investigates: the one thing its arms differ by.
+             *
+             * Set it and the run report compares the arms on that property, so a run answers
+             * "what did background noise cost" rather than just "what did each arm score".
+             * Every value is a field already recorded on each call, so the report can label an
+             * arm `CRYING_BABY` rather than repeating a flow variant's title.
+             *
+             * Omit it and the report still compares when it can: it detects which property
+             * varies across the arms. Setting it is what tells the written summary what you
+             * were trying to find out, which detection cannot infer.
+             */
+            comparisonProperty?: 'ACCENT' | 'AGE' | 'BACKGROUND_NOISE' | 'BACKGROUND_NOISE_VOLUME' | 'BASE_EMOTION' | 'CONFIRMATION_STYLE' | 'GENDER' | 'INTENT_CLARITY' | 'LANGUAGE' | 'MEMORY_RELIABILITY' | 'RESPONSE_TIMING' | 'SPEECH_CLARITY' | 'SPEECH_PACE' | null;
+            /**
+             * Which values of `comparisonProperty` to run. This is what the plan costs: the
+             * flow is attached once per value, so ten values is ten times the calls of one.
+             *
+             * Omit it to run every value the property has, which for `ACCENT` is more than
+             * twenty. Send a subset to narrow the sweep, for example three accents you
+             * actually serve. A `comparisonBaseline` outside this set is rejected, because it
+             * would anchor every difference to an arm the run never made.
+             *
+             * Not stored as a field: the arms are the values. Reading the plan back returns
+             * them as its flow attachments.
+             */
+            comparisonValues?: Array<string>;
             /**
              * Description of the run plan
              */
@@ -222,20 +259,6 @@ export declare namespace SimulationRunParams {
              * `flows`, where each variant carries its own persona.
              */
             personas?: Array<Plan.Persona>;
-            /**
-             * Name one flow variant as this run plan's REFERENCE arm.
-             *
-             * Every other flow variant the plan runs is then reported as a difference from
-             * this one, which is how a run answers "what did the change cost" rather than just
-             * "what did it score". The usual shape is one flow whose default variant is the
-             * control (say, a silent environment) plus one edge-case variant per condition
-             * under test.
-             *
-             * The variant must be one this plan actually runs: it has to belong to a flow in
-             * `flows`, and that flow's variant selection has to resolve to it. Omit or set
-             * null for a plan that is a general health check rather than an experiment.
-             */
-            referenceCustomerFlowVariantId?: string | null;
             /**
              * @deprecated Deprecated: use `flows` instead. Scenarios to include in this run
              * plan. The same scenario ID can appear multiple times with different variables.

package/resources/simulation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"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"}

package/src/resources/config.ts

@@ -597,6 +597,8 @@ export interface ConfigFlowStep {
 
   ref?: string;
 
+  requiredForValidRun?: boolean;
+
   silenceDurationSeconds?: number;
 
   steps?: Array<ConfigAPI.ConfigFlowStep>;

package/src/resources/customer-flow.ts

@@ -210,6 +210,16 @@ export class CustomerFlow extends APIResource {
  * replaces the flow-level one at that step. Omit it (or send null) to follow the
  * flow's policy. Use it where one missed step makes the rest of the call
  * meaningless: an authentication menu, say, with `then: HANG_UP_INVALIDATE`.
+ *
+ * Any step may set `requiredForValidRun`, which marks a step the flow requires a
+ * run to reach for its result to count. A run that ends without ever reaching it
+ * is invalidated: it stays in the report, labelled with the step it never reached
+ * and where it stopped, and is left out of the run score and the success-criteria
+ * verdict. Put it on the step where the test itself begins, typically the first
+ * one after an IVR or a login, so an agent that never gets past the menu does not
+ * fail every check in a scenario it never started. A path may have one; a
+ * branching flow may mark one step per branch, and reaching any of them makes the
+ * call valid. A path that marks none behaves exactly as before.
  */
 export type FlowStep =
   | FlowStep.UnionMember0
@@ -237,6 +247,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 
@@ -265,6 +277,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 
@@ -279,6 +293,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 
@@ -293,6 +309,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 
@@ -305,6 +323,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     silenceDurationSeconds?: number | null;
 
     steps?: Array<CustomerFlowAPI.FlowStep>;
@@ -321,6 +341,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 
@@ -335,6 +357,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 
@@ -347,6 +371,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 
@@ -361,6 +387,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 
@@ -377,6 +405,8 @@ export namespace FlowStep {
 
     ref?: string;
 
+    requiredForValidRun?: boolean;
+
     steps?: Array<CustomerFlowAPI.FlowStep>;
   }
 }

package/src/resources/simulation-job.ts

@@ -69,8 +69,10 @@ export namespace SimulationJobGetByIDResponse {
     enrichment: Data.Enrichment;
 
     /**
-     * Present when the run was invalidated: it keeps its transcript and recording, but
-     * nothing scored it and it is excluded from every run total.
+     * Present when the run was invalidated: the call ended before a step its flow
+     * requires for a valid run, or a strict flow went off script at a step whose
+     * policy invalidates the run. It keeps its transcript and recording, but nothing
+     * scored it and it is excluded from every run total.
      */
     invalidation: Data.Invalidation | null;
 
@@ -202,8 +204,10 @@ export namespace SimulationJobGetByIDResponse {
     }
 
     /**
-     * Present when the run was invalidated: it keeps its transcript and recording, but
-     * nothing scored it and it is excluded from every run total.
+     * Present when the run was invalidated: the call ended before a step its flow
+     * requires for a valid run, or a strict flow went off script at a step whose
+     * policy invalidates the run. It keeps its transcript and recording, but nothing
+     * scored it and it is excluded from every run total.
      */
     export interface Invalidation {
       /**
@@ -215,7 +219,7 @@ export namespace SimulationJobGetByIDResponse {
        * Why the result does not count. `SCRIPT_DIVERGED`: a strict flow went off script
        * at a step whose off-script policy is HANG_UP_INVALIDATE.
        */
-      reason: 'SCRIPT_DIVERGED';
+      reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED';
 
       /**
        * One sentence: where the script was left and what your agent did instead.
@@ -514,8 +518,10 @@ export namespace SimulationJobLookupResponse {
     enrichment: Data.Enrichment;
 
     /**
-     * Present when the run was invalidated: it keeps its transcript and recording, but
-     * nothing scored it and it is excluded from every run total.
+     * Present when the run was invalidated: the call ended before a step its flow
+     * requires for a valid run, or a strict flow went off script at a step whose
+     * policy invalidates the run. It keeps its transcript and recording, but nothing
+     * scored it and it is excluded from every run total.
      */
     invalidation: Data.Invalidation | null;
 
@@ -647,8 +653,10 @@ export namespace SimulationJobLookupResponse {
     }
 
     /**
-     * Present when the run was invalidated: it keeps its transcript and recording, but
-     * nothing scored it and it is excluded from every run total.
+     * Present when the run was invalidated: the call ended before a step its flow
+     * requires for a valid run, or a strict flow went off script at a step whose
+     * policy invalidates the run. It keeps its transcript and recording, but nothing
+     * scored it and it is excluded from every run total.
      */
     export interface Invalidation {
       /**
@@ -660,7 +668,7 @@ export namespace SimulationJobLookupResponse {
        * Why the result does not count. `SCRIPT_DIVERGED`: a strict flow went off script
        * at a step whose off-script policy is HANG_UP_INVALIDATE.
        */
-      reason: 'SCRIPT_DIVERGED';
+      reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED';
 
       /**
        * One sentence: where the script was left and what your agent did instead.

package/src/resources/simulation-run-plan-job.ts

@@ -279,8 +279,10 @@ export namespace SimulationRunPlanJobGetByIDResponse {
       createdAt: string;
 
       /**
-       * Present when the run was invalidated: it keeps its transcript and recording, but
-       * nothing scored it and it is excluded from every run total.
+       * Present when the run was invalidated: the call ended before a step its flow
+       * requires for a valid run, or a strict flow went off script at a step whose
+       * policy invalidates the run. It keeps its transcript and recording, but nothing
+       * scored it and it is excluded from every run total.
        */
       invalidation: SimulationJob.Invalidation | null;
 
@@ -382,8 +384,10 @@ export namespace SimulationRunPlanJobGetByIDResponse {
       }
 
       /**
-       * Present when the run was invalidated: it keeps its transcript and recording, but
-       * nothing scored it and it is excluded from every run total.
+       * Present when the run was invalidated: the call ended before a step its flow
+       * requires for a valid run, or a strict flow went off script at a step whose
+       * policy invalidates the run. It keeps its transcript and recording, but nothing
+       * scored it and it is excluded from every run total.
        */
       export interface Invalidation {
         /**
@@ -395,7 +399,7 @@ export namespace SimulationRunPlanJobGetByIDResponse {
          * Why the result does not count. `SCRIPT_DIVERGED`: a strict flow went off script
          * at a step whose off-script policy is HANG_UP_INVALIDATE.
          */
-        reason: 'SCRIPT_DIVERGED';
+        reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED';
 
         /**
          * One sentence: where the script was left and what your agent did instead.
@@ -654,6 +658,9 @@ export namespace SimulationRunPlanJobGetByIDResponse {
       /**
        * Every check the run was judged on, with its rate and the minimum it had to
        * reach.
+       *
+       * Thresholds and authored yes/no metrics only. See `SimulationRunPlanJobCheck` for
+       * why a provider reading is not one.
        */
       checks: Array<Verdict.Check>;
 
@@ -677,6 +684,10 @@ export namespace SimulationRunPlanJobGetByIDResponse {
        * The run's headline quality number, 0-100: the mean of each check's own pass
        * rate.
        *
+       * Every check weighs the same, however many simulations it evaluated, which is the
+       * same way `passed` treats them. It is the number the Roark dashboard shows for
+       * this run.
+       *
        * REPORTING ONLY, for dashboards and trend lines. Nothing is judged against it.
        * Null when nothing was evaluated.
        */
@@ -685,7 +696,14 @@ export namespace SimulationRunPlanJobGetByIDResponse {
 
     export namespace Verdict {
       /**
-       * How one pass/fail metric did. Present for every check, passing or not.
+       * How one check did. Present for every check the run was judged on, passing or
+       * not.
+       *
+       * A check is a metric that yields a pass/fail: a threshold
+       * (`Silence Duration <= 2s`) or a yes/no metric you authored. Provider readings
+       * such as `Comprehension Failure` are observations, not checks: their `true` is
+       * whatever the underlying field happens to mean, so they carry no passing side and
+       * never appear here. Put a threshold on one to judge it.
        */
       export interface Check {
         evaluatedSims: number;