Company world model, capabilities, and intelligence
This document is the contract for how “what the company knows” and “what runs” fit together. It exists so the console, agents rail, and issues stay one game: Postgres Company OS keyed by company_id, not a parallel in-memory product.
Repository-scale continuity principle: Enlarging an agent's context window is not the primary scaling lever. A context window is transient working memory. Completed work must become a committed, addressable object—such as a source-control commit, versioned task transition, verified artifact, memory entry, or evidence record—that later workers can inherit, resume from, and query without re-deriving it. Company OS exists to bind those objects into durable operational state and compose the relevant slice back into each worker's context.
Knowledge representation (JSON-LD): knowledge-representation.md — @context, table→type map, promotion ladder ↔ memory_edges. Export one memory: GET /api/company/companies/{company_id}/memory/{memory_id}/export-jsonld.
0. Value: outcomes that remain explainable
Company OS preserves the relationships between work, decisions, evidence, and outcomes so those outcomes remain explainable after the people and models change. This is the product value thesis clarified by the user on 2026-09-09. It is a design principle, not a claim that every workflow already satisfies it.
| Layer | Finance example | Company OS role |
|---|---|---|
| Authoritative records | Posted journal entries in the accounting system | Recorded task transitions, approvals, spend, and execution receipts, each with a stated scope of authority. |
| Business relationships | Entry → invoice → customer → contract → delivery | Outcome → artifact → tool action → run → task → objective, with owners, capabilities, and supporting evidence. |
| Governed history | Original documents, applicable rules, corrections | Versioned operational state, instructions actually supplied, decision and approval evidence, and superseding corrections. |
The ledger records what was posted. An ontology defines entities, relationships, and meaning; linked evidence supports an explanation of why. Governed history preserves the recorded sequence and historical context. AI reasons across these layers and must distinguish documented reasons, calculated effects, hypotheses, and missing evidence. A relationship alone does not establish causation.
Company OS is the operational system of record within its defined boundaries. The accounting system remains authoritative for postings; the relevant external provider or bank supplies evidence of external completion or settlement. A tool receipt showing acceptance is not proof of payment, delivery, or recognized revenue. Agent spend records are not a general ledger.
Historical reconstruction is the quality bar
For a consequential workflow, another person or model should be able to retrieve the result, responsible identities, exact authorized action, source documents, instructions and business-rule versions actually used, verification evidence, external outcome, and later corrections. Retain stable links and retrievable content under the applicable access and retention policy. A digest verifies content identity when the content is available; it cannot reconstruct missing content. A policy reference that resolves only to today's version is insufficient.
Distinguish when a rule or fact applied from when the system learned or recorded it. Preserve late-arriving evidence and corrections without presenting the corrected view as what the original decision-maker knew. Historical reconstruction does not promise deterministic replay of an LLM or an external service. If evidence is missing or outside retention, say that reconstruction is incomplete.
Current foundation and limits of the evidence
Repository inspection on 2026-09-09 found these concrete foundations:
- Task-state migration: versioned events with actor, reason, source revision, and an explicit baseline that does not invent earlier history.
- Prompt receipts: effective-input and instruction-component digests bound into a receipt. This establishes a content-identity mechanism, not universal source retention or capture coverage.
- Run story: a bounded, company-scoped composition of existing execution evidence from one database snapshot, not a new ledger.
- Governed execution admission: one append-only receipt atomically joins tenant, replayed task state, accountability, human gating, budget policy, provenance, context disposition, and economics-stream identity for fresh canonical native-worker runs. It is a conformance record, not a replacement for the source ledgers or proof of external-effect finality.
- Knowledge representation: operational entities and typed memory relationships with a shared vocabulary. This is not evidence of a complete finance ontology spanning invoices, inventory, tax, suppliers, and plants.
These are source and contract observations, not a live deployment certification. End-to-end historical rule resolution, complete source retention, cross-system reconciliation, and customer financial outcomes were not verified in this review. “Zero-day close” would require continuous reconciled, traceable, reconstructable financial understanding, including unresolved exceptions; faster numbers alone do not establish it. Company OS must not claim that capability from these operational primitives alone.
ERP and enterprise-context boundary
For ERP- or SAP-backed workflows, Company OS is the governed operational control plane around enterprise context. It is not the ERP system of record and it is not, today, the complete enterprise semantic and lineage layer. The intended boundary is:
ERP / SAP systems of record
↓
Enterprise semantic + lineage layer
↓
Company OS: governed decisions, accountable execution, learning, and audit
↓
People / agents / tools
↓
Governed actions, receipts, and outcome evidence
└───────────────────────────────→ Company OSThe semantic and lineage layer preserves business meaning across source systems: canonical entities and mappings, metric definitions, source lineage, quality and reconciliation state, and permitted uses. Company OS uses that governed context to make and review decisions, admit and settle actions, retain receipts and outcomes, and promote verified learning. People and agents remain accountable actors at the edge; their completed work returns evidence to Company OS rather than becoming untracked chat or tool history.
Implementing this end to end still requires ERP connectors, canonical mappings for business domains such as customers, products, invoices, inventory, and the general ledger, versioned metric definitions, source snapshots or reproducible references, reconciliation workflows, and enforced data-access policies. These are requirements and direction, not a claim that Company OS currently delivers the full layer.
Enterprise-context data plane v1
The source foundation now exists in the radars product family. The 20260918010000__enterprise_context_data_plane.sql migration adds tenant-bound, append-only source snapshots, lineage records, canonical entity mappings, versioned metric-definition and access-policy streams, and reconciliation events. The enterprise_context.rs routes record each mutation under Company OS admission and a governance receipt.
Business-data sync receipts can now name the exact source snapshot used for an ingest. The existing entity read endpoint requires a tenant-bound company-agent principal, evaluates the active policy and the entity read in one tenant transaction, and uses the server-owned operations purpose rather than a caller parameter. That enforcement is deliberately narrow: it does not yet map each admitted run/tool capability to a data-use purpose, protect every model or tool path, provide an SAP connector, or establish a complete customer/product/ invoice/inventory/general-ledger model. Those remain the next implementation slices rather than implicit product claims.
The broader opportunity: reusable institutional machinery
The user's further clarification on 2026-09-09 extends this thesis beyond preserving history: corporate information becomes strategically useful when the company can establish its meaning, common measures, permitted uses, analytical methods, and accountable execution. Company OS's product direction is a governed control plane connecting corporate information and machine intelligence so those institutional capabilities can be reused across work.
These responsibilities are distinct even when implemented by the same system:
| Responsibility | Contract needed for reliable reuse |
|---|---|
| Governed data foundation | Identify authoritative sources, reconcile conflicts, record quality and freshness, and retain provenance. Governance does not make an incorrect source fact true. |
| Enterprise ontology | Define entities, relationships, policies, and processes with owners and versions. Representing a policy does not itself enforce it. |
| Semantic layer | Define shared metrics through versioned formulas, dimensions, aggregation rules, units, time windows, exclusions, source mappings, and accountable owners. A vocabulary or KPI label alone is insufficient. |
| Access and use governance | Enforce who may retrieve which data, for what purpose, through which tools, models, and execution environments; cover derived outputs as well as inputs. |
| Analytical workflows | Preserve source snapshots or reproducible source references, queries/code, parameters, assumptions, dependencies, validation, and uncertainty. |
| Institutional memory and audit | Connect conclusions and actions to the evidence, definitions, permissions, reviews, and corrections that applied; preserve enough context for authorized review. |
| Model and execution orchestration | Choose permitted models and environments within task, quality, privacy, latency, and budget constraints; record the actual selection and any fallback. |
For example, answering “Why did margin fall?” first requires agreement on what margin means: treatment of returns, discounts, freight, cost allocation, currency, and reporting period. Then the analysis needs the applicable definition, source data, calculation, comparisons, and reviewed explanation. Changing the definition must not silently change the meaning of a historical answer. Claims about causes still need evidence beyond a correlation or a well-documented calculation.
Governance constrains the whole path, including retrieval, model dispatch, fallbacks, artifact storage, and output disclosure. Historical permission evidence shows what was authorized then; it does not grant a reader access now. Preserve an audit path under current access and retention rules without treating an old approval as perpetual authority.
The existing governance architecture describes bounded run authority, governed effects, and settlement evidence. The model gateway contains scoped model binding and budget mechanisms. Alongside the operational graph and evidence foundations above, these support the direction; they do not establish a complete enterprise semantic layer, universal data-use enforcement, reproducible analytics, or optimal model selection. This documentation review has not verified those capabilities end to end.
Reporting, forecasting, anomaly detection, scenario analysis, decision support, and agentic workflows are applications of this architecture, each requiring its own data, method, authorization, and outcome validation. Reconstructing an answer establishes how it was produced, not that it was correct. For stochastic models, retain the observed output and sufficient method provenance; do not promise an identical regenerated answer. This market thesis carries no independently verified market-size estimate or Company OS valuation.
How the system earns its economic value
The benefit to prove is less human effort to explain, review, recover, and reuse accepted work, with fewer costly errors and an acceptable total operating cost. Useful customer questions are: “What produced this result?”, “Who approved this exception, and what did they see?”, and “What would change under today's policy?” The last question is a counterfactual analysis, separate from the historical record.
Use the existing workflow value milestone to compare against a capable agent with Markdown and ordinary task tracking. Its customer measurements are pending. Measure accepted outcomes, human supervision, rework, recovery, latency, and total cost; do not equate code volume or replacement cost with business value. For a reconstruction evaluation, freeze additional questions and scoring before measurement rather than changing an active protocol.
Estimate annual customer benefit from measured labor savings and evidenced reductions in loss or rework, minus incremental software, infrastructure, support, and implementation costs. Avoid double-counting saved time; identify whether it creates cash savings or usable capacity. No monetary valuation, ROI, or risk reduction is established here. Expand the ontology from demonstrated workflow needs under the existing milestone, rather than modeling an enterprise upfront.
1. World model (company) — canonical operational graph
Treat Postgres Company OS as the single source of operational truth for a company:
| Area | Role in the graph |
|---|---|
| Tasks | Work units: state, checkout, requires_human, attachments, context_notes, capability_refs (links to skills/SOPs/tools/packs/agents), spawn/handoffs, spend links. |
| Runs / telemetry | Honest signals: terminal status, tool usage, logs — surfaced on tasks and in governance-style events where wired. |
company_memory_entries | Durable shared and agent-scoped facts; search/append via API and tools. |
company_human_preference_events | Human-reviewed working preferences, scoped to a company membership and included only for tasks bound to that human; see human working preferences. |
companies.context_markdown | Company-wide narrative the LLM layer always sees (with memory and task context). |
GET …/tasks/:id/llm-context | Composed read model for agents: context markdown, memory pool, task block, workforce profile, headings/TOC as implemented. |
| Goals, governance events, spend | Alignment, policy trail, and cost — same company_id. |
Anything labeled “intelligence” in product terms should read and write through this graph (or explicitly sync into it), not maintain a second ledger the UI pretends is equally real.
Task-state event-sourcing boundary
company_task_state_events is the canonical history for task state. Version 1 is an explicit baseline (the state observed when the migration lands, or the initial state of a newly created task); later versions are state transitions or a deletion tombstone. Database triggers append and validate the next immutable event before tasks.state changes, in the same transaction, so the current state is a projection that can be checked with company_replay_task_state(...) and company_task_state_projection_drift(...). The task-state command boundary also accepts an optional expected_version fence and returns the committed aggregate_version, allowing callers to advance from an observed log snapshot without silently overwriting a newer transition.
company_task_metadata_events extends the same contract to the task's title, specification, ownership, checkout lease, legacy blocker, many-to-many dependency edges, workspace attachments, and capability references. Each event carries a complete versioned metadata snapshot, so company_replay_task_metadata(...) can reconstruct the aggregate and company_task_metadata_projection_drift(...) can identify a stale row or dependency projection. The task row and dependency table remain read-optimized projections; their writes append metadata history in the same transaction, and deletion appends a terminal metadata tombstone. GET /api/company/tasks/{id}/metadata reads the replayed snapshot and committed version directly; PATCH /api/company/tasks/{id}/context accepts an optional expected_version and returns a structured conflict instead of overwriting a newer metadata transition.
Company-wide replay boundary
The task projection is not the only cache. Goal/project rows, company-agent rows (including reports_to), DRI assignments, squads, squad memberships, memory entries/edges, company configuration, run lifecycle, task-run snapshots, wait conditions, workflow frames, run forks and execution intents, active-model adoption, tool-cycle heads, tool execution, scheduler/liveness, review annotations, connector sessions, routines, routine runs, learned HITL preferences, context policies, shared-thread sessions, channel membership, task operational state, task relationship/lineage context, and credential-safe connector account/OAuth lifecycle state all have complete append-only snapshot streams in the current migration wave. Their current rows are read-optimized projections: replay functions fold ordered events, drift functions compare the cache to the fold, and admin-only repair/checkpoint functions rebuild or cache a verified head without inventing a business event. Causation/correlation/idempotency metadata, schema compatibility rows, and external stream-head export/anchoring apply to the canonical streams; migration baselines mark the point at which history becomes authoritative and do not fabricate earlier history.
The task context stream now covers the remaining non-secret relationship and lineage fields: goal/project links, goal ancestry, promotion provenance, fork and parent lineage, spawn-rule links, display numbers, and declarative step policy. company_replay_task_context(...) is the fold for that projection; repair changes only those task columns and cannot rewrite the task state, metadata, or operational streams.
This remains intentionally bounded. Principal/delegation authority tables remain ordinary operational or runtime projections until their own complete event contracts are approved. Connector account/OAuth history is credential-safe by design: secrets stay in the encrypted escrow projection, while the ledger stores only safe fields and digest/presence evidence. It must not be interpreted as an independent secret-retention boundary.
2. Capabilities — atomic building blocks
These are already modular in the product; the rule is to link them into the world model, not float them beside it:
- Tools & skills — registered and invoked with company/task context.
- Packs — bootstrap templates; after import, roster and skills should resolve to Postgres (
company_agents, adapter config, etc.). - Workforce agents — rows with roles, budgets, profiles;
llm-contextand task checkout should resolve persona → agent row where possible. - SOPs / playbooks — procedures tied to projects and tasks (see playbooks-projects-and-visions.md).
Direction: task and agent APIs (and UIs) should carry explicit references (IDs, personas, skill refs) so the graph is queryable — “who is on this,” “what skills apply,” “which SOP governs this stream.”
Implemented in tree: tasks.capability_refs (JSONB array of { "kind", "ref" } or create-body strings normalized to kind: skill). Set at create, PATCH /api/company/tasks/{id}/context, and bundle import/export; copied to spawned subtasks; merged into GET …/tasks/{id}/llm-context and the Intelligence workflow feed when updated (task_capability_refs_updated). Pack bridge: POST …/import-paperclip-home pulls on-disk agents/skills into Postgres for the company.
Paperclip → Postgres (goals & DRIs): goals.paperclip_goal_id + paperclip_snapshot for upserts; POST /api/company/companies/{id}/sync/paperclip-goals (optional JSON { "goals": [...] }, or empty body when hsm_console runs with in-process IntelligenceLayer); POST …/sync/paperclip-dris same for { "dris": [...] }. dri_assignments table + GET/POST …/dri-assignments and PATCH/DELETE …/dri-assignments/{row_id} for first-class org DRIs (including manual rows).
3. Intelligence layer — two APIs, one truth
| Surface | Scope | Use |
|---|---|---|
/api/company/companies/{company_id}/… | Per company | Canonical: goals, tasks, memory, spend, intelligence summary, llm-context, etc. |
/api/paperclip/* (proxied in dev) | Global / in-memory demo | Optional: composition, routing experiments, demos — not a second company dashboard of record. |
Allowed patterns:
- Embed composition/routing inside Company OS (per
company_id) so all state lives in Postgres; or - Sync Paperclip-style state into Postgres (goals, signals, DRIs) so operators still have one store and one UI truth.
Anti-pattern: two first-class UIs that each imply their own goals/signals/registry without migration or sync — that splits hierarchy (alignment, backlog, who is on what) across “Postgres truth” and “optional global layer.”
Workspace Intelligence in the company console should prefer GET …/intelligence/summary (and related company routes), not Paperclip-only views.
4. Interfaces — edges of the same model
| Interface | Expectation |
|---|---|
| Company console | Reads/writes /api/company/… for the selected company; copy should not imply a global parallel state is authoritative. |
| Agents rail | Chat and task actions mutate the same task graph (checkout, notes, runs) for that company_id. |
| Issues / my-work | Same task list and states as the API; no shadow issue system. |
If a feature cannot point at a company_id and a concrete row or API path, it is not yet part of the world model — it is integration or demo debt.
5. Implemented alignment contract
This section is the quick check for whether a feature helps models, harnesses, and systems stay "likewise" — seeing the same world through different interfaces instead of inventing parallel realities.
| Contract | Implemented surface | Why it matters |
|---|---|---|
| Model context contract | GET /api/company/tasks/:task_id/llm-context in src/company_os/agents.rs returns company_id, hsmii_home, context_notes, capability_refs, workspace paths, agent_run_profile, combined_system_addon, section byte counts, and context_manifest. | A model starts from the same company/task graph the UI and tools use. It can see explicit memory/tool instructions rather than guessing from chat. |
| Memory contract | company_memory_entries plus company_memory_search / company_memory_append in src/tools/company_os_tools.rs; shared, agent, and broadcast scopes are exposed in llm-context. | Shared facts compound across agents; private notes stay scoped; urgent company lines can be broadcast without becoming invisible side-channel state. |
| Capability contract | tasks.capability_refs (skill, sop, tool, pack, agent, etc.) set through task APIs/imports and rendered in llm-context + workflow feeds. | Models and harnesses can reason over explicit procedures and tools, not prose-only hints. |
| Governance / DRI contract | requires_human, dri_assignments, governance_events, run feedback, and intelligence summary workflow feed. | Escalation and accountability become rows with owners and evidence, not vibe-based chat conclusions. |
| Intelligence sync contract | Paperclip-style goals/DRIs sync into Postgres via paperclip_goal_id, paperclip_snapshot, sync/paperclip-goals, sync/paperclip-dris, and manual DRI CRUD. | External intelligence can compose and propose while Company OS remains the ledger. |
| Harness contract | hsm-eval, hsm_meta_harness, hsm_outer_loop, Python scripts/meta-harness, scripts/refiner-jsonl-pass.py, and scripts/meta-harness/company_os_refiner_pass.py write artifact trees, turns_hsm.jsonl, company_os_turns.jsonl, candidate configs, and deltas. | Evals and live agent-chat smokes improve benchmark/runtime policy through reviewable evidence; they do not silently mutate live runtime behavior. |
| Eval-pack contract | schemas/company_eval_pack.v1.json, scripts/meta-harness/pack_loader.py, and scripts/meta-harness/kpi_verifier.py let each company declare tasks, personas, scorer bindings, KPI assertions, and promotion thresholds. | Company-specific "what good looks like" stays declarative while runner, tracing, verifier registry, frontier search, and promotion gates remain shared platform primitives. |
| Hosted / LLM documentation contract | docs-site/sync-manifest.json mirrors selected docs into VitePress pages and /llm/*.md files. | Agents can fetch the same architecture contract operators read, reducing prompt drift across tools and sessions. |
Four knowledge layers
Treat company knowledge in four layers (constitution → operational → procedure → evidence). Full table, JSON-LD mapping, DRI/verifier/ledger rules, and context/review/compaction policy: knowledge-representation.md.
Promotion ladder
Use this ladder whenever a new intelligence feature, harness result, or agent behavior is introduced:
- Observe: capture the signal in a trace, task note, governance event, memory row, or run artifact.
- Bind: attach it to a company, task, DRI, goal, capability ref, or harness config path.
- Expose: make it visible through
llm-context,intelligence/summary, task APIs, or an eval artifact index. - Verify: run the relevant smoke or benchmark and record the artifact path / logs.
- Promote: only after verification, map the change into runtime config, prompt policy, tool allowlist, memory policy, or docs.
If a step cannot be completed, label the work as integration debt rather than "implemented intelligence."
Red flags
- A model answer depends on state that is not in
llm-context, memory, task notes, or a declared file path. - A dashboard shows goals, agents, DRIs, or task state without a
company_idand Company OS API path. - A harness
best_config.jsonis treated as production behavior without a runtime mapping. - A high-stakes action completes without
requires_human, DRI, governance, or run evidence when confidence is low. - A capability is described in copy but absent from
capability_refs, tool registry, skills, SOPs, or pack import.
See also
- Intelligence layer & DRI alignment — composer vs ledger vs edge (DRIs); integration checklist for external intelligence.
- Company eval packs and meta-harness scoring — declarative per-company task/KPI packs and shared scorer/promotion contract.
- HSM-II field coordination — stigmergic field, model/harness/runtime contract, and ratchet gates.
- Memory, workspace attachments, shared context —
company_memory,context_notes,llm-context, tools. - Playbooks, projects, and visions — how SOPs sit on the task/project graph.