gnomonlearn
Docs/Workflow contract decision

Workflow contract decision

Versioned draft snapshot

RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.

Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.

This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.

Status: proposed. Owner: Runtime, AI, and specification maintainers. The authored RFC, Lean catalog, and implementation remain unchanged.

Source conflicts

RFC-0022 §3.1 permits procedure, event, and manual triggers, while §9 M22214 says a trigger must reference a procedure. Section 8 authorizes the principal against the trigger’s underlying action without defining what that means for an event or manual trigger.

Section 6 requires compensate <step> to invoke a sequential step only after failure. The only sequential-step syntax is inside the normal steps: list, which executes in order. Thus the same declaration is either run normally or unreachable as a compensation-only step.

Sections 4.3, 9, and 11 make M22203 a warning when a subsequent step requires a variable supplied in only one branch. Sections 5 and 10 nevertheless promise that all bindings resolve and no validated workflow encounters a data-flow error. A reachable path with no value contradicts that promise.

Section 6 applies the workflow-level policy after step-level retries are exhausted. Both policies may be retry N; no exhaustion continuation or reapplication bound is defined for the workflow policy. Section 10 promises a finite upper bound on dispatched steps.

  1. Preserve all three trigger forms and define their entry contracts separately. A procedure trigger inherits that procedure’s authorization and typed input. An event trigger requires a declared event schema and a runtime subscription principal with scope to observe it. A manual trigger has an explicit callable entry permission and typed input. M22214 rejects a direct action trigger; M22210 should check a missing declaration of the selected trigger kind rather than only an action. Keep trigger provenance in the workflow.started event.
  2. Add compensations: as a separate named-step block outside normal steps:. A compensation target is type-checked at compile time against the data available on its failure path and runs only when referenced by a failing step. Apply the same agent authorization, bounded retry, and event rules as ordinary steps. Define ordering and failure behavior for multiple eligible compensations.
  3. Make M22203 an error when a required downstream binding is absent on any reachable branch. An author can provide a value on every branch, an explicit default, or a branch-local consumer. A merely unused conditional output may remain a warning under a separate, clearly advisory diagnostic.
  4. Count each retry N as at most N additional dispatches. After step retries, apply a workflow-level retry N to that failure at most once; exhaustion terminates with fail. Retry only the failed step, preserving completed steps and their bindings; do not restart the entire workflow. Reject a policy chain that could reapply itself.

Concrete retry budget

For one failed step occurrence, including one iteration of a repeat loop:

Effective policiesMaximum agent dispatches for that occurrence
Local retry L, default retry W1 + L + W
Local retry L, no default retry1 + L
No local policy, default retry W1 + W

The initial dispatch is counted once. A default retry budget is consumed once for that occurrence, whether inherited initially or reached after local retries. Its exhaustion terminates with fail; it never re-enters the local or default retry policy. A successful retry binds outputs once and resumes normal flow. Retries do not repeat already completed predecessor steps. An explicit local fail, continue, or compensate remains the selected policy and does not implicitly consume the default retry budget.

The scheduler must preserve consumed budgets across recovery so a process restart cannot reset the dispatch bound. Execution records crossing storage or process boundaries should use protobuf under repository instructions. This proposal does not establish exactly-once external agent side effects; retries still require the agent’s applicable idempotency contract.

This refines the pending owner decision, without changing normative source. The completed claim review also identifies an independent terminal-event gap after continue; accepting retry budgets does not resolve that gap.

Acceptance

  • Amend RFC-0022 prose, grammar, examples, diagnostics, and Lean catalog in one change; regenerate the reference and RDF projections and pass drift checks.
  • Compile and execute one example per trigger form, including denied access and missing schema cases. Verify the event log retains the principal and trigger source.
  • Test compensation-only steps never run on a successful path; exercise failure paths, multiple compensations, authorization, and compensation failure. Test conditional data flow across both branches and a missing-value rejection. Prove a finite dispatch bound for nested loops and both retry levels, then test the bound at runtime. Inject failure into every attempt of local retry 2 plus default retry 3 and require exactly six dispatches; default-only retry 3 must stop after four. Recover after budget consumption and verify the count cannot reset. Verify a successful predecessor runs once and output bindings are published only after a successful attempt.
  • Inventory existing workflow syntax and diagnostic consumers before changing public grammar or M222xx behavior. No Gnomon deployment exists, per the owner; align staging sources and consumers directly without a deployment migration.