foottrace 1.0.3 → 1.2.0

package/dist/lib/cause/validation.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uniqueGaps = exports.gap = exports.nodeIds = exports.adjacency = exports.gaps = exports.attention = exports.refs = exports.list = exports.name = exports.plain = exports.own = exports.observePromise = exports.AdmissionError = void 0;
+const admission_js_1 = require("./admission.js");
+/** Graph-port refusals carry their code through Session; loader refusals are handled at the record boundary. */
+class AdmissionError extends admission_js_1.EvidenceRefusal {
+    code;
+    constructor(code = 'invalid-data') {
+        super(code, 'Invalid cause evidence');
+        this.code = code;
+    }
+}
+exports.AdmissionError = AdmissionError;
+/**
+ * Only ordinary native promise wrappers belong to the async host contract.
+ * An own constructor could run an accessor/species during intrinsic then().
+ * Exotic wrappers remain the trusted host's responsibility, including rejection handling.
+ */
+function observePromise(raw, accept, reject) {
+    if (!raw || typeof raw !== 'object' || Object.getPrototypeOf(raw) !== Promise.prototype)
+        return false;
+    if (Object.getOwnPropertyDescriptor(raw, 'constructor'))
+        throw new AdmissionError();
+    try {
+        Promise.prototype.then.call(raw, accept, reject);
+    }
+    catch {
+        throw new AdmissionError();
+    }
+    return true;
+}
+exports.observePromise = observePromise;
+const refuseGraph = (code) => new AdmissionError(code);
+const graphDescriptors = { translateTrapErrors: false, requireOwnValue: false };
+function own(value, key) {
+    return (0, admission_js_1.ownData)(value, key, refuseGraph, graphDescriptors);
+}
+exports.own = own;
+function plain(value) {
+    if (!value || typeof value !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        throw new AdmissionError();
+}
+exports.plain = plain;
+function name(value, maximum = 2048) {
+    return (0, admission_js_1.boundedName)(value, maximum, refuseGraph);
+}
+exports.name = name;
+function list(value, maximum, read, overflow = 'invalid-data') {
+    return (0, admission_js_1.boundedList)(value, maximum, read, {
+        refuse: refuseGraph,
+        overflow,
+        freeze: true,
+        descriptors: graphDescriptors,
+    });
+}
+exports.list = list;
+const reasons = new Set([
+    'ERROR_RECORDED',
+    'UNKNOWN_EFFECT_RECORDED',
+    'RETRY_STOP_RECORDED',
+    'TIMEOUT_RECORDED',
+    'RETRY_RECORDED',
+    'QUALITY_DROP_RECORDED',
+    'EVIDENCE_NOT_COLLECTED',
+    'OUTLIER_RECORDED',
+    'BUSINESS_RULE_MATCHED',
+]);
+const codes = new Set([
+    'not-collected',
+    'untracked-input',
+    'redacted',
+    'conservative',
+    'scope-boundary',
+    'invalid-data',
+    'unavailable',
+    'timeout',
+    'cancelled',
+    'cycle',
+    'node-limit',
+    'depth-limit',
+    'edge-limit',
+    'call-limit',
+    'truncated',
+    'strategy-failed',
+]);
+const refs = (value) => list(value, 16, (item) => name(item, 512));
+exports.refs = refs;
+function attention(value) {
+    return list(value, 32, (item) => {
+        plain(item);
+        const kind = own(item, 'kind'), reason = own(item, 'reason');
+        if (typeof kind !== 'string' ||
+            !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(kind) ||
+            typeof reason !== 'string' ||
+            !reasons.has(reason))
+            throw new AdmissionError();
+        const evidence = (0, exports.refs)(own(item, 'evidence'));
+        if (kind !== 'not-collected' && evidence.length === 0)
+            throw new AdmissionError();
+        return Object.freeze({ kind, reason: reason, evidence });
+    });
+}
+exports.attention = attention;
+function gaps(value) {
+    return list(value, 32, (item) => {
+        plain(item);
+        const code = own(item, 'code'), nodeId = own(item, 'nodeId');
+        if (typeof code !== 'string' || !codes.has(code))
+            throw new AdmissionError();
+        return Object.freeze({
+            code: code,
+            ...(nodeId === undefined ? {} : { nodeId: name(nodeId) }),
+            evidence: (0, exports.refs)(own(item, 'evidence')),
+        });
+    });
+}
+exports.gaps = gaps;
+function adjacency(value, maximum) {
+    plain(value);
+    const complete = own(value, 'complete');
+    if (typeof complete !== 'boolean')
+        throw new AdmissionError();
+    const edges = list(own(value, 'edges'), maximum, (item) => {
+        plain(item);
+        const nodeId = name(own(item, 'nodeId')), kind = own(item, 'kind'), attribution = own(item, 'attribution');
+        if ((kind !== 'data' && kind !== 'control') ||
+            (attribution !== 'per-write' && attribution !== 'stage' && attribution !== 'recorded-control') ||
+            (kind === 'control' && attribution !== 'recorded-control') ||
+            (kind === 'data' && attribution === 'recorded-control'))
+            throw new AdmissionError();
+        return Object.freeze({ nodeId, kind, attribution, evidence: (0, exports.refs)(own(item, 'evidence')) });
+    }, 'edge-limit');
+    return Object.freeze({ edges, complete });
+}
+exports.adjacency = adjacency;
+const nodeIds = (value, max) => list(value, max, (item) => name(item), 'node-limit');
+exports.nodeIds = nodeIds;
+const gap = (code, nodeId) => Object.freeze({ code, ...(nodeId === undefined ? {} : { nodeId }), evidence: Object.freeze([]) });
+exports.gap = gap;
+function uniqueGaps(items) {
+    const seen = new Set();
+    return Object.freeze(items.filter((item) => {
+        const key = JSON.stringify(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }));
+}
+exports.uniqueGaps = uniqueGaps;

package/dist/lib/cause/walk.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathTo = exports.frontier = exports.walk = void 0;
+const validation_js_1 = require("./validation.js");
+/** BFS discovers the shallowest arrival; a repeated diamond node is not a cycle. */
+async function walk(session, seeds, direction) {
+    const queue = [], seen = new Set(), marks = [], edges = [], missing = [];
+    const enqueue = (id, depth) => {
+        if (seen.has(id))
+            return;
+        const refusal = session.admit(id);
+        if (refusal) {
+            missing.push(refusal);
+            return;
+        }
+        seen.add(id);
+        queue.push([id, depth]);
+    };
+    for (const id of seeds)
+        enqueue(id, 0);
+    for (let index = 0; index < queue.length; index++) {
+        const [id, depth] = queue[index], stopped = session.stopGap(id);
+        if (stopped) {
+            missing.push(stopped);
+            break;
+        }
+        const marked = await session.read('attention', id, validation_js_1.attention);
+        if (marked.gap)
+            missing.push(marked.gap);
+        if (marked.value?.length) {
+            marks.push(Object.freeze({ nodeId: id, attention: marked.value }));
+            if (marked.value.some((item) => item.kind === 'not-collected'))
+                missing.push((0, validation_js_1.gap)('not-collected', id));
+        }
+        const coverage = await session.read('gaps', id, validation_js_1.gaps);
+        if (coverage.gap)
+            missing.push(coverage.gap);
+        if (coverage.value)
+            missing.push(...coverage.value);
+        const page = await session.read(direction, id, (raw) => (0, validation_js_1.adjacency)(raw, session.limits.maxEdges));
+        if (page.gap) {
+            missing.push(page.gap);
+            continue;
+        }
+        if (!page.value)
+            continue;
+        if (!page.value.complete)
+            missing.push((0, validation_js_1.gap)('not-collected', id));
+        if (depth >= session.limits.maxDepth) {
+            if (page.value.edges.length)
+                missing.push((0, validation_js_1.gap)('depth-limit', id));
+            continue;
+        }
+        for (const edge of page.value.edges) {
+            if (session.edges >= session.limits.maxEdges) {
+                missing.push((0, validation_js_1.gap)('edge-limit', id));
+                break;
+            }
+            session.edges++;
+            const refusal = session.admit(edge.nodeId);
+            if (refusal) {
+                missing.push(refusal);
+                continue;
+            }
+            edges.push(Object.freeze({
+                from: id,
+                to: edge.nodeId,
+                kind: edge.kind,
+                attribution: edge.attribution,
+                evidence: edge.evidence,
+            }));
+            if (edge.attribution === 'stage')
+                missing.push((0, validation_js_1.gap)('conservative', id));
+            enqueue(edge.nodeId, depth + 1);
+        }
+    }
+    if (hasCycle(edges))
+        missing.push((0, validation_js_1.gap)('cycle'));
+    return Object.freeze({
+        nodes: Object.freeze(queue.map((row) => row[0])),
+        marked: Object.freeze(marks),
+        edges: Object.freeze(edges),
+        gaps: (0, validation_js_1.uniqueGaps)(missing),
+    });
+}
+exports.walk = walk;
+/** Iterative three-colour walk; shared nodes remain distinguishable from back edges. */
+function hasCycle(edges) {
+    const next = new Map();
+    for (const edge of edges) {
+        if (!next.has(edge.from))
+            next.set(edge.from, []);
+        next.get(edge.from).push(edge.to);
+    }
+    const state = new Map();
+    for (const seed of next.keys()) {
+        if (state.has(seed))
+            continue;
+        const stack = [[seed, 0]];
+        state.set(seed, 1);
+        while (stack.length) {
+            const frame = stack[stack.length - 1], children = next.get(frame[0]) ?? [];
+            if (frame[1] >= children.length) {
+                state.set(frame[0], 2);
+                stack.pop();
+                continue;
+            }
+            const child = children[frame[1]++];
+            if (state.get(child) === 1)
+                return true;
+            if (!state.has(child)) {
+                state.set(child, 1);
+                stack.push([child, 0]);
+            }
+        }
+    }
+    return false;
+}
+function frontier(result) {
+    const marked = new Set(result.marked
+        .filter((item) => item.attention.some((mark) => mark.kind !== 'not-collected'))
+        .map((item) => item.nodeId));
+    const pending = new Map(result.nodes.map((id) => [id, 0]));
+    const dependents = new Map();
+    for (const edge of result.edges) {
+        pending.set(edge.from, (pending.get(edge.from) ?? 0) + 1);
+        if (!dependents.has(edge.to))
+            dependents.set(edge.to, []);
+        dependents.get(edge.to).push(edge.from);
+    }
+    // Process causal ancestors first, propagating one boolean through the DAG.
+    // This is O(nodes + edges), rather than a fresh ancestry scan per marked node.
+    const queue = [...pending].filter(([, count]) => count === 0).map(([id]) => id);
+    const earlierMark = new Set(), eligible = new Set();
+    for (let i = 0; i < queue.length; i++) {
+        const id = queue[i];
+        if (marked.has(id) && !earlierMark.has(id))
+            eligible.add(id);
+        for (const dependent of dependents.get(id) ?? []) {
+            if (marked.has(id) || earlierMark.has(id))
+                earlierMark.add(dependent);
+            const count = pending.get(dependent) - 1;
+            pending.set(dependent, count);
+            if (count === 0)
+                queue.push(dependent);
+        }
+    }
+    // Nodes left in a cycle cannot supply a validated earliest ancestor.
+    return result.marked.filter((item) => eligible.has(item.nodeId));
+}
+exports.frontier = frontier;
+function pathTo(edges, start, target) {
+    const queue = [start], previous = new Map([[start, undefined]]);
+    const next = new Map();
+    for (const edge of edges) {
+        if (!next.has(edge.from))
+            next.set(edge.from, []);
+        next.get(edge.from).push(edge.to);
+    }
+    for (let i = 0; i < queue.length; i++) {
+        const id = queue[i];
+        if (id === target)
+            break;
+        for (const child of next.get(id) ?? [])
+            if (!previous.has(child)) {
+                previous.set(child, id);
+                queue.push(child);
+            }
+    }
+    if (!previous.has(target))
+        return Object.freeze([]);
+    const path = [];
+    let id = target;
+    while (id !== undefined) {
+        path.push(id);
+        id = previous.get(id);
+    }
+    return Object.freeze(path.reverse());
+}
+exports.pathTo = pathTo;

package/dist/lib/ids/attemptId.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * attemptId — the address of one attempt under a stage execution.
+ *
+ * Format:
+ *   <runtimeStageId>@<n>              attempt n of the stage execution      'charge#4@2'
+ *   <runtimeStageId>@<n>.<k>@<m>      attempt m of the k-th call made        'charge#4@2.1@3'
+ *                                     during stage attempt n
+ *
+ * Every number after the runtimeStageId is a positive integer, counted from 1: attempt 1 is the first
+ * try, call 1 the first call the stage attempt made. Written without leading zeros, so one attempt has
+ * one spelling and an id is a safe join key.
+ *
+ * PARSED FROM THE RIGHT. A runtimeStageId always ends in `#<execution index>`, and the suffix grammar
+ * holds no `#`, so the LAST `#` of an attempt id is its execution delimiter whatever the stage id
+ * contains — `@`, `.` and `~` stay legal in stage ids, and no byte is newly reserved (the id doors'
+ * refusal, FootPrint's `refuseReservedId`, is untouched). The delimiter is read from the grammar's one
+ * owner, `runtimeStageId.ts`.
+ *
+ * Imports nothing but the runtime-ID grammar: a leaf of the record, checked by the package fence.
+ *
+ * @example
+ * ```typescript
+ * buildAttemptId('charge#4', 2);                              // 'charge#4@2'
+ * buildAttemptId('charge#4', 2, { ordinal: 1, attempt: 3 });  // 'charge#4@2.1@3'
+ * parseAttemptId('sf/v1.2@x#7@3'); // { runtimeStageId: 'sf/v1.2@x#7', attempt: 3 }
+ * parseAttemptId('charge#4');      // undefined — a stage execution, not an attempt
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAttemptId = exports.buildAttemptId = void 0;
+const runtimeStageId_js_1 = require("./runtimeStageId.js");
+/**
+ * What follows the last `#`: the execution index, `@` and the attempt, then — for a call — `.`, the
+ * call's ordinal, `@` and the call's attempt. Counts are canonical positive integers.
+ */
+const AFTER_EXECUTION_DELIMITER = /^(\d+)@([1-9]\d*)(?:\.([1-9]\d*)@([1-9]\d*))?$/;
+const EXECUTION_INDEX = /^\d+$/;
+/** True when `id` ends in `#<digits>` — the one shape every runtimeStageId has. */
+function endsInExecutionIndex(id) {
+    const at = id.lastIndexOf(runtimeStageId_js_1.EXECUTION_DELIMITER);
+    return at !== -1 && EXECUTION_INDEX.test(id.slice(at + 1));
+}
+/** Refuse a count the parser could not give back: a positive safe integer, or a `RangeError`. */
+function requireCount(name, value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new RangeError(`buildAttemptId: ${name} must be a positive integer (counted from 1), got ${String(value)}`);
+    }
+}
+/**
+ * Build the id of one attempt.
+ *
+ * @param runtimeStageId The stage execution the attempt belongs to (`[subflowPath/]stageId#index`).
+ * @param attempt The stage attempt, from 1.
+ * @param call For an attempt of a call made inside the stage attempt: the call's `ordinal` (1 for the
+ *   first call that stage attempt made) and its own `attempt` (from 1).
+ * @throws TypeError when `runtimeStageId` does not end in `#<execution index>`, and RangeError when a
+ *   count is not a positive integer — what `parseAttemptId` could not give back is never written.
+ */
+function buildAttemptId(runtimeStageId, attempt, call) {
+    if (typeof runtimeStageId !== 'string' || !endsInExecutionIndex(runtimeStageId)) {
+        throw new TypeError(`buildAttemptId: ${JSON.stringify(runtimeStageId)} is not a runtimeStageId (it must end in #<execution index>)`);
+    }
+    requireCount('attempt', attempt);
+    if (call === undefined)
+        return `${runtimeStageId}@${attempt}`;
+    requireCount('call ordinal', call.ordinal);
+    requireCount('call attempt', call.attempt);
+    return `${runtimeStageId}@${attempt}.${call.ordinal}@${call.attempt}`;
+}
+exports.buildAttemptId = buildAttemptId;
+/**
+ * Parse an attempt id into its parts, or `undefined` when `id` is not one (a bare runtimeStageId, a
+ * count of 0, a leading zero, a missing part). Never throws.
+ *
+ * `parseAttemptId(buildAttemptId(...parts))` gives the parts back, whatever the stage id contains.
+ */
+function parseAttemptId(id) {
+    if (typeof id !== 'string')
+        return undefined;
+    const at = id.lastIndexOf(runtimeStageId_js_1.EXECUTION_DELIMITER);
+    if (at === -1)
+        return undefined;
+    const parts = AFTER_EXECUTION_DELIMITER.exec(id.slice(at + 1));
+    if (!parts)
+        return undefined;
+    const [, index, attempt, ordinal, callAttempt] = parts;
+    const counts = [attempt, ordinal, callAttempt].filter((n) => n !== undefined).map(Number);
+    if (!counts.every(Number.isSafeInteger))
+        return undefined;
+    const runtimeStageId = id.slice(0, at + 1 + index.length);
+    if (ordinal === undefined)
+        return { runtimeStageId, attempt: counts[0] };
+    return { runtimeStageId, attempt: counts[0], call: { ordinal: counts[1], attempt: counts[2] } };
+}
+exports.parseAttemptId = parseAttemptId;