# Ontology Long-Horizon Work Graph

Date: 2026-08-29

## Objective

Use an ontological graph to control large and long tasks.
Make each work item, relation, claim, and evidence item addressable.
Keep one canonical graph across planning, execution, verification, and completion.

## Reference boundary

The [Ontology Workbench](https://robit-man.github.io/ontology/) is the documentation and reference implementation.
Its [pinned raw source](https://github.com/robit-man/ontology/blob/eb15ad0c0b0535b19333551e7dc579bc99920e3d/index.html) defines the contracts and behavior reviewed for this implementation.

Use the implementation as a contract reference.
Do not copy its browser and IndexedDB monolith into Omnius.

## Implementation result

Omnius now has one versioned operational work graph across planning,
execution, evidence, and completion.

The implementation projects the existing todo, durable workboard, and completion stores.
It does not add an independent planner or evidence store.

Implemented components:

- `packages/schemas/src/operational-world.ts` defines strict, versioned graph,
  source, evidence, claim, conflict, action, patch, receipt, and reasoning-slice
  contracts.
- `packages/orchestrator/src/operational-world/reducer.ts` validates and applies
  immutable, revision-bound graph transactions.
- `packages/orchestrator/src/operational-world/workGraphProjection.ts` projects
  objectives, requirements, work hierarchy, source documents and sections,
  actions, mutations, targets, acceptance criteria, blockers, claims, and
  completion evidence.
- `packages/orchestrator/src/operational-world/reasoningSlice.ts` selects a
  bounded target neighborhood and preserves all required references.
- `packages/orchestrator/src/operational-world/persistence.ts` writes atomic
  task-epoch snapshots with revision history and validation receipts.
- `packages/orchestrator/src/operational-world/controller.ts` owns projection,
  persistence, the constrained model-patch boundary, model context, and
  explicit completion blockers.
- `AgenticRunner` refreshes the graph before each primary and brute-force model
  turn. It exposes one current reasoning slice and rechecks explicit graph
  closure at every terminal path.

The graph must join this chain:

```text
objective
  -> requirement
    -> feature
      -> component or module
        -> task
          -> artifact or mutation
            -> claim
              -> verification
                -> evidence
```

Relations must also represent dependencies, blockers, contradictions, and supersession.

The durable workboard remains the execution-control surface. The operational
graph is its evidence and reasoning projection. It does not create a second
scheduler or permit a model patch to bypass workboard transitions.

## Useful Ontology Workbench contracts

The reference separates four concerns:

- Type and schema definitions
- Mutable runtime instances
- Claims, evidence, and conflicts
- Objectives, plans, actions, approvals, and executions

The model proposes a revision-bound patch.
Deterministic code validates and applies the patch.
The code records an immutable revision receipt.

The reference also uses target-focused evidence collection.
It scans all target occurrences before it selects evidence.
It keeps varied semantic roles and document positions.
It also keeps supporting and contradicting evidence.

These contracts are more valuable than its first chunking algorithm.
Omnius already has stronger basic chunking, content hashes, staleness checks, and PDF coverage receipts.

## Strong Omnius foundations

### Work decomposition

- `todo-store.ts` has stable identifiers, parents, blockers, owners, dependencies, verifiers, and artifacts.
- `todoTruth.ts` derives hierarchy, open leaves, dependency state, and parent completion.
- `featurePlanner.ts` records paths, symbols, tests, evidence, questions, units, and return contracts.
- `featureNode.ts` provides recursive survey, plan, split, execute, verify, and eviction stages.

### Completion and closure

- `completionLedger.ts` records claims, evidence roles, risks, critiques, unresolved items, and terminal receipts.
- `deliveryCoverage.ts` has versioned manifests and deterministic coverage evaluation.
- `integrationClosure.ts` already projects requirements, claims, paths, contracts, evidence, and blockers into a graph.
- `completion-evidence-gate.ts` requires independent evidence for high-risk claims.

### Evidence and memory

- `evidenceLedger.ts` records content hashes, revisions, ranges, fidelity, mutations, and staleness.
- `contextMemoryLedger.ts` records authority, trust, temporal validity, relations, and dependency-closed transactions.
- `evidenceBranch.ts` validates selected ranges against presented windows and original source text.
- PDF receipts distinguish absence, incomplete coverage, truncation, and omitted pages.

### Retrieval

- Hybrid retrieval combines lexical, vector, and graph candidates.
- The context assembler supports rank fusion, graph expansion, snippet packing, and request budgets.
- The memory ledger supports temporal and source-aware retrieval with explicit abstention.

## Closed gaps

### Canonical work identity

The projector gives each source record a stable content-derived graph identity.
Todo identifiers, completion evidence identifiers, claim identifiers, source
references, target references, and receipt references remain traceable in node
attributes or typed references.

### Requirement identity

Todos now carry `workKind`, `requirementIds`, `acceptanceIds`, `sourceRefs`,
`targetRefs`, and a typed action contract. The todo tool schema, persistence,
no-op comparison, and exports preserve these fields.

### Feature verification

`featureNode` now invokes `verifyUnit` after the final accepted executor result.
A false result or exception fails the node. The fallback path never changes an
unverified unit to complete.

Each feature node retains its graph, workboard-card, requirement, acceptance,
evidence, verification-receipt, and attempt lineage. Feature-tree saves use an
atomic replace so an interrupted write does not publish a partial tree.

### Receipt-backed workboard verification

A declared verifier is no longer satisfied by model-authored text that merely
names the command. The controller attaches `CommandEvidenceReceipt` only
through an internal runtime API that is absent from model-callable schemas.

The verifier gate requires:

- The exact normalized declared command
- A supported process-receipt schema
- A zero process exit code
- No timeout
- Valid start and finish times
- A finish time at or after the card entered work, when that boundary exists

Failed, timed-out, stale, malformed, and receipt-free evidence remains visible
for diagnosis. It does not certify completion.

### Workboard projection

The graph projects workboard cards as adopted work nodes and preserves their
dependencies, assignees, decisions, blockers, evidence, source bindings, and
verifier contracts. It emits the canonical proof path:

```text
task -> verification -> evidence
  |
  +-> acceptance or requirement
```

A card status alone cannot complete an explicit acceptance, artifact, or
verification obligation. A fresh trusted receipt must close the corresponding
path.

### Authoritative completion evidence

The active completion gate and final terminal fail-safe now reject open,
explicit requirements, acceptance criteria, blockers, and explicit claim
conflicts. They also reject invalid authored delivery manifests and stale
post-mutation verifier evidence.

Keep inferred work advisory.
Make explicit requirements and acceptance paths authoritative.

### World transaction boundary

`WorldPatch` includes a graph identifier, base revision, target revision,
typed operations, author, rationale, and creation time. The reducer rejects
stale or reused revisions and emits an immutable validation receipt with graph
and referenced-evidence hashes.

`OperationalWorkGraphController.applyModelPatch` keeps model changes inside
this boundary. It preserves the caller's base revision, attributes the patch
to its producer, and rejects model-created nodes or claims that try to gain
explicit or adopted authority.

### First-class conflict objects

Structured claims include subject, predicate, object, valid time, authority,
confidence, evidence, and dependencies. The reducer deterministically
preserves overlapping incompatible claims in an open conflict group.

### Target-focused reasoning slices

The graph slice starts from exact or lexical targets, expands a bounded
neighborhood, includes supporting and refuting evidence roles, retains claims
and conflicts, and restores parent and action-target closure after trimming.

Rendering also has a whole-block character budget. It keeps the focus first,
then blockers, acceptance and requirements, verification and evidence, and
finally other active nodes. It emits relations only when both endpoints are in
the rendered set and reports partial coverage and omitted-node count.

### Telegram group relationship graph

Telegram social state is a separate scoped temporal projection. Version 2
records immutable turn nodes and typed relations for direct replies, mentions,
participation, and turn order. Observed and operational facts remain separate
from model-inferred relationship claims.

The target-focused social context includes only the current chat, current
thread, and user-in-chat scopes. It expands one relationship hop around the
addressed participant. Ordinary group-chat text is not written to global user
personality memory. Explicit global preferences continue to use their
dedicated adoption path.

Router relationship notes are advisory claims. They cannot rewrite observed
addressing, identity, or interaction edges. Conversation snapshots use atomic
replacement.

### Shared source bindings

The shared schema supports URI fragments, line and character ranges, pages,
sheets and rows, headings, tables, JSON pointers, fields, and temporal ranges.
It records source revision, optional hash, authority, freshness, read policy,
observation time, confidence, and evidence role.

## Canonical WorkGraph contract

Use these node kinds:

- `objective`
- `requirement`
- `feature`
- `component`
- `module`
- `task`
- `acceptance`
- `symbol`
- `artifact`
- `mutation`
- `claim`
- `verification`
- `evidence`
- `conflict`
- `blocker`

Use these core relations:

- `decomposes_to`
- `part_of`
- `depends_on`
- `satisfies`
- `implements`
- `modifies`
- `produces`
- `verified_by`
- `evidenced_by`
- `contradicts`
- `blocked_by`
- `supersedes`
- `assigned_to`
- `attempts`
- `invalidates`
- `resolves`
- `synthesizes`

Each node and relation must have a stable identifier.
Each inferred item must record its authority.
An inferred item remains advisory until code or a user adopts it.

Each action node must define these fields when they apply:

- Target references
- Inputs
- Preconditions
- Expected mutations
- Side effects
- Required authority
- Required approval
- Risk
- Verification contract

## Shared evidence contract

`SourceBinding` and `EvidenceRef` are implemented under `packages/schemas`.

The schema must include these fields:

- Evidence identifier
- Source identifier and URI
- Content hash and source revision
- Observation time and freshness
- Authority and confidence
- Typed locator and locator value
- Supporting or refuting polarity
- Coverage and truncation status
- State epoch

Use the same evidence identifier in retrieval, memory, claims, completion, and groundedness.
Validate each reference against the current source revision.

## Revisioned world reducer

The pure reducer is implemented under
`packages/orchestrator/src/operational-world/`.
Keep `AgenticRunner`, context systems, and the TUI as consumers.

The model can propose only a `WorldPatch`.
The patch must include `patchId`, `baseRevision`, and typed operations.

The reducer must do these checks:

1. Verify the base revision.
2. Validate every runtime schema.
3. Verify every node, relation, claim, and evidence reference.
4. Verify expected file hashes and read versions.
5. Reject duplicate identifiers and dangling relations.
6. Reject invalid cycles and temporal intervals.
7. Preserve incompatible claims as a conflict.
8. Apply operations in a deterministic order.
9. Emit an immutable patch and revision receipt.

Dependency and blocker cycles are invalid. Relation endpoints are also typed:
assignment targets an entity, evidence links target evidence, verification
links target verification, and satisfaction links target a requirement or
acceptance node.

Use `integrationClosure.ts` as the first graph adapter.
Do not make its bounded display neighborhood the authoritative validation universe.

## Large-document evidence pipeline

Use a source-aware decomposition tree.
Each child shard must retain its parent and exact locator.

Select shard boundaries by content type:

- Keep prose headings with their paragraphs.
- Keep JSON paths and array ranges.
- Repeat table headers for each table shard.
- Keep PDF page markers.
- Keep spreadsheet sheet and row markers.

If one extraction fails, subdivide only that shard.
Preserve the failed shard as unresolved evidence.
Do not discard it.

For a named target, use this retrieval sequence:

1. Resolve exact target entities.
2. Scan all target occurrences.
3. Build section-bounded evidence windows.
4. Classify each window by semantic role and polarity.
5. Keep earliest and latest relevant evidence.
6. Keep early, middle, and late document coverage.
7. Expand one hop to co-referenced entities.
8. Include supporting and contradicting evidence.
9. Trim background evidence before target evidence.
10. Emit a typed coverage receipt.

Pass one validated `ReasoningSlice` to the reasoner and critic.
Reject unknown citations and omitted requested targets before model criticism.

## Completion invariant

Use this rule for authoritative work:

> Complete an objective only when every explicit requirement and acceptance path reaches fresh successful evidence after the last relevant mutation.

Do not let a model-created node silently expand the user's required scope.
Keep each inferred edge advisory until adoption.

## Completed correctness repairs

- `verifyUnit` runs during the feature-node verification stage.
- Exceptions and false verification results cannot create completion.
- Feature decomposition fields survive in the todo store and tool contract.
- Exact verifier commands require trusted receipts after relevant mutations.
- Workboard cards, assignments, blockers, decisions, and evidence project into
  the canonical graph without replacing the workboard execution engine.
- Model patches remain inferred and revision-bound.
- Dependency and decomposition cycle validation uses an iterative traversal, so
  a deep acyclic graph cannot exhaust the JavaScript call stack.
- Verification relations reject evidence whose source binding is stale or has
  no fresh source binding.
- Explicit supersession relations survive deterministic patch replay and
  retain their stable source and target identities.
- Bounded graph rendering reports omissions and never emits dangling rendered
  relations.
- Telegram turns and relationships preserve observed facts separately from
  advisory model claims and stay within chat, thread, and user-in-chat scope.
- Explicit completion gaps hold `task_complete` and alternate terminal paths.
- Repeated holds terminate as `incomplete_verification`; they never report a
  false success.
- Model context contains one current bounded reasoning slice instead of a full
  unbounded graph dump.

The deterministic scale fixture validates 6,000 nodes and 5,999 dependency
relations. Separate fixtures cover dependency cycles, stale verification
evidence, explicit supersession, feature verifiers, and scoped Telegram
conversation timeline replay.

## Deployment state

### Phase 1: Shared identity — complete

Add shared work, relation, source-binding, evidence, conflict, and revision schemas.
Project current stores into stable graph identifiers.

### Phase 2: Revisioned world — complete

Patches, validation results, revisions, full snapshots, and receipts are
persisted atomically for each task epoch.

### Phase 3: Retrieval and document evidence — integrated

The graph consumes current completion evidence and source references. Reasoning
slices include counterevidence, structural locators, coverage metadata, and
target neighborhoods without replacing the existing retrieval stores.

### Phase 4: Authoritative explicit closure — complete

Gate only explicit requirement and acceptance paths.
Keep inferred paths advisory.
Require fresh evidence after each relevant mutation.

### Phase 5: Parallel long-horizon execution

Schedule ready leaves whose dependency paths are satisfied.
Assign ownership and authority to each leaf.
Commit graph patches through the revisioned reducer.
Reconcile conflicts before dependent work begins.

This design lets Omnius decompose extreme complexity into durable ontological work.
It also keeps progress, evidence, and completion lossless across long sessions.

## Deliberate remaining boundaries

These items are later durability and product extensions. They do not permit a
completion bypass:

- Replace the Telegram social snapshot source with an append-only canonical
  social event log, while retaining the snapshot as a projection.
- Add deterministic alias-merge receipts for renamed or linked identities.
- Add a transaction coordinator if social facts must commit atomically across
  conversation memory, the social projection, and other memory stores.
- Generalize the shared temporal graph only after its scope and privacy model
  can represent chat and thread boundaries without widening retrieval.
