@struktoai/mirage-core/dist/policy/match/rule.d.ts

A Unified Virtual Filesystem For AI Agents

import type { util } from 'zod';
import type { PathSpec } from '../../types.ts';
import type { AdmissionRules, CommandContext, CommandRule, VfsContext } from '../types.ts';
/**
 * The paths a command's operands name, in order: what `rm -r` removes or
 * `mv`, `tar` and `cp` take as sources, never an option's value. Mirrors
 * Python's `operand_paths`.
 */
export declare function operandPaths(ctx: CommandContext): PathSpec[];
/**
 * What a line's rules are read against, in the stream's wire shape: its
 * tokens and paths, and the host's word on its command: whether it moves or
 * removes whole subtrees (`CommandContext.subtree`) and whether it is a move
 * whose last operand is the destination. Mirrors Python's command_facts.
 */
export declare function commandFacts(ctx: CommandContext): Record<string, util.JSONType>;
/**
 * Whether a rule holds at a dispatcher too: a pure path rule, which names
 * no command and has paths to match, the one kind an op can meet. The
 * sort of a profile's rules: a POSIX-level rule holds at every entry point, a
 * command-level one (it names a command, or no path) only where a line
 * is judged.
 */
export declare function posixLevel(rule: CommandRule): boolean;
/**
 * The command-level parts of a profile's rules, which an entry point that sees
 * only ops (a kernel mount, SFTP, codex-exec's file calls) cannot apply,
 * each described for the operator's warning: the allow list and every
 * rule that is not POSIX level.
 */
export declare function skippedAtDispatch(rules: AdmissionRules | null): string[];
/**
 * Whether a rule in force could reach an entry at or under this path for
 * the running line: the rule names the line and its paths, or a mount
 * rule's mount, could cover something in the subtree. What a native walk asks before it trusts the
 * raw tree, per operand the way a hide is: a rule on `/repo/.env` leaves
 * `find /s3` its native op.
 */
export declare function ioReach(rules: AdmissionRules | null, tokens: readonly string[], virtual: string): boolean;
/**
 * The reason a command may not touch an entry it reached on its own,
 * null when it may.
 *
 * The same law the admission gate applies to a line, and literally the
 * same loop (`ruleAt`): anchor depth first, deny before ask
 * at equal depth. Reading every deny before any ask instead would let a
 * broad deny on `/repo/*` overrule an approved ask on `/repo/sealed/*`
 * that the gate had just admitted the line under, so the carve-out
 * would survive admission and then refuse every entry it was written
 * for.
 *
 * The winning rule then answers: a deny refuses, an ask refuses unless
 * the line holds a grant under it (the nod the gate took for `rm -r /x`
 * covers the entries under `/x`; a walk that wanders into an asked
 * scope from outside gets no nod mid-command, so it is refused and the
 * agent names the path to be asked).
 */
export declare function ioRefusal(rules: AdmissionRules | null, tokens: readonly string[], virtual: string, granted: readonly CommandRule[]): string | null;
/**
 * The rule an op meets and whether it asks, null when the op may run.
 *
 * The dispatcher twin of `ioRefusal`, and the same law: anchor depth first,
 * deny before ask at equal depth, and an ask satisfied by a grant the
 * line already holds. Reading every deny before any ask instead let a
 * broad deny on `/repo/*` overrule an approved ask on `/repo/outbox/*`,
 * so the carve-out command admission had just admitted the line under
 * could not authorize the redirect it was written for: the write reached
 * the dispatcher and was refused there.
 *
 * What an ask means is the entry point's to say: inside a running line it
 * refuses like a deny, since the line was admitted without it, and
 * outside one (a file tool, the host's facade) it goes to the approval
 * ledger, keyed by rule and path. Mirrors Python's `op_ruling`.
 */
export declare function opRuling(rules: AdmissionRules | null, ctx: VfsContext, granted: readonly CommandRule[]): [CommandRule, boolean] | null;
//# sourceMappingURL=rule.d.ts.map