ticket: use base32 project record ids
This commit is contained in:
@@ -0,0 +1,15 @@
|
||||
# Decision: separate internal feature modules from external-plugin authority
|
||||
|
||||
Internal modules extracted from Pod implementation files should not be treated as if they require the external-plugin permission model.
|
||||
|
||||
For an internal built-in module such as Task tools:
|
||||
|
||||
- the feature registry is an API/registration boundary;
|
||||
- descriptor-declared contributions are reconciled at install time;
|
||||
- normal ToolRegistry and PreToolCall permission behavior remains authoritative;
|
||||
- host state such as `TaskStore` can be passed by the Pod host constructor;
|
||||
- requested host authorities should normally be empty.
|
||||
|
||||
The external-plugin authority model remains necessary for sandbox/object-capability grants when plugin code receives dangerous host APIs such as filesystem, network, secrets, model-visible durable notification/history append, Pod-management façade, persistent state, or authority-bearing service access.
|
||||
|
||||
This split should be implemented separately from the Task tools extraction. The Task tools extraction should validate the contribution-only built-in module path without solving external plugin approval.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Decision: authority handles live in Hook contexts, not Hook return effects
|
||||
|
||||
The internal-module and external-plugin authority split should treat host-authority APIs as handles supplied by the host, including inside Hooks.
|
||||
|
||||
Implications:
|
||||
|
||||
- Hook return values remain per-hook-point flow-control actions.
|
||||
- Side effects such as durable model-visible SystemItem append are performed through typed host handles on event-specific Hook contexts.
|
||||
- Built-in internal modules may receive handles according to host policy without user-facing external-plugin approval.
|
||||
- Future external plugins receive only the handles allowed by their approved host authorities.
|
||||
- The main API should not be “return an effect and let the host reject it at runtime.” Rejection remains defense-in-depth for malformed calls, missing handles, bounds, and policy violations.
|
||||
- Do not model every authority combination as a distinct Hook context type. Use event-specific context types with authority-specific handles whose constructors are host-owned.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,76 @@
|
||||
# Implementation report: feature-api-authority-separation
|
||||
|
||||
## Worktree / branch
|
||||
|
||||
- Worktree: `/home/hare/Projects/yoi/.worktree/feature-api-authority-separation`
|
||||
- Branch: `work/feature-api-authority-separation`
|
||||
|
||||
## Commit
|
||||
|
||||
- `4fc361f refactor: name feature host authorities explicitly`
|
||||
|
||||
## Summary
|
||||
|
||||
Clarified the `pod::feature` authority boundary by renaming the generic authority API surface to explicit host-authority terminology. This keeps feature contribution declarations separate from host-mediated capability grants and prepares the API for later Ticket built-in tools without framing internal built-ins as external plugin package grants.
|
||||
|
||||
## Exact renames
|
||||
|
||||
- `AuthorityRequest` -> `HostAuthorityRequest`
|
||||
- `AuthorityGrantSet` -> `HostAuthorityGrantSet`
|
||||
- `AuthorityDenial` -> `HostAuthorityDenial`
|
||||
- `FeatureDescriptor::requested_authorities` -> `requested_host_authorities`
|
||||
- `FeatureDescriptor::with_authority` -> `with_host_authority`
|
||||
- `ToolContribution::required_authorities` -> `required_host_authorities`
|
||||
- `ToolContribution::with_required_authorities` -> `with_required_host_authorities`
|
||||
- `FeatureInstallReport::granted_authorities` -> `host_authority_grants`
|
||||
- `FeatureInstallContext::grants()` -> `host_authority_grants()`
|
||||
- `FeatureInstallError::AuthorityDenied` -> `HostAuthorityDenied`
|
||||
- Internal helpers/diagnostics now use host-authority terminology where applicable.
|
||||
|
||||
## Changed files
|
||||
|
||||
- `crates/pod/src/feature.rs`
|
||||
|
||||
## Behavior
|
||||
|
||||
Preserved:
|
||||
|
||||
- descriptor-first validation;
|
||||
- duplicate tool rejection;
|
||||
- undeclared contribution rejection;
|
||||
- missing required host authority install failure;
|
||||
- built-in Task feature behavior;
|
||||
- contribution-only built-in feature installation without host authority grants.
|
||||
|
||||
Added/updated tests and comments to make explicit that contributing a tool/hook/background/service descriptor is not itself a host authority grant, while per-tool host authority requirements still require a corresponding granted requested host authority.
|
||||
|
||||
## Validation
|
||||
|
||||
Coder-reported validation passed:
|
||||
|
||||
- `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`
|
||||
- `nix build .#yoi --no-link`
|
||||
|
||||
Reviewer-rerun validation passed:
|
||||
|
||||
- `git diff --check develop...HEAD`
|
||||
- `cargo test -p pod feature --lib`
|
||||
|
||||
## Review status
|
||||
|
||||
External sibling reviewer approved with no blockers and no required non-blockers before merge.
|
||||
|
||||
## Unresolved risks / follow-ups
|
||||
|
||||
The existing `HostAuthorityGrantSet::grant_all(&descriptor.requested_host_authorities)` behavior remains a builtin-only scaffold, not a real external plugin approval resolver. This is unchanged and explicitly outside this ticket's scope.
|
||||
|
||||
## Ready for merge
|
||||
|
||||
Yes. This clears the API naming prerequisite for `ticket-built-in-feature-tools`.
|
||||
@@ -0,0 +1,69 @@
|
||||
# External review: feature-api-authority-separation
|
||||
|
||||
## 1. Result
|
||||
|
||||
approve
|
||||
|
||||
## 2. Summary of implementation
|
||||
|
||||
The implementation is a focused `pod::feature` API cleanup in `crates/pod/src/feature.rs` only. It renames the generic authority API surface to explicit host-authority naming:
|
||||
|
||||
- `AuthorityRequest` -> `HostAuthorityRequest`
|
||||
- `AuthorityGrantSet` -> `HostAuthorityGrantSet`
|
||||
- `AuthorityDenial` -> `HostAuthorityDenial`
|
||||
- `FeatureDescriptor::requested_authorities` -> `requested_host_authorities`
|
||||
- `FeatureDescriptor::with_authority` -> `with_host_authority`
|
||||
- `ToolContribution::required_authorities` / builder -> `required_host_authorities` / `with_required_host_authorities`
|
||||
- `FeatureInstallReport::granted_authorities` -> `host_authority_grants`
|
||||
- `FeatureInstallContext::grants()` -> `host_authority_grants()`
|
||||
- `FeatureInstallError::AuthorityDenied` -> `HostAuthorityDenied`
|
||||
|
||||
The code comments and tests now describe contribution declarations as descriptor-approved contributions, not host authority grants. A new focused test covers a tool that needs a host authority: contribution declaration alone is not enough, while an explicit requested host authority grants the install-time host-authority requirement under the current grant-all scaffold.
|
||||
|
||||
## 3. Requirement-by-requirement assessment
|
||||
|
||||
- Generic authority ambiguity removed or clarified: satisfied. The changed source no longer exposes the generic `AuthorityRequest`, `AuthorityGrantSet`, `AuthorityDenial`, `requested_authorities`, `required_authorities`, `granted_authorities`, or `grants()` names in the live Rust API; all are explicitly host-authority named.
|
||||
- Contribution declarations remain separate from host authority grants: satisfied. Tool/hook/background/service declarations remain descriptor contribution data, while host authorities are carried through `requested_host_authorities` and `host_authority_grants`.
|
||||
- Built-in contribution registration does not require host authority merely to contribute descriptors: satisfied. `ToolContribution::new` defaults to no `required_host_authorities`, background tasks/services remain descriptor/report contributions, and Task installs with empty host-authority grants.
|
||||
- Missing required host authority still fails feature installation where appropriate: satisfied for the current install surface. `ToolContribution::with_required_host_authorities` still rejects install when the corresponding host authority is absent from the grant set, and the new test covers this path.
|
||||
- Descriptor-first validation and duplicate tool rejection preserved: satisfied. The existing undeclared contribution, tool-name mismatch, duplicate tool, background/service declaration, and worker materialization tests remain in place and passed in focused validation.
|
||||
- Built-in Task feature behavior unchanged: satisfied by diff scope and focused tests. Task descriptor/install behavior still reports no host authorities and installs the same Task tool/hook set.
|
||||
- No unrelated scope expansion: satisfied. The diff is limited to `crates/pod/src/feature.rs`; it does not introduce Ticket tools, Ticket backend authority grants, plugin loading, MCP, WASM/sandbox runtime, approval protocol, crate extraction, Hook behavior changes, Task behavior changes, or broad refactors.
|
||||
- Tests/docs/comments reflect the distinction: satisfied. Public comments and test names/assertions now consistently use host-authority terminology for this API surface, and tests explicitly cover contribution-only built-ins and host-authority-gated tools.
|
||||
- Validation sufficient: satisfied for this review. I reran focused validation and inspected the diff/source for the listed requirements.
|
||||
|
||||
## 4. Blockers
|
||||
|
||||
None.
|
||||
|
||||
## 5. Non-blockers / follow-ups
|
||||
|
||||
None required before merge.
|
||||
|
||||
Notes for later external-plugin work:
|
||||
|
||||
- `HostAuthorityGrantSet::grant_all(&descriptor.requested_host_authorities)` remains the existing builtin-only scaffold, not a real host policy/user approval resolver. This is unchanged and within this ticket's non-goals, but it must be replaced before enabling untrusted external plugins.
|
||||
- `HostAuthorityRequest::required` versus `optional` remains future-facing under the current grant-all scaffold. No behavior change is introduced here.
|
||||
|
||||
## 6. Validation assessed or rerun
|
||||
|
||||
Rerun from `/home/hare/Projects/yoi/.worktree/feature-api-authority-separation`:
|
||||
|
||||
- `git diff --check develop...HEAD` — passed.
|
||||
- `cargo test -p pod feature --lib` — passed: 33 passed, 0 failed, 252 filtered out.
|
||||
|
||||
Additional inspection:
|
||||
|
||||
- Reviewed ticket and delegation intent.
|
||||
- Reviewed `git diff develop...HEAD`.
|
||||
- Confirmed the implementation diff touches only `crates/pod/src/feature.rs`.
|
||||
- Searched Rust sources for the old generic authority names and found no live-code API leftovers, only new host-authority names or historical work-item text outside source.
|
||||
- Checked worktree status after validation; no tracked changes.
|
||||
|
||||
Not rerun:
|
||||
|
||||
- Full workspace checks, broader package tests, `./tickets.sh doctor`, and `nix build .#yoi --no-link` were not rerun for this focused external review.
|
||||
|
||||
## 7. Residual risk
|
||||
|
||||
Residual risk is low for this ticket. The change is mostly API naming plus tests, and focused validation passed. The main remaining risk is pre-existing: the feature registry still automatically grants requested host authorities, so it is not yet a real external-plugin authority enforcement layer. That risk is explicitly outside this ticket's implementation scope and does not block this host-authority naming clarification.
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "Feature API: separate internal modules from external-plugin authority model"
|
||||
state: "closed"
|
||||
created_at: "2026-06-04T23:48:44Z"
|
||||
updated_at: "2026-06-05T05:11:56Z"
|
||||
---
|
||||
|
||||
## Issue
|
||||
|
||||
The first feature-registry slice intentionally placed contribution descriptors and future external-plugin host authorities in the same `pod::feature` module. That was acceptable as a scaffold, but it risks making simple internal module extraction look like it participates in the external-plugin permission model.
|
||||
|
||||
For internal modules that are merely moved outside a Pod implementation file, the registry should act as an API/registration boundary: descriptor-declared contributions, install reports, and normal ToolRegistry/Hook paths. It should not require or imply sandbox/user-approval authorities unless the module asks the host for dangerous external/plugin-style APIs.
|
||||
|
||||
## Direction
|
||||
|
||||
Separate the concepts in code and naming:
|
||||
|
||||
- **Contribution boundary**: tools, hooks, background task declarations, service providers, descriptor/digest locking, duplicate checks, install reports.
|
||||
- **Internal built-in module boundary**: in-process modules constructed by the host with explicit Rust handles such as `TaskStore`; normally no host-authority request/grant flow.
|
||||
- **External-plugin authority boundary**: user-approved sandbox/object-capability grants for host-provided APIs and handles such as filesystem, network, secrets, model-visible durable notification, Pod-management façade, persistent/plugin state, and authority-bearing service access.
|
||||
|
||||
The goal is not to remove the authority model. The goal is to prevent the authority model from being mixed into every internal module extraction.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Audit `pod::feature` names and APIs for places where external-plugin authority concepts are presented as required for internal built-in modules.
|
||||
- Make the API clearly support a contribution-only built-in module path.
|
||||
- Internal modules should be able to declare contributions and install without requesting authorities.
|
||||
- Descriptor/contribution reconciliation still applies.
|
||||
- Normal per-call tool permission / PreToolCall policy still applies.
|
||||
- Keep `HostAuthority` or equivalent only for host-provided dangerous authorities.
|
||||
- Do not reintroduce contribution-authority variants such as `ContributeTool`, `ContributeHook`, `RunBackgroundTask`, or `ProvideService`.
|
||||
- Consider whether the authority request/grant types should be renamed, nested, moved, or documented as external-plugin/sandbox-oriented.
|
||||
- Clarify how built-in modules receive in-process state/handles from the host without treating those constructor arguments as plugin authorities.
|
||||
- Clarify how future external plugins will get only approved host handles/services, without changing the internal module path.
|
||||
- Update tests or add focused tests where needed so a built-in module with zero requested authorities is a normal first-class path.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Implementing external plugin loading or package approval lock files.
|
||||
- Implementing a real user approval resolver.
|
||||
- Changing existing manifest/tool permission policy.
|
||||
- Extracting Memory or Pod management out of core.
|
||||
- Changing Task tool behavior.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- The code/design clearly distinguishes contribution registration from external-plugin host authority grants.
|
||||
- Internal built-in modules can be represented as contribution-only modules without authority boilerplate.
|
||||
- Authority model remains available for future external plugins and host-provided dangerous APIs.
|
||||
- Tests/documentation make it hard to confuse descriptor-approved contributions with sandbox authorities.
|
||||
@@ -0,0 +1,40 @@
|
||||
Feature API authority separation is complete and merged.
|
||||
|
||||
Implementation:
|
||||
|
||||
- `4fc361f refactor: name feature host authorities explicitly`
|
||||
- merge commit: `b46ea65 merge: clarify feature host authorities`
|
||||
|
||||
Summary:
|
||||
|
||||
- Renamed the generic feature authority API surface to explicit host-authority terminology:
|
||||
- `AuthorityRequest` -> `HostAuthorityRequest`
|
||||
- `AuthorityGrantSet` -> `HostAuthorityGrantSet`
|
||||
- `AuthorityDenial` -> `HostAuthorityDenial`
|
||||
- `requested_authorities` -> `requested_host_authorities`
|
||||
- `required_authorities` -> `required_host_authorities`
|
||||
- `granted_authorities` -> `host_authority_grants`
|
||||
- `grants()` -> `host_authority_grants()`
|
||||
- `FeatureInstallError::AuthorityDenied` -> `HostAuthorityDenied`
|
||||
- Preserved descriptor-first validation, duplicate tool rejection, undeclared contribution rejection, missing host-authority install failure, and built-in Task feature behavior.
|
||||
- Added/updated tests/comments to make contribution declarations separate from host authority grants.
|
||||
- Did not implement Ticket tools, external plugin loading, approval/resume protocol, MCP, WASM/sandbox runtime, feature crate extraction, Hook behavior changes, or Task behavior changes.
|
||||
|
||||
Review:
|
||||
|
||||
- External sibling reviewer approved with no blockers and no required non-blockers.
|
||||
- Residual note: `HostAuthorityGrantSet::grant_all(&descriptor.requested_host_authorities)` remains the existing builtin-only scaffold, not a real external-plugin approval resolver. This is unchanged and remains future work.
|
||||
|
||||
Post-merge validation passed:
|
||||
|
||||
- `cargo test -p pod feature --lib`
|
||||
- `cargo test -p pod task --lib`
|
||||
- `cargo test -p pod --lib`
|
||||
- `cargo test -p llm-worker --lib`
|
||||
- `cargo fmt --check`
|
||||
- `git diff --check`
|
||||
- `./tickets.sh doctor`
|
||||
- `cargo check --workspace --all-targets`
|
||||
- `nix build .#yoi --no-link`
|
||||
|
||||
This clears the API naming prerequisite for `ticket-built-in-feature-tools`.
|
||||
@@ -0,0 +1,283 @@
|
||||
<!-- event: create author: tickets.sh at: 2026-06-04T23:48:44Z -->
|
||||
|
||||
## Created
|
||||
|
||||
Created by tickets.sh create.
|
||||
|
||||
---
|
||||
|
||||
<!-- event: decision author: hare at: 2026-06-04T23:50:15Z -->
|
||||
|
||||
## Decision
|
||||
|
||||
# Decision: separate internal feature modules from external-plugin authority
|
||||
|
||||
Internal modules extracted from Pod implementation files should not be treated as if they require the external-plugin permission model.
|
||||
|
||||
For an internal built-in module such as Task tools:
|
||||
|
||||
- the feature registry is an API/registration boundary;
|
||||
- descriptor-declared contributions are reconciled at install time;
|
||||
- normal ToolRegistry and PreToolCall permission behavior remains authoritative;
|
||||
- host state such as `TaskStore` can be passed by the Pod host constructor;
|
||||
- requested host authorities should normally be empty.
|
||||
|
||||
The external-plugin authority model remains necessary for sandbox/object-capability grants when plugin code receives dangerous host APIs such as filesystem, network, secrets, model-visible durable notification/history append, Pod-management façade, persistent state, or authority-bearing service access.
|
||||
|
||||
This split should be implemented separately from the Task tools extraction. The Task tools extraction should validate the contribution-only built-in module path without solving external plugin approval.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: decision author: hare at: 2026-06-05T00:49:53Z -->
|
||||
|
||||
## Decision
|
||||
|
||||
# Decision: authority handles live in Hook contexts, not Hook return effects
|
||||
|
||||
The internal-module and external-plugin authority split should treat host-authority APIs as handles supplied by the host, including inside Hooks.
|
||||
|
||||
Implications:
|
||||
|
||||
- Hook return values remain per-hook-point flow-control actions.
|
||||
- Side effects such as durable model-visible SystemItem append are performed through typed host handles on event-specific Hook contexts.
|
||||
- Built-in internal modules may receive handles according to host policy without user-facing external-plugin approval.
|
||||
- Future external plugins receive only the handles allowed by their approved host authorities.
|
||||
- The main API should not be “return an effect and let the host reject it at runtime.” Rejection remains defense-in-depth for malformed calls, missing handles, bounds, and policy violations.
|
||||
- Do not model every authority combination as a distinct Hook context type. Use event-specific context types with authority-specific handles whose constructors are host-owned.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: plan author: hare at: 2026-06-05T04:54:33Z -->
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: review author: hare at: 2026-06-05T05:09:36Z status: approve -->
|
||||
|
||||
## Review: approve
|
||||
|
||||
# External review: feature-api-authority-separation
|
||||
|
||||
## 1. Result
|
||||
|
||||
approve
|
||||
|
||||
## 2. Summary of implementation
|
||||
|
||||
The implementation is a focused `pod::feature` API cleanup in `crates/pod/src/feature.rs` only. It renames the generic authority API surface to explicit host-authority naming:
|
||||
|
||||
- `AuthorityRequest` -> `HostAuthorityRequest`
|
||||
- `AuthorityGrantSet` -> `HostAuthorityGrantSet`
|
||||
- `AuthorityDenial` -> `HostAuthorityDenial`
|
||||
- `FeatureDescriptor::requested_authorities` -> `requested_host_authorities`
|
||||
- `FeatureDescriptor::with_authority` -> `with_host_authority`
|
||||
- `ToolContribution::required_authorities` / builder -> `required_host_authorities` / `with_required_host_authorities`
|
||||
- `FeatureInstallReport::granted_authorities` -> `host_authority_grants`
|
||||
- `FeatureInstallContext::grants()` -> `host_authority_grants()`
|
||||
- `FeatureInstallError::AuthorityDenied` -> `HostAuthorityDenied`
|
||||
|
||||
The code comments and tests now describe contribution declarations as descriptor-approved contributions, not host authority grants. A new focused test covers a tool that needs a host authority: contribution declaration alone is not enough, while an explicit requested host authority grants the install-time host-authority requirement under the current grant-all scaffold.
|
||||
|
||||
## 3. Requirement-by-requirement assessment
|
||||
|
||||
- Generic authority ambiguity removed or clarified: satisfied. The changed source no longer exposes the generic `AuthorityRequest`, `AuthorityGrantSet`, `AuthorityDenial`, `requested_authorities`, `required_authorities`, `granted_authorities`, or `grants()` names in the live Rust API; all are explicitly host-authority named.
|
||||
- Contribution declarations remain separate from host authority grants: satisfied. Tool/hook/background/service declarations remain descriptor contribution data, while host authorities are carried through `requested_host_authorities` and `host_authority_grants`.
|
||||
- Built-in contribution registration does not require host authority merely to contribute descriptors: satisfied. `ToolContribution::new` defaults to no `required_host_authorities`, background tasks/services remain descriptor/report contributions, and Task installs with empty host-authority grants.
|
||||
- Missing required host authority still fails feature installation where appropriate: satisfied for the current install surface. `ToolContribution::with_required_host_authorities` still rejects install when the corresponding host authority is absent from the grant set, and the new test covers this path.
|
||||
- Descriptor-first validation and duplicate tool rejection preserved: satisfied. The existing undeclared contribution, tool-name mismatch, duplicate tool, background/service declaration, and worker materialization tests remain in place and passed in focused validation.
|
||||
- Built-in Task feature behavior unchanged: satisfied by diff scope and focused tests. Task descriptor/install behavior still reports no host authorities and installs the same Task tool/hook set.
|
||||
- No unrelated scope expansion: satisfied. The diff is limited to `crates/pod/src/feature.rs`; it does not introduce Ticket tools, Ticket backend authority grants, plugin loading, MCP, WASM/sandbox runtime, approval protocol, crate extraction, Hook behavior changes, Task behavior changes, or broad refactors.
|
||||
- Tests/docs/comments reflect the distinction: satisfied. Public comments and test names/assertions now consistently use host-authority terminology for this API surface, and tests explicitly cover contribution-only built-ins and host-authority-gated tools.
|
||||
- Validation sufficient: satisfied for this review. I reran focused validation and inspected the diff/source for the listed requirements.
|
||||
|
||||
## 4. Blockers
|
||||
|
||||
None.
|
||||
|
||||
## 5. Non-blockers / follow-ups
|
||||
|
||||
None required before merge.
|
||||
|
||||
Notes for later external-plugin work:
|
||||
|
||||
- `HostAuthorityGrantSet::grant_all(&descriptor.requested_host_authorities)` remains the existing builtin-only scaffold, not a real host policy/user approval resolver. This is unchanged and within this ticket's non-goals, but it must be replaced before enabling untrusted external plugins.
|
||||
- `HostAuthorityRequest::required` versus `optional` remains future-facing under the current grant-all scaffold. No behavior change is introduced here.
|
||||
|
||||
## 6. Validation assessed or rerun
|
||||
|
||||
Rerun from `/home/hare/Projects/yoi/.worktree/feature-api-authority-separation`:
|
||||
|
||||
- `git diff --check develop...HEAD` — passed.
|
||||
- `cargo test -p pod feature --lib` — passed: 33 passed, 0 failed, 252 filtered out.
|
||||
|
||||
Additional inspection:
|
||||
|
||||
- Reviewed ticket and delegation intent.
|
||||
- Reviewed `git diff develop...HEAD`.
|
||||
- Confirmed the implementation diff touches only `crates/pod/src/feature.rs`.
|
||||
- Searched Rust sources for the old generic authority names and found no live-code API leftovers, only new host-authority names or historical work-item text outside source.
|
||||
- Checked worktree status after validation; no tracked changes.
|
||||
|
||||
Not rerun:
|
||||
|
||||
- Full workspace checks, broader package tests, `./tickets.sh doctor`, and `nix build .#yoi --no-link` were not rerun for this focused external review.
|
||||
|
||||
## 7. Residual risk
|
||||
|
||||
Residual risk is low for this ticket. The change is mostly API naming plus tests, and focused validation passed. The main remaining risk is pre-existing: the feature registry still automatically grants requested host authorities, so it is not yet a real external-plugin authority enforcement layer. That risk is explicitly outside this ticket's implementation scope and does not block this host-authority naming clarification.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: implementation_report author: hare at: 2026-06-05T05:09:37Z -->
|
||||
|
||||
## Implementation report
|
||||
|
||||
# Implementation report: feature-api-authority-separation
|
||||
|
||||
## Worktree / branch
|
||||
|
||||
- Worktree: `/home/hare/Projects/yoi/.worktree/feature-api-authority-separation`
|
||||
- Branch: `work/feature-api-authority-separation`
|
||||
|
||||
## Commit
|
||||
|
||||
- `4fc361f refactor: name feature host authorities explicitly`
|
||||
|
||||
## Summary
|
||||
|
||||
Clarified the `pod::feature` authority boundary by renaming the generic authority API surface to explicit host-authority terminology. This keeps feature contribution declarations separate from host-mediated capability grants and prepares the API for later Ticket built-in tools without framing internal built-ins as external plugin package grants.
|
||||
|
||||
## Exact renames
|
||||
|
||||
- `AuthorityRequest` -> `HostAuthorityRequest`
|
||||
- `AuthorityGrantSet` -> `HostAuthorityGrantSet`
|
||||
- `AuthorityDenial` -> `HostAuthorityDenial`
|
||||
- `FeatureDescriptor::requested_authorities` -> `requested_host_authorities`
|
||||
- `FeatureDescriptor::with_authority` -> `with_host_authority`
|
||||
- `ToolContribution::required_authorities` -> `required_host_authorities`
|
||||
- `ToolContribution::with_required_authorities` -> `with_required_host_authorities`
|
||||
- `FeatureInstallReport::granted_authorities` -> `host_authority_grants`
|
||||
- `FeatureInstallContext::grants()` -> `host_authority_grants()`
|
||||
- `FeatureInstallError::AuthorityDenied` -> `HostAuthorityDenied`
|
||||
- Internal helpers/diagnostics now use host-authority terminology where applicable.
|
||||
|
||||
## Changed files
|
||||
|
||||
- `crates/pod/src/feature.rs`
|
||||
|
||||
## Behavior
|
||||
|
||||
Preserved:
|
||||
|
||||
- descriptor-first validation;
|
||||
- duplicate tool rejection;
|
||||
- undeclared contribution rejection;
|
||||
- missing required host authority install failure;
|
||||
- built-in Task feature behavior;
|
||||
- contribution-only built-in feature installation without host authority grants.
|
||||
|
||||
Added/updated tests and comments to make explicit that contributing a tool/hook/background/service descriptor is not itself a host authority grant, while per-tool host authority requirements still require a corresponding granted requested host authority.
|
||||
|
||||
## Validation
|
||||
|
||||
Coder-reported validation passed:
|
||||
|
||||
- `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`
|
||||
- `nix build .#yoi --no-link`
|
||||
|
||||
Reviewer-rerun validation passed:
|
||||
|
||||
- `git diff --check develop...HEAD`
|
||||
- `cargo test -p pod feature --lib`
|
||||
|
||||
## Review status
|
||||
|
||||
External sibling reviewer approved with no blockers and no required non-blockers before merge.
|
||||
|
||||
## Unresolved risks / follow-ups
|
||||
|
||||
The existing `HostAuthorityGrantSet::grant_all(&descriptor.requested_host_authorities)` behavior remains a builtin-only scaffold, not a real external plugin approval resolver. This is unchanged and explicitly outside this ticket's scope.
|
||||
|
||||
## Ready for merge
|
||||
|
||||
Yes. This clears the API naming prerequisite for `ticket-built-in-feature-tools`.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: close author: hare at: 2026-06-05T05:11:56Z status: closed -->
|
||||
|
||||
## Closed
|
||||
|
||||
Feature API authority separation is complete and merged.
|
||||
|
||||
Implementation:
|
||||
|
||||
- `4fc361f refactor: name feature host authorities explicitly`
|
||||
- merge commit: `b46ea65 merge: clarify feature host authorities`
|
||||
|
||||
Summary:
|
||||
|
||||
- Renamed the generic feature authority API surface to explicit host-authority terminology:
|
||||
- `AuthorityRequest` -> `HostAuthorityRequest`
|
||||
- `AuthorityGrantSet` -> `HostAuthorityGrantSet`
|
||||
- `AuthorityDenial` -> `HostAuthorityDenial`
|
||||
- `requested_authorities` -> `requested_host_authorities`
|
||||
- `required_authorities` -> `required_host_authorities`
|
||||
- `granted_authorities` -> `host_authority_grants`
|
||||
- `grants()` -> `host_authority_grants()`
|
||||
- `FeatureInstallError::AuthorityDenied` -> `HostAuthorityDenied`
|
||||
- Preserved descriptor-first validation, duplicate tool rejection, undeclared contribution rejection, missing host-authority install failure, and built-in Task feature behavior.
|
||||
- Added/updated tests/comments to make contribution declarations separate from host authority grants.
|
||||
- Did not implement Ticket tools, external plugin loading, approval/resume protocol, MCP, WASM/sandbox runtime, feature crate extraction, Hook behavior changes, or Task behavior changes.
|
||||
|
||||
Review:
|
||||
|
||||
- External sibling reviewer approved with no blockers and no required non-blockers.
|
||||
- Residual note: `HostAuthorityGrantSet::grant_all(&descriptor.requested_host_authorities)` remains the existing builtin-only scaffold, not a real external-plugin approval resolver. This is unchanged and remains future work.
|
||||
|
||||
Post-merge validation passed:
|
||||
|
||||
- `cargo test -p pod feature --lib`
|
||||
- `cargo test -p pod task --lib`
|
||||
- `cargo test -p pod --lib`
|
||||
- `cargo test -p llm-worker --lib`
|
||||
- `cargo fmt --check`
|
||||
- `git diff --check`
|
||||
- `./tickets.sh doctor`
|
||||
- `cargo check --workspace --all-targets`
|
||||
- `nix build .#yoi --no-link`
|
||||
|
||||
This clears the API naming prerequisite for `ticket-built-in-feature-tools`.
|
||||
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user