@hachej/boring-governance 0.1.71 → 0.1.73

package/README.md

@@ -30,4 +30,57 @@ const governanceCompanyAdmin = createGovernanceCompanyAdmin()
 <CoreWorkspaceAgentFront companyAdmin={governanceCompanyAdmin} />
 ```
 
-Policy source is configured with `BORING_GOVERNANCE_POLICY_PATH`. Company context source roots use `BORING_GOVERNANCE_COMPANY_CONTEXT_ROOT` or the default workspace root resolver outside sandbox mode.
+Policy source is configured with `BORING_GOVERNANCE_POLICY_PATH`. Company context source roots use `BORING_GOVERNANCE_COMPANY_CONTEXT_ROOT` or the default workspace root resolver outside sandbox mode. When an explicit, governance-owned company-context root is configured, verified tenant admins receive a tenant-wide read/write `company_context` binding; ordinary policy users receive only their regex-filtered readonly projection. Custom resolvers must opt into admin mutations with `allowAdminMutations: true` only when no other actor can mutate the root outside the governance store.
+
+## Policy budgets
+
+Model grants remain the model picker allowlist. Optional user budgets cap aggregate monthly spend across all allowed models; optional per-model budgets cap individual models.
+
+```yaml
+users:
+  - email: readonly@example.com
+    role: user
+    budgets:
+      monthlyEur: 10
+    models:
+      - provider: infomaniak
+        id: Qwen/Qwen3.5-122B-A10B-FP8
+        monthlyBudgetEur: 2
+```
+
+A run is admitted only when the user is allowed to use the selected model, the aggregate user budget has remaining monthly capacity, and the selected model budget has remaining monthly capacity.
+
+## Governance access matrix smoke
+
+The package includes a reusable HTTP matrix runner for deployment smoke tests:
+
+```bash
+boring-governance-access-matrix
+# or from the source package:
+pnpm --filter @hachej/boring-governance smoke:governance-matrix
+```
+
+It signs in two environment-provided users and verifies the expected read/write behavior for:
+
+- company-context public paths
+- company-context Adam-private paths
+- each user's own `user` workspace filesystem
+- cross-user workspace access denial
+
+All deployment-specific values must be supplied explicitly; the reusable package intentionally does not ship real credentials or workspace IDs.
+
+| Var | Required value |
+| --- | --- |
+| `MATRIX_BASE_URL` / `DEPLOY_URL` | Deployment base URL |
+| `MATRIX_ADAM_EMAIL` | Admin fixture email |
+| `MATRIX_ADAM_PASSWORD` | Admin fixture password |
+| `MATRIX_ADAM_WORKSPACE_ID` | Admin fixture workspace ID |
+| `MATRIX_READONLY_EMAIL` | Readonly fixture email |
+| `MATRIX_READONLY_PASSWORD` | Readonly fixture password |
+| `MATRIX_READONLY_WORKSPACE_ID` | Readonly fixture workspace ID |
+| `MATRIX_COMPANY_PUBLIC_READ_PATH` | Existing public company-context file readable by both users |
+| `MATRIX_COMPANY_PRIVATE_READ_PATH` | Existing private company-context file readable by admin and denied to readonly |
+| `MATRIX_COMPANY_PUBLIC_WRITE_DIR` | Company-context directory used for admin public write probes |
+| `MATRIX_COMPANY_PRIVATE_WRITE_DIR` | Company-context directory used for admin private write probes |
+| `MATRIX_ADMIN_COMPANY_WRITE_EXPECTED` | Optional admin company-context write status, defaults to `403` for the base readonly plugin |
+| `MATRIX_READONLY_COMPANY_WRITE_EXPECTED` | Optional readonly company-context write status, defaults to `403` |

package/dist/front/index.d.ts

@@ -23,6 +23,7 @@ interface GovernanceMeResponse {
     users?: Array<{
         email: string;
         role: 'admin' | 'user';
+        monthlyBudgetEur: number | null;
         modelCount: number;
         contextRuleCount: number;
     }>;

package/dist/front/index.js

@@ -85,15 +85,17 @@ function GovernanceAdminView({ status }) {
           /* @__PURE__ */ jsx("thead", { className: "bg-muted/60 text-xs uppercase tracking-[0.12em] text-muted-foreground", children: /* @__PURE__ */ jsxs("tr", { children: [
             /* @__PURE__ */ jsx("th", { className: "px-3 py-2 font-medium", children: "User" }),
             /* @__PURE__ */ jsx("th", { className: "px-3 py-2 font-medium", children: "Role" }),
+            /* @__PURE__ */ jsx("th", { className: "px-3 py-2 font-medium", children: "Monthly budget" }),
             /* @__PURE__ */ jsx("th", { className: "px-3 py-2 font-medium", children: "Models" }),
             /* @__PURE__ */ jsx("th", { className: "px-3 py-2 font-medium", children: "Context rules" })
           ] }) }),
           /* @__PURE__ */ jsx("tbody", { children: (status.users ?? []).length > 0 ? status.users.map((user) => /* @__PURE__ */ jsxs("tr", { className: "border-t border-border", children: [
             /* @__PURE__ */ jsx("td", { className: "px-3 py-2 font-medium", children: user.email }),
             /* @__PURE__ */ jsx("td", { className: "px-3 py-2", children: user.role }),
+            /* @__PURE__ */ jsx("td", { className: "px-3 py-2", children: user.monthlyBudgetEur == null ? "\u2014" : `\u20AC${user.monthlyBudgetEur}` }),
             /* @__PURE__ */ jsx("td", { className: "px-3 py-2", children: user.modelCount }),
             /* @__PURE__ */ jsx("td", { className: "px-3 py-2", children: user.contextRuleCount })
-          ] }, user.email)) : /* @__PURE__ */ jsx("tr", { children: /* @__PURE__ */ jsx("td", { colSpan: 4, className: "px-3 py-4 text-muted-foreground", children: "No users in policy." }) }) })
+          ] }, user.email)) : /* @__PURE__ */ jsx("tr", { children: /* @__PURE__ */ jsx("td", { colSpan: 5, className: "px-3 py-4 text-muted-foreground", children: "No users in policy." }) }) })
         ] }) })
       ] }) })
     ] }) })

package/dist/scripts/governance-access-matrix.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/scripts/governance-access-matrix.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+
+// src/scripts/governance-access-matrix.ts
+import { randomUUID } from "crypto";
+var baseUrl = normalizeBaseUrl(readRequiredEnv("MATRIX_BASE_URL", process.env.MATRIX_BASE_URL ?? process.env.DEPLOY_URL));
+var requestTimeoutMs = readPositiveIntEnv("MATRIX_REQUEST_TIMEOUT_MS", 1e4);
+var publicReadPath = readRequiredEnv("MATRIX_COMPANY_PUBLIC_READ_PATH");
+var privateReadPath = readRequiredEnv("MATRIX_COMPANY_PRIVATE_READ_PATH");
+var publicWriteDir = normalizeCompanyDir(readRequiredEnv("MATRIX_COMPANY_PUBLIC_WRITE_DIR"));
+var privateWriteDir = normalizeCompanyDir(readRequiredEnv("MATRIX_COMPANY_PRIVATE_WRITE_DIR"));
+var adminCompanyWriteExpected = readStatusEnv("MATRIX_ADMIN_COMPANY_WRITE_EXPECTED", 403);
+var readonlyCompanyWriteExpected = readStatusEnv("MATRIX_READONLY_COMPANY_WRITE_EXPECTED", 403);
+var runId = `${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}-${randomUUID().slice(0, 8)}`;
+var users = {
+  adam: {
+    key: "adam",
+    label: "Adam/admin",
+    email: readRequiredEnv("MATRIX_ADAM_EMAIL"),
+    password: readRequiredSecretEnv("MATRIX_ADAM_PASSWORD"),
+    workspaceId: readRequiredEnv("MATRIX_ADAM_WORKSPACE_ID")
+  },
+  readonly: {
+    key: "readonly",
+    label: "Readonly",
+    email: readRequiredEnv("MATRIX_READONLY_EMAIL"),
+    password: readRequiredSecretEnv("MATRIX_READONLY_PASSWORD"),
+    workspaceId: readRequiredEnv("MATRIX_READONLY_WORKSPACE_ID")
+  }
+};
+function readRequiredEnv(name, value = process.env[name]) {
+  const trimmed = value?.trim();
+  if (!trimmed) throw new Error(`${name} is required`);
+  return trimmed;
+}
+function readRequiredSecretEnv(name) {
+  const value = process.env[name];
+  if (value === void 0 || value === "") throw new Error(`${name} is required`);
+  return value;
+}
+function readPositiveIntEnv(name, fallback) {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${name} must be a positive integer`);
+  return parsed;
+}
+function readStatusEnv(name, fallback) {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 100 || parsed > 599) throw new Error(`${name} must be an HTTP status code`);
+  return parsed;
+}
+function normalizeCompanyDir(value) {
+  const raw = value.trim();
+  if (raw === "/") return "/";
+  const trimmed = raw.replace(/\/+$/, "");
+  if (!trimmed.startsWith("/")) throw new Error("company-context fixture directories must be absolute policy paths");
+  return trimmed;
+}
+function joinCompanyPath(dir, basename) {
+  return dir === "/" ? `/${basename}` : `${dir}/${basename}`;
+}
+async function fetchWithTimeout(input, init = {}) {
+  return fetch(input, { ...init, signal: AbortSignal.timeout(requestTimeoutMs) });
+}
+function normalizeBaseUrl(raw) {
+  const parsed = new URL(raw);
+  const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+  const loopback = ["localhost", "127.0.0.1", "::1"].includes(hostname);
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && (loopback || process.env.MATRIX_ALLOW_INSECURE_HTTP === "1"))) {
+    throw new Error("MATRIX_BASE_URL/DEPLOY_URL must be HTTPS unless targeting loopback or MATRIX_ALLOW_INSECURE_HTTP=1 is set");
+  }
+  return parsed.toString().replace(/\/$/, "");
+}
+function workspaceFor(testUser, scope) {
+  if (scope === "own") return testUser.workspaceId;
+  return users[scope].workspaceId;
+}
+function cookieFrom(headers) {
+  const setCookie = headers.get("set-cookie");
+  if (!setCookie) throw new Error("sign-in response did not set a cookie");
+  return setCookie.split(/,(?=\s*[^;,\s]+=)/).map((part) => part.split(";")[0]?.trim()).filter(Boolean).join("; ");
+}
+async function signIn(user) {
+  const response = await fetchWithTimeout(`${baseUrl}/auth/sign-in/email`, {
+    method: "POST",
+    headers: { "content-type": "application/json", origin: baseUrl },
+    body: JSON.stringify({ email: user.email, password: user.password })
+  });
+  if (!response.ok) throw new Error(`${user.label} sign-in failed: HTTP ${response.status} ${await response.text()}`);
+  return cookieFrom(response.headers);
+}
+async function requestCase(testCase, cookies, cleanupTargets) {
+  const cookie = cookies[testCase.user];
+  const user = users[testCase.user];
+  const workspaceId = workspaceFor(user, testCase.workspace);
+  let response;
+  if (testCase.operation === "read") {
+    const url = new URL(`${baseUrl}/api/v1/files`);
+    url.searchParams.set("workspaceId", workspaceId);
+    url.searchParams.set("filesystem", testCase.filesystem);
+    url.searchParams.set("path", testCase.path);
+    response = await fetchWithTimeout(url, { headers: { cookie } });
+  } else {
+    const content = testCase.content ?? `${testCase.id} ${runId}`;
+    cleanupTargets.push({ testCase, cookie: cleanupCookieFor(testCase, cookies) });
+    const url = new URL(`${baseUrl}/api/v1/files`);
+    url.searchParams.set("workspaceId", workspaceId);
+    response = await fetchWithTimeout(url, {
+      method: "POST",
+      headers: { cookie, "content-type": "application/json" },
+      body: JSON.stringify({
+        filesystem: testCase.filesystem,
+        path: testCase.path,
+        content
+      })
+    });
+    const body2 = await response.text();
+    if (response.ok && !(testCase.expected >= 200 && testCase.expected < 300)) {
+      cleanupTargets.push({ testCase, cookie: cleanupCookieFor(testCase, cookies) });
+    }
+    const statusMatches = response.status === testCase.expected;
+    if (statusMatches && response.ok && testCase.expected >= 200 && testCase.expected < 300) {
+      const verified = await verifyWrite(testCase, cookie, workspaceId, content);
+      return { ...testCase, actual: response.status, ok: verified, body: verified ? body2 : "write verification failed" };
+    }
+    if (statusMatches && testCase.expected >= 400) {
+      const noSideEffect = await verifyDeniedWriteNoSideEffect(testCase, cleanupCookieFor(testCase, cookies));
+      if (!noSideEffect) cleanupTargets.push({ testCase, cookie: cleanupCookieFor(testCase, cookies) });
+      return { ...testCase, actual: response.status, ok: noSideEffect, body: noSideEffect ? body2 : "denied write had side effects" };
+    }
+    return { ...testCase, actual: response.status, ok: statusMatches, body: body2 };
+  }
+  const body = await response.text();
+  return { ...testCase, actual: response.status, ok: response.status === testCase.expected, body };
+}
+function cleanupWorkspaceId(testCase) {
+  return testCase.filesystem === "company_context" ? users.adam.workspaceId : workspaceFor(users[testCase.user], testCase.workspace);
+}
+async function verifyWrite(testCase, cookie, workspaceId, content) {
+  const url = new URL(`${baseUrl}/api/v1/files`);
+  url.searchParams.set("workspaceId", workspaceId);
+  url.searchParams.set("filesystem", testCase.filesystem);
+  url.searchParams.set("path", testCase.path);
+  const response = await fetchWithTimeout(url, { headers: { cookie } });
+  if (!response.ok) return false;
+  try {
+    const parsed = await response.json();
+    return parsed.content === content;
+  } catch {
+    return false;
+  }
+}
+async function verifyDeniedWriteNoSideEffect(testCase, cookie) {
+  const url = new URL(`${baseUrl}/api/v1/files`);
+  url.searchParams.set("workspaceId", cleanupWorkspaceId(testCase));
+  url.searchParams.set("filesystem", testCase.filesystem);
+  url.searchParams.set("path", testCase.path);
+  const response = await fetchWithTimeout(url, { headers: { cookie } });
+  return response.status === 404;
+}
+function cleanupCookieFor(testCase, cookies) {
+  if (testCase.filesystem !== "user") return cookies.adam;
+  if (testCase.workspace === "adam") return cookies.adam;
+  if (testCase.workspace === "readonly") return cookies.readonly;
+  return cookies[testCase.user];
+}
+async function signOut(cookie) {
+  const response = await fetchWithTimeout(`${baseUrl}/auth/sign-out`, {
+    method: "POST",
+    headers: { cookie, origin: baseUrl, "content-type": "application/json" },
+    body: "{}"
+  });
+  if (!response.ok) throw new Error(`sign-out failed: HTTP ${response.status}`);
+}
+async function cleanupWrite(target) {
+  const workspaceId = cleanupWorkspaceId(target.testCase);
+  const url = new URL(`${baseUrl}/api/v1/files`);
+  url.searchParams.set("workspaceId", workspaceId);
+  url.searchParams.set("filesystem", target.testCase.filesystem);
+  url.searchParams.set("path", target.testCase.path);
+  const response = await fetchWithTimeout(url, { method: "DELETE", headers: { cookie: target.cookie } });
+  if (!response.ok && response.status !== 404) {
+    if (response.status === 403 && await verifyDeniedWriteNoSideEffect(target.testCase, target.cookie)) return;
+    throw new Error(`${target.testCase.id} cleanup failed: HTTP ${response.status}`);
+  }
+}
+function buildCases() {
+  const adamUserPath = `adam-user-matrix-${runId}.txt`;
+  const readonlyUserPath = `readonly-user-matrix-${runId}.txt`;
+  const cases = [];
+  for (const user of ["adam", "readonly"]) {
+    const isAdmin = user === "adam";
+    cases.push(
+      {
+        id: `${user}-read-company-public`,
+        user,
+        operation: "read",
+        filesystem: "company_context",
+        location: "company public",
+        workspace: "own",
+        path: publicReadPath,
+        expected: 200,
+        note: "public company context is readable by both policy users"
+      },
+      {
+        id: `${user}-read-company-adam-private`,
+        user,
+        operation: "read",
+        filesystem: "company_context",
+        location: "company adam-private",
+        workspace: "own",
+        path: privateReadPath,
+        expected: isAdmin ? 200 : 404,
+        note: "adam-private company context is restricted to Adam/admin"
+      },
+      {
+        id: `${user}-write-company-public`,
+        user,
+        operation: "write",
+        filesystem: "company_context",
+        location: "company public",
+        workspace: "own",
+        path: joinCompanyPath(publicWriteDir, `${user}-company-public-write-${runId}.txt`),
+        expected: isAdmin ? adminCompanyWriteExpected : readonlyCompanyWriteExpected,
+        note: "company context writes require admin"
+      },
+      {
+        id: `${user}-write-company-adam-private`,
+        user,
+        operation: "write",
+        filesystem: "company_context",
+        location: "company adam-private",
+        workspace: "own",
+        path: joinCompanyPath(privateWriteDir, `${user}-company-private-write-${runId}.txt`),
+        expected: isAdmin ? adminCompanyWriteExpected : readonlyCompanyWriteExpected,
+        note: "company context writes require admin, including private area"
+      },
+      {
+        id: `${user}-write-own-user-workspace`,
+        user,
+        operation: "write",
+        filesystem: "user",
+        location: "own user workspace",
+        workspace: "own",
+        path: user === "adam" ? adamUserPath : readonlyUserPath,
+        expected: 200,
+        note: "each user can write their own workspace"
+      },
+      {
+        id: `${user}-read-own-user-workspace`,
+        user,
+        operation: "read",
+        filesystem: "user",
+        location: "own user workspace",
+        workspace: "own",
+        path: user === "adam" ? adamUserPath : readonlyUserPath,
+        expected: 200,
+        note: "each user can read their own workspace"
+      },
+      {
+        id: `${user}-write-other-user-workspace`,
+        user,
+        operation: "write",
+        filesystem: "user",
+        location: "other user workspace",
+        workspace: user === "adam" ? "readonly" : "adam",
+        path: `${user}-cross-workspace-write-${runId}.txt`,
+        expected: 403,
+        note: "workspace membership blocks writes to the other user workspace"
+      },
+      {
+        id: `${user}-read-other-user-workspace`,
+        user,
+        operation: "read",
+        filesystem: "user",
+        location: "other user workspace",
+        workspace: user === "adam" ? "readonly" : "adam",
+        path: user === "adam" ? readonlyUserPath : adamUserPath,
+        expected: 403,
+        note: "workspace membership blocks reads from the other user workspace"
+      }
+    );
+  }
+  return cases;
+}
+function compactBody(body, actual) {
+  if (body === "write verification failed" || body === "denied write had side effects") return body;
+  if (actual >= 200 && actual < 300) return "[success body redacted]";
+  try {
+    const parsed = JSON.parse(body);
+    const code = typeof parsed.error?.code === "string" ? parsed.error.code : typeof parsed.code === "string" ? parsed.code : "error";
+    const message = typeof parsed.error?.message === "string" ? parsed.error.message : typeof parsed.message === "string" ? parsed.message : "";
+    return [code, message].filter(Boolean).join(": ").slice(0, 100);
+  } catch {
+    return "[error body redacted]";
+  }
+}
+function printMarkdown(results) {
+  console.log(`
+Governance access matrix (${baseUrl})
+`);
+  console.log("| User | Operation | Filesystem | Location | Workspace | Path | Expected | Actual | Result |");
+  console.log("|---|---:|---|---|---|---|---:|---:|---|");
+  for (const result of results) {
+    console.log(`| ${users[result.user].label} | ${result.operation} | \`${result.filesystem}\` | ${result.location} | ${result.workspace} | \`${result.path}\` | ${result.expected} | ${result.actual} | ${result.ok ? "\u2705" : `\u274C ${compactBody(result.body, result.actual)}`} |`);
+  }
+}
+async function main() {
+  const cookies = {};
+  const cleanupTargets = [];
+  const results = [];
+  const cleanupFailures = [];
+  let primaryError = null;
+  try {
+    cookies.adam = await signIn(users.adam);
+    cookies.readonly = await signIn(users.readonly);
+    const completeCookies = cookies;
+    for (const testCase of buildCases()) {
+      results.push(await requestCase(testCase, completeCookies, cleanupTargets));
+    }
+  } catch (error) {
+    primaryError = error;
+  } finally {
+    for (const target of cleanupTargets.reverse()) {
+      await cleanupWrite(target).catch((error) => {
+        cleanupFailures.push(error instanceof Error ? error.message : String(error));
+      });
+    }
+    await Promise.all(Object.values(cookies).filter((cookie) => Boolean(cookie)).map((cookie) => signOut(cookie).catch((error) => {
+      cleanupFailures.push(error instanceof Error ? error.message : String(error));
+    })));
+  }
+  printMarkdown(results);
+  const failures = results.filter((result) => !result.ok);
+  if (primaryError || failures.length > 0 || cleanupFailures.length > 0) {
+    if (primaryError) console.error(primaryError instanceof Error ? primaryError.stack ?? primaryError.message : String(primaryError));
+    for (const failure of cleanupFailures) console.error(`cleanup failed: ${failure}`);
+    if (failures.length > 0) console.error(`
+${failures.length} governance access matrix case(s) failed.`);
+    if (cleanupFailures.length > 0) console.error(`${cleanupFailures.length} cleanup operation(s) failed.`);
+    process.exit(1);
+  }
+  console.log("\nAll governance access matrix cases passed.");
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  process.exit(1);
+});

package/dist/server/index.d.ts

@@ -2,6 +2,7 @@ import * as _hachej_boring_agent_server from '@hachej/boring-agent/server';
 import { AgentMeteringSink, RegisterAgentRoutesOptions } from '@hachej/boring-agent/server';
 import { CoreConfig } from '@hachej/boring-core/shared';
 import { CoreWorkspaceAgentServerPlugin } from '@hachej/boring-core/app/server';
+import { PostgresBudgetReservationStore } from '@hachej/boring-core/server';
 import { FastifyRequest } from 'fastify';
 
 type TenantRole = 'admin' | 'user';
@@ -11,9 +12,14 @@ interface GovernanceModelGrant {
     monthlyBudgetEur: number;
     monthlyBudgetMicros: number;
 }
+interface GovernanceUserBudgets {
+    monthlyEur: number | null;
+    monthlyMicros: number | null;
+}
 interface GovernanceUserPolicy {
     email: string;
     role: TenantRole;
+    budgets: GovernanceUserBudgets;
     models: GovernanceModelGrant[];
     companyContext: {
         allow: string[];
@@ -69,6 +75,7 @@ interface LoadGovernancePolicyOptions {
 declare function loadGovernancePolicy({ env, nodeEnv, config, }?: LoadGovernancePolicyOptions): Promise<GovernanceLoadResult>;
 
 type GovernancePolicyErrorCode = 'disabled' | 'invalid' | 'denied' | 'not_allowed';
+type CompanyContextAccess = 'none' | 'readonly' | 'readwrite';
 declare class GovernancePolicyError extends Error {
     readonly code: GovernancePolicyErrorCode;
     constructor(message: string, code: GovernancePolicyErrorCode);
@@ -88,6 +95,7 @@ interface GovernanceMeResponse {
         email: string;
         role: TenantRole;
         modelCount: number;
+        monthlyBudgetEur: number | null;
         contextRuleCount: number;
     }>;
     models?: Array<GovernanceModelGrant & {
@@ -111,22 +119,17 @@ declare class GovernanceService {
     allowedModelsForUser<TModel extends ServedModelLike>(user: GovernanceUserLike, servedModels: readonly TModel[]): TModel[];
     assertModelAllowed(user: GovernanceUserLike, model: ServedModelLike): void;
     monthlyBudgetMicros(user: GovernanceUserLike, model: ServedModelLike): number | null;
+    userMonthlyBudgetMicros(user: GovernanceUserLike): number | null;
     companyContextRules(user: GovernanceUserLike): string[];
+    companyContextAccessForUser(user: GovernanceUserLike | null | undefined): CompanyContextAccess;
     companyContextWorkspaceId(): string | null;
     me(user: GovernanceUserLike | null | undefined): GovernanceMeResponse;
 }
 
-declare const PostgresModelBudgetStore: new (db: unknown) => {
-    reserve(input: unknown): Promise<{
-        reservationId: string;
-    }>;
-    settle(input: unknown): Promise<void>;
-    release(input: unknown): Promise<void>;
-};
-type ModelBudgetDb = ConstructorParameters<typeof PostgresModelBudgetStore>[0];
+type BudgetDb = ConstructorParameters<typeof PostgresBudgetReservationStore>[0];
 declare function createGovernanceMeteringSink(options: {
     service: GovernanceService;
-    getDb: () => ModelBudgetDb;
+    getDb: () => BudgetDb;
     delegate: AgentMeteringSink;
     holdTtlSeconds?: number;
 }): AgentMeteringSink;
@@ -145,6 +148,8 @@ type CompanyContextRootResolver = (ctx: GovernanceFilesystemBindingContext, comp
 interface CreateGovernanceFilesystemBindingsOptions {
     /** Explicit source root resolver for the tenant company-context workspace. */
     resolveCompanyContextRoot?: CompanyContextRootResolver;
+    /** Enable admin mutations only when the resolved root is exclusively managed by the governance service. */
+    allowAdminMutations?: boolean;
     projectionRootParent?: string;
 }
 declare function createDefaultCompanyContextRootResolver(env?: NodeJS.ProcessEnv): CompanyContextRootResolver | undefined;