[MACHINE-SPIRIT 4/8] Zara capability bridge — Prolog executes task effects through canonical tools #329

New issue

Open

opened 2026-09-08 02:03:33 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 02:03:33 +00:00

Owner

Parent epic: #636
Depends on: #639
Related Core authority/cancellation work: #388, #400

Goal

Make the answer to "can Prolog execute tasks?" concretely yes — without giving Prolog arbitrary host execution.

MACHINE-SPIRIT should own task decisions and request typed effects from Prolog. Every real side effect must cross a narrow Zara host bridge into the existing principal-scoped tool/capability/approval path.

Authority model

MACHINE-SPIRIT validated plan
  -> Prolog-RLM rlm_tool registry/capability check
  -> typed effect request {tool, args, task/run metadata}
  -> Zara MACHINE-SPIRIT host adapter
  -> exact principal's canonical ToolRegistry
  -> existing ToolApprovalController / policy
  -> canonical tool invocation
  -> bounded typed observation returned to Prolog

Prolog-RLM authority is a second narrowing layer. A Prolog capability set may remove authority Zara would otherwise grant; it can never invent or widen Zara authority.

Zara remains final authority for:

principal identity;
current tool registration/generation;
argument schema;
approval requirements;
plugin lifecycle;
cancellation;
effect execution.

Bridge requirements

Register only explicitly selected host tools into the MACHINE-SPIRIT/Prolog-RLM tool registry.
Discovery exposes schemas/capabilities, never Python tool objects or executable closures to model data.
Tool names and arguments are closed structured values.
Every invocation is bound to exact principal + task/run + current registry generation.
Unknown/stale/removed tools fail closed.
Tool output is size bounded before becoming an observation.
Effect status is typed: success / denied / approval_required-or-pending / rejected / cancelled / timeout / invalid_args / unavailable / failed.
No arbitrary shell tool is added for MACHINE-SPIRIT.
No endpoint accepts an arbitrary Prolog goal, Python callable, module path, shell command, or model-defined handler.
Plugin-backed long-running cancellation must converge on #388; no parallel cancellation token/control plane.
Plugin-to-plugin composition, where needed later, consumes #400 rather than importing private plugin internals.

Initial executable fixture

Prove at least one bounded multi-step task in which Prolog itself selects and sequences two safe fixture capabilities, for example:

read_fixture -> transform_fixture -> final evidence

Then prove one real current Zara read-only capability through the same bridge. Mutation-capable tools must be acceptance-tested with approval and denial before being considered supported.

Adversarial TDD — RED first

Mandatory deterministic attacks:

model supplies call(...), system(...), shell text, module-qualified arbitrary goal, or serialized callable as args -> rejected as data;
unregistered tool name -> denied;
forged tool registration/generation -> denied;
stale capability after unload/reload -> denied;
capability requested by child but absent from parent -> denied;
cross-principal task attempts another principal's tool/approval context -> denied;
copied/transferred opaque handle -> denied;
malformed/extra/missing args -> denied before effect;
approval-required mutation cannot execute before approval;
approval rejection produces no effect;
approval timeout produces no effect;
tool throws/crashes -> typed failure, executive survives;
huge tool output is bounded;
cancellation race cancels exact invocation and cannot retarget another invocation;
concurrent task invocations remain isolated;
trace/log output excludes secrets and full sensitive payloads.

Where #388/#400 are not yet canonical, write RED acceptance and either use only capabilities that do not require the missing seam or keep that acceptance blocked. Do not emulate the missing Core contract inside MACHINE-SPIRIT.

Acceptance

Prolog can choose and execute a finite multi-step task through typed registered capabilities.
All actual effects cross the existing Zara canonical execution/approval path.
Prolog/model data can never become unrestricted callable host code.
Capability narrowing is proven; widening is deterministically denied.
Principal/task/invocation binding is proven under concurrency.
Approval, rejection, failure, timeout, and cancellation are distinct typed observations.
At least one current Zara read-only capability works end-to-end.
Mutation fixture proves no pre-approval side effect.
Adversarial capability suite is green.
Generic machine_spirit_* code contains only a host-interface abstraction; Zara-specific bridge lives in Zara adapter code.

Non-goals

No generic bash capability, no arbitrary Prolog evaluator, no root/privilege escalation, no bypass of approval, no second plugin execution manager.

Parent epic: #636 Depends on: #639 Related Core authority/cancellation work: #388, #400 ## Goal Make the answer to **"can Prolog execute tasks?"** concretely yes — without giving Prolog arbitrary host execution. MACHINE-SPIRIT should own task decisions and request typed effects from Prolog. Every real side effect must cross a narrow Zara host bridge into the existing principal-scoped tool/capability/approval path. ## Authority model ```text MACHINE-SPIRIT validated plan -> Prolog-RLM rlm_tool registry/capability check -> typed effect request {tool, args, task/run metadata} -> Zara MACHINE-SPIRIT host adapter -> exact principal's canonical ToolRegistry -> existing ToolApprovalController / policy -> canonical tool invocation -> bounded typed observation returned to Prolog ``` Prolog-RLM authority is a **second narrowing layer**. A Prolog capability set may remove authority Zara would otherwise grant; it can never invent or widen Zara authority. Zara remains final authority for: - principal identity; - current tool registration/generation; - argument schema; - approval requirements; - plugin lifecycle; - cancellation; - effect execution. ## Bridge requirements - Register only explicitly selected host tools into the MACHINE-SPIRIT/Prolog-RLM tool registry. - Discovery exposes schemas/capabilities, never Python tool objects or executable closures to model data. - Tool names and arguments are closed structured values. - Every invocation is bound to exact principal + task/run + current registry generation. - Unknown/stale/removed tools fail closed. - Tool output is size bounded before becoming an observation. - Effect status is typed: success / denied / approval_required-or-pending / rejected / cancelled / timeout / invalid_args / unavailable / failed. - No arbitrary shell tool is added for MACHINE-SPIRIT. - No endpoint accepts an arbitrary Prolog goal, Python callable, module path, shell command, or model-defined handler. - Plugin-backed long-running cancellation must converge on #388; no parallel cancellation token/control plane. - Plugin-to-plugin composition, where needed later, consumes #400 rather than importing private plugin internals. ## Initial executable fixture Prove at least one bounded multi-step task in which Prolog itself selects and sequences two safe fixture capabilities, for example: ```text read_fixture -> transform_fixture -> final evidence ``` Then prove one real current Zara read-only capability through the same bridge. Mutation-capable tools must be acceptance-tested with approval and denial before being considered supported. ## Adversarial TDD — RED first Mandatory deterministic attacks: - model supplies `call(...)`, `system(...)`, shell text, module-qualified arbitrary goal, or serialized callable as args -> rejected as data; - unregistered tool name -> denied; - forged tool registration/generation -> denied; - stale capability after unload/reload -> denied; - capability requested by child but absent from parent -> denied; - cross-principal task attempts another principal's tool/approval context -> denied; - copied/transferred opaque handle -> denied; - malformed/extra/missing args -> denied before effect; - approval-required mutation cannot execute before approval; - approval rejection produces no effect; - approval timeout produces no effect; - tool throws/crashes -> typed failure, executive survives; - huge tool output is bounded; - cancellation race cancels exact invocation and cannot retarget another invocation; - concurrent task invocations remain isolated; - trace/log output excludes secrets and full sensitive payloads. Where #388/#400 are not yet canonical, write RED acceptance and either use only capabilities that do not require the missing seam or keep that acceptance blocked. Do not emulate the missing Core contract inside MACHINE-SPIRIT. ## Acceptance - [ ] Prolog can choose and execute a finite multi-step task through typed registered capabilities. - [ ] All actual effects cross the existing Zara canonical execution/approval path. - [ ] Prolog/model data can never become unrestricted callable host code. - [ ] Capability narrowing is proven; widening is deterministically denied. - [ ] Principal/task/invocation binding is proven under concurrency. - [ ] Approval, rejection, failure, timeout, and cancellation are distinct typed observations. - [ ] At least one current Zara read-only capability works end-to-end. - [ ] Mutation fixture proves no pre-approval side effect. - [ ] Adversarial capability suite is green. - [ ] Generic `machine_spirit_*` code contains only a host-interface abstraction; Zara-specific bridge lives in Zara adapter code. ## Non-goals No generic bash capability, no arbitrary Prolog evaluator, no root/privilege escalation, no bypass of approval, no second plugin execution manager.