From 8202db1eb169feafc67896ae5137cbbeb268ad58 Mon Sep 17 00:00:00 2001 From: Hare Date: Fri, 5 Jun 2026 13:54:42 +0900 Subject: [PATCH] ticket: preflight feature authority separation --- .../artifacts/delegation-intent.md | 108 ++++++++++++++++++ .../item.md | 2 +- .../thread.md | 22 ++++ 3 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 work-items/open/20260604-234844-feature-api-authority-separation/artifacts/delegation-intent.md diff --git a/work-items/open/20260604-234844-feature-api-authority-separation/artifacts/delegation-intent.md b/work-items/open/20260604-234844-feature-api-authority-separation/artifacts/delegation-intent.md new file mode 100644 index 00000000..007a52f5 --- /dev/null +++ b/work-items/open/20260604-234844-feature-api-authority-separation/artifacts/delegation-intent.md @@ -0,0 +1,108 @@ +# 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. diff --git a/work-items/open/20260604-234844-feature-api-authority-separation/item.md b/work-items/open/20260604-234844-feature-api-authority-separation/item.md index ad036cad..0e1c8574 100644 --- a/work-items/open/20260604-234844-feature-api-authority-separation/item.md +++ b/work-items/open/20260604-234844-feature-api-authority-separation/item.md @@ -7,7 +7,7 @@ kind: task priority: P1 labels: [plugin, feature-registry, permissions, architecture] created_at: 2026-06-04T23:48:44Z -updated_at: 2026-06-05T00:49:53Z +updated_at: 2026-06-05T04:54:33Z assignee: null legacy_ticket: null --- diff --git a/work-items/open/20260604-234844-feature-api-authority-separation/thread.md b/work-items/open/20260604-234844-feature-api-authority-separation/thread.md index e0ad2b42..597a1134 100644 --- a/work-items/open/20260604-234844-feature-api-authority-separation/thread.md +++ b/work-items/open/20260604-234844-feature-api-authority-separation/thread.md @@ -49,4 +49,26 @@ Implications: This preserves the clean distinction: contribution declarations are descriptor-locked; dangerous host APIs are represented by host-created handles; normal tool permission remains the per-call execution gate. +--- + + + +## Plan + +Preflight result: `implementation-ready`. + +`ticket-built-in-feature-tools` should not be implemented until this boundary is clarified, because Ticket tools need to be internal built-in feature contributions while Ticket backend operations remain typed host authority, not arbitrary filesystem scope or external plugin package approval. + +Implementation intent: + +- Clarify `pod::feature` naming around host authority grants. +- Keep contribution declarations and descriptor reconciliation separate from host authority requests/grants. +- Preserve built-in Task feature behavior as the current contribution-only example. +- Avoid external plugin loading, real approval protocol, Ticket tool implementation, Hook behavior changes, or broader crate moves. + +Detailed delegation intent is in `artifacts/delegation-intent.md`. + +Note: main workspace currently has an unrelated dirty `README.md` change. This feature work must not touch or commit that file. + + ---