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

package/index.js

@@ -1,19 +1,254 @@
 export { SCHEMA_VERSION, PACKET_TYPES, forgePacket, forgeErrorPacket, unknownForgeContext, FORBIDDEN_PACKET_KEYS } from './contracts/envelope.js';
+export {
+  V1_READ_PLAN_COMMANDS,
+  FACT_INVENTORY_PACKET_TYPES,
+  TRUSTED_ENVELOPE_FIELDS,
+  TRUSTED_NORMALIZED_BODY_FIELDS,
+  FORGE_SOURCED_STRING_LEAVES,
+  FACT_INVENTORY_BODY_SHAPES,
+  forgeFactInventoryPacket,
+} from './contracts/semantic-diff-facts.js';
+export {
+  OBSERVER_REMOGRAM_COMMANDS,
+  OBSERVER_FACT_INVENTORY_PACKETS,
+  observerProtoRemogramCommands,
+  semanticDiffFactCommands,
+  allObserverEligibleCommands,
+} from './contracts/observer-fact-inventory.js';
 export { ERROR_CODES, forgeError } from './contracts/errors.js';
+export {
+  FORGE_ERROR_FIELD_ALLOWLIST,
+  normalizeForgeErrorFields,
+} from './contracts/forge-error-fields.js';
 export {
   capText,
   sanitizeField,
+  sanitizeReadField,
+  sanitizeWriteBody,
+  sanitizeWriteTitle,
   sanitizeUrl,
   readStreamCapped,
   DEFAULT_MAX_BYTES,
   DEFAULT_FIELD_MAX_BYTES,
   FORGE_INGEST_MAX_BYTES_ENV,
+  MAX_FORGE_INGEST_ENV_BYTES,
+  DEFAULT_CHECK_STATUS_PAGE_SIZE,
+  MAX_CHECK_STATUS_PAGES,
+  DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
+  MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
   getEffectiveIngestMaxBytes,
   forgeIngestCapabilityFacts,
+  checkPaginationCapabilityFacts,
+  idempotencyScanCapabilityFacts,
+  statusSetIdempotencyScanCapabilityFacts,
+  openPullListCapabilityFacts,
 } from './caps.js';
-export { assertGitRef, assertGitRemote } from './git-args.js';
-export { gitRevParse, gitCurrentBranch, gitAheadBehind } from './git-local.js';
+export {
+  WRITE_FIELD_MAX_BYTES_ENV,
+  MAX_WRITE_FIELD_ENV_BYTES,
+  resolveEffectiveWriteFieldPolicy,
+  forgeWriteFieldCapabilityFacts,
+  getEffectiveWriteFieldMaxBytesFromEnv,
+  parseForgeWritePolicyBlock,
+} from './write-field-policy.js';
+export {
+  paginateCheckStatusPages,
+  paginateOffsetListPages,
+  fetchWithIngestPageBackoff,
+  fetchPageWithIngestBackoff,
+  withPerPageParam,
+  withLimitParam,
+} from './check-pagination.js';
+export { assertGitRef, assertGitRemote, assertCrOpenBranchRef } from './git-args.js';
+export { gitRevParse, gitCurrentBranch, gitAheadBehind, gitRepoRoot, gitDiffNameOnly } from './git-local.js';
+export { buildRefInventoryBody, refsInventory } from './ref-inventory.js';
+export { buildCrInventoryEntry, buildHeadReconcile, crInventory, DEFAULT_CR_INVENTORY_LIMIT, DEFAULT_CR_INVENTORY_SAFE_LIMIT, normalizeCrInventoryLimit } from './cr-inventory.js';
+export {
+  CR_INVENTORY_CURSOR_VERSION,
+  decodeCrInventoryCursor,
+  encodeCrInventoryCursor,
+} from './cr-inventory-cursor.js';
+export {
+  CR_INVENTORY_SLICE_SORTS,
+  DEFAULT_CR_INVENTORY_SLICE_SORT,
+  normalizeCrInventorySort,
+  parseTotalCountHeader,
+  isCrInventoryFastPathEligible,
+  forgeOrderAuthoritative,
+  validateFastPathPageLength,
+  isNumberSortFastPathEligible,
+  resolvePaginatedEntryCount,
+  resolveListTruncatedWithTrustedTotal,
+  isRecentCreatedFastPathEligible,
+  giteaRecentCreatedTailPage,
+  isNumberSortFullCollectRequired,
+  prepareGiteaOpenPullPageItems,
+  orderOpenPullNumbers,
+  buildOpenPullListMeta,
+  giteaOpenPullSortQuery,
+  gitlabOpenPullSortQuery,
+  githubOpenPullSortQuery,
+  appendSortQuery,
+} from './open-pull-list.js';
+export { buildChangeRequestOpenedBody } from './cr-open.js';
+export { buildIssueOpenedBody, parseIssueOpenArgs } from './issue-open.js';
+export {
+  assertExpectedSha,
+  mergeExecuteViewFacts,
+  mergeExecuteChecksFacts,
+  buildMergeExecuteBeforeFacts,
+  collectMergeExecuteBlockers,
+  buildCrMergeBlockedBody,
+  buildCrMergedBody,
+  buildMergeExecuteAfterFacts,
+  buildMergeExecuteMergeFacts,
+} from './change-request-merge-execute.js';
+export {
+  STATUS_SET_STATES,
+  assertCommitSha,
+  normalizeStatusSetState,
+  parseStatusSetArgs,
+  buildCommitStatusSetBody,
+} from './status-set.js';
+export {
+  buildProviderIdentityBody,
+  buildProviderIdentityFromGiteaUser,
+  parseGitHubOAuthScopes,
+  githubCanWriteFromScopes,
+  buildProviderIdentityFromGitHubUser,
+  normalizeGitLabCanWrite,
+  parseGitLabPatSelfSignals,
+  buildProviderIdentityFromGitLabUser,
+  normalizeGiteaCanWrite,
+  unimplementedTokenScopeSignal,
+  unimplementedTokenExpirySignal,
+} from './whoami.js';
+export {
+  buildBranchProtectionBody,
+  buildBranchProtectionFromGiteaProtection,
+  buildBranchProtectionFromGitHubProtection,
+  buildBranchProtectionFromGitLabProtection,
+  unimplementedApprovalsRequiredSignal,
+  MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
+  MAX_BRANCH_PROTECTION_RULES,
+} from './branch-protection.js';
+export {
+  enrichCheckStatus,
+  buildCheckDiagnostics,
+  buildPrChecksBody,
+} from './check-diagnostics.js';
+export {
+  buildCrFilesBody,
+  buildCrFilesFromGiteaFiles,
+  buildCrFilesFromGitLabChanges,
+  MAX_CR_FILES_PATHS,
+} from './cr-files.js';
+export {
+  buildCrCommentsBody,
+  buildCrCommentsFromGiteaComments,
+  buildCrCommentsFromGitLabDiscussions,
+  normalizeCrComment,
+  MAX_CR_COMMENTS,
+} from './cr-comments.js';
+export {
+  parseSinceObservedAt,
+  buildForgeChangesBody,
+  buildForgeChangesFromGiteaPulls,
+  buildChecksConclusionObservedEvent,
+  appendForgeChangeEvents,
+  MAX_FORGE_CHANGES_EVENTS,
+  FORGE_CHANGE_EVENT_KINDS,
+} from './forge-changes.js';
+export {
+  encodeForgeChangesCursor,
+  decodeForgeChangesCursor,
+  paginateForgeChangesBody,
+  FORGE_CHANGES_CURSOR_VERSION,
+  DEFAULT_FORGE_CHANGES_PAGE_SIZE,
+} from './forge-changes-cursor.js';
+export {
+  WRITE_COMMAND_IDS,
+  CONFIGURED_WRITE_COMMANDS,
+  writeCommandSchema,
+  assertWriteCommandConfigured,
+  writeNotConfiguredMessage,
+  isWriteCommandConfigured,
+  buildOperatorConfigSnippet,
+  buildRepoConfigSnippet,
+} from './write-config.js';
+export {
+  resolveEffectiveWritePolicy,
+  isWriteCommandAllowed,
+  normalizeWritePolicyInput,
+  writeSourceForCommand,
+} from './effective-write-policy.js';
+export {
+  REMOGRAM_OPERATOR_CONFIG_ENV,
+  MAX_OPERATOR_CONFIG_BYTES,
+  operatorConfigSchema,
+  defaultOperatorConfigPath,
+  discoverOperatorConfigPath,
+  parseOperatorConfigFile,
+  loadOperatorConfigFile,
+  assertOperatorBindMatches,
+  loadOperatorConfig,
+} from './operator-config.js';
+export {
+  buildWriteReadiness,
+  writeReadinessHasWarnings,
+} from './write-readiness.js';
+export {
+  buildApiReachabilityCheck,
+  classifyReachabilityFailure,
+  LIVE_REACHABILITY_TIMEOUT_MS,
+} from './provider-health.js';
+export {
+  bindIdempotencyScope,
+  idempotencyFingerprint,
+  idempotencyPacketFields,
+  normalizeIdempotencyKey,
+  resetIdempotencyScopeBindings,
+} from './idempotency.js';
+export {
+  resolveMergePolicy,
+  parseTruthyEnv,
+  mergePolicyAuditFacts,
+  ALLOW_MISSING_CHECKS_ENV,
+  ALLOW_PENDING_CHECKS_ENV,
+} from './merge-policy.js';
+export { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
+export {
+  applyForgePathScopeForMergePlan,
+  isCrFilesScopeComplete,
+  resolveMergePlanPathScope,
+  buildMergePlanBody,
+  buildMergePlanBodyFromFacts,
+  normalizeAllowedPaths,
+} from './merge-plan.js';
+export {
+  isMergePlanForgeScopeRethrowError,
+  MERGE_PLAN_FORGE_SCOPE_RETHROW_CODES,
+  resolveMergePlanOptsWithForgePaths,
+  buildMergePlanFromProviderFacts,
+} from './merge-plan-forge.js';
+export {
+  matchPathAllowlist,
+  isPathAllowed,
+  pathsOutsideAllowlist,
+  allPathsAllowed,
+  normalizeRepoRelativePath,
+  normalizeChangedPathList,
+} from './path-allowlist.js';
+export {
+  localHeadShaForPr,
+  staleHeadDetails,
+  staleHeadForgeError,
+  staleHeadForgeError as staleHeadError,
+  STALE_HEAD_MESSAGE,
+  throwIfStaleHeadByNumber,
+} from './pr-head-reconcile.js';
 export { parseConfigFile, configSchema } from './config-schema.js';
+export { normalizedForgeOrigin } from './forge-identity.js';
 export {
   findConfigPath,
   loadConfig,
@@ -23,5 +258,22 @@ export {
   assertConfigMatchesRemote,
   assertForgeReady,
   forgeContext,
+  resolveWritePolicyForForge,
+  prepareForgeContext,
 } from './resolve.js';
-export { fetchWithTimeout, fetchJson, fetchJsonWithMeta, parseLinkHeader, fetchTextCapped } from './http.js';
+export {
+  fetchWithTimeout,
+  fetchJson,
+  fetchJsonWithMeta,
+  parseLinkHeader,
+  isTrustedPaginationUrl,
+  fetchTextCapped,
+} from './http.js';
+export {
+  AUTH_CLASS,
+  API_PROVIDER_COMMAND_AUTH,
+  commandCapability,
+  apiProviderCommands,
+  stubProviderCommands,
+  assertAuthClass,
+} from './auth-classes.js';

package/issue-open.js

@@ -0,0 +1,50 @@
+import { sanitizeReadField, sanitizeWriteBody, sanitizeWriteTitle, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Normalize Gitea issue create response into issue_opened body fields. */
+export function buildIssueOpenedBody(
+  issue,
+  { title },
+  { reusedExisting = false, idempotencyFields = null } = {},
+) {
+  const issueNumber = Number(issue?.number);
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    throw Object.assign(new Error('Provider returned invalid issue number'), {
+      forgeError: forgeError(
+        ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT,
+        'Provider returned invalid issue number',
+      ),
+    });
+  }
+  const resolvedTitle = reusedExisting
+    ? sanitizeReadField(issue?.title ?? title)
+    : sanitizeReadField(title ?? issue?.title);
+  const body = {
+    issue_number: issueNumber,
+    url: sanitizeUrl(issue.html_url ?? issue.url),
+    state: sanitizeReadField(String(issue?.state ?? 'open').toLowerCase()),
+    title: resolvedTitle,
+  };
+  if (reusedExisting) {
+    body.reused_existing = true;
+  } else {
+    body.created = true;
+  }
+  if (idempotencyFields && typeof idempotencyFields === 'object') {
+    Object.assign(body, idempotencyFields);
+  }
+  return body;
+}
+
+export function parseIssueOpenArgs({ title, body: issueBody }, writeFieldPolicy = null) {
+  if (title == null || String(title).trim() === '') {
+    throw Object.assign(new Error('--title required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--title required for issue open'),
+    });
+  }
+  const parsed = { title: sanitizeWriteTitle(String(title), writeFieldPolicy) };
+  if (issueBody != null && String(issueBody).trim() !== '') {
+    parsed.body = sanitizeWriteBody(String(issueBody), writeFieldPolicy);
+  }
+  return parsed;
+}

package/merge-blockers.js

@@ -0,0 +1,68 @@
+import { allPathsAllowed, normalizeChangedPathList } from './path-allowlist.js';
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+function diagnosticBlockers(checks) {
+  const blockers = [];
+  const missing = checks.missing_required_contexts;
+  if (Array.isArray(missing) && missing.length > 0) blockers.push('required_checks_missing');
+  const stale = checks.stale_contexts;
+  if (Array.isArray(stale) && stale.length > 0) blockers.push('stale_status_context');
+  const required = new Set(
+    Array.isArray(checks.required_contexts) ? checks.required_contexts.filter(Boolean) : [],
+  );
+  if (required.size > 0 && Array.isArray(checks.pending_contexts)) {
+    const pendingRequired = checks.pending_contexts.filter((context) => required.has(context));
+    if (pendingRequired.length > 0) blockers.push('required_checks_pending');
+  }
+  return uniqueSorted(blockers);
+}
+
+/**
+ * Derive merge blockers from already-fetched PR view and checks facts.
+ * Shared by merge plan and cr inventory aggregation.
+ */
+export function isOpenPrState(state) {
+  return String(state ?? '').toLowerCase() === 'open';
+}
+
+/**
+ * @param {object} view
+ * @param {object} checks
+ * @param {{ allowed_paths?: string[], changed_paths?: string[] | null }} [pathScope]
+ */
+export function mergeBlockersFromFacts(view, checks, pathScope = {}, policy = {}) {
+  const blockers = [];
+  if (view.mergeability === 'conflicted') blockers.push('merge_conflict');
+  if (!isOpenPrState(view.state)) blockers.push('pr_not_open');
+  if (checks.checks_truncated === true) blockers.push('checks_incomplete');
+  if (checks.check_conclusion === 'failure') blockers.push('checks_failed');
+  if (checks.check_conclusion === 'missing' && !policy.allow_missing_checks) {
+    blockers.push('checks_missing');
+  }
+  if (checks.check_conclusion === 'pending' && !policy.allow_pending_checks) {
+    blockers.push('checks_pending');
+  }
+  blockers.push(...diagnosticBlockers(checks));
+
+  const allowedPaths = pathScope.allowed_paths;
+  if (Array.isArray(allowedPaths) && allowedPaths.length > 0) {
+    const changedPaths = pathScope.changed_paths;
+    if (changedPaths == null) {
+      blockers.push('changed_paths_unavailable');
+    } else if (Array.isArray(changedPaths)) {
+      const normalizedPaths = normalizeChangedPathList(changedPaths);
+      if (normalizedPaths == null) {
+        blockers.push('changed_paths_unavailable');
+      } else if (!allPathsAllowed(allowedPaths, normalizedPaths)) {
+        blockers.push('path_scope_violation');
+      }
+    } else {
+      blockers.push('changed_paths_unavailable');
+    }
+  }
+
+  return blockers;
+}

package/merge-plan-forge.js

@@ -0,0 +1,63 @@
+import { ERROR_CODES } from './contracts/errors.js';
+import {
+  applyForgePathScopeForMergePlan,
+  buildMergePlanBodyFromFacts,
+  normalizeAllowedPaths,
+} from './merge-plan.js';
+
+/** Errors that must propagate from crFiles during merge-plan path scope — not mapped to changed_paths_unavailable. */
+export const MERGE_PLAN_FORGE_SCOPE_RETHROW_CODES = new Set([
+  ERROR_CODES.UNAUTHENTICATED_PROVIDER,
+  ERROR_CODES.INVALID_ARGS,
+  ERROR_CODES.UNTRUSTED_BASE_URL,
+  ERROR_CODES.PROVIDER_UNSUPPORTED,
+  ERROR_CODES.CONFIG_INVALID,
+  ERROR_CODES.OVERSIZED_RAW_OUTPUT,
+  ERROR_CODES.CONFIG_NOT_FOUND,
+  ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT,
+  ERROR_CODES.STALE_HEAD,
+  ERROR_CODES.MISSING_REF,
+  ERROR_CODES.PR_NOT_OPEN,
+  ERROR_CODES.REMOTE_INFER_FAILED,
+]);
+
+export function isMergePlanForgeScopeRethrowError(err) {
+  const code = err?.forgeError?.code;
+  return typeof code === 'string' && MERGE_PLAN_FORGE_SCOPE_RETHROW_CODES.has(code);
+}
+
+export { normalizeAllowedPaths } from './merge-plan.js';
+
+/**
+ * Resolve merge plan opts with forge cr_files when an allowlist is configured.
+ * @param {object} opts
+ * @param {() => Promise<object>} crFilesFn
+ */
+export async function resolveMergePlanOptsWithForgePaths(opts, crFilesFn) {
+  if (!normalizeAllowedPaths(opts.allowed_paths)) return opts;
+  try {
+    const crFilesBody = await crFilesFn();
+    return applyForgePathScopeForMergePlan(opts, crFilesBody);
+  } catch (err) {
+    if (isMergePlanForgeScopeRethrowError(err)) throw err;
+    // Intentional mask bucket: transient api_error → changed_paths_unavailable.
+    // write_not_configured / idempotency codes are not emitted by crFiles today.
+    return applyForgePathScopeForMergePlan(opts, null);
+  }
+}
+
+/**
+ * Build merge_plan body from provider deps (shared tri-provider orchestration).
+ * @param {object} ctx
+ * @param {object} opts
+ * @param {{ prView: Function, prChecks: Function, crFiles: Function }} deps
+ */
+export async function buildMergePlanFromProviderFacts(ctx, opts, deps) {
+  const view = await deps.prView(ctx, opts);
+  const checks = await deps.prChecks(ctx, { number: view.pr_number });
+  const mergeOpts = await resolveMergePlanOptsWithForgePaths(opts, () =>
+    deps.crFiles(ctx, { number: view.pr_number }),
+  );
+  const mergePolicy = opts.merge_policy ?? ctx.mergePolicy ?? {};
+  return buildMergePlanBodyFromFacts(view, checks, { ...mergeOpts, merge_policy: mergePolicy });
+}

package/merge-plan.js

@@ -0,0 +1,82 @@
+import { mergeBlockersFromFacts } from './merge-blockers.js';
+import { normalizeChangedPathList } from './path-allowlist.js';
+
+function allowlistGlobHasDotDotSegment(glob) {
+  if (typeof glob !== 'string') return false;
+  const normalized = glob.replace(/\\/g, '/');
+  if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+    return true;
+  }
+  return normalized.split('/').some((segment) => segment === '..');
+}
+
+export function normalizeAllowedPaths(allowedPaths) {
+  if (!Array.isArray(allowedPaths)) return null;
+  const normalized = allowedPaths
+    .filter((entry) => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0 && !allowlistGlobHasDotDotSegment(entry));
+  return normalized.length > 0 ? normalized : null;
+}
+
+/** True when cr_files body is complete enough for merge-plan path scope. */
+export function isCrFilesScopeComplete(crFilesBody) {
+  if (!crFilesBody || crFilesBody.paths_truncated) return false;
+  const changedPaths = crFilesBody.changed_paths;
+  if (!Array.isArray(changedPaths)) return false;
+  const pathCount = Number.isFinite(Number(crFilesBody.path_count))
+    ? Math.floor(Number(crFilesBody.path_count))
+    : changedPaths.length;
+  if (pathCount > 0 && changedPaths.length === 0) return false;
+  if (pathCount > changedPaths.length) return false;
+  if (changedPaths.length > pathCount) return false;
+  return true;
+}
+
+/** Apply forge cr_files facts to merge plan opts when an allowlist is configured. */
+export function applyForgePathScopeForMergePlan(opts, crFilesBody) {
+  if (!normalizeAllowedPaths(opts.allowed_paths)) return opts;
+  if (!isCrFilesScopeComplete(crFilesBody)) {
+    return { ...opts, changed_paths: null };
+  }
+  const normalizedPaths = normalizeChangedPathList(crFilesBody.changed_paths);
+  if (normalizedPaths == null) {
+    return { ...opts, changed_paths: null };
+  }
+  return { ...opts, changed_paths: normalizedPaths };
+}
+
+export function resolveMergePlanPathScope(opts = {}) {
+  const allowedPaths = normalizeAllowedPaths(opts.allowed_paths);
+  if (!allowedPaths) {
+    return { allowed_paths: null, changed_paths: null };
+  }
+  if (Array.isArray(opts.changed_paths)) {
+    const normalizedPaths = normalizeChangedPathList(opts.changed_paths);
+    return {
+      allowed_paths: allowedPaths,
+      changed_paths: normalizedPaths,
+    };
+  }
+  return { allowed_paths: allowedPaths, changed_paths: null };
+}
+
+export function buildMergePlanBody(view, checks, pathScope = {}, policy = {}) {
+  return {
+    pr_number: view.pr_number,
+    mergeability: view.mergeability,
+    checks_conclusion: checks.check_conclusion,
+    required_contexts: checks.required_contexts ?? [],
+    missing_required_contexts: checks.missing_required_contexts ?? [],
+    failed_contexts: checks.failed_contexts ?? [],
+    pending_contexts: checks.pending_contexts ?? [],
+    stale_contexts: checks.stale_contexts ?? [],
+    blockers: mergeBlockersFromFacts(view, checks, pathScope, policy),
+  };
+}
+
+export function buildMergePlanBodyFromFacts(view, checks, opts = {}) {
+  const pathScope = resolveMergePlanPathScope(opts);
+  const policy = opts.merge_policy ?? {};
+  return buildMergePlanBody(view, checks, pathScope, policy);
+}

package/merge-policy.js

@@ -0,0 +1,55 @@
+export const ALLOW_MISSING_CHECKS_ENV = 'REMOGRAM_ALLOW_MISSING_CHECKS';
+export const ALLOW_PENDING_CHECKS_ENV = 'REMOGRAM_ALLOW_PENDING_CHECKS';
+
+/** @returns {boolean | null} true/false when recognized; null when unset/invalid */
+export function parseTruthyEnv(value) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return null;
+}
+
+function resolvePolicyFlag(configValue, envName) {
+  const envRaw = process.env[envName];
+  if (envRaw != null && envRaw !== '') {
+    const parsed = parseTruthyEnv(envRaw);
+    if (parsed === true) {
+      return { value: true, source: 'env' };
+    }
+  }
+  if (configValue === true) {
+    return { value: true, source: 'config' };
+  }
+  return { value: false, source: 'default' };
+}
+
+/**
+ * Resolved merge policy for blocker derivation (forge-facts layer only).
+ * @param {object | null | undefined} config consumer .remogram.json
+ */
+export function resolveMergePolicy(config) {
+  const filePolicy = config?.merge_policy ?? {};
+  const missing = resolvePolicyFlag(filePolicy.allow_missing_checks, ALLOW_MISSING_CHECKS_ENV);
+  const pending = resolvePolicyFlag(filePolicy.allow_pending_checks, ALLOW_PENDING_CHECKS_ENV);
+  return {
+    allow_missing_checks: missing.value,
+    allow_pending_checks: pending.value,
+    source: {
+      allow_missing_checks: missing.source,
+      allow_pending_checks: pending.source,
+    },
+  };
+}
+
+/** Observational snapshot for merge execute before facts. */
+export function mergePolicyAuditFacts(mergePolicy) {
+  if (!mergePolicy) return null;
+  return {
+    allow_missing_checks: mergePolicy.allow_missing_checks === true,
+    allow_pending_checks: mergePolicy.allow_pending_checks === true,
+    source: mergePolicy.source ?? {
+      allow_missing_checks: 'default',
+      allow_pending_checks: 'default',
+    },
+  };
+}