IT2: pure catalog projection in openspine-authority (TaskGrant -> CatalogView)

[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 pure, deterministic, I/O-free projection function in openspine-authority (beside compose), e.g. project_catalog(grant: &TaskGrant, catalog: &ActionCatalog) -> CatalogView, where CatalogView is an ordered list of the tool descriptors (from IT1) the grant permits.

Implement the three-list projection rule exactly:

• grant.allowed_actions -> projected as callable tools.
• grant.approval_required_actions -> projected, annotated "requires owner approval" (the assistant may propose them; the existing approval/gate flow handles the pause).
• grant.denied_actions and any action id not in the grant at all -> structurally absent: no name, no description, no schema is emitted.

The function is policy-free: it projects exactly what compose granted and makes no second authority decision (spec owner note B / D5). It has no I/O and no state, exactly like compose. An allowed/approval-required id whose catalog descriptor is missing is omitted (IT1's completeness test is the backstop that this never silently happens for a dispatchable action).

No wire/HTTP change in this ticket — that is IT3.

Acceptance criteria

• project_catalog exists as a pure function beside compose; no I/O, no shared state.
• Table-driven tests over the three lists: allowed -> present & callable; approval_required -> present & annotated; denied -> absent; ungranted -> absent.
• I2 structural-absence test: given an untrusted/stranger-shaped grant, a denied or ungranted privileged id (e.g. worker.commission, email.send) is asserted NOT present anywhere in the projected CatalogView (no name/description/schema).
• Policy-free purity test: project_catalog(grant, catalog) is a pure function of its inputs — identical inputs yield identical catalogs regardless of surrounding state; projection introduces no allow/deny the grant did not already carry.
• No change to compose() decision logic; no change to TaskViewBody or the shell.
• cargo test -p openspine-authority green; scripts/check.sh green.

Blocked by

IT1 (the ToolDescriptor type and the catalog descriptors map).

[coderabbitai]

Coding Plan

Summary

• Add one new private module project_catalog in openspine-authority that defines CatalogView, CatalogEntry, and a two-variant status enum, and expose them through src/lib.rs using the crate's private-mod plus pub use convention.
• Implement project_catalog as a pure function that reads only allowed_actions (as Callable) and approval_required_actions (as RequiresOwnerApproval) in grant order; denied and ungranted ids are absent by construction, which keeps the function policy-free.
• Depend on the assumed IT1 contract (ToolDescriptor plus a tool_descriptor_for lookup on ActionCatalog); IT2 requires IT1 to land first, and it adds no new crate dependency.
• Add integration tests that cover the three-list rule, missing-descriptor omission, the I2 structural-absence invariant, and policy-free purity, reusing tests/common/mod.rs fixtures and a new TaskGrant builder.

Design Choices

Design Choice 1: IT1 (ToolDescriptor type and the catalog descriptor map) does not exist yet in the repository.

Options Considered:

1. Treat IT1 as an external prerequisite. Plan IT2 against an assumed IT1 contract, and require IT1 to be merged first.
2. Include a minimal IT1 shim (a ToolDescriptor type plus a catalog lookup) inside this plan.

Chosen Option: 1

Rationale: The exploration confirmed zero matches for ToolDescriptor, CatalogView, and project_catalog anywhere in the codebase. This ticket is scoped to IT2 only and lists IT1 as a blocker. IT2 cannot compile or pass tests until IT1 lands. The ticket explicitly scopes IT2 only and marks IT1 as the blocker, so the plan targets IT2 against the assumed IT1 contract and does not build IT1.

Assumed IT1 contract used by this plan:

• ToolDescriptor carries at minimum an owner/LLM-facing name, a description, and a parameters/JSON schema field.
• ActionCatalog exposes a single-action lookup, for example tool_descriptor_for(&ActionId) -> Option<&ToolDescriptor>, and a builder setter to populate the descriptor map (mirroring the existing with_delegation_descriptors / delegation_descriptor_for pattern in crates/openspine-schemas/src/action.rs).

Design Choice 2: How to represent the per-entry status ("callable" vs "requires owner approval") on each CatalogView entry.

Options Considered:

1. Reuse GateDecision directly as the per-entry annotation.
2. Add a dedicated two-variant status enum in the new module.

Chosen Option: 2

Rationale: The gate vocabulary GateDecision (in openspine-schemas) has four variants (Allow, Deny, ApprovalRequired, EffectSuppressed). A projection only ever emits present entries with two possible states. A dedicated two-variant enum (for example Callable and RequiresOwnerApproval) avoids representing impossible states (Deny, EffectSuppressed never appear in a projection) and keeps the projection policy-free, while aligning its naming with the existing GateDecision::ApprovalRequired concept.

Design Choice 3: Entry ordering in CatalogView.

Options Considered:

1. Preserve grant list order: project allowed_actions in order as callable, then approval_required_actions in order as annotated.
2. Sort entries by action id.

Chosen Option: 1

Rationale: The grant stores actions as ordered Vec<ActionId>. The purity test requires a deterministic output for identical inputs. Preserving grant order is already deterministic, adds no extra policy, and needs no comparison logic. It satisfies the ordered-list requirement and the purity test.

💡 User Tips

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

Implementation Steps

Phase 1: Add the pure projection function and its types

This phase adds the new project_catalog module beside compose. It defines the CatalogView output types. It implements the three-list projection rule. The function stays pure: it reads only its two arguments, performs no I/O, holds no state, and makes no second authority decision.

Task 1: Define the CatalogView output types

Create the data types the projection returns.

• Create a new private module crates/openspine-authority/src/project_catalog.rs.
• Open the file with a //! doc comment that cites the relevant canon reference (Spec #209 / the IT2 three-list projection rule), matching the doc-comment habit of the other modules in this crate.
• Define CatalogView as an ordered collection of entries (a wrapper over Vec<CatalogEntry>), with an accessor to iterate entries in order.
• Define CatalogEntry to hold the projected ToolDescriptor (from IT1) together with a status field.
• Define a two-variant status enum, for example CatalogEntryStatus::Callable and CatalogEntryStatus::RequiresOwnerApproval, with a doc comment that ties the second variant to the existing approval/gate flow.
• Import ToolDescriptor, ActionCatalog, TaskGrant, and ActionId from openspine-schemas. Add no new crate dependency.

Task 2: Implement the three-list projection rule

Add the pure projection function.

• Add pub fn project_catalog(grant: &TaskGrant, catalog: &ActionCatalog) -> CatalogView in the new module.
• Iterate grant.allowed_actions in order. For each id, look up its ToolDescriptor in catalog. If a descriptor exists, emit a CatalogEntry with status Callable. If the descriptor is missing, omit the id.
• Iterate grant.approval_required_actions in order. For each id, look up its ToolDescriptor. If a descriptor exists, emit a CatalogEntry with status RequiresOwnerApproval. If the descriptor is missing, omit the id.
• Do not read grant.denied_actions. Do not read any id that is not in the two allow lists. Denied ids and ungranted ids are absent by construction, which keeps the function policy-free.
• Take no clock, no randomness, and no external state. The function is a pure function of its two arguments.
• Keep the function and types within the 500-line file gate. If the file approaches the limit, split tests into a sibling file per the repo convention (see Phase 2).

Task 3: Wire the module into the crate public surface

Expose the new symbols following the crate convention.

• Update crates/openspine-authority/src/lib.rs.
• Add mod project_catalog; to the private module block, placed alphabetically between persona_binding and route.
• Add a pub use project_catalog::{...}; line that re-exports project_catalog, CatalogView, CatalogEntry, and the status enum, placed alphabetically between the equivalence::{...} re-export block and pub use route::resolve_route;.
• Use a private mod plus curated pub use, matching the majority convention. Do not use pub mod.

🤖 Prompt for AI agents

Implement a pure, deterministic projection function `project_catalog` in the
`openspine-authority` crate, beside the existing `compose` module. The goal of
this phase is to add the module, its output types, and the projection logic,
then expose them through the crate's public surface.

First, create a new private module file
`crates/openspine-authority/src/project_catalog.rs`:
- Start the file with a `//!` doc comment citing the relevant canon reference
(Spec `#209` / the IT2 three-list projection rule), consistent with the
doc-comment style used in other modules of this crate.
- Define `CatalogView` as an ordered wrapper over `Vec<CatalogEntry>` with an
accessor to iterate entries in order.
- Define `CatalogEntry` holding a `ToolDescriptor` (from IT1) plus a status
field.
- Define a two-variant status enum (for example `CatalogEntryStatus::Callable`
and `CatalogEntryStatus::RequiresOwnerApproval`), with a doc comment linking
`RequiresOwnerApproval` to the existing approval/gate flow.
- Import `ToolDescriptor`, `ActionCatalog`, `TaskGrant`, and `ActionId` from
`openspine-schemas`. Do not add any new crate dependency.

Next, implement `pub fn project_catalog(grant: &TaskGrant, catalog:
&ActionCatalog) -> CatalogView` in the same module:
- Iterate `grant.allowed_actions` in order. Look up each id's `ToolDescriptor`
in `catalog`. If found, emit a `CatalogEntry` with status `Callable`; if
missing, omit the id.
- Iterate `grant.approval_required_actions` in order. Look up each id's
`ToolDescriptor`. If found, emit a `CatalogEntry` with status
`RequiresOwnerApproval`; if missing, omit the id.
- Never read `grant.denied_actions` or any id outside the two allow lists —
denied and ungranted ids must be absent by construction, keeping the function
policy-free.
- Ensure the function uses no clock, no randomness, and no external state — it
must be a pure function of its two arguments only.
- Respect the crate's 500-line-per-file gate; if the file grows too large, move
tests to a sibling file (handled in Phase 2).

Finally, wire the module into `crates/openspine-authority/src/lib.rs`:
- Add `mod project_catalog;` to the private module block, placed alphabetically
between `persona_binding` and `route`.
- Add `pub use project_catalog::{...};` re-exporting `project_catalog`,
`CatalogView`, `CatalogEntry`, and the status enum, placed alphabetically
between the `equivalence::{...}` re-export block and `pub use
route::resolve_route;`.
- Use the private `mod` plus curated `pub use` convention; do not use `pub mod`.

Phase 2: Add table-driven and invariant tests

This phase adds tests that prove the three-list rule, the I2 structural-absence invariant, and policy-free purity, using the crate's existing integration-test style.

Task 1: Add a TaskGrant fixture builder

Provide a reusable fixture for building grants with controlled action lists.

• Update crates/openspine-authority/tests/common/mod.rs.
• Add a private helper that builds a full TaskGrant literal, mirroring existing literal builders such as crates/openspine-kernel/src/store/tests.rs::sample_grant and crates/openspine-kernel/src/api/task.rs::worker_grant.
• Give the helper parameters (or a small builder) to set allowed_actions, approval_required_actions, and denied_actions.
• Fill non-defaultable fields with fixed test values (Ulid::new() for ids, jiff::Timestamp values, GrantLimits, GrantMode::Live, empty chain, empty caveat_mac), and set root_grant_id consistently.
• Extend the existing test_catalog() helper (or add a sibling helper) so the catalog contains ToolDescriptor entries for the action ids the tests use, plus at least one allowed id with no descriptor for the omission test.

Task 2: Add table-driven three-list tests

Prove the projection rule for each list.

• Add tests in a new integration test file crates/openspine-authority/tests/project_catalog.rs, declaring mod common; and use common::*; like tests/compose.rs.
• Add a table-driven test that covers: an id in allowed_actions is present and Callable; an id in approval_required_actions is present and RequiresOwnerApproval; an id in denied_actions is absent; an id in no list is absent.
• Add a test that an allowed or approval-required id with a missing catalog descriptor is omitted from CatalogView.
• Assert on the ordered entries returned by project_catalog, following the descriptive-name-per-scenario style.

Task 3: Add the I2 structural-absence and purity tests

Prove the two named invariants in the acceptance criteria.

• Add an I2 structural-absence test in tests/project_catalog.rs. Build a stranger-shaped grant directly (empty or minimal allowed_actions, privileged ids such as worker.commission and email.send placed in denied_actions or omitted entirely). Assert that these ids never appear in the projected CatalogView: no entry, no name, no description, no schema.
• Add a policy-free purity test. Call project_catalog(grant, catalog) twice with identical inputs and assert equal CatalogView outputs. Assert the projection introduces no id that the grant did not already carry in its allow or approval lists.
• Confirm no test touches compose(), TaskViewBody, or the shell.

🤖 Prompt for AI agents

Add integration tests for `project_catalog` in the `openspine-authority` crate
that prove the three-list rule, the I2 structural-absence invariant, and
policy-free purity, following the crate's existing integration-test style.

First, add a TaskGrant fixture builder:
- Update `crates/openspine-authority/tests/common/mod.rs`.
- Add a private helper that builds a full `TaskGrant` literal, mirroring
existing literal builders such as
`crates/openspine-kernel/src/store/tests.rs::sample_grant` and
`crates/openspine-kernel/src/api/task.rs::worker_grant`.
- Give the helper parameters (or a small builder) to set `allowed_actions`,
`approval_required_actions`, and `denied_actions`.
- Fill non-defaultable fields with fixed test values (`Ulid::new()` for ids,
`jiff::Timestamp` values, `GrantLimits`, `GrantMode::Live`, empty `chain`, empty
`caveat_mac`), and set `root_grant_id` consistently.
- Extend the existing `test_catalog()` helper (or add a sibling helper) so the
catalog contains `ToolDescriptor` entries for the action ids used in tests, plus
at least one allowed id with no descriptor for the omission test.

Next, add table-driven three-list tests:
- Create a new integration test file
`crates/openspine-authority/tests/project_catalog.rs`, declaring `mod common;`
and `use common::*;`, matching the pattern in `tests/compose.rs`.
- Add a table-driven test covering: an id in `allowed_actions` is present and
`Callable`; an id in `approval_required_actions` is present and
`RequiresOwnerApproval`; an id in `denied_actions` is absent; an id in no list
is absent.
- Add a test proving that an allowed or approval-required id with a missing
catalog descriptor is omitted from `CatalogView`.
- Assert on the ordered entries returned by `project_catalog`, following the
descriptive-name-per-scenario style used elsewhere in the crate.

Finally, add the I2 structural-absence and purity tests in the same file:
- Add an I2 structural-absence test. Build a stranger-shaped grant directly
(empty or minimal `allowed_actions`, with privileged ids such as
`worker.commission` and `email.send` placed in `denied_actions` or omitted
entirely). Assert these ids never appear in the projected `CatalogView` — no
entry, no name, no description, no schema.
- Add a policy-free purity test. Call `project_catalog(grant, catalog)` twice
with identical inputs and assert the two `CatalogView` outputs are equal. Also
assert the projection introduces no id that the grant did not already carry in
its allow or approval lists.
- Verify no test touches `compose()`, `TaskViewBody`, or the shell.

Research

openspine-authority is a small, pure-composition crate. It has no I/O. It depends only on openspine-schemas (plus jiff, thiserror, rand, ulid). It does not depend on openspine-kernel or openspine-gate.

Its modules follow one convention: a private mod x; plus a curated pub use x::{...}; re-export in src/lib.rs.

TaskGrant, ActionId, ActionCatalog, and GateDecision all live in openspine-schemas. No new crate dependency is required.

TaskGrant.allowed_actions, TaskGrant.approval_required_actions, and TaskGrant.denied_actions are each Vec<ActionId>.

Integration tests use shared fixture builders in tests/common/mod.rs, one descriptive #[test] per scenario, and a test_catalog() helper that derives an ActionCatalog from the fixtures.

The repo enforces a 500-line-per-file gate, cargo fmt --check, and cargo clippy --workspace --all-targets -- -D warnings through scripts/check.sh.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement a pure, deterministic projection function `project_catalog` in the
`openspine-authority` crate, beside the existing `compose` module. The goal of
this phase is to add the module, its output types, and the projection logic,
then expose them through the crate's public surface.

First, create a new private module file
`crates/openspine-authority/src/project_catalog.rs`:
- Start the file with a `//!` doc comment citing the relevant canon reference
(Spec `#209` / the IT2 three-list projection rule), consistent with the
doc-comment style used in other modules of this crate.
- Define `CatalogView` as an ordered wrapper over `Vec<CatalogEntry>` with an
accessor to iterate entries in order.
- Define `CatalogEntry` holding a `ToolDescriptor` (from IT1) plus a status
field.
- Define a two-variant status enum (for example `CatalogEntryStatus::Callable`
and `CatalogEntryStatus::RequiresOwnerApproval`), with a doc comment linking
`RequiresOwnerApproval` to the existing approval/gate flow.
- Import `ToolDescriptor`, `ActionCatalog`, `TaskGrant`, and `ActionId` from
`openspine-schemas`. Do not add any new crate dependency.

Next, implement `pub fn project_catalog(grant: &TaskGrant, catalog:
&ActionCatalog) -> CatalogView` in the same module:
- Iterate `grant.allowed_actions` in order. Look up each id's `ToolDescriptor`
in `catalog`. If found, emit a `CatalogEntry` with status `Callable`; if
missing, omit the id.
- Iterate `grant.approval_required_actions` in order. Look up each id's
`ToolDescriptor`. If found, emit a `CatalogEntry` with status
`RequiresOwnerApproval`; if missing, omit the id.
- Never read `grant.denied_actions` or any id outside the two allow lists —
denied and ungranted ids must be absent by construction, keeping the function
policy-free.
- Ensure the function uses no clock, no randomness, and no external state — it
must be a pure function of its two arguments only.
- Respect the crate's 500-line-per-file gate; if the file grows too large, move
tests to a sibling file (handled in Phase 2).

Finally, wire the module into `crates/openspine-authority/src/lib.rs`:
- Add `mod project_catalog;` to the private module block, placed alphabetically
between `persona_binding` and `route`.
- Add `pub use project_catalog::{...};` re-exporting `project_catalog`,
`CatalogView`, `CatalogEntry`, and the status enum, placed alphabetically
between the `equivalence::{...}` re-export block and `pub use
route::resolve_route;`.
- Use the private `mod` plus curated `pub use` convention; do not use `pub mod`.
===============================================================================

Task: 2

Add integration tests for `project_catalog` in the `openspine-authority` crate
that prove the three-list rule, the I2 structural-absence invariant, and
policy-free purity, following the crate's existing integration-test style.

First, add a TaskGrant fixture builder:
- Update `crates/openspine-authority/tests/common/mod.rs`.
- Add a private helper that builds a full `TaskGrant` literal, mirroring
existing literal builders such as
`crates/openspine-kernel/src/store/tests.rs::sample_grant` and
`crates/openspine-kernel/src/api/task.rs::worker_grant`.
- Give the helper parameters (or a small builder) to set `allowed_actions`,
`approval_required_actions`, and `denied_actions`.
- Fill non-defaultable fields with fixed test values (`Ulid::new()` for ids,
`jiff::Timestamp` values, `GrantLimits`, `GrantMode::Live`, empty `chain`, empty
`caveat_mac`), and set `root_grant_id` consistently.
- Extend the existing `test_catalog()` helper (or add a sibling helper) so the
catalog contains `ToolDescriptor` entries for the action ids used in tests, plus
at least one allowed id with no descriptor for the omission test.

Next, add table-driven three-list tests:
- Create a new integration test file
`crates/openspine-authority/tests/project_catalog.rs`, declaring `mod common;`
and `use common::*;`, matching the pattern in `tests/compose.rs`.
- Add a table-driven test covering: an id in `allowed_actions` is present and
`Callable`; an id in `approval_required_actions` is present and
`RequiresOwnerApproval`; an id in `denied_actions` is absent; an id in no list
is absent.
- Add a test proving that an allowed or approval-required id with a missing
catalog descriptor is omitted from `CatalogView`.
- Assert on the ordered entries returned by `project_catalog`, following the
descriptive-name-per-scenario style used elsewhere in the crate.

Finally, add the I2 structural-absence and purity tests in the same file:
- Add an I2 structural-absence test. Build a stranger-shaped grant directly
(empty or minimal `allowed_actions`, with privileged ids such as
`worker.commission` and `email.send` placed in `denied_actions` or omitted
entirely). Assert these ids never appear in the projected `CatalogView` — no
entry, no name, no description, no schema.
- Add a policy-free purity test. Call `project_catalog(grant, catalog)` twice
with identical inputs and assert the two `CatalogView` outputs are equal. Also
assert the projection introduces no id that the grant did not already carry in
its allow or approval lists.
- Verify no test touches `compose()`, `TaskViewBody`, or the shell.

💡 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!

[George-RD]

Owner-proxy ruling on the two flagged deviations: ACCEPTED. (1) CatalogEntry carrying action_id is load-bearing — a worker must name the action to call it. (2) No serde derives on projection types is the right conservative default for a pure-projection crate; #212 adds serialization at the HTTP boundary where it belongs.