IT1: tool-descriptor axis on the kernel ActionCatalog (+ failing completeness gate test)

[George-RD]

Parent

Spec #209 (capability-derived tool catalogs; design ticket #191, wayfinder map #182). Immune-system lane; promises Immune system + Permissions; users Bell, Lyra.

What to build

A new kernel-owned per-action tool descriptor and a descriptors map on the ActionCatalog, mirroring the existing egress_declarations axis exactly (a curated kernel const in crates/openspine-kernel/src/action_catalog.rs + supporting types in crates/openspine-schemas/src/action.rs; never shell-spoofable, never carried on the TaskGrant).

Each ToolDescriptor carries:

• the LLM-facing tool name,
• a one-line description,
• a parameter JSON Schema for the action's invocation payload,
• presentation flags: approval_required, selection_token_required.

Populate a descriptor for every currently-dispatchable action id (the ids the kernel actually mediates through POST /v1/actions). Intentionally-unwired PRD ids (route.activate, workflow.activate, capability_pack.change, policy.change_proposal, connector.enable) need no descriptor — they are not dispatchable and the completeness rule below is scoped to dispatchable actions.

Add a completeness test in the gate (runs under scripts/check.sh, mirroring the existing missing-egress-declaration completeness test in action_catalog_tests.rs) that fails if any granted/dispatchable action lacks a tool descriptor. This is a failing test, not a log line: a granted-but-undescribed action is a capability gap a human must consciously accept (spec owner note A).

No projection function and no wire/HTTP change in this ticket — those are IT2 and IT3.

Acceptance criteria

• ToolDescriptor type exists (name, description, parameter JSON Schema, approval_required, selection_token_required) and round-trips through serde.
• ActionCatalog gains a descriptors map + a builder method mirroring with_egress_declarations, and an accessor to read a descriptor by ActionId.
• Every currently-dispatchable action id has a descriptor in canonical_catalog().
• A completeness test in the gate fails when a dispatchable action has no descriptor (demonstrated by a test that would catch a deliberately-removed descriptor), matching the existing egress-declaration completeness discipline.
• No change to compose() or gate() decision logic; no change to TaskViewBody or the shell.
• cargo test -p openspine-schemas -p openspine-kernel green; scripts/check.sh green.

Blocked by

None (can start immediately).

[coderabbitai]

Coding Plan

Summary

• Add a ToolDescriptor type and a tool_descriptors map with a with_tool_descriptors builder and a tool_descriptor_for accessor on ActionCatalog. This mirrors the egress_declarations axis exactly.
• Represent the parameter JSON Schema as serde_json::Value. Keep ActionCatalog's derived Eq through a manual impl Eq on ToolDescriptor.
• Populate one curated descriptor for each dispatchable id (the 15 handler-registry ids) in a new sibling data file. Derive selection_token_required from the catalog. Curate approval_required by reviewed judgment.
• Add a gate completeness test that fails when any dispatchable action lacks a descriptor. This matches the existing egress-declaration discipline. Do not change compose(), gate(), TaskViewBody, or the shell.

Design Choices

Design Choice 1: Rust type for the parameter JSON Schema field on ToolDescriptor

Options Considered:

1. Use serde_json::Value for the schema field, derive PartialEq, and add a manual impl Eq for ToolDescriptor {} so ActionCatalog keeps its derived Eq.
2. Store the schema as a String of raw JSON schema text so Eq derives automatically.

Chosen Option: 1

Rationale: serde_json::Value is the crate's established convention for embedded free-form JSON (for example plan.rs::arguments). The manual impl Eq preserves ActionCatalog's derived Eq without changing other types.

Design Choice 2: Location of the tool_descriptors() data table

Options Considered:

1. Add tool_descriptors() to the existing action_catalog_data.rs.
2. Add a new sibling file action_catalog_tool_descriptors.rs, wired with #[path = "..."] mod ...;.

Chosen Option: 2

Rationale: A new sibling file keeps every file under the 500-line cap. It follows the established split convention used for action_catalog_data.rs and action_catalog_contracts.rs.

Design Choice 3: Determination of each descriptor's approval_required value

Options Considered:

1. Mirror catalog.is_approval_narrowing(id).
2. Curate each value by reviewed judgment, using effect-significance signals (EffectPathClass, EffectKind, counterparty_facing_actions) as rationale inputs.

Chosen Option: 2

Rationale: is_approval_narrowing marks standing-rule narrowing eligibility, not a per-instance approval requirement. approval_required is a curated presentation flag and must be set by reviewed judgment per action. selection_token_required, by contrast, is a genuine static catalog property and must mirror catalog.requires_selection_token(id).is_some().

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Define the tool-descriptor type and catalog axis

This phase adds the ToolDescriptor type and extends ActionCatalog with a descriptors map, a builder method, and an accessor. It mirrors the existing egress_declarations axis exactly. All work is in the openspine-schemas crate. This phase adds no data and no behavior change.

Task 1: Define the ToolDescriptor type

Add a serializable per-action tool descriptor type.

• Add ToolDescriptor to crates/openspine-schemas/src/action.rs, near ActionEgressDeclaration.
• Give it fields: name: String, description: String, parameters_schema: serde_json::Value, approval_required: bool, selection_token_required: bool.
• Derive Debug, Clone, PartialEq, Serialize, Deserialize and add #[serde(deny_unknown_fields)] for strict wire validation.
• Add a manual impl Eq for ToolDescriptor {} so the type is usable as a value in ActionCatalog's derived Eq (see Assumption 1).
• Do not add an action_id field. The map key carries the id, mirroring ActionEgressDeclaration exactly.

Task 2: Add the descriptors map, builder, and accessor to ActionCatalog

Extend the catalog with the new axis, mirroring egress_declarations.

• In crates/openspine-schemas/src/action.rs, add a tool_descriptors: HashMap<ActionId, ToolDescriptor> field to ActionCatalog, initialized empty in ActionCatalog::new.
• Add a with_tool_descriptors builder that consumes self, accepts impl IntoIterator<Item = (ActionId, ToolDescriptor)>, assigns (overwrites) the map, and returns Self. Match the with_egress_declarations signature and semantics exactly.
• Add a tool_descriptor_for(&self, id: &ActionId) -> Option<&ToolDescriptor> accessor that reads the map with .get(id), matching egress_decl_for.
• Do not change compose(), gate(), TaskViewBody, or the compatibility digest in action_compatibility.rs.

Task 3: Add a serde round-trip test for ToolDescriptor

Prove the type round-trips through serde.

• Add a test in crates/openspine-schemas/src/action/tests.rs, mirroring the existing GateDecision round-trip style.
• Construct a ToolDescriptor with a non-trivial parameters_schema, serialize with serde_json::to_value, deserialize with from_value, and assert equality.

🤖 Prompt for AI agents

Implement the `ToolDescriptor` type and the corresponding `ActionCatalog` axis
in the `openspine-schemas` crate. This phase mirrors the existing
`egress_declarations` axis exactly and does not change behavior or add data.

1. In `crates/openspine-schemas/src/action.rs`, near `ActionEgressDeclaration`,
define `ToolDescriptor` with fields: `name: String`, `description: String`,
`parameters_schema: serde_json::Value`, `approval_required: bool`,
`selection_token_required: bool`. Derive `Debug, Clone, PartialEq, Serialize,
Deserialize` and add `#[serde(deny_unknown_fields)]`. Add a manual `impl Eq for
ToolDescriptor {}` so `ActionCatalog`'s derived `Eq` keeps working. Do not add
an `action_id` field; the map key carries the id.

2. In the same file, add a `tool_descriptors: HashMap<ActionId, ToolDescriptor>`
field to `ActionCatalog`, initialized empty in `ActionCatalog::new`. Add a
`with_tool_descriptors` builder method that consumes `self`, accepts `impl
IntoIterator<Item = (ActionId, ToolDescriptor)>`, overwrites the map, and
returns `Self`, matching the `with_egress_declarations` signature and semantics.
Add a `tool_descriptor_for(&self, id: &ActionId) -> Option<&ToolDescriptor>`
accessor using `.get(id)`, matching `egress_decl_for`. Do not modify
`compose()`, `gate()`, `TaskViewBody`, or the compatibility digest in
`action_compatibility.rs`.

3. In `crates/openspine-schemas/src/action/tests.rs`, add a serde round-trip
test for `ToolDescriptor`, mirroring the `GateDecision` round-trip test style:
construct a `ToolDescriptor` with a non-trivial `parameters_schema`, serialize
with `serde_json::to_value`, deserialize with `from_value`, and assert equality.

Phase 2: Populate descriptors and enforce completeness in the kernel

This phase supplies a descriptor for every dispatchable action id, wires the data into canonical_catalog(), and adds the failing-when-missing completeness test. All work is in the openspine-kernel crate.

Task 1: Add the curated tool_descriptors() data table

Provide one descriptor per dispatchable action id.

• Create a new sibling file crates/openspine-kernel/src/action_catalog_tool_descriptors.rs (see Assumption 2).
• Add a pub(super) fn tool_descriptors() -> Vec<(ActionId, ToolDescriptor)> that returns exactly one entry for each of the 15 dispatchable ids from ActionHandlerRegistry::default_registrations(): openspine.status.read, telegram.reply:owner_channel, terminal.reply:owner_device, email.read_thread:selected_no_attachments, lyra.ui.preview, artifact.propose, artifact.revoke, plan.propose, artifact.nominate_upstream, worker.commission, worker.report_result, worker.failed, skill.context, openspine.overlay.export, openspine.overlay.restore.
• Set selection_token_required: true only for email.read_thread:selected_no_attachments; set it false for the other 14. This must mirror canonical_catalog().requires_selection_token(id).is_some().
• Set approval_required per action by reviewed judgment (see Assumption 3), and add a short comment per non-default value explaining the rationale, consistent with the curated-const philosophy in action_catalog.rs.
• Give each descriptor an LLM-facing name, a one-line description, and a minimal but valid parameters_schema (a serde_json::json!({...}) JSON Schema object for the action's invocation payload).
• Do not add descriptors for route.activate, workflow.activate, capability_pack.change, policy.change_proposal, or connector.enable.

Task 2: Wire the descriptors into canonical_catalog()

Attach the new axis to the canonical catalog.

• In crates/openspine-kernel/src/action_catalog.rs, wire in the new module with #[path = "action_catalog_tool_descriptors.rs"] mod action_catalog_tool_descriptors;, matching the existing action_catalog_data/action_catalog_contracts wiring.
• Add .with_tool_descriptors(action_catalog_tool_descriptors::tool_descriptors()) to the canonical_catalog() builder chain, placed near .with_egress_declarations(...).

Task 3: Add the failing-when-missing completeness test

Enforce that every dispatchable action has a descriptor.

• Add a test in crates/openspine-kernel/src/action_catalog_tests.rs, mirroring handler_registry_requires_explicit_classification.
• Iterate ActionHandlerRegistry::default_registrations().registered_action_ids() and, for each id, call catalog.tool_descriptor_for(&action) and panic! with a descriptive message naming the action if it is None. This makes a granted-but-undescribed action fail the gate, not log a warning.
• Assert that each descriptor's selection_token_required equals catalog.requires_selection_token(&action).is_some(), so the presentation flag stays honest against the catalog.
• Add a cardinality assertion pinning the dispatchable descriptor count to 15, matching the "cardinality, not just membership" idiom used by non_effect_stub_allowlist_is_explicit_and_fails_closed. This ensures a deliberately-removed descriptor fails the test.

🤖 Prompt for AI agents

Populate tool descriptors for every dispatchable action id in the
`openspine-kernel` crate, wire them into the canonical catalog, and add a
completeness test that fails closed when a descriptor is missing.

1. Create a new sibling file
`crates/openspine-kernel/src/action_catalog_tool_descriptors.rs`. Add
`pub(super) fn tool_descriptors() -> Vec<(ActionId, ToolDescriptor)>`, returning
exactly one entry for each of the 15 dispatchable ids from
`ActionHandlerRegistry::default_registrations()`: `openspine.status.read`,
`telegram.reply:owner_channel`, `terminal.reply:owner_device`,
`email.read_thread:selected_no_attachments`, `lyra.ui.preview`,
`artifact.propose`, `artifact.revoke`, `plan.propose`,
`artifact.nominate_upstream`, `worker.commission`, `worker.report_result`,
`worker.failed`, `skill.context`, `openspine.overlay.export`,
`openspine.overlay.restore`. Set `selection_token_required: true` only for
`email.read_thread:selected_no_attachments` and `false` for the other 14; this
must mirror `canonical_catalog().requires_selection_token(id).is_some()`. Set
`approval_required` for each action by reviewed judgment, adding a short
rationale comment for each non-default value, consistent with the curated-const
philosophy in `action_catalog.rs`. Give each descriptor an LLM-facing `name`, a
one-line `description`, and a minimal but valid `parameters_schema` built with
`serde_json::json!({...})` describing the action's invocation payload. Do not
add descriptors for `route.activate`, `workflow.activate`,
`capability_pack.change`, `policy.change_proposal`, or `connector.enable`.

2. In `crates/openspine-kernel/src/action_catalog.rs`, wire the new module in
with `#[path = "action_catalog_tool_descriptors.rs"] mod
action_catalog_tool_descriptors;`, matching the existing
`action_catalog_data`/`action_catalog_contracts` wiring. Add
`.with_tool_descriptors(action_catalog_tool_descriptors::tool_descriptors())` to
the `canonical_catalog()` builder chain, placed near
`.with_egress_declarations(...)`.

3. In `crates/openspine-kernel/src/action_catalog_tests.rs`, add a completeness
test mirroring `handler_registry_requires_explicit_classification`. Iterate
`ActionHandlerRegistry::default_registrations().registered_action_ids()`, and
for each id call `catalog.tool_descriptor_for(&action)`; `panic!` with a
descriptive message naming the action if the result is `None`, so a
granted-but-undescribed action fails the gate rather than only logging a
warning. Assert that each descriptor's `selection_token_required` equals
`catalog.requires_selection_token(&action).is_some()`. Add a cardinality
assertion pinning the dispatchable descriptor count to 15, matching the
"cardinality, not just membership" idiom used by
`non_effect_stub_allowlist_is_explicit_and_fails_closed`, so a deliberately
removed descriptor fails the test.

Research

The authority types are in crates/openspine-schemas/src/action.rs. This includes ActionId (a #[serde(transparent)] string newtype), ActionEgressDeclaration, and the ActionCatalog registry with its with_* builder methods and *_for accessors.

The kernel assembles the canonical catalog in crates/openspine-kernel/src/action_catalog.rs through a builder chain. It stores the raw per-action data in sibling files (action_catalog_data.rs, action_catalog_contracts.rs), wired with #[path = "..."] mod ...;.

The true dispatchable set for POST /v1/actions is the 15 ids registered in crates/openspine-kernel/src/api/handler_registry.rs::ActionHandlerRegistry::default_registrations().

The existing completeness test handler_registry_requires_explicit_classification in action_catalog_tests.rs iterates registered_action_ids(). It fails closed on a missing or wrong egress classification.

Files are capped at 500 lines by scripts/check-file-sizes.sh. scripts/check.sh runs cargo test --workspace.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the `ToolDescriptor` type and the corresponding `ActionCatalog` axis
in the `openspine-schemas` crate. This phase mirrors the existing
`egress_declarations` axis exactly and does not change behavior or add data.

1. In `crates/openspine-schemas/src/action.rs`, near `ActionEgressDeclaration`,
define `ToolDescriptor` with fields: `name: String`, `description: String`,
`parameters_schema: serde_json::Value`, `approval_required: bool`,
`selection_token_required: bool`. Derive `Debug, Clone, PartialEq, Serialize,
Deserialize` and add `#[serde(deny_unknown_fields)]`. Add a manual `impl Eq for
ToolDescriptor {}` so `ActionCatalog`'s derived `Eq` keeps working. Do not add
an `action_id` field; the map key carries the id.

2. In the same file, add a `tool_descriptors: HashMap<ActionId, ToolDescriptor>`
field to `ActionCatalog`, initialized empty in `ActionCatalog::new`. Add a
`with_tool_descriptors` builder method that consumes `self`, accepts `impl
IntoIterator<Item = (ActionId, ToolDescriptor)>`, overwrites the map, and
returns `Self`, matching the `with_egress_declarations` signature and semantics.
Add a `tool_descriptor_for(&self, id: &ActionId) -> Option<&ToolDescriptor>`
accessor using `.get(id)`, matching `egress_decl_for`. Do not modify
`compose()`, `gate()`, `TaskViewBody`, or the compatibility digest in
`action_compatibility.rs`.

3. In `crates/openspine-schemas/src/action/tests.rs`, add a serde round-trip
test for `ToolDescriptor`, mirroring the `GateDecision` round-trip test style:
construct a `ToolDescriptor` with a non-trivial `parameters_schema`, serialize
with `serde_json::to_value`, deserialize with `from_value`, and assert equality.
===============================================================================

Task: 2

Populate tool descriptors for every dispatchable action id in the
`openspine-kernel` crate, wire them into the canonical catalog, and add a
completeness test that fails closed when a descriptor is missing.

1. Create a new sibling file
`crates/openspine-kernel/src/action_catalog_tool_descriptors.rs`. Add
`pub(super) fn tool_descriptors() -> Vec<(ActionId, ToolDescriptor)>`, returning
exactly one entry for each of the 15 dispatchable ids from
`ActionHandlerRegistry::default_registrations()`: `openspine.status.read`,
`telegram.reply:owner_channel`, `terminal.reply:owner_device`,
`email.read_thread:selected_no_attachments`, `lyra.ui.preview`,
`artifact.propose`, `artifact.revoke`, `plan.propose`,
`artifact.nominate_upstream`, `worker.commission`, `worker.report_result`,
`worker.failed`, `skill.context`, `openspine.overlay.export`,
`openspine.overlay.restore`. Set `selection_token_required: true` only for
`email.read_thread:selected_no_attachments` and `false` for the other 14; this
must mirror `canonical_catalog().requires_selection_token(id).is_some()`. Set
`approval_required` for each action by reviewed judgment, adding a short
rationale comment for each non-default value, consistent with the curated-const
philosophy in `action_catalog.rs`. Give each descriptor an LLM-facing `name`, a
one-line `description`, and a minimal but valid `parameters_schema` built with
`serde_json::json!({...})` describing the action's invocation payload. Do not
add descriptors for `route.activate`, `workflow.activate`,
`capability_pack.change`, `policy.change_proposal`, or `connector.enable`.

2. In `crates/openspine-kernel/src/action_catalog.rs`, wire the new module in
with `#[path = "action_catalog_tool_descriptors.rs"] mod
action_catalog_tool_descriptors;`, matching the existing
`action_catalog_data`/`action_catalog_contracts` wiring. Add
`.with_tool_descriptors(action_catalog_tool_descriptors::tool_descriptors())` to
the `canonical_catalog()` builder chain, placed near
`.with_egress_declarations(...)`.

3. In `crates/openspine-kernel/src/action_catalog_tests.rs`, add a completeness
test mirroring `handler_registry_requires_explicit_classification`. Iterate
`ActionHandlerRegistry::default_registrations().registered_action_ids()`, and
for each id call `catalog.tool_descriptor_for(&action)`; `panic!` with a
descriptive message naming the action if the result is `None`, so a
granted-but-undescribed action fails the gate rather than only logging a
warning. Assert that each descriptor's `selection_token_required` equals
`catalog.requires_selection_token(&action).is_some()`. Add a cardinality
assertion pinning the dispatchable descriptor count to 15, matching the
"cardinality, not just membership" idiom used by
`non_effect_stub_allowlist_is_explicit_and_fails_closed`, so a deliberately
removed descriptor fails the test.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!