rea-agents 1.3.0 → 1.4.0

package/dist/application/CrossVersionInventory.js

@@ -8,13 +8,19 @@ import { scanAuthorizedArtifactInventory } from "./AuthorizedArtifactInventory.j
 import { ARTIFACT_GRAPH_PROVIDER } from "./InvestigationProviders.js";
 export const AUTOMATIC_RUN_LIMITATION = "Automatic cross-version runs compare shipped artifact structure only; they do not execute either version.";
 /** Authorize and scan both inputs once under the same bounded traversal policy. */
-export const scanVersions = async (input, inputRoots, signal) => {
+export const scanVersions = async (input, inputRoots, signal, integrityContinueEnabled = false) => {
     try {
         if (signal?.aborted === true)
             return err(new AnalysisCancelledError("find_changed_behavior"));
         const limits = artifactLimits(input.options);
-        const left = await scanAuthorizedArtifactInventory(input.left_path, inputRoots, limits, signal);
-        const right = await scanAuthorizedArtifactInventory(input.right_path, inputRoots, limits, signal);
+        const integrity = {
+            mode: input.integrity_policy,
+            approved: input.integrity_continue_approved,
+            enabled: integrityContinueEnabled,
+            maxMismatches: input.max_integrity_mismatches,
+        };
+        const left = await scanAuthorizedArtifactInventory(input.left_path, inputRoots, limits, signal, integrity);
+        const right = await scanAuthorizedArtifactInventory(input.right_path, inputRoots, limits, signal, integrity);
         return ok({ left, right });
     }
     catch (cause) {
@@ -25,8 +31,8 @@ export const scanVersions = async (input, inputRoots, signal) => {
 };
 /** Project complete snapshots into bounded, comparable Evidence page sets. */
 export const createInventoryEvidencePages = (input, snapshots) => {
-    const left = inventoryPages(input.left_path, snapshots.left, input.options);
-    const right = inventoryPages(input.right_path, snapshots.right, input.options);
+    const left = inventoryPages(input.left_path, snapshots.left, input);
+    const right = inventoryPages(input.right_path, snapshots.right, input);
     if (left.length > 100 || right.length > 100)
         return err(new ArtifactOperationError("inventory_artifact", "limit"));
     return ok({ left, right });
@@ -46,11 +52,13 @@ export const runLimitations = (snapshots) => [
         AUTOMATIC_RUN_LIMITATION,
     ]),
 ].sort((left, right) => left.localeCompare(right));
-const inventoryPages = (path, snapshot, options) => {
+const inventoryPages = (path, snapshot, input) => {
+    const options = input.options;
     const count = Math.max(1, Math.ceil(snapshot.nodes.length / options.page_size), Math.ceil(snapshot.occurrences.length / options.page_size), Math.ceil(snapshot.edges.length / options.page_size));
-    return Array.from({ length: count }, (_, index) => inventoryPage(path, snapshot, options, index * options.page_size));
+    return Array.from({ length: count }, (_, index) => inventoryPage(path, snapshot, input, index * options.page_size));
 };
-const inventoryPage = (path, snapshot, options, offset) => {
+const inventoryPage = (path, snapshot, input, offset) => {
+    const options = input.options;
     const result = paginateArtifactInventory(snapshot, {
         nodeOffset: offset,
         nodeLimit: options.page_size,
@@ -78,6 +86,9 @@ const inventoryPage = (path, snapshot, options, offset) => {
             max_compression_ratio: options.max_compression_ratio,
             max_depth: options.max_depth,
             max_path_bytes: options.max_path_bytes,
+            integrity_policy: input.integrity_policy,
+            integrity_continue_approved: input.integrity_continue_approved,
+            max_integrity_mismatches: input.max_integrity_mismatches,
         },
         result: jsonValueSchema.parse(result),
         rawResult: null,

package/dist/application/CrossVersionInvestigation.js

@@ -2,8 +2,8 @@ import { compareArtifacts } from "../domain/artifactComparison.js";
 import { findChangedBehavior } from "../domain/changedBehavior.js";
 import { createEvidence } from "../domain/evidence.js";
 import { createEvidenceBundle, } from "../domain/evidenceBundle.js";
-import { AnalysisInputError, EvidenceIntegrityError, InvestigationWorkspaceError, } from "../domain/errors.js";
-import { createInvestigationRunIdentity, createInvestigationWorkspace, crossVersionInvestigationInputSchema, investigationRunSchema, investigationRunSummarySchema, reviseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
+import { AnalysisCancelledError, AnalysisInputError, EvidenceIntegrityError, InvestigationWorkspaceError, } from "../domain/errors.js";
+import { createLegacyInvestigationRunIdentity, createInvestigationRunIdentity, createInvestigationWorkspace, crossVersionInvestigationInputSchema, investigationRunSchema, investigationRunSummarySchema, reviseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { AUTOMATIC_RUN_LIMITATION, createInventoryEvidencePages, runLimitations, scanVersions, targetFor, } from "./CrossVersionInventory.js";
@@ -22,15 +22,31 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
     const preflight = validateWorkspaceRequest(initial.value, parsed.data);
     if (!preflight.ok)
         return preflight;
-    const snapshots = await scanVersions(parsed.data, execution.inputRoots, execution.signal);
+    if (isCancelled(execution.signal))
+        return err(new AnalysisCancelledError("find_changed_behavior"));
+    await execution.progress?.report({
+        phase: "scan_versions",
+        completed: 0,
+        total: 4,
+        message: "Scanning both version inputs",
+    });
+    const snapshots = await scanVersions(parsed.data, execution.inputRoots, execution.signal, execution.integrityContinueEnabled);
     if (!snapshots.ok)
         return snapshots;
+    await execution.progress?.report({
+        phase: "scan_versions",
+        completed: 1,
+        total: 4,
+        message: "Version inputs scanned",
+    });
     return continueInvestigation({
         input: parsed.data,
         initial: initial.value,
         snapshots: snapshots.value,
         policy,
         session: execution.session,
+        signal: execution.signal,
+        progress: execution.progress,
     });
 };
 const continueInvestigation = async (context) => {
@@ -40,13 +56,29 @@ const continueInvestigation = async (context) => {
         left,
         right,
         options: context.input.options,
+        integrity_policy: context.input.integrity_policy,
+        integrity_continue_approved: context.input.integrity_continue_approved,
+        max_integrity_mismatches: context.input.max_integrity_mismatches,
     });
-    const existing = context.initial?.runs.find(({ run_id: id }) => id === identity.runId);
+    const legacyIdentity = createLegacyInvestigationRunIdentity({
+        left,
+        right,
+        options: context.input.options,
+    });
+    const existing = context.initial?.runs.find((run) => run.run_id === identity.runId ||
+        (context.input.integrity_policy === "fail" &&
+            !context.input.integrity_continue_approved &&
+            context.input.max_integrity_mismatches === 10 &&
+            "legacy_request_identity" in run &&
+            run.max_integrity_mismatches === 10 &&
+            run.run_id === legacyIdentity.runId));
     if (context.initial !== null && existing?.status === "complete")
         return completeOutcome(context.initial, existing, true, context.session);
     const pages = createInventoryEvidencePages(context.input, context.snapshots);
     if (!pages.ok)
         return pages;
+    if (isCancelled(context.signal))
+        return err(new AnalysisCancelledError("find_changed_behavior"));
     const inventoried = await ensureInventoryCheckpoint({
         input: context.input,
         current: context.initial,
@@ -57,11 +89,36 @@ const continueInvestigation = async (context) => {
     });
     if (!inventoried.ok)
         return inventoried;
+    await context.progress?.report({
+        phase: "inventory_versions",
+        completed: 2,
+        total: 4,
+        message: "Both artifact inventories checkpointed",
+    });
+    if (isCancelled(context.signal))
+        return err(new AnalysisCancelledError("find_changed_behavior"));
     const compared = await ensureComparisonCheckpoint(context.input, inventoried.value, context.policy);
     if (!compared.ok)
         return compared;
-    return finalizeInvestigation(context.input, compared.value, context.policy, context.session);
+    await context.progress?.report({
+        phase: "compare_artifacts",
+        completed: 3,
+        total: 4,
+        message: "Artifact comparison checkpointed",
+    });
+    if (isCancelled(context.signal))
+        return err(new AnalysisCancelledError("find_changed_behavior"));
+    const finalized = await finalizeInvestigation(context.input, compared.value, context.policy, context.session);
+    await context.progress?.report({
+        phase: "changed_behavior",
+        completed: 4,
+        total: 4,
+        message: finalized.ok ? "Investigation completed" : "Investigation failed",
+        terminal: true,
+    });
+    return finalized;
 };
+const isCancelled = (signal) => signal?.aborted === true;
 const ensureInventoryCheckpoint = async (input) => {
     if (input.existing !== undefined) {
         const consistent = validateInventoryCheckpoint(input.existing, input.pages);
@@ -77,6 +134,9 @@ const ensureInventoryCheckpoint = async (input) => {
         left,
         right,
         options: input.input.options,
+        integrity_policy: input.input.integrity_policy,
+        integrity_continue_approved: input.input.integrity_continue_approved,
+        max_integrity_mismatches: input.input.max_integrity_mismatches,
     });
     const run = investigationRunSchema.parse({
         schema_version: 1,
@@ -85,6 +145,9 @@ const ensureInventoryCheckpoint = async (input) => {
         left,
         right,
         options: input.input.options,
+        integrity_policy: input.input.integrity_policy,
+        integrity_continue_approved: input.input.integrity_continue_approved,
+        max_integrity_mismatches: input.input.max_integrity_mismatches,
         status: "running",
         completed_stages: ["inventory_left", "inventory_right"],
         left_inventory_evidence_ids: evidenceIds(input.pages.left),

package/dist/application/DirectAnalysis.js

@@ -1,14 +1,17 @@
 import { parseConfig } from "../config.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { createServerIdentity } from "../serverIdentity.js";
 import { EnhancedTools } from "./EnhancedTools.js";
 import { createBinarySession } from "./runtime.js";
 import { silentLogger } from "../logger.js";
 import { createEvidence } from "../domain/evidence.js";
-import { EvidenceIntegrityError, projectAnalysisError, } from "../domain/errors.js";
+import { EvidenceIntegrityError, AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "../domain/errors.js";
 import { access } from "node:fs/promises";
 import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "./AnalysisSnapshotFiles.js";
 import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { snapshotEvidenceForQuery, snapshotMatchesTarget, } from "../domain/analysisSnapshot.js";
 import { err, ok } from "../domain/result.js";
+import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
 const WORKFLOW_PROVIDER = {
     id: "rea-workflow",
     name: "REA composed investigation workflow",
@@ -19,12 +22,17 @@ const WORKFLOW_PROVIDER = {
  * Unlike MCP mode, every CLI invocation is intentionally isolated and does not
  * retain a target or bridge resources for a subsequent command.
  */
-export const runDirectAnalysis = async (path, tool, arguments_, options = {}) => runAnalysis(path, tool, arguments_, {
+export const runDirectAnalysis = async (path, tool, arguments_, options = {}) => withProcessCancellation(options.signal, (signal) => runAnalysis(path, tool, arguments_, {
     logger: options.logger ?? silentLogger,
     snapshotPath: options.snapshotPath,
-});
+    signal,
+}));
 /** Execute one provider-native semantic operation with atomic provenance. */
-export const runProviderAnalysis = async (path, tool, arguments_, logger = silentLogger) => runAnalysis(path, tool, arguments_, { logger, snapshotPath: undefined });
+export const runProviderAnalysis = async (path, tool, arguments_, logger = silentLogger, signal) => withProcessCancellation(signal, (operationSignal) => runAnalysis(path, tool, arguments_, {
+    logger,
+    snapshotPath: undefined,
+    signal: operationSignal,
+}));
 /** Describe configured providers without opening a target or launching Hopper. */
 export const runSessionStatus = async (logger = silentLogger) => {
     const config = parseConfig(process.env);
@@ -32,17 +40,84 @@ export const runSessionStatus = async (logger = silentLogger) => {
         return cliError(config.error);
     const session = createBinarySession(config.value, logger);
     try {
-        return session.status();
+        return {
+            ...jsonObjectSchema.parse(session.status()),
+            server_identity: createServerIdentity({
+                startedAt: new Date().toISOString(),
+            }),
+        };
     }
     finally {
         await session.close();
     }
 };
+const authorizeAnalysis = async (authority, tool, arguments_, snapshotPath) => {
+    const requests = [];
+    if (snapshotPath !== undefined) {
+        requests.push({
+            capability: "snapshot_read",
+            path: snapshotPath,
+            access: "write",
+        }, {
+            capability: "snapshot_write",
+            path: snapshotPath,
+            access: "write",
+        });
+    }
+    if (tool === "extract_artifact" && typeof arguments_.output_root === "string")
+        requests.push({
+            capability: "artifact_extract",
+            path: arguments_.output_root,
+            access: "write",
+        });
+    for (const request of requests) {
+        const result = await authority.authorize({
+            capability: request.capability,
+            roots: [request.path],
+            executables: [],
+            environment_names: [],
+            network: "none",
+            mount: false,
+            operation_identity: `${tool}:${request.capability}:${request.path}`,
+        }, request.access);
+        if (!result.ok)
+            return err(result.error instanceof PermissionRequiredError
+                ? result.error
+                : new AnalysisProtocolError(result.error.message, {
+                    cause: result.error,
+                }));
+    }
+    if (tool === "inventory_artifact" &&
+        arguments_.native_mount_approved === true) {
+        const result = await authority.authorize({
+            capability: "native_mount",
+            roots: [],
+            executables: [],
+            environment_names: [],
+            network: "none",
+            mount: true,
+            operation_identity: "inventory_artifact:native_mount",
+        }, "read");
+        if (!result.ok)
+            return err(result.error instanceof PermissionRequiredError
+                ? result.error
+                : new AnalysisProtocolError(result.error.message, {
+                    cause: result.error,
+                }));
+    }
+    return ok(null);
+};
 const runAnalysis = async (path, tool, arguments_, options) => {
-    const { logger, snapshotPath } = options;
+    const { logger, signal, snapshotPath } = options;
     const config = parseConfig(process.env);
     if (!config.ok)
         return cliError(config.error);
+    const permissionAuthority = await loadConfiguredPermissionAuthority(config.value);
+    if (!permissionAuthority.ok)
+        return cliError(permissionAuthority.error);
+    const authorized = await authorizeAnalysis(permissionAuthority.value, tool, arguments_, snapshotPath);
+    if (!authorized.ok)
+        return cliError(authorized.error);
     const unavailable = snapshotUnavailable(snapshotPath, config.value.hopperLoaderArgs);
     if (unavailable !== undefined)
         return cliError(unavailable);
@@ -61,7 +136,7 @@ const runAnalysis = async (path, tool, arguments_, options) => {
         if (prepared.value.evidence !== undefined)
             return prepared.value.evidence;
         const { snapshot } = prepared.value;
-        const opened = await session.open(path, snapshot === undefined ? {} : { snapshot });
+        const opened = await session.open(path, snapshot === undefined ? { signal } : { signal, snapshot });
         if (!opened.ok)
             return cliError(opened.error);
         let output;
@@ -69,7 +144,7 @@ const runAnalysis = async (path, tool, arguments_, options) => {
         if (tool === "binary_overview" ||
             tool === "analyze_function" ||
             tool === "trace_feature") {
-            const result = await new EnhancedTools(session).execute(tool, arguments_);
+            const result = await new EnhancedTools(session).execute(tool, arguments_, signal);
             if (!result.ok)
                 output = cliError(result.error);
             else {
@@ -86,7 +161,7 @@ const runAnalysis = async (path, tool, arguments_, options) => {
             }
         }
         else {
-            const result = await session.execute(tool, arguments_);
+            const result = await session.execute(tool, arguments_, { signal });
             if (!result.ok)
                 output = cliError(result.error);
             else {
@@ -117,6 +192,19 @@ const runAnalysis = async (path, tool, arguments_, options) => {
         await session.close();
     }
 };
+const withProcessCancellation = async (suppliedSignal, operation) => {
+    if (suppliedSignal !== undefined)
+        return operation(suppliedSignal);
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.once("SIGINT", cancel);
+    try {
+        return await operation(controller.signal);
+    }
+    finally {
+        process.off("SIGINT", cancel);
+    }
+};
 const prepareSnapshot = async (options) => {
     const { path, tool, arguments: arguments_, snapshotPath, policy, provider, } = options;
     if (snapshotPath === undefined || !(await fileExists(snapshotPath)))

package/dist/application/Doctor.js

@@ -1,6 +1,5 @@
 import { constants } from "node:fs";
-import { access } from "node:fs/promises";
-import { readdir } from "node:fs/promises";
+import { access, readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { execFile } from "node:child_process";
@@ -9,6 +8,9 @@ import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { probeHomebrew } from "./homebrew.js";
 import { linuxHopperBinarySupported, linuxHopperLauncherPath, linuxSharedLibrariesAvailable, readLinuxDistribution, } from "./LinuxHopper.js";
+import { CATALOG_IDENTITY } from "../catalogIdentity.js";
+import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js";
+import { readClientRegistrationStatuses, } from "./ClientRegistrationStatus.js";
 const execFileAsync = promisify(execFile);
 const DEFAULT_HOPPER = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
 const SYSTEM_LINUX_HOPPER = "/opt/hopper/bin/Hopper";
@@ -68,10 +70,54 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             remediation: "Supply a readable local app or program path.",
             classification: "config_drift",
         }));
+    const installationPaths = (await host.installationPaths?.()) ?? [];
+    const installedSkillVersion = await host.installedSkillVersion?.();
+    const registrations = (await host.clientRegistrations?.()) ?? [];
+    for (const registration of registrations)
+        if (registration.state !== "aligned")
+            checks.push({
+                name: `registration:${registration.client}`,
+                ok: false,
+                classification: "config_drift",
+                detail: registration.config_path,
+                remediation: registration.remediation ??
+                    "Run rea setup, then restart the affected client.",
+            });
     return {
         healthy: checks.every(({ ok }) => ok),
         ...(hopperPath === undefined ? {} : { hopperPath }),
         checks,
+        identity: {
+            cli_package_version: PRODUCT_IDENTITY.packageVersion,
+            expected_skill_version: PRODUCT_IDENTITY.skillVersion,
+            sdk: SDK_IDENTITY,
+            catalog: CATALOG_IDENTITY,
+            live_server: {
+                state: "unknown",
+                remediation: "Compare rea://server/identity or binary_session from the active client; an on-disk registration cannot prove the running server version.",
+            },
+            installations: {
+                paths: installationPaths,
+                state: installationPaths.length === 0
+                    ? "unknown"
+                    : installationPaths.length === 1
+                        ? "single"
+                        : "multiple",
+            },
+            skill: {
+                installed_version: installedSkillVersion ?? null,
+                state: installedSkillVersion === undefined
+                    ? "unknown"
+                    : installedSkillVersion === PRODUCT_IDENTITY.skillVersion
+                        ? "aligned"
+                        : "stale",
+                remediation: installedSkillVersion === undefined ||
+                    installedSkillVersion === PRODUCT_IDENTITY.skillVersion
+                    ? null
+                    : "Run rea setup to update the installed REA skill.",
+            },
+            registrations,
+        },
     };
 };
 const unsupportedHopperRemediation = (configured) => configured
@@ -157,8 +203,34 @@ export const systemDoctorHost = () => ({
         }
         return paths;
     },
+    async installationPaths() {
+        try {
+            const command = process.platform === "win32" ? "where" : "which";
+            const arguments_ = process.platform === "win32" ? ["rea"] : ["-a", "rea"];
+            return uniqueLines((await execFileAsync(command, arguments_)).stdout);
+        }
+        catch {
+            return [];
+        }
+    },
+    async installedSkillVersion() {
+        try {
+            const content = await readFile(join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"), "utf8");
+            return /^\s{2}version:\s*"([^"]+)"\s*$/mu.exec(content)?.[1];
+        }
+        catch {
+            return undefined;
+        }
+    },
+    clientRegistrations: () => readClientRegistrationStatuses(homedir()),
 });
 const parseMajor = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
+const uniqueLines = (value) => [
+    ...new Set(value
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)),
+];
 const check = (name, ok, detail, failure) => ({
     name,
     ok,

package/dist/application/PermissionAuthority.js

@@ -0,0 +1,183 @@
+import { realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { consumePermission, clearSessionPermissions, createPermissionPolicy, evaluatePermission, grantPermission, reloadPermissionCeilings, revokePermission, } from "../domain/permissionPolicy.js";
+import { PermissionRequiredError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Failure to establish a filesystem object's canonical authorization identity. */
+export class PermissionPathError extends Error {
+    path;
+    reason;
+    _tag = "PermissionPathError";
+    constructor(path, reason, options) {
+        super(`Cannot canonicalize permission path: ${path}`, options);
+        this.path = path;
+        this.reason = reason;
+    }
+}
+/** Canonicalize administrator ceilings before they become authorization state. */
+export const canonicalizePermissionCeilings = async (ceilings) => {
+    const normalized = [];
+    for (const ceiling of ceilings) {
+        const canonical = await canonicalizeScope(ceiling, "read");
+        if (!canonical.ok)
+            return canonical;
+        normalized.push(canonical.value);
+    }
+    return ok(normalized);
+};
+/** Canonicalize one exact operation request before subset evaluation. */
+export const canonicalizePermissionRequest = async (request, access) => {
+    const canonical = await canonicalizeScope(request, access);
+    return canonical.ok
+        ? ok({ ...canonical.value, operation_identity: request.operation_identity })
+        : canonical;
+};
+const canonicalizeScope = async (scope, access) => {
+    const roots = await canonicalizePaths(scope.roots, access);
+    if (!roots.ok)
+        return roots;
+    const executables = await canonicalizePaths(scope.executables, "read");
+    if (!executables.ok)
+        return executables;
+    return ok({ ...scope, roots: roots.value, executables: executables.value });
+};
+const canonicalizePaths = async (paths, access) => {
+    const canonical = [];
+    for (const path of paths) {
+        const result = await canonicalizePath(path, access);
+        if (!result.ok)
+            return result;
+        canonical.push(result.value);
+    }
+    return ok(canonical);
+};
+const canonicalizePath = async (path, access) => {
+    const requested = resolve(path);
+    try {
+        return ok(await realpath(requested));
+    }
+    catch (cause) {
+        if (access !== "write" || !isNotFound(cause))
+            return err(new PermissionPathError(path, errorReason(cause), { cause }));
+    }
+    try {
+        const parent = await realpath(dirname(requested));
+        return ok(join(parent, basename(requested)));
+    }
+    catch (cause) {
+        return err(new PermissionPathError(path, errorReason(cause), { cause }));
+    }
+};
+const isNotFound = (error) => error instanceof Error && "code" in error && error.code === "ENOENT";
+const errorReason = (error) => isNotFound(error) ? "not_found" : "io";
+/** Stateful owner for permission evaluation, consumption, reload, and revoke. */
+export class PermissionAuthority {
+    policy;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    /** Canonicalize and authorize one exact operation before its side effect. */
+    async authorize(request, access, options = {}) {
+        const evaluated = await this.explain(request, access, options);
+        if (!evaluated.ok)
+            return evaluated;
+        const decision = evaluated.value;
+        this.policy = consumePermission(this.policy, decision);
+        return ok(decision);
+    }
+    /** Dry-run the exact shared evaluation without consuming a once grant. */
+    async explain(request, access, options = {}) {
+        const canonical = await canonicalizePermissionRequest(request, access);
+        if (!canonical.ok)
+            return canonical;
+        const decision = evaluatePermission(this.policy, canonical.value);
+        if (!decision.allowed)
+            return err(new PermissionRequiredError(canonical.value, decision.missing, ceilingFor(this.policy, canonical.value.capability), options.elicitationSupported ?? false, options.restartRequired ?? false));
+        return ok(decision);
+    }
+    /** Add authority beneath the administrator ceiling. */
+    grant(grant) {
+        const result = grantPermission(this.policy, grant);
+        if (result.ok)
+            this.policy = result.value;
+        return result;
+    }
+    /** Revoke authority immediately for subsequent operations. */
+    revoke(grantId) {
+        this.policy = revokePermission(this.policy, grantId);
+    }
+    /** Drop once/session authority when its owning connection ends. */
+    clearSessionGrants() {
+        this.policy = clearSessionPermissions(this.policy);
+    }
+    /** Atomically replace optional persisted project grants. */
+    async replaceProjectGrants(grants) {
+        let candidate = {
+            ...this.policy,
+            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "project"),
+        };
+        for (const grant of grants) {
+            const canonical = await canonicalizeGrant(grant);
+            if (!canonical.ok)
+                return canonical;
+            const added = grantPermission(candidate, canonical.value);
+            if (!added.ok)
+                return err(new PermissionPathError(grant.grant_id, "io", {
+                    cause: added.error,
+                }));
+            candidate = added.value;
+        }
+        this.policy = candidate;
+        return ok(null);
+    }
+    /** Replace grants derived from the currently loaded administrator ceiling. */
+    async replaceAdministratorGrants(grants) {
+        let candidate = {
+            ...this.policy,
+            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "administrator"),
+        };
+        for (const grant of grants) {
+            const canonical = await canonicalizeGrant(grant);
+            if (!canonical.ok)
+                return canonical;
+            const added = grantPermission(candidate, canonical.value);
+            if (!added.ok)
+                return err(new PermissionPathError(grant.grant_id, "io", {
+                    cause: added.error,
+                }));
+            candidate = added.value;
+        }
+        this.policy = candidate;
+        return ok(null);
+    }
+    /** Replace ceilings without restarting the MCP process. */
+    async reload(ceilings) {
+        const canonical = await canonicalizePermissionCeilings(ceilings);
+        if (!canonical.ok)
+            return canonical;
+        this.policy = reloadPermissionCeilings(this.policy, canonical.value);
+        return ok(null);
+    }
+}
+/** Create one canonical policy and optional grants at the composition root. */
+export const createPermissionAuthority = async (ceilings, grants = []) => {
+    const canonical = await canonicalizePermissionCeilings(ceilings);
+    if (!canonical.ok)
+        return canonical;
+    let policy = createPermissionPolicy(canonical.value);
+    for (const grant of grants) {
+        const canonicalGrant = await canonicalizeGrant(grant);
+        if (!canonicalGrant.ok)
+            return canonicalGrant;
+        const added = grantPermission(policy, canonicalGrant.value);
+        if (!added.ok)
+            return err(new PermissionPathError(grant.grant_id, "io", { cause: added.error }));
+        policy = added.value;
+    }
+    return ok(new PermissionAuthority(policy));
+};
+const canonicalizeGrant = async (grant) => {
+    const scope = await canonicalizeScope(grant, "read");
+    return scope.ok ? ok({ ...grant, ...scope.value }) : scope;
+};
+const ceilingFor = (policy, capability) => policy.ceilings.find((ceiling) => ceiling.capability === capability) ?? null;