06-reference

data engineering weekly operational ontology

2026-08-26·reference·source: Data Engineering Weekly·by Ananth Packkildurai
ontologywrite-path-governanceai-agentsknowledge-graphddd-cqrsdata-engineering

"Building an Operational Ontology: An E-Commerce Walkthrough" — Ananth Packkildurai

Why this is in the vault

The write-side sequel to the Aug 14 DEW essay on agent ontologies ([[2026-08-14-data-engineering-weekly-agent-ontology]]): where that piece argued a read-side ontology needs a layered vocabulary, this one argues a write-side ontology needs named, rule-guarded actions instead of a generic UPDATE path — and ships a minimal open-source TypeScript reference implementation (MIT, github.com/gura105/operational-ontology) that runs every scene in the walkthrough.

Mapping against Ray Data Co

Direct hit on /supervise, RDCO's dormant fresh-eyes pre-flight verifier for write-path actions (Notion writes outside the task board, outbound email to non-founder recipients, financial/Stripe actions, public GitHub pushes, calendar invites to external attendees). Packkildurai's pattern names exactly the shape /supervise is reaching for without the vocabulary: a named action (cancelOrder, assignOrder) with a declared precondition (refuse if already shipped), a structured refusal (SHIPPED_ORDER_CANNOT_BE_CANCELLED, not a buried exception), and an append-only audit log of every attempt — applied or refused. /supervise currently returns APPROVE / REQUEST CHANGES / ESCALATE TO FOUNDER on an ad hoc basis per write-path type; this essay's three questions (who is the SSoT for this state — source-backed, ontology-owned, or derived? what happens when write-back fails? do changes survive a re-index?) are a sharper pre-registration checklist than what /supervise's proposal currently specifies, and worth folding in before that skill gets founder greenlight to activate.

Second connection: RDCO's own knowledge graph (~/.claude/scripts/graph-ingest.py → graph.duckdb, queried via /graph-query) is exactly the "read side is business as usual" half of this pattern — objects and links, traversed freely, no write path. The essay's closing move — the agent-facing surface should expose only the same named actions a human gets, never raw SQL, so a business rule holds "however the prompt is rewritten" — is the argument for why /graph-query should stay read-only rather than growing ad hoc write/edit tools as a convenience: any future write surface on the graph should get named, precondition-gated actions (e.g. a retireMemory action with a "don't retire a <24h-old correction" precondition) rather than a generic upsert exposed to agents.

The core argument

Two merged order systems (north.tbl_order, south.SALES_ORDER) get integrated into a single read model — objects (Customer, Order, Product) and links, the same shape as a semantic layer. That's the easy, familiar half. The hard half surfaces the first time someone tries to act on the model: there's no cancel button, because reading and writing are different problems. Palantir Foundry's Ontology is the working example — "semantic" elements (objects/links) plus "kinetic" elements (actions/functions) — and the single differentiating question is: can you cancel an order from your semantic layer?

The fix is not a generic write API (anyone could fire an UPDATE; nothing defends business reality) but named actions: cancelOrder declares its target, parameters, precondition ("refuse if already shipped"), and effects (local edit + write-back to the source system). Refusal is a first-class structured return value, not an exception — "in the same spirit as Result types in Rust or Haskell." Every attempt, applied or refused, hits an audit log.

Three questions become unavoidable once writes exist: (1) who is the single source of truth for each piece of state — source-backed (write-back propagates upstream), ontology-owned (no legacy column exists; the ontology's own store is authoritative), or derived (computed, never written) — with "state with no declared owner" forbidden; (2) what happens when write-back fails, declared in advance rather than discovered as a production outage; (3) do action-driven changes survive a re-index — cancellations survive by construction (write-back already changed the source), assignments survive via an overlay that reapplies ontology-owned deltas onto each freshly re-indexed base.

Everything carries over unchanged to AI agents: the operations an agent receives are model-generated — read tools (search_order) from objects/links, write tools (cancel_order) only from predefined actions, no raw SQL ever handed over. The same precondition that refuses a human refuses an agent, with the same structured error code — so the business rule holds regardless of how the prompt is written. Deliberately out of scope: authorization (who may call which action) and concurrency/idempotency — preconditions are validity rules, not permissions.

Closing prescription: don't start with a company-wide model. Pick one operation a person actually decides and performs, build one object, one action, one precondition, one audit log, one write-back — the write side starts there.

Related