# Request to Verified Proof

Experimental CompanyOS example that turns a fixed enterprise request into a
reviewed Outcome Pack, curated capability map, one approval-bound loopback
mutation, exact structured read-back, and replayable technical evidence.

## Current architecture

The package version is `0.4.1`. Its browser-safe exports are listed below; the
Node/Bun-only execution graph stays behind `./runtime` and `./runtime/server`.

The current path is:

1. `RequestToVerifiedProofPreview` renders the single adaptive
   **Understand → Shape → Match → Bound → Verify** journey.
2. Without host composition, it uses `createPreparedDemoRuntime`: prepared
   analysis and the committed recording remain available, while live browser
   execution is reported unavailable.
3. `@lssm-tech/module.examples` resolves the package preview generically. Its
   `ExamplePreviewOverridesProvider` lets an application replace one inline
   preview without importing app code into the generic examples module.
4. `web-landing` registers `CompanyOsDemoPreview`, which injects
   `companyOsDemoRuntimeClient`. The client calls the same-origin
   `/api/examples/companyos-ai-solutions-engineer-poc/[operation]` route for
   preflight, analysis, proof, fallback, and reset.
5. The route validates the browser-safe request contracts and delegates to the
   server-only runtime. For proof, the server resolves the allowlisted profile,
   recompiles the canonical prepared plan, verifies the exact approval binding,
   creates an ephemeral loopback fixture, substitutes only that fixture origin,
   then executes Harness through Playwright.
6. The live result is a bounded projection of the real Harness receipt. The
   recorded result is loaded from the committed SHA-256-validated manifest and
   its real screenshot artifact.

`/templates` and `/sandbox?template=companyos-ai-solutions-engineer-poc` use the
same hosted override. The package-only preview remains an honest
prepared/recorded experience when the provider is absent.

## Safety and truthfulness

- The default generator is deterministic and provider-free. It requires no API
  key and owns no provider configuration.
- The Node-only runtime composes canonical `HarnessRunner` with
  `PlaywrightBrowserHarnessAdapter`, accepts only `http://127.0.0.1` or
  `http://localhost`, installs an exact-origin route before navigation, sends
  no invitations or communications, and resets its fixture around every run.
- The proof records real Chromium screenshot, DOM, console, keyed structured
  output, step IDs, exact assertions, and an in-memory Harness replay bundle.
- The host accepts a strict, Zod-validated `ProofIntent`, resolves the
  allowlisted profile and scenario, recompiles the reviewed canonical mappings
  and proof plan, and rejects stale revisions or a mismatched SHA-256 execution
  binding before fixture creation.
- Live UI evidence is a bounded projection of the actual Harness receipt.
  Screenshot evidence is a capped inspectable data URL; assertion expected and
  actual values, verdict, mutation status, artifact IDs, and timestamps are not
  recalculated in the browser.
- Outcome Pack approval and proof approval are separate. Missing, denied, or
  mismatched approval fails closed before mutation.
- Live generation, proof, reset, and cleanup return within their configured
  timeout even when a dependency ignores `AbortSignal`; each session permits
  only one active proof across idempotency keys.
- Completed idempotency results and run nonces use bounded TTL/LRU stores.
  Timed-out work keeps its session quarantined until the underlying operation
  settles.
- A `verified` product receipt is technical test evidence. It is **not**
  customer acceptance, release, handoff, or evidence of business impact.

## Public exports

Browser-safe exports: `.`, `./example`,
`./companyos-ai-solutions-engineer-poc.feature`, `./outcome-pack`,
`./capabilities`, `./proof`, `./profiles`, `./runtime-contract`,
`./view-model`, `./ui`, and `./docs`.

`./runtime` is Node/Bun-only and is never re-exported by the root barrel. The
focused `./runtime/server` entrypoint exposes only server-host composition
helpers and avoids CLI/demo entrypoints in framework type graphs. The
Builder delivery-loop and acceptance-evidence projections are runtime exports
because their canonical runtime dependency is not browser-safe.

## Website demo

The package owns one shared capability/proof engine and one adaptive browser
journey used by both public surfaces:

- `/templates` — open **Request to Verified Proof** from the template catalog.
- `/sandbox?template=companyos-ai-solutions-engineer-poc` — open the same
  package-native preview directly.

The journey moves through five visual transformations: understand the request,
shape the outcome and boundaries, map proof-ready capabilities, disclose one
bounded action, and compare intended versus observed state. A quiet source and
approval cue remains visible throughout. Exact assumptions, source records,
approval facts, and evidence open from the relevant visual object instead of
competing with the primary story.

Both Customer Copilot and AI Solutions Engineer framings use this same adaptive
journey, data, approval, proof, and source policy. Prepared analysis is
deterministic; pasted unrelated requests remain analysis-only. Every result is
labeled as `live-ai`, `prepared-profile`, `live-browser`,
`validated-recording`, or `prepared-simulation`; failed and blocked verdicts
remain distinct from verified results.

The legacy `DemoSurfaceMode` type and named Call/Expert stage exports remain
available for compatibility but are deprecated. The primary preview, safe
session export, and presentation telemetry identify the surface as `adaptive`.

### Presenter paths

Audience mode is the default. It has no presenter entry button, failure
selector, internal diagnostics, or safe-export control. A host must explicitly
set `presenterEnabled` to expose framing, recorded/live/auto selection,
preflight, deliberate failure scenarios, reset, explicit fallback, and safe
local export. This does not restore a Call/Expert surface split. Auto mode
never silently loads a recording.

The final audience-facing scene asks to **Prepare this proof for your product**
with one redacted request, one test or staging account, relevant documentation
or API information, and one acceptance owner.

See [CALL_RUNBOOK.md](./CALL_RUNBOOK.md) for the two-minute rehearsal,
live-unavailable recovery path, and Arkia/Théo acceptance checklist.

## Privacy and host integration

- Raw request text stays in the in-memory UI session and is excluded from
  telemetry, logs, storage, errors, URLs, and the default export.
- The request and sandbox subtrees use PostHog no-capture/sensitive markers.
- Telemetry accepts only allowlisted operational metadata.
- The web host exposes an allowlisted, same-origin, capped JSON operation route
  at `/api/examples/companyos-ai-solutions-engineer-poc/[operation]`.
- Host responses are `no-store`, return stable error codes, and never reflect
  rejected request text.

### Optional live AI analysis

Live AI request analysis belongs only to `web-landing` and is disabled unless
`CONTRACTSPEC_COMPANYOS_LIVE_ANALYSIS=1` and an approved host provider is
configured through `CONTRACTSPEC_AI_PROXY_URL` or `ANTHROPIC_API_KEY`. The host
uses the repository AI-provider abstraction, supplies no tools, validates the
structured result, enforces a bounded cancellable timeout, and returns only an
analysis-only pack. It cannot attach the prepared scenario or create proof
authority.

The UI retains the operator's pasted request locally if the provider is absent,
malformed, unavailable, or times out. The failure is stable and the prepared
example is an explicit alternative, never a silent substitution. Hosts should
pass `analysisProviderDisclosure` when enabling this boundary.

## Local runbook

```bash
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc test
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc typecheck
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc lint:check
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc build
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc demo
```

Before a customer call, use the consolidated gate:

```bash
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc precall
```

It validates the package/profile, recording manifest and hashes, Chromium,
fixture behavior, and the host route. It is intentionally stricter than the
reliable recorded-call requirement.

Install Chromium once for the explicit browser lane, then run it without any
provider credentials:

```bash
bunx playwright install chromium
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc test:browser
```

Capture and validate the committed last-known-good recording:

```bash
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc record:demo
bun run --cwd packages/examples/companyos-ai-solutions-engineer-poc recording:verify
```

The capture starts the real loopback fixture, compiles the canonical prepared
binding, executes Harness through Playwright, persists the real screenshot and
safe receipt, and records SHA-256 artifact hashes. Synthetic negative presets
are labeled `prepared-simulation`; only the committed successful capture is
`validated-recording`.

## Deliberate failures

- Wrong administrator, missing onboarding project, disabled weekly reporting,
  missing selectors, or a nonzero external-send counter produce `failed`.
- Denied/missing approval, unsupported capabilities, non-loopback targets, or
  redirect escape produce `blocked` before the proof mutation.
- Failed and blocked receipts retain reason codes and the evidence that is safe
  and truthful for their execution stage; neither projects passed acceptance
  evidence.

Hosts may inject a result-returning `DemoRuntime`. Deprecated generation and
run callbacks remain observers only; callback return values never control
progression. `DemoRuntimeResult.data` is authoritative for rendered proof
evidence; selected recording presets cannot replace a live-browser result.
Without a host runtime, the browser-safe prepared runtime provides deterministic
analysis, explicit live-unavailable fallback, validated recording, preflight,
and reset behavior.

## Supported call configurations

### Reliable recorded call

- Use the public or hosted preview.
- Run `recording:verify` before the call.
- Select or explicitly accept the `validated-recording` path.
- Do not claim a live browser dependency or live execution.

### Local live call

- Run the local `web-landing` host with
  `CONTRACTSPEC_COMPANYOS_LIVE_BROWSER=1`.
- Install Chromium and require a fresh `ready-live` preflight.
- Use the injected same-origin API client, real loopback fixture, and
  `live-browser` receipt.
- If live execution fails, keep that failure visible and load the validated
  recording only after explicit acceptance.

## Deliberate limitations

This POC supports one allowlisted profile, one prepared executable scenario, one
loopback fixture, and one committed successful recording. It does not crawl,
index, generate arbitrary Playwright actions, target production systems, store
customer requests, establish customer acceptance, or prove ROI or other
business impact. Public/serverless hosting is recorded-ready by default and is
live-ready only when that deployed runtime genuinely launches Chromium and
passes the fixture probe.