dsh-permission-rules 0.2.0

package/lib/types/runtime.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Runtime of `dsh-permission-rules`: per-workspace rule loading (project
+ * file chain by session cwd → fallback path → empty set), the
+ * `tools/pre-execute` listener that turns a first-match hit into a
+ * deny/ask decision (and NEVER short-circuits on allow or passthrough),
+ * the `permissionRules/decision` audit event, the `/rules` session command
+ * (`list | reload | decisions [n] | test <tool> <json>`), and
+ * Chokidar-driven reloads. Every registration is an effect.
+ * @module dsh-permission-rules/runtime
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { Config, ResolvedConfig } from './config.ts';
+import type { CompiledRuleset, RuleHit } from './rules.ts';
+import type { DecisionOutcome } from './events.ts';
+export declare const name = "permission-rules";
+/** Services required before the plugin mounts. */
+export declare const inject: string[];
+/** The rule state bound to one workspace cwd. */
+interface LoadedRules {
+    /** The workspace root these rules were resolved for. */
+    readonly cwd: string;
+    /** Absolute paths of the rule files in effect, nearest first; `[]` = empty rule set. */
+    readonly sources: readonly string[];
+    readonly compiled: CompiledRuleset;
+    /** Last load error, when one is being reported (see {@link PermissionRulesRuntime.rulesFor}). */
+    readonly lastError?: string;
+    /** `true` when the last initial load threw under `badFilePolicy: 'fail'`. */
+    readonly failed?: true;
+}
+/**
+ * State and behavior. One instance per plugin mount; disposals are owned by
+ * the watcher/timer effects registered in {@link apply}.
+ */
+export declare class PermissionRulesRuntime {
+    private readonly ctx;
+    readonly config: ResolvedConfig;
+    /** Loaded (or failed) rules per workspace cwd, least-recently-used first for eviction. */
+    private readonly byCwd;
+    /** Live watchers per rule-file path, with the cwds each serves. */
+    private readonly watchers;
+    /** Debounce timers per rule-file path. */
+    private readonly timers;
+    constructor(ctx: Context, config: ResolvedConfig);
+    /** The shared compile options derived from config. */
+    private compileOptions;
+    /**
+     * Resolve which files serve a workspace, nearest first: the project file
+     * under the session cwd (or an absolute `rulesFile`), with `searchUp`
+     * also merging every parent directory's file on the way to the root,
+     * else the configured fallback, else `[]` (empty rule set). Nearer files
+     * evaluate first, so a child can override a parent rule.
+     * @param cwd - the session's absolute workspace root.
+     * @returns the absolute rule-file paths in effect, nearest first.
+     */
+    resolveSources(cwd: string): string[];
+    /** The configured fallback file when it exists, else `[]`. */
+    private resolveFallback;
+    /**
+     * Read, parse, and compile the rule-file chain serving `cwd`. Under
+     * `badFilePolicy: 'ignore-with-warning'` a bad file degrades to an empty
+     * rule set with a warning and keeps its source paths (so a later fix is
+     * watched and adopted); under `'fail'` it throws.
+     * @param cwd - the workspace root.
+     * @returns the loaded state.
+     */
+    load(cwd: string): LoadedRules;
+    /**
+     * The rules in effect for one cwd, loading on first use. Under
+     * `badFilePolicy: 'fail'` a bad initial load throws on EVERY use (the
+     * pending tool call errors loudly) while the watcher keeps observing the
+     * files so a fix reloads into active rules. Cache hits refresh the
+     * least-recently-used position, so eviction drops the workspace that
+     * went longest without a decision.
+     * @param cwd - the workspace root.
+     * @returns the loaded rules.
+     */
+    rulesFor(cwd: string): LoadedRules;
+    /**
+     * Re-read the rule-file chain for one cwd (watch-driven or
+     * `/rules reload`). A bad file NEVER crashes the process: the previous
+     * rules stay active, the error is logged and reported on the next
+     * `/rules` output.
+     * @param cwd - the workspace root.
+     */
+    reload(cwd: string): void;
+    /** The match context `when` conditions evaluate against. */
+    private matchContext;
+    /**
+     * The `tools/pre-execute` listener. A deny/ask hit returns the decision
+     * (first match wins, short-circuiting downstream listeners); an allow hit
+     * and a passthrough MUST delegate via `next()` so later listeners keep
+     * their say. Audit is appended once the final outcome is known, so the
+     * recorded `outcome` matches what the waterfall settled on.
+     * @param exec - the pending call (name, parsed arguments, caller agent).
+     * @param next - the downstream chain.
+     * @returns the pre-execute decision.
+     */
+    preExecute(exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>;
+    /**
+     * Append the log-only `permissionRules/decision` audit event for every
+     * decision (passthrough included unless `audit: 'hits'`), requesting the
+     * envelope's `ignorable: true` marker so any harness build can load the
+     * log (readers that do not know the type skip the audit record instead of
+     * refusing the session). `source` names the matched rule's file, or the
+     * nearest effective file on a passthrough. Agentless calls have no
+     * session to audit; append failures are contained so an audit hiccup can
+     * never change a permission decision.
+     * @param exec - the pending call.
+     * @param loaded - the rules in effect.
+     * @param hit - the first matching rule, or undefined for passthrough.
+     * @param outcome - the final pre-execute decision.
+     */
+    audit(exec: ToolExecution, loaded: LoadedRules, hit: RuleHit | undefined, outcome: DecisionOutcome): void;
+    /**
+     * Execute the `/rules` command: bare `/rules` lists the active rules and
+     * their sources; `/rules reload` re-reads the chain; `/rules decisions
+     * [n]` shows the session's audit trail; `/rules test <tool> <json>`
+     * dry-evaluates the rules against a hypothetical call. Command output
+     * stays in the UI — nothing here is injected into the model context.
+     * @param invocation - the received command invocation.
+     * @returns the command result shown to the user.
+     */
+    command(invocation: CommandInvocation): CommandResult;
+    /** Render the session's `permissionRules/decision` audit trail, newest last. */
+    private decisionsCommand;
+    /**
+     * Validate deployment-level file references at mount — the earliest
+     * resolvable point. An absolute `rulesFile` or a configured
+     * `fallbackPath` must exist and parse; a missing referent fails the mount
+     * loudly instead of silently degrading later.
+     * @throws when a mandated file is missing or invalid.
+     */
+    validateDeploymentFiles(): void;
+    /** Parse and compile one mandated file, rethrowing as a mount failure. */
+    private loadForValidation;
+    /** Attach (once per file path) the Chokidar watcher feeding {@link reload}. */
+    private attachWatch;
+    /**
+     * Rebind `cwd` to its current rule-source chain. When a concrete source
+     * left the chain (deleted file, fallback switch), detach the workspace
+     * from watchers serving other sources and close the ones left empty, so
+     * long-running hosts cannot accumulate stale watchers. An empty chain (no
+     * rule file in effect) keeps the previous watchers alive: they own the
+     * "file recreated → adopted" signal, and the workspace-cache bound keeps
+     * the set of such watchers finite.
+     */
+    private reconcileWatch;
+    /** Close and drop watchers whose workspace sets are empty, clearing their debounce timers. */
+    private pruneWatchers;
+    /**
+     * Bound the per-workspace cache: when a NEW workspace would exceed
+     * `maxCachedWorkspaces`, evict the least-recently-used entry (the Map
+     * head, refreshed by every {@link rulesFor} hit) and release its watcher
+     * slots. Long-lived hosts that visit many workspaces therefore keep a
+     * bounded memory footprint.
+     */
+    private evictIfFull;
+    /** Number of live watchers, for observability and tests. */
+    activeWatcherCount(): number;
+    /** Number of pending debounce timers, for observability and tests. */
+    pendingReloadCount(): number;
+    /** Debounce watch events into one reload per stability window. */
+    private scheduleReload;
+}
+/**
+ * Mount the plugin: resolve config, validate deployment-level rule files,
+ * register the pre-execute listener and the `/rules` command.
+ * @param ctx - the host context.
+ * @param config - raw plugin config.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/lib/types/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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"}

package/lib/types/runtime.js

@@ -0,0 +1,497 @@
+/**
+ * Runtime of `dsh-permission-rules`: per-workspace rule loading (project
+ * file chain by session cwd → fallback path → empty set), the
+ * `tools/pre-execute` listener that turns a first-match hit into a
+ * deny/ask decision (and NEVER short-circuits on allow or passthrough),
+ * the `permissionRules/decision` audit event, the `/rules` session command
+ * (`list | reload | decisions [n] | test <tool> <json>`), and
+ * Chokidar-driven reloads. Every registration is an effect.
+ * @module dsh-permission-rules/runtime
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import chokidar from 'chokidar';
+import { resolveConfig } from "./config.js";
+import { compileRules, compileRulesChain, describeRule, findUnreachableRules, matchRules, parseRulesDocument, RuleError } from "./rules.js";
+import { DESCRIBE_TOKENS, UI_PROSE } from "./prose.js";
+export const name = 'permission-rules';
+/** Services required before the plugin mounts. */
+export const inject = ['commands', 'tools'];
+/**
+ * State and behavior. One instance per plugin mount; disposals are owned by
+ * the watcher/timer effects registered in {@link apply}.
+ */
+export class PermissionRulesRuntime {
+    ctx;
+    config;
+    /** Loaded (or failed) rules per workspace cwd, least-recently-used first for eviction. */
+    byCwd = new Map();
+    /** Live watchers per rule-file path, with the cwds each serves. */
+    watchers = new Map();
+    /** Debounce timers per rule-file path. */
+    timers = new Map();
+    constructor(ctx, config) {
+        this.ctx = ctx;
+        this.config = config;
+    }
+    /** The shared compile options derived from config. */
+    compileOptions() {
+        return {
+            patternMode: this.config.patternMode,
+            maxRules: this.config.maxRules,
+            maxGlobStars: this.config.maxGlobStars,
+            caseInsensitivePaths: this.config.caseInsensitivePaths,
+        };
+    }
+    /**
+     * Resolve which files serve a workspace, nearest first: the project file
+     * under the session cwd (or an absolute `rulesFile`), with `searchUp`
+     * also merging every parent directory's file on the way to the root,
+     * else the configured fallback, else `[]` (empty rule set). Nearer files
+     * evaluate first, so a child can override a parent rule.
+     * @param cwd - the session's absolute workspace root.
+     * @returns the absolute rule-file paths in effect, nearest first.
+     */
+    resolveSources(cwd) {
+        if (this.config.searchUp) {
+            const sources = [];
+            let dir = cwd;
+            for (;;) {
+                const candidate = join(dir, this.config.rulesFile);
+                if (existsSync(candidate))
+                    sources.push(candidate);
+                const parent = dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+            return sources.length === 0 ? this.resolveFallback() : sources;
+        }
+        const projectPath = isAbsolute(this.config.rulesFile) ? this.config.rulesFile : join(cwd, this.config.rulesFile);
+        if (existsSync(projectPath))
+            return [projectPath];
+        return this.resolveFallback();
+    }
+    /** The configured fallback file when it exists, else `[]`. */
+    resolveFallback() {
+        const fallback = this.config.fallbackPath;
+        if (fallback !== undefined) {
+            const fallbackPath = isAbsolute(fallback) ? fallback : resolve(fallback);
+            if (existsSync(fallbackPath))
+                return [fallbackPath];
+        }
+        return [];
+    }
+    /**
+     * Read, parse, and compile the rule-file chain serving `cwd`. Under
+     * `badFilePolicy: 'ignore-with-warning'` a bad file degrades to an empty
+     * rule set with a warning and keeps its source paths (so a later fix is
+     * watched and adopted); under `'fail'` it throws.
+     * @param cwd - the workspace root.
+     * @returns the loaded state.
+     */
+    load(cwd) {
+        const sources = this.resolveSources(cwd);
+        if (sources.length === 0)
+            return { cwd, sources: [], compiled: { rules: [], caseInsensitivePaths: this.config.caseInsensitivePaths } };
+        try {
+            const entries = sources.map(path => ({ path, text: readFileSync(path, 'utf8') }));
+            const { ruleset } = compileRulesChain(entries, this.compileOptions());
+            return { cwd, sources, compiled: ruleset };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (this.config.badFilePolicy === 'ignore-with-warning') {
+                this.ctx.logger.warn(`permission-rules: ignoring ${sources.join(', ')}: ${message} (empty rule set)`);
+                return { cwd, sources, compiled: { rules: [], caseInsensitivePaths: this.config.caseInsensitivePaths }, lastError: message };
+            }
+            throw error instanceof RuleError ? error : new RuleError(`cannot load ${sources.join(', ')}: ${message}`);
+        }
+    }
+    /**
+     * The rules in effect for one cwd, loading on first use. Under
+     * `badFilePolicy: 'fail'` a bad initial load throws on EVERY use (the
+     * pending tool call errors loudly) while the watcher keeps observing the
+     * files so a fix reloads into active rules. Cache hits refresh the
+     * least-recently-used position, so eviction drops the workspace that
+     * went longest without a decision.
+     * @param cwd - the workspace root.
+     * @returns the loaded rules.
+     */
+    rulesFor(cwd) {
+        const existing = this.byCwd.get(cwd);
+        if (existing !== undefined) {
+            if (existing.failed === true) {
+                throw new RuleError(existing.lastError ?? `rule load failed for ${cwd}`);
+            }
+            this.byCwd.delete(cwd);
+            this.byCwd.set(cwd, existing);
+            return existing;
+        }
+        this.evictIfFull(cwd);
+        try {
+            const loaded = this.load(cwd);
+            this.byCwd.set(cwd, loaded);
+            this.reconcileWatch(cwd, loaded.sources);
+            return loaded;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const sources = this.resolveSources(cwd);
+            this.byCwd.set(cwd, { cwd, sources, compiled: { rules: [], caseInsensitivePaths: this.config.caseInsensitivePaths }, lastError: message, failed: true });
+            this.reconcileWatch(cwd, sources);
+            throw error;
+        }
+    }
+    /**
+     * Re-read the rule-file chain for one cwd (watch-driven or
+     * `/rules reload`). A bad file NEVER crashes the process: the previous
+     * rules stay active, the error is logged and reported on the next
+     * `/rules` output.
+     * @param cwd - the workspace root.
+     */
+    reload(cwd) {
+        const previous = this.byCwd.get(cwd);
+        try {
+            const loaded = this.load(cwd);
+            this.byCwd.set(cwd, loaded);
+            this.reconcileWatch(cwd, loaded.sources);
+            this.ctx.logger.info(`permission-rules: reloaded ${loaded.compiled.rules.length} rule(s) from ${loaded.sources.join(', ') || '(empty rule set)'} for ${cwd}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.ctx.logger.warn(`permission-rules: reload failed for ${cwd}: ${message} (keeping previous rules)`);
+            if (previous !== undefined)
+                this.byCwd.set(cwd, { ...previous, lastError: message });
+            else
+                this.byCwd.set(cwd, { cwd, sources: this.resolveSources(cwd), compiled: { rules: [], caseInsensitivePaths: this.config.caseInsensitivePaths }, lastError: message, failed: true });
+        }
+    }
+    /** The match context `when` conditions evaluate against. */
+    matchContext() {
+        return { platform: process.platform, env: process.env };
+    }
+    /**
+     * The `tools/pre-execute` listener. A deny/ask hit returns the decision
+     * (first match wins, short-circuiting downstream listeners); an allow hit
+     * and a passthrough MUST delegate via `next()` so later listeners keep
+     * their say. Audit is appended once the final outcome is known, so the
+     * recorded `outcome` matches what the waterfall settled on.
+     * @param exec - the pending call (name, parsed arguments, caller agent).
+     * @param next - the downstream chain.
+     * @returns the pre-execute decision.
+     */
+    async preExecute(exec, next) {
+        const cwd = exec.agent?.session.header.cwd ?? process.cwd();
+        const loaded = this.rulesFor(cwd);
+        const hit = matchRules(loaded.compiled, exec.name, exec.arguments, cwd, this.matchContext());
+        if (hit === undefined || hit.rule.action === 'allow') {
+            const decision = await next();
+            this.audit(exec, loaded, hit, decision.kind);
+            return decision;
+        }
+        const outcome = hit.rule.action;
+        this.audit(exec, loaded, hit, outcome);
+        if (outcome === 'deny')
+            return { kind: 'deny', reason: hit.rule.reason };
+        return { kind: 'ask', reason: hit.rule.reason };
+    }
+    /**
+     * Append the log-only `permissionRules/decision` audit event for every
+     * decision (passthrough included unless `audit: 'hits'`), requesting the
+     * envelope's `ignorable: true` marker so any harness build can load the
+     * log (readers that do not know the type skip the audit record instead of
+     * refusing the session). `source` names the matched rule's file, or the
+     * nearest effective file on a passthrough. Agentless calls have no
+     * session to audit; append failures are contained so an audit hiccup can
+     * never change a permission decision.
+     * @param exec - the pending call.
+     * @param loaded - the rules in effect.
+     * @param hit - the first matching rule, or undefined for passthrough.
+     * @param outcome - the final pre-execute decision.
+     */
+    audit(exec, loaded, hit, outcome) {
+        if (this.config.audit === 'hits' && hit === undefined)
+            return;
+        const agent = exec.agent;
+        if (agent === undefined)
+            return;
+        try {
+            ;
+            agent.session.append('permissionRules/decision', {
+                toolName: exec.name,
+                callId: exec.callId,
+                source: hit === undefined ? (loaded.sources[0] ?? '') : (loaded.sources[hit.rule.sourceIndex] ?? ''),
+                action: hit === undefined ? 'passthrough' : hit.rule.action,
+                outcome,
+                ...hit !== undefined ? { ruleIndex: hit.ruleIndex, reason: hit.rule.reason } : {},
+            }, { ignorable: true });
+        }
+        catch (error) {
+            this.ctx.logger.warn(`permission-rules: audit append failed: ${String(error)}`);
+        }
+    }
+    /**
+     * Execute the `/rules` command: bare `/rules` lists the active rules and
+     * their sources; `/rules reload` re-reads the chain; `/rules decisions
+     * [n]` shows the session's audit trail; `/rules test <tool> <json>`
+     * dry-evaluates the rules against a hypothetical call. Command output
+     * stays in the UI — nothing here is injected into the model context.
+     * @param invocation - the received command invocation.
+     * @returns the command result shown to the user.
+     */
+    command(invocation) {
+        const prose = UI_PROSE[this.config.language];
+        const raw = invocation.rawInput.trim();
+        const [verbRaw, ...rest] = raw.split(/\s+/);
+        const verb = (verbRaw ?? '').toLowerCase();
+        const cwd = invocation.agent.session.header.cwd ?? process.cwd();
+        if (verb === 'reload') {
+            if (rest.length > 0)
+                return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) };
+            this.reload(cwd);
+            const reloaded = this.byCwd.get(cwd);
+            if (reloaded?.lastError !== undefined)
+                return { kind: 'error', text: prose.reloadFailed(reloaded.lastError) };
+            const rules = reloaded?.compiled.rules ?? [];
+            const source = reloaded === undefined || reloaded.sources.length === 0 ? prose.emptySource : reloaded.sources.join(', ');
+            return { kind: 'success', text: prose.reloaded(rules.length, source) };
+        }
+        if (verb === 'decisions') {
+            if (rest.length > 1)
+                return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) };
+            let count = 10;
+            if (rest.length === 1) {
+                const parsed = Number(rest[0]);
+                if (!Number.isSafeInteger(parsed) || parsed <= 0)
+                    return { kind: 'error', text: prose.invalidDecisionsCount(rest[0]) };
+                count = parsed;
+            }
+            return this.decisionsCommand(invocation, count, prose);
+        }
+        if (verb === 'test') {
+            const verbText = verbRaw ?? '';
+            const restLine = raw.length > verbText.length ? raw.slice(verbText.length).trim() : '';
+            const match = /^(\S+)\s*(.*)$/s.exec(restLine);
+            const tool = match?.[1];
+            const jsonText = match?.[2] ?? '';
+            if (tool === undefined || tool.length === 0)
+                return { kind: 'error', text: prose.testUsage };
+            let args;
+            try {
+                args = jsonText.length > 0 ? JSON.parse(jsonText) : {};
+            }
+            catch {
+                return { kind: 'error', text: prose.testBadJson(jsonText) };
+            }
+            let loaded;
+            try {
+                loaded = this.rulesFor(cwd);
+            }
+            catch (error) {
+                return { kind: 'error', text: error instanceof Error ? error.message : String(error) };
+            }
+            const hit = matchRules(loaded.compiled, tool, args, cwd, this.matchContext());
+            return {
+                kind: 'success',
+                text: hit === undefined ? prose.testNoMatch(tool) : prose.testHit(tool, hit.ruleIndex, hit.rule.action, hit.rule.reason),
+            };
+        }
+        if (verb !== '')
+            return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) };
+        let loaded;
+        try {
+            loaded = this.rulesFor(cwd);
+        }
+        catch (error) {
+            return { kind: 'error', text: error instanceof Error ? error.message : String(error) };
+        }
+        const lines = [];
+        if (loaded.sources.length === 0) {
+            lines.push(prose.noRules(cwd, this.config.fallbackPath !== undefined ? prose.fallbackMissing : ''));
+        }
+        else {
+            lines.push(prose.rulesHeader(loaded.compiled.rules.length, loaded.sources, cwd));
+            lines.push(...loaded.compiled.rules.map(rule => describeRule(rule, DESCRIBE_TOKENS[this.config.language])));
+            const unreachable = findUnreachableRules(loaded.compiled);
+            if (unreachable.length > 0)
+                lines.push(prose.unreachableWarning(unreachable.map(index => index + 1)));
+        }
+        if (loaded.lastError !== undefined) {
+            lines.push(prose.lastReloadWarning(loaded.lastError));
+        }
+        lines.push(prose.usage);
+        return { kind: 'success', text: lines.join('\n') };
+    }
+    /** Render the session's `permissionRules/decision` audit trail, newest last. */
+    decisionsCommand(invocation, count, prose) {
+        const decisions = invocation.agent.session.events.filter(event => event.type === 'permissionRules/decision');
+        if (decisions.length === 0)
+            return { kind: 'success', text: prose.noDecisions };
+        const shown = decisions.slice(-count);
+        const lines = [prose.decisionsHeader(shown.length, decisions.length)];
+        for (const event of shown) {
+            const data = event.data;
+            lines.push(prose.decisionLine(event.seq, data.action, data.toolName, data.ruleIndex, data.reason));
+        }
+        return { kind: 'success', text: lines.join('\n') };
+    }
+    /**
+     * Validate deployment-level file references at mount — the earliest
+     * resolvable point. An absolute `rulesFile` or a configured
+     * `fallbackPath` must exist and parse; a missing referent fails the mount
+     * loudly instead of silently degrading later.
+     * @throws when a mandated file is missing or invalid.
+     */
+    validateDeploymentFiles() {
+        if (isAbsolute(this.config.rulesFile)) {
+            this.loadForValidation(this.config.rulesFile);
+        }
+        if (this.config.fallbackPath !== undefined) {
+            const fallbackPath = isAbsolute(this.config.fallbackPath) ? this.config.fallbackPath : resolve(this.config.fallbackPath);
+            if (!existsSync(fallbackPath)) {
+                throw new RuleError(`permission-rules: fallbackPath ${JSON.stringify(this.config.fallbackPath)} does not exist`);
+            }
+            this.loadForValidation(fallbackPath);
+        }
+    }
+    /** Parse and compile one mandated file, rethrowing as a mount failure. */
+    loadForValidation(filePath) {
+        try {
+            const doc = parseRulesDocument(readFileSync(filePath, 'utf8'));
+            compileRules(doc, this.compileOptions());
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw error instanceof RuleError ? error : new RuleError(`permission-rules: cannot load ${filePath}: ${message}`);
+        }
+    }
+    /** Attach (once per file path) the Chokidar watcher feeding {@link reload}. */
+    attachWatch(cwd, source) {
+        if (!this.config.watch || source === '')
+            return;
+        const existing = this.watchers.get(source);
+        if (existing !== undefined) {
+            existing.cwds.add(cwd);
+            return;
+        }
+        const cwds = new Set([cwd]);
+        const watcher = chokidar.watch(source, { persistent: true, ignoreInitial: true });
+        const onEvent = () => this.scheduleReload(source);
+        watcher.on('add', onEvent);
+        watcher.on('change', onEvent);
+        watcher.on('unlink', onEvent);
+        watcher.on('error', (error) => {
+            this.ctx.logger.warn(`permission-rules: watcher error on ${source}: ${String(error)}`);
+        });
+        this.watchers.set(source, {
+            cwds,
+            close: () => {
+                void watcher.close().catch((error) => {
+                    this.ctx.logger.warn(`permission-rules: failed to close watcher on ${source}: ${String(error)}`);
+                });
+            },
+        });
+        this.ctx.effect(() => () => {
+            this.watchers.get(source)?.close();
+            this.watchers.delete(source);
+            const timer = this.timers.get(source);
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                this.timers.delete(source);
+            }
+        });
+    }
+    /**
+     * Rebind `cwd` to its current rule-source chain. When a concrete source
+     * left the chain (deleted file, fallback switch), detach the workspace
+     * from watchers serving other sources and close the ones left empty, so
+     * long-running hosts cannot accumulate stale watchers. An empty chain (no
+     * rule file in effect) keeps the previous watchers alive: they own the
+     * "file recreated → adopted" signal, and the workspace-cache bound keeps
+     * the set of such watchers finite.
+     */
+    reconcileWatch(cwd, sources) {
+        if (sources.length === 0)
+            return;
+        for (const [watchedSource, entry] of this.watchers) {
+            if (!sources.includes(watchedSource))
+                entry.cwds.delete(cwd);
+        }
+        this.pruneWatchers();
+        for (const source of sources)
+            this.attachWatch(cwd, source);
+    }
+    /** Close and drop watchers whose workspace sets are empty, clearing their debounce timers. */
+    pruneWatchers() {
+        for (const [source, entry] of this.watchers) {
+            if (entry.cwds.size > 0)
+                continue;
+            entry.close();
+            this.watchers.delete(source);
+            const timer = this.timers.get(source);
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                this.timers.delete(source);
+            }
+        }
+    }
+    /**
+     * Bound the per-workspace cache: when a NEW workspace would exceed
+     * `maxCachedWorkspaces`, evict the least-recently-used entry (the Map
+     * head, refreshed by every {@link rulesFor} hit) and release its watcher
+     * slots. Long-lived hosts that visit many workspaces therefore keep a
+     * bounded memory footprint.
+     */
+    evictIfFull(cwd) {
+        if (this.byCwd.size < this.config.maxCachedWorkspaces || this.byCwd.has(cwd))
+            return;
+        const oldest = this.byCwd.keys().next().value;
+        if (oldest === undefined)
+            return;
+        this.byCwd.delete(oldest);
+        for (const entry of this.watchers.values())
+            entry.cwds.delete(oldest);
+        this.pruneWatchers();
+    }
+    /** Number of live watchers, for observability and tests. */
+    activeWatcherCount() {
+        return this.watchers.size;
+    }
+    /** Number of pending debounce timers, for observability and tests. */
+    pendingReloadCount() {
+        return this.timers.size;
+    }
+    /** Debounce watch events into one reload per stability window. */
+    scheduleReload(source) {
+        const existing = this.timers.get(source);
+        if (existing !== undefined)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.timers.delete(source);
+            for (const cwd of this.watchers.get(source)?.cwds ?? [])
+                this.reload(cwd);
+        }, this.config.watchStabilityThresholdMs);
+        this.timers.set(source, timer);
+    }
+}
+/**
+ * Mount the plugin: resolve config, validate deployment-level rule files,
+ * register the pre-execute listener and the `/rules` command.
+ * @param ctx - the host context.
+ * @param config - raw plugin config.
+ */
+export function apply(ctx, config) {
+    const resolved = resolveConfig(config);
+    const runtime = new PermissionRulesRuntime(ctx, resolved);
+    runtime.validateDeploymentFiles();
+    ctx.provide('permissionRulesRuntime', runtime);
+    ctx.on('tools/pre-execute', (exec, next) => runtime.preExecute(exec, next));
+    ctx.commands.register({
+        name: 'rules',
+        description: 'list, reload, audit, or dry-test the active permission rules for this workspace',
+        input: { hint: '[reload | decisions [n] | test <tool> <json-args>]' },
+        handler: invocation => runtime.command(invocation),
+    });
+}
+//# sourceMappingURL=runtime.js.map