@hraness/ghostget 0.17.6 → 0.18.2

package/src/messaging-automation.ts

@@ -0,0 +1,356 @@
+import { Database, constants as sqlite } from "bun:sqlite";
+import { closeSync, constants, fstatSync, lstatSync, openSync } from "node:fs";
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { join } from "node:path";
+import { canonicalJson, sha256 } from "./canonical-json";
+import { ensurePrivateStateDirectory, ghostgetStateHome, snapshotPrivateStateDirectory } from "./storage";
+import { AUTOMATION_ACTION_KINDS, automationArray, automationDate, automationDigest, automationId, automationInteger, automationRecord, automationText, parseAutomationAction, parseAutomationActionKind, parseAutomationCoordinate, parseAutomationIdentity, parseAutomationMessage } from "./messaging-automation-validation";
+import type { AutomationConversation, AutomationEnrollment, AutomationEvent, AutomationGrant, AutomationGrantRequest, AutomationIdentity, AutomationPlan, AutomationPlanRequest, AutomationProviderPage, AutomationProviderSendResult, AutomationRun, MessagingAutomationProvider } from "./messaging-automation-types";
+export * from "./messaging-automation-types";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+type StoredEnrollment = { id: string; data: string; cursor: string; revision: number; ready: number; baselining: number; gap: number; reason: string | null };
+type StoredGrant = { id: string; data: string; revoked: number; consumed: number; last_dispatch: number };
+type StoredRun = { id: string; plan_id: string; intent_id: string; enrollment_id: string; state: AutomationRun["state"]; accepted: string; total: number; reason: string | null };
+const RUN_COLUMNS = "id,plan_id,intent_id,enrollment_id,state,accepted,total,reason";
+const same = (a: unknown, b: unknown) => canonicalJson(a) === canonicalJson(b);
+const authority = (identity: AutomationIdentity, selected: AutomationConversation) => ({ identity, conversation: { ...selected, title: null } });
+const sameConversation = (a: AutomationConversation, b: AutomationConversation) => same({ ...a, title: null }, { ...b, title: null });
+const stopped = (signal?: AbortSignal) => { if (signal?.aborted) throw new Error("Messaging automation operation was cancelled."); };
+const CAPACITY = Object.freeze({ enrollments: 1000, grants: 10000, plans: 20000, runs: 20000, messages: 50000, events: 50000 });
+function grantData(value: unknown): AutomationGrantRequest {
+  const r = automationRecord(value, ["enrollmentId", "expectedBindingDigest", "actions", "expiresAt", "maximumActions", "minimumIntervalMs"]);
+  const actions = automationArray(r.actions, AUTOMATION_ACTION_KINDS.length).map(parseAutomationActionKind);
+  if (actions.length === 0 || new Set(actions).size !== actions.length) throw new Error("Messaging grant action list is invalid.");
+  return Object.freeze({ enrollmentId: automationId(r.enrollmentId), expectedBindingDigest: automationDigest(r.expectedBindingDigest), actions: Object.freeze(actions), expiresAt: automationDate(r.expiresAt), maximumActions: automationInteger(r.maximumActions, 1, 100000), minimumIntervalMs: automationInteger(r.minimumIntervalMs, 0, 86400000) });
+}
+function planData(value: unknown): AutomationPlan {
+  const r = automationRecord(value, ["enrollmentId", "expectedRevision", "intentId", "actions", "bindingDigest", "expiresAt", "id", "digest"]);
+  const actions = automationArray(r.actions, 8).map(parseAutomationAction);
+  if (actions.length === 0 || Buffer.byteLength(canonicalJson(actions)) > 256 * 1024) throw new Error("Messaging plan exceeds its bound.");
+  const binding = { enrollmentId: automationId(r.enrollmentId), expectedRevision: automationInteger(r.expectedRevision, 0, Number.MAX_SAFE_INTEGER), intentId: automationId(r.intentId), actions: Object.freeze(actions), bindingDigest: automationDigest(r.bindingDigest), expiresAt: automationDate(r.expiresAt) };
+  const digest = automationDigest(r.digest); const id = automationId(r.id);
+  if (sha256(canonicalJson(binding)) !== digest || id !== `plan:${digest}`) throw new Error("Messaging plan binding is invalid.");
+  return Object.freeze({ ...binding, id, digest });
+}
+
+function conversation(value: unknown): AutomationConversation {
+  const r = automationRecord(value, ["coordinate", "title", "kind", "participants"]);
+  const coordinate = parseAutomationCoordinate(r.coordinate);
+  const participants = automationArray(r.participants, 2).map(value => automationText(value, 512));
+  if (r.kind !== "single" || participants.length < 1 || new Set(participants).size !== participants.length) throw new Error("Messaging automation requires one verified individual conversation.");
+  return Object.freeze({ coordinate, title: r.title === null ? null : automationText(r.title, 512), kind: "single", participants: Object.freeze([...participants].sort()) });
+}
+function checkedPage(value: unknown, expected: AutomationIdentity, coordinate: AutomationConversation["coordinate"]): AutomationProviderPage {
+  const r = automationRecord(value, ["identity", "messages", "nextCursor", "caughtUp", "gap"]);
+  const identity = parseAutomationIdentity(r.identity);
+  if (!same(identity, expected) || typeof r.caughtUp !== "boolean" || typeof r.gap !== "boolean") throw new Error("Messaging provider identity or cursor state changed.");
+  const messages = automationArray(r.messages, 500).map(parseAutomationMessage);
+  if (messages.some(message => !same(message.coordinate, coordinate))) throw new Error("Messaging provider returned another conversation.");
+  return Object.freeze({ identity, messages: Object.freeze(messages), nextCursor: automationText(r.nextCursor, 4096), caughtUp: r.caughtUp, gap: r.gap });
+}
+function checkedResult(value: unknown): AutomationProviderSendResult {
+  if (typeof value !== "object" || value === null) throw new Error("Messaging provider result is invalid.");
+  const state = Object.getOwnPropertyDescriptor(value, "state")?.value;
+  if (state === "accepted") {
+    const r = automationRecord(value, ["state", "messageId", "providerReceiptId", "delivery"]);
+    if (r.delivery !== "unknown") throw new Error("Messaging provider delivery claim is unsupported.");
+    return { state, messageId: r.messageId === null ? null : automationId(r.messageId), providerReceiptId: r.providerReceiptId === null ? null : automationId(r.providerReceiptId), delivery: "unknown" };
+  }
+  const r = automationRecord(value, ["state", "reason"]);
+  if (state !== "not-started" && state !== "indeterminate") throw new Error("Messaging provider result is invalid.");
+  return { state, reason: automationText(r.reason, 1024) };
+}
+
+/**
+ * Durable host coordination, not a model runtime or a replacement permission policy.
+ * The owner invokes grant/revoke through Ghostget's private control boundary. A grant
+ * narrows an already permitted provider operation to one immutable conversation.
+ * Multiple processes are serialized at each durable claim; an unresolved run fences
+ * its enrollment across restarts. No startup path clears uncertain dispatch state.
+ */
+export class MessagingAutomationHost {
+  private readonly db: Database;
+  private readonly directory: string;
+  private readonly directoryIdentity: ReturnType<typeof ensurePrivateStateDirectory>;
+  private readonly fileIdentity: { dev: number; ino: number };
+  private readonly providers = new Map<string, MessagingAutomationProvider>();
+  private readonly cursorKey: Buffer;
+  private readonly controllers = new Set<AbortController>();
+  private readonly planControllers = new Map<string, Set<AbortController>>();
+  private readonly pending = new Set<Promise<unknown>>();
+  private closing = false;
+  private closed = false;
+  constructor(providers: readonly MessagingAutomationProvider[], private readonly environment: Environment = process.env, private readonly now: () => number = Date.now) {
+    if (providers.length > 16) throw new Error("Too many messaging providers.");
+    for (const provider of providers) {
+      if (this.providers.has(provider.provider)) throw new Error("Duplicate messaging provider.");
+      this.providers.set(provider.provider, provider);
+    }
+    this.directory = join(ghostgetStateHome(environment), "messaging", "automation");
+    this.directoryIdentity = ensurePrivateStateDirectory(this.directory, environment);
+    const path = join(this.directory, "host.sqlite");
+    const fd = openSync(path, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+    try { const stat = fstatSync(fd); if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600 || stat.nlink !== 1) throw new Error("Unsafe messaging journal."); this.fileIdentity = { dev: stat.dev, ino: stat.ino }; } finally { closeSync(fd); }
+    this.checkFiles();
+    this.db = new Database(path, sqlite.SQLITE_OPEN_READWRITE | sqlite.SQLITE_OPEN_NOFOLLOW);
+    try {
+      this.db.exec("PRAGMA busy_timeout=250; PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL; PRAGMA trusted_schema=OFF; PRAGMA secure_delete=ON; PRAGMA max_page_count=65536;");
+      const version = this.db.query<{ user_version: number }, []>("PRAGMA user_version").get()?.user_version;
+      if (version !== 0 && version !== 1 && version !== 2) throw new Error("Unsupported messaging journal schema.");
+      this.db.exec("CREATE TABLE IF NOT EXISTS metadata (key TEXT PRIMARY KEY,value TEXT NOT NULL); CREATE TABLE IF NOT EXISTS enrollments (id TEXT PRIMARY KEY,data TEXT NOT NULL,cursor TEXT NOT NULL,revision INTEGER NOT NULL,ready INTEGER NOT NULL,reason TEXT); CREATE TABLE IF NOT EXISTS grants (id TEXT PRIMARY KEY,data TEXT NOT NULL,revoked INTEGER NOT NULL,consumed INTEGER NOT NULL,last_dispatch INTEGER NOT NULL); CREATE TABLE IF NOT EXISTS plans (id TEXT PRIMARY KEY,data TEXT NOT NULL); CREATE TABLE IF NOT EXISTS runs (id TEXT PRIMARY KEY,plan_id TEXT NOT NULL,intent_id TEXT NOT NULL UNIQUE,enrollment_id TEXT NOT NULL,state TEXT NOT NULL,accepted TEXT NOT NULL,total INTEGER NOT NULL,reason TEXT); CREATE INDEX IF NOT EXISTS runs_contact ON runs(enrollment_id,state); CREATE TABLE IF NOT EXISTS messages (enrollment_id TEXT NOT NULL,event_key TEXT NOT NULL,data TEXT NOT NULL,PRIMARY KEY(enrollment_id,event_key)); CREATE TABLE IF NOT EXISTS events (seq INTEGER PRIMARY KEY AUTOINCREMENT,enrollment_id TEXT NOT NULL,revision INTEGER NOT NULL,data TEXT NOT NULL);");
+      // Upgrading an old cursor establishes a fresh live boundary. It must not
+      // turn its unconsumed historical backlog into new automatic replies.
+      if (version !== 2) this.db.transaction(() => {
+        this.db.exec("ALTER TABLE enrollments ADD COLUMN baselining INTEGER NOT NULL DEFAULT 1; ALTER TABLE enrollments ADD COLUMN gap INTEGER NOT NULL DEFAULT 0; UPDATE enrollments SET gap=CASE WHEN reason LIKE '%unresolved gap%' THEN 1 ELSE 0 END,ready=0; PRAGMA user_version=2;");
+      }).immediate();
+      else this.db.exec("PRAGMA user_version=2;");
+      this.db.exec("CREATE TABLE IF NOT EXISTS grant_intents (id TEXT PRIMARY KEY,request_digest TEXT NOT NULL,grant_id TEXT NOT NULL UNIQUE REFERENCES grants(id));");
+      this.db.query("INSERT OR IGNORE INTO metadata(key,value) VALUES('cursor-key',?)").run(randomBytes(32).toString("hex"));
+      this.cursorKey = Buffer.from(automationDigest(this.db.query<{ value: string }, []>("SELECT value FROM metadata WHERE key='cursor-key'").get()?.value), "hex");
+      this.checkFiles();
+    } catch (error) { this.db.close(); throw error; }
+  }
+  private checkFiles(): void {
+    snapshotPrivateStateDirectory(this.directory, this.environment, this.directoryIdentity);
+    for (const name of ["host.sqlite", "host.sqlite-journal", "host.sqlite-wal", "host.sqlite-shm"]) {
+      let stat: ReturnType<typeof lstatSync>; try { stat = lstatSync(join(this.directory, name)); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT" && name !== "host.sqlite") continue; throw error; }
+      if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600 || stat.nlink !== 1 || name.endsWith("-wal") || name.endsWith("-shm")
+        || (name === "host.sqlite" && (stat.dev !== this.fileIdentity.dev || stat.ino !== this.fileIdentity.ino))) throw new Error("Messaging journal filesystem identity changed.");
+    }
+  }
+  private ready(): void { if (this.closing || this.closed) throw new Error("Messaging automation host is closed."); this.checkFiles(); }
+  private capacity(table: keyof typeof CAPACITY, additional = 1): void {
+    const count = this.db.query<{ n: number }, []>(`SELECT COUNT(*) AS n FROM ${table}`).get()!.n;
+    const pages = this.db.query<{ page_count: number }, []>("PRAGMA page_count").get()!.page_count;
+    const size = this.db.query<{ page_size: number }, []>("PRAGMA page_size").get()!.page_size;
+    // Keep substantial physical headroom for dispatch/result journals. Nothing
+    // evicts receipts or advances consumer cursors silently when the bound fills.
+    if (count + additional > CAPACITY[table] || pages * size >= 192 * 1024 * 1024) throw new Error("Messaging journal capacity reached; owner maintenance is required before further dispatch.");
+  }
+  private provider(id: string): MessagingAutomationProvider { const provider = this.providers.get(id); if (provider === undefined) throw new Error("Messaging provider is unavailable."); return provider; }
+  private row(id: string): StoredEnrollment { this.ready(); const row = this.db.query<StoredEnrollment, [string]>("SELECT * FROM enrollments WHERE id=?").get(automationId(id)); if (row === null) throw new Error("Messaging enrollment does not exist."); return row; }
+  private enrollment(row: StoredEnrollment): AutomationEnrollment {
+    const r = automationRecord(JSON.parse(row.data) as unknown, ["identity", "conversation", "bindingDigest"]);
+    const identity = parseAutomationIdentity(r.identity); const selected = conversation(r.conversation); const bindingDigest = automationDigest(r.bindingDigest);
+    if (sha256(canonicalJson(authority(identity, selected))) !== bindingDigest) throw new Error("Messaging enrollment binding is invalid.");
+    const ready = automationInteger(row.ready, 0, 1); const baselining = automationInteger(row.baselining, 0, 1); const gap = automationInteger(row.gap, 0, 1);
+    if (ready && (baselining || gap)) throw new Error("Messaging enrollment readiness is inconsistent.");
+    return Object.freeze({ id: automationId(row.id), identity, conversation: selected, bindingDigest, revision: automationInteger(row.revision, 0, Number.MAX_SAFE_INTEGER), ready: ready === 1, reason: row.reason === null ? null : automationText(row.reason, 1024) });
+  }
+  enrollments(): readonly AutomationEnrollment[] { this.ready(); return this.db.query<StoredEnrollment, []>("SELECT * FROM enrollments ORDER BY id LIMIT 1001").all().map(row => this.enrollment(row)); }
+  private async status(provider: MessagingAutomationProvider, signal?: AbortSignal) {
+    stopped(signal); const value = await provider.inspect(signal); stopped(signal);
+    const r = automationRecord(value, ["identity", "connected", "events", "actions"]); const identity = parseAutomationIdentity(r.identity);
+    if (identity.provider !== provider.provider || typeof r.connected !== "boolean") throw new Error("Messaging provider identity is invalid.");
+    const actions = automationRecord(r.actions, AUTOMATION_ACTION_KINDS);
+    for (const capability of [r.events, ...Object.values(actions)]) { const c = automationRecord(capability, ["available", "reason"]); if (typeof c.available !== "boolean") throw new Error("Messaging capability is invalid."); if (c.reason !== null) automationText(c.reason, 1024); }
+    return value;
+  }
+  async providerStatus(id: string, signal?: AbortSignal) {
+    this.ready(); return this.status(this.provider(automationId(id)), signal);
+  }
+  async conversations(raw: Readonly<{ provider: string; limit: number }>, signal?: AbortSignal) {
+    this.ready(); const r = automationRecord(raw, ["provider", "limit"]);
+    const provider = this.provider(automationId(r.provider)), limit = automationInteger(r.limit, 1, 200);
+    const status = await this.status(provider, signal);
+    const result = automationRecord(await provider.conversations({ limit }, signal), ["identity", "conversations", "complete"]); stopped(signal);
+    const identity = parseAutomationIdentity(result.identity);
+    if (!same(identity, status.identity) || typeof result.complete !== "boolean") throw new Error("Messaging discovery identity changed.");
+    const rows = automationArray(result.conversations, limit).filter(value => automationRecord(value, ["coordinate", "title", "kind", "participants"]).kind === "single").map(conversation);
+    if (rows.some(row => row.coordinate.provider !== identity.provider) || new Set(rows.map(row => canonicalJson(row.coordinate))).size !== rows.length) throw new Error("Messaging discovery contains conflicting conversations.");
+    return Object.freeze({ identity, conversations: Object.freeze(rows), complete: result.complete });
+  }
+  history(raw: Readonly<{ enrollmentId: string; limit: number }>) {
+    this.ready(); const r = automationRecord(raw, ["enrollmentId", "limit"]), limit = automationInteger(r.limit, 1, 200);
+    const enrollment = this.enrollment(this.row(automationId(r.enrollmentId)));
+    const rows = this.db.query<{ data: string }, [string, number]>("SELECT data FROM messages WHERE rowid IN (SELECT MAX(rowid) FROM messages WHERE enrollment_id=? GROUP BY json_extract(data,'$.id')) ORDER BY json_extract(data,'$.occurredAt') DESC,rowid DESC LIMIT ?").all(enrollment.id, limit);
+    const messages = rows.map(row => parseAutomationMessage(JSON.parse(row.data) as unknown)).reverse();
+    if (messages.some(message => !same(message.coordinate, enrollment.conversation.coordinate))) throw new Error("Messaging stored history has another conversation.");
+    return Object.freeze({ enrollment, messages: Object.freeze(messages) });
+  }
+  async enroll(raw: Readonly<{ provider: string; coordinate: unknown }>, signal?: AbortSignal): Promise<AutomationEnrollment> {
+    this.ready(); const request = automationRecord(raw, ["provider", "coordinate"]); const coordinate = parseAutomationCoordinate(request.coordinate);
+    if (request.provider !== coordinate.provider) throw new Error("Messaging provider and coordinate disagree.");
+    const provider = this.provider(coordinate.provider); const status = await this.status(provider, signal);
+    const resolved = await provider.resolve(coordinate, signal); stopped(signal);
+    if (!same(parseAutomationIdentity(resolved.identity), status.identity)) throw new Error("Messaging identity changed during enrollment.");
+    const selected = conversation(resolved.conversation); if (!same(selected.coordinate, coordinate)) throw new Error("Messaging route resolution changed target.");
+    const history = checkedPage(await provider.history({ coordinate, limit: 200 }, signal), status.identity, coordinate); stopped(signal);
+    const binding = { identity: status.identity, conversation: selected }; const bindingDigest = sha256(canonicalJson(authority(status.identity, selected)));
+    const id = `enrollment:${randomUUID()}`;
+    this.ready(); this.db.transaction(() => {
+      this.capacity("enrollments"); this.capacity("messages", history.messages.length);
+      if (this.enrollments().some(enrollment => same(enrollment.identity, status.identity) && same(enrollment.conversation.coordinate, coordinate))) throw new Error("Conversation is already enrolled.");
+      this.db.query("INSERT INTO enrollments(id,data,cursor,revision,ready,reason,baselining,gap) VALUES(?,?,?,0,?,?,?,?)").run(id, canonicalJson({ ...binding, bindingDigest }), history.nextCursor, !history.gap && history.caughtUp ? 1 : 0, history.gap ? "Provider history has an unresolved gap." : history.caughtUp ? null : "Initial history catchup is incomplete.", history.caughtUp ? 0 : 1, history.gap ? 1 : 0);
+      for (const message of history.messages) this.db.query("INSERT OR IGNORE INTO messages VALUES(?,?,?)").run(id, sha256(canonicalJson(message)), canonicalJson(message));
+    }).immediate(); this.checkFiles();
+    return this.enrollment(this.row(id));
+  }
+  grant(raw: AutomationGrantRequest, intent?: string): AutomationGrant {
+    this.ready(); const r = automationRecord(raw, ["enrollmentId", "expectedBindingDigest", "actions", "expiresAt", "maximumActions", "minimumIntervalMs"]);
+    const enrollment = this.enrollment(this.row(automationId(r.enrollmentId))); const expectedBindingDigest = automationDigest(r.expectedBindingDigest);
+    if (enrollment.bindingDigest !== expectedBindingDigest) throw new Error("Messaging enrollment changed before grant issuance.");
+    const actions = automationArray(r.actions, AUTOMATION_ACTION_KINDS.length).map(parseAutomationActionKind);
+    if (actions.length === 0 || new Set(actions).size !== actions.length) throw new Error("Messaging grant action list is invalid.");
+    const expiresAt = automationDate(r.expiresAt);
+    const grant = { enrollmentId: enrollment.id, expectedBindingDigest, actions: [...actions].sort(), expiresAt, maximumActions: automationInteger(r.maximumActions, 1, 100000), minimumIntervalMs: automationInteger(r.minimumIntervalMs, 0, 86400000) };
+    const intentId = intent === undefined ? null : automationId(intent), digest = sha256(canonicalJson(grant));
+    const result = this.db.transaction(() => {
+      if (intentId !== null) {
+        const previous = this.db.query<{ request_digest: string; grant_id: string }, [string]>("SELECT request_digest,grant_id FROM grant_intents WHERE id=?").get(intentId);
+        if (previous) {
+          if (automationDigest(previous.request_digest) !== digest) throw new Error("Messaging grant intent changed its request.");
+          return this.grantStatus(previous.grant_id);
+        }
+      }
+      if (Date.parse(expiresAt) <= this.now() || Date.parse(expiresAt) > this.now() + 30 * 86400000) throw new Error("Messaging grant must expire within 30 days.");
+      const id = `grant:${randomUUID()}`;
+      this.capacity("grants"); this.db.query("INSERT INTO grants VALUES(?,?,0,0,0)").run(id, canonicalJson(grant));
+      if (intentId !== null) this.db.query("INSERT INTO grant_intents VALUES(?,?,?)").run(intentId, digest, id);
+      return Object.freeze({ ...grant, id, revoked: false, consumedActions: 0 });
+    }).immediate(); this.checkFiles(); return result;
+  }
+  /** Resolves uncertain grant creation without issuing or renewing authority. */
+  grantByIntent(intentId: string): AutomationGrant | null {
+    this.ready(); const row = this.db.query<{ grant_id: string }, [string]>("SELECT grant_id FROM grant_intents WHERE id=?").get(automationId(intentId));
+    return row === null ? null : this.grantStatus(row.grant_id);
+  }
+  revoke(id: string): void { this.ready(); if (this.db.query("UPDATE grants SET revoked=1 WHERE id=?").run(automationId(id)).changes !== 1) throw new Error("Messaging grant does not exist."); this.checkFiles(); }
+  grantStatus(id: string): AutomationGrant {
+    this.ready(); const row = this.db.query<StoredGrant, [string]>("SELECT * FROM grants WHERE id=?").get(automationId(id));
+    if (row === null) throw new Error("Messaging grant does not exist.");
+    const grant = grantData(JSON.parse(row.data) as unknown);
+    return Object.freeze({ ...grant, id: automationId(row.id), revoked: automationInteger(row.revoked, 0, 1) === 1, consumedActions: automationInteger(row.consumed, 0, grant.maximumActions) });
+  }
+  private activeRun(enrollmentId: string): boolean { return this.db.query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM runs WHERE enrollment_id=? AND state IN ('started','partial','indeterminate')").get(enrollmentId)!.n > 0; }
+  async poll(enrollmentId: string, signal?: AbortSignal): Promise<AutomationEnrollment> {
+    const initial = this.row(enrollmentId); const enrollment = this.enrollment(initial);
+    if (this.activeRun(enrollmentId)) return enrollment;
+    const provider = this.provider(enrollment.identity.provider); const status = await this.status(provider, signal);
+    if (!same(status.identity, enrollment.identity)) { this.db.query("UPDATE enrollments SET ready=0,reason=? WHERE id=?").run("Provider identity changed; enroll the conversation again.", enrollmentId); throw new Error("Messaging provider identity changed."); }
+    if (!status.connected || !status.events.available) { this.db.query("UPDATE enrollments SET ready=0,reason=? WHERE id=?").run(status.events.reason ?? "Provider events are unavailable.", enrollmentId); return this.enrollment(this.row(enrollmentId)); }
+    const page = checkedPage(await provider.events({ coordinates: [enrollment.conversation.coordinate], cursor: initial.cursor, limit: 200 }, signal), enrollment.identity, enrollment.conversation.coordinate); stopped(signal);
+    this.ready(); this.db.transaction(() => {
+      const current = this.row(enrollmentId); if (current.cursor !== initial.cursor || current.revision !== initial.revision || current.baselining !== initial.baselining || current.gap !== initial.gap || this.activeRun(enrollmentId)) throw new Error("Messaging poll lost its concurrent cursor claim.");
+      this.capacity("messages", page.messages.length); if (!initial.baselining) this.capacity("events", page.messages.length);
+      let revision = initial.revision;
+      for (const [index, message] of page.messages.entries()) {
+        const data = canonicalJson(message);
+        const previous = this.db.query<{ data: string }, [string, string]>("SELECT data FROM messages WHERE enrollment_id=? AND json_extract(data,'$.id')=? ORDER BY rowid DESC LIMIT 1").get(enrollmentId, message.id);
+        if (previous?.data === data) continue;
+        // A→B→A is another change, not a lifetime duplicate. The provider cursor
+        // and page position identify this observation while latest state dedups
+        // overlap at page boundaries.
+        this.db.query("INSERT INTO messages VALUES(?,?,?)").run(enrollmentId, sha256(canonicalJson({ cursor: page.nextCursor, index, message })), data);
+        if (initial.baselining === 1) continue;
+        revision = automationInteger(revision + 1, 1, Number.MAX_SAFE_INTEGER);
+        this.db.query("INSERT INTO events(enrollment_id,revision,data) VALUES(?,?,?)").run(enrollmentId, revision, data);
+      }
+      const gap = initial.gap === 1 || page.gap;
+      this.db.query("UPDATE enrollments SET cursor=?,revision=?,ready=?,reason=?,baselining=?,gap=? WHERE id=?").run(page.nextCursor, revision, !gap && page.caughtUp ? 1 : 0, gap ? "Provider event stream has an unresolved gap." : page.caughtUp ? null : "Provider catchup is incomplete.", initial.baselining && !page.caughtUp ? 1 : 0, gap ? 1 : 0, enrollmentId);
+    }).immediate(); this.checkFiles(); return this.enrollment(this.row(enrollmentId));
+  }
+  events(raw: Readonly<{ enrollmentIds: readonly string[]; cursor: string | null; limit: number }>): Readonly<{ events: readonly AutomationEvent[]; nextCursor: string; caughtUp: boolean }> {
+    this.ready(); const r = automationRecord(raw, ["enrollmentIds", "cursor", "limit"]); const ids = automationArray(r.enrollmentIds, 100).map(automationId).sort();
+    if (ids.length === 0 || new Set(ids).size !== ids.length) throw new Error("Messaging event selection is invalid.");
+    for (const id of ids) this.row(id);
+    const limit = automationInteger(r.limit, 1, 500); const fingerprint = sha256(canonicalJson(ids)); let after = 0;
+    if (r.cursor !== null) {
+      const cursor = automationText(r.cursor, 4096); const [payload, signature, extra] = cursor.split(".");
+      if (payload === undefined || signature === undefined || extra !== undefined || !/^[a-f0-9]{64}$/u.test(signature)) throw new Error("Messaging cursor is invalid.");
+      const mac = createHmac("sha256", this.cursorKey).update(payload).digest(); if (!timingSafeEqual(Buffer.from(signature, "hex"), mac)) throw new Error("Messaging cursor is invalid.");
+      const decoded = automationRecord(JSON.parse(Buffer.from(payload, "base64url").toString()) as unknown, ["fingerprint", "after"]);
+      if (decoded.fingerprint !== fingerprint) throw new Error("Messaging cursor belongs to a different contact selection."); after = automationInteger(decoded.after, 0, Number.MAX_SAFE_INTEGER);
+    }
+    const rows = this.db.query<{ seq: number; enrollment_id: string; revision: number; data: string }, (string | number)[]>(`SELECT seq,enrollment_id,revision,data FROM events WHERE seq>? AND enrollment_id IN (${ids.map(() => "?").join(",")}) ORDER BY seq LIMIT ?`).all(after, ...ids, limit + 1);
+    const selected = rows.slice(0, limit); const payload = Buffer.from(canonicalJson({ fingerprint, after: selected.at(-1)?.seq ?? after })).toString("base64url");
+    return Object.freeze({ events: Object.freeze(selected.map(row => Object.freeze({ sequence: row.seq, enrollmentId: row.enrollment_id, revision: row.revision, message: parseAutomationMessage(JSON.parse(row.data) as unknown) }))), nextCursor: `${payload}.${createHmac("sha256", this.cursorKey).update(payload).digest("hex")}`, caughtUp: rows.length <= limit });
+  }
+  prepare(raw: AutomationPlanRequest): AutomationPlan {
+    this.ready(); const r = automationRecord(raw, ["enrollmentId", "expectedRevision", "intentId", "actions"]);
+    const enrollment = this.enrollment(this.row(automationId(r.enrollmentId))); const expectedRevision = automationInteger(r.expectedRevision, 0, Number.MAX_SAFE_INTEGER);
+    if (!enrollment.ready || enrollment.revision !== expectedRevision) throw new Error("Messaging context is stale or unavailable.");
+    const actions = automationArray(r.actions, 8).map(parseAutomationAction); if (actions.length === 0) throw new Error("Messaging plan is empty.");
+    if (Buffer.byteLength(canonicalJson(actions)) > 256 * 1024) throw new Error("Messaging plan exceeds its byte bound.");
+    const intentId = automationId(r.intentId); const binding = { enrollmentId: enrollment.id, expectedRevision, intentId, actions, bindingDigest: enrollment.bindingDigest, expiresAt: new Date(this.now() + 120000).toISOString() };
+    const digest = sha256(canonicalJson(binding)); const plan = Object.freeze({ ...binding, id: `plan:${digest}`, digest });
+    this.db.transaction(() => { this.capacity("plans"); this.db.query("INSERT OR IGNORE INTO plans VALUES(?,?)").run(plan.id, canonicalJson(plan)); }).immediate(); this.checkFiles(); return plan;
+  }
+  private runProjection(row: StoredRun): AutomationRun {
+    const accepted = automationArray(JSON.parse(row.accepted) as unknown, 8).map(value => { const r = automationRecord(value, ["messageId", "providerReceiptId"]); return Object.freeze({ messageId: r.messageId === null ? null : automationId(r.messageId), providerReceiptId: r.providerReceiptId === null ? null : automationId(r.providerReceiptId) }); });
+    const totalActions = automationInteger(row.total, 1, 8);
+    if (!["started", "accepted", "failed", "partial", "indeterminate"].includes(row.state) || accepted.length > totalActions || (row.state === "accepted" && accepted.length !== totalActions) || (row.state === "failed" && accepted.length !== 0)) throw new Error("Messaging run state is inconsistent.");
+    return Object.freeze({ id: automationId(row.id), planId: automationId(row.plan_id), intentId: automationId(row.intent_id), enrollmentId: automationId(row.enrollment_id), state: row.state, accepted: Object.freeze(accepted), totalActions, reason: row.reason === null ? null : automationText(row.reason, 1024), retryable: false });
+  }
+  run(id: string): AutomationRun { this.ready(); const row = this.db.query<StoredRun, [string]>(`SELECT ${RUN_COLUMNS} FROM runs WHERE id=?`).get(automationId(id)); if (row === null) throw new Error("Messaging run does not exist."); return this.runProjection(row); }
+  cancel(planId: string): boolean {
+    this.ready(); const controllers = this.planControllers.get(automationId(planId));
+    if (controllers === undefined) return false;
+    for (const controller of controllers) controller.abort(); return true;
+  }
+  submit(raw: Readonly<{ planId: string; grantId: string }>, signal?: AbortSignal): Promise<AutomationRun> {
+    this.ready(); const r = automationRecord(raw, ["planId", "grantId"]); const controller = new AbortController(); const abort = () => controller.abort(); signal?.addEventListener("abort", abort, { once: true }); if (signal?.aborted) controller.abort(); this.controllers.add(controller);
+    const planId = automationId(r.planId), grantId = automationId(r.grantId);
+    const owned = this.planControllers.get(planId) ?? new Set<AbortController>(); owned.add(controller); this.planControllers.set(planId, owned);
+    const operation = this.dispatch(planId, grantId, controller.signal);
+    this.pending.add(operation); void operation.finally(() => { signal?.removeEventListener("abort", abort); this.controllers.delete(controller); owned.delete(controller); if (!owned.size) this.planControllers.delete(planId); this.pending.delete(operation); }).catch(() => undefined); return operation;
+  }
+  private async dispatch(planId: string, grantId: string, signal: AbortSignal): Promise<AutomationRun> {
+    stopped(signal); const record = this.db.query<{ data: string }, [string]>("SELECT data FROM plans WHERE id=?").get(planId); if (record === null) throw new Error("Messaging plan does not exist.");
+    const plan = planData(JSON.parse(record.data) as unknown);
+    if (plan.id !== planId) throw new Error("Messaging plan binding is invalid.");
+    const existing = this.db.query<StoredRun, [string]>(`SELECT ${RUN_COLUMNS} FROM runs WHERE intent_id=?`).get(plan.intentId);
+    if (existing !== null) { if (existing.plan_id !== plan.id) throw new Error("Messaging intent already belongs to another plan."); return this.runProjection(existing); }
+    const enrollment = await this.poll(plan.enrollmentId, signal); const provider = this.provider(enrollment.identity.provider); const status = await this.status(provider, signal);
+    const route = await provider.resolve(enrollment.conversation.coordinate, signal); stopped(signal);
+    if (!same(parseAutomationIdentity(route.identity), enrollment.identity) || !sameConversation(conversation(route.conversation), enrollment.conversation) || !same(status.identity, enrollment.identity) || !status.connected) throw new Error("Messaging route or identity changed before dispatch.");
+    for (const action of plan.actions) if (!status.actions[parseAutomationAction(action).kind].available) throw new Error("Messaging action is unavailable for this provider.");
+    const runId = `run:${randomUUID()}`;
+    this.ready(); this.db.transaction(() => {
+      stopped(signal); const current = this.enrollment(this.row(plan.enrollmentId)); const now = this.now();
+      this.capacity("runs"); this.capacity("messages", 0); this.capacity("events", 0);
+      if (!current.ready || current.revision !== plan.expectedRevision || current.bindingDigest !== plan.bindingDigest || Date.parse(plan.expiresAt) <= now || this.activeRun(current.id)) throw new Error("Messaging context expired, changed, or has an unresolved run.");
+      const grantRow = this.db.query<StoredGrant, [string]>("SELECT * FROM grants WHERE id=?").get(grantId); if (grantRow === null) throw new Error("Messaging grant does not exist.");
+      const grant = grantData(JSON.parse(grantRow.data) as unknown);
+      automationInteger(grantRow.revoked, 0, 1); automationInteger(grantRow.consumed, 0, grant.maximumActions); automationInteger(grantRow.last_dispatch, 0, Number.MAX_SAFE_INTEGER);
+      if (grantRow.revoked !== 0 || grant.enrollmentId !== current.id || grant.expectedBindingDigest !== current.bindingDigest || Date.parse(grant.expiresAt) <= now
+        || grantRow.consumed + plan.actions.length > grant.maximumActions || (grantRow.last_dispatch !== 0 && now - grantRow.last_dispatch < grant.minimumIntervalMs)
+        || plan.actions.some(action => !grant.actions.includes(action.kind))) throw new Error("Messaging grant does not authorize this dispatch.");
+      this.db.query("INSERT INTO runs VALUES(?,?,?,?, 'started','[]',?,NULL)").run(runId, plan.id, plan.intentId, current.id, plan.actions.length);
+      this.db.query("UPDATE grants SET consumed=consumed+?,last_dispatch=? WHERE id=?").run(plan.actions.length, now, grantId);
+    }).immediate(); this.checkFiles();
+    const accepted: { messageId: string | null; providerReceiptId: string | null }[] = [];
+    let state: AutomationRun["state"] = "accepted"; let reason: string | null = null;
+    for (const [index, action] of plan.actions.entries()) {
+      try {
+        this.checkFiles();
+        const observed = checkedPage(await provider.events({ coordinates: [enrollment.conversation.coordinate], cursor: this.row(enrollment.id).cursor, limit: 200 }, signal), enrollment.identity, enrollment.conversation.coordinate);
+        const ownMessages = new Set(accepted.flatMap(receipt => receipt.messageId === null ? [] : [receipt.messageId]));
+        if (observed.gap || !observed.caughtUp || observed.messages.some(message => message.direction !== "outgoing" || message.kind !== "message" || !ownMessages.has(message.id))) {
+          state = accepted.length ? "partial" : "failed"; reason = "Conversation changed before the next action."; break;
+        }
+        const grantRow = this.db.query<StoredGrant, [string]>("SELECT * FROM grants WHERE id=?").get(grantId);
+        const grant = grantRow === null ? null : grantData(JSON.parse(grantRow.data) as unknown);
+        const current = this.enrollment(this.row(plan.enrollmentId));
+        if (signal.aborted || grantRow?.revoked !== 0 || grant === null || Date.parse(grant.expiresAt) <= this.now() || Date.parse(plan.expiresAt) <= this.now()
+          || grant.enrollmentId !== current.id || grant.expectedBindingDigest !== current.bindingDigest || current.bindingDigest !== plan.bindingDigest || !grant.actions.includes(action.kind)) {
+          state = accepted.length ? "partial" : "failed"; reason = "Dispatch permission expired or changed before the next action."; break;
+        }
+        const result = checkedResult(await provider.send({ identity: enrollment.identity, coordinate: enrollment.conversation.coordinate, action, intentId: `${plan.intentId}:${index}` }, signal));
+        if (result.state !== "accepted") { state = result.state === "indeterminate" ? "indeterminate" : accepted.length ? "partial" : "failed"; reason = result.reason; break; }
+        accepted.push({ messageId: result.messageId, providerReceiptId: result.providerReceiptId });
+        this.checkFiles(); if (this.db.query("UPDATE runs SET accepted=? WHERE id=? AND state='started'").run(canonicalJson(accepted), runId).changes !== 1) throw new Error("Messaging result journal lost its claim.");
+      } catch { state = "indeterminate"; reason = "Provider dispatch or result recording did not settle conclusively."; break; }
+    }
+    this.checkFiles(); if (this.db.query("UPDATE runs SET state=?,accepted=?,reason=? WHERE id=? AND state='started'").run(state, canonicalJson(accepted), reason, runId).changes !== 1) throw new Error("Messaging terminal result could not be recorded.");
+    const row = this.db.query<StoredRun, [string]>(`SELECT ${RUN_COLUMNS} FROM runs WHERE id=?`).get(runId)!; return this.runProjection(row);
+  }
+  async close(): Promise<void> {
+    if (this.closed) return; if (this.closing) throw new Error("Messaging automation shutdown is already in progress."); this.closing = true;
+    for (const controller of this.controllers) controller.abort();
+    const settled = await Promise.allSettled([...this.pending]); const providers = await Promise.allSettled([...this.providers.values()].map(provider => provider.close()));
+    this.db.close(); this.closed = true;
+    if (settled.some(result => result.status === "rejected") || providers.some(result => result.status === "rejected")) throw new Error("Messaging automation shutdown did not establish complete cleanup.");
+  }
+}

package/src/messaging-runtime.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { checkOperationPermission } from "./operation-permission";
 import { isAbsolute, resolve } from "node:path";
 
 import type { GhostgetAuth } from "./auth";
@@ -1717,6 +1718,7 @@ export async function executeMessagingCompositeInternal(
   const environment = options.environment ?? process.env;
   const registry = options.registry ?? providerPluginRegistry;
   const actionResolution = messagingResolution(invocation, registry, "action");
+  await checkOperationPermission(invocation, { environment, registry, ...(options.signal === undefined ? {} : { signal: options.signal }) });
   const action = actionResolution.messaging.action;
   if (action.state !== "supported") {
     throw new Error("messaging action support disappeared after confirmation");
@@ -1889,6 +1891,7 @@ export async function executeMessagingCompositeInternal(
             );
           };
           const beforeExternalBegin = async (): Promise<void> => {
+            await checkOperationPermission({ ...invocation, input: composite.parts[index]!.input }, { environment, registry, ...(options.signal === undefined ? {} : { signal: options.signal }) });
             operationDeadline.throwIfUnavailable("messaging provider action");
             if (crossedExternalBoundary) {
               throw new Error(

package/src/oauth-google.ts

@@ -756,6 +756,7 @@ export function installManagedGoogleOAuth(
     managed: true,
   });
   if (auth.kind !== "oauth-token-file") throw new Error("managed OAuth login created the wrong auth kind");
+  const { contentSha256 } = loadOAuthCredential(auth, { expectedContent: content });
   let path: string;
   try {
     path = saveAuth(
@@ -764,11 +765,16 @@ export function installManagedGoogleOAuth(
       options.force === undefined ? {} : { force: options.force },
     );
   } catch (error) {
-    removePrivateStateFileIfUnchanged(
-      tokenPath,
-      { expectedCurrentContentSha256: createHash("sha256").update(content, "utf8").digest("hex") },
-      environment,
-    );
+    // Auth publication can succeed before prior-credential cleanup fails. Never
+    // delete the new live credential when reconciling that uncertain outcome.
+    const observed = loadAuthSnapshotIfPresent(id, environment)?.auth;
+    if (observed?.kind !== "oauth-token-file" || observed.path !== tokenPath) {
+      removePrivateStateFileIfUnchanged(
+        tokenPath,
+        { expectedCurrentContentSha256: contentSha256 },
+        environment,
+      );
+    }
     throw error;
   }
   if (

package/src/omni-runtime.ts

@@ -2,6 +2,7 @@ import { types as nodeTypes } from "node:util";
 
 import { canonicalJson, sha256 } from "./canonical-json";
 import { loadAuthSnapshotIfPresent } from "./auth";
+import { assertOperationPermission, withOperationPermissions, withUnmanagedOperationPermission, readOperationPolicy } from "./operation-permission";
 import {
   isProviderOperation,
   isLocalCliOperation,
@@ -1573,7 +1574,10 @@ export function readCachedOmniViewInternal(
   options: OmniRuntimeOptions = {},
 ): OmniReadResultV1 {
   const prepared = prepareSources(requestValue, options);
-  return result("omni-cache", prepared, view(prepared, options));
+  for (const source of prepared.sources) assertOperationPermission(source.invocation, { environment: options.environment ?? process.env, registry: prepared.registry });
+  const output = result("omni-cache", prepared, view(prepared, options));
+  for (const source of prepared.sources) assertOperationPermission(source.invocation, { environment: options.environment ?? process.env, registry: prepared.registry });
+  return output;
 }
 
 export function rebuildOmniViewFromExactCache(
@@ -1581,6 +1585,7 @@ export function rebuildOmniViewFromExactCache(
   options: OmniRuntimeOptions = {},
 ): OmniReadResultV1 {
   const prepared = prepareSources(requestValue, options);
+  for (const source of prepared.sources) assertOperationPermission(source.invocation, { environment: options.environment ?? process.env, registry: prepared.registry });
   const errors = new Map<string, OmniSourceUpdateError>();
   for (const source of prepared.sources) {
     if (source.omni?.state !== "supported") continue;
@@ -1596,10 +1601,12 @@ export function rebuildOmniViewFromExactCache(
       );
     }
   }
-  return result("omni-exact-cache", prepared, view(prepared, options, errors));
+  const output = result("omni-exact-cache", prepared, view(prepared, options, errors));
+  for (const source of prepared.sources) assertOperationPermission(source.invocation, { environment: options.environment ?? process.env, registry: prepared.registry });
+  return output;
 }
 
-export async function revalidateOmniViewInternal(
+async function revalidateOmniViewCore(
   requestValue: unknown,
   options: OmniLiveRuntimeOptions = {},
 ): Promise<OmniReadResultV1> {
@@ -1630,3 +1637,11 @@ export async function revalidateOmniViewInternal(
   throwIfAborted(options.signal);
   return result("omni-live", prepared, selectedView);
 }
+
+export async function revalidateOmniViewInternal(requestValue: unknown, options: OmniLiveRuntimeOptions = {}): Promise<OmniReadResultV1> {
+  const environment = options.environment ?? process.env;
+  if (!readOperationPolicy(environment).managed) return withUnmanagedOperationPermission(environment, () => revalidateOmniViewCore(requestValue, options));
+  const prepared = prepareSources(requestValue, options);
+  return withOperationPermissions(prepared.sources.map(source => source.invocation), { environment, registry: prepared.registry,
+    ...(options.signal === undefined ? {} : { signal: options.signal }) }, () => revalidateOmniViewCore(requestValue, options));
+}

package/src/operation-permission-store.ts

@@ -0,0 +1,92 @@
+import { join } from "node:path";
+import { canonicalJson, sha256 } from "./canonical-json";
+import { createPrivateJsonIfAbsent, ensurePrivateStateDirectory, ghostgetStateHome, privateStateFilesMayExist, readPrivateStateFileIfPresent, writePrivateJsonIfUnchanged } from "./storage";
+import type { PermissionDecision } from "./control/protocol";
+
+export type PermissionEnvironment = Readonly<Record<string, string | undefined>>;
+export type OperationPolicyEntry = Readonly<{ digest: string; decision: PermissionDecision }>;
+export type OperationPolicy = Readonly<{ schemaVersion: 1; revision: number; entries: readonly OperationPolicyEntry[] }>;
+export type OperationPolicySnapshot = Readonly<{ managed: boolean; revision: number; entries: readonly OperationPolicyEntry[]; contentSha256: string | null }>;
+const MAX_POLICY_BYTES = 512 * 1024;
+const MAX_ENTRIES = 4096;
+const DIGEST = /^[a-f0-9]{64}$/u;
+const marker = Object.freeze({ schemaVersion: 1, managed: true });
+
+export class OperationPermissionError extends Error {
+  constructor(readonly code: "OPERATION_PERMISSION_DENIED" | "OPERATION_APPROVAL_REQUIRED" | "OPERATION_PERMISSION_CHANGED" | "OPERATION_POLICY_INVALID" | "OPERATION_APPROVAL_TOO_LARGE", message: string) {
+    super(message);
+    this.name = "OperationPermissionError";
+  }
+}
+
+export function parseOperationPolicy(value: unknown): OperationPolicy {
+  const fail = (): never => { throw new OperationPermissionError("OPERATION_POLICY_INVALID", "Operation permission policy is invalid; repair it in Ghostget before execution."); };
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return fail();
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).sort().join(",") !== "entries,revision,schemaVersion" || record.schemaVersion !== 1
+    || !Number.isSafeInteger(record.revision) || (record.revision as number) < 1
+    || !Array.isArray(record.entries) || record.entries.length > MAX_ENTRIES) return fail();
+  let previous = "";
+  const entries = record.entries.map((candidate: unknown): OperationPolicyEntry => {
+    if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) return fail();
+    const entry = candidate as Record<string, unknown>;
+    if (Object.keys(entry).sort().join(",") !== "decision,digest" || typeof entry.digest !== "string" || !DIGEST.test(entry.digest)
+      || entry.digest <= previous || (entry.decision !== "allow" && entry.decision !== "deny" && entry.decision !== "ask")) return fail();
+    previous = entry.digest;
+    return Object.freeze({ digest: entry.digest, decision: entry.decision });
+  });
+  return Object.freeze({ schemaVersion: 1, revision: record.revision as number, entries: Object.freeze(entries) });
+}
+
+function paths(environment: PermissionEnvironment) {
+  const directory = join(ghostgetStateHome(environment), "operation-permissions");
+  return { directory, marker: join(directory, "managed.json"), policy: join(directory, "policy.json") };
+}
+
+export function readOperationPolicy(environment: PermissionEnvironment = process.env): OperationPolicySnapshot {
+  try {
+    if (!privateStateFilesMayExist("operation-permissions", ["managed.json", "policy.json"], environment)) {
+      return Object.freeze({ managed: false, revision: 0, entries: Object.freeze([]), contentSha256: null });
+    }
+    const selected = paths(environment);
+    const markerText = readPrivateStateFileIfPresent(selected.marker, 256, "operation policy marker", environment);
+    if (markerText !== null && markerText !== `${canonicalJson(marker)}\n`) throw new Error("marker");
+    const text = readPrivateStateFileIfPresent(selected.policy, MAX_POLICY_BYTES, "operation permission policy", environment);
+    if (text === null) {
+      if (markerText !== null) throw new Error("missing policy");
+      return Object.freeze({ managed: false, revision: 0, entries: Object.freeze([]), contentSha256: null });
+    }
+    const policy = parseOperationPolicy(JSON.parse(text) as unknown);
+    if (text !== `${canonicalJson(policy)}\n`) throw new Error("noncanonical policy");
+    return Object.freeze({ managed: true, revision: policy.revision, entries: policy.entries, contentSha256: sha256(text) });
+  } catch {
+    throw new OperationPermissionError("OPERATION_POLICY_INVALID", "Operation permission state is missing or invalid; execution is blocked until it is repaired.");
+  }
+}
+
+export function enableOperationPermissions(expectedRevision: number, environment: PermissionEnvironment = process.env): OperationPolicySnapshot {
+  const snapshot = readOperationPolicy(environment);
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision !== snapshot.revision) throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Operation policy changed; refresh Ghostget before editing it.");
+  if (snapshot.managed) return snapshot;
+  const selected = paths(environment);
+  ensurePrivateStateDirectory(selected.directory, environment);
+  // Publishing the marker first deliberately makes interrupted opt-in fail closed.
+  const created = createPrivateJsonIfAbsent(selected.marker, marker, { environment });
+  if (!created.created) throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Another control session enabled operation permissions.");
+  if (!createPrivateJsonIfAbsent(selected.policy, { schemaVersion: 1, revision: 1, entries: [] }, { environment }).created) {
+    throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Operation policy appeared concurrently; refresh Ghostget.");
+  }
+  return readOperationPolicy(environment);
+}
+
+export function setOperationPolicyEntry(digest: string, decision: PermissionDecision, expectedRevision: number, environment: PermissionEnvironment = process.env): OperationPolicySnapshot {
+  if (!DIGEST.test(digest) || !["allow", "deny", "ask"].includes(decision)) throw new OperationPermissionError("OPERATION_POLICY_INVALID", "Operation permission update is invalid.");
+  const snapshot = readOperationPolicy(environment);
+  if (!snapshot.managed || snapshot.contentSha256 === null || !Number.isSafeInteger(expectedRevision) || snapshot.revision !== expectedRevision
+    || snapshot.revision >= Number.MAX_SAFE_INTEGER) throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Enable operation permissions or refresh the policy before editing it.");
+  const entries = [...snapshot.entries.filter(entry => entry.digest !== digest), { digest, decision }].sort((a, b) => a.digest.localeCompare(b.digest));
+  const policy = parseOperationPolicy({ schemaVersion: 1, revision: snapshot.revision + 1, entries });
+  if (Buffer.byteLength(canonicalJson(policy)) > MAX_POLICY_BYTES - 1) throw new OperationPermissionError("OPERATION_POLICY_INVALID", "Operation policy exceeds its size limit.");
+  if (!writePrivateJsonIfUnchanged(paths(environment).policy, policy, { expectedCurrentContentSha256: snapshot.contentSha256 })) throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Operation policy changed; refresh Ghostget before editing it.");
+  return readOperationPolicy(environment);
+}