do_arm: arago ActionHandler contract + action-ws lifecycle parity#121
Merged
Conversation
…pping
Brings OGAR to full CONTRACT + LIFECYCLE parity with arago's HIRO ActionHandler
(the operator's "switch from Python to OGAR running it here" goal), grounded in
the real arago sources (github.com/arago/ActionHandlers config format,
python-hiro-stonebranch-actionhandler daemon, HIRO 7 Action API action-ws
protocol) + the vendored OGIT NTO/Automation ontology.
do_arm additions (string-keyed; no new codebook mint needed):
- assemble_action_handler(entities) walks the OGIT `provides` graph
(ActionHandler -> ActionApplicability -> ActionCapability) into
ActionHandlerSpec / ApplicabilitySlot / CapabilitySlot.
- ActionParam { name, mandatory, default } — the arago Parameter I/O tuple.
- Parity points proven by tests: arago ModelFilter{Var,Mode,Value} ->
KausalSpec::StateGuard (environmentFilter); Capability declares the
mandatory/optional/result param slots (resultParameters = the output sig).
docs/ARAGO-ACTIONHANDLER-PARITY.md — the scorecard:
- config+ontology contract: full parity [G] (the assembly).
- action-ws protocol <-> ActionInvocation Rubicon lifecycle: submitAction ->
ack -> execute -> sendActionResult -> ack maps onto Pending -> (commit_via:
RBAC ^ guard ^ MUL) -> Committed -> Lance-append, field-for-field.
- the switch path: an OGAR action-ws adapter replaces the Python daemon; the
only unbuilt pieces are B1 (the ExecTarget executor) and B2 (the action-ws
adapter + deployed-YAML instance lift) — glue over existing types, not new IR.
- PROBE-OGAR-ACTIONHANDLER-RUN certifies B1/B2 (replay a real arago submitAction
corpus; assert sendActionResult matches bit-for-bit).
27 do_arm tests green (4 new), clippy-clean. Ledger D-ACTIONHANDLER-PARITY;
EPIPHANIES E-ARAGO-ACTIONHANDLER-PARITY.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
The socket-free heart of the action-ws adapter (parity brick B2-core): the typed protocol messages + the submitAction -> ActionInvocation -> sendActionResult binding, no live WebSocket, no command execution. Builds on the contract parity (#121); together they make the Python->OGAR switch a transport/runner/parser job over existing types, not new IR. crates/ogar-from-schema/src/action_ws.rs: - SubmitAction / Acknowledged / SendActionResult — the typed action-ws messages (serde-gated for the wire). - acknowledge(submit) — the 200 receipt. - bind_parameters(supplied, ActionParam[]) — validates inputs against the capability signature (mandatory present, defaults filled) — the same check arago's Python handler runs before executing. - submit_to_invocation(submit, def) — builds the Pending ActionInvocation (capability->predicate match, id->idempotency_key, host->object_instance, handler/scope->lokal); rejects capability mismatch. - invocation_to_result(committed_inv, result) — only a Committed invocation (the Rubicon crossing) yields the sendActionResult. 7 new tests incl. full_action_ws_roundtrip (submit -> ack -> bind -> invoke -> commit -> result, id-correlated). 34 do_arm/action_ws tests green under default AND serde features; action_ws clippy-clean. Docs: ARAGO-ACTIONHANDLER-PARITY scorecard updated (B2-core shipped; remaining B1 executor + B2-transport live-WS + B2-lift YAML); D-ACTIONHANDLER-PARITY row. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP
…ocol core
Harvested the authoritative machine-readable contract from the HIRO 7.0 dev
portal (core.engine.datagroup.de/help/specs/definitions/{action-ws,action}.yaml)
and folded the corrections into the action-ws core, so it now matches the spec
rather than the tutorial-only first pass.
Corrections the spec forced:
- result is a SINGLE STRING (<= 1048576 chars), not an object: SendActionResult.result
is now String; invocation_to_result JSON-encodes the bound resultParameters via
a new minimal escaping json_object(); MAX_RESULT_LEN + ResultTooLarge guard.
- id is 12-256 chars: validate_id() + InvalidId.
- three missing message types added: NegativeAcknowledged {id,code,message},
ConfigChanged (re-fetch capabilities), InboundError {code,message}.
New connection facts captured (for B2-transport):
- ACTION_WS_PATH = "/api/action-ws/1.0/connect"
- auth_subprotocol(token) = "token-$TOKEN" (the sec-websocket-protocol header)
- registration is REST (GET /capabilities, /applicabilities), NOT a WS handshake;
configChanged just signals a re-fetch. The REST view lifts straight into
do_arm::assemble_action_handler's ActionHandlerSpec (the B2-lift brick).
38 do_arm/action_ws tests green (4 new: nack, validate_id, json_object escaping,
auth_subprotocol) under default AND serde features; action_ws clippy-clean.
Docs: ARAGO-ACTIONHANDLER-PARITY §2a (the full harvested contract + the
corrections) + §6 spec URLs; D-ACTIONHANDLER-PARITY row updated.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Goal
The operator's target: parity with arago's HIRO ActionHandler such that one "could basically switch from [arago's] Python to OGAR running it here." This PR scores OGAR against arago's actual implementation and closes the contract + lifecycle gap.
Grounded in the real arago sources (not just the vendored mirror):
github.com/arago/ActionHandlers(config format),arago/python-hiro-stonebranch-actionhandler(a concrete daemon), and the HIRO 7 Action APIaction-wsprotocol (the runtime contract).The three parity findings
Capability{Name,Description,Command,Parameter[]}+Applicability{ModelFilter,…}) and the OGITNTO/Automationontology (ActionHandler → provides → ActionApplicability → provides → ActionCapability) are two encodings of one shape. Newdo_arm::assemble_action_handlerwalks the vendoredprovidesgraph intoActionHandlerSpec/ApplicabilitySlot/CapabilitySlot/ActionParam— proven byassembles_the_full_action_handler_contract.ModelFilterisStateGuard. arago's node-matchModelFilter{Var,Mode,Value}maps field-for-field to OGARKausalSpec::StateGuard{guard_field,guard_values}(theenvironmentFiltercarrier).action-wslifecycle is theActionInvocationRubicon.submitAction → handler acknowledged → execute → sendActionResult → server acknowledgedmaps ontoPending → (commit_via: RBAC ∧ guard ∧ MUL) → Committed → Lance-append.timeout→state_timeout_millis,id→idempotency_key,result→resultParameters, server-ack→theCommitHookLance commit. Nothing in the protocol needs a type OGAR lacks.Verdict (
docs/ARAGO-ACTIONHANDLER-PARITY.mdscorecard)OGAR is at full contract + lifecycle parity — every config / ontology /
action-wsfield has an OGAR type, and the execution gate (commit_via<ClassRbac>) is shipped. The switch to "OGAR running it here" reduces to two glue bricks over existing types, not new IR:ExecTargetexecutor (run the Command → result;graph-flow-action's trait, still no impl).ActionDef/ActionParaminstance lift.Certified by
PROBE-OGAR-ACTIONHANDLER-RUN: replay a real aragosubmitActioncorpus through the adapter + executor; assertsendActionResultmatches the Python handler's recorded result bit-for-bit.Discipline
action_capability/intent/automation_issuestay reserved in the codebook — the assembly is string-keyed and doesn't resolve them byu16; they mint when B1 needs classid resolution (the "mint only what code uses" rule).Tests
27
do_armtests green (4 new: the contract assembly, the no-handler case, theActionParamtuple), clippy-clean. LedgerD-ACTIONHANDLER-PARITY; boardE-ARAGO-ACTIONHANDLER-PARITY.🤖 Generated with Claude Code
Generated by Claude Code