dsh-perm-gate 2.1.2 → 4.0.0

package/lib/parsers/shell-cmds.js

@@ -0,0 +1,293 @@
+/**
+ * Shell dangerous commands parser - rm, mv, cp, chmod, dd, diskpart, etc.
+ * P1 priority - detects destructive filesystem operations.
+ *
+ * Handles:
+ * - rm -rf / recursive deletion
+ * - mv overwriting existing files
+ * - cp -r with destructive patterns
+ * - chmod/chown with system directories
+ * - dd writing to disk
+ * - diskpart on Windows
+ * - format disk operations
+ * - PowerShell Remove-Item with dangerous patterns
+ */
+/** Commands that are inherently destructive (only dangerous ones trigger canParse) */
+const DESTRUCTIVE_COMMANDS = {
+    // Level 5: Extreme (system-wide, data loss)
+    'dd': 5,
+    'diskpart': 5,
+    'format': 5,
+    'fdisk': 5,
+    'mkfs': 5,
+    'rm-sudo': 5,
+    // Level 4: High (significant file deletion/modification)
+    'rm': 4,
+    'rmdir': 4,
+    'shred': 4,
+    'wipefs': 4,
+    // Level 3: Medium (file operations with potential data loss)
+    'mv': 3,
+    // Level 2: Low (potentially risky)
+    'cp': 2,
+    'chmod': 2,
+    'chown': 2,
+    'chgrp': 2,
+    'install': 2,
+    'rsync': 2,
+    'tar': 2,
+};
+/** System directories that shouldn't be modified */
+const SYSTEM_DIRS = /^(\/bin|\/sbin|\/usr|\/lib|\/etc|\/boot|\/dev|\/proc|\/sys|\/var|C:\\Windows|C:\\Program Files)/i;
+/** Patterns that indicate destructive operations */
+const DESTRUCTIVE_PATTERNS = [
+    /rm\s+(-\w*\s+)*[^-\w]*\//i, // rm with /
+    /rm\s+(-\w*\s+)*\*/i, // rm with *
+    /rm\s+(-\w*\s+)*~/i, // rm with ~
+    /rm\s+(-\w*\s+)*\/[a-z]/i, // rm /anything
+    /rmdir\s+/i,
+    /mv\s+.*\//i, // mv to absolute path
+    /chmod\s+[0-7]*\s*\//i, // chmod on root paths
+    /chown\s+.*\//i, // chown on root paths
+    /dd\s+.*of=/i, // dd writing
+    /mkfs\./i, // format filesystem
+    />\s*\//i, // redirect to /
+    />>\s*\//i, // append to /
+];
+export class ShellDangerousParser {
+    name = 'shell-dangerous';
+    priority = 20;
+    canParse(command) {
+        const cmd = command.trim().toLowerCase();
+        const baseName = this.extractBaseName(cmd);
+        // Check if it's a known destructive command
+        if (DESTRUCTIVE_COMMANDS[baseName] !== undefined) {
+            return true;
+        }
+        // Check for PowerShell equivalents
+        if (cmd.startsWith('remove-item') || cmd.startsWith('ri ')) {
+            return true;
+        }
+        // Check for destructive patterns
+        return DESTRUCTIVE_PATTERNS.some(p => p.test(command));
+    }
+    parse(command) {
+        const trimmed = command.trim();
+        const cmd = trimmed.toLowerCase();
+        const baseName = this.extractBaseName(cmd);
+        let destructiveness = DESTRUCTIVE_COMMANDS[baseName] || 1;
+        let operation = baseName;
+        let targets = [];
+        let destructiveFlags = false;
+        // Parse based on command type
+        if (baseName === 'rm' || baseName === 'rmdir') {
+            const parsed = this.parseRm(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.recursive || parsed.force;
+            if (parsed.recursive && parsed.force) {
+                destructiveness = 5;
+                operation = 'recursive-force-delete';
+            }
+            else if (parsed.recursive) {
+                destructiveness = 4;
+                operation = 'recursive-delete';
+            }
+            else if (parsed.force) {
+                destructiveness = 3;
+                operation = 'force-delete';
+            }
+            // Check if targeting system directories
+            if (targets.some(t => SYSTEM_DIRS.test(t))) {
+                destructiveness = 5;
+            }
+        }
+        else if (baseName === 'mv') {
+            const parsed = this.parseMv(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.force;
+            if (parsed.force) {
+                destructiveness = 4;
+                operation = 'force-move';
+            }
+            // Check if overwriting system files
+            if (targets.some(t => SYSTEM_DIRS.test(t))) {
+                destructiveness = 4;
+            }
+        }
+        else if (baseName === 'chmod' || baseName === 'chown' || baseName === 'chgrp') {
+            const parsed = this.parseChmod(trimmed);
+            targets = parsed.targets;
+            if (targets.some(t => SYSTEM_DIRS.test(t))) {
+                destructiveness = 4;
+            }
+        }
+        else if (baseName === 'dd') {
+            const parsed = this.parseDd(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.force;
+        }
+        else if (baseName === 'diskpart' || baseName === 'format') {
+            const parsed = this.parseDiskpart(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = true;
+        }
+        else if (baseName.startsWith('remove-item') || baseName.startsWith('ri ')) {
+            const parsed = this.parsePowerShellRemove(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.recursive || parsed.force;
+            if (parsed.recursive && parsed.force) {
+                destructiveness = 5;
+                operation = 'recursive-force-delete';
+            }
+            else if (parsed.recursive) {
+                destructiveness = 4;
+                operation = 'recursive-delete';
+            }
+        }
+        else if (baseName === 'cp') {
+            const parsed = this.parseCp(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.force;
+            if (parsed.recursive) {
+                operation = 'recursive-copy';
+                destructiveness = 3;
+            }
+        }
+        else if (baseName === 'tar' || baseName === 'rsync') {
+            const parsed = this.parseArchive(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.delete;
+            if (parsed.delete) {
+                destructiveness = 4;
+                operation = 'archive-delete-target';
+            }
+        }
+        const flags = this.extractFlags(trimmed);
+        return {
+            family: 'shell-dangerous',
+            subcommand: baseName,
+            operation,
+            destructiveness: destructiveness,
+            destructiveFlags,
+            targets,
+            flags,
+            requiresConfirmation: destructiveness >= 4,
+            compound: false,
+            gitOperation: false,
+            targetsSharedBranch: false,
+            rawCommand: trimmed,
+        };
+    }
+    extractBaseName(command) {
+        // Handle sh -c "..." patterns
+        const shMatch = command.match(/(?:sh|bash|pwsh)(?:\s+-c\s+['"]?)(.+?)(?:['"]?)$/);
+        const actual = shMatch ? shMatch[1] : command;
+        // Extract first word
+        const parts = actual.trim().split(/\s+/);
+        return parts[0]?.toLowerCase() || '';
+    }
+    parseRm(command) {
+        const args = this.extractArgs(command);
+        const recursive = args.some(a => a === '-r' || a === '-rf' || a === '-fr' || a === '--recursive');
+        const force = args.some(a => a === '-f' || a === '-rf' || a === '-fr' || a === '--force');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, recursive, force };
+    }
+    parseMv(command) {
+        const args = this.extractArgs(command);
+        const force = args.some(a => a === '-f' || a === '--force');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, force };
+    }
+    parseCp(command) {
+        const args = this.extractArgs(command);
+        const recursive = args.some(a => a === '-r' || a === '-R' || a === '--recursive');
+        const force = args.some(a => a === '-f' || a === '--force');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, recursive, force };
+    }
+    parseChmod(command) {
+        const args = this.extractArgs(command);
+        const targets = args.filter(a => !a.startsWith('-') && !/^[0-7]+$/.test(a));
+        return { targets };
+    }
+    parseDd(command) {
+        const args = this.extractArgs(command);
+        const targets = [];
+        for (const arg of args) {
+            if (arg.startsWith('of=')) {
+                targets.push(arg.slice(3));
+            }
+            if (arg.startsWith('if=')) {
+                targets.push(arg.slice(3));
+            }
+        }
+        const force = command.includes('conv=') || command.includes('oflag=');
+        return { targets, force };
+    }
+    parseDiskpart(command) {
+        // Diskpart commands are always dangerous
+        const args = this.extractArgs(command);
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets };
+    }
+    parsePowerShellRemove(command) {
+        const args = this.extractArgs(command);
+        const recursive = args.some(a => a === '-Recurse' || a === '-r');
+        const force = args.some(a => a === '-Force' || a === '-f');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, recursive, force };
+    }
+    parseArchive(command) {
+        const args = this.extractArgs(command);
+        const deleteFlag = args.some(a => a === '--delete' || a === '-d');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, delete: deleteFlag };
+    }
+    extractArgs(command) {
+        const args = [];
+        let current = '';
+        let inQuote = false;
+        let quoteChar = '';
+        let escape = false;
+        for (const char of command) {
+            if (escape) {
+                current += char;
+                escape = false;
+                continue;
+            }
+            if (char === '\\') {
+                escape = true;
+                continue;
+            }
+            if (inQuote) {
+                if (char === quoteChar) {
+                    inQuote = false;
+                    continue;
+                }
+                current += char;
+                continue;
+            }
+            if (char === '"' || char === "'") {
+                inQuote = true;
+                quoteChar = char;
+                continue;
+            }
+            if (/\s/.test(char)) {
+                if (current) {
+                    args.push(current);
+                    current = '';
+                }
+                continue;
+            }
+            current += char;
+        }
+        if (current)
+            args.push(current);
+        return args;
+    }
+    extractFlags(command) {
+        const args = this.extractArgs(command);
+        return args.filter(a => a.startsWith('-'));
+    }
+}

package/lib/preset.d.ts

@@ -28,3 +28,16 @@ export interface SessionEventLike {
 export declare function permissionPresetOf(events: readonly SessionEventLike[] | undefined): string | undefined;
 /** Whether one preset name is covered by a configured scope list. */
 export declare function presetInScope(preset: string | undefined, scope: readonly string[]): boolean;
+/**
+ * Presets in which the gate is active. It owns both 自动审查 tiers — the plain
+ * one (file sandbox kept) and the full-access one (sandbox restriction lifted,
+ * same approval behaviour) — so a user can have the gate without inheriting a
+ * sandbox that breaks `git` / Cygwin tools. `'*'` makes it global (every
+ * preset, including the hard-deny layer).
+ *
+ * Lives in this dependency-free module (not `config.ts`) so the browser half can
+ * render the scope without pulling schemastery into the client bundle.
+ */
+export declare const DEFAULT_GATE_PRESETS: readonly string[];
+/** Normalize the gate scope: an unset/empty list means the default. */
+export declare function resolveGatePresets(configured?: readonly string[]): readonly string[];

package/lib/preset.js

@@ -39,3 +39,20 @@ export function presetInScope(preset, scope) {
         return false;
     return scope.includes(preset);
 }
+/**
+ * Presets in which the gate is active. It owns both 自动审查 tiers — the plain
+ * one (file sandbox kept) and the full-access one (sandbox restriction lifted,
+ * same approval behaviour) — so a user can have the gate without inheriting a
+ * sandbox that breaks `git` / Cygwin tools. `'*'` makes it global (every
+ * preset, including the hard-deny layer).
+ *
+ * Lives in this dependency-free module (not `config.ts`) so the browser half can
+ * render the scope without pulling schemastery into the client bundle.
+ */
+export const DEFAULT_GATE_PRESETS = ['permissive', 'permissive-full'];
+/** Normalize the gate scope: an unset/empty list means the default. */
+export function resolveGatePresets(configured) {
+    if (configured === undefined || configured.length === 0)
+        return DEFAULT_GATE_PRESETS;
+    return configured.filter((name) => typeof name === 'string' && name !== '');
+}

package/lib/risk.d.ts

@@ -6,8 +6,13 @@
  *
  *   safe                      → the gate may auto-allow the ask
  *   risky:<hard category>     → deletion / credential / remote / system / bulk —
- *                               auto-deny: the operation is clearly dangerous,
- *                               no popup or human review needed
+ *                               the operation looks dangerous; the gate KEEPS the
+ *                               human ask and never learns these into an
+ *                               auto-allow. It is NOT an auto-deny: denying is
+ *                               reserved for the deterministic layers (P0,
+ *                               deny-keywords, `deny:` rules), because a
+ *                               probabilistic verdict must not be able to hand
+ *                               down an unappealable block.
  *   risky:neutral             → no hard-risk signal but not clearly safe; the
  *                               verdict-learning path may auto-allow after
  *                               enough human confirmations
@@ -25,9 +30,18 @@ export type RiskCategory = 'deletion' | 'credential' | 'remote' | 'system' | 'bu
 /**
  * Categories that always route to the human seam regardless of learning state
  * or any later LLM opinion. Order-stable for prompts and event payloads.
+ *
+ * "Hard" means *never auto-allowed and never learned* — the gate keeps asking.
+ * It does not mean auto-denied: the deny path belongs to the deterministic
+ * layers alone (P0 hard-deny, the deny-keyword blacklist, explicit `deny:`
+ * rules), so a misgraded category can always be negotiated instead of becoming
+ * an unappealable block.
  */
 export declare const HARD_RISK_CATEGORIES: readonly RiskCategory[];
-/** Whether a category must never be auto-allowed. Unknown categories are hard too (fail-closed). */
+/**
+ * Whether a category must never be auto-allowed — and never learned into one.
+ * Unknown categories are hard too (fail-closed).
+ */
 export declare function isHardRisk(category: string): boolean;
 /**
  * A graded verdict for one tool call. `unresolved` covers every failure mode —

package/lib/risk.js

@@ -6,8 +6,13 @@
  *
  *   safe                      → the gate may auto-allow the ask
  *   risky:<hard category>     → deletion / credential / remote / system / bulk —
- *                               auto-deny: the operation is clearly dangerous,
- *                               no popup or human review needed
+ *                               the operation looks dangerous; the gate KEEPS the
+ *                               human ask and never learns these into an
+ *                               auto-allow. It is NOT an auto-deny: denying is
+ *                               reserved for the deterministic layers (P0,
+ *                               deny-keywords, `deny:` rules), because a
+ *                               probabilistic verdict must not be able to hand
+ *                               down an unappealable block.
  *   risky:neutral             → no hard-risk signal but not clearly safe; the
  *                               verdict-learning path may auto-allow after
  *                               enough human confirmations
@@ -23,10 +28,19 @@ import { chatCompletion, withLlmRetry } from './classifier.js';
 /**
  * Categories that always route to the human seam regardless of learning state
  * or any later LLM opinion. Order-stable for prompts and event payloads.
+ *
+ * "Hard" means *never auto-allowed and never learned* — the gate keeps asking.
+ * It does not mean auto-denied: the deny path belongs to the deterministic
+ * layers alone (P0 hard-deny, the deny-keyword blacklist, explicit `deny:`
+ * rules), so a misgraded category can always be negotiated instead of becoming
+ * an unappealable block.
  */
 export const HARD_RISK_CATEGORIES = ['deletion', 'credential', 'remote', 'system', 'bulk'];
 const RISK_CATEGORIES = [...HARD_RISK_CATEGORIES, 'neutral'];
-/** Whether a category must never be auto-allowed. Unknown categories are hard too (fail-closed). */
+/**
+ * Whether a category must never be auto-allowed — and never learned into one.
+ * Unknown categories are hard too (fail-closed).
+ */
 export function isHardRisk(category) {
     if (HARD_RISK_CATEGORIES.includes(category))
         return true;

package/lib/rule-chain.js

@@ -17,7 +17,7 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { existsSync, statSync } from 'node:fs';
-import { parsePermissionsDocument, compileDocument, documentHash } from './rule.js';
+import { parsePermissionsDocument, compileDocument, compileRuleEntry, documentHash } from './rule.js';
 import { hashText } from './compiler.js';
 /** Compile-cache entry: hash → compiled ruleset. */
 const compileCache = new Map();
@@ -136,11 +136,11 @@ function mergeChain(entries, badFilePolicy, opts) {
     // Flatten: deny entries from all files, then allow, then ask.
     // Index numbering is sequential across the entire chain.
     let index = 0;
-    const deny = flattenEntries(denyDocs, 'deny', index);
+    const deny = flattenEntries(denyDocs, 'deny', index, opts);
     index += deny.length;
-    const allow = flattenEntries(allowDocs, 'allow', index);
+    const allow = flattenEntries(allowDocs, 'allow', index, opts);
     index += allow.length;
-    const ask = flattenEntries(askDocs, 'ask', index);
+    const ask = flattenEntries(askDocs, 'ask', index, opts);
     return {
         defaultAction: entries.length > 0 ? entries[0].doc.defaultAction : 'ask',
         deny,
@@ -152,30 +152,21 @@ function mergeChain(entries, badFilePolicy, opts) {
 /**
  * Flatten a list of PermissionDocs into a single list of CompiledRuleEntry
  * for a specific action partition.
+ *
+ * Every entry goes through `compileRuleEntry` — the exact compiler the
+ * single-file path uses. Building entries by hand here previously left
+ * `tools`/`command`/`args`/`paths` as empty arrays, and an empty dimension
+ * means "no constraint", so EVERY entry matched EVERY call: the first deny
+ * entry denied everything in its partition and the first allow entry allowed
+ * everything before the `ask` partition was ever consulted.
  */
-function flattenEntries(docs, action, startIndex) {
+function flattenEntries(docs, action, startIndex, opts) {
     const result = [];
     let idx = startIndex;
     for (const doc of docs) {
         const list = action === 'deny' ? doc.deny : action === 'allow' ? doc.allow : doc.ask;
         for (const entry of list) {
-            result.push({
-                index: idx++,
-                action,
-                reason: entry.reason,
-                enabled: entry.enabled,
-                tools: [], // Will be compiled in the final merge step
-                command: [],
-                args: [],
-                paths: [],
-                params: entry.params,
-                absent: entry.absent,
-                agents: entry.agents,
-                when: entry.when,
-                argv: entry.argv,
-                network: entry.network,
-                source: entry,
-            });
+            result.push(compileRuleEntry(entry, action, idx++, opts));
         }
     }
     return result;

package/lib/rule-dims.d.ts

@@ -137,3 +137,38 @@ export interface NetworkDimension {
  * ```
  */
 export declare function parseNetworkDimension(raw: unknown, at: string): NetworkDimension | undefined;
+/**
+ * Parsed `branch` dimension: git branch / remote / shared-branch matching.
+ *
+ * Sub-dimensions are AND — every present sub-dimension must match. Within a
+ * sub-dimension, entries are OR.
+ *
+ * The candidates come from `dispatchCommand` (see `src/command-dispatcher.ts`)
+ * over each decomposed simple command, so `refspec` forms (`HEAD:main`) are
+ * already split and a remote name is never mistaken for a branch name.
+ *
+ * `shared` is **static**: it reflects the parser's protected-branch rule
+ * (`PROTECTED_BRANCHES` in `src/parsers/git.ts`: main / master / production /
+ * release / stable). It does **not** run git to discover whether a branch is
+ * genuinely shared — that would put a subprocess on the decision path.
+ */
+export interface BranchDimension {
+    /** Branch-name globs (e.g. `main`, `release*`). */
+    readonly target?: readonly string[];
+    /** Remote-name globs (e.g. `origin`, `upstream`). */
+    readonly remote?: readonly string[];
+    /** Require the command to target a protected branch. */
+    readonly shared?: boolean;
+}
+/**
+ * Parse the `branch` field: branch / remote / protected-branch matching.
+ *
+ * Format:
+ * ```yaml
+ * branch:
+ *   target: [main, "release*"]
+ *   remote: [origin]
+ *   shared: true
+ * ```
+ */
+export declare function parseBranchDimension(raw: unknown, at: string): BranchDimension | undefined;

package/lib/rule-dims.js

@@ -174,6 +174,42 @@ export function parseNetworkDimension(raw, at) {
     };
     return result;
 }
+/**
+ * Parse the `branch` field: branch / remote / protected-branch matching.
+ *
+ * Format:
+ * ```yaml
+ * branch:
+ *   target: [main, "release*"]
+ *   remote: [origin]
+ *   shared: true
+ * ```
+ */
+export function parseBranchDimension(raw, at) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new RuleError(`${at}.branch must be a mapping`);
+    }
+    const obj = raw;
+    const unknownKeys = Object.keys(obj).filter((k) => k !== 'target' && k !== 'remote' && k !== 'shared');
+    if (unknownKeys.length > 0) {
+        throw new RuleError(`${at}.branch unknown field${unknownKeys.length > 1 ? 's' : ''} ${unknownKeys.map((k) => JSON.stringify(k)).join(', ')} (expected target / remote / shared)`);
+    }
+    const target_ = obj.target !== undefined ? toStringList(obj.target, `${at}.branch.target`) : undefined;
+    const remote_ = obj.remote !== undefined ? toStringList(obj.remote, `${at}.branch.remote`) : undefined;
+    if (obj.shared !== undefined && typeof obj.shared !== 'boolean') {
+        throw new RuleError(`${at}.branch.shared must be a boolean`);
+    }
+    const shared_ = obj.shared;
+    if (target_ === undefined && remote_ === undefined && shared_ === undefined)
+        return undefined;
+    return {
+        ...(target_ !== undefined && { target: target_ }),
+        ...(remote_ !== undefined && { remote: remote_ }),
+        ...(shared_ !== undefined && { shared: shared_ }),
+    };
+}
 // ─── Helpers ───────────────────────────────────────────────────────────────
 /** Convert an unknown value to a string list (string → [string], array → filtered). */
 function toStringList(value, at) {

package/lib/rule.d.ts

@@ -1,5 +1,5 @@
 import { type CompiledPattern } from './compiler.js';
-import { type ParamsDimension, type AbsentDimension, type AgentsDimension, type WhenDimension, type ArgvDimension, type NetworkDimension } from './rule-dims.js';
+import { type ParamsDimension, type AbsentDimension, type AgentsDimension, type WhenDimension, type ArgvDimension, type NetworkDimension, type BranchDimension } from './rule-dims.js';
 export type RuleAction = 'allow' | 'ask' | 'deny';
 /** A parsed, shape-validated permissions document (patterns not yet compiled). */
 export interface PermissionsDoc {
@@ -33,6 +33,8 @@ export interface RuleEntryDoc {
     readonly argv: ArgvDimension | undefined;
     /** Network dimension (domain / IP / port / scheme). */
     readonly network: NetworkDimension | undefined;
+    /** Git branch / remote / protected-branch dimension. */
+    readonly branch: BranchDimension | undefined;
     readonly action: RuleAction;
     readonly reason: string;
     readonly enabled: boolean;
@@ -59,8 +61,16 @@ export interface CompiledRuleEntry {
     readonly argv: ArgvDimension | undefined;
     /** Parsed network dimension (raw patterns). */
     readonly network: NetworkDimension | undefined;
+    /** Compiled branch dimension (patterns compiled; absent = no constraint). */
+    readonly branch: CompiledBranchDimension | undefined;
     readonly source: RuleEntryDoc;
 }
+/** Compiled `branch` dimension: `target`/`remote` globs, raw `shared` flag. */
+export interface CompiledBranchDimension {
+    readonly target: readonly CompiledPattern[];
+    readonly remote: readonly CompiledPattern[];
+    readonly shared: boolean;
+}
 export interface CommandSpec {
     readonly word: CompiledPattern;
     readonly flag?: 'recursive' | 'force';
@@ -81,8 +91,33 @@ export declare class RuleError extends Error {
 }
 /** Parse a raw YAML permissions document; malformed files fail loud at load. */
 export declare function parsePermissionsDocument(text: string): PermissionsDoc;
+/**
+ * Parse a permissions document given as an already-parsed object — the shape
+ * the DSH settings namespace stores (the JSON twin of the YAML file). Accepts
+ * both the bare `{ defaultAction, deny, allow, ask }` form and the file's
+ * `permissions:`-wrapped form. Malformed input fails loud, exactly like the
+ * YAML path, so a settings doc that cannot compile is a state the operator
+ * sees, never a silent ruleset change.
+ */
+export declare function parsePermissionsObject(raw: unknown): PermissionsDoc;
+/**
+ * Compile one parsed entry into a hot-path rule.
+ *
+ * Exported because the multi-file rule chain (`rule-chain.ts`) merges entries
+ * from several documents into one ruleset and must produce the SAME shape here
+ * — an entry built by hand would silently drop every compiled dimension, and an
+ * empty dimension means "no constraint", i.e. "matches everything".
+ */
+export declare function compileRuleEntry(entry: RuleEntryDoc, action: RuleAction, index: number, opts?: CompileOptions): CompiledRuleEntry;
 /** Compile a validated document into hot-path rules. */
 export declare function compileDocument(doc: PermissionsDoc, opts?: CompileOptions): CompiledRuleset;
+/**
+ * Compile rules given as a structured settings object (already parsed — no
+ * YAML in the loop). The settings-first half of the dual-source read path:
+ * `parsePermissionsObject` validates the JSON form exactly as strictly as the
+ * YAML path, then the standard `compileDocument` runs.
+ */
+export declare function compileRulesObject(root: unknown, opts?: CompileOptions): CompiledRuleset;
 /** SHA-256 hash of the raw document (compile-cache key without recompiling). */
 export declare function documentHash(text: string): string;
 export declare function extractPathCandidates(args: Record<string, unknown>): string[];