feat(platform): establish the portable Ontology Runtime and trusted execution contract #328

schemaVersion: requirement-record.v2
revision: R2
status: needs-design
priority: P1
productOwner: pending maintainer decision
technicalOwner: pending cross-repository assignment
userOutcome: >
An operator can ask a RoleWeave employee to inspect a bounded business object,
reach a traceable decision, and propose or execute a controlled action with
evidence, policy enforcement, idempotency, and trusted readback.
parent: #37
dependencies:

• feat(memory): define the RoleWeave memory plane for bounded context, archival, and multi-agent recall #327
• feat(turns): session follow-up context — inject a bounded trusted window into engine spawns #143
• https://github.com/bytefolk/roleweave/blob/main/docs/design/workflow-handoff-v1.md
  technicalPilot: A GitHub-operations team that can file issues, open PRs and merge — with authoring and merging split across positions #302
  relatedPullRequests:
• docs(platform): record Ontology Runtime R2 contract for trusted execution (#328) #344
• docs(platform): record trusted execution semantic contract R1 (#328) #346
  lastDecisionAt: pending

North star

RoleWeave is moving from multi-Agent demonstrations to a domain-neutral,
open-source trusted execution platform for enterprise Agents.

The platform lets an Agent work with bounded business objects, evidence,
policies, and actions without directly depending on raw database schemas or
unrestricted external tools.

The open-source core is not a domain-specific business application, BI system,
general-purpose ontology editor, graph database, or Palantir replacement.
Business solutions are delivered as optional domain packs and enterprise
adapters on top of the platform.

User outcome

An operator can ask a RoleWeave employee to:

1. inspect a bounded business object or relationship;
2. resolve its semantic context and source evidence;
3. produce a traceable decision or hypothesis;
4. propose a controlled action with explicit preconditions;
5. obtain the required policy or human approval;
6. execute the action idempotently; and
7. inspect the exact readback and terminal receipt.

A multi-Agent conversation alone is not evidence of a trusted execution
platform.

Product boundary

No repository may introduce a second source of truth for sessions, permissions,
approvals, durable memory, raw source occurrences, or execution receipts.

Execution model

The normative execution path is:

source ingest
  -> normalization and semantic binding
  -> Ontology Runtime
  -> typed query / function / action API
  -> Agent / Workbench / Skill / MCP
  -> policy and approval evaluation
  -> idempotent execution
  -> exact readback
  -> execution receipt

The Agent is responsible for intent understanding, planning, explanation, and
delegation. The Ontology Runtime is responsible for bounded business meaning
and deterministic operational state.

The Agent must not directly control arbitrary SQL, database writes, or
unrestricted external APIs.

Ontology Runtime scope

The Ontology Runtime is a portable contract and runtime seam, not a mandated
storage engine.

The minimum model includes:

• business objects and stable object references;
• relationships;
• semantic bindings;
• derived state;
• lifecycle and expiry;
• typed queries and functions;
• business actions;
• source evidence;
• version and digest checks;
• policy and permission context; and
• execution events and receipts.

The first implementation must not require a graph database or a new enterprise
data platform. Storage and source adapters remain replaceable.

Core contracts

BusinessObjectRef

A bounded reference to a business object, relationship, metric, event, or
derived state. It preserves source identity, scope, time, version, digest, and
permission context where applicable. It must not contain an unbounded raw source
payload.

EvidenceRef

A reference to source evidence supporting a claim or decision. It preserves a
source locator, source type, time range, revision or digest, provenance, and
access scope.

DecisionRecord

A bounded conclusion, hypothesis, or recommendation. It records confidence or
uncertainty, evidence references, semantic bindings, timestamp, and originating
turn or task.

ActionProposal

A proposed action that has not necessarily executed. It records action type,
target, intent, expected effect, preconditions, required permission, approval
policy, idempotency key, target version or digest, expiry, and originating
decision.

ExecutionReceipt

A record of what actually happened. It records actor and position, effective
permission, target identity and version, action and idempotency identities,
start and terminal states, external identifiers, exact readback, failure or
indeterminate reason, and originating turn or task.

indeterminate must never be rendered as succeeded.

Requirements

REQ-001 — Stable semantic references

Define versioned contracts for business objects, relationships, metrics,
events, derived state, and evidence. References must preserve scope,
provenance, time, and version information.

REQ-002 — Ontology Runtime boundary

Define minimum runtime behavior for object and relationship resolution, derived
state, lifecycle transitions, typed queries and functions, action discovery,
and source/version invalidation.

REQ-003 — Decision-to-action contract

Define a versioned contract connecting DecisionRecord to ActionProposal.
Target, intent, expected effect, preconditions, policy, approval, expiry, and
idempotency must be explicit.

REQ-004 — Fail-closed execution

An action must not execute unless effective permission is present, required
approval is satisfied, the target is still valid, the proposal has not expired,
and the idempotency identity is preserved.

Retries must reuse the same idempotency identity.

REQ-005 — Trusted execution state machine

Define and enforce:

proposed -> approved -> running
                         -> succeeded | failed | cancelled | indeterminate

No client-side inference may convert failed or indeterminate into succeeded.

REQ-006 — Workbench traceability

The RoleWeave workbench must allow an operator to inspect semantic context,
source evidence, decision, action proposal, policy result, execution state,
readback, and final receipt from the task or turn timeline.

Parallel, relay, and handoff flows must preserve these references without
silently widening permissions or re-running an action.

REQ-007 — Cross-repository ownership

Portable contracts belong in digital-employee. RoleWeave owns local
orchestration, presentation, and receipt navigation. context and mem retain
ownership of source occurrences and durable memory.

No direct database coupling may bypass these boundaries.

REQ-008 — Domain neutrality

The core must not hard-code one organization's business vocabulary, one
vendor's data model, graph database assumptions, or unattended Agent autonomy.

Business semantics, metrics, rules, mappings, and action policies are supplied
by a domain pack or enterprise adapter.

Acceptance criteria

AC-001 — R2 decision and ownership

Record an accepted decision that freezes the glossary, repository ownership,
technical pilot, product owner, technical owner, domain-pack policy, and
revisit trigger.

Platform acceptance, technical-pilot acceptance, and business-domain acceptance
must remain separate.

AC-002 — Contract examples

Publish bounded examples for:

1. a read-only semantic analysis; and
2. a write-capable action proposal.

Examples must include evidence, semantic binding, uncertainty, permission,
approval, idempotency, target version, and readback.

AC-003 — Safety invariants

Add executable tests proving that:

• unauthorized actions cannot execute;
• missing approval blocks execution;
• retries preserve idempotency;
• stale targets invalidate proposals;
• expired proposals cannot execute; and
• indeterminate execution is never reported as success.

AC-004 — Deterministic read-only proof

Using the GitHub operations pilot from #302, demonstrate:

source -> semantic binding -> object / relationship
       -> derived state -> evidence-backed result

This proof must not claim live business impact.

AC-005 — Controlled write proof

Demonstrate one low-risk write-capable path:

action proposal -> policy / approval -> idempotent execution
                -> exact readback -> execution receipt

A contract example or mock execution is not equivalent to live external
execution. The verification level must be stated explicitly.

AC-006 — Existing contract reconciliation

Document what is reused, extended, or intentionally unchanged from #327,
#143, workflow-handoff-v1, existing permission and approval records, and the
GitHub operations proof.

AC-007 — Security and data boundary

Define workspace and tenant scope, actor identity, execution-time permission
re-evaluation, sensitive-field handling, retention and expiry, audit access,
source ownership, and public-repository exclusions.

Credentials, private chat content, and raw customer data must not enter the
public contract or examples.

AC-008 — Evidence ledger

Every implementation PR must record the consumed Issue revision, exact commit
and PR head, test commands and results, CI status, independent review status,
security and scope checks, known limitations, and product acceptance status.

Design complete, implemented, CI-green, reviewed, merged, and product-accepted
are separate states.

Issue lifecycle and governance

The intended lifecycle is:

needs-design -> ready -> in-progress -> product-review -> accepted

Any semantic change must first be recorded as an append-only
requirement-decision comment. The Issue body then advances to a new revision,
and every implementation PR must state which revision it consumes.

A green CI run or a merged PR does not by itself close this Issue. Product
acceptance requires the evidence ledger and an explicit decision on the current
revision.

Technical pilot and domain packs

The technical pilot is the GitHub operations path from #302.

Any business domain may later be validated as an optional domain pack, but no
single domain is a committed core vocabulary or a prerequisite for the
domain-neutral platform.

Users and organizations must be able to bring their own business objects,
metrics, rules, evidence mappings, and action policies through the same
portable contracts.

Current evidence

As of 2026-09-18:

• PR docs(platform): record trusted execution semantic contract R1 (#328) #346 records the R1 design decision and trusted-execution semantics. It is
  open and requires review; no runtime behavior is claimed.
• PR docs(platform): record Ontology Runtime R2 contract for trusted execution (#328) #344 records the R2 Ontology Runtime contract, examples, and fail-closed
  tests. It is open and requires review; it is not live external execution.
• Product and technical owners are not yet frozen in this Issue.
• No production readiness, business result, or merge is claimed by this Issue.

Non-goals

This Issue does not include:

• a general-purpose ontology editor;
• a graph database;
• a data warehouse or BI replacement;
• a Palantir clone;
• a universal enterprise ontology;
• unrestricted Agent autonomy;
• unattended scheduling or automatic routing;
• replacement of context or mem;
• direct database access from RoleWeave; or
• business ROI claims before a separately approved pilot.

Delivery sequence

1. Accept the R2 decision and assign owners.
2. Merge the portable semantic and execution contract.
3. Merge bounded examples and executable safety tests.
4. Deliver the deterministic read-only proof.
5. Deliver one controlled low-risk write proof.
6. Split runtime implementation into repository-owned child Issues.
7. Validate one domain pack separately from core platform acceptance.
8. Measure execution success, readback completeness, duplicate-action rate,
   indeterminate rate, approval latency, operator correction rate, and relevant
   token/tool-result cost.

Definition of done

This Issue may move to an accepted design state only when:

• R2 ownership and boundaries are accepted;
• the glossary and contracts are versioned;
• the examples are present;
• safety invariants are executable;
• the technical pilot is explicitly selected;
• implementation gaps are split into child Issues; and
• no design, CI, merge, or business-acceptance claim is overstated.

Runtime implementation, live external execution, domain-pack validation, and
business outcomes require separate Issues and evidence.

Non-normative references

• Getui AIBI practice: https://www.getui.com/news/2026090841
• OntoFlow discussion: https://mp.weixin.qq.com/s/qy1OOT0_wbq15Rw_iuEWrQ