@knowttl/mg-axi 0.1.0

package/dist/msal-app-provider.js

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { ConfidentialClientApplication } from "@azure/msal-node";
+import { graphAudience } from "./app-auth.js";
+// Only this adapter touches application credentials; keys and assertions are referenced, never logged.
+export class MsalApplicationProvider {
+    storage = "session-only";
+    async acquire(profile, scopes) {
+        const configuration = {
+            auth: { clientId: profile.clientId, authority: `https://login.microsoftonline.com/${profile.tenantId}`,
+                ...(profile.credentialRef.provider === "certificate"
+                    ? { clientCertificate: { thumbprint: profile.credentialRef.thumbprint, privateKey: await this.privateKey(profile.credentialRef.key) } }
+                    : { clientAssertion: () => this.assertion() }) },
+            system: { loggerOptions: { loggerCallback: () => { }, piiLoggingEnabled: false } },
+        };
+        const result = await new ConfidentialClientApplication(configuration)
+            .acquireTokenByClientCredential({ scopes: scopes.length ? scopes : [graphAudience(profile)] });
+        if (!result)
+            throw new Error("Empty application token response");
+        if (result.authority.toLowerCase() !== `${configuration.auth.authority.toLowerCase()}/`)
+            throw new Error("Configured application authority mismatch");
+        return { token: result.accessToken, expiresAt: result.expiresOn?.getTime() ?? NaN, tenantId: profile.tenantId, clientId: profile.clientId };
+    }
+    async privateKey(key) {
+        const store = await import("keytar").then(module => module.default).catch(() => undefined);
+        this.storage = store ? "os-protected" : "session-only";
+        const material = await store?.getPassword("mg-axi", key).catch(() => null);
+        if (typeof material !== "string" || !material.trim())
+            throw new Error("Missing referenced certificate private key");
+        return material;
+    }
+    async assertion() {
+        this.storage = "session-only";
+        const file = process.env.AZURE_FEDERATED_TOKEN_FILE;
+        if (!file?.trim())
+            throw new Error("Missing federated token source");
+        // Read on every invocation: projected federated tokens rotate on disk.
+        const assertion = readFileSync(file, "utf8").trim();
+        if (!assertion)
+            throw new Error("Missing federated token source");
+        return assertion;
+    }
+}

package/dist/msal-provider.js

@@ -0,0 +1,82 @@
+import { PublicClientApplication } from "@azure/msal-node";
+import open from "open";
+// Only this adapter touches Microsoft authentication and OS credential storage.
+export class MsalProvider {
+    storage = "session-only";
+    sessions = new Map();
+    async application(profile, fresh = false) {
+        const key = JSON.stringify([profile.credentialRef.key, profile.tenantId, profile.clientId, profile.cloud]);
+        const existing = this.sessions.get(key);
+        if (existing && !fresh) {
+            this.storage = existing.store ? "os-protected" : "session-only";
+            return existing.app;
+        }
+        const store = existing ? existing.store : await import("keytar").then(module => module.default).catch(() => undefined);
+        this.storage = store ? "os-protected" : "session-only";
+        if (fresh) {
+            this.sessions.delete(key);
+            if (store) {
+                await store.deletePassword("mg-axi", key);
+                if (await store.getPassword("mg-axi", key) !== null)
+                    throw new Error("Unable to wipe profile cache");
+            }
+        }
+        const configuration = {
+            auth: { clientId: profile.clientId, authority: `https://login.microsoftonline.com/${profile.tenantId}` },
+            system: { loggerOptions: { loggerCallback: () => { }, piiLoggingEnabled: false } },
+        };
+        const app = new PublicClientApplication({
+            ...configuration,
+            cache: store ? { cachePlugin: {
+                    beforeCacheAccess: async (context) => {
+                        const saved = await store.getPassword("mg-axi", key);
+                        if (saved)
+                            context.tokenCache.deserialize(saved);
+                    },
+                    afterCacheAccess: async (context) => {
+                        if (!context.cacheHasChanged)
+                            return;
+                        const saved = context.tokenCache.serialize();
+                        if (process.platform === "win32" && Buffer.byteLength(saved, "utf8") > 2560) {
+                            await store.deletePassword("mg-axi", key);
+                            if (await store.getPassword("mg-axi", key) !== null)
+                                throw new Error("Unable to wipe profile cache");
+                            const session = new PublicClientApplication(configuration);
+                            session.getTokenCache().deserialize(saved);
+                            this.sessions.set(key, { app: session });
+                            this.storage = "session-only";
+                            return;
+                        }
+                        await store.setPassword("mg-axi", key, saved);
+                    },
+                } } : undefined,
+        });
+        this.sessions.set(key, { app, store });
+        return app;
+    }
+    async login(profile, method, scopes) {
+        // Each explicit login starts with a new client and a verified empty protected cache.
+        const app = await this.application(profile, true);
+        const result = method === "browser"
+            ? await app.acquireTokenInteractive({ scopes, openBrowser: async (url) => { await open(url); }, prompt: "select_account", errorTemplate: "Sign-in failed. Return to mg-axi for recovery guidance." })
+            : await app.acquireTokenByDeviceCode({ scopes, deviceCodeCallback: response => {
+                    if (typeof response.userCode !== "string" || !response.userCode.trim() || typeof response.deviceCode !== "string" || !response.deviceCode.trim() || !Number.isFinite(response.expiresIn) || response.expiresIn <= 0)
+                        throw new Error("Invalid device-code challenge");
+                    // The one-time user challenge belongs only to explicit login stderr.
+                    process.stderr.write(`Open https://microsoft.com/devicelogin and enter ${response.userCode}\n`);
+                } });
+        return this.result(profile, result);
+    }
+    async silent(profile, scopes) {
+        const app = await this.application(profile);
+        const accounts = (await app.getTokenCache().getAllAccounts()).filter(account => account.tenantId.toLowerCase() === profile.tenantId.toLowerCase());
+        if (accounts.length !== 1)
+            throw new Error("Explicit login required");
+        return this.result(profile, await app.acquireTokenSilent({ scopes, account: accounts[0] }));
+    }
+    result(profile, result) {
+        if (!result?.account || result.tenantId.toLowerCase() !== profile.tenantId.toLowerCase())
+            throw new Error("Configured tenant mismatch");
+        return { token: result.accessToken, expiresAt: result.expiresOn?.getTime() ?? NaN, tenantId: result.tenantId, clientId: profile.clientId, accountId: result.account.homeAccountId };
+    }
+}

package/dist/mutations.js

@@ -0,0 +1,529 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { AxiError } from "axi-sdk-js";
+import { encodeGraphPathSegment, GRAPH_HOST, redactGraphValue } from "./graph-session.js";
+import { validateApplicationProfile, validateDelegatedProfile } from "./profiles.js";
+// Shared mutation coordinator for reviewed named mutation families.
+// The gate order follows az-axi's write gates as the reference: read-only default,
+// allowWrites plus a scope allowlist, preview, --execute, --confirm,
+// --if-match and a durable journal. The shared read-only
+// scope guard in graph-session.ts stays in force for reads; write scopes are
+// requested only through this coordinator path.
+// Forced read-only beats every profile, mirroring AZ_AXI_READ_ONLY.
+export const READ_ONLY_ENV = "MG_AXI_READ_ONLY";
+export const WRITE_LOG_ENV = "MG_AXI_WRITE_LOG";
+export function readOnlyForced(env = process.env) {
+    return env[READ_ONLY_ENV] === "1";
+}
+// Mutation intents and outcomes are journaled here: MG_AXI_WRITE_LOG when
+// set, otherwise ~/.mg-axi/writes.log. A blank override falls back.
+export function resolveWriteLogPath(env = process.env) {
+    const override = env[WRITE_LOG_ENV]?.trim();
+    if (override)
+        return override;
+    return join(homedir(), ".mg-axi", "writes.log");
+}
+export const mutationFetchTransport = async (request) => {
+    const response = await fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+        signal: request.signal,
+        redirect: "manual",
+    });
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    return { status: response.status, headers, body: await response.text() };
+};
+const authorizations = new WeakMap();
+function consumeMutationAuthorization(authorization, sender) {
+    if (authorizations.get(authorization) !== sender)
+        return false;
+    authorizations.delete(authorization);
+    return true;
+}
+function assertMutationDestination(url) {
+    let destination;
+    try {
+        destination = new URL(url);
+    }
+    catch {
+        throw new AxiError("Refusing unparseable mutation destination", "DESTINATION_DENIED", [
+            "Mutation destinations must be absolute HTTPS URLs on the commercial Graph host; no credential was sent",
+        ]);
+    }
+    if (destination.protocol !== "https:" || destination.hostname.toLowerCase() !== GRAPH_HOST
+        || destination.port || destination.username || destination.password
+        || !destination.pathname.startsWith("/v1.0/")) {
+        throw new AxiError("Refusing mutation destination outside the commercial Graph host", "DESTINATION_DENIED", [
+            `Mutations must stay under https://${GRAPH_HOST}/v1.0/; no credential was sent`,
+        ]);
+    }
+}
+function mutationFailure(message, code, suggestions, details) {
+    return Object.assign(new AxiError(message, code, suggestions), { details });
+}
+export function mutationHttpStatus(error) {
+    if (error && typeof error === "object" && "details" in error) {
+        const details = error.details;
+        if (details && typeof details === "object" && "httpStatus" in details) {
+            const status = details.httpStatus;
+            if (typeof status === "number" && Number.isInteger(status) && status > 0)
+                return status;
+        }
+    }
+    return 0;
+}
+export function mutationAccepted(error) {
+    if (error && typeof error === "object" && "details" in error) {
+        const details = error.details;
+        if (details && typeof details === "object" && "accepted" in details) {
+            return details.accepted === true;
+        }
+    }
+    return false;
+}
+export function mutationGraphFault(error) {
+    if (error && typeof error === "object" && "details" in error) {
+        const details = error.details;
+        if (details && typeof details === "object") {
+            const record = details;
+            if (typeof record.graphCode === "string" || typeof record.graphMessage === "string") {
+                return { code: typeof record.graphCode === "string" ? record.graphCode : "", message: typeof record.graphMessage === "string" ? record.graphMessage : "" };
+            }
+        }
+    }
+    return null;
+}
+const mutationsNotSent = new WeakSet();
+export function mutationNotSent(error) {
+    return error instanceof Error && mutationsNotSent.has(error);
+}
+// Graph error code/message carried on mutation failures for idempotency
+// classifiers (WRITE-01 duplicate detection). Never secrets: only the
+// error code and a truncated message, matching the read faultBody shape.
+function graphFaultDetail(body) {
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        const code = typeof parsed?.error?.code === "string" ? parsed.error.code : "";
+        const message = typeof parsed?.error?.message === "string" ? parsed.error.message.slice(0, 300) : "";
+        return code || message ? { code, message } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function decodeMutationBody(response) {
+    const fault = graphFaultDetail(response.body);
+    const faultDetails = fault === null ? {} : { graphCode: fault.code, graphMessage: fault.message };
+    if (response.status === 401) {
+        throw mutationFailure(`Graph rejected the mutation credential (401)`, "AUTH_REQUIRED", [
+            "mg-axi login --profile <name> --scopes <comma-separated-Graph-scopes>",
+            "For application profiles, ask an administrator to grant application consent for the Graph .default audience",
+        ], { httpStatus: response.status });
+    }
+    if (response.status === 403) {
+        throw mutationFailure(`Graph denied the mutation (403): the grant, role, licence or policy prerequisite is missing and Graph does not say which`, "GRAPH_ERROR", [
+            "Check the catalogue permission and role guidance for this operation",
+            "A 403 never proves which prerequisite is missing; do not retry blindly",
+        ], { httpStatus: response.status });
+    }
+    if (response.status === 404) {
+        throw mutationFailure(`Graph reports the mutation target as not found or inaccessible (404); Graph does not distinguish missing from hidden`, "GRAPH_ERROR", ["Verify the bound identifier; absence is not proof of nonexistence"], { httpStatus: response.status });
+    }
+    if (response.status < 200 || response.status > 299) {
+        throw mutationFailure(`Graph mutation returned status ${response.status}`, "GRAPH_ERROR", [
+            "Read back the target before doing anything else; never replay this intent",
+        ], { httpStatus: response.status, ...faultDetails });
+    }
+    try {
+        return response.body ? JSON.parse(response.body) : {};
+    }
+    catch {
+        // The server accepted the mutation; only its response body was discarded.
+        throw mutationFailure("Graph mutation response is not valid JSON", "RESPONSE_INVALID", ["The server accepted the mutation but its response body was discarded"], { httpStatus: response.status, accepted: true });
+    }
+}
+// The authorized mutation sender. It shares credential providers and the
+// transport seam with reads while keeping mutation policy explicit: every
+// send needs a coordinator authorization minted after the write gates pass.
+// The bound profile copy is private; no profile snapshot is exposed.
+export function createMutationSender(args) {
+    const { delegated, application, transport } = args;
+    const bound = args.profile.mode === "application" ? validateApplicationProfile(args.profile) : validateDelegatedProfile(args.profile);
+    async function credential(scopes, signal) {
+        signal?.throwIfAborted();
+        if (bound.mode === "delegated") {
+            if (scopes === undefined) {
+                throw new AxiError("Delegated mutations require explicit Graph scopes", "VALIDATION_ERROR", [
+                    "Pass the operation's documented delegated permission using full https://graph.microsoft.com/ scope names",
+                ]);
+            }
+            return (await delegated.credential(validateDelegatedProfile(bound), scopes)).token;
+        }
+        if (scopes !== undefined) {
+            throw new AxiError("Application profiles use the configured Graph .default audience; delegated scopes are unavailable", "VALIDATION_ERROR", [
+                "mg-axi profile show --profile <name>",
+            ]);
+        }
+        return (await application.credential(validateApplicationProfile(bound))).token;
+    }
+    async function send(authorization, options) {
+        let handedOff = false;
+        try {
+            if (!consumeMutationAuthorization(authorization, sender)) {
+                throw new AxiError("Refusing mutation without coordinator authorization", "OPERATION_BLOCKED", [
+                    "Mutations are sent only with a coordinator authorization minted after the write gates pass; no credential was sent",
+                ]);
+            }
+            if (!["POST", "PUT", "PATCH", "DELETE"].includes(authorization.method)) {
+                throw new AxiError(`Refusing mutation with method: ${authorization.method}`, "OPERATION_BLOCKED", [
+                    "Mutations use POST, PUT, PATCH or DELETE only",
+                ]);
+            }
+            // Re-check the bound destination after authorization, before credentials.
+            assertMutationDestination(authorization.url);
+            if (options?.ifMatch !== undefined && (!options.ifMatch.trim() || /[\x00-\x1f\x7f]/.test(options.ifMatch))) {
+                throw new AxiError("Invalid If-Match value", "VALIDATION_ERROR", [
+                    "Provide the exact entity tag returned by the previewed read",
+                ]);
+            }
+            options?.signal?.throwIfAborted();
+            if (readOnlyForced()) {
+                throw new AxiError("blocked: forced read-only disables mutations", "WRITES_DISABLED", [
+                    "MG_AXI_READ_ONLY=1 overrides profile write enablement",
+                ]);
+            }
+            // Provider checks bind the acquired credential to the snapshotted
+            // tenant and client; a credential for another identity fails here and
+            // nothing is sent.
+            const token = await credential(options?.scopes, options?.signal);
+            options?.signal?.throwIfAborted();
+            assertMutationDestination(authorization.url);
+            if (readOnlyForced()) {
+                throw new AxiError("blocked: forced read-only disables mutations", "WRITES_DISABLED", [
+                    "MG_AXI_READ_ONLY=1 overrides profile write enablement",
+                ]);
+            }
+            // The request is handed to the transport here: any later failure is
+            // ambiguous (bytes may have gone out) and is never replayed.
+            handedOff = true;
+            const response = await transport({
+                method: authorization.method,
+                url: authorization.url,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: "application/json",
+                    "client-request-id": randomUUID(),
+                    ...(options?.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                    ...(options?.ifMatch !== undefined ? { "If-Match": options.ifMatch } : {}),
+                },
+                ...(options?.body !== undefined ? { body: options.body } : {}),
+                ...(options?.signal ? { signal: options.signal } : {}),
+            });
+            options?.signal?.throwIfAborted();
+            return { status: response.status, body: decodeMutationBody(response) };
+        }
+        catch (error) {
+            if (!handedOff && error instanceof Error)
+                mutationsNotSent.add(error);
+            throw error;
+        }
+    }
+    const sender = { send };
+    return sender;
+}
+function flushDirectory(path) {
+    // Node cannot open directory handles on Windows; journal fsync still
+    // applies, and recordAudit pre-creates the journal file there instead.
+    if (process.platform === "win32")
+        return;
+    const fd = openSync(path, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function serialize(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        if (value !== undefined && serialized === undefined)
+            throw new Error("Not JSON");
+        return serialized;
+    }
+    catch {
+        throw new AxiError("Mutation state or payload is not serializable", "VALIDATION_ERROR", [
+            "Provide JSON-serializable current state and payload",
+        ]);
+    }
+}
+export function createMutationCoordinator(args) {
+    const { profile, delegated, application, transport } = args;
+    const clock = args.clock ?? Date.now;
+    const journalPath = args.journalPath ?? resolveWriteLogPath();
+    const validated = profile.mode === "application" ? validateApplicationProfile(profile) : validateDelegatedProfile(profile);
+    const scope = Object.freeze({
+        tenantId: validated.tenantId,
+        allowWrites: validated.writes?.allowWrites === true,
+        operations: Object.freeze([...(validated.writes?.operations ?? [])]),
+    });
+    const sender = createMutationSender({ profile: validated, delegated, application, transport });
+    function enforceWriteGates(definition) {
+        // Gate 1: forced read-only overrides every profile.
+        // Gate 2: the profile must opt in through hand-edited configuration.
+        if (readOnlyForced() || !scope.allowWrites) {
+            throw new AxiError(`blocked: writes are disabled for this profile (${definition.method} ${definition.operation})`, "WRITES_DISABLED", [
+                "Writes are disabled for this profile",
+                "Enable named writes explicitly in the profile configuration; see README.md for the write gates",
+            ]);
+        }
+        // Classification precedes scope gating, mirroring az-axi: a malformed
+        // definition fails as VALIDATION_ERROR before membership is considered.
+        if (!definition.operation.trim()) {
+            throw new AxiError("Mutation operation must be a non-empty name", "VALIDATION_ERROR", [
+                "Name the approved operation the coordinator should authorize",
+            ]);
+        }
+        if (!definition.target.trim()) {
+            throw new AxiError("Mutation target must be a non-empty name", "VALIDATION_ERROR", [
+                "Name the exact target this mutation would change",
+            ]);
+        }
+        if (definition.version !== "v1.0") {
+            throw new AxiError(`Unsupported mutation version ${definition.version}`, "VALIDATION_ERROR", [
+                "Mutations are bound to v1.0; beta writes stay blocked",
+            ]);
+        }
+        // Gate 3: the operation must fall inside the profile's own configured scope.
+        if (!scope.operations.includes(definition.operation)) {
+            throw new AxiError(`blocked: operation '${definition.operation}' is outside the write scope of this profile (${definition.method} request)`, "OPERATION_NOT_WRITABLE", [
+                "Writes are limited to this profile's configured operations",
+                "The named write must be in the profile's writes.operations allowlist; see README.md for configuration",
+            ]);
+        }
+    }
+    function boundMutationUrl(definition) {
+        const prefix = "/v1.0/";
+        const segments = definition.path.split("/");
+        if (!definition.path.startsWith(prefix) || segments[0] !== ""
+            || segments.slice(1).some(segment => !segment || segment === "." || segment === "..")
+            || /[\s\x00-\x1f\x7f\\?#{}]/.test(definition.path)) {
+            throw new AxiError("Refusing mutation path outside the bound operation scope", "VALIDATION_ERROR", [
+                `Mutation paths must stay under ${prefix} without traversal, query strings or fragments`,
+            ]);
+        }
+        for (const segment of segments.slice(1)) {
+            if (segment === "$ref" && definition.operation === "mg.entra.group.member.add" && definition.method === "POST"
+                && /^\/v1\.0\/groups\/[^/]+\/members\/\$ref$/.test(definition.path))
+                continue;
+            let decoded;
+            try {
+                decoded = decodeURIComponent(segment);
+            }
+            catch {
+                throw new AxiError("Invalid mutation path encoding", "VALIDATION_ERROR", [
+                    "Bind one encoded resource identifier per path segment",
+                ]);
+            }
+            encodeGraphPathSegment(decoded);
+        }
+        return `https://${GRAPH_HOST}${definition.path}`;
+    }
+    function preview(definition, current, isNoop) {
+        enforceWriteGates(definition);
+        const url = boundMutationUrl(definition);
+        return Object.freeze({
+            operation: definition.operation,
+            method: definition.method,
+            url,
+            effect: definition.effect,
+            target: definition.target,
+            noop: current === undefined || isNoop === undefined ? false : isNoop(current),
+            currentState: current === undefined ? null : serialize(redactGraphValue(current)),
+            proposedChange: definition.payload === undefined ? null : serialize(redactGraphValue(definition.payload)),
+        });
+    }
+    // Metadata only: never payloads, headers, secrets or bodies.
+    function recordAudit(record) {
+        const safe = redactGraphValue({ ...record, time: new Date(clock()).toISOString() });
+        const line = JSON.stringify({ ...safe, intentKey: record.intentKey });
+        try {
+            const directory = dirname(journalPath);
+            const firstCreated = mkdirSync(directory, { recursive: true, mode: 0o700 });
+            if (firstCreated) {
+                let path = directory;
+                const parent = dirname(firstCreated);
+                while (path !== parent) {
+                    flushDirectory(path);
+                    path = dirname(path);
+                }
+                flushDirectory(parent);
+            }
+            if (process.platform === "win32" && !existsSync(journalPath)) {
+                const journal = openSync(journalPath, "a", 0o600);
+                try {
+                    fsyncSync(journal);
+                }
+                finally {
+                    closeSync(journal);
+                }
+            }
+            const lockPath = `${journalPath}.lock`;
+            const lock = openSync(lockPath, "wx", 0o600);
+            try {
+                const created = !existsSync(journalPath);
+                const journal = openSync(journalPath, "a+", 0o600);
+                try {
+                    if (record.kind === "intent") {
+                        const contents = readFileSync(journal, "utf8");
+                        if (contents && !contents.endsWith("\n"))
+                            throw new Error("Incomplete mutation journal");
+                        const records = contents.split("\n").filter(Boolean)
+                            .map(entry => JSON.parse(entry));
+                        if (records.some(entry => !entry || !["intent", "outcome"].includes(entry.kind)
+                            || typeof entry.intentKey !== "string" || !/^[a-f0-9]{64}$/.test(entry.intentKey))) {
+                            throw new Error("Invalid mutation journal");
+                        }
+                        // No automatic replay: a recreated coordinator refuses an intent
+                        // recorded without a terminal outcome, and a duplicate intent id
+                        // is never reserved twice.
+                        if (records.some(entry => entry.kind === "intent" && entry.intentKey === record.intentKey)) {
+                            throw new AxiError(`blocked: intent '${record.id}' was already reserved`, "ALREADY_EXECUTED", [
+                                `Intent '${record.id}' requires manual reconciliation; read back its target and never resend it`,
+                            ]);
+                        }
+                    }
+                    writeFileSync(journal, `${line}\n`);
+                    fsyncSync(journal);
+                    if (created)
+                        flushDirectory(directory);
+                }
+                finally {
+                    closeSync(journal);
+                }
+            }
+            finally {
+                closeSync(lock);
+                unlinkSync(lockPath);
+            }
+        }
+        catch (error) {
+            if (error instanceof AxiError && error.code === "ALREADY_EXECUTED")
+                throw error;
+            if (record.kind === "intent") {
+                throw new AxiError(`Mutation intent '${record.id}' could not be recorded`, "INTENT_NOT_RECORDED", [
+                    "The mutation was not sent",
+                    `Check the audit path ${journalPath}; a remaining lock requires manual reconciliation before removal`,
+                ]);
+            }
+            throw new AxiError(`Mutation outcome '${record.id}' could not be recorded`, "OUTCOME_NOT_RECORDED", [
+                "The mutation may have been applied; read back the target before doing anything else",
+                `Check the audit path ${journalPath}`,
+            ]);
+        }
+    }
+    function metadata(definition, seen, id, ifMatch) {
+        return {
+            id,
+            intentKey: createHash("sha256").update(id).digest("hex"),
+            profile: scope.tenantId,
+            operation: definition.operation,
+            method: definition.method,
+            url: seen.url,
+            target: definition.target,
+            effect: definition.effect,
+            ...(ifMatch !== undefined ? { ifMatch } : {}),
+        };
+    }
+    async function execute(definition, options) {
+        const body = serialize(definition.payload);
+        definition = { ...definition, ...(body === undefined ? {} : { payload: JSON.parse(body) }) };
+        options = { ...options };
+        const seen = preview(definition, await options.readState(), options.isNoop);
+        // Gate 4: without --execute the caller runs the dry run instead.
+        if (options.execute !== true)
+            return { kind: "dry-run", preview: seen };
+        // Verified already-desired state is a no-op: nothing is sent.
+        if (seen.noop)
+            return { kind: "noop", preview: seen };
+        // Gate 5: disruptive mutations need the target name back.
+        if (definition.effect === "disruptive") {
+            if (options.confirm === undefined) {
+                throw new AxiError(`blocked: disruptive ${definition.method} needs --confirm '${definition.target}'`, "CONFIRM_REQUIRED", [`Re-run with --confirm '${definition.target}'`]);
+            }
+            if (options.confirm !== definition.target) {
+                throw new AxiError(`blocked: --confirm '${options.confirm}' does not match target '${definition.target}'`, "CONFIRM_MISMATCH", [`Re-run with --confirm '${definition.target}'`]);
+            }
+        }
+        const id = options.intentId ?? randomUUID();
+        // A re-read alone is not atomic protection; conditional writes travel as
+        // If-Match only where the endpoint supports them (WRITE-N evidence).
+        const meta = metadata(definition, seen, id, options.ifMatch);
+        // Failure to record intent blocks the send.
+        recordAudit({ ...meta, kind: "intent" });
+        // Re-read before the single send; a failed re-read aborts without sending.
+        let fresh;
+        try {
+            fresh = await options.readState();
+        }
+        catch (error) {
+            recordAudit({ ...meta, kind: "outcome", httpStatus: 0, outcome: "NOT_SENT" });
+            throw error;
+        }
+        if (options.isNoop?.(fresh) === true) {
+            recordAudit({ ...meta, kind: "outcome", httpStatus: 0, outcome: "NOT_SENT" });
+            return { kind: "noop", preview: seen };
+        }
+        const authorization = Object.freeze({ nonce: randomUUID(), method: definition.method, url: seen.url });
+        authorizations.set(authorization, sender);
+        let sent;
+        try {
+            sent = await sender.send(authorization, {
+                ...(body !== undefined ? { body } : {}),
+                ...(options.ifMatch !== undefined ? { ifMatch: options.ifMatch } : {}),
+                ...(options.scopes !== undefined ? { scopes: options.scopes } : {}),
+            });
+        }
+        catch (error) {
+            if (mutationNotSent(error)) {
+                recordAudit({ ...meta, kind: "outcome", httpStatus: 0, outcome: "NOT_SENT" });
+                throw error;
+            }
+            const httpStatus = mutationHttpStatus(error);
+            if (httpStatus > 0 && mutationAccepted(error)) {
+                recordAudit({ ...meta, kind: "outcome", httpStatus, outcome: "SUCCESS" });
+                return { kind: "success", preview: seen, auditId: id, status: httpStatus, response: {} };
+            }
+            // Idempotent already-applied outcome (WRITE-01 duplicate reference):
+            // the desired state holds, so this is a no-op, not a failure. The
+            // intent still cannot replay: the recorded intent blocks any resend.
+            if (httpStatus > 0 && options.isDuplicate?.(error) === true) {
+                recordAudit({ ...meta, kind: "outcome", httpStatus, outcome: "NOOP" });
+                return { kind: "noop", preview: seen, auditId: id, duplicate: true };
+            }
+            if (httpStatus >= 400 && httpStatus < 500 && httpStatus !== 408) {
+                recordAudit({ ...meta, kind: "outcome", httpStatus, outcome: "FAILED" });
+                return { kind: "failed", preview: seen, auditId: id, status: httpStatus };
+            }
+            recordAudit({ ...meta, kind: "outcome", httpStatus, outcome: "OUTCOME_UNKNOWN" });
+            return {
+                kind: "unknown",
+                preview: seen,
+                auditId: id,
+                httpStatus,
+                guidance: `Mutation ${definition.operation} may or may not have been applied (audit ${id}); read back target '${definition.target}' before doing anything else; never replay this intent`,
+            };
+        }
+        recordAudit({ ...meta, kind: "outcome", httpStatus: sent.status, outcome: "SUCCESS" });
+        return { kind: "success", preview: seen, auditId: id, status: sent.status, response: sent.body };
+    }
+    return { scope, preview, execute };
+}