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

package/auth-classes.js

@@ -17,6 +17,13 @@ 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,
+  status_set: AUTH_CLASS.TOKEN_REQUIRED,
+  whoami: AUTH_CLASS.TOKEN_REQUIRED,
+  branch_protection: AUTH_CLASS.TOKEN_REQUIRED,
+  cr_files: AUTH_CLASS.TOKEN_REQUIRED,
+  cr_comments: AUTH_CLASS.TOKEN_REQUIRED,
+  forge_changes: AUTH_CLASS.TOKEN_REQUIRED,
 };
 
 export function commandCapability(name, { implemented = true } = {}) {
@@ -27,10 +34,24 @@ 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,
+  statusSetImplemented = false,
+  branchProtectionImplemented = false,
+  crFilesImplemented = false,
+  crCommentsImplemented = false,
+  forgeChangesImplemented = false,
+} = {}) {
+  return Object.keys(API_PROVIDER_COMMAND_AUTH).map((name) => {
+    let implemented = true;
+    if (name === 'cr_open') implemented = writeCommandsImplemented;
+    if (name === 'status_set') implemented = statusSetImplemented;
+    if (name === 'branch_protection') implemented = branchProtectionImplemented;
+    if (name === 'cr_files') implemented = crFilesImplemented;
+    if (name === 'cr_comments') implemented = crCommentsImplemented;
+    if (name === 'forge_changes') implemented = forgeChangesImplemented;
+    return commandCapability(name, { implemented });
+  });
 }
 
 export function stubProviderCommands() {

package/branch-protection.js

@@ -0,0 +1,155 @@
+import { sanitizeField } from './caps.js';
+
+export const MAX_BRANCH_PROTECTION_STATUS_CONTEXTS = 64;
+export const MAX_BRANCH_PROTECTION_RULES = 32;
+
+/** Gitea exposes required_approvals on branch protection; omit when unavailable. */
+export function unimplementedApprovalsRequiredSignal() {
+  return { implemented: false, count: null };
+}
+
+function sanitizeStringList(values, maxItems) {
+  if (!Array.isArray(values)) return [];
+  const out = [];
+  for (const value of values) {
+    if (out.length >= maxItems) break;
+    const sanitized = sanitizeField(value);
+    if (sanitized) out.push(sanitized);
+  }
+  return out;
+}
+
+function normalizeApprovalsRequired(signal) {
+  if (signal == null || typeof signal !== 'object') {
+    return unimplementedApprovalsRequiredSignal();
+  }
+  if (signal.implemented === false) {
+    return { implemented: false, count: null };
+  }
+  if (signal.implemented === true) {
+    if (signal.count == null) {
+      return { implemented: true, count: null };
+    }
+    const count = Number(signal.count);
+    if (!Number.isFinite(count) || count < 0) {
+      return { implemented: true, count: null };
+    }
+    return { implemented: true, count: Math.floor(count) };
+  }
+  return unimplementedApprovalsRequiredSignal();
+}
+
+export function buildBranchProtectionBody({
+  branch_ref,
+  required_status_contexts,
+  protected_branch_rules,
+  approvals_required,
+}) {
+  const rules = (Array.isArray(protected_branch_rules) ? protected_branch_rules : [])
+    .slice(0, MAX_BRANCH_PROTECTION_RULES)
+    .map((rule) => {
+      const name =
+        rule != null && typeof rule === 'object'
+          ? sanitizeField(rule.name)
+          : sanitizeField(rule);
+      return name ? { name } : null;
+    })
+    .filter(Boolean);
+
+  return {
+    branch_ref: sanitizeField(branch_ref),
+    required_status_contexts: sanitizeStringList(
+      required_status_contexts,
+      MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
+    ),
+    protected_branch_rules: rules,
+    approvals_required: normalizeApprovalsRequired(approvals_required),
+  };
+}
+
+export function buildBranchProtectionFromGitLabProtection(
+  branchRef,
+  { protectedBranch = null, approvalRules = [] } = {},
+) {
+  if (protectedBranch == null) {
+    return buildBranchProtectionBody({
+      branch_ref: branchRef,
+      required_status_contexts: [],
+      protected_branch_rules: [],
+      approvals_required: unimplementedApprovalsRequiredSignal(),
+    });
+  }
+  const ruleName = sanitizeField(protectedBranch.name ?? branchRef);
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  if (Array.isArray(approvalRules) && approvalRules.length > 0) {
+    const counts = approvalRules
+      .map((rule) => Number(rule.approvals_required))
+      .filter((count) => Number.isFinite(count) && count >= 0);
+    if (counts.length > 0) {
+      approvals_required = { implemented: true, count: Math.max(...counts) };
+    }
+  }
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts: [],
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}
+
+export function buildBranchProtectionFromGitHubProtection(branchRef, protectionPayload) {
+  if (protectionPayload == null) {
+    return buildBranchProtectionBody({
+      branch_ref: branchRef,
+      required_status_contexts: [],
+      protected_branch_rules: [],
+      approvals_required: unimplementedApprovalsRequiredSignal(),
+    });
+  }
+  const payload =
+    protectionPayload != null && typeof protectionPayload === 'object' ? protectionPayload : {};
+  const required_status_contexts = sanitizeStringList(
+    payload.required_status_checks?.contexts,
+    MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
+  );
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  const reviews = payload.required_pull_request_reviews;
+  if (reviews != null && typeof reviews === 'object' && 'required_approving_review_count' in reviews) {
+    const count = Number(reviews.required_approving_review_count);
+    if (Number.isFinite(count) && count >= 0) {
+      approvals_required = { implemented: true, count: Math.floor(count) };
+    }
+  }
+  const ruleName = sanitizeField(branchRef);
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts,
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}
+
+export function buildBranchProtectionFromGiteaProtection(branchRef, protectionPayload) {
+  const payload =
+    protectionPayload != null && typeof protectionPayload === 'object' ? protectionPayload : {};
+  const ruleName = sanitizeField(payload.branch_name ?? payload.rule_name ?? branchRef);
+  const required_status_contexts =
+    payload.enable_status_check === false
+      ? []
+      : sanitizeStringList(payload.status_check_contexts, MAX_BRANCH_PROTECTION_STATUS_CONTEXTS);
+
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  if ('required_approvals' in payload) {
+    const count = Number(payload.required_approvals);
+    if (Number.isFinite(count) && count >= 0) {
+      approvals_required = { implemented: true, count: Math.floor(count) };
+    }
+  }
+
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts,
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}

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,57 @@ 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',
+    },
+  };
+}
+
+/** Idempotency scan facts for status set (commit-status list pagination). */
+export function statusSetIdempotencyScanCapabilityFacts() {
+  return {
+    idempotency_scan: {
+      max_pages: MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
+      page_size: DEFAULT_CHECK_STATUS_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');
@@ -75,6 +131,8 @@ function redactSecretPatterns(text) {
     .replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]')
     .replace(/\bghp_[A-Za-z0-9]+\b/g, '[REDACTED]')
     .replace(/\bgho_[A-Za-z0-9]+\b/g, '[REDACTED]')
+    .replace(/\bghs_[A-Za-z0-9._-]{36,}/g, '[REDACTED]')
+    .replace(/\bghs_[A-Za-z0-9_-]+\b/g, '[REDACTED]')
     .replace(/\bglpat-[A-Za-z0-9_-]+\b/g, '[REDACTED]')
     .replace(/\b(GITHUB_TOKEN|GH_TOKEN|GITLAB_TOKEN|GITEA_TOKEN)\b/gi, '[REDACTED]');
 }

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,13 @@ export const PACKET_TYPES = {
   PROVIDER_CAPABILITIES: 'provider_capabilities',
   PROVIDER_DOCTOR: 'provider_doctor',
   FORGE_ERROR: 'forge_error',
+  CHANGE_REQUEST_OPENED: 'change_request_opened',
+  COMMIT_STATUS_SET: 'commit_status_set',
+  PROVIDER_IDENTITY: 'provider_identity',
+  BRANCH_PROTECTION: 'branch_protection',
+  CR_FILES: 'cr_files',
+  CR_COMMENTS: 'cr_comments',
+  FORGE_CHANGES: 'forge_changes',
 };
 
 export const FORBIDDEN_PACKET_KEYS = new Set([
@@ -29,7 +37,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 +61,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';
@@ -21,6 +18,11 @@ export const OBSERVER_REMOGRAM_COMMANDS = Object.freeze([
   { 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 },
+  { command: 'whoami', mcp_tool: 'whoami', read_only: true, observer_proto: false },
+  { command: 'branch protection', mcp_tool: 'branch_protection', read_only: true, observer_proto: false },
+  { command: 'cr files', mcp_tool: 'cr_files', read_only: true, observer_proto: false },
+  { command: 'cr comments', mcp_tool: 'cr_comments', read_only: true, observer_proto: false },
+  { command: 'forge changes', mcp_tool: 'forge_changes', read_only: true, observer_proto: false },
 ]);
 
 /** Fact inventory packet types for semantic-diff / branch-workcycle composition. */