@remogram/core 0.1.0-beta.3 → 0.1.0-beta.4

package/auth-classes.js

@@ -17,6 +17,7 @@ export const API_PROVIDER_COMMAND_AUTH = {
   pr_checks: AUTH_CLASS.TOKEN_REQUIRED,
   merge_plan: AUTH_CLASS.TOKEN_REQUIRED,
   sync_plan: AUTH_CLASS.GIT_ONLY,
+  cr_open: AUTH_CLASS.TOKEN_REQUIRED,
 };
 
 export function commandCapability(name, { implemented = true } = {}) {
@@ -27,10 +28,11 @@ export function commandCapability(name, { implemented = true } = {}) {
   return { name, implemented, auth_class };
 }
 
-export function apiProviderCommands() {
-  return Object.keys(API_PROVIDER_COMMAND_AUTH).map((name) =>
-    commandCapability(name, { implemented: true }),
-  );
+export function apiProviderCommands({ writeCommandsImplemented = false } = {}) {
+  return Object.keys(API_PROVIDER_COMMAND_AUTH).map((name) => {
+    const implemented = name === 'cr_open' ? writeCommandsImplemented : true;
+    return commandCapability(name, { implemented });
+  });
 }
 
 export function stubProviderCommands() {

package/caps.js

@@ -6,6 +6,11 @@ export const FORGE_INGEST_MAX_BYTES_ENV = 'REMOGRAM_FORGE_INGEST_MAX_BYTES';
 export const DEFAULT_CHECK_STATUS_PAGE_SIZE = 25;
 export const MAX_CHECK_STATUS_PAGES = 50;
 
+/** Gitea open-pull list page size for idempotency scan and inventory list bounds. */
+export const DEFAULT_OPEN_PULL_LIST_PAGE_SIZE = 100;
+/** Max pages scanned before cr open idempotency fails closed (decoupled from check-status pagination). */
+export const MAX_OPEN_PULL_IDEMPOTENCY_PAGES = 50;
+
 export function getEffectiveIngestMaxBytes() {
   const raw = process.env[FORGE_INGEST_MAX_BYTES_ENV];
   if (raw == null || raw === '') {
@@ -48,6 +53,46 @@ export function checkPaginationCapabilityFacts({ strategy, pageSizeParam, source
   };
 }
 
+/** Structured idempotency scan facts for provider capabilities (cr open). */
+export function idempotencyScanCapabilityFacts() {
+  return {
+    idempotency_scan: {
+      max_pages: MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
+      page_size: DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
+      ingest_backoff: 'halve_until_fit',
+    },
+  };
+}
+
+/** Structured open-pull list pagination facts for provider capabilities (cr inventory). */
+export function openPullListCapabilityFacts({
+  totalCountSource = null,
+  totalCountHeader = null,
+  sliceSortNotes = null,
+} = {}) {
+  const compliantMaxItems = DEFAULT_OPEN_PULL_LIST_PAGE_SIZE * MAX_CHECK_STATUS_PAGES;
+  return {
+    open_pull_list: {
+      max_pages: MAX_CHECK_STATUS_PAGES,
+      page_size: DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
+      ingest_backoff: 'halve_until_fit',
+      compliant_max_items: compliantMaxItems,
+      truncation_packet_field: 'list_truncated',
+      incomplete_error_code: 'inventory_list_incomplete',
+      default_slice_sort: 'number_asc',
+      supported_slice_sorts: [
+        'number_asc',
+        'number_desc',
+        'recent_update',
+        'recent_created',
+      ],
+      ...(totalCountSource ? { total_count_source: totalCountSource } : {}),
+      ...(totalCountHeader ? { total_count_header: totalCountHeader } : {}),
+      ...(sliceSortNotes ? { slice_sort_notes: sliceSortNotes } : {}),
+    },
+  };
+}
+
 export function capText(text, maxBytes = DEFAULT_MAX_BYTES) {
   if (!text) return { text: '', truncated: false, bytes: 0 };
   const buf = Buffer.from(text, 'utf8');

package/check-pagination.js

@@ -1,5 +1,6 @@
 import { ERROR_CODES } from './contracts/errors.js';
 import { DEFAULT_CHECK_STATUS_PAGE_SIZE, MAX_CHECK_STATUS_PAGES } from './caps.js';
+import { resolvePaginatedEntryCount } from './open-pull-list.js';
 
 function isOversizedIngestError(err) {
   return err?.forgeError?.code === ERROR_CODES.OVERSIZED_RAW_OUTPUT;
@@ -65,6 +66,21 @@ export async function fetchPageWithIngestBackoff(fetchPage, page, initialLimit)
   return { items, usedLimit };
 }
 
+/**
+ * When a full page lands on maxPages, probe one item on the next page to distinguish
+ * end-of-list from truncation.
+ * @template T
+ * @param {(opts: { page: number, limit: number }) => Promise<unknown[]>} fetchPage
+ * @param {number} page
+ * @param {number} maxPages
+ * @returns {Promise<boolean>} true when list is truncated (more items exist)
+ */
+async function probeNextPageHasItems(fetchPage, page, maxPages) {
+  if (page > maxPages) return true;
+  const { items: probeItems } = await fetchPageWithIngestBackoff(fetchPage, page + 1, 1);
+  return probeItems.length > 0;
+}
+
 /**
  * Offset/limit check-status pagination with ingest-cap backoff.
  * @param {{ fetchPage: (opts: { page: number, limit: number }) => Promise<unknown[]>, pageSize?: number, maxPages?: number }} opts
@@ -99,8 +115,8 @@ export async function paginateCheckStatusPages({
 /**
  * Offset/limit open-list pagination with ingest-cap backoff and optional list cap.
  * listLimit bounds request size per page; callers slice returned items when enforcing a hard cap.
- * @param {{ fetchPage: (opts: { page: number, limit: number }) => Promise<unknown[]>, pageSize: number, listLimit?: number | null, maxPages?: number, maxPagesTruncatesWithLimit?: boolean }} opts
- * @returns {Promise<{ items: unknown[], list_truncated: boolean }>}
+ * @param {{ fetchPage: (opts: { page: number, limit: number }) => Promise<unknown[]>, pageSize: number, listLimit?: number | null, maxPages?: number, maxPagesTruncatesWithLimit?: boolean, retainMax?: number | null, trustedEntryCount?: number | null, seededFirstPage?: { items: unknown[], usedLimit: number } | null, startPage?: number, suppressFinalPageProbe?: boolean }} opts
+ * @returns {Promise<{ items: unknown[], list_truncated: boolean, walked_count: number, entry_count?: number }>}
  */
 export async function paginateOffsetListPages({
   fetchPage,
@@ -108,31 +124,92 @@ export async function paginateOffsetListPages({
   listLimit = null,
   maxPages = MAX_CHECK_STATUS_PAGES,
   maxPagesTruncatesWithLimit = false,
+  retainMax = null,
+  trustedEntryCount = null,
+  seededFirstPage = null,
+  startPage = 1,
+  suppressFinalPageProbe = false,
 }) {
   const all = [];
+  let entryCount = 0;
   let listTruncated = false;
   let activeLimit = pageSize;
-  for (let page = 1; page <= maxPages; page += 1) {
-    const remaining = listLimit != null ? Math.max(listLimit - all.length, 0) : activeLimit;
-    if (listLimit != null && remaining === 0) break;
-    const requestLimit = listLimit != null ? Math.min(activeLimit, remaining) : activeLimit;
-    const { items, usedLimit } = await fetchPageWithIngestBackoff(fetchPage, page, requestLimit);
-    activeLimit = usedLimit;
-    all.push(...items);
-    if (items.length < usedLimit) break;
-    if (listLimit != null) {
-      if (all.length >= listLimit) {
-        listTruncated = items.length >= usedLimit;
-        break;
+
+  async function afterPage(page, items, usedLimit) {
+    entryCount += items.length;
+    if (retainMax != null) {
+      const space = Math.max(retainMax - all.length, 0);
+      if (space > 0) all.push(...items.slice(0, space));
+    } else {
+      all.push(...items);
+    }
+    if (items.length < usedLimit) {
+      if (
+        trustedEntryCount != null &&
+        trustedEntryCount > entryCount &&
+        page === 1 &&
+        page < maxPages
+      ) {
+        return false;
       }
+      return true;
+    }
+    if (listLimit != null && all.length >= listLimit) {
+      listTruncated = await probeNextPageHasItems(fetchPage, page, maxPages);
+      return true;
+    }
+    if (listLimit != null) {
       if (maxPagesTruncatesWithLimit && page === maxPages) {
         listTruncated = true;
-        break;
+        return true;
       }
     } else if (page === maxPages) {
-      listTruncated = true;
+      if (suppressFinalPageProbe) {
+        listTruncated = items.length >= usedLimit;
+      } else {
+        listTruncated = await probeNextPageHasItems(fetchPage, page, maxPages);
+      }
+      return true;
+    }
+    return false;
+  }
+
+  let page = startPage;
+  if (seededFirstPage && startPage === 1) {
+    const { items, usedLimit } = seededFirstPage;
+    activeLimit = usedLimit;
+    if (await afterPage(1, items, usedLimit)) {
+      return {
+        items: all,
+        list_truncated: listTruncated,
+        walked_count: entryCount,
+        ...(retainMax != null || trustedEntryCount != null
+          ? { entry_count: resolvePaginatedEntryCount(trustedEntryCount, entryCount) }
+          : {}),
+      };
+    }
+    page = 2;
+  }
+
+  for (; page <= maxPages; page += 1) {
+    const remaining = listLimit != null ? Math.max(listLimit - all.length, 0) : activeLimit;
+    if (listLimit != null && remaining === 0) break;
+    const requestLimit = listLimit != null ? Math.min(activeLimit, remaining) : activeLimit;
+    const { items, usedLimit } = await fetchPageWithIngestBackoff(fetchPage, page, requestLimit);
+    activeLimit = usedLimit;
+    if (await afterPage(page, items, usedLimit)) {
       break;
     }
   }
-  return { items: all, list_truncated: listTruncated };
+
+  return {
+    items: all,
+    list_truncated: listTruncated,
+    walked_count: entryCount,
+    ...(retainMax != null || trustedEntryCount != null
+      ? {
+          entry_count: resolvePaginatedEntryCount(trustedEntryCount, entryCount),
+        }
+      : {}),
+  };
 }

package/config-schema.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { writeCommandSchema } from './write-config.js';
 
 const providerSchema = z.enum([
   'gitea-api',
@@ -23,6 +24,7 @@ export const configSchema = z
     owner: repoSegmentSchema,
     repo: repoSegmentSchema,
     baseUrl: z.string().url().optional(),
+    write_commands: z.array(writeCommandSchema).optional(),
   })
   .strict();
 

package/contracts/envelope.js

@@ -1,4 +1,5 @@
 import { sanitizeField } from '../caps.js';
+import { normalizeForgeErrorFields } from './forge-error-fields.js';
 
 export const SCHEMA_VERSION = 1;
 
@@ -12,6 +13,7 @@ export const PACKET_TYPES = {
   PROVIDER_CAPABILITIES: 'provider_capabilities',
   PROVIDER_DOCTOR: 'provider_doctor',
   FORGE_ERROR: 'forge_error',
+  CHANGE_REQUEST_OPENED: 'change_request_opened',
 };
 
 export const FORBIDDEN_PACKET_KEYS = new Set([
@@ -29,7 +31,7 @@ function assertNoForbiddenKeys(value) {
   }
   for (const [key, nested] of Object.entries(value)) {
     if (FORBIDDEN_PACKET_KEYS.has(key)) {
-      throw new Error(`Forbidden Topogram concept in remogram output: ${key}`);
+      throw new Error(`Forbidden workflow/planning-tool key in remogram output: ${key}`);
     }
     assertNoForbiddenKeys(nested);
   }
@@ -53,13 +55,21 @@ export function forgePacket(type, context, body = {}, error = null) {
     packet.error_code = error.code;
     packet.error_message = sanitizeField(error.message);
     if (error.status != null) packet.error_status = error.status;
+    if (error.fields != null && typeof error.fields === 'object') {
+      assertNoForbiddenKeys(error.fields);
+      const trustedFields = normalizeForgeErrorFields(error.code, error.fields);
+      if (trustedFields != null) {
+        Object.assign(packet, trustedFields);
+      }
+    }
   }
 
   return packet;
 }
 
 export function forgeErrorPacket(context, error, type = PACKET_TYPES.FORGE_ERROR) {
-  return forgePacket(type, context, {}, error);
+  const body = error?.fields != null && typeof error.fields === 'object' ? error.fields : {};
+  return forgePacket(type, context, body, error);
 }
 
 export function unknownForgeContext() {

package/contracts/errors.js

@@ -13,8 +13,16 @@ export const ERROR_CODES = {
   API_ERROR: 'api_error',
   PR_NOT_OPEN: 'pr_not_open',
   REMOTE_INFER_FAILED: 'remote_infer_failed',
+  WRITE_NOT_CONFIGURED: 'write_not_configured',
+  IDEMPOTENCY_SCAN_INCOMPLETE: 'idempotency_scan_incomplete',
+  INVENTORY_LIST_INCOMPLETE: 'inventory_list_incomplete',
 };
 
-export function forgeError(code, message, status = null) {
-  return { code, message, ...(status != null ? { status } : {}) };
+export function forgeError(code, message, status = null, fields = null) {
+  return {
+    code,
+    message,
+    ...(status != null ? { status } : {}),
+    ...(fields != null && typeof fields === 'object' ? { fields } : {}),
+  };
 }

package/contracts/forge-error-fields.js

@@ -0,0 +1,97 @@
+import { ERROR_CODES } from './errors.js';
+
+/** Top-level packet keys forge error fields must never override. */
+const FORBIDDEN_ERROR_FIELD_KEYS = new Set([
+  'type',
+  'schema_version',
+  'provider_id',
+  'remote_name',
+  'repo_id',
+  'observed_at',
+  'ok',
+  'error_code',
+  'error_message',
+  'error_status',
+]);
+
+/** Trusted body fields allowed per forge error code. */
+export const FORGE_ERROR_FIELD_ALLOWLIST = Object.freeze({
+  [ERROR_CODES.IDEMPOTENCY_SCAN_INCOMPLETE]: ['idempotency_scan'],
+  [ERROR_CODES.INVENTORY_LIST_INCOMPLETE]: ['inventory_list'],
+});
+
+function assertPositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`Invalid forge error field ${name}: must be a positive integer`);
+  }
+}
+
+function validateIdempotencyScan(scan) {
+  if (scan == null || typeof scan !== 'object' || Array.isArray(scan)) {
+    throw new Error('Invalid forge error field idempotency_scan: must be an object');
+  }
+  const keys = Object.keys(scan).sort();
+  const expected = ['max_pages', 'page_size', 'pages'];
+  if (keys.length !== expected.length || !expected.every((k) => keys.includes(k))) {
+    throw new Error('Invalid forge error field idempotency_scan: unexpected keys');
+  }
+  assertPositiveInteger('idempotency_scan.pages', scan.pages);
+  assertPositiveInteger('idempotency_scan.max_pages', scan.max_pages);
+  assertPositiveInteger('idempotency_scan.page_size', scan.page_size);
+  return { idempotency_scan: scan };
+}
+
+function validateInventoryList(list) {
+  if (list == null || typeof list !== 'object' || Array.isArray(list)) {
+    throw new Error('Invalid forge error field inventory_list: must be an object');
+  }
+  const keys = Object.keys(list).sort();
+  if (keys.length !== 1 || keys[0] !== 'entry_count') {
+    throw new Error('Invalid forge error field inventory_list: unexpected keys');
+  }
+  assertPositiveInteger('inventory_list.entry_count', list.entry_count);
+  return { inventory_list: list };
+}
+
+/**
+ * Validate and normalize trusted forge_error body fields before packet merge.
+ * @param {string} code
+ * @param {Record<string, unknown> | null | undefined} fields
+ * @returns {Record<string, unknown> | null}
+ */
+export function normalizeForgeErrorFields(code, fields) {
+  if (fields == null) return null;
+  if (typeof fields !== 'object' || Array.isArray(fields)) {
+    throw new Error('Invalid forge error fields: must be an object');
+  }
+
+  const keys = Object.keys(fields);
+  if (keys.length === 0) return null;
+
+  for (const key of keys) {
+    if (FORBIDDEN_ERROR_FIELD_KEYS.has(key)) {
+      throw new Error(`Forge error fields cannot override packet field ${key}`);
+    }
+  }
+
+  const allowlist = FORGE_ERROR_FIELD_ALLOWLIST[code];
+  if (!allowlist) {
+    throw new Error(`Forge error code ${code} does not allow trusted fields`);
+  }
+
+  for (const key of keys) {
+    if (!allowlist.includes(key)) {
+      throw new Error(`Forge error field ${key} is not allowed for code ${code}`);
+    }
+  }
+
+  if (fields.idempotency_scan != null) {
+    return validateIdempotencyScan(fields.idempotency_scan);
+  }
+
+  if (fields.inventory_list != null) {
+    return validateInventoryList(fields.inventory_list);
+  }
+
+  return fields;
+}

package/contracts/observer-fact-inventory.js

@@ -1,10 +1,7 @@
 /**
- * Remogram fact requirements for Topogram branch-workcycle observer snapshots.
- * Observer proto today captures remogram repo status only; semantic-diff consumers
+ * Remogram fact requirements for observer and semantic-diff consumer snapshots.
+ * Observer proto today captures remogram repo status only; downstream consumers
  * may compose additional read-only fact packets listed here.
- *
- * @see ../topogram/tools/branch-workcycle/observer-snapshot.sh
- * @see topo/sdlc/acceptance_criteria/semantic_diff_fact_inventory.tg ac_semantic_diff_observer_facts
  */
 
 import { FACT_INVENTORY_PACKET_TYPES, V1_READ_PLAN_COMMANDS } from './semantic-diff-facts.js';

package/contracts/semantic-diff-facts.js

@@ -22,6 +22,9 @@ export const V1_READ_PLAN_COMMANDS = Object.freeze([
   'doctor',
 ]);
 
+/** v1 write surface (Gitea cr open only in first slice). */
+export const V1_WRITE_COMMANDS = Object.freeze(['cr open']);
+
 /**
  * Planned fact-inventory packet types (not emitted until wave 2+ commands ship).
  * All use schema_version 1 envelope discipline via forgePacket.
@@ -55,11 +58,14 @@ export const TRUSTED_NORMALIZED_BODY_FIELDS = Object.freeze({
   truncated: true,
   list_truncated: true,
   checks_truncated: true,
+  slice_sort: true,
   entry_count: true,
   mergeability_confidence: true,
   write_support: true,
   diverged: true,
   auth_present: true,
+  reused_existing: true,
+  idempotency_scan: true,
 });
 
 /**
@@ -74,6 +80,7 @@ export const FORGE_SOURCED_STRING_LEAVES = Object.freeze({
   merge_plan: ['blockers[].message', 'blockers[].context'],
   sync_plan: ['remote', 'local_sha', 'remote_sha', 'blockers[].message'],
   ref_inventory: ['refs[].name', 'refs[].sha', 'default_ref'],
+  change_request_opened: ['url', 'title', 'head', 'base'],
   cr_inventory_slice: [
     'entries[].url',
     'entries[].title',
@@ -88,7 +95,7 @@ export const FORGE_SOURCED_STRING_LEAVES = Object.freeze({
   ],
 });
 
-/** Keys that must never appear in remogram output (Topogram SDLC/workflow concepts). */
+/** Keys that must never appear in remogram output (external planning/SDLC workflow concepts). */
 export { FORBIDDEN_PACKET_KEYS };
 
 /**
@@ -108,6 +115,8 @@ export const FACT_INVENTORY_BODY_SHAPES = Object.freeze({
     /** true when list cap applied (entry_count > limit), not missing entries */
     truncated: 'boolean',
     list_truncated: 'boolean',
+    /** normalized slice sort preset applied to open-list resolution */
+    slice_sort: 'string',
     entries_skipped:
       'array<{ pr_number: number, error_code: pr_not_open | api_error | oversized_raw_output | ... }> optional',
     slice_ref: 'string optional',
@@ -116,7 +125,7 @@ export const FACT_INVENTORY_BODY_SHAPES = Object.freeze({
 
 /**
  * Build a fact-inventory packet body through the standard envelope gate.
- * Throws if body contains forbidden Topogram workflow keys.
+ * Throws if body contains forbidden workflow/planning-tool keys.
  */
 export function forgeFactInventoryPacket(type, context, body = {}, error = null) {
   if (!Object.values(FACT_INVENTORY_PACKET_TYPES).includes(type)) {

package/cr-inventory.js

@@ -1,12 +1,18 @@
 import { sanitizeField } from './caps.js';
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
 import { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
+import {
+  DEFAULT_CR_INVENTORY_SLICE_SORT,
+  normalizeCrInventorySort,
+} from './open-pull-list.js';
 import { staleHeadDetails } from './pr-head-reconcile.js';
 
 export const DEFAULT_CR_INVENTORY_LIMIT = 50;
+/** Default bound when `--limit` is omitted (keeps forge ingest under cap on large repos). */
+export const DEFAULT_CR_INVENTORY_SAFE_LIMIT = 3;
 
 export function normalizeCrInventoryLimit(value) {
-  if (value == null || value === '') return DEFAULT_CR_INVENTORY_LIMIT;
+  if (value == null || value === '') return DEFAULT_CR_INVENTORY_SAFE_LIMIT;
   const n = Number(value);
   if (!Number.isInteger(n) || n <= 0) {
     throw Object.assign(new Error('Invalid cr inventory limit'), {
@@ -16,12 +22,11 @@ export function normalizeCrInventoryLimit(value) {
   return n;
 }
 
-async function resolveOpenPullList(provider, ctx, limit) {
-  const listOpts = { limit };
+async function resolveOpenPullList(provider, ctx, entryLimit, sliceSort) {
   if (typeof provider.listOpenPullsWithMeta === 'function') {
-    return provider.listOpenPullsWithMeta(ctx, listOpts);
+    return provider.listOpenPullsWithMeta(ctx, { retain_max: entryLimit, sort: sliceSort });
   }
-  const numbers = await provider.listOpenPulls(ctx, listOpts);
+  const numbers = await provider.listOpenPulls(ctx, {});
   return { numbers, list_truncated: false };
 }
 
@@ -71,16 +76,17 @@ 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 }} [opts]
+ * @param {{ slice_ref?: string, limit?: number, sort?: string }} [opts]
  */
 export async function crInventory(ctx, provider, opts = {}) {
   const limit = normalizeCrInventoryLimit(opts.limit);
-  const { numbers, list_truncated: listTruncated } = await resolveOpenPullList(
-    provider,
-    ctx,
-    limit,
-  );
-  const entryCount = numbers.length;
+  const sliceSort = normalizeCrInventorySort(opts.sort);
+  const {
+    numbers,
+    list_truncated: listTruncated,
+    entry_count: providerEntryCount,
+  } = await resolveOpenPullList(provider, ctx, limit, sliceSort);
+  const entryCount = providerEntryCount ?? numbers.length;
   const selected = numbers.slice(0, limit);
   const entries = [];
   const entries_skipped = [];
@@ -106,6 +112,7 @@ export async function crInventory(ctx, provider, opts = {}) {
     entry_count: entryCount,
     truncated: entryCount > selected.length,
     list_truncated: listTruncated,
+    slice_sort: sliceSort ?? DEFAULT_CR_INVENTORY_SLICE_SORT,
     ...(opts.slice_ref ? { slice_ref: sanitizeField(opts.slice_ref) } : {}),
   };
 }

package/cr-open.js

@@ -0,0 +1,33 @@
+import { sanitizeField, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Normalize Gitea pull create response into change_request_opened body fields. */
+export function buildChangeRequestOpenedBody(
+  pull,
+  { head, base, title },
+  { reusedExisting = false } = {},
+) {
+  const prNumber = Number(pull?.number);
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    throw Object.assign(new Error('Provider returned invalid pull number'), {
+      forgeError: forgeError(
+        ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT,
+        'Provider returned invalid pull number',
+      ),
+    });
+  }
+  const resolvedTitle = reusedExisting
+    ? sanitizeField(pull?.title ?? title)
+    : sanitizeField(title ?? pull?.title);
+  const body = {
+    pr_number: prNumber,
+    url: sanitizeUrl(pull.html_url ?? pull.url),
+    head: sanitizeField(head),
+    base: sanitizeField(base),
+    title: resolvedTitle,
+  };
+  if (reusedExisting) {
+    body.reused_existing = true;
+  }
+  return body;
+}

package/git-local.js

@@ -43,3 +43,15 @@ export function gitAheadBehind(cwd, base, head) {
     return { ahead_by: null, behind_by: null };
   }
 }
+
+export function gitDiffNameOnly(cwd, base, head) {
+  assertGitRef(base, 'base');
+  assertGitRef(head, 'head');
+  try {
+    const out = gitExec(cwd, ['diff', '--name-only', base, head]);
+    if (!out) return [];
+    return out.split('\n').filter(Boolean);
+  } catch {
+    return null;
+  }
+}

package/index.js

@@ -16,6 +16,10 @@ export {
   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,
@@ -26,9 +30,13 @@ export {
   FORGE_INGEST_MAX_BYTES_ENV,
   DEFAULT_CHECK_STATUS_PAGE_SIZE,
   MAX_CHECK_STATUS_PAGES,
+  DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
+  MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
   getEffectiveIngestMaxBytes,
   forgeIngestCapabilityFacts,
   checkPaginationCapabilityFacts,
+  idempotencyScanCapabilityFacts,
+  openPullListCapabilityFacts,
 } from './caps.js';
 export {
   paginateCheckStatusPages,
@@ -39,10 +47,51 @@ export {
   withLimitParam,
 } from './check-pagination.js';
 export { assertGitRef, assertGitRemote } from './git-args.js';
-export { gitRevParse, gitCurrentBranch, gitAheadBehind, gitRepoRoot } from './git-local.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, normalizeCrInventoryLimit } from './cr-inventory.js';
+export { buildCrInventoryEntry, buildHeadReconcile, crInventory, DEFAULT_CR_INVENTORY_LIMIT, DEFAULT_CR_INVENTORY_SAFE_LIMIT, normalizeCrInventoryLimit } from './cr-inventory.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 {
+  WRITE_COMMAND_IDS,
+  CONFIGURED_WRITE_COMMANDS,
+  writeCommandSchema,
+  assertWriteCommandConfigured,
+  isWriteCommandConfigured,
+} from './write-config.js';
 export { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
+export {
+  resolveMergePlanPathScope,
+  buildMergePlanBody,
+  buildMergePlanBodyFromFacts,
+} from './merge-plan.js';
+export {
+  matchPathAllowlist,
+  isPathAllowed,
+  pathsOutsideAllowlist,
+  allPathsAllowed,
+} from './path-allowlist.js';
 export {
   localHeadShaForPr,
   staleHeadDetails,

package/merge-blockers.js

@@ -1,3 +1,5 @@
+import { allPathsAllowed } from './path-allowlist.js';
+
 /**
  * Derive merge blockers from already-fetched PR view and checks facts.
  * Shared by merge plan and cr inventory aggregation.
@@ -6,7 +8,12 @@ export function isOpenPrState(state) {
   return String(state ?? '').toLowerCase() === 'open';
 }
 
-export function mergeBlockersFromFacts(view, checks) {
+/**
+ * @param {object} view
+ * @param {object} checks
+ * @param {{ allowed_paths?: string[], changed_paths?: string[] | null }} [pathScope]
+ */
+export function mergeBlockersFromFacts(view, checks, pathScope = {}) {
   const blockers = [];
   if (view.mergeability === 'conflicted') blockers.push('merge_conflict');
   if (!isOpenPrState(view.state)) blockers.push('pr_not_open');
@@ -14,5 +21,16 @@ export function mergeBlockersFromFacts(view, checks) {
   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');
+
+  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 (!allPathsAllowed(allowedPaths, changedPaths)) {
+      blockers.push('path_scope_violation');
+    }
+  }
+
   return blockers;
 }

package/merge-plan.js

@@ -0,0 +1,34 @@
+import { gitDiffNameOnly } from './git-local.js';
+import { mergeBlockersFromFacts } from './merge-blockers.js';
+
+function normalizeAllowedPaths(allowedPaths) {
+  if (!Array.isArray(allowedPaths)) return null;
+  const normalized = allowedPaths.filter((entry) => typeof entry === 'string' && entry.length > 0);
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function resolveMergePlanPathScope(ctx, view, opts = {}) {
+  const allowedPaths = normalizeAllowedPaths(opts.allowed_paths);
+  if (!allowedPaths) {
+    return { allowed_paths: null, changed_paths: null };
+  }
+  if (!view.base_sha || !view.head_sha) {
+    return { allowed_paths: allowedPaths, changed_paths: null };
+  }
+  const changedPaths = gitDiffNameOnly(ctx.cwd, view.base_sha, view.head_sha);
+  return { allowed_paths: allowedPaths, changed_paths: changedPaths };
+}
+
+export function buildMergePlanBody(view, checks, pathScope = {}) {
+  return {
+    pr_number: view.pr_number,
+    mergeability: view.mergeability,
+    checks_conclusion: checks.check_conclusion,
+    blockers: mergeBlockersFromFacts(view, checks, pathScope),
+  };
+}
+
+export function buildMergePlanBodyFromFacts(ctx, view, checks, opts = {}) {
+  const pathScope = resolveMergePlanPathScope(ctx, view, opts);
+  return buildMergePlanBody(view, checks, pathScope);
+}

package/open-pull-list.js

@@ -0,0 +1,256 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Normalized slice sort keys exposed on CLI/MCP and success packets. */
+export const CR_INVENTORY_SLICE_SORTS = Object.freeze([
+  'number_asc',
+  'number_desc',
+  'recent_update',
+  'recent_created',
+]);
+
+export const DEFAULT_CR_INVENTORY_SLICE_SORT = 'number_asc';
+
+/**
+ * @param {unknown} value
+ * @returns {typeof CR_INVENTORY_SLICE_SORTS[number]}
+ */
+export function normalizeCrInventorySort(value) {
+  if (value == null || value === '') return DEFAULT_CR_INVENTORY_SLICE_SORT;
+  const sort = String(value).trim().toLowerCase();
+  if (!CR_INVENTORY_SLICE_SORTS.includes(sort)) {
+    throw Object.assign(new Error('Invalid cr inventory sort'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        `--sort must be one of: ${CR_INVENTORY_SLICE_SORTS.join(', ')}`,
+      ),
+    });
+  }
+  return sort;
+}
+
+/**
+ * Parse forge total-count response header as a positive integer within sanity bounds.
+ * @param {Headers | Record<string, string> | null | undefined} headers
+ * @param {string} headerName
+ * @param {{ maxTrusted: number }} opts
+ * @returns {number | null}
+ */
+export function parseTotalCountHeader(headers, headerName, { maxTrusted }) {
+  if (headers == null || maxTrusted <= 0) return null;
+  const read =
+    typeof headers.get === 'function'
+      ? (name) => headers.get(name)
+      : (name) => headers[name] ?? headers[String(name).toLowerCase()];
+  const raw = read(headerName) ?? read(String(headerName).toLowerCase());
+  if (raw == null || raw === '') return null;
+  const n = Number.parseInt(String(raw).trim(), 10);
+  if (!Number.isFinite(n) || n <= 0 || n > maxTrusted) return null;
+  return n;
+}
+
+/**
+ * Fast path applies to cr inventory retain_max slices, not idempotency scans.
+ * @param {{ retain_max?: number | null, limit?: number | null }} opts
+ */
+export function isCrInventoryFastPathEligible(opts = {}) {
+  return (
+    opts.retain_max != null &&
+    Number.isInteger(Number(opts.retain_max)) &&
+    Number(opts.retain_max) > 0
+  );
+}
+
+/**
+ * When forge order is authoritative, skip client-side number reordering.
+ * @param {string} sliceSort
+ */
+export function forgeOrderAuthoritative(sliceSort) {
+  return sliceSort === 'recent_update' || sliceSort === 'recent_created';
+}
+
+/**
+ * Fast path requires the first page to contain the expected item count.
+ * @param {number} totalCount
+ * @param {number} requestLimit
+ * @param {number} bodyLength
+ */
+export function validateFastPathPageLength(totalCount, requestLimit, bodyLength) {
+  const expected = Math.min(totalCount, requestLimit);
+  return bodyLength === expected;
+}
+
+/**
+ * Number sorts need full local reorder; skip fast path when total exceeds retain_max.
+ * @param {number} totalCount
+ * @param {number} retainMax
+ * @param {string} sliceSort
+ */
+export function isNumberSortFastPathEligible(totalCount, retainMax, sliceSort) {
+  if (sliceSort !== 'number_asc' && sliceSort !== 'number_desc') return true;
+  return totalCount <= retainMax;
+}
+
+/**
+ * Prefer forge header/search total over summed pagination lengths on fallback.
+ * @param {number | null | undefined} trustedTotal
+ * @param {number} summedCount
+ */
+export function resolvePaginatedEntryCount(trustedTotal, summedCount) {
+  if (trustedTotal != null && Number.isInteger(trustedTotal) && trustedTotal > 0) {
+    return trustedTotal;
+  }
+  return summedCount;
+}
+
+/**
+ * When forge total is trusted but pagination walked fewer items, mark truncated.
+ * @param {{ listTruncated: boolean, trustedTotalCount?: number | null, walkedCount: number, fullCollect?: boolean }} opts
+ */
+export function resolveListTruncatedWithTrustedTotal({
+  listTruncated,
+  trustedTotalCount,
+  walkedCount,
+  fullCollect = false,
+}) {
+  if (
+    trustedTotalCount != null &&
+    Number.isInteger(trustedTotalCount) &&
+    trustedTotalCount > 0 &&
+    walkedCount < trustedTotalCount
+  ) {
+    return true;
+  }
+  return listTruncated;
+}
+
+/**
+ * Gitea recent_created uses oldest sort; fast path only when total fits retain_max.
+ * @param {number} totalCount
+ * @param {number} retainMax
+ * @param {string} sliceSort
+ * @param {string} providerId
+ */
+export function isRecentCreatedFastPathEligible(totalCount, retainMax, sliceSort, providerId) {
+  if (sliceSort !== 'recent_created' || providerId !== 'gitea-api') return true;
+  return totalCount <= retainMax;
+}
+
+/**
+ * Last page index for Gitea sort=oldest when fetching globally newest-created slice.
+ * @param {number} totalCount
+ * @param {number} pageSize
+ */
+export function giteaRecentCreatedTailPage(totalCount, pageSize) {
+  if (!Number.isInteger(totalCount) || totalCount <= 0) return 1;
+  if (!Number.isInteger(pageSize) || pageSize <= 0) return 1;
+  return Math.max(1, Math.ceil(totalCount / pageSize));
+}
+
+/**
+ * Number sorts need full local reorder when total exceeds retain_max.
+ * @param {number} totalCount
+ * @param {number} retainMax
+ * @param {string} sliceSort
+ */
+export function isNumberSortFullCollectRequired(totalCount, retainMax, sliceSort) {
+  if (forgeOrderAuthoritative(sliceSort)) return false;
+  return !isNumberSortFastPathEligible(totalCount, retainMax, sliceSort);
+}
+
+/**
+ * Gitea sort=oldest returns oldest-first; recent_created needs newest-first.
+ * @param {unknown[]} items
+ * @param {string} sliceSort
+ */
+export function prepareGiteaOpenPullPageItems(items, sliceSort) {
+  if (sliceSort !== 'recent_created' || !Array.isArray(items)) return items;
+  return items.slice().reverse();
+}
+
+/**
+ * @param {unknown[]} items
+ * @param {(item: unknown) => number | null | undefined} getNumber
+ * @param {string} sliceSort
+ * @returns {number[]}
+ */
+export function orderOpenPullNumbers(items, getNumber, sliceSort) {
+  const numbers = items
+    .map(getNumber)
+    .filter((number) => Number.isInteger(number));
+  if (forgeOrderAuthoritative(sliceSort)) return numbers;
+  numbers.sort((a, b) => (sliceSort === 'number_desc' ? b - a : a - b));
+  return numbers;
+}
+
+/**
+ * @param {{ totalCount?: number | null, numbers: number[], listTruncated: boolean, sliceSort?: string }} meta
+ */
+export function buildOpenPullListMeta({ totalCount, numbers, listTruncated, sliceSort }) {
+  return {
+    numbers,
+    list_truncated: listTruncated,
+    ...(totalCount != null ? { entry_count: totalCount } : {}),
+    ...(sliceSort ? { slice_sort: sliceSort } : {}),
+  };
+}
+
+/**
+ * Gitea query params for normalized slice sort.
+ * @param {string} sliceSort
+ */
+export function giteaOpenPullSortQuery(sliceSort) {
+  switch (sliceSort) {
+    case 'recent_update':
+      return { sort: 'recentupdate' };
+    case 'recent_created':
+      return { sort: 'oldest' };
+    default:
+      return {};
+  }
+}
+
+/**
+ * GitLab query params for normalized slice sort.
+ * @param {string} sliceSort
+ */
+export function gitlabOpenPullSortQuery(sliceSort) {
+  switch (sliceSort) {
+    case 'recent_update':
+      return { order_by: 'updated_at', sort: 'desc' };
+    case 'recent_created':
+      return { order_by: 'created_at', sort: 'desc' };
+    case 'number_desc':
+      return { order_by: 'created_at', sort: 'desc' };
+    default:
+      return { order_by: 'created_at', sort: 'asc' };
+  }
+}
+
+/**
+ * GitHub query params for normalized slice sort on list pulls.
+ * @param {string} sliceSort
+ */
+export function githubOpenPullSortQuery(sliceSort) {
+  switch (sliceSort) {
+    case 'recent_update':
+      return { sort: 'updated', direction: 'desc' };
+    case 'recent_created':
+      return { sort: 'created', direction: 'desc' };
+    case 'number_desc':
+      return { sort: 'created', direction: 'desc' };
+    default:
+      return { sort: 'created', direction: 'asc' };
+  }
+}
+
+/**
+ * Append URLSearchParams for forge sort query entries.
+ * @param {string} path
+ * @param {Record<string, string>} query
+ */
+export function appendSortQuery(path, query) {
+  if (!query || Object.keys(query).length === 0) return path;
+  const sep = path.includes('?') ? '&' : '?';
+  const params = new URLSearchParams(query);
+  return `${path}${sep}${params.toString()}`;
+}

package/package.json

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

package/path-allowlist.js

@@ -0,0 +1,63 @@
+/**
+ * Glob allowlist matching for autonomous Observer auto-merge scope checks.
+ * Supports `**`, `*`, and literal path segments (e.g. README.md).
+ */
+
+function globToRegExp(glob) {
+  let pattern = '';
+  for (let i = 0; i < glob.length; i += 1) {
+    const ch = glob[i];
+    if (ch === '*' && glob[i + 1] === '*') {
+      pattern += '.*';
+      i += 1;
+      if (glob[i + 1] === '/') i += 1;
+    } else if (ch === '*') {
+      pattern += '[^/]*';
+    } else if (/[+?^${}()|[\]\\]/.test(ch)) {
+      pattern += `\\${ch}`;
+    } else {
+      pattern += ch;
+    }
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * @param {string} glob
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function matchPathAllowlist(glob, filePath) {
+  if (typeof glob !== 'string' || typeof filePath !== 'string') return false;
+  const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  return globToRegExp(glob).test(normalized);
+}
+
+/**
+ * @param {string[]} allowedPaths
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isPathAllowed(allowedPaths, filePath) {
+  if (!Array.isArray(allowedPaths) || allowedPaths.length === 0) return false;
+  return allowedPaths.some((glob) => matchPathAllowlist(glob, filePath));
+}
+
+/**
+ * @param {string[]} allowedPaths
+ * @param {string[]} changedPaths
+ * @returns {string[]}
+ */
+export function pathsOutsideAllowlist(allowedPaths, changedPaths) {
+  if (!Array.isArray(changedPaths)) return [];
+  return changedPaths.filter((filePath) => !isPathAllowed(allowedPaths, filePath));
+}
+
+/**
+ * @param {string[]} allowedPaths
+ * @param {string[]} changedPaths
+ * @returns {boolean}
+ */
+export function allPathsAllowed(allowedPaths, changedPaths) {
+  return pathsOutsideAllowlist(allowedPaths, changedPaths).length === 0;
+}

package/write-config.js

@@ -0,0 +1,34 @@
+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']);
+
+export const writeCommandSchema = z.enum(WRITE_COMMAND_IDS);
+
+/** @deprecated use WRITE_COMMAND_IDS */
+export const CONFIGURED_WRITE_COMMANDS = WRITE_COMMAND_IDS;
+
+export function isWriteCommandConfigured(config, commandName) {
+  if (!writeCommandSchema.safeParse(commandName).success) return false;
+  const allowed = config?.write_commands;
+  return Array.isArray(allowed) && allowed.includes(commandName);
+}
+
+export function assertWriteCommandConfigured(config, 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(', ')}`,
+      ),
+    });
+  }
+  if (isWriteCommandConfigured(config, commandName)) return;
+  throw Object.assign(new Error(`Write command not configured: ${commandName}`), {
+    forgeError: forgeError(
+      ERROR_CODES.WRITE_NOT_CONFIGURED,
+      `Add "${commandName}" to write_commands in .remogram.json to enable this command`,
+    ),
+  });
+}