agentic-orchestrator 0.1.6 → 0.1.8

package/spec-files/outstanding/agentic_orchestrator_productization_commercial_spec.md

@@ -14,6 +14,7 @@
 ### 0.1 Required Standards
 
 All implementation MUST preserve:
+
 - deterministic kernel behavior and normalized error envelopes
 - local execution viability when cloud/commercial services are unavailable
 - MCP/in-process transport parity for tool contracts
@@ -23,6 +24,7 @@ All implementation MUST preserve:
 ### 0.2 Required Upstream Inputs
 
 Implementing agents MUST read:
+
 - `README.md`
 - `spec-files/outstanding/agentic_orchestrator_quality_adoption_execution_spec.md`
 - `spec-files/outstanding/agentic_orchestrator_enterprise_governance_dashboard_spec.md`
@@ -49,6 +51,7 @@ Implementing agents MUST read:
 ### 0.3 Feature Scope
 
 This spec implements:
+
 - **P1** Product packaging and entitlement model
 - **P2** Workspace identity and cloud connectivity (`auth`, `whoami`, workspace binding)
 - **P3** Entitlement enforcement and offline cache semantics
@@ -57,6 +60,7 @@ This spec implements:
 - **P6** Team/enterprise dashboard capabilities and tenant-aware APIs
 
 Out of scope:
+
 - fully automated sales/CRM workflows
 - payment processor selection lock-in (Stripe is default implementation target, not protocol requirement)
 - replacing local `.aop/**` as source of truth
@@ -68,6 +72,7 @@ Out of scope:
 ### 1.1 Free vs Paid Value Boundary
 
 Customers do not pay for basic local orchestration. They pay for organizational risk reduction and operational scale:
+
 - durable audit history across runs/repos/teams
 - enterprise identity, authorization, and compliance evidence
 - usage analytics, cost controls, and executive reporting
@@ -75,15 +80,16 @@ Customers do not pay for basic local orchestration. They pay for organizational
 
 ### 1.2 Product Packaging (Normative)
 
-| Tier | Primary Buyer | Included Capabilities | Technical Gate |
-|---|---|---|---|
-| Community (Free) | Individual devs | Local deterministic orchestration, local dashboard, local `.aop` artifacts | `product.mode=community` |
-| Team (Paid) | Eng managers | Multi-user workspace, hosted artifact retention, trend analytics, shared dashboard | `entitlements.features.team_workspace=true` |
+| Tier              | Primary Buyer     | Included Capabilities                                                                     | Technical Gate                                   |
+| ----------------- | ----------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Community (Free)  | Individual devs   | Local deterministic orchestration, local dashboard, local `.aop` artifacts                | `product.mode=community`                         |
+| Team (Paid)       | Eng managers      | Multi-user workspace, hosted artifact retention, trend analytics, shared dashboard        | `entitlements.features.team_workspace=true`      |
 | Enterprise (Paid) | Platform/security | SSO/SAML/OIDC, SCIM, compliance exports, policy packs, long retention, private deployment | `entitlements.features.enterprise_controls=true` |
 
 ### 1.3 Billable Dimensions
 
 Billing MUST be derivable from deterministic metering events:
+
 - `active_seats` (distinct active users per billing period)
 - `orchestrated_runs` (count of completed run IDs)
 - `artifact_storage_gb_month` (hosted storage footprint)
@@ -95,26 +101,32 @@ Billing MUST be derivable from deterministic metering events:
 ## 2. Architectural Critique of Current State
 
 1. **No tenancy model**
+
 - Current runtime is repository-local with no first-class `organization/workspace/project` contract.
 - Result: no customer/account boundary for paid features.
 
 2. **No entitlement boundary in tool execution path**
+
 - `ToolRuntime.callTool()` enforces RBAC and schema, but not plan/tier entitlements.
 - Result: no deterministic paid feature gate.
 
 3. **No canonical usage-metering stream for billing**
+
 - Cost tracking exists per feature, but there is no auditable, periodized commercial usage event model.
 - Result: cannot invoice reliably.
 
 4. **Dashboard is filesystem-local and single-tenant**
+
 - Dashboard reads `.aop/**` directly via local API routes.
 - Result: cannot support paid multi-user workspace analytics without a hosted backend.
 
 5. **No customer auth lifecycle in CLI**
+
 - CLI has no login/whoami/workspace binding flow.
 - Result: no secure binding to subscription and entitlements.
 
 6. **Artifact persistence exists but is not yet monetization-connected**
+
 - Artifact publishing spec exists, but not tied to product plans, retention SKUs, or workspace-level access.
 - Result: technical capability without commercial control plane.
 
@@ -127,18 +139,22 @@ Billing MUST be derivable from deterministic metering events:
 Retain the current deterministic local control-plane as execution engine. Add an optional commercial control hub and sync plane.
 
 1. **Local Execution Plane (existing, enhanced)**
+
 - Runs orchestrator and writes canonical `.aop/**` artifacts.
 - Emits usage events and optional cloud-sync batches.
 
 2. **Commercial Control Hub (new)**
+
 - Multi-tenant API for auth, workspaces, entitlements, usage ingest, artifact indexing, and billing summaries.
 - Can be hosted SaaS or self-hosted enterprise deployment.
 
 3. **Entitlement Cache Layer (new, local)**
+
 - Local signed entitlement snapshot with TTL + grace behavior.
 - Ensures paid features can be enforced deterministically even during temporary cloud outages.
 
 4. **Billing/Metering Pipeline (new)**
+
 - Usage event ingestion -> aggregation -> invoice line item derivation.
 
 ### 3.2 Non-Negotiable Boundary Rules
@@ -161,20 +177,20 @@ innovation:
   commercial_productization: false
 
 product:
-  mode: community               # community | team | enterprise
+  mode: community # community | team | enterprise
   cloud:
     enabled: false
-    endpoint: ""
-    workspace_id: ""
+    endpoint: ''
+    workspace_id: ''
     api_token_env: AOP_CLOUD_API_TOKEN
-    sync_mode: best_effort      # best_effort | required
+    sync_mode: best_effort # best_effort | required
     sync_triggers:
-      - post_run                # post_run | manual
+      - post_run # post_run | manual
   entitlements:
     enabled: false
     cache_ttl_seconds: 900
     grace_period_hours: 168
-    fail_mode: grace_then_block_paid   # allow_cached | grace_then_block_paid
+    fail_mode: grace_then_block_paid # allow_cached | grace_then_block_paid
   metering:
     enabled: false
     flush_interval_seconds: 60
@@ -184,6 +200,7 @@ product:
 ```
 
 Normative behavior:
+
 - all productization toggles default off
 - `product.mode=community` implies no paid-only enforcement
 - if `product.mode in {team, enterprise}`, `entitlements.enabled=true` is required
@@ -223,6 +240,7 @@ Contract:
 ```
 
 Rules:
+
 - snapshot must be signed by control hub key and verified locally
 - expired snapshot inside grace can run with warning; outside grace paid features block
 - missing snapshot in team/enterprise mode returns explicit entitlement error for paid operations
@@ -260,6 +278,7 @@ Event contract:
 ```
 
 Rules:
+
 - `event_id` must be deterministic (UUIDv7 allowed; stable dedupe key must also be emitted)
 - flush must be idempotent with server-side dedupe key `(workspace_id,event_id)`
 - local writes are append-only and never block core tool execution in best-effort mode
@@ -292,18 +311,23 @@ Checkpoint contract:
 ## 4.5 New Tool Surface
 
 1. `entitlements.get` (read-only)
+
 - returns active entitlement snapshot and effective capability matrix.
 
 2. `usage.summary_get` (read-only)
+
 - returns local and remote usage summary for current workspace/project.
 
 3. `artifacts.sync_remote` (mutating)
+
 - pushes run artifacts and usage events to control hub.
 
 4. `billing.subscription_get` (read-only)
+
 - returns plan, period usage, and overage status.
 
 Required wiring for all tools:
+
 - `apps/control-plane/src/core/constants.ts`
 - `apps/control-plane/src/core/kernel.ts`
 - `apps/control-plane/src/application/tools/tool-metadata.ts`
@@ -316,6 +340,7 @@ Required wiring for all tools:
 ## 4.6 CLI Surface Changes
 
 Add commands:
+
 - `aop auth login --endpoint <url> --workspace <id> [--token-env <ENV>]`
 - `aop auth whoami`
 - `aop auth logout`
@@ -324,6 +349,7 @@ Add commands:
 - `aop billing [--json]`
 
 Required CLI wiring:
+
 - `apps/control-plane/src/cli/types.ts`
 - `apps/control-plane/src/cli/cli-argument-parser.ts`
 - `apps/control-plane/src/cli/help-command-handler.ts`
@@ -333,6 +359,7 @@ Required CLI wiring:
 ## 4.7 Error Code Additions
 
 Add to `apps/control-plane/src/core/error-codes.ts`:
+
 - `entitlement_required`
 - `entitlement_cache_missing`
 - `entitlement_signature_invalid`
@@ -350,9 +377,11 @@ Add to `apps/control-plane/src/core/error-codes.ts`:
 ## CP0: Contract Scaffolding and Feature Flags
 
 ### Goals
+
 - add policy/schema/tool/CLI scaffolding with defaults off
 
 ### File Targets
+
 - `agentic/orchestrator/defaults/policy.defaults.yaml`
 - `agentic/orchestrator/schemas/policy.schema.json`
 - `agentic/orchestrator/schemas/policy.user.schema.json`
@@ -363,10 +392,12 @@ Add to `apps/control-plane/src/core/error-codes.ts`:
 - `agentic/orchestrator/tools.md`
 
 ### Mandatory Checks
+
 - `npm run validate:mcp-contracts`
 - `npm run validate:architecture`
 
 Exit criteria:
+
 - policy loads with new fields
 - tool catalog/schemas/docs are consistent
 
@@ -379,6 +410,7 @@ Exit criteria:
 Introduce a control-hub client and local credential binding.
 
 ### Implementation Targets
+
 - `apps/control-plane/src/application/services/cloud-auth-service.ts` (new)
 - `apps/control-plane/src/application/services/workspace-binding-service.ts` (new)
 - `apps/control-plane/src/cli/auth-command-handler.ts` (new)
@@ -386,15 +418,18 @@ Introduce a control-hub client and local credential binding.
 - `.aop/runtime/cloud-auth/session.json` contract helper in `path-layout.ts`
 
 ### Rules
+
 - credentials never stored in plaintext if token env indirection exists
 - `whoami` reads from validated local session + optional remote refresh
 - auth failures must not break non-commercial local operations
 
 ### Tests
+
 - `apps/control-plane/test/cloud-auth-service.spec.ts` (new)
 - `apps/control-plane/test/cli.unit.spec.ts` auth parser/help coverage
 
 Exit criteria:
+
 - `auth login/whoami/logout` deterministic and tested
 
 ---
@@ -406,22 +441,26 @@ Exit criteria:
 Enforce paid features through a central entitlement service queried by tool runtime and selected CLI paths.
 
 ### Implementation Targets
+
 - `apps/control-plane/src/application/services/entitlement-service.ts` (new)
 - `apps/control-plane/src/mcp/tool-runtime.ts` (pre-execution entitlement gate)
 - `apps/control-plane/src/application/tools/tool-metadata.ts` (required entitlement tag per paid tool)
 - `apps/control-plane/src/core/kernel.ts` (tool wrappers where needed)
 
 ### Rules
+
 - entitlement checks apply only to paid operations
 - core orchestration commands remain accessible in community mode
 - grace behavior driven solely by policy + cache timestamps
 
 ### Tests
+
 - `apps/control-plane/test/entitlement-service.spec.ts` (new)
 - extend `apps/control-plane/test/tool-runtime.spec.ts`
 - extend `apps/control-plane/test/mcp.spec.ts` for entitlement failures and parity
 
 Exit criteria:
+
 - paid tool calls blocked deterministically when not entitled
 - no regressions in community flow
 
@@ -434,6 +473,7 @@ Exit criteria:
 Emit deterministic usage events from runtime boundaries and flush in batches.
 
 ### Implementation Targets
+
 - `apps/control-plane/src/application/services/usage-metering-service.ts` (new)
 - `apps/control-plane/src/mcp/tool-runtime.ts` (tool invocation events)
 - `apps/control-plane/src/supervisor/run-coordinator.ts` (run lifecycle events)
@@ -441,15 +481,18 @@ Emit deterministic usage events from runtime boundaries and flush in batches.
 - `apps/control-plane/src/cli/usage-command-handler.ts` (new)
 
 ### Rules
+
 - event writes append-only and non-blocking by default
 - dedupe keys required on remote flush
 - local summary always available even when cloud is unavailable
 
 ### Tests
+
 - `apps/control-plane/test/usage-metering-service.spec.ts` (new)
 - integration test for end-to-end run event emission
 
 Exit criteria:
+
 - usage events generated for run start/end, tool invocations, gate execution
 - local summary and remote flush both deterministic
 
@@ -462,21 +505,25 @@ Exit criteria:
 Build on artifact publishing to support control-hub sync and retention-aware indexing.
 
 ### Implementation Targets
+
 - `apps/control-plane/src/application/services/artifact-publisher-service.ts` (extend)
 - `apps/control-plane/src/application/services/cloud-sync-service.ts` (new)
 - `apps/control-plane/src/cli/cloud-sync-command-handler.ts` (new)
 - `apps/control-plane/src/cli/run-command-handler.ts` (post-run sync trigger)
 
 ### Rules
+
 - `sync_mode=best_effort` must not fail base run completion
 - `sync_mode=required` fails paid sync action only, with explicit error
 - checkpoints guarantee idempotent retries
 
 ### Tests
+
 - `apps/control-plane/test/cloud-sync-service.spec.ts` (new)
 - extend run-command tests for post-run sync outcomes
 
 Exit criteria:
+
 - remote sync supports full run + retry without duplicate logical records
 
 ---
@@ -488,20 +535,24 @@ Exit criteria:
 Enable workspace-scoped views and paid analytics in dashboard APIs/UI.
 
 ### Implementation Targets
+
 - `packages/web-dashboard/src/lib/aop-client.ts`
 - `packages/web-dashboard/src/lib/types.ts`
 - `packages/web-dashboard/src/app/api/*` routes for workspace/billing/usage
 - `packages/web-dashboard/src/app/page.tsx` (workspace selector, paid analytics cards)
 
 ### Rules
+
 - paid panels hidden when entitlement absent
 - APIs enforce workspace identity server-side, not only UI checks
 
 ### Tests
+
 - dashboard API integration tests for workspace isolation
 - UI tests for entitlement-conditioned rendering
 
 Exit criteria:
+
 - team dashboards show cross-run metrics and audit trend views per workspace
 
 ---
@@ -513,6 +564,7 @@ Exit criteria:
 Introduce a new multi-tenant backend service inside this monorepo.
 
 ### New Workspace Targets
+
 - `apps/control-hub-api/` (new)
 - `apps/control-hub-api/src/auth/*`
 - `apps/control-hub-api/src/tenancy/*`
@@ -523,6 +575,7 @@ Introduce a new multi-tenant backend service inside this monorepo.
 - `apps/control-hub-api/src/db/migrations/*`
 
 ### Minimum API Contract
+
 - `GET /v1/whoami`
 - `GET /v1/entitlements/current`
 - `POST /v1/usage/events:ingest`
@@ -530,6 +583,7 @@ Introduce a new multi-tenant backend service inside this monorepo.
 - `GET /v1/billing/subscription`
 
 ### Data Model (Minimum)
+
 - `organizations`
 - `workspaces`
 - `projects`
@@ -541,6 +595,7 @@ Introduce a new multi-tenant backend service inside this monorepo.
 - `artifact_runs`
 
 ### Exit criteria
+
 - control-plane can authenticate and sync against control-hub in staging
 - metering and entitlement endpoints are production-safe with tenant isolation tests
 
@@ -549,17 +604,20 @@ Introduce a new multi-tenant backend service inside this monorepo.
 ## CP7: Rollout, Migration, and Commercial Readiness
 
 ### Rollout Phases
+
 1. Internal dogfood: community mode + optional auth only.
 2. Pilot customers: team mode with best-effort sync and warning-only overage.
 3. Paid GA: required entitlement checks for paid operations, invoicing enabled.
 4. Enterprise GA: SSO/SCIM/compliance controls enabled by entitlement.
 
 ### Migration Rules
+
 - existing repos require no config changes for community mode
 - `aop init --advanced-policy` adds product section templates
 - paid mode onboarding requires explicit `aop auth login` and workspace bind
 
 ### Rollback Rules
+
 - disable `innovation.commercial_productization` to return to community behavior
 - keep usage/artifact logs; do not delete commercial runtime artifacts on rollback
 
@@ -568,19 +626,23 @@ Introduce a new multi-tenant backend service inside this monorepo.
 ## 6. Test Strategy (Normative)
 
 ### 6.1 Unit Tests
+
 - entitlement signature and expiry/grace logic
 - metering event generation and dedupe keys
 - cloud sync checkpoint idempotency
 
 ### 6.2 Integration Tests
+
 - end-to-end paid flow: login -> entitlement fetch -> run -> usage flush -> artifact sync
 - tenant isolation: workspace A cannot read workspace B assets
 
 ### 6.3 Contract/Parity Tests
+
 - new tools validated in MCP and in-process modes
 - CLI commands parse/help/bootstrap coverage for `auth`, `cloud sync`, `usage`, `billing`
 
 ### 6.4 Regression Tests
+
 - community mode behavior unchanged when productization disabled
 - run completion unaffected by cloud outage in best-effort mode
 
@@ -602,18 +664,22 @@ Introduce a new multi-tenant backend service inside this monorepo.
 ## 8. Core Tradeoffs
 
 1. **Fail-open reliability vs revenue enforcement**
+
 - strict entitlement blocking improves monetization control but risks customer-facing outages.
 - chosen path: core execution always local-safe; paid operations enforce with TTL+grace.
 
 2. **Hosted convenience vs data sovereignty**
+
 - SaaS enables fast value but regulated customers need self-hosting.
 - chosen path: same APIs for hosted and enterprise self-hosted control-hub.
 
 3. **Metering granularity vs runtime overhead**
+
 - finer events improve billing accuracy but increase write/flush cost.
 - chosen path: bounded JSONL events, batched flush, deterministic aggregation.
 
 4. **Broad paywall vs trust/adoption**
+
 - over-gating core capabilities harms OSS adoption.
 - chosen path: keep deterministic orchestration free; monetize team governance, hosted retention, enterprise controls.
 
@@ -638,6 +704,7 @@ Introduce a new multi-tenant backend service inside this monorepo.
 ## 10. Definition of Done
 
 A completed implementation session for this program MUST provide:
+
 - phase-by-phase completion notes (CP0-CP7)
 - policy/schema/catalog/tool docs deltas and rationale
 - executed validation/test commands with outcomes