openoma 0.1.0__tar.gz

openoma-0.1.0/PKG-INFO

@@ -0,0 +1,1009 @@
+Metadata-Version: 2.4
+Name: openoma
+Version: 0.1.0
+Summary: Opera Autonoma is designed to be a versatile and powerful tool for automating various tasks and processes. It provides a user-friendly interface and a wide range of features to help users streamline their workflows and increase productivity.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.12.5
+
+# Openoma (Opera Autonoma) Specification 
+
+
+> **I vibe-coded this library via Claude Opus 4.6**
+---
+> **Open Operational Model Architecture** — A declarative framework for modeling,
+> composing, and tracking operational processes in organizations.
+
+**Version:** 0.1.0-draft  
+**Status:** Draft  
+
+---
+
+## 1. Philosophy
+
+Openoma separates **what work is** from **how work is done**.
+
+The framework is built on three principles:
+
+1. **Declarative over imperative.** Every entity — blocks, flows, contracts,
+   conditions, assessments — describes *what* should happen, never *how* to
+   execute it. Execution is a separate concern.
+2. **Composability.** Small units compose into larger units. Work blocks compose
+   into flows. Flows compose into contracts. Assessment itself is a flow.
+3. **Identity and immutability.** Every entity has a UUID. Every mutation
+   produces a new version. Executions reference a specific version, so the
+   definition of work never shifts under a running process.
+
+---
+
+## 2. Core Module — `openoma.core`
+
+The core module defines the logical model of operational processes. It contains
+no execution semantics.
+
+### 2.1 WorkBlock
+
+A **WorkBlock** is the atomic unit of operational work. It declares what inputs
+are needed and what outputs will be produced — like a single entry from a team's
+runbook.
+
+A WorkBlock is **reusable**: it can appear in many flows because it describes
+*what* needs to be done, not a specific instance of doing it.
+
+| Field             | Type                          | Description                                                                 |
+|-------------------|-------------------------------|-----------------------------------------------------------------------------|
+| `id`              | `UUID`                        | Stable identity across versions.                                            |
+| `version`         | `int`                         | Monotonically increasing. `(id, version)` is globally unique.               |
+| `name`            | `str`                         | Human-readable name.                                                        |
+| `description`     | `str`                         | Natural-language description of the work to be performed.                   |
+| `inputs`          | `list[PortDescriptor]`        | Declared input ports.                                                       |
+| `outputs`         | `list[PortDescriptor]`        | Declared output ports.                                                      |
+| `execution_hints` | `list[str]`                   | Optional capability tags (e.g. `"sql-access"`, `"api-gateway"`). Never names a specific executor. |
+| `metadata`        | `dict`                        | Arbitrary key-value pairs (tags, labels, ownership).                        |
+
+#### PortDescriptor
+
+A **PortDescriptor** names and describes a single input or output of a WorkBlock.
+
+| Field         | Type           | Description                                                   |
+|---------------|----------------|---------------------------------------------------------------|
+| `name`        | `str`          | Identifier unique within the block's input or output list.    |
+| `description` | `str`          | Natural-language description.                                 |
+| `required`    | `bool`         | Whether this port must be supplied / will always be produced.  |
+| `schema`      | `dict \| None` | Optional. A JSON Schema document describing the expected shape of data on this port. The framework does not enforce it; consumers and adapters may validate against it. |
+| `metadata`    | `dict`         | Optional. Hints for consumers (e.g. expected media type).     |
+
+> **Design decision — execution hints.** WorkBlocks may carry *capability hints*
+> that describe what tooling or access is needed, but they never name a specific
+> executor. The binding of a block to an executor is the responsibility of the
+> Execution module. This keeps the core model clean while still allowing
+> execution planners to filter and match blocks to capable executors.
+
+---
+
+### 2.2 Condition
+
+A **Condition** is a **value object** embedded in an edge. It governs traversal
+between nodes in a flow. Conditions are declarative — the framework stores them
+but never evaluates them. Evaluation is the responsibility of an external
+execution engine.
+
+Conditions are not first-class entities. They have no UUID and no version
+lineage. They exist only as part of the edge that contains them. If the same
+logical condition is needed on multiple edges, it is duplicated (or the
+consuming application maintains a condition template library outside Openoma).
+
+| Field         | Type            | Description                                                        |
+|---------------|-----------------|--------------------------------------------------------------------|
+| `description` | `str`           | Natural-language description (prompt-like). Always present.        |
+| `predicate`   | `dict \| None`  | Optional structured predicate (e.g. JSONLogic, CEL expression, or a simple expression tree). |
+| `metadata`    | `dict`          | Optional.                                                          |
+
+A Condition with only a `description` is evaluated by a human or an LLM agent.
+A Condition with a `predicate` can be evaluated programmatically. Both can
+coexist — the description serves as documentation, the predicate as machine
+logic.
+
+---
+
+### 2.3 Flow
+
+A **Flow** is a directed graph of nodes connected by edges with optional
+conditions. It is the primary composition mechanism in Openoma.
+
+Key properties:
+
+- A flow is **not necessarily fully connected**. It may contain multiple
+  disconnected subgraphs representing independent work streams.
+- A flow's nodes reference **WorkBlocks**.
+- A flow can appear in multiple contracts.
+
+#### 2.3.1 NodeReference
+
+A **NodeReference** is a *slot* within a flow that points to a WorkBlock. The
+same WorkBlock can be referenced multiple times within the same flow (e.g. two
+parallel lanes doing the same type of work with different executors). Each slot
+has its own UUID so that executions, edges, and conditions can address it
+unambiguously.
+
+| Field            | Type                       | Description                                                      |
+|------------------|----------------------------|------------------------------------------------------------------|
+| `id`             | `UUID`                     | Unique slot identifier within this flow.                         |
+| `target_id`      | `UUID`                     | The referenced WorkBlock ID.                                     |
+| `target_version` | `int`                      | The pinned version of the target.                                |
+| `alias`          | `str \| None`              | Optional human label (e.g. `"primary-review"`, `"backup-review"`). |
+| `metadata`       | `dict`                     | Optional.                                                        |
+
+> **Design decision — same block, two slots.** When the same task must be
+> performed in parallel (e.g. by different teams), the flow creates two
+> NodeReferences pointing to the same WorkBlock. The core model is identical;
+> differentiation happens in the Execution module where each slot is assigned
+> to a different executor.
+
+#### 2.3.2 Edge
+
+An **Edge** connects two nodes in the flow's directed graph.
+
+| Field           | Type                   | Description                                                   |
+|-----------------|------------------------|---------------------------------------------------------------|
+| `source_id`     | `UUID \| None`         | Source NodeReference ID. `None` marks an **entry edge** — the node is a starting point. |
+| `target_id`     | `UUID`                 | Target NodeReference ID.                                      |
+| `condition`     | `Condition \| None`    | Traversal condition. `None` means unconditional.              |
+| `port_mappings` | `list[PortMapping]`    | How outputs of the source node map to inputs of the target node. Empty list if no explicit mapping (adapter uses convention). |
+
+- Entry edges (`source_id = None`) designate starting nodes of the flow or of
+  a disconnected subgraph. Port mappings on entry edges describe how external
+  inputs to the flow are wired to the entry node's input ports.
+- Terminal nodes are nodes with no outgoing edges.
+
+#### PortMapping
+
+A **PortMapping** connects an output port on the source node to an input port
+on the target node.
+
+| Field         | Type   | Description                                           |
+|---------------|--------|-------------------------------------------------------|
+| `source_port` | `str`  | Name of an output port on the source node.            |
+| `target_port` | `str`  | Name of an input port on the target node.             |
+
+Port mappings are optional. When omitted, adapters may apply convention-based
+wiring (e.g. matching port names). When present, they make data flow explicit
+and portable across adapters.
+
+#### 2.3.3 Flow Entity
+
+| Field              | Type                     | Description                                                        |
+|--------------------|--------------------------|--------------------------------------------------------------------|
+| `id`               | `UUID`                   | Stable identity.                                                   |
+| `version`          | `int`                    | Monotonically increasing.                                          |
+| `name`             | `str`                    | Human-readable name.                                               |
+| `description`      | `str`                    | Natural-language description.                                      |
+| `nodes`            | `list[NodeReference]`    | All slots in this flow.                                            |
+| `edges`            | `list[Edge]`             | Directed edges between slots, with optional conditions.            |
+| `expected_outcome` | `Any \| None`            | Opaque blob. Declared upfront: what this flow is meant to achieve. |
+| `metadata`         | `dict`                   | Optional.                                                          |
+
+> **Interpreted outcome.** A flow's *interpreted outcome* is not stored in the
+> core model. It is derived at execution time from the actual outputs of its
+> terminal nodes. The core model only stores the *expected* outcome as a
+> declarative goal.
+
+---
+
+### 2.4 Contract
+
+A **Contract** is the highest-level organizational unit. It models an
+organizational commitment — a mission, an SLA, a project charter — with two
+sides:
+
+| Side              | Contains                                                                   |
+|-------------------|----------------------------------------------------------------------------|
+| **Work side**     | Workflows (FlowReferences) and/or sub-contracts (ContractReferences) that carry out the work. |
+| **Outcome side**  | Required outcomes (declarative goals) and assessment flows that evaluate whether goals are met. |
+
+#### 2.4.1 RequiredOutcome
+
+A **RequiredOutcome** is a named, opaque declaration of what the contract must
+achieve.
+
+| Field         | Type     | Description                                        |
+|---------------|----------|----------------------------------------------------|
+| `id`          | `UUID`   | Identity.                                          |
+| `name`        | `str`    | Human label (e.g. `"99.9% uptime"`, `"Q3 revenue target"`). |
+| `description` | `str`    | Natural-language specification of the outcome.     |
+| `metadata`    | `dict`   | Optional.                                          |
+
+#### 2.4.2 Assessment Flows
+
+Assessment is modeled as a **regular Flow** with one constraint:
+
+> **An assessment flow must have exactly one terminal node.** The output of that
+> terminal node is the assessment result for the required outcome it evaluates.
+
+Assessment flows are first-class flows. They can contain WorkBlocks that pull
+data from test executions, compare against required outcomes, compute scores,
+and produce a final verdict. Because they are flows, they themselves can be
+executed, tracked, versioned, and even assessed by higher-level contracts.
+
+The Contract links each RequiredOutcome to one or more assessment flows. The
+assessment flows may consume:
+
+- Outputs from the contract's **work-side flows** (the work being assessed).
+- Outputs from dedicated **test flows** (flows specifically designed to probe
+  outcomes, e.g. integration tests, audits, KPI computations).
+- Assessment results from **sub-contracts**.
+
+#### 2.4.3 ContractReference
+
+| Field              | Type           | Description                          |
+|--------------------|----------------|--------------------------------------|
+| `contract_id`      | `UUID`         | Referenced sub-contract.             |
+| `contract_version` | `int`          | Pinned version.                      |
+| `alias`            | `str \| None`  | Optional human label.                |
+| `metadata`         | `dict`         | Optional.                            |
+
+#### 2.4.4 AssessmentBinding
+
+An **AssessmentBinding** links a RequiredOutcome to its assessment mechanism.
+
+| Field                 | Type                     | Description                                                    |
+|-----------------------|--------------------------|----------------------------------------------------------------|
+| `required_outcome_id` | `UUID`                  | The outcome being assessed.                                    |
+| `assessment_flow_id`  | `UUID`                  | The flow that performs the assessment.                          |
+| `assessment_flow_version` | `int`               | Pinned version.                                                |
+| `test_flow_refs`      | `list[FlowReference]`   | Flows whose execution outputs are supplied as inputs to the assessment flow's entry nodes. The adapter is responsible for wiring test flow terminal-node outputs to assessment flow entry-node inputs. |
+| `metadata`            | `dict`                  | Optional.                                                      |
+
+#### 2.4.5 Contract Entity
+
+| Field                  | Type                        | Description                                           |
+|------------------------|-----------------------------|-------------------------------------------------------|
+| `id`                   | `UUID`                      | Stable identity.                                      |
+| `version`              | `int`                       | Monotonically increasing.                             |
+| `name`                 | `str`                       | Human-readable name.                                  |
+| `description`          | `str`                       | Natural-language description.                         |
+| `work_flows`           | `list[FlowReference]`      | Operational workflows on the work side.               |
+| `sub_contracts`        | `list[ContractReference]`   | Nested contracts on the work side.                    |
+| `required_outcomes`    | `list[RequiredOutcome]`     | Declared goals on the outcome side.                   |
+| `assessment_bindings`  | `list[AssessmentBinding]`   | Links outcomes to assessment flows and test flows.    |
+| `metadata`             | `dict`                      | Optional.                                             |
+
+#### FlowReference
+
+Used anywhere a flow is referenced by another entity.
+
+| Field          | Type           | Description              |
+|----------------|----------------|---------------------------|
+| `flow_id`      | `UUID`         | Referenced flow.         |
+| `flow_version` | `int`          | Pinned version.          |
+| `alias`        | `str \| None`  | Optional human label to distinguish multiple references to the same flow. |
+| `metadata`     | `dict`         | Optional.                |
+
+---
+
+### 2.5 Versioning Model
+
+All primary entities (WorkBlock, Flow, Contract) follow the same versioning
+scheme:
+
+- **`id`** (`UUID`) is the stable identity of the entity across all versions.
+- **`version`** (`int`) starts at `1` and increments with each mutation.
+- The pair `(id, version)` is globally unique and immutable once created.
+- All references to an entity pin a specific version (`target_id` +
+  `target_version`, `flow_id` + `flow_version`, etc.).
+- Executions always reference a pinned version, ensuring the definition of work
+  cannot change under a running process.
+- Creating a new version does **not** invalidate existing versions. Old versions
+  remain accessible for auditing and for in-flight executions.
+
+---
+
+### 2.6 Entity Relationship Summary
+
+```
+Contract
+├── work_flows ──────→ Flow (via FlowReference)
+├── sub_contracts ───→ Contract (via ContractReference)
+├── required_outcomes: [RequiredOutcome]
+└── assessment_bindings
+    ├── required_outcome_id → RequiredOutcome
+    ├── assessment_flow_id → Flow (assessment flow, 1 terminal node)
+    └── test_flow_refs ───→ [Flow] (via FlowReference)
+
+Flow
+├── nodes: [NodeReference]
+│   └── target_id → WorkBlock
+└── edges: [Edge]
+    ├── source_id → NodeReference (or None for entry)
+    ├── target_id → NodeReference
+    ├── condition → Condition (value object, optional)
+    └── port_mappings → [PortMapping] (source_port → target_port)
+
+WorkBlock
+├── inputs: [PortDescriptor]  (each with optional schema)
+├── outputs: [PortDescriptor] (each with optional schema)
+└── execution_hints: [str]
+
+Execution Interfaces
+├── EventStore (protocol) ← storage backends implement
+└── ExecutionAdapter (protocol, uses EventStore) ← orchestration engines implement
+```
+
+---
+
+## 3. Execution Module — `openoma.execution`
+
+The execution module records **how** work defined in the core module was carried
+out. It is strictly separate: the core model is a blueprint; the execution model
+is the as-built record.
+
+The execution module never modifies core entities. It only references them.
+
+### 3.1 Event-Sourced Execution Log
+
+All execution state is derived from an **append-only event log**. Execution
+entities (BlockExecution, FlowExecution, ContractExecution) are projections
+of the event stream — they are materialized views, not mutable records.
+
+This design is motivated by a key principle from modern agent infrastructure:
+**the session must outlive any single executor.** If an agent crashes, a human
+goes off-shift, or an orchestration engine is swapped, the event log remains
+the durable source of truth. A new executor can resume from the last event
+without data loss.
+
+#### ExecutionEvent
+
+Every state change in the execution module is recorded as an immutable event.
+
+| Field              | Type                     | Description                                                       |
+|--------------------|--------------------------|-------------------------------------------------------------------|
+| `id`               | `UUID`                   | Unique event identity.                                            |
+| `timestamp`        | `datetime`               | When the event was recorded.                                      |
+| `execution_id`     | `UUID`                   | The BlockExecution, FlowExecution, or ContractExecution this event belongs to. |
+| `event_type`       | `ExecutionEventType`     | The type of state transition (see below).                         |
+| `executor`         | `ExecutorInfo \| None`   | The executor active at the time of this event (if applicable).    |
+| `payload`          | `Any`                    | Event-specific data (opaque blob).                                |
+| `metadata`         | `dict`                   | Optional.                                                         |
+
+#### ExecutionEventType
+
+| Event Type            | Description                                                           |
+|-----------------------|-----------------------------------------------------------------------|
+| `created`             | Execution entity was initialized.                                     |
+| `executor_assigned`   | An executor was assigned or reassigned.                               |
+| `executor_released`   | An executor released the execution (crash, handoff, shift end).       |
+| `started`             | Work began.                                                           |
+| `progress`            | Intermediate progress update (opaque payload).                        |
+| `outcome_produced`    | An output was produced (payload contains the outcome blob).           |
+| `completed`           | Execution finished successfully.                                      |
+| `failed`              | Execution finished with an error.                                     |
+| `skipped`             | Execution was deliberately skipped.                                   |
+| `cancelled`           | Execution was aborted.                                                |
+
+#### ExecutionState (derived)
+
+The current state of any execution entity is **derived** by replaying its event
+stream. The canonical states are:
+
+| State         | Description                                           |
+|---------------|-------------------------------------------------------|
+| `pending`     | `created` event exists, no `started` event yet.       |
+| `in_progress` | `started` event exists, no terminal event yet.        |
+| `completed`   | `completed` event exists.                             |
+| `failed`      | `failed` event exists.                                |
+| `skipped`     | `skipped` event exists.                               |
+| `cancelled`   | `cancelled` event exists.                             |
+
+> **Resumability.** Because state is derived from events, any executor can
+> pick up an execution by reading the event log. The `executor_assigned` and
+> `executor_released` events make handoffs explicit. An orchestration engine
+> that crashes simply stops emitting events; a replacement reads the log up
+> to the last event and resumes.
+
+### 3.2 ExecutorInfo
+
+Executor identity is recorded **per event**, not per execution, because
+executors can change over the lifetime of an execution (crash recovery, shift
+handoff, escalation from agent to human).
+
+| Field        | Type                            | Description                                      |
+|--------------|---------------------------------|--------------------------------------------------|
+| `type`       | `"human" \| "agent" \| "system"` | Category of executor.                           |
+| `identifier` | `str`                           | Unique identifier (user ID, agent name, system URI). |
+| `metadata`   | `dict`                          | Optional (team, role, model version, etc.).       |
+
+> **Executor continuity.** The execution log naturally records the full
+> lineage of who worked on what. If agent A starts a block, crashes, and
+> agent B resumes, the event stream contains:
+> `executor_assigned(A)` → `started` → `executor_released(A)` →
+> `executor_assigned(B)` → `completed`. No information is lost.
+
+### 3.3 BlockExecution
+
+A **BlockExecution** is a projection over the event stream for a single
+WorkBlock execution within a specific flow context.
+
+| Field              | Type                     | Description                                                       |
+|--------------------|--------------------------|-------------------------------------------------------------------|
+| `id`               | `UUID`                   | Unique execution identity.                                        |
+| `node_reference_id`| `UUID`                   | The NodeReference (slot) in the flow that was executed.            |
+| `work_block_id`    | `UUID`                   | The WorkBlock that was executed.                                   |
+| `work_block_version` | `int`                  | Pinned version.                                                   |
+| `state`            | `ExecutionState`         | Derived from event stream.                                        |
+| `events`           | `list[ExecutionEvent]`   | The ordered event log for this execution.                         |
+
+Inputs, outcomes, executor assignments, timing, and attempt counts are all
+read from the event stream rather than stored as top-level fields.
+
+### 3.4 FlowExecution
+
+A **FlowExecution** records the execution of a flow as a whole. Its state is
+**derived** from its block executions — it is not set independently.
+
+| Field               | Type                        | Description                                                     |
+|---------------------|-----------------------------|-----------------------------------------------------------------|
+| `id`                | `UUID`                      | Unique execution identity.                                      |
+| `flow_id`           | `UUID`                      | The flow being executed.                                        |
+| `flow_version`      | `int`                       | Pinned version.                                                 |
+| `block_executions`  | `list[UUID]`                | BlockExecution IDs. **Many-to-many**: a BlockExecution can belong to multiple FlowExecutions. |
+| `state`             | `ExecutionState`            | Derived from constituent block executions.                      |
+| `events`            | `list[ExecutionEvent]`      | Flow-level events (e.g. flow started, flow completed).          |
+
+> **Shared execution outcomes.** A single BlockExecution (with its UUID and
+> outcome) can be referenced by multiple FlowExecutions if the work it
+> represents satisfies requirements in all of them. This avoids redundant
+> execution of identical work.
+
+#### FlowExecution State Derivation
+
+A FlowExecution's state is derived deterministically from its block executions:
+
+| Rule | Condition | Derived State |
+|------|-----------|---------------|
+| 1 | Any block is `failed`. | `failed` |
+| 2 | Any block is `cancelled`. | `cancelled` |
+| 3 | All **terminal nodes** are `completed` or `skipped`. | `completed` |
+| 4 | Any block is `in_progress` or `pending` (and no rule 1–2 applies). | `in_progress` |
+| 5 | All blocks are `pending`. | `pending` |
+
+Rules are evaluated in priority order (1 is highest). A terminal node is a
+node with no outgoing edges in the flow definition. Skipped terminal nodes
+count as satisfied — they represent branches that were legitimately not taken.
+
+### 3.5 ContractExecution
+
+A **ContractExecution** records the execution state of a contract.
+
+| Field                      | Type                         | Description                                                  |
+|----------------------------|------------------------------|--------------------------------------------------------------|
+| `id`                       | `UUID`                       | Unique execution identity.                                   |
+| `contract_id`              | `UUID`                       | The contract being executed.                                  |
+| `contract_version`         | `int`                        | Pinned version.                                               |
+| `flow_executions`          | `list[UUID]`                 | FlowExecution IDs for work-side flows. **Many-to-many**: a FlowExecution can belong to multiple ContractExecutions. |
+| `sub_contract_executions`  | `list[UUID]`                 | ContractExecution IDs for sub-contracts.                      |
+| `assessment_executions`    | `list[AssessmentResult]`     | Assessment flow execution results.                            |
+| `state`                    | `ExecutionState`             | Derived from flow and sub-contract executions.                |
+| `events`                   | `list[ExecutionEvent]`       | Contract-level events.                                        |
+
+#### ContractExecution State Derivation
+
+A ContractExecution's state is derived from its flow executions and
+sub-contract executions:
+
+| Rule | Condition | Derived State |
+|------|-----------|---------------|
+| 1 | Any flow execution or sub-contract execution is `failed`. | `failed` |
+| 2 | Any flow execution or sub-contract execution is `cancelled`. | `cancelled` |
+| 3 | All flow executions and sub-contract executions are `completed` or `skipped`. | `completed` |
+| 4 | Any is `in_progress` or `pending` (and no rule 1–2 applies). | `in_progress` |
+| 5 | All are `pending`. | `pending` |
+
+Assessment flow executions are **not** factored into the contract's work-side
+state derivation. They run independently and their results populate the
+`assessment_executions` list. A contract can be `completed` (all work done)
+but have failing assessments — this is an important distinction between
+"work finished" and "goals met."
+
+#### AssessmentResult
+
+Links an assessment flow's execution to the required outcome it evaluated.
+
+| Field                      | Type       | Description                                              |
+|----------------------------|------------|----------------------------------------------------------|
+| `required_outcome_id`      | `UUID`     | The outcome being assessed.                              |
+| `assessment_flow_execution_id` | `UUID` | The FlowExecution of the assessment flow.                |
+| `result`                   | `Any`      | The terminal node's output — the assessment verdict.     |
+
+---
+
+## 4. Execution Interfaces — `openoma.adapter` and `openoma.store`
+
+Openoma defines the **what** (core) and the **record** (execution). Two
+interfaces connect it to the outside world:
+
+- **Execution Adapter** — drives work (orchestration engines implement this).
+- **Event Store** — persists and retrieves the event log (storage backends
+  implement this).
+
+These are deliberately separate concerns. An orchestration engine (CrewAI,
+Managed Agents, Temporal, a human task board) should not need to implement
+storage. A storage backend (Kafka, EventStoreDB, a NoSQL collection, an
+in-memory test store) should not need to know how work is executed.
+
+### 4.1 Event Store Protocol
+
+```python
+class EventStore(Protocol):
+    """Interface for persisting and retrieving the execution event log."""
+
+    def append(self, event: ExecutionEvent) -> None:
+        """Append an event to the log. Immutable once appended."""
+        ...
+
+    def get_events(
+        self,
+        execution_id: UUID,
+        after: datetime | None = None,
+    ) -> list[ExecutionEvent]:
+        """Retrieve events for an execution, optionally after a timestamp.
+
+        Returns events in chronological order.
+        """
+        ...
+
+    def get_latest_event(self, execution_id: UUID) -> ExecutionEvent | None:
+        """Retrieve the most recent event for an execution.
+
+        Used for quick state checks and resumption without replaying
+        the full log.
+        """
+        ...
+```
+
+Openoma ships an `InMemoryEventStore` for testing and prototyping. Production
+deployments implement the protocol with their storage backend of choice.
+
+### 4.2 Execution Adapter Protocol
+
+```python
+class ExecutionAdapter(Protocol):
+    """Interface that any orchestration engine implements to drive Openoma."""
+
+    def execute_block(
+        self,
+        block: WorkBlock,
+        node_ref: NodeReference,
+        inputs: Any,
+        store: EventStore,
+    ) -> UUID:
+        """Begin execution of a work block.
+
+        The adapter is responsible for:
+        - Selecting an appropriate executor based on execution_hints.
+        - Emitting ExecutionEvents via `store.append()`.
+        - Returning the BlockExecution UUID.
+
+        The adapter must NOT modify the WorkBlock or NodeReference.
+        """
+        ...
+
+    def resume_block(
+        self,
+        block_execution_id: UUID,
+        store: EventStore,
+    ) -> None:
+        """Resume a block execution from the last event in its log.
+
+        Called when an executor crashes or is replaced. The adapter reads
+        the event stream via `store.get_events()`, determines the last
+        known state, and continues.
+        """
+        ...
+
+    def evaluate_condition(
+        self,
+        condition: Condition,
+        context: Any,
+    ) -> bool:
+        """Evaluate a traversal condition given the current execution context.
+
+        For conditions with a structured predicate, the adapter may evaluate
+        it directly. For natural-language conditions, it may delegate to an
+        LLM, a human, or any other mechanism.
+        """
+        ...
+```
+
+### 4.3 Adapter and Store Semantics
+
+- **The adapter drives; the store records.** The adapter decides *when* to
+  emit events. The store decides *where* events are persisted. Neither knows
+  the other's implementation.
+- **The store is injected into the adapter.** Adapter methods receive the
+  store as a parameter. This allows the same adapter to work against different
+  storage backends without modification.
+- **Multiple adapters can coexist.** A human-task adapter for manual work, an
+  agent adapter for AI-driven blocks, a CI/CD adapter for automated pipelines
+  — all writing to the same event store.
+- The adapter is responsible for **executor selection**. It reads the
+  WorkBlock's `execution_hints` and matches them against available executors.
+- The adapter is responsible for **condition evaluation**. It reads the
+  Condition's `description` and/or `predicate` and returns a boolean.
+
+> **Analogy.** In Anthropic's Managed Agents architecture, the harness calls
+> hands via `execute(name, input) → string` and records to a durable session
+> log. In Openoma, the Execution Adapter is the harness interface, and the
+> Event Store is the session log interface. Both are abstract — any
+> orchestration engine implements the adapter, any storage backend implements
+> the store.
+
+---
+
+## 5. Design Principles
+
+### 5.1 Separation of Definition and Execution
+
+The core module (`openoma.core`) and the execution module (`openoma.execution`)
+are strictly separated. The core module defines the topology and intent of
+work. The execution module records what actually happened. A third-party
+orchestration engine reads the core model, decides how to execute it, and
+writes results into the execution model via the Execution Adapter.
+
+### 5.2 Event Sourcing
+
+Execution state is never mutated in place. Every state transition is an
+immutable event appended to a log. Current state is derived by replaying the
+log. This guarantees:
+
+- **Resumability.** Any executor can resume from the last event after a crash.
+- **Auditability.** The complete history of who did what and when is preserved.
+- **Executor independence.** The log outlives any single executor or
+  orchestration engine.
+
+### 5.3 Self-Similar Assessment
+
+Assessment is not a special mechanism — it is a regular flow with the constraint
+of having exactly one terminal node. This means:
+
+- Assessment flows can be versioned, executed, and tracked like any other flow.
+- Assessment flows can themselves be assessed by higher-level contracts.
+- The entire framework is recursively composable: contracts assess sub-contracts
+  whose assessments are themselves flows.
+
+### 5.4 Graph Topology Freedom
+
+Flows are directed graphs with no requirement for full connectivity. This
+supports real-world operational structures where independent work streams
+coexist within the same logical boundary without artificial sequencing.
+
+### 5.5 Many-to-Many Execution Sharing
+
+A BlockExecution can be claimed by multiple FlowExecutions, and a
+FlowExecution can be claimed by multiple ContractExecutions. This models
+reality: a single piece of completed work often satisfies obligations in
+multiple contexts.
+
+### 5.6 Opaque Outcomes
+
+Outcomes (inputs, outputs, assessment verdicts) are opaque blobs. The framework
+stores and routes them but does not inspect their contents. Schema enforcement,
+if desired, is the responsibility of the execution engine or a validation layer
+built on top of Openoma.
+
+### 5.7 Orchestration Agnosticism
+
+Openoma makes no assumptions about the orchestration engine. It does not
+assume agents, does not assume humans, does not assume any particular
+scheduling model. The Execution Adapter and Event Store protocols are the only
+contracts between Openoma and the outside world. This ensures the framework
+remains a stable substrate as orchestration tools evolve — today's harness
+assumptions become tomorrow's dead weight, but the data model persists.
+
+### 5.8 Flows as Templates, Executions as Instances
+
+A Flow in the core model is a **template** — a reusable definition of work
+structure. Each time a flow is run, a new **FlowExecution** is created in the
+execution module. The same flow can produce many FlowExecutions (e.g. a sprint
+cycle flow runs every two weeks).
+
+Contracts reference flows (via FlowReference), not flow executions. A contract
+does not model recurrence — it declares which flows constitute its work side.
+Recurrence, scheduling, and triggering are the orchestration engine's concern.
+Each run of a contract's workflows produces a new set of FlowExecutions, which
+are grouped under a **ContractExecution**.
+
+This means:
+- The same Contract can have many ContractExecutions (one per evaluation
+  period, milestone, or triggered run).
+- The same Flow can have many FlowExecutions across different
+  ContractExecutions or even the same one (e.g. a "daily health check" flow
+  executed multiple times within a single contract period).
+- Openoma tracks every execution instance independently — the full history is
+  in the event log.
+
+---
+
+## 6. Illustrative Example
+
+> An organization modeled end-to-end with Openoma.
+
+### The Mission (Contract)
+
+```
+Contract: "Q3 Product Launch"
+├── required_outcomes:
+│   ├── "Feature X shipped to production"
+│   └── "Customer satisfaction ≥ 4.5/5"
+├── work_flows:
+│   ├── Flow: "Engineering Sprint Cycle"
+│   └── Flow: "QA Validation Pipeline"
+├── sub_contracts:
+│   └── Contract: "Infrastructure SLA"
+│       ├── required_outcomes: ["99.9% uptime"]
+│       ├── work_flows: [Flow: "Infra BAU"]
+│       └── assessment_bindings: [→ Flow: "Uptime Monitor Assessment"]
+└── assessment_bindings:
+    ├── "Feature X shipped" → assessment Flow: "Release Verification"
+    │   └── test_flows: [Flow: "Smoke Test Suite"]
+    └── "Satisfaction ≥ 4.5" → assessment Flow: "CSAT Evaluator"
+        └── test_flows: [Flow: "Survey Collection"]
+```
+
+### A Workflow (Flow)
+
+```
+Flow: "Engineering Sprint Cycle"
+├── nodes:
+│   ├── [slot-A] → WorkBlock: "Ticket Triage"
+│   ├── [slot-B] → WorkBlock: "Implementation"
+│   ├── [slot-C] → WorkBlock: "Code Review"
+│   └── [slot-D] → WorkBlock: "Implementation"   ← same block, second slot
+├── edges:
+│   ├── None → slot-A                            (entry)
+│   ├── slot-A → slot-B  [condition: "ticket is approved"]
+│   ├── slot-A → slot-D  [condition: "ticket is fast-track"]
+│   ├── slot-B → slot-C  (unconditional)
+│   └── slot-D → slot-C  (unconditional)
+└── expected_outcome: "All sprint tickets implemented and reviewed"
+```
+
+Note that `slot-B` and `slot-D` reference the same `WorkBlock: "Implementation"`
+but represent two parallel lanes. At execution time, they may be assigned to
+different engineers or agent systems.
+
+### Daily Work (WorkBlock)
+
+```
+WorkBlock: "Code Review"
+├── inputs:
+│   ├── name: "pull_request_url", description: "URL of the PR to review"
+│   └── name: "review_checklist", description: "Criteria for approval", required: false
+├── outputs:
+│   ├── name: "verdict", description: "approved | changes_requested | rejected"
+│   └── name: "comments", description: "Review comments"
+└── execution_hints: ["github-access", "codebase-read"]
+```
+
+### Assessment (Assessment Flow)
+
+```
+Flow: "Release Verification"  [assessment flow — 1 terminal node]
+├── nodes:
+│   ├── [slot-1] → WorkBlock: "Check Deployment Status"
+│   ├── [slot-2] → WorkBlock: "Run Smoke Tests"
+│   └── [slot-3] → WorkBlock: "Produce Release Verdict"  ← terminal
+├── edges:
+│   ├── None → slot-1
+│   ├── slot-1 → slot-2
+│   └── slot-2 → slot-3
+└── expected_outcome: "Binary pass/fail on release readiness"
+```
+
+The terminal node (`slot-3`) produces the assessment result that the contract
+uses to evaluate whether `"Feature X shipped to production"` is satisfied.
+
+---
+
+## 7. Module Boundary
+
+```
+openoma/
+├── core/           # Core model — definitions only
+│   ├── work_block.py
+│   ├── condition.py
+│   ├── flow.py
+│   ├── contract.py
+│   ├── types.py        # PortDescriptor, PortMapping, FlowReference, ContractReference, etc.
+│   └── versioning.py   # Version management utilities
+├── execution/      # Execution model — event-sourced records
+│   ├── events.py       # ExecutionEvent, ExecutionEventType
+│   ├── block_execution.py
+│   ├── flow_execution.py
+│   ├── contract_execution.py
+│   └── types.py        # ExecutorInfo, ExecutionState, AssessmentResult, etc.
+├── store/          # Event Store protocol + built-in implementations
+│   ├── protocol.py     # EventStore abstract interface
+│   └── memory.py       # InMemoryEventStore (for testing / prototyping)
+├── adapter/        # Execution Adapter protocol
+│   ├── protocol.py     # ExecutionAdapter abstract interface
+│   └── base.py         # Optional base class with common event-emitting logic
+├── validation/     # Invariant validators
+│   ├── graph.py        # Terminal node checks, edge validity
+│   └── references.py   # Version pin validation, reference integrity
+├── builders/       # Fluent builder APIs for constructing entities
+│   ├── work_block.py
+│   ├── flow.py
+│   └── contract.py
+└── __init__.py
+```
+
+---
+
+## 8. Constraints and Invariants
+
+1. **Assessment terminal constraint.** Any flow used as an assessment flow in
+   an AssessmentBinding must have exactly one terminal node (a node with no
+   outgoing edges).
+
+2. **Version pinning.** All cross-entity references must pin a specific
+   version. Unpinned references are not permitted.
+
+3. **No circular sub-contract inclusion.** A contract may not include itself
+   (directly or transitively) as a sub-contract.
+
+4. **NodeReference uniqueness.** Within a flow, each NodeReference has a unique
+   `id`, even if multiple references point to the same target entity.
+
+5. **Edge validity.** Every `source_id` and `target_id` in an edge must
+   reference a NodeReference that exists in the same flow's `nodes` list.
+
+6. **Event append-only.** Execution events are immutable once appended. Events
+   cannot be deleted or modified. State is always derived by replaying the log.
+
+7. **Terminal state finality.** Once an execution's derived state reaches a
+   terminal state (`completed`, `failed`, `cancelled`), no further
+   non-administrative events may be appended. A new execution must be created
+   for retries.
+
+8. **Adapter writes via store.** The Execution Adapter emits events
+   exclusively through the Event Store's `append()` method. The adapter
+   never writes directly to the underlying persistence layer.
+
+9. **Port mapping validity.** Every `source_port` in a PortMapping must
+    reference an output port that exists on the source node's WorkBlock.
+    Every `target_port` must reference an input port on the target node's
+    WorkBlock.
+
+---
+
+## 9. Out of Scope (for this framework)
+
+- **Orchestration / scheduling.** How flows get executed (task queues, agent
+  routing, human assignment) is the domain of an orchestration engine that
+  implements the Execution Adapter and drives Openoma models.
+- **Harness implementation.** The specific agent loop, context engineering,
+  prompt management, and model selection are the orchestration engine's
+  concern. Openoma only defines the adapter interface.
+- **Schema enforcement.** PortDescriptor may carry an optional `schema` field,
+  but the framework does not validate data against it. Enforcement is the
+  responsibility of adapters or validation layers.
+- **Production persistence.** Openoma ships an in-memory EventStore for
+  testing. Production storage backends (NoSQL, EventStoreDB, Kafka, etc.)
+  implement the EventStore protocol externally.
+- **Access control.** Authorization over who can view/edit/execute entities is
+  external.
+
+---
+
+## 10. Open Questions
+
+1. **Condition expression language.** Should the spec mandate a specific
+   structured predicate format (JSONLogic, CEL, custom AST), or leave it as an
+   opaque dict for now? Current decision: opaque dict, with a recommended
+   format to be specified in a future RFC.
+
+2. **Execution lineage.** Should the execution model track causal
+   relationships between block executions (e.g. "this block was triggered
+   because that block completed")? This could be a `triggered_by` field on the
+   `started` event's payload, enabling full provenance graphs.
+
+3. **Event compaction.** For long-running contracts, the event log may grow
+   very large. Should the spec define a compaction/snapshotting mechanism
+   that preserves auditability while bounding read costs?
+
+---
+
+## 11. What Ships in the Package
+
+When a consumer installs Openoma (`pip install openoma`), they get the
+following:
+
+### 11.1 Data Models
+
+Immutable, serializable data classes (Pydantic or dataclasses) for every entity
+in Sections 2 and 3:
+
+- **Core:** `WorkBlock`, `PortDescriptor`, `PortMapping`, `Condition`,
+  `NodeReference`, `Edge`, `Flow`, `Contract`, `RequiredOutcome`,
+  `AssessmentBinding`, `FlowReference`, `ContractReference`.
+- **Execution:** `ExecutionEvent`, `ExecutionEventType`, `ExecutorInfo`,
+  `ExecutionState`, `BlockExecution`, `FlowExecution`, `ContractExecution`,
+  `AssessmentResult`.
+
+All models support serialization to/from JSON-compatible dicts (ready for
+GraphQL resolvers, NoSQL documents, or API payloads).
+
+### 11.2 Validators
+
+Functions that enforce the invariants from Section 8:
+
+- `validate_flow(flow)` — checks edge validity, NodeReference uniqueness,
+  and assessment terminal constraint.
+- `validate_contract(contract)` — checks cycle detection (no circular
+  sub-contracts), version pin integrity, and assessment binding validity.
+- `validate_port_mappings(flow)` — checks that all port mappings reference
+  ports that exist on the source and target nodes.
+
+Validators raise structured errors with paths to the offending entity.
+
+### 11.3 State Derivation
+
+Pure functions that compute execution state from event streams:
+
+- `derive_block_state(events) → ExecutionState`
+- `derive_flow_state(block_executions) → ExecutionState`
+- `derive_contract_state(flow_executions, sub_contract_executions) → ExecutionState`
+
+These implement the rules from Sections 3.4 and 3.5.
+
+### 11.4 Protocols
+
+- `EventStore` protocol (Section 4.1) — for storage backends.
+- `ExecutionAdapter` protocol (Section 4.2) — for orchestration engines.
+
+### 11.5 Built-in Implementations
+
+- `InMemoryEventStore` — a simple in-memory EventStore for testing,
+  prototyping, and local development. Not suitable for production.
+
+### 11.6 Builder APIs
+
+Fluent builder classes for constructing entities without error-prone dict
+assembly:
+
+```python
+from openoma.builders import FlowBuilder, WorkBlockBuilder
+
+block = (
+    WorkBlockBuilder("Code Review")
+    .input("pull_request_url", "URL of the PR to review")
+    .input("review_checklist", "Criteria for approval", required=False)
+    .output("verdict", "approved | changes_requested | rejected")
+    .output("comments", "Review comments")
+    .hint("github-access")
+    .build()
+)
+
+flow = (
+    FlowBuilder("Sprint Cycle")
+    .add_block(block, alias="review")
+    .add_block(impl_block, alias="impl-primary")
+    .add_block(impl_block, alias="impl-fast-track")  # same block, two slots
+    .edge("impl-primary", "review")
+    .edge("impl-fast-track", "review")
+    .entry("impl-primary", condition=Condition(description="ticket is approved"))
+    .entry("impl-fast-track", condition=Condition(description="ticket is fast-track"))
+    .build()  # runs validate_flow() automatically
+)
+```
+
+### 11.7 What Openoma Does NOT Ship
+
+- **No orchestration engine.** No scheduler, no task queue, no agent loop.
+- **No production storage.** No database drivers, no Kafka integration.
+- **No UI.** No dashboard, no visualization.
+- **No network layer.** No REST/GraphQL server. (A separate `openoma-graphql`
+  package may be created for this.)
+
+Openoma is a **data model + validation + protocol** library. It is the stable
+kernel that other systems build on top of.