# 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
