@remogram/core 0.1.0-beta.1 → 0.1.0-beta.10

package/provider-health.js

@@ -0,0 +1,93 @@
+import { ERROR_CODES } from './contracts/errors.js';
+import { sanitizeField } from './caps.js';
+
+const LIVE_REACHABILITY_TIMEOUT_MS = 5000;
+
+export { LIVE_REACHABILITY_TIMEOUT_MS };
+
+export function classifyReachabilityFailure(err) {
+  const code = err?.forgeError?.code;
+  const status = err?.status ?? err?.forgeError?.status ?? null;
+  let causeCode = null;
+  for (let current = err; current; current = current.cause) {
+    if (current.code) {
+      causeCode = current.code;
+      break;
+    }
+  }
+  const message = String(err?.forgeError?.message ?? err?.message ?? '');
+
+  if (code === ERROR_CODES.UNAUTHENTICATED_PROVIDER) return 'auth_missing';
+  if (code === ERROR_CODES.OVERSIZED_RAW_OUTPUT) return 'oversized_raw_output';
+  if (status === 401 || /401/.test(message)) return 'http_401';
+  if (status === 404 || /not found/i.test(message)) return 'repo_not_found';
+  if (status >= 300 && status < 400) return 'redirect_rejected';
+  if (/redirect rejected/i.test(message)) return 'redirect_rejected';
+  if (causeCode === 'ECONNREFUSED') return 'connection_refused';
+  if (causeCode === 'ENOTFOUND' || causeCode === 'EAI_AGAIN') return 'network_unreachable';
+  if (causeCode === 'ECONNRESET' || causeCode === 'ENETUNREACH') return 'network_unreachable';
+  if (err?.name === 'TimeoutError' || causeCode === 'ETIMEDOUT' || /timed out/i.test(message)) {
+    return 'timeout';
+  }
+  return 'network_unreachable';
+}
+
+export function doctorReachabilityCheck(name, status, message, details = null) {
+  return {
+    name,
+    status,
+    message: sanitizeField(message),
+    ...(details ? { details } : {}),
+  };
+}
+
+/**
+ * @param {object} ctx
+ * @param {object | undefined} provider
+ * @param {{ live?: boolean, prerequisitesPass?: boolean }} [opts]
+ */
+export async function buildApiReachabilityCheck(ctx, provider, opts = {}) {
+  const { live = false, prerequisitesPass = false } = opts;
+  if (!live) {
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'skipped',
+      'Live API reachability is not checked by default',
+    );
+  }
+  if (!prerequisitesPass) {
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'fail',
+      'Live reachability requires valid config and trusted host binding',
+      { failure_kind: 'prerequisites_failed' },
+    );
+  }
+  if (typeof provider?.apiReachability !== 'function') {
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'warn',
+      'Provider does not implement live API reachability',
+      { failure_kind: 'not_implemented' },
+    );
+  }
+  try {
+    const facts = await provider.apiReachability(ctx);
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'pass',
+      'Forge API is reachable',
+      { repo_accessible: true, ...(facts && typeof facts === 'object' ? facts : {}) },
+    );
+  } catch (err) {
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'fail',
+      err.forgeError?.message || err.message || 'Forge API reachability check failed',
+      {
+        failure_kind: classifyReachabilityFailure(err),
+        ...(err.status != null ? { http_status: err.status } : {}),
+      },
+    );
+  }
+}

package/ref-inventory.js

@@ -0,0 +1,98 @@
+import { execFileSync } from 'node:child_process';
+import { sanitizeField } from './caps.js';
+import { gitAheadBehind, gitCurrentBranch, gitRevParse } from './git-local.js';
+
+const GIT_TIMEOUT_MS = 10_000;
+
+function gitExec(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
+}
+
+function listRefs(cwd) {
+  try {
+    const out = gitExec(cwd, [
+      'for-each-ref',
+      '--format=%(refname:short)|%(objectname)|%(refname)',
+      'refs/heads',
+      'refs/remotes',
+    ]);
+    if (!out) return [];
+    return out.split('\n').filter(Boolean).map((line) => {
+      const [name, sha, fullRef] = line.split('|');
+      const kind = fullRef.startsWith('refs/heads/') ? 'branch' : 'remote';
+      return { name, sha, kind };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function resolveDefaultRef(cwd, remoteName) {
+  try {
+    const sym = gitExec(cwd, ['symbolic-ref', `refs/remotes/${remoteName}/HEAD`]);
+    const prefix = `refs/remotes/${remoteName}/`;
+    if (sym.startsWith(prefix)) {
+      return sym.slice(prefix.length);
+    }
+    return sym.replace(/^refs\/remotes\/[^/]+\//, '');
+  } catch {
+    return null;
+  }
+}
+
+function buildAncestryHints(cwd, defaultRef, refs) {
+  if (!defaultRef) return [];
+  const defaultEntry = refs.find((r) => r.name === defaultRef || r.name === `origin/${defaultRef}`);
+  const headBranch = gitCurrentBranch(cwd);
+  if (!headBranch || headBranch === 'HEAD') return [];
+  const headEntry = refs.find((r) => r.name === headBranch);
+  if (!defaultEntry?.sha || !headEntry?.sha || defaultEntry.sha === headEntry.sha) return [];
+
+  const counts = gitAheadBehind(cwd, defaultEntry.sha, headEntry.sha);
+  if (counts.ahead_by == null && counts.behind_by == null) return [];
+
+  return [
+    {
+      compare_base_ref: sanitizeField(defaultRef),
+      compare_head_ref: sanitizeField(headBranch),
+      ahead_by: counts.ahead_by,
+      behind_by: counts.behind_by,
+    },
+  ];
+}
+
+/**
+ * Build provider-neutral ref inventory body from local git.
+ * @param {string} cwd repository working directory (git root after config load)
+ * @param {string} [remoteName]
+ */
+export function buildRefInventoryBody(cwd, remoteName = 'origin') {
+  const refs = listRefs(cwd).map((ref) => ({
+    name: sanitizeField(ref.name),
+    sha: ref.sha,
+    kind: ref.kind,
+    is_default: false,
+  }));
+
+  const defaultRef = resolveDefaultRef(cwd, remoteName);
+  if (defaultRef) {
+    for (const ref of refs) {
+      if (ref.name === defaultRef || ref.name === `${remoteName}/${defaultRef}`) {
+        ref.is_default = true;
+      }
+    }
+  }
+
+  const ancestry_hints = buildAncestryHints(cwd, defaultRef, refs);
+
+  return {
+    refs,
+    ...(defaultRef ? { default_ref: sanitizeField(defaultRef) } : {}),
+    ...(ancestry_hints.length > 0 ? { ancestry_hints } : {}),
+  };
+}
+
+export async function refsInventory(ctx) {
+  const remoteName = ctx.config.remote || 'origin';
+  return buildRefInventoryBody(ctx.cwd, remoteName);
+}

package/resolve.js

@@ -1,20 +1,40 @@
 import { execFileSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { parseConfigFile } from './config-schema.js';
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { normalizedForgeOrigin } from './forge-identity.js';
+import { resolveMergePolicy } from './merge-policy.js';
+import { loadOperatorConfig } from './operator-config.js';
+import { resolveEffectiveWritePolicy } from './effective-write-policy.js';
+import { resolveEffectiveWriteFieldPolicy } from './write-field-policy.js';
 import { assertGitRemote } from './git-args.js';
+import { gitRepoRoot } from './git-local.js';
 
 const HOST_ALIASES = new Map([
   ['localhost:3000', '127.0.0.1:3000'],
   ['127.0.0.1:3000', 'localhost:3000'],
 ]);
 
+function samePath(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return resolve(a) === resolve(b);
+  }
+}
+
 export function findConfigPath(startDir = process.cwd()) {
+  const repoRoot = gitRepoRoot(startDir);
   let dir = startDir;
   while (true) {
     const candidate = join(dir, '.remogram.json');
     if (existsSync(candidate)) return candidate;
+    if (repoRoot) {
+      if (samePath(dir, repoRoot)) break;
+    } else {
+      break;
+    }
     const parent = dirname(dir);
     if (parent === dir) break;
     dir = parent;
@@ -124,14 +144,43 @@ export function assertForgeReady(loaded) {
   return { ...loaded, remoteUrl, parsed };
 }
 
-export function forgeContext(loaded) {
+export function forgeContext(loaded, options = {}) {
   const { config, parsed } = loaded;
-  return {
+  const baseCtx = {
     providerId: config.provider,
     remoteName: config.remote,
     repoId: `${parsed.owner}/${parsed.repo}`,
+    baseUrl: normalizedForgeOrigin(config),
     config,
     cwd: loaded.cwd,
     parsed,
+    mergePolicy: resolveMergePolicy(config),
+  };
+
+  const operatorLoad = loadOperatorConfig({
+    cliPath: options.operatorConfigPath ?? null,
+    forgeContext: baseCtx,
+  });
+  const writePolicy = resolveEffectiveWritePolicy(config, operatorLoad);
+  const writeFieldPolicy = resolveEffectiveWriteFieldPolicy(config, operatorLoad);
+
+  return {
+    ...baseCtx,
+    writePolicy,
+    writeFieldPolicy,
+    operatorConfigMeta: operatorLoad.meta,
   };
 }
+
+export function resolveWritePolicyForForge(forgeCtx, options = {}) {
+  const operatorLoad = loadOperatorConfig({
+    cliPath: options.operatorConfigPath ?? null,
+    forgeContext: forgeCtx,
+  });
+  return resolveEffectiveWritePolicy(forgeCtx.config, operatorLoad);
+}
+
+export function prepareForgeContext(cwd = process.cwd(), options = {}) {
+  const loaded = assertForgeReady(loadConfig(cwd));
+  return forgeContext(loaded, options);
+}

package/status-set.js

@@ -0,0 +1,92 @@
+import { sanitizeReadField, sanitizeWriteBody, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Supported commit status states (Gitea/GitHub parity). */
+export const STATUS_SET_STATES = Object.freeze(['pending', 'success', 'failure', 'error']);
+
+const STATUS_SET_STATE_SET = new Set(STATUS_SET_STATES);
+
+const FULL_SHA_RE = /^[0-9a-fA-F]{40}$/;
+
+export function assertCommitSha(sha, label = 'sha') {
+  const value = String(sha ?? '').trim();
+  if (!FULL_SHA_RE.test(value)) {
+    throw Object.assign(new Error(`Invalid ${label}`), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        `${label} must be a 40-character hexadecimal commit SHA`,
+      ),
+    });
+  }
+  return value.toLowerCase();
+}
+
+export function normalizeStatusSetState(state) {
+  const normalized = String(state ?? '').toLowerCase();
+  if (STATUS_SET_STATE_SET.has(normalized)) return normalized;
+  if (normalized === 'pass') return 'success';
+  if (normalized === 'fail') return 'failure';
+  throw Object.assign(new Error('Invalid status state'), {
+    forgeError: forgeError(
+      ERROR_CODES.INVALID_ARGS,
+      `state must be one of: ${STATUS_SET_STATES.join(', ')}`,
+    ),
+  });
+}
+
+export function parseStatusSetArgs({ sha, context, state, target_url, description }, writeFieldPolicy = null) {
+  const parsedSha = assertCommitSha(sha, '--sha');
+  if (context == null || String(context).trim() === '') {
+    throw Object.assign(new Error('--context required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--context required for status set'),
+    });
+  }
+  if (state == null || String(state).trim() === '') {
+    throw Object.assign(new Error('--state required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--state required for status set'),
+    });
+  }
+  const parsed = {
+    sha: parsedSha,
+    context: sanitizeReadField(String(context)),
+    state: normalizeStatusSetState(state),
+  };
+  if (target_url != null && String(target_url).trim() !== '') {
+    parsed.target_url = sanitizeUrl(String(target_url));
+  }
+  if (description != null && String(description).trim() !== '') {
+    parsed.description = sanitizeWriteBody(String(description), writeFieldPolicy);
+  }
+  return parsed;
+}
+
+/** Normalize forge commit status POST/GET response into commit_status_set body fields. */
+export function buildCommitStatusSetBody(
+  response,
+  args,
+  { reusedExisting = false, idempotencyFields = null } = {},
+) {
+  const state = normalizeStatusSetState(response?.status ?? response?.state ?? args.state);
+  const body = {
+    sha: args.sha,
+    context: sanitizeReadField(args.context),
+    state,
+  };
+  const description = response?.description ?? args.description;
+  if (description != null && String(description).trim() !== '') {
+    body.description = sanitizeReadField(String(description));
+  }
+  const targetUrl = response?.target_url ?? args.target_url;
+  if (targetUrl != null && String(targetUrl).trim() !== '') {
+    body.target_url = sanitizeUrl(String(targetUrl));
+  }
+  if (reusedExisting) {
+    body.reused_existing = true;
+  } else {
+    body.created = true;
+  }
+  if (idempotencyFields && typeof idempotencyFields === 'object') {
+    Object.assign(body, idempotencyFields);
+  }
+  return body;
+}

package/stub-provider.js

@@ -1,4 +1,5 @@
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { stubProviderCommands } from './auth-classes.js';
 
 export function createStubProvider(id) {
   function unsupported() {
@@ -8,14 +9,7 @@ export function createStubProvider(id) {
   }
   function providerCapabilities() {
     return {
-      commands: [
-        { name: 'repo_status', implemented: false },
-        { name: 'ref_compare', implemented: false },
-        { name: 'pr_status', implemented: false },
-        { name: 'pr_checks', implemented: false },
-        { name: 'merge_plan', implemented: false },
-        { name: 'sync_plan', implemented: false },
-      ],
+      commands: stubProviderCommands(),
       auth_envs: [],
       check_sources: [],
       mergeability_confidence: 'unknown',
@@ -29,9 +23,18 @@ export function createStubProvider(id) {
     providerCapabilities,
     repoStatus: unsupported,
     refsCompare: unsupported,
+    refsInventory: unsupported,
+    crInventory: unsupported,
     prView: unsupported,
     prChecks: unsupported,
     mergePlan: unsupported,
     syncPlan: unsupported,
+    whoami: unsupported,
+    branchProtection: unsupported,
+    crFiles: unsupported,
+    crComments: unsupported,
+    forgeChanges: unsupported,
+    crOpen: unsupported,
+    statusSet: unsupported,
   };
 }

package/whoami.js

@@ -0,0 +1,114 @@
+import { sanitizeField } from './caps.js';
+
+/** Gitea does not expose OAuth scope or token expiry on GET /user. */
+export function unimplementedTokenScopeSignal() {
+  return { implemented: false, scopes: null };
+}
+
+export function unimplementedTokenExpirySignal() {
+  return { implemented: false, expires_at: null };
+}
+
+/** Restricted Gitea users are read-only; others may write per forge policy. */
+export function normalizeGiteaCanWrite(user) {
+  if (user == null || typeof user !== 'object') return false;
+  if (user.restricted === true) return false;
+  return true;
+}
+
+export function buildProviderIdentityBody({
+  login,
+  can_write,
+  token_scope_signal,
+  token_expiry_signal,
+}) {
+  return {
+    login: sanitizeField(login),
+    can_write: Boolean(can_write),
+    token_scope_signal,
+    token_expiry_signal,
+  };
+}
+
+export function buildProviderIdentityFromGiteaUser(user) {
+  return buildProviderIdentityBody({
+    login: user?.login ?? '',
+    can_write: normalizeGiteaCanWrite(user),
+    token_scope_signal: unimplementedTokenScopeSignal(),
+    token_expiry_signal: unimplementedTokenExpirySignal(),
+  });
+}
+
+export function parseGitHubOAuthScopes(headerValue) {
+  if (headerValue == null || String(headerValue).trim() === '') {
+    return unimplementedTokenScopeSignal();
+  }
+  const scopes = String(headerValue)
+    .split(',')
+    .map((scope) => sanitizeField(scope.trim()))
+    .filter(Boolean);
+  if (scopes.length === 0) {
+    return unimplementedTokenScopeSignal();
+  }
+  return { implemented: true, scopes };
+}
+
+export function githubCanWriteFromScopes(tokenScopeSignal) {
+  if (!tokenScopeSignal?.implemented || !Array.isArray(tokenScopeSignal.scopes)) {
+    return false;
+  }
+  return tokenScopeSignal.scopes.some(
+    (scope) => scope === 'repo' || scope === 'public_repo' || scope.startsWith('repo:'),
+  );
+}
+
+export function buildProviderIdentityFromGitHubUser(user, oauthScopesHeader) {
+  const token_scope_signal = parseGitHubOAuthScopes(oauthScopesHeader);
+  return buildProviderIdentityBody({
+    login: user?.login ?? '',
+    can_write: githubCanWriteFromScopes(token_scope_signal),
+    token_scope_signal,
+    token_expiry_signal: unimplementedTokenExpirySignal(),
+  });
+}
+
+export function normalizeGitLabCanWrite(user) {
+  if (user == null || typeof user !== 'object') return false;
+  if (user.state != null && user.state !== 'active') return false;
+  if (user.can_create_project === false) return false;
+  return true;
+}
+
+export function parseGitLabPatSelfSignals(patSelf) {
+  if (patSelf == null || typeof patSelf !== 'object') {
+    return {
+      token_scope_signal: unimplementedTokenScopeSignal(),
+      token_expiry_signal: unimplementedTokenExpirySignal(),
+    };
+  }
+  let token_scope_signal = unimplementedTokenScopeSignal();
+  if (Array.isArray(patSelf.scopes)) {
+    const scopes = patSelf.scopes.map((scope) => sanitizeField(String(scope))).filter(Boolean);
+    if (scopes.length > 0) {
+      token_scope_signal = { implemented: true, scopes };
+    }
+  }
+  const token_expiry_signal =
+    'expires_at' in patSelf
+      ? {
+          implemented: true,
+          expires_at: patSelf.expires_at == null ? null : sanitizeField(String(patSelf.expires_at)),
+        }
+      : unimplementedTokenExpirySignal();
+  return { token_scope_signal, token_expiry_signal };
+}
+
+export function buildProviderIdentityFromGitLabUser(user, patSelf) {
+  const { token_scope_signal, token_expiry_signal } = parseGitLabPatSelfSignals(patSelf);
+  return buildProviderIdentityBody({
+    login: user?.username ?? user?.login ?? '',
+    can_write: normalizeGitLabCanWrite(user),
+    token_scope_signal,
+    token_expiry_signal,
+  });
+}

package/write-config.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import {
+  isWriteCommandAllowed,
+  normalizeWritePolicyInput,
+  buildOperatorConfigSnippet,
+  buildRepoConfigSnippet,
+} from './effective-write-policy.js';
+
+/** Canonical v1 consumer write command ids (schema + gate single source). */
+export const WRITE_COMMAND_IDS = Object.freeze(['cr_open', 'status_set', 'merge', 'issue_open']);
+
+export const writeCommandSchema = z.enum(WRITE_COMMAND_IDS);
+
+/** @deprecated use WRITE_COMMAND_IDS */
+export const CONFIGURED_WRITE_COMMANDS = WRITE_COMMAND_IDS;
+
+export function isWriteCommandConfigured(configOrPolicy, commandName) {
+  if (!writeCommandSchema.safeParse(commandName).success) return false;
+  const policy = normalizeWritePolicyInput(configOrPolicy);
+  return isWriteCommandAllowed(policy, commandName);
+}
+
+/** Consumer-facing message when a write command is not opted in. */
+export function writeNotConfiguredMessage(commandName) {
+  return (
+    `Command "${commandName}" is not in effective write_commands; add it to .remogram.json `
+    + 'or a bound operator config (REMOGRAM_OPERATOR_CONFIG / --operator-config) '
+    + 'for Remogram CLI/MCP writes, or use your forge/CI tooling outside Remogram '
+    + '(read commands still work)'
+  );
+}
+
+export function assertWriteCommandConfigured(configOrPolicy, commandName) {
+  if (!writeCommandSchema.safeParse(commandName).success) {
+    throw Object.assign(new Error(`Unknown write command: ${commandName}`), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        `Unknown write command "${commandName}"; supported: ${WRITE_COMMAND_IDS.join(', ')}`,
+      ),
+    });
+  }
+  const policy = normalizeWritePolicyInput(configOrPolicy);
+  if (policy.operatorError) {
+    const err = policy.operatorError;
+    const message =
+      err.fields?.reason === 'operator_bind_mismatch' && err.fields?.remediation
+        ? err.message
+        : err.message;
+    throw Object.assign(new Error(message), {
+      forgeError: err,
+    });
+  }
+  if (isWriteCommandAllowed(policy, commandName)) return;
+  throw Object.assign(new Error(`Write command not configured: ${commandName}`), {
+    forgeError: forgeError(
+      ERROR_CODES.WRITE_NOT_CONFIGURED,
+      writeNotConfiguredMessage(commandName),
+    ),
+  });
+}
+
+export { buildOperatorConfigSnippet, buildRepoConfigSnippet };

package/write-field-policy.js

@@ -0,0 +1,93 @@
+import { DEFAULT_FIELD_MAX_BYTES } from './caps.js';
+
+export const WRITE_FIELD_MAX_BYTES_ENV = 'REMOGRAM_WRITE_FIELD_MAX_BYTES';
+/** Upper bound for undocumented REMOGRAM_WRITE_FIELD_MAX_BYTES debug override. */
+export const MAX_WRITE_FIELD_ENV_BYTES = 65536;
+
+const forgeWritePolicySchemaValue = (value) => {
+  if (value == null || value === 'none') return null;
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) return Math.floor(value);
+  return undefined;
+};
+
+/**
+ * @param {object | null | undefined} policyBlock
+ * @returns {number | null | undefined} bytes cap, null = uncapped, undefined = unset
+ */
+export function parseForgeWritePolicyBlock(policyBlock) {
+  if (!policyBlock || typeof policyBlock !== 'object') return undefined;
+  return forgeWritePolicySchemaValue(policyBlock.field_max_bytes);
+}
+
+/**
+ * @param {object} repoConfig
+ * @param {{ config?: object | null }} operatorLoad
+ */
+export function resolveEffectiveWriteFieldPolicy(repoConfig, operatorLoad = {}) {
+  const repoCap = parseForgeWritePolicyBlock(repoConfig?.forge_write_policy);
+  const operatorCap =
+    operatorLoad.config != null
+      ? parseForgeWritePolicyBlock(operatorLoad.config.forge_write_policy)
+      : undefined;
+
+  const envFacts = getEffectiveWriteFieldMaxBytesFromEnv();
+  let fieldMaxBytes = DEFAULT_FIELD_MAX_BYTES;
+  let source = 'default';
+
+  if (repoCap !== undefined) {
+    fieldMaxBytes = repoCap;
+    source = 'repo';
+  }
+  if (operatorCap !== undefined) {
+    fieldMaxBytes = operatorCap;
+    source = 'operator';
+  }
+  if (envFacts.envOverride) {
+    fieldMaxBytes = envFacts.bytes;
+    source = 'env';
+  }
+
+  return {
+    fieldMaxBytes,
+    uncapped: fieldMaxBytes == null,
+    source,
+    readFieldMaxBytes: DEFAULT_FIELD_MAX_BYTES,
+    repoFieldMaxBytes: repoCap,
+    operatorFieldMaxBytes: operatorCap,
+    envOverride: envFacts.envOverride,
+    envClamped: envFacts.clamped ?? false,
+    envInvalid: envFacts.invalidEnv ?? false,
+  };
+}
+
+export function getEffectiveWriteFieldMaxBytesFromEnv() {
+  const raw = process.env[WRITE_FIELD_MAX_BYTES_ENV];
+  if (raw == null || raw === '') {
+    return { bytes: DEFAULT_FIELD_MAX_BYTES, envOverride: false };
+  }
+  if (raw === '0' || raw === 'none' || raw === 'null') {
+    return { bytes: null, envOverride: true };
+  }
+  const parsed = Number.parseInt(String(raw), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return { bytes: DEFAULT_FIELD_MAX_BYTES, envOverride: false, invalidEnv: true };
+  }
+  if (parsed > MAX_WRITE_FIELD_ENV_BYTES) {
+    return { bytes: MAX_WRITE_FIELD_ENV_BYTES, envOverride: true, clamped: true };
+  }
+  return { bytes: parsed, envOverride: true };
+}
+
+/** Facts for provider capabilities / doctor packets. */
+export function forgeWriteFieldCapabilityFacts(writeFieldPolicy) {
+  const policy = writeFieldPolicy ?? resolveEffectiveWriteFieldPolicy({}, {});
+  return {
+    read_field_max_bytes: policy.readFieldMaxBytes,
+    write_field_max_bytes: policy.uncapped ? null : policy.fieldMaxBytes,
+    write_field_uncapped: policy.uncapped,
+    write_field_policy_source: policy.source,
+    ...(policy.envOverride ? { write_field_env_override: true } : {}),
+    ...(policy.envClamped ? { write_field_cap_clamped: true } : {}),
+    ...(policy.envInvalid ? { write_field_env_invalid: true } : {}),
+  };
+}