vouchington-tooling 0.20.0 → 0.22.0

package/dist/vitest-diagnostics/vitest-worker-exit-diagnostics-errors.mjs

@@ -0,0 +1,42 @@
+// Shared error-introspection helpers for vitest-worker-exit-diagnostics-reporter.mts. Split out so
+// that file stays focused on the Reporter implementation and its own formatting; these two walk an
+// arbitrary, possibly-circular error-shaped value (Vitest's SerializedError, or anything nested
+// inside it) without assuming a fixed shape, since the "Worker exited unexpectedly" wrapper varies
+// by which layer (pool, tinypool-alike, Node) produced it.
+const diagnosticPropertyNames = ['name', 'message', 'stack', 'code', 'type', 'workerError', 'cause'];
+export function collectStringValues(value, seen = new Set()) {
+    if (value == null)
+        return [];
+    if (typeof value === 'string')
+        return [value];
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return [String(value)];
+    }
+    if (typeof value !== 'object' || seen.has(value))
+        return [];
+    seen.add(value);
+    const values = [];
+    for (const key of diagnosticKeys(value)) {
+        values.push(...collectStringValues(value[key], seen));
+    }
+    return values;
+}
+export function serializeDiagnosticsError(error, seen = new Set()) {
+    if (error == null || typeof error !== 'object')
+        return { value: error };
+    if (seen.has(error))
+        return { circular: true };
+    seen.add(error);
+    const output = {};
+    for (const key of diagnosticKeys(error)) {
+        if (!(key in error))
+            continue;
+        const value = error[key];
+        output[key] =
+            value == null || typeof value !== 'object' ? value : serializeDiagnosticsError(value, seen);
+    }
+    return output;
+}
+function diagnosticKeys(source) {
+    return new Set([...Object.keys(source), ...diagnosticPropertyNames]);
+}

package/dist/vitest-diagnostics/vitest-worker-exit-diagnostics-reporter.d.mts

@@ -0,0 +1,12 @@
+import type { Reporter, SerializedError, TestRunEndReason } from 'vitest/node';
+import { type ForkExitRecordSummary } from './vitest-fork-exit-records.mts';
+type ModuleEvent = {
+    kind: 'queued' | 'started' | 'ended';
+    moduleId: string;
+};
+export declare function createVitestWorkerExitDiagnosticsReporter(options: {
+    recordDirectory: string;
+}): Reporter;
+export declare function isWorkerExitError(error: unknown): boolean;
+export declare function formatWorkerExitDiagnostics(reason: TestRunEndReason, recentModuleEvents: ModuleEvent[], recentStderrLines: string[], unhandledErrors: ReadonlyArray<SerializedError>, unfinishedModules: string[], sentinelSummary: ForkExitRecordSummary): string;
+export {};

package/dist/vitest-diagnostics/vitest-worker-exit-diagnostics-reporter.mjs

@@ -0,0 +1,142 @@
+import { EOL } from 'node:os';
+import { clearForkExitRecords, formatForkExitSentinelSection, readForkExitRecords, summarizeForkExitRecords, } from './vitest-fork-exit-records.mjs';
+import { collectStringValues, serializeDiagnosticsError, } from './vitest-worker-exit-diagnostics-errors.mjs';
+const MAX_RECENT_MODULE_EVENTS = 8;
+const MAX_RECENT_STDERR_LINES = 12;
+const MAX_UNHANDLED_ERRORS = 2;
+const MAX_UNFINISHED_MODULES = 20;
+const MAX_SERIALIZED_ERROR_CHARS = 900;
+const MAX_STDERR_LINE_CHARS = 500;
+const workerExitSignals = [
+    'Error: [vitest-pool]: Worker forks emitted error.',
+    'Caused by: Error: Worker exited unexpectedly',
+    'Worker exited unexpectedly',
+];
+class VitestWorkerExitDiagnosticsReporter {
+    recordDirectory;
+    emitted = false;
+    recentModuleEvents = [];
+    recentStderrLines = [];
+    constructor(recordDirectory) {
+        this.recordDirectory = recordDirectory;
+        // Clear once before forks start. Clearing on watch reruns would unlink the files still held
+        // open by reused workers and make their later records invisible.
+        clearForkExitRecords(recordDirectory);
+    }
+    onTestRunStart() {
+        this.emitted = false;
+        this.recentModuleEvents = [];
+        this.recentStderrLines = [];
+    }
+    onTestModuleQueued(testModule) {
+        this.recordModuleEvent('queued', testModule);
+    }
+    onTestModuleStart(testModule) {
+        this.recordModuleEvent('started', testModule);
+    }
+    onTestModuleEnd(testModule) {
+        this.recordModuleEvent('ended', testModule);
+    }
+    onTestRunEnd(testModules, unhandledErrors, reason) {
+        const workerErrors = unhandledErrors.filter((error) => isWorkerExitError(error));
+        if (this.emitted || workerErrors.length === 0)
+            return;
+        this.emitted = true;
+        process.stderr.write(formatWorkerExitDiagnostics(reason, this.recentModuleEvents, this.recentStderrLines, workerErrors, unfinishedModuleIds(testModules), summarizeForkExitRecords(readForkExitRecords(this.recordDirectory))));
+    }
+    // Fired by Vitest's exit() watchdog at the teardownTimeout deadline; see
+    // formatTeardownOverrunDiagnostics() for why this stays separate from onTestRunEnd.
+    onProcessTimeout() {
+        process.stderr.write(`[vitest-worker-timeout] ${formatProcessResources()}${EOL}`);
+    }
+    onUserConsoleLog(log) {
+        if (log.type !== 'stderr')
+            return;
+        for (const line of log.content.split(/\r?\n/).filter(Boolean)) {
+            this.recentStderrLines.push(truncateBounded(line, MAX_STDERR_LINE_CHARS));
+        }
+        trimHead(this.recentStderrLines, MAX_RECENT_STDERR_LINES);
+    }
+    recordModuleEvent(kind, testModule) {
+        this.recentModuleEvents.push({
+            kind,
+            moduleId: testModule.relativeModuleId || testModule.moduleId,
+        });
+        trimHead(this.recentModuleEvents, MAX_RECENT_MODULE_EVENTS);
+    }
+}
+export function createVitestWorkerExitDiagnosticsReporter(options) {
+    if (!options.recordDirectory)
+        throw new Error('recordDirectory is required');
+    return new VitestWorkerExitDiagnosticsReporter(options.recordDirectory);
+}
+function formatProcessResources() {
+    const memory = process.memoryUsage();
+    return `pid=${process.pid} rssMB=${(memory.rss / 1024 / 1024).toFixed(1)} heapUsedMB=${(memory.heapUsed / 1024 / 1024).toFixed(1)}`;
+}
+function formatActiveResources() {
+    const counts = new Map();
+    for (const name of process.getActiveResourcesInfo())
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    return ([...counts]
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([name, count]) => `${name}=${count}`)
+        .join(' ') || 'none');
+}
+export function isWorkerExitError(error) {
+    const haystack = collectStringValues(error).join('\n');
+    return workerExitSignals.some((signal) => haystack.includes(signal));
+}
+export function formatWorkerExitDiagnostics(reason, recentModuleEvents, recentStderrLines, unhandledErrors, unfinishedModules, sentinelSummary) {
+    const lines = [
+        '',
+        '[vitest-worker-exit-diagnostics]',
+        `reason: ${reason}`,
+        `main-process: ${formatProcessResources()}`,
+        `active resources: ${formatActiveResources()}`,
+        'recent modules:',
+        ...formatList(recentModuleEvents, (event) => `${event.kind}: ${event.moduleId}`),
+        'unfinished modules:',
+        ...formatList(unfinishedModules.slice(0, MAX_UNFINISHED_MODULES), (moduleId) => moduleId),
+        'recent stderr:',
+        ...formatList(recentStderrLines, (line) => line),
+        'unhandled errors:',
+        ...formatList(unhandledErrors.slice(0, MAX_UNHANDLED_ERRORS), (error) => truncateBounded(JSON.stringify(serializeDiagnosticsError(error)), MAX_SERIALIZED_ERROR_CHARS)),
+        ...formatForkExitSentinelSection(sentinelSummary),
+    ];
+    if (unfinishedModules.length > MAX_UNFINISHED_MODULES) {
+        lines.push(`  ... ${unfinishedModules.length - MAX_UNFINISHED_MODULES} more unfinished modules`);
+    }
+    if (unhandledErrors.length > MAX_UNHANDLED_ERRORS) {
+        lines.push(`  ... ${unhandledErrors.length - MAX_UNHANDLED_ERRORS} more`);
+    }
+    return `${lines.join(EOL)}${EOL}`;
+}
+// A module Vitest never reported queued/started/ended for at all (the crash-mid-collection case)
+// won't appear in testModules; a module whose fork died before finishing it will, stuck in
+// 'queued' or 'pending' — that's the signature this section exists to name.
+function unfinishedModuleIds(testModules) {
+    const moduleIds = [];
+    for (const testModule of testModules) {
+        const state = testModule.state();
+        if (state === 'queued' || state === 'pending') {
+            moduleIds.push(testModule.relativeModuleId || testModule.moduleId);
+        }
+    }
+    return moduleIds;
+}
+function formatList(items, label) {
+    if (items.length === 0)
+        return ['  (none recorded)'];
+    return items.map((item) => `  - ${label(item)}`);
+}
+function truncateBounded(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${text.slice(0, maxChars - 3)}...`;
+}
+function trimHead(items, maxLength) {
+    if (items.length > maxLength) {
+        items.splice(0, items.length - maxLength);
+    }
+}

package/dist/workflow-policy/concurrency-scope.d.mts

@@ -0,0 +1,4 @@
+export type ConcurrencyScope = 'fixed-resource' | 'pull-request' | 'ref' | 'sha' | 'run' | 'event' | 'input-resource';
+export type NormalizedConcurrencyScope = Exclude<ConcurrencyScope, 'fixed-resource'> | `unsupported:${string}`;
+export declare function extractConcurrencyScopes(group: string): NormalizedConcurrencyScope[];
+export declare function normalizePolicyScopes(scopes: readonly ConcurrencyScope[]): NormalizedConcurrencyScope[];

package/dist/workflow-policy/concurrency-scope.mjs

@@ -0,0 +1,66 @@
+const scopeOrder = [
+    'pull-request',
+    'ref',
+    'sha',
+    'run',
+    'event',
+    'input-resource',
+];
+const ignoredOwnerContexts = new Set(['github.workflow', 'github.run_attempt']);
+const eventPayloadContexts = new Set([
+    'github.event_name',
+    'github.event.action',
+    'github.event.label.name',
+    'github.event.issue.number',
+    'github.event.schedule',
+    'github.event.workflow_run.event',
+    'github.event.workflow_run.id',
+    'github.event.workflow_run.workflow_id',
+]);
+function classifyContext(reference) {
+    if (ignoredOwnerContexts.has(reference))
+        return undefined;
+    if (reference === 'github.event.pull_request.number' ||
+        reference === 'github.event.workflow_run.pull_requests')
+        return 'pull-request';
+    if (reference === 'github.event.pull_request.head.sha' ||
+        reference === 'github.event.workflow_run.head_sha' ||
+        reference === 'github.sha')
+        return 'sha';
+    if (reference === 'github.ref' ||
+        reference === 'github.ref_name' ||
+        reference === 'github.event.workflow_run.head_branch')
+        return 'ref';
+    if (reference === 'github.run_id')
+        return 'run';
+    if (reference.startsWith('inputs.') ||
+        reference === 'github.event.inputs' ||
+        reference.startsWith('github.event.inputs.')) {
+        return 'input-resource';
+    }
+    if (eventPayloadContexts.has(reference))
+        return 'event';
+    return `unsupported:${reference}`;
+}
+function sortScopes(scopes) {
+    return [...new Set(scopes)].toSorted((left, right) => {
+        const leftIndex = scopeOrder.indexOf(left);
+        const rightIndex = scopeOrder.indexOf(right);
+        if (leftIndex === -1 || rightIndex === -1) {
+            if (leftIndex === rightIndex)
+                return left.localeCompare(right);
+            return leftIndex === -1 ? 1 : -1;
+        }
+        return leftIndex - rightIndex;
+    });
+}
+export function extractConcurrencyScopes(group) {
+    const references = group.match(/\b(?:github|inputs)(?:\.[A-Za-z_][\w-]*)+/gu) ?? [];
+    return sortScopes(references.flatMap((reference) => classifyContext(reference) ?? []));
+}
+export function normalizePolicyScopes(scopes) {
+    if (scopes.includes('fixed-resource')) {
+        return scopes.length === 1 ? [] : ['unsupported:fixed-resource-combination'];
+    }
+    return sortScopes(scopes.filter((scope) => scope !== 'fixed-resource'));
+}

package/dist/workflow-policy/concurrency.d.mts

@@ -0,0 +1,10 @@
+import type { WorkflowTopology } from './types.mts';
+import { type ConcurrencyScope } from './concurrency-scope.mts';
+type ConcurrencyCancellationBehavior = 'cancel-running' | 'retain-running' | 'conditional';
+export type ConcurrencyPolicy = {
+    pending: 'coalesce-latest' | 'fifo';
+    cancellation: ConcurrencyCancellationBehavior;
+    scope: readonly ConcurrencyScope[];
+};
+export declare function evaluateLockPolicy(topology: WorkflowTopology, unlockedWorkflowReasons: Readonly<Record<string, string>>, semanticPolicy: Readonly<Record<string, ConcurrencyPolicy>>): string[];
+export {};

package/dist/workflow-policy/concurrency.mjs

@@ -0,0 +1,77 @@
+import { extractConcurrencyScopes, normalizePolicyScopes, } from './concurrency-scope.mjs';
+function cancellation(value) {
+    return typeof value === 'string' ? 'conditional' : value ? 'cancel-running' : 'retain-running';
+}
+export function evaluateLockPolicy(topology, unlockedWorkflowReasons, semanticPolicy) {
+    const diagnostics = [];
+    const owners = [...topology.workflows, ...topology.jobs].filter((owner) => owner.concurrency);
+    const actualOwnerIds = new Set(owners.map((owner) => owner.id));
+    const declaredOwnerIds = new Set(Object.keys(semanticPolicy));
+    for (const id of [...actualOwnerIds].toSorted()) {
+        if (!declaredOwnerIds.has(id))
+            diagnostics.push(`lock intent missing: ${id}`);
+    }
+    for (const id of [...declaredOwnerIds].toSorted()) {
+        if (!actualOwnerIds.has(id))
+            diagnostics.push(`lock intent stale: ${id}`);
+    }
+    const jobsById = new Map(topology.jobs.map((job) => [job.id, job]));
+    for (const workflow of topology.workflows) {
+        const unlockedReason = unlockedWorkflowReasons[workflow.path];
+        const hasUnlockedJob = !workflow.concurrency &&
+            workflow.jobIds.some((jobId) => jobsById.get(jobId)?.concurrency === undefined);
+        if (hasUnlockedJob && !unlockedReason)
+            diagnostics.push(`lock intent missing: ${workflow.path}`);
+        if (!hasUnlockedJob && unlockedReason)
+            diagnostics.push(`unlocked reason stale: ${workflow.path}`);
+        if (unlockedReason !== undefined && unlockedReason.trim() === '')
+            diagnostics.push(`unlocked reason empty: ${workflow.path}`);
+    }
+    for (const path of Object.keys(unlockedWorkflowReasons).toSorted()) {
+        if (!topology.workflows.some((workflow) => workflow.path === path))
+            diagnostics.push(`unlocked reason stale: ${path}`);
+    }
+    for (const owner of owners) {
+        const declared = semanticPolicy[owner.id];
+        if (!declared || !owner.concurrency)
+            continue;
+        const cancelInProgress = owner.concurrency.effective.cancelInProgress;
+        if (typeof cancelInProgress === 'string' &&
+            !/^\$\{\{\s*\S[\s\S]*\}\}$/.test(cancelInProgress.trim()))
+            diagnostics.push(`conditional cancel-in-progress expression invalid: ${owner.id}: ${cancelInProgress}`);
+        const actualPending = owner.concurrency.effective.queue === 'max' ? 'fifo' : 'coalesce-latest';
+        if (actualPending !== declared.pending)
+            diagnostics.push(`concurrency pending mismatch: ${owner.id}: expected ${declared.pending}, got ${actualPending}`);
+        const actualCancellation = cancellation(owner.concurrency.effective.cancelInProgress);
+        if (actualCancellation !== declared.cancellation)
+            diagnostics.push(`concurrency cancellation mismatch: ${owner.id}: expected ${declared.cancellation}, got ${actualCancellation}`);
+        const actualScopes = extractConcurrencyScopes(owner.concurrency.effective.group);
+        const expectedScopes = normalizePolicyScopes(declared.scope);
+        if (JSON.stringify(actualScopes) !== JSON.stringify(expectedScopes))
+            diagnostics.push(`concurrency scope mismatch: ${owner.id}: expected ${expectedScopes.join(',')}, got ${actualScopes.join(',')}`);
+    }
+    diagnostics.push(...collisionDiagnostics(owners, topology));
+    return [...new Set(diagnostics)].toSorted();
+}
+function collisionDiagnostics(owners, topology) {
+    const workflowPathsById = new Map(topology.workflows.map((workflow) => [workflow.id, workflow.path]));
+    const ownerWorkflowPaths = new Map([
+        ...topology.workflows.map((workflow) => [workflow.id, workflow.path]),
+        ...topology.jobs.map((job) => [job.id, workflowPathsById.get(job.workflowId) ?? job.workflowId]),
+    ]);
+    const groups = new Map();
+    for (const owner of owners) {
+        const group = owner.concurrency?.effective.group;
+        if (!group)
+            continue;
+        const normalizedGroup = group.toLocaleLowerCase('en-US');
+        const workflowPartition = /\$\{\{\s*github\.workflow\s*\}\}/.test(group)
+            ? ownerWorkflowPaths.get(owner.id)
+            : '';
+        const key = `${normalizedGroup}\0${workflowPartition}`;
+        const entry = groups.get(key) ?? { group: normalizedGroup, ids: [] };
+        entry.ids.push(owner.id);
+        groups.set(key, entry);
+    }
+    return [...groups.values()].flatMap(({ group, ids }) => ids.length > 1 ? [`concurrency group collision: ${group}: ${ids.toSorted().join(', ')}`] : []);
+}

package/dist/workflow-policy/condition-entailment.d.mts

@@ -0,0 +1,20 @@
+/**
+ * True when `guardCondition` is guaranteed to hold whenever `consumerCondition` does, so a step
+ * gated by `guardCondition` cannot be skipped on any execution path that reaches a step gated by
+ * `consumerCondition`. Each of the guard's top-level `&&` clauses must either be one of the
+ * consumer's own clauses, or — when the guard clause is itself a `(a || b)` group — the consumer
+ * must require one of that group's alternatives. That second case is what a shared trailing gate
+ * ANDed onto an OR of per-consumer clauses produces: `(A || B) && G` guarding two steps gated
+ * `A && G` and `B && G` respectively — the shape a shared secret takes when it backs two
+ * differently-gated consumer steps in the same job.
+ *
+ * Clauses alone aren't enough: a guard with the implicit `success()`/default status restriction is
+ * skipped on any path where an earlier step already failed, so it cannot protect a consumer gated
+ * `always()` or `failure()` that still runs on that same path. `other` (e.g. `failure()`,
+ * `cancelled()`) is rejected outright as a guard status — this check can't reason about whether the
+ * guard and consumer agree on which failure path they run on, and a false "safe" verdict is the real
+ * risk (see file header). An `always()` guard has no restriction, so it entails any consumer status.
+ * Either side being `ambiguous` (an unparenthesized `&&`/`||` mix — see `hasTopLevelMixedOperators`)
+ * rejects entailment outright, since its clauses can't be trusted to reflect real precedence.
+ */
+export declare function conditionEntails(guardCondition: string, consumerCondition: string): boolean;

package/dist/workflow-policy/condition-entailment.mjs

@@ -0,0 +1,132 @@
+import { splitTopLevel, hasTopLevelMixedOperators } from './condition-split.mjs';
+/**
+ * Conservative GitHub Actions `if:` condition comparison.
+ * Deliberately conservative: a condition shape this can't reason about is treated as NOT entailed
+ * (readiness step rejected) rather than guessed at, since a false "safe" verdict is the real risk.
+ */
+/**
+ * Splits `expression` on top-level occurrences of `operator` — one inside parens or a quoted
+ * string doesn't count as top-level.
+ */
+function stripOuterParens(expression) {
+    const trimmed = expression.trim();
+    if (!trimmed.startsWith('(') || !trimmed.endsWith(')'))
+        return trimmed;
+    let depth = 0;
+    for (let index = 0; index < trimmed.length; index += 1) {
+        if (trimmed[index] === '(')
+            depth += 1;
+        else if (trimmed[index] === ')') {
+            depth -= 1;
+            if (depth === 0 && index !== trimmed.length - 1)
+                return trimmed;
+        }
+    }
+    return trimmed.slice(1, -1).trim();
+}
+const STATUS_CLAUSES = {
+    'success()': 'default',
+    'always()': 'always',
+    'failure()': 'other',
+    'cancelled()': 'other',
+};
+/**
+ * Recognizes a clause as a status-function check even when wrapped — a single layer of parens
+ * (`(cancelled())`) or a leading negation (`!cancelled()`, this repo's common form) — not just an
+ * exact bare match. Negation flips a status function's permissiveness in a way this file can't
+ * cleanly reason about (`!cancelled()` runs on both success and failure, a strict superset of the
+ * default success()-only restriction), so any negated form is conservatively classified `other`
+ * regardless of which function it negates — the same "can't reason about it, reject" fallback used
+ * elsewhere in this file.
+ */
+function classifyStatusClause(clause) {
+    const direct = STATUS_CLAUSES[clause] ?? STATUS_CLAUSES[stripOuterParens(clause)];
+    if (direct)
+        return direct;
+    if (!clause.startsWith('!'))
+        return undefined;
+    const negated = stripOuterParens(clause.slice(1).trim());
+    return STATUS_CLAUSES[negated] ? 'other' : undefined;
+}
+/**
+ * True when `clause` — or its single paren layer — is a top-level `||` where at least one branch
+ * is itself a status function (including wrapped forms, see `classifyStatusClause`). A shape like
+ * `always() || vars.FORCE == 'true'` mixes a status restriction into what looks like an ordinary
+ * clause — it can't be folded into the condition's one overall `ImpliedStatus`, nor matched as an
+ * ordinary clause (which needs an identical consumer-side string). Callers reject it outright.
+ */
+function hasStatusFunctionInOrBranch(clause) {
+    const branches = splitTopLevel(stripOuterParens(clause), '||');
+    if (branches.length <= 1)
+        return false;
+    return branches.some((branch) => classifyStatusClause(branch.trim()) !== undefined);
+}
+/**
+ * True when `expression` contains both a top-level `&&` and a top-level `||` — outside any
+ * parens or quoted string. GitHub Actions binds `&&` tighter than `||`, so `A || B && G` means
+ * `A || (B && G)`, not `(A || B) && G` — naively AND-splitting such a mix on `&&` would silently
+ * misread its grouping and could accept a guard that doesn't actually cover every path the
+ * consumer runs on. A condition mixing both operators without full parenthesization is one this
+ * file cannot safely reason about — see the conservative-rejection policy in the file header.
+ */
+function parseCondition(condition) {
+    const trimmed = condition.trim();
+    if (hasTopLevelMixedOperators(trimmed))
+        return { status: 'other', clauses: [], ambiguous: true };
+    const allClauses = trimmed === '' ? [] : splitTopLevel(trimmed, '&&');
+    const statuses = new Set();
+    const clauses = [];
+    for (const clause of allClauses) {
+        if (hasStatusFunctionInOrBranch(clause))
+            return { status: 'other', clauses: [], ambiguous: true };
+        const status = classifyStatusClause(clause);
+        if (status)
+            statuses.add(status);
+        else
+            clauses.push(clause);
+    }
+    if (statuses.size === 0)
+        return { status: 'default', clauses, ambiguous: false };
+    if (statuses.size > 1)
+        return { status: 'other', clauses, ambiguous: false };
+    return { status: [...statuses][0], clauses, ambiguous: false };
+}
+/**
+ * True when `guardCondition` is guaranteed to hold whenever `consumerCondition` does, so a step
+ * gated by `guardCondition` cannot be skipped on any execution path that reaches a step gated by
+ * `consumerCondition`. Each of the guard's top-level `&&` clauses must either be one of the
+ * consumer's own clauses, or — when the guard clause is itself a `(a || b)` group — the consumer
+ * must require one of that group's alternatives. That second case is what a shared trailing gate
+ * ANDed onto an OR of per-consumer clauses produces: `(A || B) && G` guarding two steps gated
+ * `A && G` and `B && G` respectively — the shape a shared secret takes when it backs two
+ * differently-gated consumer steps in the same job.
+ *
+ * Clauses alone aren't enough: a guard with the implicit `success()`/default status restriction is
+ * skipped on any path where an earlier step already failed, so it cannot protect a consumer gated
+ * `always()` or `failure()` that still runs on that same path. `other` (e.g. `failure()`,
+ * `cancelled()`) is rejected outright as a guard status — this check can't reason about whether the
+ * guard and consumer agree on which failure path they run on, and a false "safe" verdict is the real
+ * risk (see file header). An `always()` guard has no restriction, so it entails any consumer status.
+ * Either side being `ambiguous` (an unparenthesized `&&`/`||` mix — see `hasTopLevelMixedOperators`)
+ * rejects entailment outright, since its clauses can't be trusted to reflect real precedence.
+ */
+export function conditionEntails(guardCondition, consumerCondition) {
+    const guard = parseCondition(guardCondition);
+    if (guard.ambiguous || guard.status === 'other')
+        return false;
+    const consumer = parseCondition(consumerCondition);
+    if (consumer.ambiguous)
+        return false;
+    if (consumer.status !== 'default' && guard.status !== 'always')
+        return false;
+    const consumerClauses = new Set(consumer.clauses);
+    return guard.clauses.every((guardClause) => {
+        if (consumerClauses.has(guardClause))
+            return true;
+        const inner = stripOuterParens(guardClause);
+        if (inner === guardClause)
+            return false;
+        const branches = splitTopLevel(inner, '||');
+        return branches.length > 1 && branches.some((branch) => consumerClauses.has(branch));
+    });
+}

package/dist/workflow-policy/condition-split.d.mts

@@ -0,0 +1,15 @@
+export declare function splitTopLevel(expression: string, operator: '&&' | '||'): string[];
+/** Strips one layer of enclosing parens — only when the opening `(` at index 0 is the match for
+ *  the closing `)` at the end, not e.g. `(a) && (b)` which merely starts and ends with parens. */
+export declare function hasTopLevelMixedOperators(expression: string): boolean;
+/**
+ * Splits `condition` into its non-status `&&` clauses and its implied status restriction. A status
+ * function can appear anywhere among the top-level `&&` clauses (e.g. `always() && vars.X == 'true'`),
+ * not just as the entire condition, so every clause is checked rather than only a whole-string match —
+ * including wrapped forms like `!cancelled()`, see `classifyStatusClause`. Mixing two different status
+ * functions in one condition (`success() && failure()`, never valid in practice) is treated as `other`
+ * — the same conservative "can't reason about it" fallback as an unrecognized shape elsewhere in this
+ * file. A top-level `&&`/`||` mix, or a status function nested inside an OR branch (e.g.
+ * `always() || vars.FORCE`, see `hasStatusFunctionInOrBranch`), is flagged `ambiguous` instead, since
+ * neither shape is safe to decompose into clauses.
+ */

package/dist/workflow-policy/condition-split.mjs

@@ -0,0 +1,71 @@
+export function splitTopLevel(expression, operator) {
+    const segments = [];
+    let depth = 0;
+    let start = 0;
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    for (let index = 0; index < expression.length; index += 1) {
+        const char = expression[index];
+        if (char === "'" && !inDoubleQuote)
+            inSingleQuote = !inSingleQuote;
+        else if (char === '"' && !inSingleQuote)
+            inDoubleQuote = !inDoubleQuote;
+        else if (!inSingleQuote && !inDoubleQuote) {
+            if (char === '(')
+                depth += 1;
+            else if (char === ')')
+                depth -= 1;
+            else if (depth === 0 && expression.startsWith(operator, index)) {
+                segments.push(expression.slice(start, index));
+                index += operator.length - 1;
+                start = index + 1;
+            }
+        }
+    }
+    segments.push(expression.slice(start));
+    const trimmedSegments = [];
+    for (const segment of segments) {
+        const trimmed = segment.trim();
+        if (trimmed.length > 0)
+            trimmedSegments.push(trimmed);
+    }
+    return trimmedSegments;
+}
+/** Strips one layer of enclosing parens — only when the opening `(` at index 0 is the match for
+ *  the closing `)` at the end, not e.g. `(a) && (b)` which merely starts and ends with parens. */
+export function hasTopLevelMixedOperators(expression) {
+    let depth = 0;
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    let sawAnd = false;
+    let sawOr = false;
+    for (let index = 0; index < expression.length; index += 1) {
+        const char = expression[index];
+        if (char === "'" && !inDoubleQuote)
+            inSingleQuote = !inSingleQuote;
+        else if (char === '"' && !inSingleQuote)
+            inDoubleQuote = !inDoubleQuote;
+        else if (!inSingleQuote && !inDoubleQuote) {
+            if (char === '(')
+                depth += 1;
+            else if (char === ')')
+                depth -= 1;
+            else if (depth === 0 && expression.startsWith('&&', index))
+                sawAnd = true;
+            else if (depth === 0 && expression.startsWith('||', index))
+                sawOr = true;
+        }
+    }
+    return sawAnd && sawOr;
+}
+/**
+ * Splits `condition` into its non-status `&&` clauses and its implied status restriction. A status
+ * function can appear anywhere among the top-level `&&` clauses (e.g. `always() && vars.X == 'true'`),
+ * not just as the entire condition, so every clause is checked rather than only a whole-string match —
+ * including wrapped forms like `!cancelled()`, see `classifyStatusClause`. Mixing two different status
+ * functions in one condition (`success() && failure()`, never valid in practice) is treated as `other`
+ * — the same conservative "can't reason about it" fallback as an unrecognized shape elsewhere in this
+ * file. A top-level `&&`/`||` mix, or a status function nested inside an OR branch (e.g.
+ * `always() || vars.FORCE`, see `hasStatusFunctionInOrBranch`), is flagged `ambiguous` instead, since
+ * neither shape is safe to decompose into clauses.
+ */

package/dist/workflow-policy/graph.d.mts

@@ -0,0 +1,2 @@
+import type { WorkflowTopology, WorkflowTopologyIndex, WorkflowTopologyPolicy } from './types.mts';
+export declare function evaluateGraphPolicy(topology: WorkflowTopology, index: WorkflowTopologyIndex, policy: WorkflowTopologyPolicy): string[];