agentic-orchestrator 0.1.4 → 0.1.6

package/spec-files/outstanding/agentic_orchestrator_productization_commercial_spec.md

@@ -0,0 +1,645 @@
+# Feature Spec: Commercial Productization and Monetization Platform (AOP)
+
+> **Purpose of this document**: Define a concrete, implementation-ready path to turn Agentic-Orchestrator from a strong local tool into a product customers will pay for by adding team-scale governance, hosted audit durability, enterprise identity controls, and usage-based commercial operations.
+
+**Version:** 1.0  
+**Date:** 2026-03-04  
+**Status:** Draft (Productization Program)  
+**Roadmap Mapping:** M39-M44
+
+---
+
+## 0. Standards and Dependencies
+
+### 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
+- strict schema-driven policy evolution (`policy.schema.json`, `policy.user.schema.json`)
+- architecture boundary validation and contract validation (`validate:architecture`, `validate:mcp-contracts`)
+
+### 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`
+- `spec-files/outstanding/agentic_orchestrator_artifact_database_publishing_spec.md`
+- `apps/control-plane/src/mcp/tool-runtime.ts`
+- `apps/control-plane/src/mcp/operation-ledger.ts`
+- `apps/control-plane/src/application/tools/tool-metadata.ts`
+- `apps/control-plane/src/application/services/cost-tracking-service.ts`
+- `apps/control-plane/src/core/kernel.ts`
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/core/error-codes.ts`
+- `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`
+- `apps/control-plane/src/interfaces/cli/bootstrap.ts`
+- `agentic/orchestrator/defaults/policy.defaults.yaml`
+- `agentic/orchestrator/schemas/policy.schema.json`
+- `agentic/orchestrator/schemas/policy.user.schema.json`
+- `agentic/orchestrator/tools/catalog.json`
+- `packages/web-dashboard/src/lib/aop-client.ts`
+- `packages/web-dashboard/src/lib/types.ts`
+- `packages/web-dashboard/src/app/page.tsx`
+
+### 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
+- **P4** Usage metering and billing event pipeline
+- **P5** Hosted audit history sync (building on artifact publishing)
+- **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
+
+---
+
+## 1. Monetization Thesis (What Customers Pay For)
+
+### 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
+- managed reliability with entitlements, retention, and SLA-backed operations
+
+### 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` |
+| 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)
+- `artifact_retention_days` (retention tier)
+- optional overage dimension: `tool_invocations` beyond plan allowance
+
+---
+
+## 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.
+
+---
+
+## 3. Target Product Architecture
+
+### 3.1 Architecture Summary
+
+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
+
+- Core free orchestration (`run`, local gates, local artifacts) MUST remain functional without cloud.
+- Paid-only features MUST fail with explicit entitlement errors, never silent downgrades.
+- Entitlement and usage calculations MUST be deterministic from persisted events.
+- Billing logic MUST never mutate execution outcomes retroactively.
+
+---
+
+## 4. Contracts and Schema Deltas
+
+## 4.1 Policy Extensions (Defaults + User Schema + Full Schema)
+
+Add:
+
+```yaml
+innovation:
+  commercial_productization: false
+
+product:
+  mode: community               # community | team | enterprise
+  cloud:
+    enabled: false
+    endpoint: ""
+    workspace_id: ""
+    api_token_env: AOP_CLOUD_API_TOKEN
+    sync_mode: best_effort      # best_effort | required
+    sync_triggers:
+      - 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
+  metering:
+    enabled: false
+    flush_interval_seconds: 60
+    max_batch_size: 500
+  retention:
+    hosted_artifact_days: 30
+```
+
+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
+- `sync_mode=required` affects only paid sync operations, never base local run completion
+
+## 4.2 Entitlement Snapshot Contract
+
+Path:
+
+```text
+.aop/runtime/entitlements/cache.json
+```
+
+Contract:
+
+```json
+{
+  "workspace_id": "ws_123",
+  "plan": "team",
+  "fetched_at": "2026-03-04T10:00:00.000Z",
+  "expires_at": "2026-03-04T10:15:00.000Z",
+  "grace_expires_at": "2026-03-11T10:15:00.000Z",
+  "features": {
+    "team_workspace": true,
+    "hosted_audit_history": true,
+    "enterprise_controls": false,
+    "sso": false,
+    "scim": false
+  },
+  "limits": {
+    "max_seats": 25,
+    "max_projects": 50,
+    "artifact_retention_days": 30
+  },
+  "signature": "base64:..."
+}
+```
+
+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
+
+## 4.3 Usage Metering Event Contract
+
+Path:
+
+```text
+.aop/runtime/usage/events/<run_id>.jsonl
+.aop/runtime/usage/checkpoints/last_flush.json
+```
+
+Event contract:
+
+```json
+{
+  "event_id": "evt_01J...",
+  "ts": "2026-03-04T10:01:12.000Z",
+  "workspace_id": "ws_123",
+  "project_id": "proj_abc",
+  "run_id": "run:...",
+  "feature_id": "payment_retry_guard",
+  "event_type": "tool_invocation",
+  "dimensions": {
+    "tool_name": "repo.apply_patch",
+    "actor_type": "builder",
+    "result": "ok",
+    "latency_ms": 173
+  },
+  "billable_units": {
+    "tool_invocations": 1
+  }
+}
+```
+
+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
+
+## 4.4 Hosted Artifact Sync Contract
+
+This extends the artifact publishing foundation into commercial product behavior.
+
+Paths:
+
+```text
+.aop/runtime/cloud-sync/checkpoints/<run_id>.json
+.aop/runtime/cloud-sync/last_sync.json
+```
+
+Checkpoint contract:
+
+```json
+{
+  "run_id": "run:...",
+  "target": "control_hub",
+  "status": "succeeded",
+  "last_synced_at": "2026-03-04T10:09:00.000Z",
+  "artifact_count": 242,
+  "bytes_synced": 8172634,
+  "revision": 3
+}
+```
+
+## 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`
+- `agentic/orchestrator/tools/catalog.json`
+- `agentic/orchestrator/tools/schemas/input/*.json`
+- `agentic/orchestrator/tools/schemas/output/*.json`
+- RBAC in `policy.defaults.yaml`
+- regenerated `agentic/orchestrator/tools.md`
+
+## 4.6 CLI Surface Changes
+
+Add commands:
+- `aop auth login --endpoint <url> --workspace <id> [--token-env <ENV>]`
+- `aop auth whoami`
+- `aop auth logout`
+- `aop cloud sync [--run-id <id>|--latest] [--strict]`
+- `aop usage [--period current] [--json]`
+- `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`
+- `apps/control-plane/src/interfaces/cli/bootstrap.ts`
+- new handlers under `apps/control-plane/src/cli/*`
+
+## 4.7 Error Code Additions
+
+Add to `apps/control-plane/src/core/error-codes.ts`:
+- `entitlement_required`
+- `entitlement_cache_missing`
+- `entitlement_signature_invalid`
+- `entitlement_expired`
+- `cloud_auth_failed`
+- `cloud_workspace_unbound`
+- `cloud_sync_failed`
+- `metering_flush_failed`
+- `billing_overage_blocked`
+
+---
+
+## 5. Detailed Implementation Plan (Normative)
+
+## 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`
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/core/error-codes.ts`
+- `agentic/orchestrator/tools/catalog.json`
+- input/output schemas for new tools
+- `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
+
+---
+
+## CP1: Workspace Auth and Binding
+
+### Design
+
+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)
+- `apps/control-plane/src/cli/types.ts` / parser / bootstrap wiring
+- `.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
+
+---
+
+## CP2: Entitlement Engine and Enforcement
+
+### Design
+
+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
+
+---
+
+## CP3: Usage Metering Pipeline
+
+### Design
+
+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)
+- `apps/control-plane/src/application/services/cost-tracking-service.ts` (alignment with billable dimensions)
+- `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
+
+---
+
+## CP4: Hosted Artifact and Audit Sync
+
+### Design
+
+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
+
+---
+
+## CP5: Tenant-Aware Dashboard and Team Features
+
+### Design
+
+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
+
+---
+
+## CP6: Commercial Control Hub (New Service)
+
+### Design
+
+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/*`
+- `apps/control-hub-api/src/entitlements/*`
+- `apps/control-hub-api/src/metering/*`
+- `apps/control-hub-api/src/artifacts/*`
+- `apps/control-hub-api/src/billing/*`
+- `apps/control-hub-api/src/db/migrations/*`
+
+### Minimum API Contract
+- `GET /v1/whoami`
+- `GET /v1/entitlements/current`
+- `POST /v1/usage/events:ingest`
+- `POST /v1/artifacts/sync`
+- `GET /v1/billing/subscription`
+
+### Data Model (Minimum)
+- `organizations`
+- `workspaces`
+- `projects`
+- `memberships`
+- `subscriptions`
+- `entitlement_snapshots`
+- `usage_events`
+- `usage_aggregates`
+- `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
+
+---
+
+## 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
+
+---
+
+## 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
+
+---
+
+## 7. Acceptance Criteria
+
+1. Community users can run existing workflows unchanged with productization disabled.
+2. Team/enterprise mode requires valid workspace auth and entitlement snapshot.
+3. Paid features are blocked with explicit entitlement errors when unauthorized.
+4. Usage events are persisted locally and can be flushed idempotently to control-hub.
+5. Artifact sync supports durable hosted audit history and deterministic retry behavior.
+6. Dashboard can render tenant-aware, entitlement-gated analytics without data leakage.
+7. Billing summary endpoint returns plan usage and overage signals from deterministic aggregates.
+8. Quality gates pass: `lint`, `typecheck`, `test`, `validate:mcp-contracts`, `validate:architecture`.
+
+---
+
+## 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.
+
+---
+
+## 9. Risks and Mitigations
+
+- Risk: entitlement service outage blocks paying customers.
+  - Mitigation: signed local cache + grace period + explicit degraded-mode warnings.
+
+- Risk: billing disputes due to inconsistent metering.
+  - Mitigation: immutable event log, deterministic aggregation jobs, exportable customer usage report.
+
+- Risk: tenant data leakage.
+  - Mitigation: mandatory workspace scoping in every API query plus isolation integration tests.
+
+- Risk: implementation spread across too many subsystems.
+  - Mitigation: CP0-first contract scaffolding and phased rollout with strict exit criteria.
+
+---
+
+## 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
+- rollout/rollback runbook notes
+- `spec-files/progress.md` entry with completed milestones and remaining commercialization tasks