aoa-ocel 1.0.0__tar.gz

aoa_ocel-1.0.0/.gitignore

@@ -0,0 +1,92 @@
+# ============================================================================
+# Python
+# ============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# ============================================================================
+# Virtual environments
+# ============================================================================
+.venv/
+venv/
+ENV/
+env/
+
+# ============================================================================
+# Distribution / packaging
+# ============================================================================
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+
+# ============================================================================
+# Testing
+# ============================================================================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+*.cover
+.hypothesis/
+.tox/
+.nox/
+
+# ============================================================================
+# Type checking
+# ============================================================================
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# ============================================================================
+# Node (Maxitor web client — source lives in git; node_modules stays local only)
+# ============================================================================
+packages/aoa-maxitor/client/node_modules/
+packages/aoa-maxitor/client/.vite/
+
+# ============================================================================
+# IDE
+# ============================================================================
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# ============================================================================
+# Logs and temporary files
+# ============================================================================
+*.log
+code_quality.log
+*.tmp
+*.temp
+
+# ============================================================================
+# Project specific - ARCHIVE (ваши локальные снимки)
+# ============================================================================
+archive/
+*.ver
+code.txt
+project_structure.txt
+
+# ============================================================================
+# Локальные черновики (русские версии документации и примеров)
+# ============================================================================
+*_draft.md
+*_draft.py
+.ipynb_checkpoints/
+docs/ru/
+
+# ============================================================================
+# НЕ ИГНОРИРУЕМ - эти файлы должны быть в git!
+# ============================================================================
+!.python-version
+!uv.lock

aoa_ocel-1.0.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `aoa-ocel` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] – 2026-06-24
+
+### Added
+
+- **Initial standalone release, extracted from `aoa-action-machine`.** `OcelPlugin`, `OcelFrame`, `InMemoryOcelStoreResource`, `OcelStoreResource`, `OCEL_FRAMES_KEY`, and supporting DTOs are now distributed under the `aoa.ocel` namespace as a separate package (`pip install aoa-ocel`). The package depends on `aoa-action-machine` and `xxhash`. ([#71](https://github.com/bystrovmaxim/aoa/issues/71))
+
+For the pre-extraction history of `OcelPlugin` (originally introduced in the monorepo at `[0.12.8]`), see the [aoa-action-machine CHANGELOG](../aoa-action-machine/CHANGELOG.md).

aoa_ocel-1.0.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: aoa-ocel
+Version: 1.0.0
+Summary: OCEL 2.0 export plugin for AOA — expose action runs as object-centric event logs for process mining.
+Project-URL: Homepage, https://github.com/action-machine/action-machine
+Project-URL: Documentation, https://action-machine.readthedocs.io
+Project-URL: Repository, https://github.com/action-machine/action-machine
+Author: @Bystrov.Maxim
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: aoa-action-machine>=1.0.0a5
+Requires-Dist: xxhash<4,>=3.4

aoa_ocel-1.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+# packages/aoa-ocel/pyproject.toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aoa-ocel"
+version = "1.0.0"
+description = "OCEL 2.0 export plugin for AOA — expose action runs as object-centric event logs for process mining."
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [{ name = "@Bystrov.Maxim" }]
+dependencies = [
+    "aoa-action-machine>=1.0.0a5",
+    "xxhash>=3.4,<4",
+]
+
+[project.urls]
+Homepage = "https://github.com/action-machine/action-machine"
+Documentation = "https://action-machine.readthedocs.io"
+Repository = "https://github.com/action-machine/action-machine"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aoa"]

aoa_ocel-1.0.0/src/aoa/ocel/README.md

@@ -0,0 +1,118 @@
+<p align="center">
+  <img src="../../../../../../../docs/assets/aoa-logo.png" alt="AOA" width="660"><br><br>
+  <a href="https://github.com/bystrovmaxim/aoa"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white" alt="Python 3.12+"></a>
+  <img src="https://img.shields.io/badge/tests-26-brightgreen" alt="26 tests">
+  <a href="https://pypi.org/project/aoa-ocel/"><img src="https://img.shields.io/badge/install-aoa--ocel--plugin-blue?logo=pypi&logoColor=white" alt="pip install aoa-ocel"></a>
+  <img src="https://img.shields.io/badge/OCEL-2.0-orange" alt="OCEL 2.0">
+</p>
+
+# OCEL export (`aoa.ocel`)
+
+This module exports data in [OCEL 2.0](https://ocel-standard.org/) format. Install with ``pip install aoa-ocel``. It turns Action execution logs into object-centric event logs that Process Mining tools can consume.
+
+<p align="center">
+  <img src="../../../../../../../docs/assets/ocel-ocdfg.png" alt="Object-centric process graph (OCEL)" width="900">
+</p>
+
+### Viewing logs in OC-PM
+
+After ``await store.close()`` writes JSON, open the file in **[Object-Centric Process Mining (OC-PM)](https://www.ocpm.info/ocel.html)** — a browser app for OCEL JSON/XML logs. Upload the export, then use event/object explorers, OCDFG graphs, filters, and conformance views without extra tooling. See also ``examples/07_ocel.py`` and the Store batch export under ``packages/aoa-examples`` (``archive/logs/ocel.json`` in integration tests).
+
+## How it works
+
+The builder (``OcelPlugin.build_ocel_event``) maps domain entities to ``OcelEvent`` DTOs. **v1 uses E2O only; O2O is not exported.**
+
+We do **not** know in advance which questions process-mining users will ask. Export therefore prefers **reachability** (objects appear in event relationships when the aspect loaded them) over a minimal graph. Filters in PM tools can narrow views later; missing E2O cannot be recovered without re-export.
+
+### `OcelFrame` input
+
+Aspects return one or more `OcelFrame` rows in pipeline state:
+
+| Field | Role |
+|-------|------|
+| `object` | Root domain entity for this participation row |
+| `qualifier` | Required E2O role for the root (non-empty string) |
+| `attributes` | Optional event-level attributes (merged across frames; name clash with different values → error) |
+
+### E2O (event → object)
+
+**Rule — loaded relations only:** E2O includes **only relation containers that are loaded on `frame.object` at export time** (`BaseEntity.get_foreign_keys(loaded_only=True)`). Scalar FK columns and relations not loaded on the instance are **not** exported. Nothing is read from the database beyond what the aspect already put on the entity.
+
+**Rule — one hop:** From each `OcelFrame.object`, the builder walks **one level** of loaded relation fields only. It does **not** recurse into peers’ relations.
+
+**Rule — no manual peer frames:** Loaded peers do not require separate `OcelFrame` rows. The builder materializes them automatically.
+
+| Object | E2O qualifier |
+|--------|----------------|
+| `frame.object` (root) | `frame.qualifier` |
+| Each loaded peer from a relation field `field_name` | `{frame.qualifier}.{field_name}` |
+
+`AssociationMany` yields one E2O per peer id, same composite qualifier prefix.
+
+### O2O (object → object)
+
+**v1: not used.** `OcelObject.relationships` stays empty. Structural links are represented only through co-occurrence in E2O for the same event.
+
+### Object attributes
+
+| Source on domain entity | OCEL target |
+|-------------------------|-------------|
+| Loaded scalars on `frame.object` | `OcelObject.attributes` for the root |
+| Loaded lifecycle snapshot on root | root attributes (state string, v1) |
+| Loaded scalars on a one-hop peer | that peer’s `OcelObject.attributes` |
+
+Event attributes: ``OcelPlugin`` merges ``OcelFrame.attributes`` across frames; not from entity fields.
+
+### Example — “Doctor signed prescription”
+
+Aspect loads on the doctor entity before wrapping `OcelFrame`:
+
+- `patient` — loaded → **E2O** with qualifier `"Signed prescription.patient"`
+- `clinic` where the doctor works — **not loaded** → no E2O for clinic (clinic is context, not a participant in this action)
+
+```text
+OcelFrame(doctor, qualifier="Signed prescription")
+    │
+    ├─ E2O  doctor   qualifier "Signed prescription"
+    ├─ E2O  patient  qualifier "Signed prescription.patient"   (loaded FK, one hop)
+    └─ (clinic omitted — relation not loaded on doctor)
+```
+
+If the aspect **did** load `clinic` on the doctor, the builder would add  
+`E2O clinic` with `"Signed prescription.clinic"`. That is valid but may add noise in PM graphs; the aspect controls participation via **partial loading**.
+
+### E2O vs “everything in the database”
+
+| In DB | On framed entity at export | In OCEL v1 |
+|-------|----------------------------|------------|
+| Order → Customer FK | `customer` loaded | E2O + materialized `OcelObject` |
+| Order → Customer FK | `customer` not loaded | absent |
+| Scalar `customer_id` only | in `get_scalar_fields()` | object attribute on order, not E2O |
+
+Participation is **not** inferred from SQL or undeclared fields — only from what the aspect loaded on the entity inside `OcelFrame`.
+
+## OcelPlugin
+
+Register on ``ActionProductMachine(plugins=[OcelPlugin(store=resource)])``. The store must be opened by the owning action connection; the plugin only calls ``add_event``.
+
+```python
+from aoa.ocel import OCEL_FRAMES_KEY, OcelFrame, OcelPlugin
+
+@regular_aspect("Export")
+@result_instance(OCEL_FRAMES_KEY, OcelFrame, required=False)
+async def ocel_aspect(self, params, state, box, connections):
+    order = ...  # partial load: only relations that should participate
+    return {
+        OCEL_FRAMES_KEY: [
+            OcelFrame(
+                object=order,
+                qualifier="Created order with identifier",
+                attributes=[OcelAttribute(name="domain", value="shop")],
+            ),
+        ]
+    }
+```
+
+On each trace, ``OcelPlugin`` reads ``GlobalFinishEvent.all_aspect_states`` (and optional frames on ``result``), builds one ``OcelEvent``, and appends to the store. The plugin does not mutate pipeline state.
+

aoa_ocel-1.0.0/src/aoa/ocel/__init__.py

@@ -0,0 +1,39 @@
+# packages/aoa-ocel/src/aoa/ocel/__init__.py
+"""
+OCEL 2.0 export plugin for AOA — install with ``pip install aoa-ocel``.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+Aspects return ``list[OcelFrame]``; ``OcelPlugin`` builds ``OcelEvent`` on
+``GlobalFinishEvent``. Export policy (loaded FK → E2O, one hop, no O2O v1):
+``packages/aoa-ocel/src/aoa/ocel/README.md``.
+
+═══════════════════════════════════════════════════════════════════════════════
+ARCHITECTURE / DATA FLOW
+═══════════════════════════════════════════════════════════════════════════════
+
+::
+
+    aspect → list[OcelFrame] (partial entity controls loaded relations)
+              │
+              ▼
+    OcelPlugin → OcelEvent (E2O + OcelObject attributes) → OcelStoreResource
+"""
+
+from __future__ import annotations
+
+from aoa.ocel.contracts import OcelFrame
+from aoa.ocel.plugin import OCEL_FRAMES_KEY, OcelPlugin
+from aoa.ocel.resource import InMemoryOcelStoreResource, OcelStoreResource
+from aoa.ocel.type_id import make_oid
+
+__all__ = [
+    "OCEL_FRAMES_KEY",
+    "InMemoryOcelStoreResource",
+    "OcelFrame",
+    "OcelPlugin",
+    "OcelStoreResource",
+    "make_oid",
+]

aoa_ocel-1.0.0/src/aoa/ocel/contracts/__init__.py

@@ -0,0 +1,4 @@
+# packages/aoa-ocel/src/aoa/ocel/contracts/__init__.py
+from aoa.ocel.contracts.ocel_frame import OcelFrame
+
+__all__ = ["OcelFrame"]

aoa_ocel-1.0.0/src/aoa/ocel/contracts/ocel_frame.py

@@ -0,0 +1,79 @@
+# packages/aoa-ocel/src/aoa/ocel/contracts/ocel_frame.py
+"""
+OcelFrame[T] — explicit contract container for OCEL serialization.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+Aspects declare which domain object anchors an export row and the E2O role
+(``qualifier``) for the root. The future builder adds E2O for **loaded**
+one-hop relation peers on ``frame.object`` without separate frames.
+
+Full export rules (E2O-only v1, loaded FK, one hop, analytics trade-off):
+``packages/aoa-ocel/src/aoa/ocel/README.md`` — section **Export policy (v1)**.
+
+═══════════════════════════════════════════════════════════════════════════════
+ARCHITECTURE / DATA FLOW
+═══════════════════════════════════════════════════════════════════════════════
+
+::
+
+    aspect loads relations on entity → OcelFrame(object, qualifier, attributes?)
+              │
+              ▼
+    builder (PR-7): root E2O + one-hop loaded FK → E2O with "{qualifier}.{field}"
+              │
+              ▼
+    OcelEvent → OcelStoreResource
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TypeVar
+
+from aoa.action_machine.domain.entity import BaseEntity
+from aoa.ocel.dto.ocel_attribute import OcelAttribute
+from aoa.ocel.exceptions.ocel_contract_error import OcelContractError
+
+T = TypeVar("T", bound=BaseEntity)
+
+
+@dataclass(frozen=True)
+class OcelFrame[T: BaseEntity]:
+    """Explicit contract that an aspect returns for OCEL serialization.
+
+    Builder mapping (v1, see package README)::
+
+        OcelFrame
+        ├── object ──────────────────────► E2O (qualifier = frame.qualifier)
+        │   └── loaded FK peers (1 hop) ► E2O (qualifier = "{frame.qualifier}.{field}")
+        └── attributes ──────────────────► OcelPlugin merges → OcelEvent.attributes
+
+    Loaded-only rule: only ``get_foreign_keys(loaded_only=True)`` on ``object``;
+    undeclared DB relations and scalar ``*_id`` columns are not E2O.
+
+    AI-CORE-BEGIN
+    ROLE: Root participation row; builder derives secondary E2O from loaded one-hop relations on ``object``.
+    CONTRACT: ``object``, non-empty ``qualifier``, optional ``attributes``; multiple frames per trace allowed.
+    INVARIANTS: ``qualifier`` is non-empty; zero frames in finish snapshots → no OCEL write; v1 exports E2O only (no O2O); attribute merge is ``OcelPlugin`` policy on ``GlobalFinishEvent.all_aspect_states``.
+    AI-CORE-END
+
+    Example — one frame; patient loaded, clinic not loaded::
+
+        OcelFrame(
+            object=doctor,  # patient relation loaded; clinic relation not loaded
+            qualifier="Signed prescription",
+            attributes=[OcelAttribute(name="channel", value="electronic")],
+        )
+        # builder E2O: doctor ("Signed prescription"), patient ("Signed prescription.patient")
+    """
+
+    object: T
+    qualifier: str
+    attributes: list[OcelAttribute] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.qualifier.strip():
+            raise OcelContractError("OcelFrame.qualifier must be non-empty")

aoa_ocel-1.0.0/src/aoa/ocel/dto/__init__.py

@@ -0,0 +1,14 @@
+# packages/aoa-ocel/src/aoa/ocel/dto/__init__.py
+from aoa.ocel.dto.ocel_attribute import OcelAttribute
+from aoa.ocel.dto.ocel_event import OcelEvent
+from aoa.ocel.dto.ocel_object import OcelObject
+from aoa.ocel.dto.ocel_object_ref import OcelObjectRef
+from aoa.ocel.dto.ocel_object_relationship import OcelObjectRelationship
+
+__all__ = [
+    "OcelAttribute",
+    "OcelEvent",
+    "OcelObject",
+    "OcelObjectRef",
+    "OcelObjectRelationship",
+]

aoa_ocel-1.0.0/src/aoa/ocel/dto/ocel_attribute.py

@@ -0,0 +1,13 @@
+# packages/aoa-ocel/src/aoa/ocel/dto/ocel_attribute.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class OcelAttribute:
+    """Named attribute of an event or object (no ``time`` field = static)."""
+
+    name: str
+    value: Any

aoa_ocel-1.0.0/src/aoa/ocel/dto/ocel_event.py

@@ -0,0 +1,58 @@
+# packages/aoa-ocel/src/aoa/ocel/dto/ocel_event.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from aoa.ocel.dto.ocel_attribute import OcelAttribute
+from aoa.ocel.dto.ocel_object import OcelObject
+from aoa.ocel.dto.ocel_object_ref import OcelObjectRef
+
+
+@dataclass(slots=True)
+class OcelEvent:
+    """Composite event record passed to ``OcelStoreResource.add_event()``.
+
+    DTO graph (maps to OCEL 2.0 ``events[]`` + embedded ``objects[]`` facts)::
+
+        OcelEvent
+        ├── id: str
+        ├── type: str                          → eventTypes[].name
+        ├── time: datetime                     → events[].time (UTC)
+        │
+        ├── attributes: list[OcelAttribute]
+        │       OcelAttribute
+        │       ├── name: str
+        │       └── value: Any                 → static; no ``time`` field
+        │
+        ├── relationships: list[OcelObjectRef]   → E2O (event → object)
+        │       OcelObjectRef
+        │       ├── object_id: str             → target ``OcelObject.id``
+        │       └── qualifier: str
+        │
+        └── objects: list[OcelObject]          → objects[] section
+                OcelObject
+                ├── id: str
+                ├── type: str                  → objectTypes[].name
+                │
+                └── attributes: list[OcelAttribute]
+                        └── static object attrs (scalars / lifecycle snapshot)
+
+    v1 builder policy (E2O only): ``relationships`` are built from ``OcelFrame`` rows
+    plus one-hop **loaded** relation peers on each ``frame.object``; composite
+    peer qualifier ``{frame.qualifier}.{field_name}``. No O2O export; see
+    ``packages/aoa-ocel/src/aoa/ocel/README.md`` — **Export policy (v1)**.
+
+    AI-CORE-BEGIN
+    ROLE: Single composite payload for one ``OcelStoreResource.add_event()`` call.
+    CONTRACT: ``relationships`` are E2O rows; ``objects`` materialize root and one-hop loaded peers.
+    INVARIANTS: ``time`` is UTC-aware before persist; attribute values are JSON-serializable primitives (plugin builds DTOs).
+    AI-CORE-END
+    """
+
+    id: str
+    type: str
+    time: datetime
+    attributes: list[OcelAttribute] = field(default_factory=list)
+    relationships: list[OcelObjectRef] = field(default_factory=list)
+    objects: list[OcelObject] = field(default_factory=list)

aoa_ocel-1.0.0/src/aoa/ocel/dto/ocel_object.py

@@ -0,0 +1,17 @@
+# packages/aoa-ocel/src/aoa/ocel/dto/ocel_object.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from aoa.ocel.dto.ocel_attribute import OcelAttribute
+from aoa.ocel.dto.ocel_object_relationship import OcelObjectRelationship
+
+
+@dataclass(slots=True)
+class OcelObject:
+    """Full object entry for materializing the objects section."""
+
+    id: str
+    type: str
+    attributes: list[OcelAttribute] = field(default_factory=list)
+    relationships: list[OcelObjectRelationship] = field(default_factory=list)

aoa_ocel-1.0.0/src/aoa/ocel/dto/ocel_object_ref.py

@@ -0,0 +1,12 @@
+# packages/aoa-ocel/src/aoa/ocel/dto/ocel_object_ref.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class OcelObjectRef:
+    """Event-to-object reference (events[].relationships entry)."""
+
+    object_id: str
+    qualifier: str

aoa_ocel-1.0.0/src/aoa/ocel/dto/ocel_object_relationship.py

@@ -0,0 +1,12 @@
+# packages/aoa-ocel/src/aoa/ocel/dto/ocel_object_relationship.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class OcelObjectRelationship:
+    """Object-to-object relationship derived from a relation container field."""
+
+    object_id: str
+    qualifier: str

aoa_ocel-1.0.0/src/aoa/ocel/exceptions/__init__.py

@@ -0,0 +1,12 @@
+# packages/aoa-ocel/src/aoa/ocel/exceptions/__init__.py
+from aoa.ocel.exceptions.ocel_contract_error import OcelContractError
+from aoa.ocel.exceptions.ocel_error import OcelError
+from aoa.ocel.exceptions.ocel_resource_access_prohibited_error import (
+    OcelResourceAccessProhibitedError,
+)
+
+__all__ = [
+    "OcelContractError",
+    "OcelError",
+    "OcelResourceAccessProhibitedError",
+]

aoa_ocel-1.0.0/src/aoa/ocel/exceptions/ocel_contract_error.py

@@ -0,0 +1,11 @@
+# packages/aoa-ocel/src/aoa/ocel/exceptions/ocel_contract_error.py
+"""OcelContractError — data/invariant contract violation."""
+
+from aoa.ocel.exceptions.ocel_error import OcelError
+
+
+class OcelContractError(OcelError):
+    """Raised when OCEL data or invariant contract is violated.
+
+    Catch with: ``except OcelContractError``.
+    """

aoa_ocel-1.0.0/src/aoa/ocel/exceptions/ocel_error.py

@@ -0,0 +1,6 @@
+# packages/aoa-ocel/src/aoa/ocel/exceptions/ocel_error.py
+"""OcelError — base exception for the OCEL package."""
+
+
+class OcelError(Exception):
+    """Base for all OCEL exceptions (lifecycle access and data contract)."""

aoa_ocel-1.0.0/src/aoa/ocel/exceptions/ocel_resource_access_prohibited_error.py

@@ -0,0 +1,11 @@
+# packages/aoa-ocel/src/aoa/ocel/exceptions/ocel_resource_access_prohibited_error.py
+"""OcelResourceAccessProhibitedError — lifecycle call from proxy connection."""
+
+from aoa.ocel.exceptions.ocel_error import OcelError
+
+
+class OcelResourceAccessProhibitedError(OcelError):
+    """Raised when action code calls ``open()`` or ``close()`` on a proxy connection.
+
+    Not a subclass of ``OcelContractError`` — lifecycle access violation, not data contract.
+    """

aoa_ocel-1.0.0/src/aoa/ocel/plugin/__init__.py

@@ -0,0 +1,10 @@
+# packages/aoa-ocel/src/aoa/ocel/plugin/__init__.py
+"""
+OcelPlugin — builds ``OcelEvent`` from ``OcelFrame`` rows on ``GlobalFinishEvent``.
+
+See ``packages/aoa-ocel/src/aoa/ocel/README.md`` — **Export policy (v1)**.
+"""
+
+from aoa.ocel.plugin.ocel_plugin import OCEL_FRAMES_KEY, OcelPlugin
+
+__all__ = ["OCEL_FRAMES_KEY", "OcelPlugin"]

aoa_ocel-1.0.0/src/aoa/ocel/plugin/ocel_plugin.py

@@ -0,0 +1,333 @@
+# packages/aoa-ocel/src/aoa/ocel/plugin/ocel_plugin.py
+"""
+OcelPlugin — OCEL 2.0 export on ``GlobalFinishEvent``.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+Read ``OcelFrame`` rows from ``GlobalFinishEvent.all_aspect_states`` (and
+optional frames on ``result``), build one ``OcelEvent`` (E2O-only v1), append via
+``OcelStoreProtocol.add_event``. Does not mutate pipeline state or the event.
+
+Export policy: ``packages/aoa-ocel/src/aoa/ocel/README.md`` — **Export policy (v1)**.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterable, Mapping
+from datetime import UTC, datetime
+from typing import Annotated, Any, Union, get_args, get_origin
+
+from aoa.action_machine.domain.entity import BaseEntity
+from aoa.action_machine.domain.relation_containers import BaseRelationMany, BaseRelationOne
+from aoa.action_machine.intents.on import GlobalFinishEvent, on
+from aoa.action_machine.plugin.core import Plugin
+from aoa.ocel.contracts.ocel_frame import OcelFrame
+from aoa.ocel.dto.ocel_attribute import OcelAttribute
+from aoa.ocel.dto.ocel_event import OcelEvent
+from aoa.ocel.dto.ocel_object import OcelObject
+from aoa.ocel.dto.ocel_object_ref import OcelObjectRef
+from aoa.ocel.exceptions.ocel_contract_error import OcelContractError
+from aoa.ocel.resource.ocel_store_protocol import OcelStoreProtocol
+from aoa.ocel.type_id import make_oid
+
+OCEL_FRAMES_KEY = "ocel_frames"
+_OCEL_TYPE_SUFFIXES = ("Action", "Entity", "Lifecycle")
+
+
+class OcelPlugin(Plugin):
+    """
+    AI-CORE-BEGIN
+    ROLE: On ``GlobalFinishEvent``, scan ``all_aspect_states`` for ``OcelFrame`` rows and write one ``OcelEvent``.
+    CONTRACT: Requires injected ``OcelStoreProtocol``; optional ``short_names`` strips ``Action``/``Entity``/``Lifecycle`` suffixes from event and object type labels; read-only on event and pipeline state; E2O-only v1 (loaded one-hop FK, composite peer qualifiers).
+    INVARIANTS: Zero frames → no ``add_event``; event attribute name conflicts → ``OcelContractError``; store must already be open in the owning action.
+    AI-CORE-END
+    """
+
+    def __init__(
+        self,
+        store: OcelStoreProtocol,
+        *,
+        short_names: bool = False,
+    ) -> None:
+        super().__init__()
+        self._store = store
+        self._short_names = short_names
+
+    async def get_initial_state(self) -> dict[str, Any]:
+        return {}
+
+    @on(GlobalFinishEvent, ignore_exceptions=False)
+    async def on_export_ocel(
+        self,
+        state: dict[str, Any],
+        event: GlobalFinishEvent,
+        log: Any,
+    ) -> dict[str, Any]:
+        """Build ``OcelEvent`` from finish snapshots and append to the store."""
+        frames = collect_ocel_frames(event)
+        if not frames:
+            return state
+        ocel_event = self.build_ocel_event(frames, event)
+        await self._store.add_event(ocel_event)
+        return state
+
+    def build_ocel_event(
+        self,
+        frames: Iterable[OcelFrame[BaseEntity]],
+        event: GlobalFinishEvent,
+    ) -> OcelEvent:
+        """Assemble one composite ``OcelEvent`` from collected frames."""
+        frame_list = list(frames)
+        if not frame_list:
+            raise OcelContractError("build_ocel_event requires at least one OcelFrame")
+
+        relationships: list[OcelObjectRef] = []
+        objects_by_id: dict[str, OcelObject] = {}
+        for frame in frame_list:
+            refs, objects = self._materialize_frame(frame)
+            relationships.extend(refs)
+            for obj in objects:
+                objects_by_id[obj.id] = obj
+
+        return OcelEvent(
+            id=self._event_id(event),
+            type=self._ocel_type_name(event.action_class),
+            time=self._event_time(event),
+            attributes=self._merge_event_attributes(frame_list),
+            relationships=relationships,
+            objects=list(objects_by_id.values()),
+        )
+
+    @staticmethod
+    def ensure_utc(dt: datetime) -> datetime:
+        """Normalize datetime to UTC for OCEL 2.0 JSON (naive → UTC)."""
+        if dt.tzinfo is None:
+            return dt.replace(tzinfo=UTC)
+        return dt.astimezone(UTC)
+
+    def _merge_event_attributes(
+        self,
+        frames: Iterable[OcelFrame[BaseEntity]],
+    ) -> list[OcelAttribute]:
+        merged: dict[str, OcelAttribute] = {}
+        for frame in frames:
+            for attr in frame.attributes:
+                existing = merged.get(attr.name)
+                if existing is not None and existing.value != attr.value:
+                    raise OcelContractError(
+                        f"Conflicting OcelEvent attribute {attr.name!r}: " f"{existing.value!r} vs {attr.value!r}"
+                    )
+                merged[attr.name] = attr
+        return list(merged.values())
+
+    def _materialize_frame(
+        self,
+        frame: OcelFrame[BaseEntity],
+    ) -> tuple[list[OcelObjectRef], list[OcelObject]]:
+        root = frame.object
+        root_id = self._entity_object_id(root)
+        objects = [self._build_ocel_object(root)]
+        refs = [OcelObjectRef(object_id=root_id, qualifier=frame.qualifier)]
+
+        for field_name, relation in root.get_foreign_keys().items():
+            peer_qualifier = f"{frame.qualifier}.{field_name}"
+            if isinstance(relation, BaseRelationOne):
+                refs.extend(
+                    self._materialize_relation_one(
+                        root,
+                        field_name,
+                        relation,
+                        peer_qualifier,
+                        objects,
+                    )
+                )
+            elif isinstance(relation, BaseRelationMany):
+                refs.extend(
+                    self._materialize_relation_many(
+                        root,
+                        field_name,
+                        relation,
+                        peer_qualifier,
+                        objects,
+                    )
+                )
+        return refs, objects
+
+    def _materialize_relation_one(
+        self,
+        owner: BaseEntity,
+        field_name: str,
+        relation: BaseRelationOne[Any],
+        peer_qualifier: str,
+        objects: list[OcelObject],
+    ) -> list[OcelObjectRef]:
+        if relation.entity is not None:
+            peer = relation.entity
+            peer_id = self._entity_object_id(peer)
+            if peer_id not in {obj.id for obj in objects}:
+                objects.append(self._build_ocel_object(peer))
+            return [OcelObjectRef(object_id=peer_id, qualifier=peer_qualifier)]
+
+        related_cls = _related_entity_class(type(owner), field_name)
+        if related_cls is None:
+            raise OcelContractError(
+                f"Cannot materialize id-only relation {field_name!r} on "
+                f"{type(owner).__name__}: related entity type is unknown"
+            )
+        peer_id = make_oid(related_cls, relation.id)
+        if peer_id not in {obj.id for obj in objects}:
+            objects.append(
+                OcelObject(
+                    id=peer_id,
+                    type=self._ocel_type_name(related_cls),
+                    attributes=[OcelAttribute(name="id", value=str(relation.id))],
+                )
+            )
+        return [OcelObjectRef(object_id=peer_id, qualifier=peer_qualifier)]
+
+    def _materialize_relation_many(
+        self,
+        owner: BaseEntity,
+        field_name: str,
+        relation: BaseRelationMany[Any],
+        peer_qualifier: str,
+        objects: list[OcelObject],
+    ) -> list[OcelObjectRef]:
+        _ = owner
+        _ = field_name
+        if not relation.is_loaded:
+            return []
+        refs: list[OcelObjectRef] = []
+        known_ids = {obj.id for obj in objects}
+        for peer in relation.entities:
+            peer_id = self._entity_object_id(peer)
+            if peer_id not in known_ids:
+                objects.append(self._build_ocel_object(peer))
+                known_ids.add(peer_id)
+            refs.append(OcelObjectRef(object_id=peer_id, qualifier=peer_qualifier))
+        return refs
+
+    def _build_ocel_object(self, entity: BaseEntity) -> OcelObject:
+        attributes: list[OcelAttribute] = []
+        for name, value in entity.get_scalar_fields().items():
+            attributes.append(OcelAttribute(name=name, value=value))
+        for name, lifecycle in entity.get_lifecycle_fields().items():
+            attributes.append(OcelAttribute(name=name, value=lifecycle.current_state))
+        return OcelObject(
+            id=self._entity_object_id(entity),
+            type=self._ocel_type_name(type(entity)),
+            attributes=attributes,
+        )
+
+    def _ocel_type_name(self, cls: type) -> str:
+        """Return OCEL event/object type label (FQN or short class name)."""
+        return _ocel_type_name(cls, short_names=self._short_names)
+
+    @staticmethod
+    def _entity_object_id(entity: BaseEntity) -> str:
+        pk = entity.get_primary_key()
+        entity_id = pk.get("id")
+        if entity_id is None:
+            raise OcelContractError(f"Entity {type(entity).__name__} has no loaded primary key 'id' for OCEL export")
+        return make_oid(entity, entity_id)
+
+    @staticmethod
+    def _event_id(event: GlobalFinishEvent) -> str:
+        trace_id = event.context.request.trace_id
+        if trace_id:
+            return trace_id
+        return str(uuid.uuid4())
+
+    def _event_time(self, event: GlobalFinishEvent) -> datetime:
+        ts = event.context.request.request_timestamp
+        if ts is not None:
+            return self.ensure_utc(ts)
+        return datetime.now(UTC)
+
+
+def collect_ocel_frames(
+    source: GlobalFinishEvent | Mapping[str, Any] | None,
+) -> list[OcelFrame[BaseEntity]]:
+    """Collect ``OcelFrame`` rows from a finish event or one state-like mapping."""
+    if source is None:
+        return []
+    if isinstance(source, GlobalFinishEvent):
+        frames: list[OcelFrame[BaseEntity]] = []
+        for snapshot in source.all_aspect_states:
+            frames.extend(collect_ocel_frames(snapshot))
+        frames.extend(collect_ocel_frames(_mapping_from_schema(source.result)))
+        return frames
+
+    payload = source
+    if not payload:
+        return []
+    mapping_frames: list[OcelFrame[BaseEntity]] = []
+    if OCEL_FRAMES_KEY in payload:
+        mapping_frames.extend(_normalize_frame_values(payload[OCEL_FRAMES_KEY]))
+    for value in payload.values():
+        if isinstance(value, OcelFrame):
+            mapping_frames.append(value)
+    return mapping_frames
+
+
+def _normalize_frame_values(value: Any) -> list[OcelFrame[BaseEntity]]:
+    if isinstance(value, OcelFrame):
+        return [value]
+    if isinstance(value, (list, tuple)):
+        return [item for item in value if isinstance(item, OcelFrame)]
+    return []
+
+
+def _mapping_from_schema(value: Any) -> dict[str, Any]:
+    if isinstance(value, Mapping):
+        return dict(value)
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        dumped = model_dump()
+        if isinstance(dumped, Mapping):
+            return dict(dumped)
+    return {}
+
+
+def _ocel_type_name(cls: type, *, short_names: bool) -> str:
+    if not short_names:
+        return f"{cls.__module__}.{cls.__qualname__}"
+    name = cls.__name__
+    for suffix in _OCEL_TYPE_SUFFIXES:
+        if name.endswith(suffix) and len(name) > len(suffix):
+            return name[: -len(suffix)]
+    return name
+
+
+def _unwrap_annotation(annotation: Any) -> Any:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        return get_args(annotation)[0]
+    if origin is Union:
+        non_none = [arg for arg in get_args(annotation) if arg is not type(None)]
+        if len(non_none) == 1:
+            return _unwrap_annotation(non_none[0])
+    return annotation
+
+
+def _related_entity_class(
+    owner: type[BaseEntity],
+    field_name: str,
+) -> type[BaseEntity] | None:
+    field = owner.model_fields.get(field_name)
+    if field is None:
+        return None
+    annotation = _unwrap_annotation(field.annotation)
+    origin = get_origin(annotation)
+    if origin is None:
+        return None
+    args = get_args(annotation)
+    if not args:
+        return None
+    related = _unwrap_annotation(args[0])
+    if isinstance(related, type) and issubclass(related, BaseEntity):
+        return related
+    return None

aoa_ocel-1.0.0/src/aoa/ocel/resource/__init__.py

@@ -0,0 +1,12 @@
+# packages/aoa-ocel/src/aoa/ocel/resource/__init__.py
+from aoa.ocel.resource.in_memory_ocel_store_resource import InMemoryOcelStoreResource
+from aoa.ocel.resource.ocel_store_protocol import OcelStoreProtocol
+from aoa.ocel.resource.ocel_store_resource import OcelStoreResource
+from aoa.ocel.resource.ocel_store_wrapper import OcelStoreWrapper
+
+__all__ = [
+    "InMemoryOcelStoreResource",
+    "OcelStoreProtocol",
+    "OcelStoreResource",
+    "OcelStoreWrapper",
+]

aoa_ocel-1.0.0/src/aoa/ocel/resource/in_memory_ocel_store_resource.py

@@ -0,0 +1,180 @@
+# packages/aoa-ocel/src/aoa/ocel/resource/in_memory_ocel_store_resource.py
+"""InMemoryOcelStoreResource — in-memory OCEL 2.0 backend."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from aoa.action_machine.exceptions.connection_already_open_error import ConnectionAlreadyOpenError
+from aoa.action_machine.graph.core.exclude_graph_model import exclude_graph_model
+from aoa.ocel.dto.ocel_event import OcelEvent
+from aoa.ocel.dto.ocel_object import OcelObject
+from aoa.ocel.exceptions.ocel_contract_error import OcelContractError
+from aoa.ocel.resource.ocel_store_resource import OcelStoreResource
+
+
+def _type_catalog(type_attrs: dict[str, dict[str, str]]) -> list[dict[str, Any]]:
+    """Build OCEL 2.0 eventTypes/objectTypes JSON from name → {attr: ocel_type}."""
+    return [
+        {
+            "name": type_name,
+            "attributes": [
+                {"name": attr_name, "type": attr_type} for attr_name, attr_type in sorted(type_attrs[type_name].items())
+            ],
+        }
+        for type_name in sorted(type_attrs)
+    ]
+
+
+def _infer_ocel_type(value: Any) -> str:
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int):
+        return "integer"
+    if isinstance(value, float):
+        return "float"
+    if isinstance(value, datetime):
+        return "date"
+    return "string"
+
+
+@exclude_graph_model
+class InMemoryOcelStoreResource(OcelStoreResource):
+    """In-memory backend that writes OCEL 2.0 JSON on ``close()``."""
+
+    def __init__(self, output_file: Path) -> None:
+        self._output_file = output_file
+        self._lock = asyncio.Lock()
+        self._open = False
+        self._events: list[OcelEvent] = []
+        self._objects: dict[str, OcelObject] = {}
+        self._event_ids: set[str] = set()
+
+    async def open(self) -> None:
+        async with self._lock:
+            if self._open:
+                raise ConnectionAlreadyOpenError("InMemoryOcelStoreResource is already open.")
+            self._open = True
+
+    async def close(self) -> None:
+        async with self._lock:
+            if not self._open:
+                return
+            await self._write_locked()
+            self._open = False
+
+    async def add_event(self, event: OcelEvent) -> None:
+        async with self._lock:
+            self._assert_open()
+            if event.id in self._event_ids:
+                raise OcelContractError(f"Duplicate OcelEvent.id: {event.id}")
+            self._event_ids.add(event.id)
+            self._events.append(event)
+            for obj_fact in event.objects:
+                self._merge_object_fact(obj_fact)
+
+    def _assert_open(self) -> None:
+        if not self._open:
+            raise OcelContractError("Resource is not open. Call await resource.open() first.")
+
+    def _merge_object_fact(self, incoming: OcelObject) -> None:
+        if incoming.id not in self._objects:
+            self._objects[incoming.id] = OcelObject(
+                id=incoming.id,
+                type=incoming.type,
+                attributes=list(incoming.attributes),
+                relationships=list(incoming.relationships),
+            )
+            return
+
+        existing = self._objects[incoming.id]
+        existing_attrs = {a.name: a for a in existing.attributes}
+        for attr in incoming.attributes:
+            existing_attrs[attr.name] = attr
+        existing.attributes = list(existing_attrs.values())
+
+        existing_rels = {(r.object_id, r.qualifier) for r in existing.relationships}
+        for rel in incoming.relationships:
+            key = (rel.object_id, rel.qualifier)
+            if key not in existing_rels:
+                existing.relationships.append(rel)
+                existing_rels.add(key)
+
+    async def _write_locked(self) -> None:
+        doc = self._materialize()
+        self._output_file.parent.mkdir(parents=True, exist_ok=True)
+        self._output_file.write_text(
+            json.dumps(doc, ensure_ascii=False, indent=2, default=self._json_default),
+            encoding="utf-8",
+        )
+
+    @staticmethod
+    def _json_default(obj: Any) -> Any:
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+    def _materialize(self) -> dict[str, Any]:
+        return {
+            "eventTypes": self._derive_event_types(),
+            "objectTypes": self._derive_object_types(),
+            "events": [self._serialize_event(ev) for ev in self._events],
+            "objects": [self._serialize_object(obj) for obj in sorted(self._objects.values(), key=lambda o: o.id)],
+        }
+
+    def _derive_event_types(self) -> list[dict[str, Any]]:
+        type_attrs: dict[str, dict[str, str]] = {}
+        for ev in self._events:
+            type_attrs.setdefault(ev.type, {})
+            for attr in ev.attributes:
+                if attr.name not in type_attrs[ev.type]:
+                    type_attrs[ev.type][attr.name] = _infer_ocel_type(attr.value)
+        return _type_catalog(type_attrs)
+
+    def _derive_object_types(self) -> list[dict[str, Any]]:
+        type_attrs: dict[str, dict[str, str]] = {}
+        for obj in self._objects.values():
+            type_attrs.setdefault(obj.type, {})
+            for attr in obj.attributes:
+                if attr.name not in type_attrs[obj.type]:
+                    type_attrs[obj.type][attr.name] = _infer_ocel_type(attr.value)
+        return _type_catalog(type_attrs)
+
+    def _serialize_event(self, ev: OcelEvent) -> dict[str, Any]:
+        return {
+            "id": ev.id,
+            "type": ev.type,
+            "time": ev.time.isoformat(),
+            "attributes": [{"name": a.name, "value": self._serialize_attr_value(a.value)} for a in ev.attributes],
+            "relationships": [{"objectId": r.object_id, "qualifier": r.qualifier} for r in ev.relationships],
+        }
+
+    def _serialize_object(self, obj: OcelObject) -> dict[str, Any]:
+        attrs_out: list[dict[str, Any]] = []
+        for attr in sorted(obj.attributes, key=lambda a: a.name):
+            attrs_out.append({"name": attr.name, "value": self._serialize_attr_value(attr.value)})
+        return {
+            "id": obj.id,
+            "type": obj.type,
+            "attributes": attrs_out,
+            "relationships": [
+                {"objectId": r.object_id, "qualifier": r.qualifier}
+                for r in sorted(obj.relationships, key=lambda r: (r.object_id, r.qualifier))
+            ],
+        }
+
+    @staticmethod
+    def _serialize_attr_value(value: Any) -> Any:
+        if isinstance(value, datetime):
+            return value.isoformat()
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, (int, float)):
+            return value
+        if value is None:
+            return None
+        return str(value)

aoa_ocel-1.0.0/src/aoa/ocel/resource/ocel_store_protocol.py

@@ -0,0 +1,24 @@
+# packages/aoa-ocel/src/aoa/ocel/resource/ocel_store_protocol.py
+# pylint: disable=unnecessary-ellipsis  # Protocol member bodies use ellipsis per PEP 544 stubs.
+"""OcelStoreProtocol — full public OCEL store interface."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from aoa.ocel.dto.ocel_event import OcelEvent
+
+
+class OcelStoreProtocol(Protocol):
+    """Full public protocol for OCEL store (§5.27)."""
+
+    async def check_rollup_support(self) -> bool:
+        """Same contract as ``BaseResource.check_rollup_support``."""
+        ...
+
+    async def open(self) -> None: ...
+
+    async def add_event(self, event: OcelEvent) -> None: ...
+
+    async def close(self) -> None: ...

aoa_ocel-1.0.0/src/aoa/ocel/resource/ocel_store_resource.py

@@ -0,0 +1,45 @@
+# packages/aoa-ocel/src/aoa/ocel/resource/ocel_store_resource.py
+"""OcelStoreResource — abstract base for OCEL persistence backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from aoa.action_machine.graph.core.exclude_graph_model import exclude_graph_model
+from aoa.action_machine.resources.base_resource import BaseResource
+from aoa.ocel.dto.ocel_event import OcelEvent
+from aoa.ocel.resource.ocel_store_protocol import OcelStoreProtocol
+from aoa.ocel.resource.ocel_store_wrapper import OcelStoreWrapper
+
+
+@exclude_graph_model
+class OcelStoreResource(BaseResource, OcelStoreProtocol, ABC):
+    """
+    AI-CORE-BEGIN
+    ROLE: Abstract persistent resource for OCEL 2.0 accumulation and persist on close.
+    CONTRACT: Public API is ``open``, ``add_event``, ``close``; nested actions get ``OcelStoreWrapper``.
+    INVARIANTS: ``add_event`` accepts only ``OcelEvent`` DTO; persistence runs in ``close()``.
+    AI-CORE-END
+    """
+
+    async def check_rollup_support(self) -> bool:
+        return False
+
+    def get_wrapper_class(self) -> type[BaseResource] | None:
+        return OcelStoreWrapper
+
+    @abstractmethod
+    async def open(self) -> None:
+        """Initialize the resource."""
+
+    @abstractmethod
+    async def add_event(self, event: OcelEvent) -> None:
+        """Accumulate one composite OCEL event record.
+
+        Raises:
+            OcelContractError: duplicate ``event.id`` or resource not open.
+        """
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Persist accumulated data and release resources."""

aoa_ocel-1.0.0/src/aoa/ocel/resource/ocel_store_wrapper.py

@@ -0,0 +1,45 @@
+# packages/aoa-ocel/src/aoa/ocel/resource/ocel_store_wrapper.py
+"""OcelStoreWrapper — proxy for nested actions (mirrors WrapperSqlResource)."""
+
+from __future__ import annotations
+
+from aoa.action_machine.graph.core.exclude_graph_model import exclude_graph_model
+from aoa.action_machine.resources.base_resource import BaseResource
+from aoa.ocel.dto.ocel_event import OcelEvent
+from aoa.ocel.exceptions.ocel_resource_access_prohibited_error import (
+    OcelResourceAccessProhibitedError,
+)
+from aoa.ocel.resource.ocel_store_protocol import OcelStoreProtocol
+
+
+@exclude_graph_model
+class OcelStoreWrapper(BaseResource, OcelStoreProtocol):
+    """Proxy wrapper for OCEL store passed into nested actions via ``ToolsBox.run``.
+
+    Delegates ``add_event``; ``open`` and ``close`` raise
+    ``OcelResourceAccessProhibitedError`` (§5.27.2).
+    """
+
+    def __init__(self, resource: OcelStoreProtocol) -> None:
+        self._resource = resource
+
+    async def check_rollup_support(self) -> bool:
+        return await self._resource.check_rollup_support()
+
+    def get_wrapper_class(self) -> type[BaseResource] | None:
+        return OcelStoreWrapper
+
+    async def open(self) -> None:
+        raise OcelResourceAccessProhibitedError(
+            "Opening OCEL store is allowed only in the action that created the resource. "
+            "Current action received a proxy connection, so open is unavailable."
+        )
+
+    async def add_event(self, event: OcelEvent) -> None:
+        await self._resource.add_event(event)
+
+    async def close(self) -> None:
+        raise OcelResourceAccessProhibitedError(
+            "Closing OCEL store is allowed only in the action that created the resource. "
+            "Current action received a proxy connection, so close is unavailable."
+        )

aoa_ocel-1.0.0/src/aoa/ocel/type_id.py

@@ -0,0 +1,31 @@
+# packages/aoa-ocel/src/aoa/ocel/type_id.py
+"""Short OCEL type prefixes and object IDs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import xxhash
+
+_prefix_cache: dict[str, str] = {}
+
+
+def make_oid(obj: Any, original_id: str | int | None = None) -> str:
+    """Short OCEL type id, or object id when ``original_id`` is set.
+
+    Without ``original_id``: ``orde_a1b`` (type prefix for ``event.type`` / ``object.type``).
+    With ``original_id``: ``orde_a1b_123`` (full ``object.id``).
+    """
+    cls = obj if isinstance(obj, type) else type(obj)
+    full_name = f"{cls.__module__}.{cls.__qualname__}"
+
+    prefix = _prefix_cache.get(full_name)
+    if prefix is None:
+        base = cls.__name__[:4].lower()
+        suffix = xxhash.xxh32(full_name.encode()).hexdigest()[:3]
+        prefix = f"{base}_{suffix}"
+        _prefix_cache[full_name] = prefix
+
+    if original_id is None:
+        return prefix
+    return f"{prefix}_{original_id}"