@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/aic/callbacks.d.ts

@@ -0,0 +1,35 @@
+import type { CallbackEffect, JsonValue } from "../case/types.ts";
+export interface AuthenticateCallbacks {
+    /** JSON payload from the result node's HiddenValueCallback, if present. */
+    dumpRaw: string | undefined;
+    /** Subject-node callbacks; harness dump stripped. */
+    callbacks: CallbackEffect[];
+}
+/**
+ * Read `/authenticate` callbacks. `type` is taken from the HTTP field as-is
+ * (the effects-contract spelling: Java simple class name, PascalCase).
+ * Other fields are the callback's `output` name/value pairs, so a NameCallback
+ * becomes `{ type: "NameCallback", prompt: "User Name" }` — no `input` (that
+ * is the client's reply, not the effect).
+ */
+export declare function parseAuthenticateCallbacks(body: unknown): AuthenticateCallbacks;
+/**
+ * Build the body that answers a pass's callbacks.
+ *
+ * AM wants the whole `/authenticate` response back with each callback's
+ * `input` slot filled, so the response is cloned and edited rather than
+ * rebuilt — `authId` and every field the harness does not understand survive
+ * untouched. Replies are matched to callbacks by type, in order, exactly as
+ * the local lane's `submittedCallbacks` matches them; a reply the pass never
+ * asked for is refused rather than dropped, because a chain that silently
+ * ignores a reply is a test asserting something it never sent.
+ *
+ * Callbacks with no reply keep whatever AM put in their input slot. That is
+ * the tenant's own default, which is the one case where a default is not a
+ * guess (an unanswered HiddenValueCallback comes back holding its `id`,
+ * measured 2026-09-14).
+ */
+export declare function fillCallbackInputs(body: unknown, replies: readonly {
+    type: string;
+    value: JsonValue;
+}[], label: string): string;

package/dist/src/aic/callbacks.js

@@ -0,0 +1,130 @@
+import { isPlainObject, parseJsonValue } from "../case/util.js";
+import { HARNESS_CALLBACK_ID } from "./constants.js";
+/**
+ * Read `/authenticate` callbacks. `type` is taken from the HTTP field as-is
+ * (the effects-contract spelling: Java simple class name, PascalCase).
+ * Other fields are the callback's `output` name/value pairs, so a NameCallback
+ * becomes `{ type: "NameCallback", prompt: "User Name" }` — no `input` (that
+ * is the client's reply, not the effect).
+ */
+export function parseAuthenticateCallbacks(body) {
+    if (!isPlainObject(body)) {
+        throw new Error("rhino-local: authenticate body is not an object");
+    }
+    const rawCallbacks = body.callbacks;
+    if (rawCallbacks === undefined) {
+        return { dumpRaw: undefined, callbacks: [] };
+    }
+    if (!Array.isArray(rawCallbacks)) {
+        throw new Error("rhino-local: authenticate.callbacks is not an array");
+    }
+    let dumpRaw;
+    const callbacks = [];
+    for (let index = 0; index < rawCallbacks.length; index += 1) {
+        const parsed = parseOneCallback(rawCallbacks[index], `callbacks[${index}]`);
+        if (parsed.harnessValue !== undefined) {
+            dumpRaw = parsed.harnessValue;
+            continue;
+        }
+        callbacks.push(parsed.effect);
+    }
+    return { dumpRaw, callbacks };
+}
+function parseOneCallback(raw, path) {
+    if (!isPlainObject(raw)) {
+        throw new Error(`rhino-local: ${path} is not an object`);
+    }
+    if (typeof raw.type !== "string" || raw.type.trim() === "") {
+        throw new Error(`rhino-local: ${path}.type must be a non-empty string`);
+    }
+    const effect = { type: raw.type };
+    const output = raw.output;
+    let id;
+    let value;
+    if (output !== undefined) {
+        if (!Array.isArray(output)) {
+            throw new Error(`rhino-local: ${path}.output is not an array`);
+        }
+        for (let index = 0; index < output.length; index += 1) {
+            const item = output[index];
+            if (!isPlainObject(item) || typeof item.name !== "string") {
+                continue;
+            }
+            if (item.name === "_id") {
+                continue;
+            }
+            const parsed = parseJsonValue(item.value ?? null, `${path}.output[${index}].value`);
+            if (item.name === "id") {
+                id = typeof parsed === "string" ? parsed : String(parsed);
+                effect.id = id;
+                continue;
+            }
+            if (item.name === "value") {
+                value = parsed;
+            }
+            effect[item.name] = parsed;
+        }
+    }
+    if (raw.type === "HiddenValueCallback" && id === HARNESS_CALLBACK_ID) {
+        if (typeof value !== "string") {
+            throw new Error(`rhino-local: harness HiddenValueCallback value must be a string, got ${typeof value}`);
+        }
+        return { effect, harnessValue: value };
+    }
+    return { effect };
+}
+/**
+ * Build the body that answers a pass's callbacks.
+ *
+ * AM wants the whole `/authenticate` response back with each callback's
+ * `input` slot filled, so the response is cloned and edited rather than
+ * rebuilt — `authId` and every field the harness does not understand survive
+ * untouched. Replies are matched to callbacks by type, in order, exactly as
+ * the local lane's `submittedCallbacks` matches them; a reply the pass never
+ * asked for is refused rather than dropped, because a chain that silently
+ * ignores a reply is a test asserting something it never sent.
+ *
+ * Callbacks with no reply keep whatever AM put in their input slot. That is
+ * the tenant's own default, which is the one case where a default is not a
+ * guess (an unanswered HiddenValueCallback comes back holding its `id`,
+ * measured 2026-09-14).
+ */
+export function fillCallbackInputs(body, replies, label) {
+    if (!isPlainObject(body)) {
+        throw new Error(`rhino-local: ${label}: authenticate body is not an object`);
+    }
+    const clone = JSON.parse(JSON.stringify(body));
+    const rawCallbacks = Array.isArray(clone.callbacks) ? clone.callbacks : [];
+    const pending = new Map();
+    for (const reply of replies) {
+        const queue = pending.get(reply.type);
+        if (queue === undefined) {
+            pending.set(reply.type, [reply.value]);
+        }
+        else {
+            queue.push(reply.value);
+        }
+    }
+    for (const raw of rawCallbacks) {
+        if (!isPlainObject(raw) || typeof raw.type !== "string") {
+            continue;
+        }
+        const queue = pending.get(raw.type);
+        if (queue === undefined || queue.length === 0) {
+            continue;
+        }
+        const input = raw.input;
+        if (!Array.isArray(input) || input.length === 0 || !isPlainObject(input[0])) {
+            throw new Error(`rhino-local: ${label}: cannot answer a ${raw.type} — it has no input slot`);
+        }
+        input[0].value = queue.shift();
+    }
+    const leftover = [...pending.entries()].filter(([, queue]) => queue.length > 0);
+    if (leftover.length > 0) {
+        const detail = leftover
+            .map(([type, queue]) => `${queue.length} unused ${type}`)
+            .join("; ");
+        throw new Error(`rhino-local: ${label} replied to callbacks the pass did not send — ${detail}`);
+    }
+    return JSON.stringify(clone);
+}

package/dist/src/aic/conform.d.ts

@@ -0,0 +1,90 @@
+import type { Case, JsonObject, RecordedEffects, Verdict } from "../case/types.ts";
+import type { RunResult } from "../harness/lease.ts";
+import { type EffectsDisagreement, type ObservationGap } from "./diff.ts";
+import { type ManagedFixture } from "./managed.ts";
+import { type AicReply } from "./run.ts";
+export type LaneRunner = (args: {
+    kase: Case;
+    source: string;
+}) => Promise<RecordedEffects>;
+export interface ConformanceInput {
+    kase: Case;
+    source: string;
+    local?: LaneRunner;
+    /** Omit to skip; pass a runner, or `"tenant"` to use `runAicLane`. */
+    aic?: LaneRunner | "tenant";
+}
+export interface LaneResult {
+    effects?: RecordedEffects;
+    verdict?: Verdict;
+    skipped?: string;
+    error?: string;
+}
+export interface ConformanceReport {
+    name: string;
+    portable: boolean;
+    local: LaneResult;
+    aic: LaneResult;
+    disagreements: EffectsDisagreement[];
+    observationGaps: ObservationGap[];
+    ambientState: Array<{
+        lane: "local" | "aic";
+        values: JsonObject;
+    }>;
+}
+/** The local lane's completed chain, ready to be checked by the AIC lane. */
+export interface LocalChainResult {
+    cases: readonly Case[];
+    localEffects: readonly RecordedEffects[];
+    replies: readonly (readonly AicReply[])[];
+    /** Present only when the local result came through the lease fixture ledger. */
+    managedFixtures?: readonly ManagedFixture[];
+}
+export type AicChainRunner = (args: {
+    cases: readonly Case[];
+    source: string;
+    replies: readonly (readonly AicReply[])[];
+    managedFixtures?: readonly ManagedFixture[];
+}) => Promise<readonly RecordedEffects[]>;
+export interface ChainConformanceInput extends LocalChainResult {
+    source: string;
+    /** Omit to skip; pass a runner, or `"tenant"` to use `runAicChain`. */
+    aic?: AicChainRunner | "tenant";
+}
+export interface ChainPassReport extends ConformanceReport {
+    /** 1-based position in the chain. */
+    pass: number;
+    final: boolean;
+    /** False when the pass suspended before the wrapper could dump its effects. */
+    aicObserved: boolean;
+}
+export interface ChainConformanceReport {
+    name: string;
+    portable: boolean;
+    passes: ChainPassReport[];
+    disagreements: EffectsDisagreement[];
+    observationGaps: ObservationGap[];
+}
+/**
+ * Run one case on both lanes and diff the two `RecordedEffects`.
+ * Both lanes are judged by `judge()` from verdict.ts — a second pass/fail
+ * implementation here would make the comparison prove nothing.
+ *
+ * Either lane may be omitted. A missing local runner is the expected state
+ * until the bindings slice lands; a missing AIC runner is used by tests.
+ */
+export declare function conform(input: ConformanceInput): Promise<ConformanceReport>;
+/**
+ * Check an already-completed local chain against one AIC journey.
+ *
+ * The caller supplies every carried case and reply. This function deliberately
+ * cannot compute either: making the AIC lane repeat the local carry rule would
+ * hide a wrong mock when both lanes made the same guess.
+ */
+export declare function conformChain(input: ChainConformanceInput): Promise<ChainConformanceReport>;
+/**
+ * Convert `Lease.execute()` output without re-running or reconstructing it.
+ * External one-shot callers may use this too; `useLease()` sends it to the
+ * file's already-open `AicFileLease`, not to `runAicChain()`.
+ */
+export declare function chainFromRunResult(result: RunResult): LocalChainResult;

package/dist/src/aic/conform.js

@@ -0,0 +1,193 @@
+import { isPortable } from "../case/portable.js";
+import { diffRecordedEffects, } from "./diff.js";
+import { judge } from "../case/verdict.js";
+import { managedSeedMatches } from "./managed.js";
+import { runAicChain, runAicLane } from "./run.js";
+import { aicUnsupportedReason } from "./unsupported.js";
+/**
+ * Run one case on both lanes and diff the two `RecordedEffects`.
+ * Both lanes are judged by `judge()` from verdict.ts — a second pass/fail
+ * implementation here would make the comparison prove nothing.
+ *
+ * Either lane may be omitted. A missing local runner is the expected state
+ * until the bindings slice lands; a missing AIC runner is used by tests.
+ */
+export async function conform(input) {
+    const local = await runLane(input.local, input, "no local runner provided (bindings lane is a separate slice)");
+    const aicSkip = aicUnsupportedReason(input.kase);
+    const aicRunner = input.aic === "tenant" ? tenantRunner : input.aic;
+    const aic = aicSkip
+        ? skipResult(aicSkip)
+        : await runLane(aicRunner, input, "no AIC runner provided");
+    const comparison = local.effects !== undefined && aic.effects !== undefined
+        ? diffRecordedEffects(local.effects, aic.effects)
+        : { disagreements: [], observationGaps: [] };
+    return {
+        name: input.kase.name,
+        portable: isPortable(input.kase),
+        local,
+        aic,
+        disagreements: comparison.disagreements,
+        observationGaps: comparison.observationGaps,
+        ambientState: collectAmbient(local, aic),
+    };
+}
+/**
+ * Check an already-completed local chain against one AIC journey.
+ *
+ * The caller supplies every carried case and reply. This function deliberately
+ * cannot compute either: making the AIC lane repeat the local carry rule would
+ * hide a wrong mock when both lanes made the same guess.
+ */
+export async function conformChain(input) {
+    validateChainInput(input);
+    const local = input.cases.map((kase, index) => observedResult(kase, input.localEffects[index]));
+    const harnessOwnsManaged = input.managedFixtures !== undefined &&
+        managedSeedMatches(input.cases[0].given.managed, input.managedFixtures);
+    const unsupported = input.cases.flatMap((kase) => {
+        const reason = aicUnsupportedReason(kase, { harnessOwnsManaged });
+        return reason === undefined ? [] : [`${kase.name}: ${reason}`];
+    });
+    const aicRunner = input.aic === "tenant" ? tenantChainRunner : input.aic;
+    let aic;
+    if (unsupported.length > 0) {
+        aic = input.cases.map(() => skipResult(`AIC lane skipped for the whole chain: ${unsupported.join("; ")}`));
+    }
+    else if (aicRunner === undefined) {
+        aic = input.cases.map(() => skipResult("no AIC chain runner provided"));
+    }
+    else {
+        aic = await runChainLane(aicRunner, input);
+    }
+    const finalIndex = input.cases.length - 1;
+    const passes = input.cases.map((kase, index) => {
+        const isFinal = index === finalIndex;
+        return chainPassReport(kase, index, isFinal, local[index], aic[index]);
+    });
+    return {
+        name: input.cases[finalIndex].name,
+        portable: input.cases.every(isPortable),
+        passes,
+        disagreements: passes.flatMap((pass) => pass.disagreements),
+        observationGaps: passes.flatMap((pass) => pass.observationGaps),
+    };
+}
+/**
+ * Convert `Lease.execute()` output without re-running or reconstructing it.
+ * External one-shot callers may use this too; `useLease()` sends it to the
+ * file's already-open `AicFileLease`, not to `runAicChain()`.
+ */
+export function chainFromRunResult(result) {
+    return {
+        cases: [...result.steps.map((step) => step.kase), result.kase],
+        localEffects: [...result.steps.map((step) => step.effects), result.effects],
+        replies: result.steps.map((step) => submittedToAicReplies(step.submitted)),
+        managedFixtures: result.fixtures,
+    };
+}
+function submittedToAicReplies(submitted) {
+    const replies = [];
+    for (const callback of submitted) {
+        const value = callback.value;
+        if (Object.prototype.hasOwnProperty.call(callback, "value") && value !== undefined) {
+            replies.push({ type: callback.type, value });
+        }
+    }
+    return replies;
+}
+function validateChainInput(input) {
+    if (input.cases.length === 0) {
+        throw new Error("conformChain needs at least one case");
+    }
+    if (input.localEffects.length !== input.cases.length) {
+        throw new Error(`conformChain: ${input.cases.length} cases need ${input.cases.length} local effects, got ${input.localEffects.length}`);
+    }
+    if (input.replies.length !== input.cases.length - 1) {
+        throw new Error(`conformChain: ${input.cases.length} passes need ${input.cases.length - 1} reply sets, got ${input.replies.length}`);
+    }
+}
+async function runChainLane(runner, input) {
+    try {
+        const effects = await runner({
+            cases: input.cases,
+            source: input.source,
+            replies: input.replies,
+            ...(input.managedFixtures !== undefined
+                ? { managedFixtures: input.managedFixtures }
+                : {}),
+        });
+        if (effects.length !== input.cases.length) {
+            throw new Error(`AIC chain runner returned ${effects.length} effects for ${input.cases.length} passes`);
+        }
+        return input.cases.map((kase, index) => observedResult(kase, effects[index]));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return input.cases.map(() => ({ error: message }));
+    }
+}
+function observedResult(kase, effects) {
+    return { effects, verdict: judge(kase, effects) };
+}
+function chainPassReport(kase, index, final, local, aic) {
+    const comparison = final && local.effects !== undefined && aic.effects !== undefined
+        ? diffRecordedEffects(local.effects, aic.effects)
+        : { disagreements: [], observationGaps: [] };
+    if (!final && aic.effects !== undefined) {
+        comparison.observationGaps.push(intermediatePassGap(kase));
+    }
+    return {
+        pass: index + 1,
+        final,
+        aicObserved: final && aic.effects !== undefined,
+        name: kase.name,
+        portable: isPortable(kase),
+        local,
+        aic,
+        disagreements: comparison.disagreements,
+        observationGaps: comparison.observationGaps,
+        ambientState: collectAmbient(local, aic),
+    };
+}
+function intermediatePassGap(kase) {
+    return {
+        channel: "nodeState",
+        path: "pass",
+        local: "observed",
+        aic: "unobserved",
+        message: `${kase.name}: intermediate AIC effects are unobserved because the wrapper cannot dump state without adding a script-visible callback`,
+    };
+}
+function collectAmbient(local, aic) {
+    const ambient = [];
+    for (const [lane, result] of [
+        ["local", local],
+        ["aic", aic],
+    ]) {
+        const values = result.effects?.evidence?.ambientState;
+        if (values !== undefined && Object.keys(values).length > 0) {
+            ambient.push({ lane, values });
+        }
+    }
+    return ambient;
+}
+async function runLane(runner, input, missing) {
+    if (runner === undefined) {
+        return skipResult(missing);
+    }
+    try {
+        const effects = await runner({ kase: input.kase, source: input.source });
+        return { effects, verdict: judge(input.kase, effects) };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function skipResult(reason) {
+    return { skipped: reason };
+}
+const tenantRunner = ({ kase, source }) => runAicLane(kase, source);
+const tenantChainRunner = ({ cases, source, replies, managedFixtures, }) => runAicChain(cases, source, {
+    replies,
+    ...(managedFixtures !== undefined ? { managedFixtures } : {}),
+});

package/dist/src/aic/constants.d.ts

@@ -0,0 +1,13 @@
+/** Built-in Success node. Same id on every AM tenant (`docs/api/09-journeys.md`). */
+export declare const SUCCESS_NODE_ID = "70e691a5-1e33-4ac3-a356-e7b6d60d92e0";
+/** Built-in Failure node. Same id on every AM tenant (`docs/api/09-journeys.md`). */
+export declare const FAILURE_NODE_ID = "e301438c-0bd0-429c-ab0c-66126501069a";
+/**
+ * HiddenValueCallback `id` the result script writes. The AIC runner reads
+ * this callback back from `/authenticate` and strips it from `effects.callbacks`
+ * so the harness dump is not mistaken for a subject-node callback.
+ */
+export declare const HARNESS_CALLBACK_ID = "__rhinoLocalEffects";
+/** Prefix for throwaway tree and script names. Distinct from operator config. */
+export declare const RESOURCE_PREFIX = "rl-aic";
+export declare const SETUP_OUTCOME = "true";

package/dist/src/aic/constants.js

@@ -0,0 +1,13 @@
+/** Built-in Success node. Same id on every AM tenant (`docs/api/09-journeys.md`). */
+export const SUCCESS_NODE_ID = "70e691a5-1e33-4ac3-a356-e7b6d60d92e0";
+/** Built-in Failure node. Same id on every AM tenant (`docs/api/09-journeys.md`). */
+export const FAILURE_NODE_ID = "e301438c-0bd0-429c-ab0c-66126501069a";
+/**
+ * HiddenValueCallback `id` the result script writes. The AIC runner reads
+ * this callback back from `/authenticate` and strips it from `effects.callbacks`
+ * so the harness dump is not mistaken for a subject-node callback.
+ */
+export const HARNESS_CALLBACK_ID = "__rhinoLocalEffects";
+/** Prefix for throwaway tree and script names. Distinct from operator config. */
+export const RESOURCE_PREFIX = "rl-aic";
+export const SETUP_OUTCOME = "true";

package/dist/src/aic/diff.d.ts

@@ -0,0 +1,25 @@
+import type { Case, EvidenceChannel, RecordedEffects, Verdict } from "../case/types.ts";
+export interface EffectsDisagreement {
+    channel: EvidenceChannel;
+    path: string;
+    local: string;
+    aic: string;
+    message: string;
+}
+export interface ObservationGap {
+    channel: EvidenceChannel;
+    path: string;
+    local: string;
+    aic: string;
+    message: string;
+}
+export interface EffectsComparison {
+    disagreements: EffectsDisagreement[];
+    observationGaps: ObservationGap[];
+}
+/** Compare observable effects without turning absent evidence into equality. */
+export declare function diffRecordedEffects(local: RecordedEffects, aic: RecordedEffects): EffectsComparison;
+export declare function judgeBoth(kase: Case, local: RecordedEffects, aic: RecordedEffects): {
+    local: Verdict;
+    aic: Verdict;
+};