Skip to content

feat: add deterministic operation catalog foundation - #325

Draft
Joncallim wants to merge 1 commit into
agent/normalize-execution-outcomesfrom
codex/issue-201-operation-catalog
Draft

feat: add deterministic operation catalog foundation#325
Joncallim wants to merge 1 commit into
agent/normalize-execution-outcomesfrom
codex/issue-201-operation-catalog

Conversation

@Joncallim

Copy link
Copy Markdown
Owner

Summary

Part of #201.

This draft adds the first bounded foundation for Forge's deterministic Operation Catalog:

  • a strict, versioned operation request and code-owned catalog;
  • three fixed read-only operations: repository status, diff summary, and current branch;
  • authoritative task, project, work-package, filesystem-grant, and repository-root checks;
  • audited argv-based Git execution with cancellation and deterministic verification;
  • a PostgreSQL operation ledger with ordered append-only phase events, idempotent replay, canonical outcomes, and tamper fingerprints;
  • ADR 0011 and unit, security-regression, migration, privilege, and hosted PostgreSQL behavior tests.

Safety boundaries

  • Model output cannot supply a path, working directory, command, argv, adapter, server, or tool name.
  • Repository reads require a current approved/running task and an always_allow filesystem.project.read grant. allow_once fails closed because this slice does not atomically consume it.
  • Git diff uses --no-ext-diff --no-textconv; a malicious textconv regression proves repository configuration cannot execute a helper.
  • Failed, cancelled, and timed-out commands retain bounded command-audit evidence without copying raw output into the operation ledger.
  • This slice does not add writes, arbitrary shell, GitHub/MCP mutation, project-local registrations, autonomy promotion, or retry automation.

Validation

  • Full unit suite: 1,993 passed; 42 skipped locally.
  • Full ESLint: passed.
  • TypeScript and production build: passed after temporarily excluding and restoring the checkout's duplicate generated node_modules/@types/* 2 folders.
  • Focused Security/Adversarial review: no blockers in this draft-foundation scope.
  • Orthogonal Review: no blockers in this draft-foundation scope.
  • Migration journal parity: 31 SQL migrations / 31 journal entries; latest 0030_operation_runs.
  • Hosted PostgreSQL 16 ledger proof is mandatory and non-skippable in Web CI; it could not run locally without the disposable CI database.

Stack and follow-ons

This is a stacked draft targeting agent/normalize-execution-outcomes (draft PR #324), because the ledger consumes #324's canonical execution-outcome contract.

This PR intentionally does not close #201. Follow-ons before full issue closure include:

  • connecting executeTrustedOperation to the normal task/model worker path;
  • fenced stale-run lease and recovery;
  • independent Workforce verification and autonomy integration;
  • MCP-health integration after its dependency chain supports real cancellation;
  • stronger filesystem containment before broader reads or any write operation.

After #324 is corrected and merged, this branch should be retargeted to main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant