#byteor-actiongraph

byteor-actiongraph is the enterprise runtime surface for side-effecting stages. Use it when the spec needs to call an external HTTP target or launch an approved local program as part of pipeline execution.

#Action-stage resolution

ActionGraph publishes two resolver-key stage families today:

The resolver is intentionally thin glue over byteor-actions plus byteor-policy defaults. That matters operationally because the same authored stage key can lead to four different outcomes depending on environment and replay posture:

• Allow
• DryRunOnly
• RequireApproval
• Deny

For that reason, always read ActionGraph execution through the policy decision, not only through the presence of a stage key in the spec.

#Approval-aware execution

The current operator posture is conservative:

• dev may allow side effects for iteration,
• staging and prod generally require approval for side-effecting actions,
• replay should begin in dry-run mode rather than live execution.

Credential and trust lookup follow the shared enterprise conventions:

• pass a credential explicitly with --approval=...,
• or place approval.cred next to the extracted spec.kv,
• pass trusted keys with --approval-key-set=...,
• or place signing_keys.json next to the extracted spec.kv.

If BYTEOR_API_BASE_URL, BYTEOR_AGENT_ID, and BYTEOR_AGENT_API_KEY are all present, ActionGraph can refresh trusted signing keys before verification. If refresh fails, the local key cache remains the fallback path.

#Operator constraints

ActionGraph is intentionally not a free-form side-effect runner.

#http_post:*

• URLs must start with http:// or https://.
• BYTEOR_HTTP_POST_TIMEOUT overrides the default request timeout.
• BYTEOR_HTTP_POST_ALLOWLIST can restrict the permitted URL prefixes.
• BYTEOR_ACTION_MAX_RETRIES and BYTEOR_ACTION_RETRY_BASE_MS shape retry behavior for retryable failures.

#exec:*

• process execution is disabled by default,
• BYTEOR_EXEC_ALLOWLIST must name the permitted program strings exactly,
• approval and policy checks still apply even when a program is allowlisted.

These constraints are deliberate. They keep authored stage identities stable while leaving the final live-execution decision under operator control.

#Execution modes that matter in practice

• run is the normal long-running or continuous execution path.
• run --sp is the fastest way to prove one-shot bring-up with --input-hex=... or --input-ascii=....
• --dry-run is the safe first step for new side-effecting paths and for replay promotion.

The product surface also preserves the shared runtime tooling:

• doctor for host-readiness checks,
• snapshot for current runtime state,
• incident-bundle for reproducible triage export.

#Recommended operator flow

1. Start with validate and describe so the exact stage keys are reviewable.
2. Use --dry-run first for new http_post:* or exec:* deployments.
3. Confirm the approval credential, signing keys, and environment posture before enabling live side effects.
4. Keep the resulting policy audit and replay audit artifacts with the deployment or incident record.

Use policy-and-approvals.md for the shared approval model and operator-flow.md for the end-to-end operator runbook.