@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/workflows/manifest-schema.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/workflows/manifest-schema.mjs — canonical workflow manifest schema descriptor.
+ *
+ * Defines the vocabulary for workflow manifests as per ADR-0054 (LMCP-A4).
+ * A plain JS descriptor, not JSON Schema — the validator in validate.mjs
+ * consumes it directly. The schema is intentionally additive: new optional fields
+ * may be added in a minor version bump; new required fields or type removals are
+ * breaking and require a COMPAT_VERSION increment.
+ */
+
+/**
+ * All valid workflow type values. These correspond to the execution topologies
+ * the orchestration runtime can dispatch. `embed` (ADR-0061, LMCP-P1/P2) is a
+ * workflow-manifest specialization carrying an `embed` block rather than a
+ * dispatchable topology — it reuses this schema's id/version/tiering rules
+ * instead of forking a second manifest system.
+ */
+export const WORKFLOW_TYPES = ['linear', 'routing', 'orchestrator-worker', 'evaluator-loop', 'pipeline', 'embed'];
+
+/**
+ * Fields every workflow manifest must carry. Absence of any required field is a
+ * hard validation error and the manifest is rejected.
+ */
+export const WORKFLOW_REQUIRED_FIELDS = ['id', 'version', 'type', 'defaultApprovalMode'];
+
+/**
+ * Fields a workflow manifest may carry. These are not validated for shape — the
+ * validator checks only presence of required fields and semantic constraints.
+ * Manifests that add fields outside this list are accepted but their extra
+ * fields are ignored by core consumers.
+ *
+ * `intakeType` (LMCP-D3) lets a pack or project manifest claim a triage
+ * classifier label without editing the hardcoded INTAKE_TO_WORKFLOW table in
+ * lib/embedded-contract/workflow-defs.mjs — the shim rebuilds that table from
+ * every loaded manifest's `intakeType` field, project/pack entries applied
+ * after builtins so a contributed manifest can add or remap a label.
+ */
+export const WORKFLOW_OPTIONAL_FIELDS = [
+  'modes', 'surfaces', 'inputSchema', 'outputSchema',
+  'roleChain', 'packRequirements', 'providerRequirements',
+  'toolGrants', 'policyGates', 'durableStateModel',
+  'telemetryEvents', 'tests', 'docs', 'examples',
+  'degradation', 'owner', 'compatVersion', 'description', 'tier',
+  'intakeType',
+];
+
+/**
+ * Current schema version. A manifest with compatVersion > WORKFLOW_COMPAT_VERSION
+ * was written for a newer schema than this runtime understands — load is refused
+ * to prevent silent misinterpretation. Forward compatibility is not guaranteed.
+ */
+export const WORKFLOW_COMPAT_VERSION = 1;
+
+/**
+ * All valid approval mode values. These govern whether a workflow run proceeds
+ * without human intervention or requires explicit approval at one or more gates.
+ */
+export const APPROVAL_MODES = ['proposal-only', 'requires-human-approval', 'allow-durable-write'];
+
+/**
+ * All valid durable state model values. These describe how the workflow runtime
+ * persists intermediate state across invocations for resumability and audit.
+ */
+export const DURABLE_STATE_MODELS = ['none', 'git-queue', 'in-process'];
+
+/**
+ * All valid model tier values. These hint at the minimum model capability the
+ * orchestrator should assign to the workflow, from fastest/cheapest to most
+ * capable/expensive.
+ */
+export const TIERS = ['fast', 'standard', 'reasoning'];

package/lib/workflows/surface-parity.mjs

@@ -0,0 +1,118 @@
+/**
+ * lib/workflows/surface-parity.mjs — workflow manifest surface-parity check (LMCP-D4).
+ *
+ * Compares each workflow manifest's declared `surfaces` field against its
+ * ACTUAL registration, derived from the real dispatch code rather than
+ * inferred:
+ *
+ *   - lib/embedded-contract/workflow-invoke.mjs exports one `invokeWorkflow`
+ *     core that CLI (`construct workflow invoke --workflow-type`, bin/construct
+ *     cmdWorkflow), MCP (`workflow_invoke`, lib/mcp/tools/embedded-contract.mjs),
+ *     and SDK (`invokeWorkflow`, lib/embedded-contract/index.mjs) all wrap
+ *     unchanged (lib/embedded-contract/envelope.mjs even documents the three
+ *     surfaces as "structurally identical"). That core resolves a workflow id
+ *     through `getWorkflowDef` (lib/embedded-contract/workflow-defs.mjs),
+ *     whose DEFS table is generated from every loaded manifest with
+ *     `type !== 'embed'`.
+ *   - A manifest with `type !== 'embed'` is therefore registered on cli, mcp,
+ *     AND sdk simultaneously — there is no dispatch path that can register a
+ *     workflow id on one of the three without the other two, so per-manifest
+ *     divergence between them is structurally impossible today. sdk carries
+ *     no separate opt-in and is reported as an info line, never a checkable
+ *     declared/actual pair — flagging it as a per-manifest mismatch would
+ *     fail every manifest for a fact no author can change.
+ *   - A manifest with `type === 'embed'` (ADR-0061) is scheduled by the embed
+ *     daemon on a cadence; it is never reached through workflow_invoke /
+ *     `construct workflow invoke` / SDK invokeWorkflow at all, so its actual
+ *     registration is the empty set on cli and mcp.
+ *
+ * checkSurfaceParity() flags two failure shapes as errors:
+ *   1. A manifest declares a surface ('cli' or 'mcp') it is not actually
+ *      registered on (an embed manifest declaring 'cli'/'mcp', or a non-embed
+ *      manifest whose id is absent from WORKFLOW_TYPES because it failed to
+ *      load into workflow-defs.mjs).
+ *   2. A non-embed manifest omits a surface ('cli' or 'mcp') it IS actually
+ *      registered on.
+ * Both shapes are suppressed, with a passing info line instead, when the
+ * manifest carries a `surfaceExceptions` map with a non-empty `reason` string
+ * for that surface — `surfaceExceptions` is an optional, unvalidated field
+ * (manifests load with strict:false in this caller, so unknown fields pass
+ * through) rather than a schema addition, keeping this rule additive.
+ */
+
+import { WORKFLOW_TYPES } from '../embedded-contract/workflow-defs.mjs';
+
+/** The two surfaces a manifest can meaningfully declare/omit per-workflow. */
+export const DECLARABLE_SURFACES = ['cli', 'mcp'];
+
+/**
+ * Actual registration for a manifest, derived from workflow-defs.mjs's DEFS
+ * table (built from loadAllWorkflows() — the same loader this check itself
+ * consumes elsewhere) rather than re-implemented here.
+ *
+ * @param {object} manifest
+ * @returns {string[]} subset of DECLARABLE_SURFACES the manifest is actually
+ *   dispatchable on; sdk is always additionally true for non-embed manifests
+ *   but is not part of this declarable set (see module header).
+ */
+export function actualSurfaces(manifest) {
+  if (!manifest || manifest.type === 'embed') return [];
+  return WORKFLOW_TYPES.includes(manifest.id) ? [...DECLARABLE_SURFACES] : [];
+}
+
+/**
+ * Look up a manifest's declared exception reason for a surface, if any.
+ *
+ * @param {object} manifest
+ * @param {string} surface
+ * @returns {string|null} the reason string, or null when no valid exception is declared
+ */
+function exceptionReason(manifest, surface) {
+  const exceptions = manifest?.surfaceExceptions;
+  if (!exceptions || typeof exceptions !== 'object') return null;
+  const entry = exceptions[surface];
+  if (typeof entry === 'string' && entry.trim()) return entry;
+  if (entry && typeof entry === 'object' && typeof entry.reason === 'string' && entry.reason.trim()) return entry.reason;
+  return null;
+}
+
+/**
+ * checkSurfaceParity(manifests)
+ *
+ * Runs the surface-parity check over an already-loaded manifest list (each
+ * carrying `_filePath` and `id`, per lib/workflows/loader.mjs). Never throws.
+ *
+ * @param {object[]} manifests
+ * @returns {{ errors: string[], infos: string[] }}
+ */
+export function checkSurfaceParity(manifests = []) {
+  const errors = [];
+  const infos = [];
+
+  for (const manifest of manifests) {
+    const label = manifest._filePath || manifest.id || '(unknown manifest)';
+    const declared = new Set(Array.isArray(manifest.surfaces) ? manifest.surfaces : []);
+    const actual = new Set(actualSurfaces(manifest));
+
+    for (const surface of DECLARABLE_SURFACES) {
+      const isDeclared = declared.has(surface);
+      const isActual = actual.has(surface);
+      if (isDeclared === isActual) continue;
+
+      const reason = exceptionReason(manifest, surface);
+      if (reason) {
+        const shape = isDeclared ? 'declared but not registered' : 'registered but not declared';
+        infos.push(`${label}: workflow '${manifest.id}' surface '${surface}' is ${shape} — declared exception: ${reason}`);
+        continue;
+      }
+
+      if (isDeclared && !isActual) {
+        errors.push(`${label}: workflow '${manifest.id}' declares surface '${surface}' but is not actually registered there (no reason given — add a 'surfaceExceptions.${surface}' reason or remove the declaration)`);
+      } else {
+        errors.push(`${label}: workflow '${manifest.id}' is registered on surface '${surface}' but does not declare it in 'surfaces' (no reason given — add '${surface}' to 'surfaces' or a 'surfaceExceptions.${surface}' reason)`);
+      }
+    }
+  }
+
+  return { errors, infos };
+}

package/lib/workflows/validate.mjs

@@ -0,0 +1,127 @@
+/**
+ * lib/workflows/validate.mjs — workflow manifest validator.
+ *
+ * Validates a plain-JS manifest object against the canonical schema defined in
+ * manifest-schema.mjs. All errors are returned in a structured result; this
+ * function never throws. Error messages are single-line, actionable, and
+ * prefixed with the filePath (when provided) so consumers can surface them
+ * directly to users.
+ */
+
+import {
+  WORKFLOW_TYPES, WORKFLOW_REQUIRED_FIELDS, WORKFLOW_OPTIONAL_FIELDS,
+  WORKFLOW_COMPAT_VERSION, APPROVAL_MODES,
+} from './manifest-schema.mjs';
+
+/** Basic semver pattern: MAJOR.MINOR.PATCH with optional pre-release/build metadata. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/;
+
+/** Valid id characters: lowercase alphanumeric, hyphens, dots, forward slashes. */
+const ID_RE = /^[a-z0-9\-./]+$/;
+
+/**
+ * validateWorkflowManifest(manifest, { filePath, strict } = {})
+ *
+ * Returns { valid: true } on success, or { valid: false, errors: string[] }
+ * on failure. Every error string is a self-contained, single-line description
+ * of the problem. The filePath prefix is included in every error so callers
+ * can surface messages without additional decoration.
+ *
+ * Checks performed (in order):
+ *   1. Manifest is a non-null object.
+ *   2. Required fields are present.
+ *   3. `type` is one of the canonical WORKFLOW_TYPES.
+ *   4. `version` matches the semver pattern.
+ *   5. `id` is a non-empty string matching [a-z0-9-./]+.
+ *   6. `compatVersion` (if present) does not exceed WORKFLOW_COMPAT_VERSION.
+ *   7. `defaultApprovalMode` is one of APPROVAL_MODES.
+ *
+ * When strict is true, unknown fields (outside REQUIRED + OPTIONAL) are rejected.
+ *
+ * @param {unknown} manifest - The parsed manifest object to validate.
+ * @param {{ filePath?: string, strict?: boolean }} [opts]
+ * @returns {{ valid: true } | { valid: false, errors: string[] }}
+ */
+export function validateWorkflowManifest(manifest, { filePath, strict = false } = {}) {
+  const prefix = filePath ? `${filePath}: ` : '';
+  const errors = [];
+
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { valid: false, errors: [`${prefix}manifest must be a JSON object`] };
+  }
+
+  // Required fields
+  for (const field of WORKFLOW_REQUIRED_FIELDS) {
+    if (!(field in manifest) || manifest[field] === undefined || manifest[field] === null) {
+      errors.push(`${prefix}missing required field: ${field}`);
+    }
+  }
+
+  // type check (only if type is present — otherwise already flagged above)
+  if ('type' in manifest && manifest.type !== undefined && manifest.type !== null) {
+    if (!WORKFLOW_TYPES.includes(manifest.type)) {
+      errors.push(
+        `${prefix}unknown type '${manifest.type}'; expected one of: ${WORKFLOW_TYPES.join(', ')}`
+      );
+    }
+  }
+
+  // version semver check
+  if ('version' in manifest && manifest.version !== undefined && manifest.version !== null) {
+    if (typeof manifest.version !== 'string' || !SEMVER_RE.test(manifest.version)) {
+      errors.push(`${prefix}version must be a semver string`);
+    }
+  }
+
+  // id format check
+  if ('id' in manifest && manifest.id !== undefined && manifest.id !== null) {
+    if (typeof manifest.id !== 'string' || manifest.id.length === 0) {
+      errors.push(`${prefix}id must be a non-empty string`);
+    } else if (!ID_RE.test(manifest.id)) {
+      errors.push(`${prefix}id must match [a-z0-9-./]+ (got '${manifest.id}')`);
+    }
+  }
+
+  // Forward-compat guard
+  if (
+    manifest.compatVersion !== undefined &&
+    manifest.compatVersion !== null
+  ) {
+    if (typeof manifest.compatVersion !== 'number' || !Number.isInteger(manifest.compatVersion)) {
+      errors.push(`${prefix}compatVersion must be an integer`);
+    } else if (manifest.compatVersion > WORKFLOW_COMPAT_VERSION) {
+      errors.push(
+        `${prefix}compatVersion ${manifest.compatVersion} exceeds supported version ${WORKFLOW_COMPAT_VERSION}; upgrade Construct to use this manifest`
+      );
+    }
+  }
+
+  // defaultApprovalMode check
+  if (
+    'defaultApprovalMode' in manifest &&
+    manifest.defaultApprovalMode !== undefined &&
+    manifest.defaultApprovalMode !== null
+  ) {
+    if (!APPROVAL_MODES.includes(manifest.defaultApprovalMode)) {
+      errors.push(
+        `${prefix}defaultApprovalMode must be one of: ${APPROVAL_MODES.join(', ')} (got '${manifest.defaultApprovalMode}')`
+      );
+    }
+  }
+
+  // Strict-mode hardening: reject unknown fields
+  if (strict) {
+    const knownFields = new Set([...WORKFLOW_REQUIRED_FIELDS, ...WORKFLOW_OPTIONAL_FIELDS]);
+    for (const key of Object.keys(manifest)) {
+      if (key.startsWith('_')) continue;
+      if (!knownFields.has(key)) {
+        errors.push(`${prefix}unknown field '${key}' in strict mode`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return { valid: true };
+}

package/lib/writes/control-plane.mjs

@@ -0,0 +1,140 @@
+/**
+ * lib/writes/control-plane.mjs — the only entry point that turns a queued
+ * writeIntent into an executed write (LMCP-J6).
+ *
+ * A specialist (in-process, embed-invoked, or MCP-invoked) may only ever
+ * *recommend* a write: it produces a writeIntent (lib/writes/write-intent.mjs)
+ * and hands it to an ApprovalQueue (lib/embed/approval-queue.mjs, the F5/I2
+ * durable queue). Nothing else in this file, nor anywhere outside it, is
+ * permitted to resolve a governed-write adapter and call
+ * lib/writes/envelope.mjs's writeWithEnvelope() for a queue-sourced intent —
+ * that resolution + call happens exclusively in executeApprovedWriteIntent()
+ * below, gated on the queue record's own state.
+ *
+ * Concretely, the state machine this module enforces:
+ *   1. ApprovalQueue.enqueue() records state 'awaiting_approval' — this
+ *      module never calls a governed adapter for a record in that state.
+ *   2. A human or policy actor calls ApprovalQueue.approve()/deny() out of
+ *      band (CLI, dashboard, MCP resume) — this module does not decide
+ *      approval, it only checks the decision already recorded.
+ *   3. drainApprovedWriteIntents() scans the queue for state === 'approved'
+ *      records this module has not yet executed, resolves the matching
+ *      governed adapter (lib/providers/contract/adapters/*\/governed-write.mjs,
+ *      built by J3-J5), and calls writeWithEnvelope() exactly once per
+ *      record — the envelope's own idempotency key + sent-log dedup still
+ *      apply on top, so a re-drain of an already-sent record is a cache hit,
+ *      not a second external write.
+ *
+ * No dependency on lib/embed/daemon.mjs or lib/embed/capability-jobs.mjs —
+ * only the ApprovalQueue class shape is required, so a queue instance handed
+ * over by the daemon, a CLI command, or a test drains the same way, without
+ * reaching into daemon internals.
+ */
+
+import { writeWithEnvelope } from './envelope.mjs';
+import { WriteSentLog } from './sent-log.mjs';
+import { parseWriteIntentToolName } from './write-intent.mjs';
+import { createGovernedJiraProvider } from '../providers/contract/adapters/jira/governed-write.mjs';
+import { createJiraTransport } from '../providers/contract/adapters/jira/transport.mjs';
+import { createGovernedConfluenceProvider } from '../providers/contract/adapters/confluence/governed-write.mjs';
+import { createConfluenceTransport } from '../providers/contract/adapters/confluence/transport.mjs';
+import { createGovernedGithubProvider } from '../providers/contract/adapters/github/governed-write.mjs';
+import githubAdapter from '../providers/contract/adapters/github/index.mjs';
+
+/**
+ * Default adapter factories, one per known governed provider. Lazy per-call
+ * construction (not module-load-time) keeps a missing-credential error
+ * scoped to the one drain call that needed that provider, matching
+ * lib/mcp/tools/provider-write.mjs's resolution strategy.
+ */
+const DEFAULT_ADAPTER_FACTORIES = {
+  jira: () => createGovernedJiraProvider({ jiraTransport: createJiraTransport() }),
+  confluence: () => createGovernedConfluenceProvider({ confluenceTransport: createConfluenceTransport() }),
+  github: () => createGovernedGithubProvider({ ghAdapter: githubAdapter }),
+};
+
+/**
+ * Execute exactly one approved queue record through the envelope. Throws if
+ * the record's state is not 'approved' — this is the structural gate: there
+ * is no code path in this module that reaches writeWithEnvelope() without
+ * first observing state === 'approved' on the queue record itself.
+ *
+ * @param {object} record - an ApprovalQueue record (state, toolCall, requestedBy, approvalId)
+ * @param {object} [opts]
+ * @param {Record<string, () => object>} [opts.adapterFactories] - override adapter resolution (tests)
+ * @param {WriteSentLog} [opts.sentLog]
+ * @param {string} [opts.rootDir]
+ * @returns {Promise<object>} the envelope result ({ status, envelope })
+ */
+export async function executeApprovedWriteIntent(record, opts = {}) {
+  if (!record || record.state !== 'approved') {
+    throw new Error(
+      `executeApprovedWriteIntent: refusing to execute record in state "${record?.state ?? 'unknown'}" — only 'approved' records may reach the envelope`,
+    );
+  }
+
+  const parsed = parseWriteIntentToolName(record.toolCall?.tool);
+  if (!parsed) {
+    throw new Error(`executeApprovedWriteIntent: cannot resolve provider from tool name "${record.toolCall?.tool}"`);
+  }
+
+  const factories = opts.adapterFactories ?? DEFAULT_ADAPTER_FACTORIES;
+  const factory = factories[parsed.providerId];
+  if (!factory) {
+    throw new Error(`executeApprovedWriteIntent: no governed adapter registered for provider "${parsed.providerId}"`);
+  }
+  const adapter = factory();
+
+  const sentLog = opts.sentLog ?? new WriteSentLog({ persistPath: WriteSentLog.resolvePersistPath(opts.rootDir ?? process.cwd()) });
+
+  return writeWithEnvelope({
+    provider: adapter,
+    config: {},
+    payload: { type: parsed.writeKind, ...(record.toolCall?.args ?? {}) },
+    dryRun: false,
+    sentLog,
+    idempotencyKey: record.toolCall?.argsHash,
+    requestedBy: record.requestedBy ?? {},
+  });
+}
+
+/**
+ * Drain every 'approved' record in an ApprovalQueue through the envelope,
+ * marking each executed record so a subsequent drain does not re-execute it
+ * (the envelope's sent-log dedup is a second, independent line of defense,
+ * not the only one — this in-memory executed-set makes the "exactly one
+ * adapter call" property observable per drain call even before sent-log
+ * persistence is consulted).
+ *
+ * Records in any other state ('awaiting_approval', 'denied', 'expired') are
+ * left untouched — this is read-only with respect to the queue's approval
+ * decision, it only ever appends outcomes for records already decided
+ * 'approved' by something outside this module.
+ *
+ * @param {import('../embed/approval-queue.mjs').ApprovalQueue} approvalQueue
+ * @param {object} [opts]
+ * @param {Record<string, () => object>} [opts.adapterFactories]
+ * @param {WriteSentLog} [opts.sentLog]
+ * @param {string} [opts.rootDir]
+ * @param {Set<string>} [opts.executedApprovalIds] - approvalIds already drained; mutated in place
+ * @returns {Promise<Array<{ approvalId: string, result: object|null, error: string|null }>>}
+ */
+export async function drainApprovedWriteIntents(approvalQueue, opts = {}) {
+  const executed = opts.executedApprovalIds ?? new Set();
+  const outcomes = [];
+
+  const approvedRecords = approvalQueue.list('approved');
+  for (const record of approvedRecords) {
+    if (executed.has(record.approvalId)) continue;
+
+    try {
+      const result = await executeApprovedWriteIntent(record, opts);
+      executed.add(record.approvalId);
+      outcomes.push({ approvalId: record.approvalId, result, error: null });
+    } catch (err) {
+      outcomes.push({ approvalId: record.approvalId, result: null, error: err.message ?? String(err) });
+    }
+  }
+
+  return outcomes;
+}

package/lib/writes/envelope.mjs

@@ -0,0 +1,206 @@
+/**
+ * lib/writes/envelope.mjs — the single governed path for external writes.
+ *
+ * writeWithEnvelope() runs every external write through: idempotency key →
+ * sent-log dedup → dry-run render → policy/approval gate → rate-limited retry →
+ * sent-log append + audit. Specialists never call provider adapters directly;
+ * they recommend a write-intent and the control plane executes it here.
+ */
+
+import crypto from 'node:crypto';
+import { WriteSentLog } from './sent-log.mjs';
+import { ApprovalQueue } from '../embed/approval-queue.mjs';
+
+/**
+ * Execute a governed write through the envelope.
+ *
+ * Flow:
+ *   1. Generate idempotency key (if none provided) from provider + writeType + stable payload hash
+ *   2. Check sent-log: if same key already succeeded, return cached result
+ *   3. Dry-run mode: return rendered payload without executing
+ *   4. Policy gate: if broker provided, run policy check
+ *      - If approval required, create durable approval record and return awaiting_approval
+ *   5. Execute provider.write() with retry
+ *   6. Record in sent-log
+ *   7. Append audit record
+ *   8. Return structured result with linkback
+ *
+ * @param {object} spec
+ * @param {object} spec.provider - Provider instance with write() method
+ * @param {object} spec.config - Provider configuration
+ * @param {object} spec.payload - Write payload (e.g. { type: 'issue', title, body, ... })
+ * @param {string} [spec.idempotencyKey] - Explicit idempotency key (auto-generated if absent)
+ * @param {boolean} [spec.dryRun] - If true, return rendered payload without executing
+ * @param {object} [spec.broker] - Broker instance for policy gating
+ * @param {ApprovalQueue} [spec.approvalQueue] - For durable approval
+ * @param {WriteSentLog} [spec.sentLog] - For idempotency tracking
+ * @param {object} [spec.requestedBy] - Actor identity { userId, serviceId, role }
+ * @param {object} [spec.traceInfo] - { traceId, spanId } for observability
+ * @param {number} [spec.maxRetries] - Max retry attempts on rate-limit (default 3)
+ * @returns {object} { status: 'sent'|'awaiting_approval'|'denied'|'error'|'cached', envelope: {...} }
+ */
+export async function writeWithEnvelope(spec) {
+  const {
+    provider, config, payload,
+    idempotencyKey: explicitKey,
+    dryRun = false,
+    broker, approvalQueue, sentLog,
+    requestedBy = {},
+    traceInfo = {},
+    maxRetries = 3,
+  } = spec;
+
+  const payloadStable = JSON.stringify(payload, Object.keys(payload).sort());
+  const idempotencyKey = explicitKey || crypto
+    .createHash('sha256')
+    .update(`${provider.meta?.id || 'unknown'}:${payload.type || 'write'}:${payloadStable}`)
+    .digest('hex')
+    .slice(0, 24);
+
+  const writeType = payload.type || 'write';
+  const providerId = provider.meta?.id || spec.providerId || 'unknown';
+  const now = new Date().toISOString();
+
+  if (sentLog) {
+    const existing = sentLog.findByIdempotencyKey(idempotencyKey);
+    if (existing && existing.status === 'sent') {
+      return {
+        status: 'cached',
+        envelope: {
+          idempotencyKey,
+          sentAt: existing.sentAt,
+          provider: existing.provider || providerId,
+          writeType,
+          state: 'sent',
+          externalUrl: existing.externalUrl,
+          externalId: existing.externalId,
+          result: existing.result,
+        },
+      };
+    }
+  }
+
+  if (sentLog) {
+    sentLog.record({ idempotencyKey, writeType, provider: providerId, sentAt: now, status: 'pending' });
+  }
+
+  if (dryRun) {
+    return {
+      status: 'dry-run',
+      envelope: {
+        idempotencyKey,
+        sentAt: now,
+        provider: providerId,
+        writeType,
+        state: 'dry-run',
+        payload,
+      },
+    };
+  }
+
+  if (broker) {
+    try {
+      const policyResult = await broker.invoke({
+        role: requestedBy.role || 'member',
+        tool: `write:${providerId}:${writeType}`,
+        action: 'write',
+        toolArgs: payload,
+        risk: 'write',
+        requestedBy,
+        resumeToken: spec.resumeToken,
+        execute: async () => ({ ok: true, deferred: true }),
+      });
+
+      if (policyResult.status === 'awaiting_approval') {
+        if (sentLog) sentLog.record({
+          idempotencyKey, writeType, provider: providerId, sentAt: now,
+          status: 'awaiting_approval',
+          result: { approvalId: policyResult.approvalId },
+        });
+        return {
+          status: 'awaiting_approval',
+          envelope: {
+            idempotencyKey,
+            approvalId: policyResult.approvalId,
+            resumeToken: policyResult.resumeToken,
+            expiresAt: policyResult.expiresAt,
+          },
+        };
+      }
+
+      if (policyResult.status === 'denied') {
+        if (sentLog) sentLog.record({
+          idempotencyKey, writeType, provider: providerId, sentAt: now,
+          status: 'denied',
+          error: policyResult.reason || 'denied by policy',
+        });
+        return {
+          status: 'denied',
+          envelope: { idempotencyKey, reason: policyResult.reason },
+        };
+      }
+    } catch (err) {
+      if (err.name === 'PolicyDenied') {
+        return { status: 'denied', envelope: { idempotencyKey, reason: err.message } };
+      }
+    }
+  }
+
+  let lastError = null;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const result = await provider.write(config, payload);
+      const externalUrl = result?.url || result?.externalUrl || null;
+      const externalId = result?.id || result?.key || result?.externalId || null;
+
+      if (sentLog) {
+        sentLog.record({
+          idempotencyKey, writeType, provider: providerId, sentAt: now,
+          completedAt: new Date().toISOString(),
+          status: 'sent',
+          externalUrl, externalId, result,
+        });
+      }
+
+      return {
+        status: 'sent',
+        envelope: {
+          idempotencyKey,
+          sentAt: now,
+          provider: providerId,
+          writeType,
+          state: 'sent',
+          externalUrl,
+          externalId,
+          result,
+        },
+      };
+    } catch (err) {
+      lastError = err;
+      const isRateLimit = err.message?.includes('rate') || err.status === 429;
+      if (!isRateLimit || attempt >= maxRetries) break;
+      await new Promise(r => setTimeout(r, Math.pow(2, attempt - 1) * 1000));
+    }
+  }
+
+  if (sentLog) {
+    sentLog.record({
+      idempotencyKey, writeType, provider: providerId, sentAt: now,
+      completedAt: new Date().toISOString(),
+      status: 'failed',
+      error: lastError?.message || String(lastError),
+    });
+  }
+
+  return {
+    status: 'error',
+    envelope: {
+      idempotencyKey,
+      sentAt: now,
+      provider: providerId,
+      writeType,
+      state: 'failed',
+      error: lastError?.message || String(lastError),
+    },
+  };
+}