Skip to content

feat(engine): bind approvals to artifacts and gate verification nodes - #1070

Open
chenhonggang0623-sketch wants to merge 2 commits into
Tencent:mainfrom
chenhonggang0623-sketch:feat/approval-binding-upstream
Open

chenhonggang0623-sketch wants to merge 2 commits into
Tencent:mainfrom
chenhonggang0623-sketch:feat/approval-binding-upstream

Conversation

@chenhonggang0623-sketch

Copy link
Copy Markdown

Motivation

Two human-control conventions were not engine guarantees:

  1. POST /api/runs/{id}/approve could be recorded against a run state the operator never saw. A stale workbench card, or an artifact that changed between rendering and clicking, still approved something.
  2. POST /api/runs/{id}/pass could mark any failed script node as succeeded. A node that exists to verify the change could be bypassed with no trace of who did it.

This change binds a human decision to the artifact it reviewed and makes verification nodes refuse /pass without an explicit, audited override.

What changes

  • engine.NodeExpectation / the HTTP expected object gain artifactName and artifactSha256. Approval checks the newest artifact with that name (by creation time) still carries that hash. A mismatch returns 409, appends gate.approval_rejected with expected/actual values, and leaves the node in waiting_approval. Half a binding (name without hash or vice versa) is 400.
  • WorkflowNode.requires supports artifact:<name>@<sha256> and verdict:<PASS|FAIL>@<diffHash>. An unmet precondition fails the node with the expected and actual values instead of silently skipping it; the check is deferred while a sibling is still in flight.
  • WorkflowNode.verificationStep makes /pass return 409 and audit node.pass_rejected; override: true passes it and audits node.passed_override with the operator (server-resolved; anonymous is recorded as such).
  • Docs and OpenAPI updated; engine and HTTP tests cover all three.

Compatibility

  • A stale expected (status/attempt/rework mismatch) now returns 409 instead of 400. Same meaning — the decision is stale — and no in-repo client branches on 400 for these endpoints.
  • The marker is named verificationStep rather than verification because verification is the removed legacy gate-array field the API strips on save; reusing it breaks that normalization.
  • Requests without expected behave exactly as before.

Tests

  • internal/engine/gate_binding_test.go, node_requires_test.go, pass_override_test.go
  • internal/httpapi/gate_binding_http_test.go
  • Verified on a local dev stack through the real API: stale approval 409 + audit row, bound approval completes the run, /pass refuses a verification node and override records operator=admin.

This PR intentionally contains no sidecar or AegisOS integration code.

🤖 Generated with Claude Code

陈洪刚 and others added 2 commits November 18, 2026 23:13
An approval could be recorded against a node that had moved on, and
/pass could mark any failed script node as succeeded. Both conventions
now have engine enforcement.

- NodeExpectation gains artifactName/artifactSha256; approval verifies
  the newest artifact of that name still carries that hash, returns 409
  on a stale decision, and writes gate.approval_rejected with expected
  and actual values.
- WorkflowNode.requires supports artifact:<name>@<sha256> and
  verdict:<PASS|FAIL>@<diffHash>; an unmet precondition fails the node
  with both values instead of silently skipping it.
- WorkflowNode.verificationStep makes /pass refuse the node unless the
  request carries override:true; both outcomes are audited with the
  operator. The JSON name avoids the removed legacy `verification`
  gate-array field that the API strips on save.
- Docs and OpenAPI updated; new engine and HTTP tests cover all three.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Review fixes for the approval-binding change:

- Half an artifact binding (name without hash or hash without name) is
  now a 400, not a silently unbound approval.
- The rejection audit releases only the lease it acquired and never a
  worker's live lease, and writes with the revision guard, re-applying
  the event to the newest snapshot on conflict.
- Artifact recency is creation time, not attempt number: attempts are
  per node, so cross-node attempt comparison picked the wrong artifact.
- A requires check is deferred while a sibling is still in flight, so a
  parallel producer cannot cause a spurious permanent failure.
- The SOP overlay carries requires/verificationStep on retry.
- Docs/OpenAPI: expected fan-out, half-binding rule, run-global artifact
  names, verdict case/whitespace, basename, parallel-producer rule, and
  the scope of /pass versus /approve on a verification step.

Co-Authored-By: Claude Code <noreply@anthropic.com>
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