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

package/auth-classes.js

@@ -11,10 +11,13 @@ const AUTH_CLASS_VALUES = new Set(Object.values(AUTH_CLASS));
 export const API_PROVIDER_COMMAND_AUTH = {
   repo_status: AUTH_CLASS.NONE,
   ref_compare: AUTH_CLASS.GIT_ONLY,
+  ref_inventory: AUTH_CLASS.GIT_ONLY,
+  cr_inventory: AUTH_CLASS.TOKEN_REQUIRED,
   pr_status: AUTH_CLASS.TOKEN_REQUIRED,
   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 } = {}) {
@@ -25,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

@@ -2,6 +2,15 @@ export const DEFAULT_MAX_BYTES = 8192;
 export const DEFAULT_FIELD_MAX_BYTES = 512;
 export const FORGE_INGEST_MAX_BYTES_ENV = 'REMOGRAM_FORGE_INGEST_MAX_BYTES';
 
+/** Conservative check/status page size vs DEFAULT_MAX_BYTES raw ingest cap (pre-parse). */
+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 === '') {
@@ -20,6 +29,70 @@ export function forgeIngestCapabilityFacts() {
   return { forge_ingest_cap_bytes: bytes };
 }
 
+/**
+ * Structured check-list pagination facts for provider capabilities.
+ * @param {{ strategy: 'offset_limit' | 'link_header', pageSizeParam: 'limit' | 'per_page' | null, sourceCount?: number }} opts
+ */
+export function checkPaginationCapabilityFacts({ strategy, pageSizeParam, sourceCount = 1 }) {
+  const perSource = DEFAULT_CHECK_STATUS_PAGE_SIZE * MAX_CHECK_STATUS_PAGES;
+  return {
+    check_pagination: {
+      strategy,
+      page_size: DEFAULT_CHECK_STATUS_PAGE_SIZE,
+      max_pages: MAX_CHECK_STATUS_PAGES,
+      page_size_param: pageSizeParam,
+      ingest_backoff: 'halve_until_fit',
+      on_page_cap: 'set_checks_truncated',
+      compliant_max_items_per_source: perSource,
+      check_source_count: sourceCount,
+      truncation_combination:
+        sourceCount > 1 ? 'any_source_truncated' : 'single_source',
+      compliant_max_items_total: perSource * sourceCount,
+      truncation_packet_field: 'checks_truncated',
+    },
+  };
+}
+
+/** 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

@@ -0,0 +1,215 @@
+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;
+}
+
+export function withPerPageParam(url, limit) {
+  const parsed = new URL(url);
+  parsed.searchParams.set('per_page', String(limit));
+  return parsed.toString();
+}
+
+export function withLimitParam(url, limit) {
+  const parsed = new URL(url);
+  parsed.searchParams.set('limit', String(limit));
+  return parsed.toString();
+}
+
+/**
+ * Retry fetch with halved page size when raw ingest exceeds cap.
+ * @template T
+ * @param {(url: string) => Promise<T>} fetchFn
+ * @param {(limit: number) => string} buildUrl
+ * @param {number} [initialLimit]
+ */
+export async function fetchWithIngestPageBackoff(
+  fetchFn,
+  buildUrl,
+  initialLimit = DEFAULT_CHECK_STATUS_PAGE_SIZE,
+) {
+  let limit = initialLimit;
+  while (true) {
+    try {
+      return await fetchFn(buildUrl(limit));
+    } catch (err) {
+      if (isOversizedIngestError(err) && limit > 1) {
+        limit = Math.max(1, Math.floor(limit / 2));
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Fetch one offset page with ingest-cap backoff.
+ * @template T
+ * @param {(opts: { page: number, limit: number }) => Promise<unknown[]>} fetchPage
+ * @param {number} page
+ * @param {number} initialLimit
+ * @returns {Promise<{ items: unknown[], usedLimit: number }>}
+ */
+export async function fetchPageWithIngestBackoff(fetchPage, page, initialLimit) {
+  let usedLimit = initialLimit;
+  const items = await fetchWithIngestPageBackoff(
+    async (limit) => {
+      usedLimit = limit;
+      const pageItems = await fetchPage({ page, limit });
+      return Array.isArray(pageItems) ? pageItems : [];
+    },
+    (limit) => limit,
+    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
+ */
+export async function paginateCheckStatusPages({
+  fetchPage,
+  pageSize = DEFAULT_CHECK_STATUS_PAGE_SIZE,
+  maxPages = MAX_CHECK_STATUS_PAGES,
+}) {
+  const all = [];
+  let truncated = false;
+  let activeLimit = pageSize;
+  for (let page = 1; page <= maxPages; page += 1) {
+    const { items: pageItems, usedLimit } = await fetchPageWithIngestBackoff(
+      fetchPage,
+      page,
+      activeLimit,
+    );
+    activeLimit = usedLimit;
+    all.push(...pageItems);
+    if (pageItems.length < usedLimit) {
+      break;
+    }
+    if (page === maxPages) {
+      truncated = true;
+      break;
+    }
+  }
+  return { items: all, truncated };
+}
+
+/**
+ * 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, 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,
+  pageSize,
+  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;
+
+  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;
+        return true;
+      }
+    } else if (page === maxPages) {
+      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,
+    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

@@ -11,9 +11,18 @@ export const ERROR_CODES = {
   CONFIG_NOT_FOUND: 'config_not_found',
   INVALID_ARGS: 'invalid_args',
   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

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+
+import { FACT_INVENTORY_PACKET_TYPES, V1_READ_PLAN_COMMANDS } from './semantic-diff-facts.js';
+
+/** CLI/MCP surface entries observer consumers may call (read-only). */
+export const OBSERVER_REMOGRAM_COMMANDS = Object.freeze([
+  { command: 'repo status', mcp_tool: 'repo_status', read_only: true, observer_proto: true },
+  { command: 'refs inventory', mcp_tool: 'ref_inventory', read_only: true, observer_proto: false },
+  { command: 'cr inventory', mcp_tool: 'cr_inventory', read_only: true, observer_proto: false },
+  { command: 'refs compare', mcp_tool: 'ref_compare', read_only: true, observer_proto: false },
+  { command: 'pr view', mcp_tool: 'pr_status', read_only: true, observer_proto: false },
+  { command: 'pr checks', mcp_tool: 'pr_checks', read_only: true, observer_proto: false },
+  { command: 'merge plan', mcp_tool: 'merge_plan', read_only: true, observer_proto: false },
+  { command: 'sync plan', mcp_tool: 'sync_plan', read_only: true, observer_proto: false },
+  { command: 'provider capabilities', mcp_tool: 'provider_capabilities', read_only: true, observer_proto: false },
+  { command: 'doctor', mcp_tool: 'doctor', read_only: true, observer_proto: false },
+]);
+
+/** Fact inventory packet types for semantic-diff / branch-workcycle composition. */
+export const OBSERVER_FACT_INVENTORY_PACKETS = Object.freeze([
+  {
+    packet_type: FACT_INVENTORY_PACKET_TYPES.REF_INVENTORY,
+    command: 'refs inventory',
+    mcp_tool: 'ref_inventory',
+    read_only: true,
+  },
+  {
+    packet_type: FACT_INVENTORY_PACKET_TYPES.CR_INVENTORY_SLICE,
+    command: 'cr inventory',
+    mcp_tool: 'cr_inventory',
+    read_only: true,
+  },
+]);
+
+/** Commands captured directly by observer-snapshot.sh today. */
+export function observerProtoRemogramCommands() {
+  return OBSERVER_REMOGRAM_COMMANDS.filter((entry) => entry.observer_proto);
+}
+
+/** Extended fact commands for semantic-diff inventory beyond the proto script. */
+export function semanticDiffFactCommands() {
+  return OBSERVER_REMOGRAM_COMMANDS.filter((entry) => !entry.observer_proto);
+}
+
+/** All v1 read/plan commands remain authoritative alongside fact inventory. */
+export function allObserverEligibleCommands() {
+  return V1_READ_PLAN_COMMANDS.map((command) => {
+    const entry = OBSERVER_REMOGRAM_COMMANDS.find((c) => c.command === command);
+    return {
+      command,
+      mcp_tool: entry?.mcp_tool ?? null,
+      read_only: entry?.read_only ?? true,
+    };
+  });
+}