Company Navigator

One machine-readable interface over Company OS capabilities for agents. It is a projection plus a receipt-backed action lifecycle; it owns no table, no dashboard, and no execution path. Everything lands in the canonical ledger: tenant admission, SCOPE_TASKS authority, create_task_tx, and governance_events.

Source: src/company_os/company_navigator/ (mod.rs catalogue and router, context.rs entity resolver, lifecycle.rs action lifecycle and gaps, coverage.rs freshness map, tests.rs database-backed contracts). Outcome Radar integration lives in src/company_os/outcome_radar.rs; Capability Home embeds the coverage map in src/company_os/capability_home.rs.

All routes sit under /api/company/companies/{company_id}/navigator and require a company-bound principal token. POST routes additionally pass the standard mutation admission (SCOPE_TASKS).

Routes

Method	Path	Purpose
GET	/capabilities	Catalogue: input/output schemas, effect, risk, approval, prerequisites, entity types, idempotency, examples, readiness, expected receipts, lowering.
GET	/capabilities/{id}/explain	explain step: what a capability does, what it needs, who approves, which receipts prove it ran. Records nothing.
GET	/context?ref=<domain>:<selector> or ?q=<text>	Cross-domain entity context with aliases, related entities, and store coverage.
GET	/coverage	Coverage and freshness map: domains, connectors, business sources, mail queue, open capability gaps, what cannot be performed and why.
GET	/actions	Recent actions with derived status and next action.
POST	/actions/plan	plan step. Body: {capability_id?, input, owner_persona?, priority?, due_at?, business_impact?}.
GET	/actions/{action_id}	Current envelope of one action.
POST	/actions/{action_id}/preview	preview step: the exact task that would be created.
POST	/actions/{action_id}/approve	approve step. Body: {decision: approve|reject, note?}.
POST	/actions/{action_id}/execute	execute step: one canonical task through create_task_tx.
POST	/actions/{action_id}/verify	verify step: proves task and receipts are bound.

Action lifecycle

explain → plan → preview → approve → execute → verify

• The action_id is the SHA-256 of the canonical plan input (company, capability, intent, sorted entity bindings, sorted evidence refs). Same input, same action; re-planning never writes a second receipt.
• Every step is a governance_events row with subject_type = navigator_action and subject_id = action_id. Receipt actions: company_navigator_action_planned, _previewed, _approved or _rejected, _executed, _verified. Task creation adds task_created.
• Approval requires an active owner/admin who is not the planning principal (separation of duties). Rejected actions cannot execute.
• Execute is idempotent: the executed receipt carries the task id, and the task is deduplicated by navigator:<action_id>. Outcome Radar's acceptance of a navigator: proposal calls the same execute_action_tx.
• Global safe mode returns the plan as a blocked_safe_mode envelope without writing anything.

Every step returns one envelope (hsm.company_os.navigator_action.v1): action_id, capability_id, step, status, entity_bindings, changed_state (task id, display number, state, task preview), evidence (evidence refs, receipts, verification checks), receipt_ids, approval, and next_action.

Entity references

<domain>:<selector>. Selectors: a UUID, #<display_number> for tasks, email:<address>, external:<id>, or a bare natural key.

Domains with a canonical store: client (company_customers), request (customer_requests), task (tasks), message and thread (company_email_operator_queue), order, ticket, invoice (company_*), action (navigator receipts). opportunity is computed by Outcome Radar.

Domains with no store in Company OS: property, unit, lease, resident, vendor, inspection, incident, compliance, deal, visit, document, case. These bind by reference. The lowered task carries {"kind":"label","ref":"entity:<domain>:<selector>"} in capability_refs, so /context?ref=property:velora-12 still joins to its tasks and actions through the ledger.

Capability gaps

When plan receives no capability id (or an unknown one), the navigator records company_navigator_capability_gap with subject_type = capability_gap and subject_id = fingerprint. The fingerprint hashes the requested capability, the entity kinds, and the normalized intent terms, so rewordings of the same ask collapse. Frequency is the receipt count per fingerprint. Each receipt keeps the attempted intent, the missing tool or data, business impact, DRI, and suggested catalogue capabilities.

Open gaps appear in /coverage and in Outcome Radar as gap:<first receipt id>. Accepting one creates the deduplicated missing-capability task (dedupe key capability-gap:<fingerprint>).

Outcome Radar sources added

Proposal ids keep the <prefix>:<uuid> convention:

Prefix	Source	Proposal
connector	company_connectors in error/degraded or failed after last success	Repair connector
source	company_business_sources degraded/error or non-manual and stale over 7 days	Refresh source
mail	company_email_operator_queue pending over 24 hours	Answer waiting email
navigator	planned actions with an approval and no execution/rejection	Execute approved action (accept executes it)
gap	capability gaps grouped by fingerprint	Close capability gap

Property operations pack

Nine capabilities under company_os_property_operations_pack: property.portfolio.context, property.lease.renewal, property.resident.followup, property.maintenance.triage, property.vendor.coordinate, property.inspection.schedule, property.finance.review, property.compliance.deadline, property.incident.respond. Each lowers to one canonical task through the lifecycle with approval required; property entities bind by reference.

Verification

cargo test --lib -- company_navigator:: outcome_radar:: capability_home:: with DATABASE_URL set. The database-backed tests cover the read gate, the full lifecycle, the Radar hand-off, gap deduplication, safe mode, and the entity resolver.