example.companyos-ai-solutions-engineer-poc

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 2.0.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 Harness assertions, and separate product postcondition assertions. In-memory replay identifiers are not transported as inspectable evidence.
• 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 proof also requires a bounded, raw-request-free session authority created by the exact prepared generation result.
• 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, prepared session authorities, 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, including CompanyOsProofSessionAuthority (TTL/LRU prepared-session registry whose requireExact() rejects any proof intent that differs from the registered binding) and requireLiveProofReady. 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 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

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

Before a customer call, use the consolidated gate:

bun run --cwd 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:

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

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

Repeat capture after a package-version bump: verification binds the recording to the current manifest version and checks the captured artifact hashes.

bun run --cwd examples/companyos-ai-solutions-engineer-poc record:demo
bun run --cwd 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.