@pikku/core 0.12.150 → 0.12.151

package/dist/testing/trace-matrix/dimensions.d.ts

@@ -0,0 +1,55 @@
+import { type Combo } from './pairwise.js';
+export declare const STARTS: readonly ['http', 'channel', 'mcp', 'cli', 'trigger', 'gateway', 'queue-job', 'schedule', 'agent-tool'];
+export declare const HOPS: readonly ['rpc', 'mesh', 'remote-addon', 'enqueue', 'schedule', 'start-workflow', 'child-workflow'];
+export declare const ADAPTERS: readonly ['in-memory', 'bullmq', 'pg-boss', 'nats'];
+export declare const WORKFLOWS: readonly ['dsl-queued', 'dsl-inline', 'graph-queued', 'graph-inline'];
+export declare const STEPS: readonly ['rpc', 'sleep', 'suspend', 'approval', 'fan-out', 'retry', 'compensation'];
+export declare const INBOUNDS: readonly ['none', 'valid', 'invalid', 'forged'];
+export declare const OUTCOMES: readonly ['success', 'throw-pikku-error', 'throw-plain-error', 'schema-invalid', 'auth-mesh-jwt', 'auth-remote-addon', 'permission-denied', 'remote-4xx', 'remote-5xx', 'remote-network', 'remote-timeout', 'job-exhausted', 'job-discarded', 'job-poison', 'abandoned', 'step-compensated', 'workflow-cancelled', 'approval-rejected', 'fan-out-sibling-failure'];
+export declare const TIMINGS: readonly ['immediate', 'delayed-job', 'sleep-wakeup', 'slow-overlap', 'retry-backoff', 'lease-expiry-redelivery', 'duplicate-delivery', 'concurrent-starts', 'enqueue-before-fail', 'job-after-parent'];
+export type Start = (typeof STARTS)[number];
+export type Hop = (typeof HOPS)[number];
+export type Adapter = (typeof ADAPTERS)[number];
+export type Workflow = (typeof WORKFLOWS)[number];
+export type Step = (typeof STEPS)[number];
+export type Inbound = (typeof INBOUNDS)[number];
+export type Outcome = (typeof OUTCOMES)[number];
+export type Timing = (typeof TIMINGS)[number];
+/**
+ * The combinations that cannot happen, each with why. Every matrix goes through
+ * this list and reports what it dropped, so nothing is filtered silently. Rules
+ * see partial combinations and must stay undecided (false) on a missing value.
+ */
+export declare const EXCLUSIONS: ReadonlyArray<{
+    id: string;
+    why: string;
+    applies: (combo: Combo) => boolean;
+}>;
+/** The first rule that excludes this combination, if any. */
+export declare const exclusionOf: (combo: Combo) => string | undefined;
+export type MatrixReport = {
+    name: string;
+    generated: number;
+    included: number;
+    excluded: Record<string, number>;
+};
+/** Start × hop × outcome. */
+export declare const chainMatrix: () => {
+    combos: Combo[];
+    report: MatrixReport;
+};
+/** Adapter × workflow × step × outcome. */
+export declare const workflowMatrix: () => {
+    combos: Combo[];
+    report: MatrixReport;
+};
+/**
+ * Every value pair across all eight dimensions. `workflow` and `step` gain the
+ * value `none` for a chain with no workflow in it.
+ */
+export declare const pairwiseMatrix: () => {
+    combos: Combo[];
+    report: MatrixReport;
+    impossible: string[];
+    rulesUsed: Set<string>;
+};

package/dist/testing/trace-matrix/dimensions.js

@@ -0,0 +1,305 @@
+import { crossProduct, pairwiseCombos } from './pairwise.js';
+export const STARTS = [
+    'http',
+    'channel',
+    'mcp',
+    'cli',
+    'trigger',
+    'gateway',
+    'queue-job',
+    'schedule',
+    'agent-tool',
+];
+export const HOPS = [
+    'rpc',
+    'mesh',
+    'remote-addon',
+    'enqueue',
+    'schedule',
+    'start-workflow',
+    'child-workflow',
+];
+export const ADAPTERS = ['in-memory', 'bullmq', 'pg-boss', 'nats'];
+export const WORKFLOWS = [
+    'dsl-queued',
+    'dsl-inline',
+    'graph-queued',
+    'graph-inline',
+];
+export const STEPS = [
+    'rpc',
+    'sleep',
+    'suspend',
+    'approval',
+    'fan-out',
+    'retry',
+    'compensation',
+];
+export const INBOUNDS = ['none', 'valid', 'invalid', 'forged'];
+export const OUTCOMES = [
+    'success',
+    'throw-pikku-error',
+    'throw-plain-error',
+    'schema-invalid',
+    'auth-mesh-jwt',
+    'auth-remote-addon',
+    'permission-denied',
+    'remote-4xx',
+    'remote-5xx',
+    'remote-network',
+    'remote-timeout',
+    'job-exhausted',
+    'job-discarded',
+    'job-poison',
+    'abandoned',
+    'step-compensated',
+    'workflow-cancelled',
+    'approval-rejected',
+    'fan-out-sibling-failure',
+];
+export const TIMINGS = [
+    'immediate',
+    'delayed-job',
+    'sleep-wakeup',
+    'slow-overlap',
+    'retry-backoff',
+    'lease-expiry-redelivery',
+    'duplicate-delivery',
+    'concurrent-starts',
+    'enqueue-before-fail',
+    'job-after-parent',
+];
+const WORKFLOW_OUTCOMES = [
+    'step-compensated',
+    'workflow-cancelled',
+    'approval-rejected',
+    'fan-out-sibling-failure',
+];
+const REMOTE_OUTCOMES = [
+    'auth-remote-addon',
+    'remote-4xx',
+    'remote-5xx',
+    'remote-network',
+    'remote-timeout',
+];
+const JOB_OUTCOMES = [
+    'job-exhausted',
+    'job-discarded',
+    'job-poison',
+];
+/** Timings that are about how a queue delivers a job. */
+const DELIVERY_TIMINGS = [
+    'delayed-job',
+    'lease-expiry-redelivery',
+    'duplicate-delivery',
+    'job-after-parent',
+];
+const isWorkflowHop = (hop) => hop === 'start-workflow' || hop === 'child-workflow';
+const isInline = (workflow) => workflow?.endsWith('-inline') ?? false;
+const isGraph = (workflow) => workflow?.startsWith('graph') ?? false;
+const noStep = (step) => step === undefined || step === 'none';
+const known = (...values) => values.every((value) => value !== undefined);
+/**
+ * Whether a partial combination could only be run by a queue, given the chain
+ * has no queue job in it. Undecided until both the start and the hop are known.
+ */
+const noJobInChain = ({ start, hop }) => known(start, hop) && start !== 'queue-job' && hop !== 'enqueue';
+/**
+ * The combinations that cannot happen, each with why. Every matrix goes through
+ * this list and reports what it dropped, so nothing is filtered silently. Rules
+ * see partial combinations and must stay undecided (false) on a missing value.
+ */
+export const EXCLUSIONS = [
+    {
+        id: 'no-inbound-carrier',
+        why: 'CLI argv, a trigger source event and a gateway platform message carry no traceparent: each is the root of a trace',
+        applies: ({ start, inbound }) => known(start, inbound) &&
+            ['cli', 'trigger', 'gateway'].includes(start) &&
+            inbound !== 'none',
+    },
+    {
+        id: 'agent-caller-trace-is-not-parsed',
+        why: 'An agent tool takes the TraceContext object of its own caller, in-process: no string to be malformed or forged',
+        applies: ({ start, inbound }) => start === 'agent-tool' && (inbound === 'invalid' || inbound === 'forged'),
+    },
+    {
+        id: 'job-outcome-needs-a-job',
+        why: 'Exhausted retries, discard and poison are about a queue job, and the chain has none',
+        applies: (combo) => JOB_OUTCOMES.includes(combo.outcome) && noJobInChain(combo),
+    },
+    {
+        id: 'remote-outcome-needs-a-remote-addon',
+        why: 'Remote addon failures only exist on a hop to a remote addon',
+        applies: ({ hop, outcome, step }) => 
+        // A workflow step's RPC can itself be a remote addon call.
+        noStep(step) &&
+            known(hop) &&
+            REMOTE_OUTCOMES.includes(outcome) &&
+            hop !== 'remote-addon',
+    },
+    {
+        id: 'mesh-auth-needs-mesh',
+        why: 'pikkuMeshAuthMiddleware guards a mesh hop or an HTTP route; nothing else presents a mesh JWT',
+        applies: ({ start, hop, outcome, step }) => noStep(step) &&
+            known(start, hop) &&
+            outcome === 'auth-mesh-jwt' &&
+            hop !== 'mesh' &&
+            start !== 'http',
+    },
+    {
+        id: 'remote-host-validates-for-itself',
+        why: 'Schema and permission checks of a remote addon run on its host; this side sees a remote-4xx, its own outcome',
+        applies: ({ hop, outcome }) => hop === 'remote-addon' &&
+            (outcome === 'schema-invalid' || outcome === 'permission-denied'),
+    },
+    {
+        id: 'workflow-outcome-needs-a-workflow',
+        why: 'Compensation, cancellation, approval and fan-out only exist inside a workflow run',
+        applies: ({ hop, outcome }) => known(hop) && WORKFLOW_OUTCOMES.includes(outcome) && !isWorkflowHop(hop),
+    },
+    {
+        id: 'workflow-dimensions-need-a-workflow-hop',
+        why: 'Pairwise only: a chain with no workflow in it has no workflow type or step, which is the value `none`',
+        applies: ({ hop, workflow, step }) => known(hop) &&
+            ((workflow !== undefined &&
+                (workflow !== 'none') !== isWorkflowHop(hop)) ||
+                (step !== undefined && (step !== 'none') !== isWorkflowHop(hop))),
+    },
+    {
+        id: 'adapter-needs-a-queue',
+        why: 'Pairwise only: a chain with no job through a queue exercises no adapter, so only the in-memory value applies',
+        applies: ({ adapter, start, hop, workflow }) => known(adapter, start, hop, workflow) &&
+            adapter !== 'in-memory' &&
+            start !== 'queue-job' &&
+            hop !== 'enqueue' &&
+            !workflow.endsWith('-queued'),
+    },
+    {
+        id: 'graph-has-no-such-step',
+        why: 'A graph is RPC nodes: sleep, suspend and approval are DSL primitives',
+        applies: ({ workflow, step }) => isGraph(workflow) && ['sleep', 'suspend', 'approval'].includes(step),
+    },
+    {
+        id: 'inline-graph-has-no-retry-loop',
+        why: 'An inline graph node does not retry',
+        applies: ({ workflow, step, timing }) => workflow === 'graph-inline' &&
+            (step === 'retry' || timing === 'retry-backoff'),
+    },
+    {
+        id: 'inline-run-has-no-job',
+        why: 'An inline workflow does not touch the queue, so no job can exhaust, be discarded or be poison',
+        applies: ({ workflow, outcome }) => isInline(workflow) && JOB_OUTCOMES.includes(outcome),
+    },
+    {
+        id: 'approval-outcome-needs-approval-step',
+        why: 'Only an approval step can be rejected',
+        applies: ({ step, outcome }) => known(step) &&
+            step !== 'none' &&
+            outcome === 'approval-rejected' &&
+            step !== 'approval',
+    },
+    {
+        id: 'fan-out-outcome-needs-fan-out-step',
+        why: 'Only a fan-out has concurrent siblings',
+        applies: ({ step, outcome }) => known(step) &&
+            step !== 'none' &&
+            outcome === 'fan-out-sibling-failure' &&
+            step !== 'fan-out',
+    },
+    {
+        id: 'delivery-timing-needs-a-job',
+        why: 'Delays, redelivery and duplicates are how a queue delivers a job, and the chain has none',
+        applies: (combo) => DELIVERY_TIMINGS.includes(combo.timing) && noJobInChain(combo),
+    },
+    {
+        id: 'enqueue-timing-needs-enqueue',
+        why: 'Only a chain that enqueues can enqueue just before failing, or leave a job to outlive it',
+        applies: ({ hop, timing }) => known(hop) &&
+            (timing === 'enqueue-before-fail' || timing === 'job-after-parent') &&
+            hop !== 'enqueue',
+    },
+    {
+        id: 'sleep-timing-needs-sleep-step',
+        why: 'Only a sleep step wakes up',
+        applies: ({ hop, step, timing }) => timing === 'sleep-wakeup' &&
+            ((known(hop) && !isWorkflowHop(hop)) ||
+                (known(step) && step !== 'sleep')),
+    },
+    {
+        id: 'retry-timing-needs-a-retry',
+        why: 'Backoff needs a retried job or a retried step, and only an outcome that fails once can show it',
+        applies: ({ start, hop, step, outcome, timing }) => timing === 'retry-backoff' &&
+            ((known(start, hop) &&
+                start !== 'queue-job' &&
+                hop !== 'enqueue' &&
+                !isWorkflowHop(hop)) ||
+                (known(outcome) &&
+                    outcome !== 'success' &&
+                    outcome !== 'job-exhausted') ||
+                (known(hop, step) && isWorkflowHop(hop) && step !== 'retry')),
+    },
+];
+/** The first rule that excludes this combination, if any. */
+export const exclusionOf = (combo) => EXCLUSIONS.find((rule) => rule.applies(combo))?.id;
+const tally = (name, combos) => {
+    const included = [];
+    const excluded = {};
+    for (const combo of combos) {
+        const rule = exclusionOf(combo);
+        if (rule)
+            excluded[rule] = (excluded[rule] ?? 0) + 1;
+        else
+            included.push(combo);
+    }
+    const report = {
+        name,
+        generated: combos.length,
+        included: included.length,
+        excluded,
+    };
+    return { combos: included, report };
+};
+/** Start × hop × outcome. */
+export const chainMatrix = () => tally('start × hop × outcome', crossProduct({ start: STARTS, hop: HOPS, outcome: OUTCOMES }));
+/** Adapter × workflow × step × outcome. */
+export const workflowMatrix = () => tally('adapter × workflow × step × outcome', crossProduct({
+    adapter: ADAPTERS,
+    workflow: WORKFLOWS,
+    step: STEPS,
+    outcome: OUTCOMES,
+}));
+/**
+ * Every value pair across all eight dimensions. `workflow` and `step` gain the
+ * value `none` for a chain with no workflow in it.
+ */
+export const pairwiseMatrix = () => {
+    const rulesUsed = new Set();
+    const { combos, impossible, pairs } = pairwiseCombos({
+        start: STARTS,
+        hop: HOPS,
+        inbound: INBOUNDS,
+        outcome: OUTCOMES,
+        timing: TIMINGS,
+        workflow: ['none', ...WORKFLOWS],
+        step: ['none', ...STEPS],
+        adapter: ADAPTERS,
+    }, (partial) => {
+        const rule = exclusionOf(partial);
+        if (rule)
+            rulesUsed.add(rule);
+        return rule === undefined;
+    });
+    const excluded = {};
+    for (const key of impossible) {
+        const pair = Object.fromEntries(key.split('&').map((part) => part.split('=')));
+        const rule = exclusionOf(pair) ?? 'no-combination-holds-this-pair';
+        excluded[rule] = (excluded[rule] ?? 0) + 1;
+    }
+    const report = {
+        name: 'pairwise (value pairs)',
+        generated: pairs,
+        included: pairs - impossible.length,
+        excluded,
+    };
+    return { combos, report, impossible, rulesUsed };
+};

package/dist/testing/trace-matrix/pairwise.d.ts

@@ -0,0 +1,20 @@
+/** One value per dimension, possibly only some of them while being built. */
+export type Combo = Record<string, string>;
+export type Dimensions = Record<string, readonly string[]>;
+/** Every combination of the named dimensions. */
+export declare const crossProduct: (dimensions: Dimensions) => Combo[];
+/**
+ * Finds whole combinations covering every pair of values across `dimensions`,
+ * deterministically. A partial combination `allowed` refuses is never extended,
+ * and a pair no allowed combination can hold is returned in `impossible` rather
+ * than dropped, so a caller can account for it.
+ *
+ * Greedy: each round takes the first uncovered pair and fills the remaining
+ * dimensions with whichever value covers the most new pairs, backtracking when
+ * `allowed` closes a branch.
+ */
+export declare const pairwiseCombos: (dimensions: Dimensions, allowed?: (partial: Combo) => boolean) => {
+    combos: Combo[];
+    impossible: string[];
+    pairs: number;
+};

package/dist/testing/trace-matrix/pairwise.js

@@ -0,0 +1,75 @@
+/** Every combination of the named dimensions. */
+export const crossProduct = (dimensions) => Object.entries(dimensions).reduce((combos, [name, values]) => combos.flatMap((combo) => values.map((value) => ({ ...combo, [name]: value }))), [{}]);
+const pairKey = (a, x, b, y) => a < b ? `${a}=${x}&${b}=${y}` : `${b}=${y}&${a}=${x}`;
+/**
+ * Finds whole combinations covering every pair of values across `dimensions`,
+ * deterministically. A partial combination `allowed` refuses is never extended,
+ * and a pair no allowed combination can hold is returned in `impossible` rather
+ * than dropped, so a caller can account for it.
+ *
+ * Greedy: each round takes the first uncovered pair and fills the remaining
+ * dimensions with whichever value covers the most new pairs, backtracking when
+ * `allowed` closes a branch.
+ */
+export const pairwiseCombos = (dimensions, allowed = () => true) => {
+    const names = Object.keys(dimensions);
+    const uncovered = new Map();
+    for (let i = 0; i < names.length; i++) {
+        for (let j = i + 1; j < names.length; j++) {
+            const [a, b] = [names[i], names[j]];
+            for (const x of dimensions[a]) {
+                for (const y of dimensions[b]) {
+                    uncovered.set(pairKey(a, x, b, y), { [a]: x, [b]: y });
+                }
+            }
+        }
+    }
+    const pairs = uncovered.size;
+    const covers = (combo, name, value) => {
+        let count = 0;
+        for (const other of Object.keys(combo)) {
+            if (other !== name &&
+                uncovered.has(pairKey(name, value, other, combo[other]))) {
+                count++;
+            }
+        }
+        return count;
+    };
+    const complete = (combo, remaining) => {
+        if (!allowed(combo))
+            return undefined;
+        const [name, ...rest] = remaining;
+        if (!name)
+            return combo;
+        const ranked = dimensions[name].map((value, order) => ({
+            value,
+            order,
+            gain: covers(combo, name, value),
+        })).sort((x, y) => y.gain - x.gain || x.order - y.order);
+        for (const { value } of ranked) {
+            const found = complete({ ...combo, [name]: value }, rest);
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    const combos = [];
+    const impossible = [];
+    while (uncovered.size > 0) {
+        const [key, seed] = uncovered.entries().next().value;
+        const combo = complete(seed, names.filter((name) => !(name in seed)));
+        if (!combo) {
+            uncovered.delete(key);
+            impossible.push(key);
+            continue;
+        }
+        combos.push(combo);
+        for (let i = 0; i < names.length; i++) {
+            for (let j = i + 1; j < names.length; j++) {
+                const [a, b] = [names[i], names[j]];
+                uncovered.delete(pairKey(a, combo[a], b, combo[b]));
+            }
+        }
+    }
+    return { combos, impossible, pairs };
+};

package/dist/testing/trace-matrix/report.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/testing/trace-matrix/report.js

@@ -0,0 +1,16 @@
+/**
+ * Prints what each matrix generated and dropped, by reason:
+ * `bun src/testing/trace-matrix/report.ts`
+ */
+import { chainMatrix, EXCLUSIONS, pairwiseMatrix, workflowMatrix, } from './dimensions.js';
+for (const { report, combos } of [
+    chainMatrix(),
+    workflowMatrix(),
+    pairwiseMatrix(),
+]) {
+    console.log(`${report.name}: ${combos.length} tests from ${report.generated}, ${report.included} kept`);
+    for (const [id, count] of Object.entries(report.excluded)) {
+        const why = EXCLUSIONS.find((rule) => rule.id === id)?.why;
+        console.log(`  ${count} ${id}: ${why ?? 'see the rules this pair crosses'}`);
+    }
+}

package/dist/testing/trace-matrix/transports.d.ts

@@ -0,0 +1,19 @@
+import type { JobOptions } from '../../wirings/queue/queue.types.js';
+import type { Adapter } from './dimensions.js';
+export type EncodedJob = {
+    body: string;
+    headers: Record<string, string>;
+};
+/**
+ * How one adapter puts a job on the wire, so the core run covers each wire
+ * format with no broker. SIMULATED: the real adapters run the same permutations
+ * in `queue-trace-conformance.ts`, behind `scripts/test-trace-adapters.sh`.
+ */
+export type JobTransport = {
+    encode: (data: unknown, options?: JobOptions) => EncodedJob;
+    decode: (job: EncodedJob) => {
+        data: any;
+        traceparent?: string;
+    };
+};
+export declare const TRANSPORTS: Record<Adapter, JobTransport>;

package/dist/testing/trace-matrix/transports.js

@@ -0,0 +1,27 @@
+import { unwrapJobTrace, wrapJobTrace, } from '../../wirings/queue/queue-trace.js';
+const json = (value) => value === undefined ? 'null' : JSON.stringify(value);
+const envelope = {
+    encode: (data, options) => ({
+        body: json(wrapJobTrace(data, options?.traceparent)),
+        headers: {},
+    }),
+    decode: ({ body }) => unwrapJobTrace(JSON.parse(body)),
+};
+const headers = {
+    encode: (data, options) => ({
+        body: json(data),
+        headers: options?.traceparent
+            ? { traceparent: options.traceparent }
+            : {},
+    }),
+    decode: ({ body, headers }) => ({
+        data: JSON.parse(body),
+        traceparent: headers.traceparent,
+    }),
+};
+export const TRANSPORTS = {
+    'in-memory': headers,
+    bullmq: envelope,
+    'pg-boss': envelope,
+    nats: headers,
+};

package/dist/testing/trace-matrix/workflow-cases.d.ts

@@ -0,0 +1,24 @@
+import { InMemoryWorkflowService } from '../../wirings/workflow/in-memory-workflow-service.js';
+import type { QueuedWorkflowHarness } from '../service-tests/queued-workflow-harness.js';
+import type { Outcome, Step, Workflow } from './dimensions.js';
+/** Sleeps go through the scheduler, as in a deployment, so the wake-up is driven by hand. */
+export declare class ScheduledSleeps extends InMemoryWorkflowService {
+    protected scheduleSleep(...args: [string, string, number | string]): Promise<boolean>;
+}
+/** What a step's RPC throws for an outcome: the class a real call would raise. */
+export declare const outcomeError: (outcome: Outcome) => Error | undefined;
+export type RunCase = {
+    /** Names every function and workflow of this run apart from a concurrent one. */
+    id: string;
+    workflow: Workflow;
+    step: Step;
+    outcome: Outcome;
+};
+/**
+ * Registers a workflow named `flow-<id>` that reaches `step`, then has its last
+ * RPC meet `outcome`. Returns what brings the run to its end.
+ */
+export declare const defineRun: (h: QueuedWorkflowHarness, run: RunCase, child?: boolean) => {
+    /** Wakes whatever the run is waiting on, then lets it finish. */
+    settle: (runId: string, wakeSleeps: () => Promise<void>) => Promise<void>;
+};