nsaspy/prolog-rlm

Fork 0

[EPIC][experts] Canonical expert runtime: contract, registry, symbolic selection, invocation, recursion, and projections #421

New issue

Open

opened 2026-09-08 01:29:22 +00:00 by nsaspy · 7 comments

nsaspy commented

2026-09-08 01:29:22 +00:00

Owner

Parent: #376

Goal

Implement the reusable runtime substrate that makes a Prolog expert a first-class, inspectable, callable capability without creating another agent framework.

This epic owns the generic expert machinery only. Specialist domain logic belongs in sibling expert epics.

Core invariants

Experts are free local computation

Pure expert invocation, including expert→expert nesting, must perform zero provider calls and add zero model-token/cost usage.

Metering begins only when an expert explicitly invokes a metered dependency such as an LLM fallback or paid external API. That dependency's usage is recorded normally and linked to the expert invocation.

Runtime safety limits still apply: wall time, inference/work bound, recursion depth, output size, concurrency, cancellation and capability/authority ceilings.

One runtime path

Do not create separate plan experts, direct experts, chat experts or AgentProlog experts.

plan/workflow caller ─┐
direct/native caller ─┼─> canonical expert registry/invocation
host/API caller ──────┘

D6-11 exclusion

The plan-native set from #355 is excluded from expert mapping:

sync_remote/1
run/1
index/1
delete/1

edit/2 and create/2 remain valid expert-owned reasoning goals and will be owned by the Write Expert epic.

Public contract direction

Provide semantics equivalent to:

expert_registry_create(+Options, -Registry).
expert_register(+Registry, +Contract, -Outcome).
expert_unregister(+Registry, +ExpertId, -Outcome).
expert_catalog(+Registry, -Catalog).
expert_lookup(+Registry, +ExpertId, -Outcome).

expert_applicable(+Registry, +Goal, +Context, -Candidates).
expert_select(+Registry, +Goal, +Context, -Decision).
expert_invoke(+Registry, +ExpertId, +Goal, +Context, -Outcome).
expert_call(+Registry, +Goal, +Context, -Outcome).

expert_explain(+DecisionOrInvocation, -Explanation).

Exact names/arity should follow repository conventions.

Contract schema

A registered expert needs stable normalized metadata roughly equivalent to:

expert_contract{
    id: ExpertId,
    version: Version,
    accepts: GoalSchema,
    produces: ResultSchema,
    specialties: Specialties,
    applicability: ApplicabilityRef,
    requires: RequiredCapabilities,
    observations: RequiredObservations,
    effects: PossibleEffects,
    fallback: FallbackPolicy,
    child_policy: ChildPolicy,
    limits: Limits,
    handler: TrustedHandler
}.

The model-visible/inspection catalog exposes sanitized metadata and schemas, never arbitrary callable closures.

Generated/model/project data cannot register executable expert handlers unless it crosses an existing explicit trusted extension/config boundary.

Symbolic applicability and selection

Selection must be possible without an LLM.

Support deterministic rule/fact/constraint inputs such as:

goal shape/type;
current project/source facts;
available evidence;
required capability availability;
expert preconditions;
specialization priority/specificity;
confidence or certainty class;
explicit host preference;
exclusions/conflicts;
fallback chain.

The selection outcome should preserve all considered candidates plus a structured reason for the chosen expert or why no expert was eligible.

Do not silently ask a model to choose when symbolic selection yields no valid candidate.

Invocation lifecycle

Normalize a canonical invocation record with stable identity and state transitions equivalent to:

created
validated
selected
running
waiting_child
waiting_tool
succeeded
failed
unknown
blocked
cancelled
error

Preserve parent/child lineage, run/session identity, expert/version identity, relevant context snapshot identity, capabilities and evidence refs.

Expert→expert calls

Nested calls use the same registry and invocation machinery.

Required semantics:

depth and aggregate work bounds;
cycle/repeated-subgoal detection;
cancellation propagation;
child capability ceiling never exceeds parent/host ceiling;
child results/evidence are attached to parent lineage;
no separate scheduler;
no model charge merely because nesting occurred.

Use existing graph/async primitives where latency/concurrency requires them.

Tool/capability integration

An expert is reasoning, not ambient authority.

If an expert needs a tool it must use the existing typed registry/capability/authority/effect boundary. Registration or selection does not grant tool capability.

Preflight should be able to distinguish:

expert unavailable
expert not applicable
required capability unavailable
capability not granted
authority denied
runtime/effect failure

Explicit fallback boundary

Implement a generic fallback hook/policy that specialist experts may opt into.

A fallback event records at least:

expert invocation id
fallback reason
fallback class
provider/model request lineage if model-backed
usage/cost from the metered dependency
validated fallback output/result

Fallback must never replace the primary expert handler or make every expert secretly model-backed.

Direct/native projection

Replace/supersede the useful intent of #353 with a canonical adapter over the expert registry.

A direct-mode model may be shown selected expert capabilities as native callable tools only when host policy chooses to project them. Projection is availability, not authority. Invocation re-enters expert_invoke and the normal capability/tool boundaries.

Do not create a fourth native binding family if the existing registry/native tool path can adapt the expert contract cleanly.

Important correction from older research: the expert invocation itself is not token/cost charged. If an expert internally uses a model fallback, only that fallback's real provider usage is charged.

Plan/workflow projection

#288 plan graph routing should be able to bind typed expert-owned operations to expert ids/contracts during preflight or execution without embedding trusted closures in model-authored plan data.

The graph remains the scheduler. Expert selection does not become a second scheduler.

Observability / explanation

Expose bounded structured inspection for:

registered experts;
applicability candidates;
selection decision;
parent/child lineage;
evidence consumed/produced;
tool calls/effects invoked;
fallback events;
stop/failure reason;
local work counters separately from provider usage.

Deterministic acceptance

Register two pure Prolog experts and select correctly from goal facts with model_calls = 0.
Nested expert call remains model_calls = 0 and $0 while preserving parent/child lineage.
Expert selection is deterministic for a fixed registry/context.
Equal-priority ambiguity returns a structured ambiguity unless policy defines a deterministic tie-break.
Missing capability fails before underlying tool dispatch.
Registration does not grant capabilities/authority.
Child cannot widen parent capability ceiling.
Recursion cycle/no-progress loop terminates structurally.
Cancellation stops child and prevents subsequent tool/effect dispatch.
D6-11 native ops cannot be registered/mapped as experts in the plan expert map.
edit/2 and create/2 can be mapped to the Write Expert once that expert is registered.
Direct projection and plan routing invoke the same expert implementation.
Explicit model fallback records provider usage while the surrounding pure expert invocations remain uncharged.
Catalog/trace output never exposes trusted callable terms or secrets.

Non-goals

No domain-specific Git/write/project/verify rules here.
No product-specific AgentProlog tools or UI.
No new scheduler, effect ledger, capability system or provider runtime.

Refs #376 #141 #288 #355 #353 #354

Parent: #376 ## Goal Implement the reusable runtime substrate that makes a Prolog expert a first-class, inspectable, callable capability without creating another agent framework. This epic owns the **generic expert machinery only**. Specialist domain logic belongs in sibling expert epics. ## Core invariants ### Experts are free local computation Pure expert invocation, including expert→expert nesting, must perform **zero provider calls** and add **zero model-token/cost usage**. Metering begins only when an expert explicitly invokes a metered dependency such as an LLM fallback or paid external API. That dependency's usage is recorded normally and linked to the expert invocation. Runtime safety limits still apply: wall time, inference/work bound, recursion depth, output size, concurrency, cancellation and capability/authority ceilings. ### One runtime path Do not create separate plan experts, direct experts, chat experts or AgentProlog experts. ```text plan/workflow caller ─┐ direct/native caller ─┼─> canonical expert registry/invocation host/API caller ──────┘ ``` ### D6-11 exclusion The plan-native set from #355 is excluded from expert mapping: ```text sync_remote/1 run/1 index/1 delete/1 ``` `edit/2` and `create/2` remain valid expert-owned reasoning goals and will be owned by the Write Expert epic. ## Public contract direction Provide semantics equivalent to: ```prolog expert_registry_create(+Options, -Registry). expert_register(+Registry, +Contract, -Outcome). expert_unregister(+Registry, +ExpertId, -Outcome). expert_catalog(+Registry, -Catalog). expert_lookup(+Registry, +ExpertId, -Outcome). expert_applicable(+Registry, +Goal, +Context, -Candidates). expert_select(+Registry, +Goal, +Context, -Decision). expert_invoke(+Registry, +ExpertId, +Goal, +Context, -Outcome). expert_call(+Registry, +Goal, +Context, -Outcome). expert_explain(+DecisionOrInvocation, -Explanation). ``` Exact names/arity should follow repository conventions. ## Contract schema A registered expert needs stable normalized metadata roughly equivalent to: ```prolog expert_contract{ id: ExpertId, version: Version, accepts: GoalSchema, produces: ResultSchema, specialties: Specialties, applicability: ApplicabilityRef, requires: RequiredCapabilities, observations: RequiredObservations, effects: PossibleEffects, fallback: FallbackPolicy, child_policy: ChildPolicy, limits: Limits, handler: TrustedHandler }. ``` The model-visible/inspection catalog exposes sanitized metadata and schemas, never arbitrary callable closures. Generated/model/project data cannot register executable expert handlers unless it crosses an existing explicit trusted extension/config boundary. ## Symbolic applicability and selection Selection must be possible without an LLM. Support deterministic rule/fact/constraint inputs such as: - goal shape/type; - current project/source facts; - available evidence; - required capability availability; - expert preconditions; - specialization priority/specificity; - confidence or certainty class; - explicit host preference; - exclusions/conflicts; - fallback chain. The selection outcome should preserve all considered candidates plus a structured reason for the chosen expert or why no expert was eligible. Do not silently ask a model to choose when symbolic selection yields no valid candidate. ## Invocation lifecycle Normalize a canonical invocation record with stable identity and state transitions equivalent to: ```text created validated selected running waiting_child waiting_tool succeeded failed unknown blocked cancelled error ``` Preserve parent/child lineage, run/session identity, expert/version identity, relevant context snapshot identity, capabilities and evidence refs. ## Expert→expert calls Nested calls use the same registry and invocation machinery. Required semantics: - depth and aggregate work bounds; - cycle/repeated-subgoal detection; - cancellation propagation; - child capability ceiling never exceeds parent/host ceiling; - child results/evidence are attached to parent lineage; - no separate scheduler; - no model charge merely because nesting occurred. Use existing graph/async primitives where latency/concurrency requires them. ## Tool/capability integration An expert is reasoning, not ambient authority. If an expert needs a tool it must use the existing typed registry/capability/authority/effect boundary. Registration or selection does not grant tool capability. Preflight should be able to distinguish: ```text expert unavailable expert not applicable required capability unavailable capability not granted authority denied runtime/effect failure ``` ## Explicit fallback boundary Implement a generic fallback hook/policy that specialist experts may opt into. A fallback event records at least: ```text expert invocation id fallback reason fallback class provider/model request lineage if model-backed usage/cost from the metered dependency validated fallback output/result ``` Fallback must never replace the primary expert handler or make every expert secretly model-backed. ## Direct/native projection Replace/supersede the useful intent of #353 with a canonical adapter over the expert registry. A direct-mode model may be shown selected expert capabilities as native callable tools **only when host policy chooses to project them**. Projection is availability, not authority. Invocation re-enters `expert_invoke` and the normal capability/tool boundaries. Do not create a fourth native binding family if the existing registry/native tool path can adapt the expert contract cleanly. Important correction from older research: the expert invocation itself is not token/cost charged. If an expert internally uses a model fallback, only that fallback's real provider usage is charged. ## Plan/workflow projection #288 plan graph routing should be able to bind typed expert-owned operations to expert ids/contracts during preflight or execution without embedding trusted closures in model-authored plan data. The graph remains the scheduler. Expert selection does not become a second scheduler. ## Observability / explanation Expose bounded structured inspection for: - registered experts; - applicability candidates; - selection decision; - parent/child lineage; - evidence consumed/produced; - tool calls/effects invoked; - fallback events; - stop/failure reason; - local work counters separately from provider usage. ## Deterministic acceptance - [ ] Register two pure Prolog experts and select correctly from goal facts with `model_calls = 0`. - [ ] Nested expert call remains `model_calls = 0` and `$0` while preserving parent/child lineage. - [ ] Expert selection is deterministic for a fixed registry/context. - [ ] Equal-priority ambiguity returns a structured ambiguity unless policy defines a deterministic tie-break. - [ ] Missing capability fails before underlying tool dispatch. - [ ] Registration does not grant capabilities/authority. - [ ] Child cannot widen parent capability ceiling. - [ ] Recursion cycle/no-progress loop terminates structurally. - [ ] Cancellation stops child and prevents subsequent tool/effect dispatch. - [ ] D6-11 native ops cannot be registered/mapped as experts in the plan expert map. - [ ] `edit/2` and `create/2` can be mapped to the Write Expert once that expert is registered. - [ ] Direct projection and plan routing invoke the same expert implementation. - [ ] Explicit model fallback records provider usage while the surrounding pure expert invocations remain uncharged. - [ ] Catalog/trace output never exposes trusted callable terms or secrets. ## Non-goals - No domain-specific Git/write/project/verify rules here. - No product-specific AgentProlog tools or UI. - No new scheduler, effect ledger, capability system or provider runtime. Refs #376 #141 #288 #355 #353 #354

nsaspy commented

2026-09-08 01:46:23 +00:00

Author

Owner

Machine Spirit #401C handoff — expert portability is goal-contract based

Procedural federation must not persist/import trusted expert closures or assume expert IDs are portable across hosts. Reusable methods name typed solver/goal contracts; #377 performs local applicability/selection against the current registry/version/capability context.

procedure requires GoalSchema
    -> local #377 expert selection
    -> expert result/status

Method identity remains stable if a different compatible expert implementation is selected. compatible expert still does not imply authority. Result adapters must preserve unknown/blocked/unsupported/cancelled/error rather than Boolean-flattening them. See #401C PIFF/PSC design.

## Machine Spirit #401C handoff — expert portability is goal-contract based Procedural federation must not persist/import trusted expert closures or assume expert IDs are portable across hosts. Reusable methods name typed solver/goal contracts; #377 performs local applicability/selection against the current registry/version/capability context. ```text procedure requires GoalSchema -> local #377 expert selection -> expert result/status ``` Method identity remains stable if a different compatible expert implementation is selected. `compatible expert` still does not imply authority. Result adapters must preserve `unknown/blocked/unsupported/cancelled/error` rather than Boolean-flattening them. See #401C PIFF/PSC design.

nsaspy commented

2026-09-08 01:46:24 +00:00

Author

Owner

Machine Spirit #401D handoff — expert runtime as DPEC dependency

Depth 4D keeps the existing expert runtime intact and makes its versioned goal-contract/registry state an explicit dependency of procedural host projections.

Required runtime consequences:

host projection cache keys include only the relevant expert contract/registry generation; unrelated expert changes must not invalidate unrelated procedures;
expert selection remains downstream of method/task decomposition;
physical concurrency among independent experts may vary, but normalized result sets/receipts must be deterministic for identical canonical inputs;
cancellation prevents any later child/tool/effect dispatch and remains distinct from failure;
authority/capability remains rechecked at dispatch where current policy matters; cached procedure compatibility never becomes cached authority;
native procedural engines are not registered as alternate schedulers. If used, they are reference validators/test oracles only;
known heterogeneous procedure + expert cooperation gets a provider-disabled conformance lane with model_calls = 0.

Full DPEC design and conformance fixtures are on #401.

## Machine Spirit #401D handoff — expert runtime as DPEC dependency Depth 4D keeps the existing expert runtime intact and makes its **versioned goal-contract/registry state an explicit dependency of procedural host projections**. Required runtime consequences: - host projection cache keys include only the relevant expert contract/registry generation; unrelated expert changes must not invalidate unrelated procedures; - expert selection remains downstream of method/task decomposition; - physical concurrency among independent experts may vary, but normalized result sets/receipts must be deterministic for identical canonical inputs; - cancellation prevents any later child/tool/effect dispatch and remains distinct from failure; - authority/capability remains rechecked at dispatch where current policy matters; cached procedure compatibility never becomes cached authority; - native procedural engines are not registered as alternate schedulers. If used, they are reference validators/test oracles only; - known heterogeneous procedure + expert cooperation gets a provider-disabled conformance lane with `model_calls = 0`. Full DPEC design and conformance fixtures are on #401.

nsaspy commented

2026-09-08 01:46:24 +00:00

Author

Owner

MACHINE-SPIRIT #404A handoff — EPOCH

Depth 7A establishes that learned expert behavior must remain declarative strategy/composition data over this canonical registry, not generated executable handlers.

Add to the eventual contract:

experience/performance profile != applicability fact != selection != registration != authority
learned expert composition      != trusted handler

An admitted learned composition may reference stable expert contract/version IDs, goal schemas, dependencies and bounded selection policy. Invocation still re-enters the normal #377 registry, capability narrowing, cancellation and trace path. Missing/incompatible expert versions make the learned composition stale/unsupported. Performance statistics may rank already-applicable experts but are operational evidence, not epistemic truth and never widen authority.

Promotion/suspension/version lineage belongs to #404 + durable memory; #377 should expose enough versioned selection/composition dependencies for replay and invalidation. Ref #404A EPOCH.

## MACHINE-SPIRIT #404A handoff — EPOCH Depth 7A establishes that learned expert behavior must remain **declarative strategy/composition data over this canonical registry**, not generated executable handlers. Add to the eventual contract: ```text experience/performance profile != applicability fact != selection != registration != authority learned expert composition != trusted handler ``` An admitted learned composition may reference stable expert contract/version IDs, goal schemas, dependencies and bounded selection policy. Invocation still re-enters the normal #377 registry, capability narrowing, cancellation and trace path. Missing/incompatible expert versions make the learned composition stale/unsupported. Performance statistics may rank already-applicable experts but are operational evidence, not epistemic truth and never widen authority. Promotion/suspension/version lineage belongs to #404 + durable memory; #377 should expose enough versioned selection/composition dependencies for replay and invalidation. Ref #404A EPOCH.

nsaspy commented

2026-09-08 01:46:24 +00:00

Author

Owner

Machine Spirit #404B / CITADEL-EPOCH handoff

Learned selection profiles, expert-performance statistics and self-model outputs remain advisory control evidence over the existing registered expert contract. Add/retain lineage sufficient for #404 to detect self-selection bias:

candidate/strategy version;
eligible alternatives at decision time;
selection policy/version;
task/context signature;
relevant evidence cut;
authority/capability ceiling;
observed outcome/VERIFY lineage.

A learned competence/profile may influence which already-authorized expert is tried, but it cannot widen authority/capability, weaken applicability/verification obligations, mark its own evidence independent, or change its own promotion policy. Refs #404B CITADEL fixtures B19, B27-B28, B40.

## Machine Spirit #404B / CITADEL-EPOCH handoff Learned selection profiles, expert-performance statistics and self-model outputs remain **advisory control evidence** over the existing registered expert contract. Add/retain lineage sufficient for #404 to detect self-selection bias: - candidate/strategy version; - eligible alternatives at decision time; - selection policy/version; - task/context signature; - relevant evidence cut; - authority/capability ceiling; - observed outcome/VERIFY lineage. A learned competence/profile may influence which already-authorized expert is tried, but it cannot widen authority/capability, weaken applicability/verification obligations, mark its own evidence independent, or change its own promotion policy. Refs #404B CITADEL fixtures B19, B27-B28, B40.

nsaspy commented

2026-09-08 01:46:24 +00:00

Author

Owner

Machine Spirit #404C handoff — foreign learned expert/control artifacts

PACT-EPOCH requires imported learned selection rules or expert compositions to enter #377 as declarative foreign candidates, never as registered handlers or locally admitted policy merely because another memory/authority promoted them.

Preserve source artifact/version, learner kind, source authority/policy receipt, applicability/transfer assumptions and target-local admission receipt separately. Same expert name/id across trust domains is not principal/binding identity. Foreign compositions may reference compatible goal contracts only; local registry resolution, capability ceilings and authority remain unchanged. Full design: #404C.

## Machine Spirit #404C handoff — foreign learned expert/control artifacts PACT-EPOCH requires imported learned selection rules or expert compositions to enter #377 as **declarative foreign candidates**, never as registered handlers or locally admitted policy merely because another memory/authority promoted them. Preserve source artifact/version, learner kind, source authority/policy receipt, applicability/transfer assumptions and target-local admission receipt separately. Same expert name/id across trust domains is not principal/binding identity. Foreign compositions may reference compatible goal contracts only; local registry resolution, capability ceilings and authority remain unchanged. Full design: #404C.

nsaspy commented

2026-09-08 01:46:24 +00:00

Author

Owner

MACHINE-SPIRIT #404D / CLOCKWORK runtime boundary

Depth 7D keeps the current expert-runtime architecture intact: learned candidates, locally admitted methods/control rules and imported LACs remain declarative selection/knowledge inputs. Admission never creates a trusted expert handler, capability or authority.

Latency-bearing evaluation reuses the existing rlm_async / #288 execution machinery; do not add a learning scheduler. Known-symbolic candidate validation/selection should remain provider-free where the profile supports it.

A learned expert composition may select only already registered target-local expert contracts. Missing/incompatible registration remains unsupported/blocked rather than synthesizing an executable handler. Refs #397 #404 #379 #395.

## MACHINE-SPIRIT #404D / CLOCKWORK runtime boundary Depth 7D keeps the current expert-runtime architecture intact: learned candidates, locally admitted methods/control rules and imported LACs remain **declarative selection/knowledge inputs**. Admission never creates a trusted expert handler, capability or authority. Latency-bearing evaluation reuses the existing `rlm_async` / #288 execution machinery; do not add a learning scheduler. Known-symbolic candidate validation/selection should remain provider-free where the profile supports it. A learned expert composition may select only already registered target-local expert contracts. Missing/incompatible registration remains unsupported/blocked rather than synthesizing an executable handler. Refs #397 #404 #379 #395.

nsaspy commented

2026-09-08 01:46:24 +00:00

Author

Owner

#405B AEGIS-MS runtime handoff: material expert selection/fallback/control decisions should emit compact direct influence refs plus the relevant registry/control generations. Source/model/project data may parameterize an invocation as data but cannot register/replace trusted handlers, policies or capability ceilings. Child delegation preserves/narrows explicit authority context; no prior wider receipt can be spent after a current capability/policy change. This is metadata/conformance over the existing registry/invocation path, not a second scheduler or authority system.

nsaspy referenced this issue

2026-09-16 21:56:26 +00:00

WIP: feat: add bounded symbolic expert registry and selection #461