109 lines
5.2 KiB
Markdown
109 lines
5.2 KiB
Markdown
# Delegation intent: feature API authority separation
|
|
|
|
## Classification
|
|
|
|
`implementation-ready` as a bounded API cleanup/refinement.
|
|
|
|
This ticket is a prerequisite for `ticket-built-in-feature-tools` because Ticket tools must be installed as internal built-in feature contributions while Ticket operation authority remains a host-granted backend capability, not arbitrary filesystem write scope.
|
|
|
|
## Intent
|
|
|
|
Clarify the `pod::feature` API boundary so internal built-in feature contributions are not confused with external plugin/sandbox authority grants.
|
|
|
|
The important distinction:
|
|
|
|
- Contribution declarations (`tools`, `hooks`, alerts/notices, service/background descriptors) are what a feature contributes to the host registry.
|
|
- Host authority grants are capabilities required for privileged host-mediated operations such as filesystem, network, secrets, Pod management, model notification, state store, or service access.
|
|
|
|
Internal built-in features should be able to register contributions without implying external plugin approval/sandbox semantics. External plugin authority remains a separate future concern.
|
|
|
|
## Worktree / branch
|
|
|
|
- worktree: `/home/hare/Projects/yoi/.worktree/feature-api-authority-separation`
|
|
- branch: `work/feature-api-authority-separation`
|
|
|
|
## Requirements
|
|
|
|
- Keep the change inside the existing `pod::feature` layer; do not create a new crate in this ticket.
|
|
- Make naming and type boundaries explicit enough that later built-in Ticket tools can request Ticket backend authority without being framed as an external plugin package grant.
|
|
- Prefer concrete rename/clarification over compatibility aliases because this is unreleased internal API.
|
|
- Distinguish host authority naming from generic contribution naming. Candidate renames if they fit the code:
|
|
- `AuthorityRequest` -> `HostAuthorityRequest`
|
|
- `AuthorityGrantSet` -> `HostAuthorityGrantSet`
|
|
- `AuthorityDenial` -> `HostAuthorityDenial`
|
|
- `FeatureDescriptor::requested_authorities` -> `requested_host_authorities`
|
|
- `FeatureDescriptor::with_authority` -> `with_host_authority`
|
|
- `ToolContribution::required_authorities` -> `required_host_authorities`
|
|
- `FeatureInstallReport::granted_authorities` -> `host_authority_grants`
|
|
- `FeatureInstallContext::grants()` -> `host_authority_grants()` or equivalent
|
|
- Keep contribution declarations as contribution declarations; do not require host authority grants merely to contribute a tool/hook.
|
|
- Keep existing built-in Task feature behavior unchanged.
|
|
- Keep descriptor-first validation:
|
|
- actual contributed tools/hooks/notifications/etc. must be declared;
|
|
- duplicate tool names remain rejected;
|
|
- missing required host authority still fails feature installation where applicable.
|
|
- Update tests/docs/comments to reflect the new distinction.
|
|
|
|
## Non-goals
|
|
|
|
- Implementing Ticket built-in tools.
|
|
- Implementing Ticket backend authority grants beyond the generic host authority naming/model needed here.
|
|
- External plugin loading/discovery/package approval.
|
|
- WASM/sandbox runtime.
|
|
- MCP integration.
|
|
- Real human approval/resume protocol.
|
|
- Moving feature API to a new crate.
|
|
- Changing Hook API behavior.
|
|
- Changing Task feature behavior.
|
|
- Broad refactors outside `pod::feature` and direct callers/tests.
|
|
|
|
## Current code map
|
|
|
|
- `crates/pod/src/feature.rs`
|
|
- Main feature API, descriptors, contributions, installation, authority request/grant types, tests.
|
|
- Current generic names include `AuthorityRequest`, `AuthorityGrantSet`, `AuthorityDenial`, `requested_authorities`, `granted_authorities`, and `required_authorities`.
|
|
- `FeatureRuntimeKind` already distinguishes `Builtin`, `LuaProfile`, and `ExternalPlugin`.
|
|
- `HostAuthority` already names the host-mediated capability concept.
|
|
- `crates/pod/src/feature/builtin/task/mod.rs`
|
|
- Built-in Task feature implementation and contribution example.
|
|
- Must continue to install Task tools/hooks/reminders unchanged.
|
|
- `crates/pod/src/feature/builtin.rs`
|
|
- Built-in feature contribution wiring.
|
|
- `crates/pod/src/lib.rs`
|
|
- Public exports if affected.
|
|
|
|
## Critical risks
|
|
|
|
- Leaving generic `Authority*` naming in place makes later Ticket tools read like external plugin/sandbox grants, which is the confusion this ticket is meant to prevent.
|
|
- Overcorrecting by making built-in contribution registration depend on host authority grants would make internal features unnecessarily complex.
|
|
- Adding compatibility aliases for old names would preserve the ambiguity; avoid unless required by external public API, which should not be the case for this unreleased surface.
|
|
- Changing behavior instead of naming/boundary tests could destabilize Task feature installation.
|
|
|
|
## Validation
|
|
|
|
Run at least:
|
|
|
|
- `cargo test -p pod feature --lib`
|
|
- `cargo test -p pod task --lib`
|
|
- `cargo test -p pod --lib`
|
|
- `cargo test -p llm-worker --lib`
|
|
- `cargo check --workspace --all-targets`
|
|
- `cargo fmt --check`
|
|
- `git diff --check`
|
|
- `./tickets.sh doctor`
|
|
|
|
Run `nix build .#yoi --no-link` if feasible.
|
|
|
|
## Completion report
|
|
|
|
Report:
|
|
|
|
- worktree path / branch;
|
|
- commit hash;
|
|
- exact API/type/field renames;
|
|
- behavior preserved/changed;
|
|
- changed files;
|
|
- validation results;
|
|
- unresolved risks/follow-ups;
|
|
- whether `ticket-built-in-feature-tools` can proceed afterward.
|