@remogram/core 0.1.0-beta.8 → 0.1.0-beta.9

package/auth-classes.js

@@ -18,6 +18,7 @@ export const API_PROVIDER_COMMAND_AUTH = {
   merge_plan: AUTH_CLASS.TOKEN_REQUIRED,
   sync_plan: AUTH_CLASS.GIT_ONLY,
   cr_open: AUTH_CLASS.TOKEN_REQUIRED,
+  issue_open: AUTH_CLASS.TOKEN_REQUIRED,
   status_set: AUTH_CLASS.TOKEN_REQUIRED,
   whoami: AUTH_CLASS.TOKEN_REQUIRED,
   branch_protection: AUTH_CLASS.TOKEN_REQUIRED,
@@ -37,6 +38,7 @@ export function commandCapability(name, { implemented = true } = {}) {
 
 export function apiProviderCommands({
   writeCommandsImplemented = false,
+  issueOpenImplemented = false,
   statusSetImplemented = false,
   branchProtectionImplemented = false,
   crFilesImplemented = false,
@@ -47,6 +49,7 @@ export function apiProviderCommands({
   return Object.keys(API_PROVIDER_COMMAND_AUTH).map((name) => {
     let implemented = true;
     if (name === 'cr_open') implemented = writeCommandsImplemented;
+    if (name === 'issue_open') implemented = issueOpenImplemented;
     if (name === 'status_set') implemented = statusSetImplemented;
     if (name === 'branch_protection') implemented = branchProtectionImplemented;
     if (name === 'cr_files') implemented = crFilesImplemented;

package/change-request-merge-execute.js

@@ -1,5 +1,6 @@
 import { sanitizeField } from './caps.js';
 import { mergeBlockersFromFacts } from './merge-blockers.js';
+import { mergePolicyAuditFacts } from './merge-policy.js';
 
 const SHA40 = /^[0-9a-f]{40}$/i;
 
@@ -27,9 +28,16 @@ export function assertExpectedSha(value, flagName) {
   return normalized;
 }
 
-export function buildMergeExecuteBeforeFacts(view, checks, mergePlanBody, forgeHeadRefSha = null) {
+export function buildMergeExecuteBeforeFacts(
+  view,
+  checks,
+  mergePlanBody,
+  forgeHeadRefSha = null,
+  mergePolicy = null,
+) {
   const viewFacts = mergeExecuteViewFacts(view);
   const checksFacts = mergeExecuteChecksFacts(checks);
+  const audit = mergePolicyAuditFacts(mergePolicy);
   return {
     base_sha: viewFacts.targetSha ?? null,
     head_sha: viewFacts.sourceSha ?? null,
@@ -39,6 +47,7 @@ export function buildMergeExecuteBeforeFacts(view, checks, mergePlanBody, forgeH
     checks_conclusion: checks.check_conclusion ?? 'unknown',
     checks_truncated: checks.checks_truncated === true,
     merge_plan_blockers: Array.isArray(mergePlanBody.blockers) ? [...mergePlanBody.blockers] : [],
+    ...(audit ? { merge_policy: audit } : {}),
   };
 }
 
@@ -51,7 +60,7 @@ export function collectMergeExecuteBlockers(
   checks,
   mergePlanBody,
   expected,
-  { forgeHeadRefSha } = {},
+  { forgeHeadRefSha, mergePolicy = {} } = {},
 ) {
   const viewFacts = mergeExecuteViewFacts(view);
   const checksFacts = mergeExecuteChecksFacts(checks);
@@ -69,7 +78,7 @@ export function collectMergeExecuteBlockers(
   if (checksHead && forgeHead && checksHead !== forgeHead) blockers.push('checks_forge_head_mismatch');
   if (forgeHead && forgeHead !== expected.headSha) blockers.push('head_ref_moved');
 
-  const planBlockers = mergeBlockersFromFacts(view, checks, {});
+  const planBlockers = mergeBlockersFromFacts(view, checks, {}, mergePolicy);
   for (const blocker of planBlockers) {
     if (!blockers.includes(blocker)) blockers.push(blocker);
   }

package/check-diagnostics.js

@@ -0,0 +1,92 @@
+import { sanitizeField } from './caps.js';
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * @param {object} entry
+ * @param {{ headSha?: string | null, requiredContexts?: Set<string> }} opts
+ */
+export function enrichCheckStatus(entry, opts = {}) {
+  const headSha = opts.headSha ?? null;
+  const context = sanitizeField(entry?.context);
+  const rawSha = entry?.sha != null ? sanitizeField(entry.sha) : headSha;
+  const sha = rawSha || null;
+  const stale = Boolean(headSha && sha && sha !== headSha);
+  const required = context ? opts.requiredContexts?.has(context) === true : false;
+  return {
+    context,
+    state: entry?.state ?? 'unknown',
+    ...(sha ? { sha } : {}),
+    required,
+    source: sanitizeField(entry?.source) || 'commit_status',
+    ...(entry?.target_url ? { target_url: sanitizeField(entry.target_url) } : {}),
+    ...(entry?.description ? { description: sanitizeField(entry.description) } : {}),
+    ...(stale ? { stale: true } : {}),
+  };
+}
+
+/**
+ * @param {object[]} statuses
+ * @param {{ headSha?: string | null, requiredContexts?: string[] }} opts
+ */
+export function buildCheckDiagnostics(statuses, opts = {}) {
+  const headSha = opts.headSha ?? null;
+  const requiredContexts = uniqueSorted(
+    Array.isArray(opts.requiredContexts) ? opts.requiredContexts.map((c) => sanitizeField(c)) : [],
+  );
+  const requiredSet = new Set(requiredContexts);
+  const enriched = (Array.isArray(statuses) ? statuses : []).map((entry) =>
+    enrichCheckStatus(entry, { headSha, requiredContexts: requiredSet }),
+  );
+  const byContext = new Map();
+  for (const status of enriched) {
+    if (status.context) byContext.set(status.context, status);
+  }
+
+  const failed_contexts = [];
+  const pending_contexts = [];
+  const stale_contexts = [];
+  for (const status of enriched) {
+    if (!status.context) continue;
+    if (status.stale === true) stale_contexts.push(status.context);
+    if (status.state === 'failure') failed_contexts.push(status.context);
+    if (status.state === 'pending') pending_contexts.push(status.context);
+  }
+
+  const missing_required_contexts = [];
+  for (const context of requiredContexts) {
+    if (!byContext.has(context)) missing_required_contexts.push(context);
+  }
+
+  return {
+    statuses: enriched,
+    required_contexts: requiredContexts,
+    missing_required_contexts: uniqueSorted(missing_required_contexts),
+    failed_contexts: uniqueSorted(failed_contexts),
+    pending_contexts: uniqueSorted(pending_contexts),
+    stale_contexts: uniqueSorted(stale_contexts),
+  };
+}
+
+/**
+ * @param {{ forge_source_sha: string, check_conclusion: string, checks_truncated?: boolean, statuses?: object[], required_contexts?: string[] }} body
+ */
+export function buildPrChecksBody(body) {
+  const diagnostics = buildCheckDiagnostics(body.statuses ?? [], {
+    headSha: body.forge_source_sha,
+    requiredContexts: body.required_contexts ?? [],
+  });
+  return {
+    forge_source_sha: body.forge_source_sha,
+    check_conclusion: body.check_conclusion,
+    checks_truncated: body.checks_truncated === true,
+    statuses: diagnostics.statuses,
+    required_contexts: diagnostics.required_contexts,
+    missing_required_contexts: diagnostics.missing_required_contexts,
+    failed_contexts: diagnostics.failed_contexts,
+    pending_contexts: diagnostics.pending_contexts,
+    stale_contexts: diagnostics.stale_contexts,
+  };
+}

package/check-pagination.js

@@ -189,6 +189,7 @@ export async function paginateOffsetListPages({
       };
     }
     page = 2;
+    activeLimit = pageSize;
   }
 
   for (; page <= maxPages; page += 1) {

package/config-schema.js

@@ -25,6 +25,12 @@ export const configSchema = z
     repo: repoSegmentSchema,
     baseUrl: z.string().url().optional(),
     write_commands: z.array(writeCommandSchema).optional(),
+    merge_policy: z
+      .object({
+        allow_missing_checks: z.boolean().optional(),
+        allow_pending_checks: z.boolean().optional(),
+      })
+      .optional(),
   })
   .strict();
 

package/contracts/envelope.js

@@ -14,6 +14,7 @@ export const PACKET_TYPES = {
   PROVIDER_DOCTOR: 'provider_doctor',
   FORGE_ERROR: 'forge_error',
   CHANGE_REQUEST_OPENED: 'change_request_opened',
+  ISSUE_OPENED: 'issue_opened',
   COMMIT_STATUS_SET: 'commit_status_set',
   PROVIDER_IDENTITY: 'provider_identity',
   BRANCH_PROTECTION: 'branch_protection',

package/contracts/errors.js

@@ -15,6 +15,7 @@ export const ERROR_CODES = {
   REMOTE_INFER_FAILED: 'remote_infer_failed',
   WRITE_NOT_CONFIGURED: 'write_not_configured',
   IDEMPOTENCY_SCAN_INCOMPLETE: 'idempotency_scan_incomplete',
+  IDEMPOTENCY_CONFLICT: 'idempotency_conflict',
   INVENTORY_LIST_INCOMPLETE: 'inventory_list_incomplete',
   MERGE_BLOCKED: 'merge_blocked',
   MERGE_ENDPOINT_FAILED: 'merge_endpoint_failed',

package/contracts/semantic-diff-facts.js

@@ -28,7 +28,7 @@ export const V1_READ_PLAN_COMMANDS = Object.freeze([
 ]);
 
 /** v1 write surface (Gitea cr open and status set in first slices). */
-export const V1_WRITE_COMMANDS = Object.freeze(['cr open', 'status set', 'merge execute']);
+export const V1_WRITE_COMMANDS = Object.freeze(['cr open', 'status set', 'merge execute', 'issue open']);
 
 /**
  * Planned fact-inventory packet types (not emitted until wave 2+ commands ship).
@@ -75,6 +75,9 @@ export const TRUSTED_NORMALIZED_BODY_FIELDS = Object.freeze({
   auth_present: true,
   can_write: true,
   reused_existing: true,
+  created: true,
+  idempotency_fingerprint: true,
+  ambiguous_after_write: true,
   idempotency_scan: true,
 });
 
@@ -135,6 +138,14 @@ export const FACT_INVENTORY_BODY_SHAPES = Object.freeze({
     /** true when list cap applied (entry_count > limit), not missing entries */
     truncated: 'boolean',
     list_truncated: 'boolean',
+    /** true when more pages remain via next_cursor */
+    has_more: 'boolean',
+    /** true when open-list enumeration is complete for slice_sort */
+    complete: 'boolean',
+    /** opaque cursor for the next page when has_more is true */
+    next_cursor: 'string optional',
+    /** numbers consumed from open-list ordering including skipped entries */
+    entry_count_observed: 'number',
     /** normalized slice sort preset applied to open-list resolution */
     slice_sort: 'string',
     entries_skipped:

package/cr-inventory-cursor.js

@@ -0,0 +1,64 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { normalizeCrInventorySort } from './open-pull-list.js';
+
+export const CR_INVENTORY_CURSOR_VERSION = 1;
+
+/**
+ * @param {{ sort: string, offset: number }} state
+ * @returns {string}
+ */
+export function encodeCrInventoryCursor(state) {
+  const sort = normalizeCrInventorySort(state.sort);
+  const offset = Number(state.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, 'cursor offset must be a non-negative integer'),
+    });
+  }
+  const payload = JSON.stringify({ v: CR_INVENTORY_CURSOR_VERSION, sort, offset });
+  return Buffer.from(payload, 'utf8').toString('base64url');
+}
+
+/**
+ * @param {unknown} raw
+ * @param {{ sort?: string | null }} [opts]
+ * @returns {{ sort: string, offset: number }}
+ */
+export function decodeCrInventoryCursor(raw, opts = {}) {
+  if (raw == null || raw === '') {
+    throw Object.assign(new Error('Missing cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor must not be empty when provided'),
+    });
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
+  } catch {
+    throw Object.assign(new Error('Invalid cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor is malformed or not base64url JSON'),
+    });
+  }
+  if (decoded?.v !== CR_INVENTORY_CURSOR_VERSION) {
+    throw Object.assign(new Error('Invalid cursor version'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor version is unsupported'),
+    });
+  }
+  const sort = normalizeCrInventorySort(decoded.sort);
+  const offset = Number(decoded.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor offset must be a non-negative integer'),
+    });
+  }
+  const requestedSort =
+    opts.sort == null || opts.sort === '' ? null : normalizeCrInventorySort(opts.sort);
+  if (requestedSort != null && requestedSort !== sort) {
+    throw Object.assign(new Error('Cursor sort mismatch'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        '--sort must match the cursor slice_sort when both are provided',
+      ),
+    });
+  }
+  return { sort, offset };
+}

package/cr-inventory.js

@@ -1,5 +1,6 @@
 import { sanitizeField } from './caps.js';
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { decodeCrInventoryCursor, encodeCrInventoryCursor } from './cr-inventory-cursor.js';
 import { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
 import {
   DEFAULT_CR_INVENTORY_SLICE_SORT,
@@ -22,9 +23,9 @@ export function normalizeCrInventoryLimit(value) {
   return n;
 }
 
-async function resolveOpenPullList(provider, ctx, entryLimit, sliceSort) {
+async function resolveOpenPullList(provider, ctx, listWindow, sliceSort) {
   if (typeof provider.listOpenPullsWithMeta === 'function') {
-    return provider.listOpenPullsWithMeta(ctx, { retain_max: entryLimit, sort: sliceSort });
+    return provider.listOpenPullsWithMeta(ctx, { retain_max: listWindow, sort: sliceSort });
   }
   const numbers = await provider.listOpenPulls(ctx, {});
   return { numbers, list_truncated: false };
@@ -64,7 +65,7 @@ export function buildCrInventoryEntry(ctx, view, checks) {
     mergeability: view.mergeability,
     checks_conclusion: checks.check_conclusion,
     checks_truncated: checks.checks_truncated === true,
-    blockers: mergeBlockersFromFacts(view, checks),
+    blockers: mergeBlockersFromFacts(view, checks, {}, ctx.mergePolicy ?? {}),
     head_reconcile: buildHeadReconcile(ctx, view),
   };
   if (view.forge_target_sha) entry.forge_target_sha = view.forge_target_sha;
@@ -76,18 +77,26 @@ export function buildCrInventoryEntry(ctx, view, checks) {
  * Aggregate open change requests into a semantic-diff-oriented inventory slice.
  * @param {object} ctx forge context
  * @param {object} provider must expose listOpenPulls, prView, prChecks
- * @param {{ slice_ref?: string, limit?: number, sort?: string }} [opts]
+ * @param {{ slice_ref?: string, limit?: number, sort?: string, cursor?: string }} [opts]
  */
 export async function crInventory(ctx, provider, opts = {}) {
   const limit = normalizeCrInventoryLimit(opts.limit);
-  const sliceSort = normalizeCrInventorySort(opts.sort);
+  let sliceSort = normalizeCrInventorySort(opts.sort);
+  let offset = 0;
+  if (opts.cursor != null && opts.cursor !== '') {
+    const decoded = decodeCrInventoryCursor(opts.cursor, { sort: opts.sort });
+    offset = decoded.offset;
+    sliceSort = decoded.sort;
+  }
+
+  const listWindow = offset + limit;
   const {
     numbers,
     list_truncated: listTruncated,
     entry_count: providerEntryCount,
-  } = await resolveOpenPullList(provider, ctx, limit, sliceSort);
+  } = await resolveOpenPullList(provider, ctx, listWindow, sliceSort);
   const entryCount = providerEntryCount ?? numbers.length;
-  const selected = numbers.slice(0, limit);
+  const selected = numbers.slice(offset, offset + limit);
   const entries = [];
   const entries_skipped = [];
   for (const number of selected) {
@@ -106,13 +115,22 @@ export async function crInventory(ctx, provider, opts = {}) {
       });
     }
   }
+
+  const observedEnd = offset + selected.length;
+  const hasMore = listTruncated || observedEnd < entryCount;
+  const complete = !hasMore;
+
   return {
     entries,
     ...(entries_skipped.length ? { entries_skipped } : {}),
     entry_count: entryCount,
-    truncated: entryCount > selected.length,
+    entry_count_observed: observedEnd,
+    truncated: entryCount > observedEnd || listTruncated,
     list_truncated: listTruncated,
     slice_sort: sliceSort ?? DEFAULT_CR_INVENTORY_SLICE_SORT,
+    has_more: hasMore,
+    complete,
+    ...(hasMore ? { next_cursor: encodeCrInventoryCursor({ sort: sliceSort, offset: observedEnd }) } : {}),
     ...(opts.slice_ref ? { slice_ref: sanitizeField(opts.slice_ref) } : {}),
   };
 }

package/cr-open.js

@@ -5,7 +5,7 @@ import { ERROR_CODES, forgeError } from './contracts/errors.js';
 export function buildChangeRequestOpenedBody(
   pull,
   { head, base, title },
-  { reusedExisting = false } = {},
+  { reusedExisting = false, idempotencyFields = null } = {},
 ) {
   const prNumber = Number(pull?.number);
   if (!Number.isInteger(prNumber) || prNumber <= 0) {
@@ -28,6 +28,11 @@ export function buildChangeRequestOpenedBody(
   };
   if (reusedExisting) {
     body.reused_existing = true;
+  } else {
+    body.created = true;
+  }
+  if (idempotencyFields && typeof idempotencyFields === 'object') {
+    Object.assign(body, idempotencyFields);
   }
   return body;
 }

package/forge-changes-cursor.js

@@ -0,0 +1,88 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { parseSinceObservedAt } from './forge-changes.js';
+
+export const FORGE_CHANGES_CURSOR_VERSION = 1;
+export const DEFAULT_FORGE_CHANGES_PAGE_SIZE = 64;
+
+/**
+ * @param {{ since: string, offset: number }} state
+ * @returns {string}
+ */
+export function encodeForgeChangesCursor(state) {
+  const since = parseSinceObservedAt(state.since);
+  const offset = Number(state.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid forge changes cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, 'cursor offset must be a non-negative integer'),
+    });
+  }
+  const payload = JSON.stringify({ v: FORGE_CHANGES_CURSOR_VERSION, since, offset });
+  return Buffer.from(payload, 'utf8').toString('base64url');
+}
+
+/**
+ * @param {unknown} raw
+ * @param {{ since?: string }} [opts]
+ * @returns {{ since: string, offset: number }}
+ */
+export function decodeForgeChangesCursor(raw, opts = {}) {
+  if (raw == null || raw === '') {
+    throw Object.assign(new Error('Missing forge changes cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor must not be empty when provided'),
+    });
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
+  } catch {
+    throw Object.assign(new Error('Invalid forge changes cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor is malformed or not base64url JSON'),
+    });
+  }
+  if (decoded?.v !== FORGE_CHANGES_CURSOR_VERSION) {
+    throw Object.assign(new Error('Invalid forge changes cursor version'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor version is unsupported'),
+    });
+  }
+  const since = parseSinceObservedAt(decoded.since);
+  const offset = Number(decoded.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid forge changes cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor offset must be a non-negative integer'),
+    });
+  }
+  if (opts.since != null && opts.since !== '') {
+    const requestedSince = parseSinceObservedAt(opts.since);
+    if (requestedSince !== since) {
+      throw Object.assign(new Error('Forge changes cursor since mismatch'), {
+        forgeError: forgeError(
+          ERROR_CODES.INVALID_ARGS,
+          '--since must match the cursor since when both are provided',
+        ),
+      });
+    }
+  }
+  return { since, offset };
+}
+
+/**
+ * @param {object} body
+ * @param {{ offset?: number, limit?: number }} [opts]
+ */
+export function paginateForgeChangesBody(body, opts = {}) {
+  const offset = opts.offset ?? 0;
+  const limit = opts.limit ?? DEFAULT_FORGE_CHANGES_PAGE_SIZE;
+  const allEvents = Array.isArray(body.events) ? body.events : [];
+  const pageEvents = allEvents.slice(offset, offset + limit);
+  const observedEnd = offset + pageEvents.length;
+  const hasMore = observedEnd < allEvents.length || body.events_truncated === true;
+  return {
+    ...body,
+    events: pageEvents,
+    has_more: hasMore,
+    complete: !hasMore,
+    ...(hasMore
+      ? { next_cursor: encodeForgeChangesCursor({ since: body.since, offset: observedEnd }) }
+      : {}),
+  };
+}

package/idempotency.js

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { sanitizeField } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+/** @type {Map<string, string>} */
+const scopeBindings = new Map();
+
+export function resetIdempotencyScopeBindings() {
+  scopeBindings.clear();
+}
+
+export function normalizeIdempotencyKey(value) {
+  if (value == null || value === '') return null;
+  const key = sanitizeField(String(value).trim());
+  if (!key || !KEY_PATTERN.test(key)) {
+    throw Object.assign(new Error('Invalid idempotency key'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        'idempotency key must be 1-128 characters from [A-Za-z0-9._:-]',
+      ),
+    });
+  }
+  return key;
+}
+
+export function idempotencyFingerprint(key, scopeParts = []) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  const scope = scopeParts.map((part) => sanitizeField(String(part ?? ''))).join('\0');
+  return createHash('sha256').update(`${normalizedKey}\0${scope}`).digest('hex').slice(0, 16);
+}
+
+export function idempotencyScopeKey(repoId, key) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  return `${sanitizeField(repoId)}:${normalizedKey}`;
+}
+
+export function bindIdempotencyScope(repoId, key, scopeParts) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  const bindingKey = idempotencyScopeKey(repoId, normalizedKey);
+  const serialized = JSON.stringify(scopeParts.map((part) => sanitizeField(String(part ?? ''))));
+  const prior = scopeBindings.get(bindingKey);
+  if (prior && prior !== serialized) {
+    throw Object.assign(new Error('Idempotency key scope conflict'), {
+      forgeError: forgeError(
+        ERROR_CODES.IDEMPOTENCY_CONFLICT,
+        'idempotency key was already used with a different write scope',
+      ),
+    });
+  }
+  scopeBindings.set(bindingKey, serialized);
+  return idempotencyFingerprint(normalizedKey, scopeParts);
+}
+
+export function idempotencyPacketFields(fingerprint, { reusedExisting = false, ambiguousAfterWrite = false } = {}) {
+  const fields = {};
+  if (fingerprint) fields.idempotency_fingerprint = fingerprint;
+  if (reusedExisting) {
+    fields.reused_existing = true;
+  } else {
+    fields.created = true;
+  }
+  if (ambiguousAfterWrite) fields.ambiguous_after_write = true;
+  return fields;
+}

package/index.js

@@ -52,6 +52,11 @@ export { assertGitRef, assertGitRemote } 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,
@@ -75,6 +80,7 @@ export {
   appendSortQuery,
 } from './open-pull-list.js';
 export { buildChangeRequestOpenedBody } from './cr-open.js';
+export { buildIssueOpenedBody, parseIssueOpenArgs } from './issue-open.js';
 export {
   assertExpectedSha,
   mergeExecuteViewFacts,
@@ -115,6 +121,11 @@ export {
   MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
   MAX_BRANCH_PROTECTION_RULES,
 } from './branch-protection.js';
+export {
+  enrichCheckStatus,
+  buildCheckDiagnostics,
+  buildPrChecksBody,
+} from './check-diagnostics.js';
 export {
   buildCrFilesBody,
   buildCrFilesFromGiteaFiles,
@@ -137,6 +148,13 @@ export {
   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,
@@ -145,6 +163,29 @@ export {
   writeNotConfiguredMessage,
   isWriteCommandConfigured,
 } from './write-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,

package/issue-open.js

@@ -0,0 +1,50 @@
+import { sanitizeField, 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
+    ? sanitizeField(issue?.title ?? title)
+    : sanitizeField(title ?? issue?.title);
+  const body = {
+    issue_number: issueNumber,
+    url: sanitizeUrl(issue.html_url ?? issue.url),
+    state: sanitizeField(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 }) {
+  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: sanitizeField(String(title)) };
+  if (issueBody != null && String(issueBody).trim() !== '') {
+    parsed.body = sanitizeField(String(issueBody));
+  }
+  return parsed;
+}

package/merge-blockers.js

@@ -1,5 +1,25 @@
 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.
@@ -13,14 +33,19 @@ export function isOpenPrState(state) {
  * @param {object} checks
  * @param {{ allowed_paths?: string[], changed_paths?: string[] | null }} [pathScope]
  */
-export function mergeBlockersFromFacts(view, checks, 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') blockers.push('checks_missing');
-  if (checks.check_conclusion === 'pending') blockers.push('checks_pending');
+  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) {

package/merge-plan-forge.js

@@ -58,5 +58,6 @@ export async function buildMergePlanFromProviderFacts(ctx, opts, deps) {
   const mergeOpts = await resolveMergePlanOptsWithForgePaths(opts, () =>
     deps.crFiles(ctx, { number: view.pr_number }),
   );
-  return buildMergePlanBodyFromFacts(view, checks, mergeOpts);
+  const mergePolicy = opts.merge_policy ?? ctx.mergePolicy ?? {};
+  return buildMergePlanBodyFromFacts(view, checks, { ...mergeOpts, merge_policy: mergePolicy });
 }

package/merge-plan.js

@@ -61,16 +61,22 @@ export function resolveMergePlanPathScope(opts = {}) {
   return { allowed_paths: allowedPaths, changed_paths: null };
 }
 
-export function buildMergePlanBody(view, checks, pathScope = {}) {
+export function buildMergePlanBody(view, checks, pathScope = {}, policy = {}) {
   return {
     pr_number: view.pr_number,
     mergeability: view.mergeability,
     checks_conclusion: checks.check_conclusion,
-    blockers: mergeBlockersFromFacts(view, checks, pathScope),
+    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);
-  return buildMergePlanBody(view, checks, pathScope);
+  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',
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remogram/core",
-  "version": "0.1.0-beta.8",
+  "version": "0.1.0-beta.9",
   "description": "Remogram forge envelope, config, caps, and HTTP utilities",
   "type": "module",
   "license": "MIT",

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/resolve.js

@@ -4,6 +4,7 @@ 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 { assertGitRemote } from './git-args.js';
 import { gitRepoRoot } from './git-local.js';
 
@@ -150,5 +151,6 @@ export function forgeContext(loaded) {
     config,
     cwd: loaded.cwd,
     parsed,
+    mergePolicy: resolveMergePolicy(config),
   };
 }

package/status-set.js

@@ -64,7 +64,7 @@ export function parseStatusSetArgs({ sha, context, state, target_url, descriptio
 export function buildCommitStatusSetBody(
   response,
   args,
-  { reusedExisting = false } = {},
+  { reusedExisting = false, idempotencyFields = null } = {},
 ) {
   const state = normalizeStatusSetState(response?.status ?? response?.state ?? args.state);
   const body = {
@@ -82,6 +82,11 @@ export function buildCommitStatusSetBody(
   }
   if (reusedExisting) {
     body.reused_existing = true;
+  } else {
+    body.created = true;
+  }
+  if (idempotencyFields && typeof idempotencyFields === 'object') {
+    Object.assign(body, idempotencyFields);
   }
   return body;
 }

package/write-config.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
 
 /** Canonical v1 consumer write command ids (schema + gate single source). */
-export const WRITE_COMMAND_IDS = Object.freeze(['cr_open', 'status_set', 'merge']);
+export const WRITE_COMMAND_IDS = Object.freeze(['cr_open', 'status_set', 'merge', 'issue_open']);
 
 export const writeCommandSchema = z.enum(WRITE_COMMAND_IDS);
 

package/write-readiness.js

@@ -0,0 +1,76 @@
+import { isWriteCommandConfigured } from './write-config.js';
+import { API_PROVIDER_COMMAND_AUTH, AUTH_CLASS } from './auth-classes.js';
+
+const WRITE_ID_TO_AUTH_COMMAND = Object.freeze({
+  merge: 'merge_execute',
+});
+
+function authCommandForWriteId(commandId) {
+  return WRITE_ID_TO_AUTH_COMMAND[commandId] ?? commandId;
+}
+
+function commandNeedsToken(commandId) {
+  return API_PROVIDER_COMMAND_AUTH[authCommandForWriteId(commandId)] === AUTH_CLASS.TOKEN_REQUIRED;
+}
+
+function providerImplementsWrite(commandId, providerCapabilities) {
+  const authCommand = authCommandForWriteId(commandId);
+  const command = providerCapabilities?.commands?.find(
+    (entry) => entry.name === commandId || entry.name === authCommand,
+  );
+  if (command) return command.implemented !== false;
+  return (providerCapabilities?.write_commands || []).includes(commandId);
+}
+
+function buildNextConfigSnippet(commandId, configuredWrites) {
+  const next = [...new Set([...(configuredWrites || []), commandId])].sort((a, b) => a.localeCompare(b));
+  return `"write_commands": ${JSON.stringify(next)}`;
+}
+
+/**
+ * @param {object} config
+ * @param {object | null} providerCapabilities
+ * @param {{ authPresent?: boolean }} [opts]
+ */
+export function buildWriteReadiness(config, providerCapabilities, opts = {}) {
+  const authPresent = opts.authPresent === true;
+  const providerWrites = [...new Set((providerCapabilities?.write_commands || []).filter(Boolean))].sort(
+    (a, b) => a.localeCompare(b),
+  );
+  const configuredWrites = [...new Set((Array.isArray(config?.write_commands) ? config.write_commands : []).filter(Boolean))].sort(
+    (a, b) => a.localeCompare(b),
+  );
+  const commandIds = [...new Set([...providerWrites, ...configuredWrites])].sort((a, b) => a.localeCompare(b));
+
+  const commands = commandIds.map((id) => {
+    const provider_supported = providerWrites.includes(id) && providerImplementsWrite(id, providerCapabilities);
+    const configured = isWriteCommandConfigured(config, id);
+    const auth_present = commandNeedsToken(id) ? authPresent : true;
+    const ready = provider_supported && configured && auth_present;
+    const entry = {
+      id,
+      provider_supported,
+      configured,
+      auth_present,
+      ready,
+    };
+    if (provider_supported && !configured) {
+      entry.next_config_snippet = buildNextConfigSnippet(id, configuredWrites);
+    }
+    return entry;
+  });
+
+  return {
+    configured_write_commands: configuredWrites,
+    provider_write_commands: providerWrites,
+    commands,
+  };
+}
+
+/** True when any provider-supported write is not ready (config or auth). */
+export function writeReadinessHasWarnings(writeConfig) {
+  if (!writeConfig?.commands?.length) return false;
+  return writeConfig.commands.some(
+    (entry) => entry.provider_supported === true && entry.ready !== true,
+  );
+}