# Canonical Company OS product path

This document labels the **supported product spine** vs legacy/research surfaces (Phase 6).

## Canonical path (use for production work)

| Layer | Path |
|-------|------|
| Customer desktop | `external/company-os-desktop/apps/zeron/` → `company-os-desktop` binary (Zeron-based native GPUI shell, [ADR 0004](../adr/0004-zeron-desktop-is-canonical.md); packaged release still gated) |
| HTTP API | `src/bin/hsm_console.rs` → `src/company_os/` |
| Database | `migrations/` (Postgres via `HSM_COMPANY_OS_DATABASE_URL`) |
| Internal/admin web UI | `web/company-console/` |
| One-command up | `./company-os` (`scripts/company-os-up.sh` is the internal supervisor) |
| Sacred loop tests | `bash scripts/company-os-sacred-loops.sh` |
| Eval → runtime promotion | `scripts/meta-harness/company_os_promote_runtime_policy.py` |

## Product spine (mechanical contract)

The narrowly scoped native task/memory deployment with an isolated provider
credential gateway is documented in
[Secured local deployment](SECURED_LOCAL_DEPLOYMENT.md). It uses the same
runtime and ledger, adds fail-closed admission, and does not widen the desktop
or public-release claim. Existing companion installations remain host-managed.

The supported product is one line:

> one authored company/agent surface → one turn runtime → Postgres Company OS ledger → console

| Stage | What it is | Entrypoints |
|-------|------------|-------------|
| Authored company/agent surface | A company and its agents are authored once — a Passport industry pack (`starter_roster` + `first_task`) or an on-disk pack (`agents/*/AGENTS.md`, `skills/**/SKILL.md`) — and land as rows in Postgres | `config/company-passport-industry-packs.v1.json`, `src/company_os/http_company_passport.rs`, `hire-pack` in `src/company_os/agents.rs`, `src/company_os/paperclip_import.rs` |
| One turn runtime | One dependency-light kernel owns the agent turn; Company OS drives it through one runtime session from the execute-worker path | `Turn` / `TurnExecutor` in `crates/hsm-agent-core`, `RuntimeSession` in `crates/hsm-agent-runtime`, `src/company_os/http_worker.rs` |
| Postgres Company OS ledger | The only world model: tasks, runs, agents, memory, governance receipts; every mutation takes the company authority lock in its own transaction and commits with its receipt or not at all | `migrations/`, `connect_optional_pools`, `lock_mutation_authority_tx`, `record_governed_receipt_tx` |
| Console | `hsm_console` serves the ledger over HTTP; the Company Console reads and acts through that API only | `src/bin/hsm_console.rs`, `console_router`, `web/company-console/app`, `./company-os` |

Cross-cutting authority is recorded in
`config/company-os-canonical-authority-matrix.v1.json`. Entries are classified
as `authoritative`, `generated`, or `adapter`; a release claim must not infer
authority from a similarly named compatibility surface.

Everything else is an **optional internal or a plugin**. The ledger
[`PRODUCT_SPINE.json`](PRODUCT_SPINE.json) records each one with its gate and a
reference ratchet, and `node scripts/product-spine-contract.mjs` enforces it
(self-tests: `node --test scripts/product-spine-contract.test.mjs`):

| Subsystem | Gate today | Rule |
|-----------|-----------|------|
| Paperclip experiments (`src/paperclip`, `/api/paperclip/*`, `sync/paperclip-*`) | Cargo feature `paperclip-experiments`, **off by default**; `hsm_console` never composes it | every spine reference must sit behind the feature cfg; count may only fall |
| Hypergraph / stigmergic world model (`hypergraph`, `hyper_stigmergy`, `dream`, `dks`, `council`, `cass`, …) | unconditional in the root crate; the spine references none of it directly, but reaches it through `tools → hyper_stigmergy`, `api → council/meta_graph`, and `personal → federation/honcho` | spine reference count may only fall; a cfg gate needs those three seams moved first |
| Federation | unconditional; the spine references none of it directly | same |
| Evals and benchmarks (`eval`, `bench`, `experiment`) | unconditional; the compaction evidence vocabulary is ledger-owned (`company_os::compaction_evidence`) so the spine references `eval` nowhere | same |
| Legacy binaries (every `[[bin]]` other than `hsm_console` without `required-features`) | 31 ungated; eight research/demo/historical-runtime binaries sit behind `research-tools` | count may only fall; a binary gains a feature gate or is retired, never the reverse |

The canonical binary `hsm_console` must carry no `required-features` and may
not reference any optional subsystem at all — that rule has no baseline. The
ledger-owned signal vocabulary (`CompanyOsSnapshot`, `Signal`, `SignalKind`)
lives in `src/company_os/intelligence_signals.rs`; the Paperclip experiment
re-exports it, so the dependency points experiment → ledger.

## Closed loops (proof targets)

1. **Agent-chat task** — task row + worker execution (`agent-chat-e2e.test.mjs` live suite)
2. **Memory roundtrip** — `memory_arbitrator` write → search/llm-context with provenance
3. **Eval policy activation** — delta → verify → review → activate → worker policy JSON applied
4. **Trace skill promotion** — three matching successful tasks → exact rerun →
   attributable regression eval → verifier approval → `company_skills` (see
   [HITL and skill-promotion moat contract](HITL_AND_SKILL_PROMOTION_MOAT_CONTRACT.md))
5. **DB insight → task** — db-preview promote → scheduled checks → anomaly → task + governance

## Receipt-led roadmap decision (2026-10-04)

The product advantage to develop is the trust layer: an attributable action,
its authority decision, evidence, and a durable receipt that a person can
inspect through the supported path. The canonical ledger and closed loops above
already give this work a coherent spine. Module and table counts alone do not
show duplicated authority; some specialized ledgers have distinct identity,
replay, retention, or security contracts. Stop using count reduction as a
consolidation objective.

Prioritize the receipt primitive and its operator read projection: make the
actor, authority, subject, outcome, evidence reference, and replay identity
clear and consistent for each consequential action. Keep the existing
append-only and tenant boundaries. Judge a proposed consolidation by whether
it removes a second source of truth and improves an end-to-end receipt view,
not by the number of files or tables removed.

The reported inventory of 104 event/receipt tables is context, not a mandate
to funnel every event into `governance_events`. Any remaining table
collapse is a deliberate migration of one table at a time. A possible first
slice is `company_review_delivery_receipts` into a typed
`family: "review_delivery"` governance payload. That slice must include the
writer, historical data and identity mapping, every dependent constraint and
reader, and the operator read projection. Prove tenant isolation, append-only
behavior, idempotent replay, and equivalent observable receipt history before
retiring the old table. If those contracts cannot be preserved, keep the
specialized table and project it into the common receipt view instead.

## Legacy / research (do not treat as product defaults)

| Surface | Label |
|---------|--------|
| `src/main.rs` (TUI mega-binary) | Legacy runtime |
| `web_interface/viz/` (HSM-II Studio) | **Retired UI** — inert notice only; do not add product capabilities |
| `src/bin/hypergraphd.rs` | Legacy/internal diagnostics API only; no supported operator UI |
| Top-level `web/` (non company-console) | Legacy dashboard |
| `best_config.json` without RuntimePolicyDelta | Eval artifact only — see `docs/EVAL_AND_META_HARNESS.md` |
| `HSM_COMPANY_OS_HARNESS_POLICY_PATH` file policy | **Fallback only** — agent-chat prefers `runtime_policy_versions` via `/runtime-policy/active`; file path for local/dev when DB policy is unset |
| Eval harness refiner steps marked “not implemented” | Research — `docs/company-os/continual-harness-implementation-plan.md` |
| Binary upload in company-console | Not implemented — `AgentWorkspacePanel.tsx` |
| `web/company-console-desktop/` | Non-canonical Electron development shell; never a customer or employee-device fallback |
| `external/company-os-desktop/apps/gpuix/` | Abandoned GPUiX port (ADR 0004); not a product surface, may be removed |
| `crates/companyos-device/`, `packaging/companyos/`, `native/companyos_desktop/` | **Phase-0 scaffold** for the planned employee device plane (`companyos` CLI + daemon; see [`docs/companyos-device`](../companyos-device/ARCHITECTURE.md)). Untracked, not a release claim, and not a second customer shell: its product identity and telemetry schema are pending a founder decision against ADR 0004. It joins the canonical table only once enrollment, a ledger heartbeat, and a Console device row exist end to end. |

The desktop decision and fail-closed release inventory live in
[ADR 0001](adr/0001-canonical-self-serve-desktop.md) and
[`supported-capabilities.json`](supported-capabilities.json). A capability is
not release-supported merely because it exists in the web Console or old
raw-GPUI shell.

## Operator checklist

```bash
# Proof suite (Postgres required)
bash scripts/company-os-sacred-loops.sh

# Promote eval winner to governance inbox
python3 scripts/meta-harness/company_os_promote_runtime_policy.py \
  --company-id "$HSM_COMPANY_ID" \
  --best-config runs/run_*/best_config.json \
  --post
```