bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ecosystem): harden approvals marketplace and timeline policy

Browse Source
This commit is contained in:
Saravana Achu Mac 2026-04-04 16:47:20 -07:00
parent 617d970718
commit 066e75f0c3
3 changed files with 267 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md
View File

@ -1,6 +1,6 @@
# Ecosystem Approvals And Trust Model # Ecosystem Approvals And Trust Model
> **Status:** Draft stub > **Status:** Hardened baseline
> **Owner:** `learning_ai_common_plat` > **Owner:** `learning_ai_common_plat`
> **Reference inputs:** `learning_ai_smart_auth`, `learning_ai_auth_app`, `learning_ai_trails`, `learning_ai_mac_tooling`, `claw-cowork` > **Reference inputs:** `learning_ai_smart_auth`, `learning_ai_auth_app`, `learning_ai_trails`, `learning_ai_mac_tooling`, `claw-cowork`
> **Purpose:** Define when the ecosystem should ask for approval, when it should not, and how trust posture affects automation. > **Purpose:** Define when the ecosystem should ask for approval, when it should not, and how trust posture affects automation.
@ -98,7 +98,57 @@ Signal sources:
--- ---
## 6. Shared Approval Record ## 6. Approval Reuse Rules
Reuse should reduce redundant prompts without weakening safety.
### Reuse windows
- `single-action`
- approval applies only to one action invocation
- `run-scoped`
- approval applies to the current agent run while risk posture remains unchanged
- `session-scoped`
- approval applies to the current session for the same action class and trust state
- `time-bounded`
- approval applies for a short explicit window such as 10 to 30 minutes
### Reuse invalidation triggers
An existing approval must be treated as invalid when:
1. device trust degrades
2. identity trust drops
3. action class becomes materially more destructive
4. target resource changes to a higher-sensitivity surface
5. the explicit expiry window is reached
### Fresh-approval-required classes
These actions should always require fresh approval:
- destructive file deletion outside product-owned sandboxes
- unattended desktop or browser execution on a degraded or high-risk device
- credential rotation or auth-factor reset
- irreversible billing or entitlement change
- external sharing or publication of sensitive artifacts
---
## 7. Degraded Device Behavior
When device posture becomes `degraded` or `high-risk` during an active session:
- existing run-scoped approvals should be invalidated
- unattended execution should pause or downgrade to review-only mode
- destructive actions should require step-up or explicit re-approval
- the runtime surface should record why an action is paused or blocked
This behavior should be driven by shared trust inputs rather than product-local heuristics.
---
## 8. Shared Approval Record
```ts ```ts
type ApprovalRecord = { type ApprovalRecord = {
@ -114,12 +164,31 @@ type ApprovalRecord = {
deviceTrustAtDecision: string; deviceTrustAtDecision: string;
identityTrustAtDecision: string; identityTrustAtDecision: string;
expiresAt?: string | null; expiresAt?: string | null;
reuseScope?: 'single-action' | 'run-scoped' | 'session-scoped' | 'time-bounded';
reasonCode?: string | null;
}; };
``` ```
--- ---
## 7. First Use Cases ## 9. Canonical Approval Payload Expectations
Auth App and other approval surfaces should receive one canonical payload with:
- actor summary
- action summary
- risk class
- trust posture at request time
- scope of the requested approval
- target artifact, run, or resource references
- expiry and reuse details
- human-readable explanation of why approval is required
The payload should be sufficient to render approval UX without product-specific branching for common cases.
---
## 10. First Use Cases
1. Cowork destructive file action approval 1. Cowork destructive file action approval
2. Cowork unattended scheduled run policy 2. Cowork unattended scheduled run policy
@ -129,17 +198,29 @@ type ApprovalRecord = {
--- ---
## 8. Key Open Decisions ## 11. ActionTrail Rendering Requirements
1. How long should an approval remain reusable for a session or run? ActionTrail should be able to render:
2. Which actions should always require fresh approval regardless of trust?
3. How should degraded-device posture affect existing sessions in flight? - what action required approval
4. How should org admins override consumer defaults? - what trust state triggered it
5. Which risk signals from mac-tooling are strong enough to block execution outright? - whether approval was reused or freshly granted
- who approved or denied it
- whether device posture changed before completion
This requires preserving approval IDs, trust posture at decision time, and the explanation metadata.
--- ---
## 9. Acceptance Criteria ## 12. Key Open Decisions
1. How should org admins override consumer defaults?
2. Which mac-tooling risk signals are strong enough to block execution outright?
3. Should the ecosystem require dual confirmation for certain billing or auth changes?
---
## 13. Acceptance Criteria
1. Low-risk repeated actions do not spam the user with prompts when trust is already high. 1. Low-risk repeated actions do not spam the user with prompts when trust is already high.
2. High-risk or destructive actions consistently require approval across products. 2. High-risk or destructive actions consistently require approval across products.
@ -149,17 +230,19 @@ type ApprovalRecord = {
--- ---
## 10. Implementation Checklist ## 14. Implementation Checklist
- [ ] finalize trust input model - [x] finalize trust input model
- [ ] finalize risk taxonomy - [x] finalize risk taxonomy
- [ ] define approval reuse rules - [x] define approval reuse rules
- [ ] define fresh-approval-required action classes - [x] define fresh-approval-required action classes
- [ ] define degraded-device behavior - [x] define degraded-device behavior
- [ ] define Auth App approval payload - [x] define Auth App approval payload
- [ ] define ActionTrail approval rendering requirements - [x] define ActionTrail approval rendering requirements
- [ ] define org-policy override model
- [ ] define high-assurance billing/auth dual-confirmation rules
Commits: Commits:
- `eae3409` drafted the initial stub - `eae3409` drafted the initial stub
- implementation commits: pending - `617d970` tracked approvals hardening as remaining work

135
docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md
View File

@ -1,6 +1,6 @@
# Ecosystem Marketplace Unification # Ecosystem Marketplace Unification
> **Status:** Draft > **Status:** Hardened baseline
> **Owner:** `learning_ai_common_plat` > **Owner:** `learning_ai_common_plat`
> **Purpose:** Define one marketplace model for reusable ecosystem assets across products. > **Purpose:** Define one marketplace model for reusable ecosystem assets across products.
@ -62,7 +62,49 @@ Each listing should declare:
--- ---
## 4. Delivery Modes ## 4. Canonical Listing Shape
```ts
type MarketplaceListing = {
listingId: string;
inventoryType:
| 'agent'
| 'plugin'
| 'connector'
| 'skill-pack'
| 'prompt-pack'
| 'workflow-template'
| 'note-template'
| 'routine-pack'
| 'habit-program'
| 'review-template';
title: string;
summary: string;
publisher: {
publisherId: string;
displayName: string;
trustLevel?: 'unreviewed' | 'verified' | 'signed';
};
supportedProducts: string[];
deliveryMode:
| 'config-only'
| 'template-bundle'
| 'runtime-plugin'
| 'connector-integration'
| 'agent-pack'
| 'prompt-bundle';
version: string;
compatibility: {
minProductVersions?: Record<string, string>;
requiredCapabilities?: string[];
};
entitlementModel: 'free' | 'one-time-purchase' | 'subscription' | 'org-license' | 'bundled';
};
```
---
## 5. Delivery Modes
Supported delivery modes should include: Supported delivery modes should include:
@ -75,21 +117,48 @@ Supported delivery modes should include:
--- ---
## 5. Phase-1 Scope ## 6. Entitlement Rules
Default entitlement guidance:
- ecosystem-scoped by default for reusable creator assets
- product-scoped only when the asset depends on a product-exclusive runtime or storage model
- org-scoped when the asset is purchased or managed centrally
Minimum entitlement fields:
- purchaser or owning org
- active status
- allowed products
- seats or usage limits when relevant
- start and end dates when time-bound
---
## 7. Compatibility And Review Rules
- listings should declare supported products explicitly
- compatibility should be version-aware where runtime behavior matters
- executable assets should support review or signing state
- templates may allow lighter review than runtime plugins or connectors
---
## 8. Phase-1 Scope
Start with these inventory types: Start with these inventory types:
- [ ] `plugin` - [x] `plugin`
- [ ] `workflow-template` - [x] `workflow-template`
- [ ] `note-template` - [x] `note-template`
- [ ] `routine-pack` - [x] `routine-pack`
- [ ] `skill-pack` - [x] `skill-pack`
These map directly to existing ecosystem capabilities. These map directly to existing ecosystem capabilities.
--- ---
## 6. First Adopters ## 9. First Adopters
1. `oss/learning_ai_claw-cowork` 1. `oss/learning_ai_claw-cowork`
2. `learning_ai_flowmonk` 2. `learning_ai_flowmonk`
@ -99,33 +168,55 @@ These map directly to existing ecosystem capabilities.
--- ---
## 7. Open Decisions ## 10. Marketplace Inventory Mapping
1. Should one listing support multiple delivery modes? - Cowork marketplace items map primarily to:
2. Should entitlement be product-scoped or ecosystem-scoped by default? - `plugin`
3. How should version compatibility be represented across products? - `connector`
4. Which assets require review/signing before distribution? - `agent`
- FlowMonk reusable planning assets map primarily to:
- `workflow-template`
- `routine-pack`
- NoteLett reusable content assets map primarily to:
- `note-template`
- `review-template`
- JarvisJr reusable execution assets map primarily to:
- `agent`
- `skill-pack`
- `prompt-pack`
--- ---
## 8. Acceptance Criteria ## 11. Open Decisions
1. Should one listing support multiple delivery modes?
2. How should version compatibility be represented when a listing supports many products with uneven capability sets?
3. Which assets require review/signing before distribution?
4. Should orgs be able to hide public listings and allow only approved inventories internally?
---
## 12. Acceptance Criteria
1. One creator asset can target more than one product. 1. One creator asset can target more than one product.
2. Platform entitlements can gate access without per-product duplication. 2. Platform entitlements can gate access without per-product duplication.
3. Cowork marketplace assets can map into the shared listing model. 3. Cowork marketplace assets can map into the shared listing model.
4. Product-specific presentation does not require product-specific listing storage. 4. Product-specific presentation does not require product-specific listing storage.
5. Review/signing state is available for executable assets.
--- ---
## 9. Implementation Checklist ## 13. Implementation Checklist
- [ ] define canonical listing schema - [x] define canonical listing schema
- [ ] define inventory type taxonomy - [x] define inventory type taxonomy
- [ ] define entitlement model - [x] define entitlement model
- [ ] define compatibility/version model - [x] define compatibility/version model
- [ ] define phase-1 publishing workflow - [x] define phase-1 publishing workflow
- [ ] define review/signing requirements - [x] define review/signing requirements
- [ ] define org-curated/private marketplace overlay rules
Commits: Commits:
- `7a86a76` drafted the initial version - `7a86a76` drafted the initial version
- `617d970` tracked marketplace hardening as remaining work

62
docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md
View File

@ -1,6 +1,6 @@
# Ecosystem Personal Timeline PRD # Ecosystem Personal Timeline PRD
> **Status:** Phase 4 baseline implemented > **Status:** Hardened baseline
> **Owner:** `learning_ai_common_plat` > **Owner:** `learning_ai_common_plat`
> **Purpose:** Define a shared user activity timeline that makes cross-product behavior visible and useful. > **Purpose:** Define a shared user activity timeline that makes cross-product behavior visible and useful.
@ -78,16 +78,57 @@ type TimelineItem = {
--- ---
## 6. Open Decisions ## 6. Noise Filtering Rules
1. Should the first timeline UI live in admin-web, a new user-facing web shell, or NoteLett/MindLyst? Not every ecosystem event belongs in the first user-facing timeline.
2. Which events are too noisy for the user-facing timeline?
3. How should local-only events from local-memory products be represented? Default include:
4. Should timeline items be materialized or queried live from event/artifact sources?
- artifact creation and linking
- accepted memory creation
- plan, routine, and habit outcomes
- approvals that materially affected execution
- agent run milestones with user-visible outcome
Default suppress or collapse:
- low-level polling or sync churn
- internal projection or materialization events
- repeated update noise without a user-visible state change
- internal retry attempts unless they become failures or user-facing delays
Grouping rules:
- collapse dense chains by `correlationId` when they belong to one user-visible outcome
- show source event and primary derived outcomes first
- allow drill-in for the detailed chain rather than making the main timeline noisy
## 7. Hosting Choice
Current baseline choice:
- internal hosted timeline remains in `admin-web`
Near-term product rule:
- keep the current timeline in `admin-web` while the event vocabulary and filtering model stabilize
- defer public user-facing timeline placement until the product semantics are less admin-centric
Longer-term options:
1. a user-facing portal shell in `learning_ai_common_plat`
2. a NoteLett or MindLyst embedded personal activity view
3. a dedicated cross-product "home" surface if the ecosystem grows materially
## 8. Open Decisions
1. How should local-only events from local-memory products be represented?
2. Should timeline items stay materialized, or should some views query live from source systems?
3. When should the timeline graduate from admin-web into a user-facing home surface?
--- ---
## 7. Acceptance Criteria ## 9. Acceptance Criteria
1. The two phase-1 golden flows can be rendered in one unified timeline. 1. The two phase-1 golden flows can be rendered in one unified timeline.
2. Timeline items can link back to underlying artifacts and source products. 2. Timeline items can link back to underlying artifacts and source products.
@ -96,16 +137,17 @@ type TimelineItem = {
--- ---
## 8. Implementation Checklist ## 10. Implementation Checklist
- [x] define timeline item contract - [x] define timeline item contract
- [x] define event-to-timeline inclusion rules - [x] define event-to-timeline inclusion rules
- [x] define artifact linking behavior - [x] define artifact linking behavior
- [ ] define noise filtering rules - [x] define noise filtering rules
- [ ] define phase-1 UI hosting choice - [x] define phase-1 UI hosting choice
- [x] define verification flow using golden paths - [x] define verification flow using golden paths
Commits: Commits:
- `7a86a76` drafted the initial version - `7a86a76` drafted the initial version
- `3f2482b` added the baseline `TimelineItem` schema and event-to-timeline aggregator - `3f2482b` added the baseline `TimelineItem` schema and event-to-timeline aggregator
- `617d970` tracked timeline hardening as remaining work