# CompanyOS AI OS Proofs

Deterministic sandbox proofs for the CompanyOS operating graph.

This package demonstrates one claim:

> CompanyOS turns messy company workflows into a permissioned operating graph where AI and humans can inspect, approve, replay, and prove work across multiple workflows.

The demo is local, deterministic, provider-free, credential-free, and side-effect-free. It does not call AI providers, send network requests, load credentials, or write to production systems.

## Canonical demo flow

The primary UI export is `CompanyOsAiOsProofsPreview` from `@lssm-tech/example.companyos-ai-os-proofs/ui`.

It follows exactly six top-level steps:

1. **Executive Story** — explains the proof in one sentence.
2. **Scenario Workbench** — selects the default `support-to-product` workflow and inspects the raw messy signal.
3. **Operating Graph** — shows explicit signals, actors, capabilities, policies, approvals, evidence, and graph edges.
4. **Permission + Redaction** — proves unsafe agent actions are blocked, sensitive data is redacted, and PM approval is required where needed.
5. **Replay** — replays the deterministic run with timeline events, state diffs, graph diffs, blocked actions, redactions, and approvals.
6. **Evidence Receipt** — exports structured JSON proving what happened.

Do not add dashboards, settings, onboarding, or extra top-level proof steps to this flow.

## Default proof scenario

The fully wired scenario is **Support-to-Product**:

> A customer support signal becomes a product gap. The agent proposes work, CompanyOS redacts sensitive data, blocks unsafe actions, requires PM approval, replays the run, and exports a receipt.

Canonical metadata:

| Field | Value |
| --- | --- |
| Run ID | `run_support_to_product_001` |
| Receipt ID | `receipt_support_to_product_001` |
| Scenario | `support-to-product` |
| Graph schema | `companyos.graph.v0` |
| Proof version | `ai-os-proof.v0.1.0` |
| Sandbox mode | `true` |
| External calls | `false` |
| Production writes | `false` |

Other scenario previews may exist for comparison, but `support-to-product` is the canonical end-to-end proof path.

## What the receipt proves

The Evidence Receipt is derived from the same deterministic replay events used by Step 5. It includes:

- run and scenario metadata
- graph nodes and edges created
- actors involved
- permissions checked
- data redactions applied
- allowed and blocked actions
- approval gates still pending
- state changes
- verification metadata, including event count and replay path

The receipt intentionally does **not** prove production integration, real customer usage, external provider execution, or legal compliance certification.

## Safety and trust boundaries

User-facing copy should consistently make these boundaries clear:

- Deterministic sandbox
- No provider calls
- No credentials
- No production writes
- Replayable run
- Evidence receipt
- Blocked by policy
- Redacted before agent access
- Requires PM approval
- Stale runbooks stay blocked

Avoid user-facing copy such as “fake adapters”, “AI agent magic”, “trust me”, or unqualified production claims.

## Package surfaces

Important source areas:

- `src/shared-core.ts` — shared deterministic proof-building primitives.
- `src/scenarios/*` — scenario-level proofs using the shared core.
- `src/ui/CompanyOsAiOsProofsPreview.tsx` — demo shell.
- `src/ui/proof-app.navigation.ts` — canonical six-step navigation.
- `src/ui/support-to-product-proof.data.ts` — shared canonical proof data.
- `src/ui/support-to-product-replay.data.ts` — deterministic replay events.
- `src/ui/proof-app.receipts.ts` — receipt derivation from replay events.

## Local commands

Run from `packages/examples/companyos-ai-os-proofs`:

```bash
bun run lint:check
bun run typecheck
bun run test
bun run build:bundle
```

Use `bun run build` when type artifact generation is needed for release validation.