@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/policy/audit-gate.mjs

@@ -0,0 +1,42 @@
+/**
+ * lib/policy/audit-gate.mjs — mandatory-audit enforcement for enterprise mode (LMCP-H5).
+ *
+ * ADR-0057 (A7): enterprise mode promises every mutating action is audited.
+ * A broker/policy/write path that silently swallows an audit-sink failure
+ * (as lib/mcp/broker.mjs's best-effort catch does today) makes that promise
+ * false under exactly the condition it exists to cover. enforceMandatoryAudit
+ * is a policy-decision precondition: in enterprise mode, when the audit sink
+ * (lib/audit-trail.mjs#checkAuditSinkAvailable) is down, every action is
+ * denied before any role/manifest logic runs — fail closed, no
+ * CONSTRUCT_SKIP_* escape hatch. Solo and team modes never call the sink
+ * check and are unaffected.
+ */
+
+import { checkAuditSinkAvailable } from '../audit-trail.mjs';
+
+export const AUDIT_GATE_SOURCE = 'mandatory-audit-gate';
+
+/**
+ * Enterprise-only precondition: deny everything if the audit sink is down.
+ * Returns null (no opinion) for solo/team or when the sink is healthy, so
+ * callers can compose this before their own decision logic without changing
+ * behavior outside enterprise mode.
+ *
+ * @param {object} input
+ * @param {'solo'|'team'|'enterprise'} input.deploymentMode
+ * @param {function} [input.checkSink] - injectable for tests; defaults to the real fs probe
+ * @returns {{allowed: boolean, reason: string, approvalRequired: boolean, source: string}|null}
+ */
+export function enforceMandatoryAudit({ deploymentMode, checkSink = checkAuditSinkAvailable } = {}) {
+  if (deploymentMode !== 'enterprise') return null;
+
+  const sink = checkSink();
+  if (sink.available) return null;
+
+  return {
+    allowed: false,
+    reason: `enterprise mode requires a healthy audit sink; audit sink unavailable (${sink.reason || 'unknown-error'}) — action refused fail-closed`,
+    approvalRequired: false,
+    source: AUDIT_GATE_SOURCE,
+  };
+}

package/lib/policy/consumption-budget.mjs

@@ -0,0 +1,149 @@
+/**
+ * lib/policy/consumption-budget.mjs — durable per-actor/run consumption budgets (LMCP-N5).
+ *
+ * Nothing durably bounded token/tool-call/external-write/queue-submission
+ * consumption per actor or run before this: lib/mcp/broker.mjs's BrokerStore
+ * (LMCP-I1) covers only a fixed-window tool-call rate per actor+tool, reset
+ * on every window rather than accumulating for the life of a run. This store
+ * persists cumulative consumption per actor+run to
+ * `<rootDir>/.cx/consumption-budgets.json`, survives process restarts the
+ * same way BrokerStore does, and is consulted pre-execution so an exhausted
+ * run halts with a clear, durable budget-denied record instead of a
+ * surprise bill.
+ *
+ * Budgets default per deployment mode (lib/deployment-mode.mjs): solo is
+ * `null` (unbounded) — a single local operator should never hit a wall a
+ * team/enterprise multi-actor deployment needs; team/enterprise apply real
+ * per-kind caps. An explicit `budget` object always overrides the mode
+ * default.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { getDeploymentMode } from '../deployment-mode.mjs';
+
+const BUDGET_STORE_SUBPATH = path.join('.cx', 'consumption-budgets.json');
+
+export const CONSUMPTION_KINDS = ['tokens', 'toolCalls', 'externalWrites', 'queueSubmissions'];
+
+export const DEFAULT_BUDGETS_BY_MODE = Object.freeze({
+  solo: null,
+  team: Object.freeze({ tokens: 2_000_000, toolCalls: 2000, externalWrites: 200, queueSubmissions: 500 }),
+  enterprise: Object.freeze({ tokens: 5_000_000, toolCalls: 5000, externalWrites: 500, queueSubmissions: 1000 }),
+});
+
+export function resolveDefaultBudget(mode) {
+  // `??` treats solo's deliberate `null` (unbounded) as absent and would fall
+  // through to the team default, defeating the solo-is-unbounded default —
+  // an explicit `in` check is required so null is a real, honored value.
+  return mode in DEFAULT_BUDGETS_BY_MODE ? DEFAULT_BUDGETS_BY_MODE[mode] : DEFAULT_BUDGETS_BY_MODE.team;
+}
+
+export function budgetStorePath(rootDir) {
+  return path.join(rootDir, BUDGET_STORE_SUBPATH);
+}
+
+function emptyConsumption() {
+  return { tokens: 0, toolCalls: 0, externalWrites: 0, queueSubmissions: 0 };
+}
+
+function readStoreFile(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export class BudgetExceeded extends Error {
+  constructor({ actor, runId, kind, cap, projected }) {
+    super(`consumption budget exceeded: actor '${actor}' run '${runId}' would reach ${projected} ${kind} against a budget of ${cap}`);
+    this.name = 'BudgetExceeded';
+    this.actor = actor;
+    this.runId = runId;
+    this.kind = kind;
+    this.cap = cap;
+    this.projected = projected;
+  }
+}
+
+/**
+ * ConsumptionBudgetStore — file-backed durable per-actor/run consumption.
+ *
+ * Read/write mirrors lib/mcp/broker.mjs's BrokerStore: in-memory `_data` is
+ * the write buffer, `save()` persists the whole map, and every disk
+ * operation is best-effort so a disk failure never breaks the caller.
+ */
+export class ConsumptionBudgetStore {
+  constructor({ rootDir, file, env = process.env } = {}) {
+    if (!rootDir && !file) throw new Error('ConsumptionBudgetStore: rootDir or file is required');
+    this.rootDir = rootDir ?? null;
+    this.env = env;
+    this._storePath = file || budgetStorePath(rootDir);
+    this._data = readStoreFile(this._storePath);
+  }
+
+  _key(actor, runId) {
+    return `${actor}::${runId}`;
+  }
+
+  _save() {
+    try {
+      fs.mkdirSync(path.dirname(this._storePath), { recursive: true });
+      fs.writeFileSync(this._storePath, JSON.stringify(this._data), 'utf8');
+    } catch { /* best-effort, mirrors BrokerStore.save */ }
+  }
+
+  /** Resolves the effective budget: an explicit override, else the deployment-mode default. */
+  resolveBudget(budgetOverride) {
+    if (budgetOverride !== undefined) return budgetOverride;
+    const mode = getDeploymentMode(this.env, { cwd: this.rootDir ?? process.cwd() });
+    return resolveDefaultBudget(mode);
+  }
+
+  /** Cumulative consumption recorded so far for actor+run, zeroed if none. */
+  consumptionFor(actor, runId) {
+    return { ...emptyConsumption(), ...(this._data[this._key(actor, runId)] || {}) };
+  }
+
+  /**
+   * check(actor, runId, kind, amount, { budget }) — would recording `amount`
+   * more of `kind` exceed the budget? Read-only, no state mutated.
+   */
+  check(actor, runId, kind, amount = 1, { budget } = {}) {
+    const resolved = this.resolveBudget(budget);
+    const consumption = this.consumptionFor(actor, runId);
+    if (!resolved) return { allowed: true, cap: null, projected: consumption[kind] + amount, consumption };
+    const cap = resolved[kind];
+    if (!Number.isFinite(cap)) return { allowed: true, cap: null, projected: consumption[kind] + amount, consumption };
+    const projected = consumption[kind] + amount;
+    return { allowed: projected <= cap, cap, projected, consumption };
+  }
+
+  /** Durably record `amount` more of `kind` for actor+run. Returns the updated row. */
+  record(actor, runId, kind, amount = 1) {
+    const key = this._key(actor, runId);
+    const current = { ...emptyConsumption(), ...(this._data[key] || {}) };
+    current[kind] = (current[kind] || 0) + amount;
+    this._data[key] = current;
+    this._save();
+    return current;
+  }
+
+  /** Every actor+run row with its resolved budget, for status surfacing. */
+  allEntries() {
+    return Object.entries(this._data).map(([key, consumption]) => {
+      const sep = key.indexOf('::');
+      const actor = sep === -1 ? key : key.slice(0, sep);
+      const runId = sep === -1 ? null : key.slice(sep + 2);
+      return {
+        actor,
+        runId,
+        consumption: { ...emptyConsumption(), ...consumption },
+        budget: this.resolveBudget(undefined),
+      };
+    });
+  }
+}

package/lib/policy/engine.mjs

@@ -8,16 +8,24 @@
  * engine returns allow-without-approval everywhere.
  *
  * Decision precedence:
- *   1. Team-level decisions gate specialist decisions — forbidden by team blocks the action.
- *   2. Explicit deny in the role's fence → denied + typed reason.
- *   3. Action falls in the role's approvalRequired list → allowed but
+ *   0. Mandatory-audit gate (LMCP-H5) — enterprise only: if the audit sink is
+ *      down, every action is denied fail-closed before any other check runs.
+ *   1. Identity-anchored role authority (LMCP-I6) — in team/enterprise, an
+ *      env-claimed role not among the identity's registered grants is
+ *      denied before any manifest is consulted.
+ *   2. Team-level decisions gate specialist decisions — forbidden by team blocks the action.
+ *   3. Explicit deny in the role's fence → denied + typed reason.
+ *   4. Action falls in the role's approvalRequired list → allowed but
  *      approvalRequired = true (UI must collect human consent).
- *   4. risk === 'high' and role is not in HIGH_RISK_AUTONOMOUS → approval required.
- *   5. Otherwise → allowed.
+ *   5. risk === 'high' and role is not in HIGH_RISK_AUTONOMOUS → approval required.
+ *   6. Deny-by-default: team → deny unless explicit grant; enterprise → deny always.
+ *   7. solo → allowed.
  */
 
 import { readFileSync, existsSync } from 'node:fs';
 import { loadRegistry } from '../registry/loader.mjs';
+import { authorizeRoleClaim } from './role-authority.mjs';
+import { enforceMandatoryAudit } from './audit-gate.mjs';
 
 const HIGH_RISK_AUTONOMOUS = new Set(['security', 'sre', 'release-manager']);
 
@@ -97,6 +105,25 @@ function manifestFor(role, manifests) {
   return manifests?.personas?.[role] || null;
 }
 
+/**
+ * Return the default decision for unclassified (no matching explicit rule) tool calls.
+ *
+ * - solo       → 'allow'               (unchanged permissive behaviour)
+ * - team       → 'deny-unclassified'   (deny unless an explicit grant exists or the
+ *                                       user escapes with an approval flow)
+ * - enterprise → 'deny'               (hard deny regardless of approval escape)
+ *
+ * @param {'solo'|'team'|'enterprise'} deploymentMode
+ * @returns {'allow'|'deny-unclassified'|'deny'}
+ */
+export function getDefaultDecision(deploymentMode) {
+  switch (deploymentMode) {
+    case 'enterprise': return 'deny';
+    case 'team':       return 'deny-unclassified';
+    default:           return 'allow'; // solo and unknown → permissive
+  }
+}
+
 function actionMatches(pattern, action) {
   if (!pattern || !action) return false;
   if (pattern === action) return true;
@@ -125,15 +152,41 @@ function needsApprovalFromManifest(action, manifest) {
  * @param {string} input.action
  * @param {string} [input.decision] — optional decision id for team-level gate
  * @param {string} [input.risk]
+ * @param {'solo'|'team'|'enterprise'} [input.deploymentMode='solo'] — controls deny-by-default behaviour
+ * @param {object} [input.identity] — resolved actor/service identity (lib/identity.mjs). In
+ *   team/enterprise, `input.role` is validated as a claim against this identity's registered
+ *   grants (see lib/policy/role-authority.mjs) before any manifest lookup.
  * @param {object} [opts]
+ * @param {function} [opts.checkSink] — injectable audit-sink probe for LMCP-H5 tests;
+ *   defaults to the real fs-backed checkAuditSinkAvailable.
  * @returns {{allowed: boolean, reason: string, approvalRequired: boolean, source: string}}
  */
 export function policyDecision(input = {}, opts = {}) {
-  const { role, tool, action, decision, risk = 'low' } = input;
+  const { role, tool, action, decision, risk = 'low', deploymentMode = 'solo', identity } = input;
   if (!role) return { allowed: false, reason: 'role is required', approvalRequired: false, source: 'engine' };
   if (!tool) return { allowed: false, reason: 'tool is required', approvalRequired: false, source: 'engine' };
   if (!action) return { allowed: false, reason: 'action is required', approvalRequired: false, source: 'engine' };
 
+  const auditGateDecision = enforceMandatoryAudit({
+    deploymentMode,
+    ...(opts.checkSink ? { checkSink: opts.checkSink } : {}),
+  });
+  if (auditGateDecision) return auditGateDecision;
+
+  if ((deploymentMode === 'team' || deploymentMode === 'enterprise') && identity) {
+    if (identity.source === 'implicit-solo') {
+      return { allowed: false, reason: `Identity not resolved for ${deploymentMode} mode`, approvalRequired: false, source: 'identity-boundary' };
+    }
+
+    // Identity-anchored authority (LMCP-I6): the role claim under evaluation
+    // must be among the identity's registered grants — an env-declared role
+    // with no matching grant is denied before any manifest lookup runs.
+    const authority = authorizeRoleClaim({ identity, role, deploymentMode });
+    if (!authority.authorized) {
+      return { allowed: false, reason: authority.reason, approvalRequired: false, source: authority.source };
+    }
+  }
+
   const manifests = opts.manifests || loadRoleManifests(opts.manifestPath);
   const manifest = manifestFor(role, manifests);
 
@@ -186,6 +239,28 @@ export function policyDecision(input = {}, opts = {}) {
     };
   }
 
+  // Deny-by-default for team and enterprise modes.
+  // No explicit rule granted this action — consult the deployment-mode default.
+  const defaultDecision = getDefaultDecision(deploymentMode);
+  if (defaultDecision === 'deny') {
+    return {
+      allowed: false,
+      reason: 'deny-by-default',
+      approvalRequired: false,
+      mode: deploymentMode,
+      source: 'deny-by-default',
+    };
+  }
+  if (defaultDecision === 'deny-unclassified') {
+    return {
+      allowed: false,
+      reason: 'deny-by-default',
+      approvalRequired: false,
+      mode: deploymentMode,
+      source: 'deny-by-default',
+    };
+  }
+
   return {
     allowed: true,
     reason: `action "${action}" permitted for role "${role}"`,

package/lib/policy/role-authority.mjs

@@ -0,0 +1,89 @@
+/**
+ * lib/policy/role-authority.mjs — identity-anchored role claim authority.
+ *
+ * A6/ADR-0056 requires policy decisions to bind to actor/service identity
+ * (H2, lib/identity.mjs), not to a self-declared env var. Prior to this
+ * module, `CONSTRUCT_ROLE` alone selected the role manifest a caller was
+ * evaluated against — a worker could export the env var and claim any
+ * role's authority, including `security` or `release-manager`, with no
+ * check against who the identity actually is.
+ *
+ * `authorizeRoleClaim` closes that gap: it takes the resolved identity
+ * (from resolveIdentity()) and the role claim under evaluation, and
+ * decides whether the identity is entitled to act as that role.
+ *
+ * Registered-grants source: `identity.grants` — a list of role ids the
+ * identity is registered for. This is the seam LMCP-G5 (worker
+ * registration/heartbeat) and pack `toolGrantsRequested` (LMCP-E1) populate;
+ * neither exists as a live registration store yet, so until G5 lands the
+ * only way an identity acquires a grant is an explicit `identity.grants`
+ * array set by the caller that resolved the identity (e.g. from a signed
+ * header, a worker registration record, or test fixture). No implicit
+ * grants are invented here — an identity with no `grants` array has none.
+ *
+ * Mode behavior:
+ *   - solo: always authorized. CONSTRUCT_ROLE remains a documented
+ *     solo-only convenience (lib/identity.mjs env fallback); there is no
+ *     registration authority to check against in single-user mode.
+ *   - team / enterprise: the claimed role must be present in the
+ *     identity's `grants`. A role claim sourced from `env-fallback` (an
+ *     env var with no actor identity headers at all) is never itself
+ *     trusted as a grant — it is a claim, and claims are checked, not
+ *     trusted. Missing or non-matching grants are DENIED (fail closed).
+ */
+
+export class RoleAuthorityError extends Error {
+  constructor(message) { super(message); this.name = 'RoleAuthorityError'; }
+}
+
+/**
+ * Return the set of role ids an identity is registered for.
+ *
+ * `identity.grants` is the only source read today (see file header for
+ * why). Absent/malformed values resolve to an empty set — never to "all
+ * roles" — so a caller who forgets to populate grants fails closed rather
+ * than silently trusting the claim.
+ *
+ * @param {object} identity
+ * @returns {Set<string>}
+ */
+export function resolveIdentityGrants(identity) {
+  const grants = identity?.grants;
+  if (!Array.isArray(grants)) return new Set();
+  return new Set(grants.filter((g) => typeof g === 'string' && g.length > 0));
+}
+
+/**
+ * Decide whether `role` is an authorized claim for `identity` under
+ * `deploymentMode`.
+ *
+ * @param {object} input
+ * @param {object} input.identity - resolved identity (lib/identity.mjs shape)
+ * @param {string} input.role - the role claim under evaluation
+ * @param {'solo'|'team'|'enterprise'} [input.deploymentMode='solo']
+ * @returns {{authorized: boolean, reason: string, source: string}}
+ */
+export function authorizeRoleClaim({ identity, role, deploymentMode = 'solo' } = {}) {
+  if (!role) {
+    return { authorized: false, reason: 'role claim is required', source: 'role-authority' };
+  }
+
+  if (deploymentMode !== 'team' && deploymentMode !== 'enterprise') {
+    return { authorized: true, reason: 'solo mode: env-claimed role permitted (documented convenience)', source: 'solo-ergonomics' };
+  }
+
+  if (!identity) {
+    return { authorized: false, reason: `no identity resolved to validate role claim "${role}" in ${deploymentMode} mode`, source: 'role-authority' };
+  }
+
+  const grants = resolveIdentityGrants(identity);
+  if (grants.has(role)) {
+    return { authorized: true, reason: `role "${role}" is a registered grant for this identity`, source: 'identity-grant' };
+  }
+
+  return {
+    authorized: false,
+    reason: `role claim "${role}" is not in this identity's registered grants in ${deploymentMode} mode`,
+    source: 'role-authority.ungranted',
+  };
+}

package/lib/prompt-composer.js

@@ -39,7 +39,7 @@ import { estimateTokens, estimatePromptTokens, estimateTokensSync } from './toke
 import { cxDir } from './paths.mjs';
 import { getStrategyDigestSync } from './strategy-store.mjs';
 import { loadRegistry } from './registry/loader.mjs';
-import { bindingForSpecialist, resolveRoleOverlayId } from './roles/flavor-bindings.mjs';
+import { bindingForSpecialist, bindingsForSpecialistId, resolveRoleOverlayId } from './roles/flavor-bindings.mjs';
 
 const MAX_OBSERVATIONS = 3;
 
@@ -254,12 +254,23 @@ export function composePrompt(agentName, {
   }
 
   const shortName = String(agentName).replace(/^cx-/, '');
-  const flavorMapping = bindingForSpecialist(shortName);
 
   // When workspaceType is provided and roleFlavors doesn't already specify this agent's flavor,
   // auto-select the matching overlay so agents get domain guidance without requiring explicit caller config.
   const effectiveRoleFlavors = resolveRoleFlavors(roleFlavors, workspaceType, shortName);
 
+  // Since construct-rf26.11, one specialist can carry several flavor bindings
+  // (e.g. cx-engineer owns engineer/ai-engineer/platform-engineer/data-engineer
+  // overlays). Prefer whichever candidate binding's classifierKey the caller
+  // actually named in roleFlavors over the specialist's own bare-name binding,
+  // so a flavor-specific request (roleFlavors.platformEngineer) still resolves
+  // even though bindingForSpecialist(shortName) alone would only ever return
+  // the base 'engineer' entry.
+  const candidates = bindingsForSpecialistId(agentName);
+  const flavorMapping = (effectiveRoleFlavors
+    && candidates.find((b) => effectiveRoleFlavors[b.classifierKey]))
+    || bindingForSpecialist(shortName);
+
   if (flavorMapping && effectiveRoleFlavors) {
     const flavor = effectiveRoleFlavors[flavorMapping.classifierKey];
     if (flavor) {
@@ -276,7 +287,12 @@ export function composePrompt(agentName, {
           type: 'role-flavor',
           priority: PRIORITY['role-flavor'],
           label: roleId,
-          content: `### ${flavor === 'core' ? shortName : flavor} domain guidance\n\n${overlayContent}`,
+          // flavorMapping.rolePrefix (not the agent's own shortName) names the
+          // domain guidance: since construct-rf26.11 one specialist can carry
+          // several flavor bindings (e.g. cx-engineer), and shortName only
+          // ever reflects the specialist's own bare name, not which of its
+          // several possible overlays actually matched.
+          content: `### ${flavor === 'core' ? flavorMapping.rolePrefix : flavor} domain guidance\n\n${overlayContent}`,
           tokenBudget: selectedProfile.roleFlavorTokens,
         });
       }

package/lib/providers/contract/adapters/confluence/governed-write.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/providers/contract/adapters/confluence/governed-write.mjs —
+ * envelope-shaped Confluence write adapter.
+ *
+ * Wraps a Confluence REST transport in the provider shape
+ * lib/writes/envelope.mjs expects: write(config, payload), meta.id,
+ * search(). This is the only exposed entry point for Confluence writes —
+ * specialists and CLI callers route through writeWithEnvelope(), never
+ * through a raw Confluence client, so dedup, retry, dry-run, approval, and
+ * audit stay centralized in the envelope (LMCP-J2) rather than being
+ * reimplemented per-adapter.
+ *
+ * Adds the three behaviors a generic envelope cannot provide:
+ *
+ *   - Duplicate detection by title+space: before create, searches the
+ *     target space for an existing page with the same title (via the
+ *     injected `confluenceTransport.searchPagesByTitle`). A match returns a
+ *     `page-duplicate` result carrying a `linkback` to the existing page
+ *     instead of creating a second page — mirrors the GitHub adapter's
+ *     marker-search dedup (LMCP-J-github) but keyed on title+space rather
+ *     than a hidden marker, since Confluence page search has no analogue to
+ *     GitHub's full-text issue search over a hidden comment.
+ *   - Version-conflict recovery on update: Confluence page updates require
+ *     the current `version.number`; if the page changed since the caller
+ *     last fetched it, the API returns 409. On 409 this adapter refetches
+ *     the live page, re-renders the caller's update against the fresh
+ *     version, and returns a `version-conflict` result carrying the fresh
+ *     page and a `retryPayload` — the caller (or a human via the envelope's
+ *     approval path) re-approves before the adapter retries the write. The
+ *     adapter never blindly overwrites a page that changed underneath it.
+ *   - Linkback comment: after a successful create or update, posts a footer
+ *     comment on the page recording the write's idempotency key, so anyone
+ *     reading the page in Confluence can trace which governed write
+ *     produced or last touched it.
+ */
+
+import { AuthError } from '../../errors.mjs';
+
+const LINKBACK_PREFIX = 'construct:write:';
+
+function linkbackComment(idempotencyKey) {
+  return `<p>Published via Construct governed write (${LINKBACK_PREFIX}${idempotencyKey}).</p>`;
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.confluenceTransport - underlying Confluence REST transport; must implement
+ *   `searchPagesByTitle(spaceId, title)`, `getPage(pageId)`, `createPage(fields)`,
+ *   `updatePage(fields)`, `createFooterComment(pageId, body)`.
+ */
+export function createGovernedConfluenceProvider({ confluenceTransport } = {}) {
+  if (!confluenceTransport) throw new Error('createGovernedConfluenceProvider: confluenceTransport is required');
+
+  async function postLinkback(pageId, idempotencyKey) {
+    if (!idempotencyKey) return;
+    try {
+      await confluenceTransport.createFooterComment(pageId, linkbackComment(idempotencyKey));
+    } catch {
+      // Linkback is best-effort audit trail on the page itself; the
+      // envelope's sent-log is the authoritative record, so a comment
+      // failure must not fail an otherwise-successful publish.
+    }
+  }
+
+  async function writePage(payload) {
+    const { spaceId, title, body, parentId, idempotencyKey } = payload;
+    if (!spaceId) throw new Error('confluence governed write: payload.spaceId is required for type "page"');
+    if (!title) throw new Error('confluence governed write: payload.title is required for type "page"');
+
+    let existing;
+    try {
+      existing = await confluenceTransport.searchPagesByTitle(spaceId, title);
+    } catch (err) {
+      throw mapWriteTransportError(err, { spaceId });
+    }
+
+    const match = (existing ?? []).find((p) => p.title === title);
+    if (match) {
+      return {
+        type: 'page-duplicate',
+        id: match.id,
+        title: match.title,
+        url: match.url,
+        linkback: match.url,
+      };
+    }
+
+    try {
+      const result = await confluenceTransport.createPage({ spaceId, title, body, parentId });
+      await postLinkback(result.id, idempotencyKey);
+      return { type: 'page-created', id: result.id, title: result.title, version: result.version, url: result.url };
+    } catch (err) {
+      throw mapWriteTransportError(err, { spaceId });
+    }
+  }
+
+  async function writePageUpdate(payload) {
+    const { pageId, title, body, version, idempotencyKey } = payload;
+    if (!pageId) throw new Error('confluence governed write: payload.pageId is required for type "page-update"');
+    if (version === undefined || version === null) {
+      throw new Error('confluence governed write: payload.version is required for type "page-update"');
+    }
+
+    try {
+      const result = await confluenceTransport.updatePage({ pageId, title, body, version });
+      await postLinkback(pageId, idempotencyKey);
+      return { type: 'page-updated', id: result.id, title: result.title, version: result.version, url: result.url };
+    } catch (err) {
+      if (err?.status === 409) {
+        const fresh = await confluenceTransport.getPage(pageId);
+        return {
+          type: 'version-conflict',
+          id: pageId,
+          url: fresh.url,
+          currentVersion: fresh.version,
+          currentBody: fresh.body,
+          currentTitle: fresh.title,
+          retryPayload: {
+            type: 'page-update',
+            pageId,
+            title: title ?? fresh.title,
+            body,
+            version: fresh.version,
+            idempotencyKey,
+          },
+        };
+      }
+      throw mapWriteTransportError(err, { pageId });
+    }
+  }
+
+  return {
+    meta: {
+      id: 'confluence',
+      displayName: 'Confluence (governed)',
+      capabilities: ['write', 'search'],
+      description: 'Envelope-routed Confluence writes with title+space dedup, version-conflict recovery, and linkback comments.',
+    },
+
+    async write(config, payload) {
+      if (payload?.type === 'page') return writePage(payload);
+      if (payload?.type === 'page-update') return writePageUpdate(payload);
+      throw new Error(`confluence governed write: unsupported type "${payload?.type}" (only 'page' and 'page-update' are supported)`);
+    },
+
+    async search(config, query) {
+      const spaceId = typeof query === 'object' ? query?.spaceId : undefined;
+      const title = typeof query === 'object' ? query?.title : query;
+      return confluenceTransport.searchPagesByTitle(spaceId, title);
+    },
+
+    /**
+     * Render the payload the envelope would submit, without calling search,
+     * getPage, or the transport. Feeds the envelope's dry-run path
+     * (lib/writes/envelope.mjs `dryRun: true`), giving a human reviewing a
+     * pending write the exact storage-format body and target coordinates
+     * before anything is sent.
+     *
+     * @param {object} payload
+     * @returns {{ type: string, fields: object }}
+     */
+    renderDryRun(payload) {
+      if (payload?.type === 'page') {
+        return {
+          type: 'page',
+          fields: {
+            spaceId: payload.spaceId,
+            title: payload.title,
+            parentId: payload.parentId,
+            body: { representation: 'storage', value: payload.body },
+          },
+        };
+      }
+      if (payload?.type === 'page-update') {
+        return {
+          type: 'page-update',
+          fields: {
+            pageId: payload.pageId,
+            title: payload.title,
+            version: { number: payload.version },
+            body: { representation: 'storage', value: payload.body },
+          },
+        };
+      }
+      throw new Error(`confluence governed write: cannot render dry-run for unsupported type "${payload?.type}"`);
+    },
+  };
+}
+
+/**
+ * Map a create/update/search transport failure (401/403/404) to an
+ * actionable message. 409 (version conflict) is handled by the caller
+ * directly and never reaches this mapper.
+ *
+ * @param {Error & {status?: number}} err
+ * @param {{ spaceId?: string, pageId?: string }} ctx
+ * @returns {Error}
+ */
+function mapWriteTransportError(err, ctx) {
+  const status = err?.status;
+  if (status === 401) {
+    return new AuthError('Confluence authentication failed. Check CONFLUENCE_EMAIL / CONFLUENCE_TOKEN.', { provider: 'confluence' });
+  }
+  if (status === 403) {
+    const target = ctx.spaceId ? `space "${ctx.spaceId}"` : `page "${ctx.pageId}"`;
+    return new Error(`Forbidden: the authenticated account lacks permission to write to ${target}. Check the confluence-content:write scope.`);
+  }
+  if (status === 404) {
+    const target = ctx.spaceId ? `Space "${ctx.spaceId}"` : `Page "${ctx.pageId}"`;
+    return new Error(`${target} was not found, or the authenticated account cannot access it.`);
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+export default createGovernedConfluenceProvider;