vouchington-tooling 0.23.0 → 0.24.0

package/dist/session-friction/log-file.mjs

@@ -7,10 +7,25 @@ export function validEvent(value) {
         return false;
     // oxlint-disable-next-line no-mistakes/ts-no-const-aliases -- establish a record view after the runtime object check
     const record = value;
-    return ((record.kind === 'sandbox-escalation' || record.kind === 'sandbox-failure') &&
+    return ((record.kind === 'sandbox-escalation' ||
+        record.kind === 'sandbox-failure' ||
+        record.kind === 'ambiguous-failure') &&
         isSafeAuditText(record.timestamp) &&
         isSafeAuditText(record.commandPrefix) &&
-        isSafeAuditText(record.detail));
+        isSafeAuditText(record.detail) &&
+        (record.failure === undefined || validFailure(record.failure)) &&
+        (record.outcome === undefined ||
+            (typeof record.outcome === 'string' &&
+                ['requested', 'approved', 'denied', 'unknown'].includes(record.outcome))));
+}
+function validFailure(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    // oxlint-disable-next-line no-mistakes/ts-no-const-aliases -- establish a validated object view
+    const failure = value;
+    return (Object.keys(failure).length === 2 &&
+        (failure.kind === 'sandbox-failure' || failure.kind === 'ambiguous-failure') &&
+        isSafeAuditText(failure.detail));
 }
 export function openLogFile(path, flags) {
     let descriptor;
@@ -36,10 +51,10 @@ export function openLogFile(path, flags) {
         throw error;
     }
 }
-export function readLogContent(descriptor) {
-    if (fstatSync(descriptor).size > LOG_MAX_BYTES)
+export function readLogContent(descriptor, maximumBytes = LOG_MAX_BYTES) {
+    if (fstatSync(descriptor).size > maximumBytes)
         throw new Error('session-friction log is too large');
-    const buffer = Buffer.alloc(LOG_MAX_BYTES + 1);
+    const buffer = Buffer.alloc(maximumBytes + 1);
     let length = 0;
     while (length < buffer.length) {
         const bytes = readSync(descriptor, buffer, length, buffer.length - length, length);
@@ -48,11 +63,11 @@ export function readLogContent(descriptor) {
         length += bytes;
     }
     /* v8 ignore next -- detects external growth after the descriptor size check. */
-    if (length > LOG_MAX_BYTES)
+    if (length > maximumBytes)
         throw new Error('session-friction log is too large');
     return decodeUtf8(buffer.subarray(0, length));
 }
-function validEventCount(content, limit) {
+export function validEventCount(content, limit) {
     let count = 0;
     for (const line of content.split('\n')) {
         if (!line.trim())
@@ -67,9 +82,6 @@ function validEventCount(content, limit) {
     }
     return count;
 }
-export function atEventLimit(content, limit) {
-    return validEventCount(content, limit) >= limit;
-}
 export function writeAll(descriptor, value) {
     const buffer = Buffer.from(value);
     let offset = 0;

package/dist/session-friction/log.mjs

@@ -1,9 +1,10 @@
+import { readCoverageLedger, writeCoverageLedger } from './coverage-ledger.mjs';
 import { closeSync, constants, fchmodSync, fstatSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { classifyFrictionObservation } from './classify.mjs';
 import { ensurePrivateDirectory } from './directory.mjs';
 import { withFileLock } from './lock.mjs';
-import { atEventLimit, LOG_MAX_BYTES, openLogFile, readLogContent, validEvent, writeAll, } from './log-file.mjs';
+import { validEventCount, LOG_MAX_BYTES, openLogFile, readLogContent, validEvent, writeAll, } from './log-file.mjs';
 import { sanitizeSessionId } from './session-id.mjs';
 import { boundedText, isWellFormedUnicode, normalizeAuditText } from './text.mjs';
 export const FRICTION_LOG_MAX_EVENTS = 500;
@@ -52,9 +53,23 @@ export function recordFriction(sessionId, observation, options) {
                 throw new Error('session-friction log is too large');
             if (!classified)
                 return;
+            const coverage = readCoverageLedger(path);
+            const logBytes = fstatSync(descriptor).size;
+            if (coverage && coverage.logBytes === logBytes && coverage.retainedEvents >= maxEvents) {
+                writeCoverageLedger(path, { ...coverage, droppedCount: coverage.droppedCount + 1 });
+                return;
+            }
             const content = readLogContent(descriptor);
-            if (atEventLimit(content, maxEvents))
+            const retainedEvents = validEventCount(content, FRICTION_LOG_MAX_EVENTS);
+            if (retainedEvents >= maxEvents) {
+                writeCoverageLedger(path, {
+                    schemaVersion: 1,
+                    logBytes,
+                    retainedEvents,
+                    droppedCount: (coverage?.droppedCount ?? 0) + 1,
+                });
                 return;
+            }
             const event = {
                 ...classified,
                 commandPrefix: normalizeAuditText(classified.commandPrefix),
@@ -66,9 +81,22 @@ export function recordFriction(sessionId, observation, options) {
                 return;
             const prefix = content && !content.endsWith('\n') ? '\n' : '';
             const addition = `${prefix}${JSON.stringify(event)}\n`;
-            if (fstatSync(descriptor).size + Buffer.byteLength(addition) > LOG_MAX_BYTES)
-                throw new Error('session-friction log is too large');
+            if (logBytes + Buffer.byteLength(addition) > LOG_MAX_BYTES) {
+                writeCoverageLedger(path, {
+                    schemaVersion: 1,
+                    logBytes,
+                    retainedEvents,
+                    droppedCount: (coverage?.droppedCount ?? 0) + 1,
+                });
+                return;
+            }
             writeAll(descriptor, addition);
+            if (coverage)
+                writeCoverageLedger(path, {
+                    ...coverage,
+                    logBytes: fstatSync(descriptor).size,
+                    retainedEvents: retainedEvents + 1,
+                });
         }
         finally {
             closeSync(descriptor);
@@ -89,19 +117,38 @@ export function readFrictionLog(sessionId, options) {
             const descriptor = openLogFile(path, constants.O_RDONLY);
             try {
                 const events = [];
+                const ledger = readCoverageLedger(path);
+                let droppedCount = ledger?.droppedCount ?? 0;
+                let retainedEvents = 0;
                 for (const line of readLogContent(descriptor).split('\n')) {
                     if (!line.trim())
                         continue;
                     try {
                         const value = JSON.parse(line);
-                        if (validEvent(value))
-                            events.push(value);
+                        if (validEvent(value)) {
+                            retainedEvents++;
+                            if (events.length < maxEvents)
+                                events.push(value);
+                            else
+                                droppedCount++;
+                        }
+                        else
+                            droppedCount++;
+                    }
+                    catch {
+                        droppedCount++;
                     }
-                    catch { }
-                    if (events.length >= maxEvents)
-                        break;
                 }
-                return events.length ? { status: 'events', events } : { status: 'empty' };
+                if (ledger &&
+                    (ledger.logBytes !== fstatSync(descriptor).size ||
+                        ledger.retainedEvents !== Math.min(retainedEvents, FRICTION_LOG_MAX_EVENTS)))
+                    throw new Error('session-friction coverage ledger does not match retained log');
+                if (!Number.isSafeInteger(droppedCount))
+                    throw new Error('session-friction dropped count overflow; capture incomplete');
+                const coverage = droppedCount ? { truncated: true, droppedCount } : {};
+                return events.length
+                    ? { status: 'events', events, ...coverage }
+                    : { status: 'empty', ...coverage };
             }
             finally {
                 closeSync(descriptor);

package/dist/session-friction/report.mjs

@@ -11,7 +11,7 @@ function journalData(entry) {
         return data ? { type: data.type, markdown: data.markdown } : undefined;
     }
     catch {
-        return undefined;
+        return 'unreadable';
     }
 }
 async function collectEntries(entries) {
@@ -22,8 +22,13 @@ async function collectEntries(entries) {
     let truncated = false;
     for await (const entry of entries) {
         consumed++;
-        const data = journalData(entry);
+        const scanned = journalData(entry);
+        if (scanned === 'unreadable')
+            truncated = true;
+        const data = scanned === 'unreadable' ? undefined : scanned;
         const markdown = data?.markdown;
+        if (data?.type === 'journal' && typeof markdown !== 'string')
+            truncated = true;
         if (data?.type === 'journal' && typeof markdown === 'string') {
             const bytes = Buffer.byteLength(markdown);
             inspectedBytes += bytes;
@@ -53,28 +58,52 @@ function errorMessage(error) {
 }
 function sandboxMarkdown(friction) {
     if (friction.status === 'events')
-        return buildSandboxSection(friction.events);
+        return `${friction.truncated ? `## Capture Coverage\nStatus: partial\nDropped records: ${friction.droppedCount}\n\n` : ''}${buildSandboxSection(friction.events)}`;
+    if (friction.status === 'empty' && friction.truncated)
+        return `## Sandbox & Permission Audit\nStatus: unavailable (partial capture; dropped ${friction.droppedCount} records)`;
     const status = friction.status === 'empty' ? 'none observed' : 'unavailable (no friction log)';
     return `## Sandbox & Permission Audit\nStatus: ${status}`;
 }
+function incompleteCiSection(markdownBlocks) {
+    return ['## CI Failures\nStatus: unavailable (journal scan incomplete)', ...markdownBlocks].join('\n\n');
+}
 function reportFromLog(sessionId, logOptions, journal) {
     try {
         const friction = readFrictionLog(sessionId, logOptions);
+        const coverage = {
+            journalStatus: journal.status === 'unreachable'
+                ? 'unavailable'
+                : journal.truncated
+                    ? 'partial'
+                    : 'complete',
+            frictionStatus: friction.status,
+            truncated: friction.status !== 'absent' && friction.truncated === true,
+            ...(friction.status === 'absent' ? {} : { droppedCount: friction.droppedCount ?? 0 }),
+        };
         if (journal.status === 'ok' && journal.truncated)
             return {
-                markdown: '## CI Failures\nStatus: unavailable (journal scan incomplete)\n\n' +
-                    sandboxMarkdown(friction),
+                coverage,
+                markdown: incompleteCiSection(journal.markdownBlocks) + '\n\n' + sandboxMarkdown(friction),
             };
         const markdown = buildCiFailuresSection(sessionId, journal, friction.status);
-        return { markdown: `${markdown}\n\n${sandboxMarkdown(friction)}` };
+        return { coverage, markdown: `${markdown}\n\n${sandboxMarkdown(friction)}` };
     }
     catch (error) {
         const ciMarkdown = journal.status === 'ok' && journal.truncated
-            ? '## CI Failures\nStatus: unavailable (journal scan incomplete)'
+            ? incompleteCiSection(journal.markdownBlocks)
             : journal.status === 'ok' && journal.markdownBlocks.length === 0
                 ? '## CI Failures\nStatus: unavailable (friction log unreadable)'
                 : buildCiFailuresSection(sessionId, journal, 'empty');
         return {
+            coverage: {
+                journalStatus: journal.status === 'unreachable'
+                    ? 'unavailable'
+                    : journal.truncated
+                        ? 'partial'
+                        : 'complete',
+                frictionStatus: 'unreadable',
+                truncated: true,
+            },
             markdown: `${ciMarkdown}\n\n## Sandbox & Permission Audit\nStatus: unavailable (friction log unreadable)`,
             diagnostic: errorMessage(error),
         };

package/dist/session-friction/sandbox.mjs

@@ -1,15 +1,22 @@
 import { markdownAuditText } from './text.mjs';
 const SANDBOX_SECTION_HEADER = '## Sandbox & Permission Audit';
-const KIND_ORDER = ['sandbox-escalation', 'sandbox-failure'];
+const KIND_ORDER = [
+    'sandbox-escalation',
+    'sandbox-failure',
+    'ambiguous-failure',
+];
 export function buildSandboxSection(events) {
+    const observations = events.flatMap((event) => event.failure
+        ? [event, { ...event, kind: event.failure.kind, detail: event.failure.detail }]
+        : [event]);
     const groups = KIND_ORDER.map((kind) => {
-        const selected = events.filter((event) => event.kind === kind);
+        const selected = observations.filter((event) => event.kind === kind);
         return selected.length
             ? [
                 `- ${kind} (${selected.length})`,
-                ...selected.map((event) => `  - ${markdownAuditText(event.commandPrefix)} — ${markdownAuditText(event.detail)} — ${markdownAuditText(event.timestamp)}`),
+                ...selected.map((event) => `  - ${markdownAuditText(event.commandPrefix)} — ${markdownAuditText(event.detail)} — ${markdownAuditText(event.timestamp)}${event.kind === 'sandbox-escalation' ? ` — outcome: ${event.outcome ?? 'unknown'}` : ''}`),
             ].join('\n')
             : undefined;
     }).filter((group) => group !== undefined);
-    return `${SANDBOX_SECTION_HEADER}\nEvents observed: ${events.length}\n\n${groups.join('\n')}`;
+    return `${SANDBOX_SECTION_HEADER}\nEvents observed: ${observations.length}\n\n${groups.join('\n')}`;
 }

package/dist/session-friction/types.d.mts

@@ -1,14 +1,20 @@
-export type FrictionEventKind = 'sandbox-escalation' | 'sandbox-failure';
+export type FrictionEventKind = 'sandbox-escalation' | 'sandbox-failure' | 'ambiguous-failure';
 export type FrictionEvent = {
     kind: FrictionEventKind;
     timestamp: string;
     commandPrefix: string;
     detail: string;
+    outcome?: 'requested' | 'approved' | 'denied' | 'unknown';
+    failure?: {
+        kind: 'sandbox-failure' | 'ambiguous-failure';
+        detail: string;
+    };
 };
 export type ToolResultObservation = {
     type: 'tool-result';
     command: string;
     commandWrappers?: string[];
+    permissionOutcome?: 'approved' | 'denied';
     escalationDetail?: string;
     structuredStderr?: string;
 };
@@ -18,14 +24,21 @@ export type PermissionRequestObservation = {
     commandWrappers?: string[];
 };
 export type FrictionObservation = ToolResultObservation | PermissionRequestObservation;
+type FrictionLogCoverage = {
+    truncated: true;
+    droppedCount: number;
+} | {
+    truncated?: false;
+    droppedCount?: never;
+};
 export type FrictionLogReadResult = {
     status: 'absent';
-} | {
+} | ({
     status: 'empty';
-} | {
+} & FrictionLogCoverage) | ({
     status: 'events';
     events: FrictionEvent[];
-};
+} & FrictionLogCoverage);
 export type FrictionLogOptions = {
     directory: string;
     maxEvents?: number;
@@ -43,10 +56,18 @@ export type JournalLoadResult = {
     status: 'not-found';
 };
 export type JournalLoader = (sessionId: string) => JournalLoadResult | Promise<JournalLoadResult>;
+export type SessionFrictionCoverage = {
+    journalStatus: 'complete' | 'partial' | 'unavailable';
+    frictionStatus: 'absent' | 'empty' | 'events' | 'unreadable';
+    truncated: boolean;
+    droppedCount?: number;
+};
 export type SessionFrictionReport = {
+    coverage: SessionFrictionCoverage;
     markdown: string;
     diagnostic?: string;
 };
 export type SessionFrictionReportOptions = FrictionLogOptions & {
     journalLoader: JournalLoader;
 };
+export {};

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

@@ -2,6 +2,6 @@ export { evaluateGraphPolicy } from './graph.mts';
 export { evaluateLockPolicy, type ConcurrencyPolicy } from './concurrency.mts';
 export { conditionEntails } from './condition-entailment.mts';
 export { unprovisionedSecretsWithoutReadinessStep } from './secret-readiness.mts';
-export { callerCalleePermissionMismatches } from './permission-mismatches.mts';
+export { callerCalleePermissionMismatches, type CallerCalleePermissionPolicy, } from './permission-mismatches.mts';
 export { missingTopLevelPermissionPaths, parsePermissions, parseWorkflow, requiredWorkflowPermissions, type Workflow, } from './permissions.mts';
 export type { WorkflowTopology, WorkflowTopologyIndex, WorkflowTopologyPolicy, WorkflowNode, WorkflowJobNode, WorkflowStep, } from './types.mts';

package/dist/workflow-policy/index.mjs

@@ -2,5 +2,5 @@ export { evaluateGraphPolicy } from './graph.mjs';
 export { evaluateLockPolicy } from './concurrency.mjs';
 export { conditionEntails } from './condition-entailment.mjs';
 export { unprovisionedSecretsWithoutReadinessStep } from './secret-readiness.mjs';
-export { callerCalleePermissionMismatches } from './permission-mismatches.mjs';
+export { callerCalleePermissionMismatches, } from './permission-mismatches.mjs';
 export { missingTopLevelPermissionPaths, parsePermissions, parseWorkflow, requiredWorkflowPermissions, } from './permissions.mjs';

package/dist/workflow-policy/permission-declarations.d.mts

@@ -0,0 +1,14 @@
+export declare const PERMISSION_LEVEL_RANK: {
+    readonly none: 0;
+    readonly read: 1;
+    readonly write: 2;
+};
+export type PermissionLevel = keyof typeof PERMISSION_LEVEL_RANK;
+type PermissionMap = Record<string, PermissionLevel>;
+export type BoundedPermissionDeclaration = PermissionMap | 'read-all';
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+export declare function isValidPermissionMap(value: unknown): value is PermissionMap;
+export declare function isValidDeclaration(value: unknown): value is BoundedPermissionDeclaration;
+export declare function permissionMap(value: BoundedPermissionDeclaration): Map<string, PermissionLevel>;
+export declare function mergePermissionMaps(target: Map<string, PermissionLevel>, source: Map<string, PermissionLevel>): void;
+export {};

package/dist/workflow-policy/permission-declarations.mjs

@@ -0,0 +1,55 @@
+export const PERMISSION_LEVEL_RANK = { none: 0, read: 1, write: 2 };
+const LEVELS_BY_SCOPE = {
+    actions: ['none', 'read', 'write'],
+    'artifact-metadata': ['none', 'read', 'write'],
+    attestations: ['none', 'read', 'write'],
+    checks: ['none', 'read', 'write'],
+    'code-quality': ['none', 'read', 'write'],
+    contents: ['none', 'read', 'write'],
+    deployments: ['none', 'read', 'write'],
+    discussions: ['none', 'read', 'write'],
+    'id-token': ['none', 'write'],
+    issues: ['none', 'read', 'write'],
+    models: ['none', 'read'],
+    packages: ['none', 'read', 'write'],
+    pages: ['none', 'read', 'write'],
+    'pull-requests': ['none', 'read', 'write'],
+    'repository-projects': ['none', 'read', 'write'],
+    'security-events': ['none', 'read', 'write'],
+    statuses: ['none', 'read', 'write'],
+    'vulnerability-alerts': ['none', 'read'],
+};
+export function isPlainRecord(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+export function isValidPermissionMap(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return Object.entries(value).every(([scope, level]) => {
+        const allowed = Object.hasOwn(LEVELS_BY_SCOPE, scope)
+            ? LEVELS_BY_SCOPE[scope]
+            : undefined;
+        return typeof level === 'string' && allowed?.includes(level) === true;
+    });
+}
+export function isValidDeclaration(value) {
+    return value === 'read-all' || isValidPermissionMap(value);
+}
+export function permissionMap(value) {
+    if (value === 'read-all') {
+        return new Map(Object.entries(LEVELS_BY_SCOPE)
+            .filter(([, levels]) => levels.includes('read'))
+            .map(([scope]) => [scope, 'read']));
+    }
+    return new Map(Object.entries(value).filter(([, level]) => level !== 'none'));
+}
+export function mergePermissionMaps(target, source) {
+    for (const [scope, level] of source) {
+        const current = target.get(scope) ?? 'none';
+        if (PERMISSION_LEVEL_RANK[level] > PERMISSION_LEVEL_RANK[current])
+            target.set(scope, level);
+    }
+}

package/dist/workflow-policy/permission-inheritance.d.mts

@@ -0,0 +1,8 @@
+import type { Workflow } from './permissions.mts';
+export declare function inheritanceAwarePermissionMismatches(args: {
+    callerPath: string;
+    callerJobKey: string;
+    callerWorkflow: Workflow;
+    calleePath: string;
+    calleeWorkflow: Workflow;
+}): string[];

package/dist/workflow-policy/permission-inheritance.mjs

@@ -0,0 +1,88 @@
+import { isPlainRecord, isValidDeclaration, isValidPermissionMap, mergePermissionMaps, permissionMap, PERMISSION_LEVEL_RANK, } from './permission-declarations.mjs';
+function sortedEntries(value) {
+    return [...value].toSorted(([left], [right]) => left.localeCompare(right));
+}
+function formatMap(value) {
+    return JSON.stringify(Object.fromEntries(sortedEntries(value)));
+}
+function diagnostic(callerPath, callerJobKey, calleePath, detail) {
+    return `  ${callerPath} job "${callerJobKey}" → ${calleePath}: ${detail}`;
+}
+export function inheritanceAwarePermissionMismatches(args) {
+    const prefix = (detail) => diagnostic(args.callerPath, args.callerJobKey, args.calleePath, detail);
+    const callerJob = args.callerWorkflow.jobs?.[args.callerJobKey];
+    const callerPermissions = callerJob?.permissions;
+    if (callerPermissions === 'write-all')
+        return [prefix('caller grants write-all')];
+    if (callerJob == null ||
+        !Object.hasOwn(callerJob, 'permissions') ||
+        !isValidPermissionMap(callerPermissions)) {
+        return [prefix('caller permissions must be an explicit map')];
+    }
+    const jobsPresent = Object.hasOwn(args.calleeWorkflow, 'jobs');
+    const jobsValue = args.calleeWorkflow.jobs;
+    if (jobsPresent && !isPlainRecord(jobsValue))
+        return [prefix('callee jobs are invalid')];
+    const calleeJobEntries = Object.entries(isPlainRecord(jobsValue) ? jobsValue : {});
+    const invalidJobKeys = [];
+    const calleeJobs = [];
+    for (const [key, job] of calleeJobEntries) {
+        if (isPlainRecord(job))
+            calleeJobs.push([key, job]);
+        else
+            invalidJobKeys.push(key);
+    }
+    if (invalidJobKeys.length > 0) {
+        return invalidJobKeys.map((key) => prefix(`callee job "${key}" is invalid`));
+    }
+    const topLevelPresent = Object.hasOwn(args.calleeWorkflow, 'permissions');
+    const topLevelPermissions = args.calleeWorkflow.permissions;
+    let validatedTopLevelPermissions;
+    if (topLevelPresent) {
+        if (topLevelPermissions === 'write-all')
+            return [prefix('callee requires write-all')];
+        if (!isValidDeclaration(topLevelPermissions)) {
+            return [prefix('callee top-level permissions are invalid')];
+        }
+        validatedTopLevelPermissions = topLevelPermissions;
+    }
+    if (calleeJobs.length === 0)
+        return [prefix('callee must declare at least one job')];
+    const invalidJobs = [];
+    const validatedJobPermissions = [];
+    let requiresWriteAll = false;
+    for (const [key, job] of calleeJobs) {
+        if (!Object.hasOwn(job, 'permissions'))
+            continue;
+        if (job.permissions === 'write-all') {
+            requiresWriteAll = true;
+        }
+        else if (isValidDeclaration(job.permissions)) {
+            validatedJobPermissions.push(job.permissions);
+        }
+        else {
+            invalidJobs.push(prefix(`callee job "${key}" permissions are invalid`));
+        }
+    }
+    if (invalidJobs.length > 0)
+        return invalidJobs;
+    if (requiresWriteAll)
+        return [prefix('callee requires write-all')];
+    const callerMap = permissionMap(callerPermissions);
+    const calleeMap = new Map();
+    if (validatedTopLevelPermissions !== undefined) {
+        mergePermissionMaps(calleeMap, permissionMap(validatedTopLevelPermissions));
+    }
+    for (const permissions of validatedJobPermissions) {
+        mergePermissionMaps(calleeMap, permissionMap(permissions));
+    }
+    const calleeFitsCaller = [...calleeMap].every(([scope, level]) => {
+        const callerLevel = callerMap.get(scope) ?? 'none';
+        return PERMISSION_LEVEL_RANK[callerLevel] >= PERMISSION_LEVEL_RANK[level];
+    });
+    const hasCallerInheritance = !topLevelPresent && calleeJobs.some(([, job]) => !Object.hasOwn(job, 'permissions'));
+    const permissionsMatch = JSON.stringify(sortedEntries(callerMap)) === JSON.stringify(sortedEntries(calleeMap));
+    if (calleeFitsCaller && (hasCallerInheritance || permissionsMatch))
+        return [];
+    return [prefix(`caller grants ${formatMap(callerMap)}, callee requires ${formatMap(calleeMap)}`)];
+}

package/dist/workflow-policy/permission-mismatches.d.mts

@@ -1,3 +1,6 @@
 import type { WorkflowTopology } from './types.mts';
 import { type Workflow } from './permissions.mts';
-export declare function callerCalleePermissionMismatches(topology: WorkflowTopology, documents: Readonly<Record<string, Workflow>>): string[];
+export type CallerCalleePermissionPolicy = {
+    comparison: 'exact' | 'inheritance-aware';
+};
+export declare function callerCalleePermissionMismatches(topology: WorkflowTopology, documents: Readonly<Record<string, Workflow>>, policy?: CallerCalleePermissionPolicy): string[];

package/dist/workflow-policy/permission-mismatches.mjs

@@ -1,4 +1,5 @@
 import { parsePermissions, permissionsToMap, requiredWorkflowPermissions, } from './permissions.mjs';
+import { inheritanceAwarePermissionMismatches } from './permission-inheritance.mjs';
 function formatPermissions(value) {
     if (value === null)
         return 'none';
@@ -6,7 +7,7 @@ function formatPermissions(value) {
         return value;
     return JSON.stringify(Object.fromEntries([...value].toSorted(([a], [b]) => a.localeCompare(b))));
 }
-export function callerCalleePermissionMismatches(topology, documents) {
+export function callerCalleePermissionMismatches(topology, documents, policy = { comparison: 'exact' }) {
     const mismatches = [];
     const jobsById = new Map(topology.jobs.map((job) => [job.id, job]));
     const workflowsById = new Map(topology.workflows.map((workflow) => [workflow.id, workflow]));
@@ -22,14 +23,24 @@ export function callerCalleePermissionMismatches(topology, documents) {
         if (!caller)
             throw new Error(`missing workflow document: ${callerPath}`);
         const job = caller.jobs?.[callerJob.key];
-        if (!job)
+        if (policy.comparison === 'exact' && !job)
             continue;
         const calleePath = callee.path;
         const calleeWorkflow = documents[calleePath];
         if (!calleeWorkflow)
             throw new Error(`missing workflow document: ${calleePath}`);
+        if (policy.comparison === 'inheritance-aware') {
+            mismatches.push(...inheritanceAwarePermissionMismatches({
+                callerPath,
+                callerJobKey: callerJob.key,
+                callerWorkflow: caller,
+                calleePath,
+                calleeWorkflow,
+            }));
+            continue;
+        }
         const calleePerms = requiredWorkflowPermissions(calleeWorkflow);
-        const jobPerms = parsePermissions(job.permissions);
+        const jobPerms = parsePermissions(job?.permissions);
         if (jobPerms == null) {
             mismatches.push(`  ${callerPath} job "${callerJob.key}" → ${calleePath}: missing explicit job-level permissions`);
             continue;

package/docs/workflow-and-compiler.md

@@ -37,7 +37,24 @@ const guardCoversConsumer = conditionEntails('always()', 'failure()')
 
 The permission comparison expects documents for every local caller and callable callee in the
 topology. The consumer reads workflow files and decides which inventory entries are provisioned;
-these functions never fetch secret values. Readiness checks rely on the parser's
+these functions never fetch secret values. The two-argument permission comparison requires exact
+caller/callee grants for compatibility. Consumers that intentionally let a reusable workflow job
+inherit the caller's token can opt into the fail-closed inheritance policy:
+
+```ts
+callerCalleePermissionMismatches(topology, documents, {
+  comparison: 'inheritance-aware',
+})
+```
+
+This mode requires an explicit caller permission map, rejects malformed declarations and
+`write-all`, and permits extra caller grants only when the callee omits top-level permissions and
+at least one callee job omits its own permissions. Explicit grants from every callee job still form
+required minima that must fit within the caller grants, including jobs guarded by `if`. The strict
+scope model follows GitHub's
+[workflow permission syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions).
+
+Readiness checks rely on the parser's
 `secretReferences` at workflow, job, and step scope. A missing required secret is considered ready
 only when a preceding guarded `run` step binds it to an env var, checks that var for emptiness,
 and exits with status 1. Optional `workflow_call` secrets are exempt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {