activegraph 1.0.5.post2__tar.gz → 1.2.0__tar.gz

{activegraph-1.0.5.post2/activegraph.egg-info → activegraph-1.2.0}/PKG-INFO

@@ -1,10 +1,14 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.0.5.post2
+Version: 1.2.0
 Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
 Author: Active Graph contributors
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/yoheinakajima/activegraph
+Project-URL: Documentation, https://docs.activegraph.ai/
+Project-URL: Repository, https://github.com/yoheinakajima/activegraph
+Project-URL: Changelog, https://docs.activegraph.ai/about/changelog/
+Project-URL: Issues, https://github.com/yoheinakajima/activegraph/issues
 Keywords: graph,agents,event-sourcing,runtime
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -32,8 +36,15 @@ Requires-Dist: pydantic>=2; extra == "openai"
 Provides-Extra: sqlite
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == "postgres"
+Provides-Extra: falkordb
+Requires-Dist: falkordb>=1.0; extra == "falkordb"
+Provides-Extra: falkordb-embedded
+Requires-Dist: falkordblite>=0.10; extra == "falkordb-embedded"
 Provides-Extra: prometheus
 Requires-Dist: prometheus_client>=0.20; extra == "prometheus"
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-api>=1.25; extra == "opentelemetry"
+Requires-Dist: opentelemetry-sdk>=1.25; extra == "opentelemetry"
 Provides-Extra: all
 Requires-Dist: anthropic>=0.40; extra == "all"
 Requires-Dist: openai>=1.0; extra == "all"
@@ -41,11 +52,16 @@ Requires-Dist: tiktoken>=0.7; extra == "all"
 Requires-Dist: pydantic>=2; extra == "all"
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == "all"
 Requires-Dist: prometheus_client>=0.20; extra == "all"
+Requires-Dist: opentelemetry-api>=1.25; extra == "all"
+Requires-Dist: opentelemetry-sdk>=1.25; extra == "all"
 Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pydantic>=2; extra == "dev"
 Requires-Dist: prometheus_client>=0.20; extra == "dev"
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == "dev"
+Requires-Dist: opentelemetry-api>=1.25; extra == "dev"
+Requires-Dist: opentelemetry-sdk>=1.25; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.6; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
@@ -96,14 +112,15 @@ pip install "activegraph[anthropic]"       # Anthropic provider only
 pip install "activegraph[openai]"          # OpenAI provider only (+ tiktoken)
 pip install "activegraph[postgres]"        # Postgres-backed event store
 pip install "activegraph[prometheus]"      # Prometheus metrics
+pip install "activegraph[opentelemetry]"   # OpenTelemetry metrics
 pip install "activegraph[all]"             # everything
 ```
 
 Both LLM providers expose the same `LLMProvider` Protocol surface;
 swap one for the other without touching `@llm_behavior` definitions.
 The [LLM providers reference](https://docs.activegraph.ai/reference/llm-providers/)
-covers the side-by-side surface and the v1.0.1 limitations
-(OpenAI tool use is a v1.1 candidate).
+covers the side-by-side surface, including tool use and provider-specific
+token counting.
 
 Python 3.11+. Two hard dependencies (`click` for the CLI, `pydantic`
 for the pack format); persistence backends and provider integrations
@@ -294,23 +311,34 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.ai/concepts/relations
 - Not a rules engine, exactly. Rules engines forward-chain over
   facts. This event-sources over a graph and supports LLM behaviors
   as first-class.
-- Not a production graph database. The default store is SQLite,
-  optionally Postgres. For a high-throughput graph backend, plug one
-  in behind the `EventStore` protocol.
+- Not a production graph database. The event log lives in SQLite
+  (default) or Postgres behind the `EventStore` protocol; the
+  materialized graph lives behind the `GraphStore` protocol —
+  in-memory by default, or [FalkorDB](https://docs.activegraph.ai/guides/using-falkordb/)
+  for a real, traversable graph backend. For a different
+  high-throughput store, plug one in behind either protocol.
 - Not magic. Bad behaviors produce bad graphs. The runtime makes the
   badness inspectable, not absent.
 
 ## Status
 
-**v1.0 (stable)** (2026-05). The first-time-user gate per
-[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally)
-ran through three rcs; v1.0 final ships rc3 plus a tutorial-step-7
-output fix and a README "Concepts at a glance" index. See
-[CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
-per-version migration notes.
+**v1.2.0 (stable)** (2026-07). v1.0 shipped in May 2026 after a
+three-rc external user-test gate per
+[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally);
+v1.1.0 and v1.2.0 followed. See [CHANGELOG.md](CHANGELOG.md) for the
+full v0 → v1.2 history and per-version migration notes.
 
 Major shipped milestones:
 
+- **v1.2** — the `GraphStore` seam: the materialized projection
+  becomes pluggable, with `FalkorDBGraphStore` (native edges, Cypher
+  query push-down) as the first external backend, contributed by
+  [@dudizimber](https://github.com/dudizimber); the test suite
+  becomes a CI gate.
+- **v1.1** — bounded LLM retries for transient provider failures,
+  `inspect --memo` / `inspect --search`, `fork --set`, OpenAI
+  tool-shape parity, `OpenTelemetryMetrics`, and the
+  spec-vs-impl drift gates.
 - **v1.0** — error hierarchy rewrite with per-error reference
   pages, doc site at [docs.activegraph.ai](https://docs.activegraph.ai/),
   `activegraph quickstart` command, mypy `--strict` and docstring
@@ -331,8 +359,9 @@ Major shipped milestones:
   patches with optimistic concurrency, views, frames, policies,
   budgets, the trace.
 
-Roadmap items planned for v1.1 are tracked in
-[CONTRACT.md § v1.1](CONTRACT.md).
+Roadmap items for the current cycle are tracked in
+[ROADMAP.md](ROADMAP.md); unscheduled candidates live in
+[FUTURE_IDEAS.md](FUTURE_IDEAS.md).
 
 ## License
 

{activegraph-1.0.5.post2 → activegraph-1.2.0}/README.md

@@ -41,14 +41,15 @@ pip install "activegraph[anthropic]"       # Anthropic provider only
 pip install "activegraph[openai]"          # OpenAI provider only (+ tiktoken)
 pip install "activegraph[postgres]"        # Postgres-backed event store
 pip install "activegraph[prometheus]"      # Prometheus metrics
+pip install "activegraph[opentelemetry]"   # OpenTelemetry metrics
 pip install "activegraph[all]"             # everything
 ```
 
 Both LLM providers expose the same `LLMProvider` Protocol surface;
 swap one for the other without touching `@llm_behavior` definitions.
 The [LLM providers reference](https://docs.activegraph.ai/reference/llm-providers/)
-covers the side-by-side surface and the v1.0.1 limitations
-(OpenAI tool use is a v1.1 candidate).
+covers the side-by-side surface, including tool use and provider-specific
+token counting.
 
 Python 3.11+. Two hard dependencies (`click` for the CLI, `pydantic`
 for the pack format); persistence backends and provider integrations
@@ -239,23 +240,34 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.ai/concepts/relations
 - Not a rules engine, exactly. Rules engines forward-chain over
   facts. This event-sources over a graph and supports LLM behaviors
   as first-class.
-- Not a production graph database. The default store is SQLite,
-  optionally Postgres. For a high-throughput graph backend, plug one
-  in behind the `EventStore` protocol.
+- Not a production graph database. The event log lives in SQLite
+  (default) or Postgres behind the `EventStore` protocol; the
+  materialized graph lives behind the `GraphStore` protocol —
+  in-memory by default, or [FalkorDB](https://docs.activegraph.ai/guides/using-falkordb/)
+  for a real, traversable graph backend. For a different
+  high-throughput store, plug one in behind either protocol.
 - Not magic. Bad behaviors produce bad graphs. The runtime makes the
   badness inspectable, not absent.
 
 ## Status
 
-**v1.0 (stable)** (2026-05). The first-time-user gate per
-[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally)
-ran through three rcs; v1.0 final ships rc3 plus a tutorial-step-7
-output fix and a README "Concepts at a glance" index. See
-[CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
-per-version migration notes.
+**v1.2.0 (stable)** (2026-07). v1.0 shipped in May 2026 after a
+three-rc external user-test gate per
+[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally);
+v1.1.0 and v1.2.0 followed. See [CHANGELOG.md](CHANGELOG.md) for the
+full v0 → v1.2 history and per-version migration notes.
 
 Major shipped milestones:
 
+- **v1.2** — the `GraphStore` seam: the materialized projection
+  becomes pluggable, with `FalkorDBGraphStore` (native edges, Cypher
+  query push-down) as the first external backend, contributed by
+  [@dudizimber](https://github.com/dudizimber); the test suite
+  becomes a CI gate.
+- **v1.1** — bounded LLM retries for transient provider failures,
+  `inspect --memo` / `inspect --search`, `fork --set`, OpenAI
+  tool-shape parity, `OpenTelemetryMetrics`, and the
+  spec-vs-impl drift gates.
 - **v1.0** — error hierarchy rewrite with per-error reference
   pages, doc site at [docs.activegraph.ai](https://docs.activegraph.ai/),
   `activegraph quickstart` command, mypy `--strict` and docstring
@@ -276,8 +288,9 @@ Major shipped milestones:
   patches with optimistic concurrency, views, frames, policies,
   budgets, the trace.
 
-Roadmap items planned for v1.1 are tracked in
-[CONTRACT.md § v1.1](CONTRACT.md).
+Roadmap items for the current cycle are tracked in
+[ROADMAP.md](ROADMAP.md); unscheduled candidates live in
+[FUTURE_IDEAS.md](FUTURE_IDEAS.md).
 
 ## License
 

{activegraph-1.0.5.post2 → activegraph-1.2.0}/activegraph/__init__.py

@@ -61,7 +61,10 @@ from activegraph.store import (
     DuplicateEventError,
     EventNotFoundError,
     EventStore,
+    FalkorDBGraphStore,
+    GraphStore,
     InMemoryEventStore,
+    InMemoryGraphStore,
     InvalidStoreURL,
     NonSerializableEventError,
     RunRecord,
@@ -87,6 +90,7 @@ from activegraph.observability import (
     MigrationReport,
     MigrationRunReport,
     NoOpMetrics,
+    OpenTelemetryMetrics,
     PrometheusMetrics,
     RuntimeStatus,
     configure_logging,
@@ -141,11 +145,14 @@ __all__ = [
     "EventNotFoundError",
     "EventStore",
     "ExecutionError",
+    "FalkorDBGraphStore",
     "Frame",
     "FrozenClock",
     "Graph",
+    "GraphStore",
     "IDGen",
     "InMemoryEventStore",
+    "InMemoryGraphStore",
     "IncompatibleRuntimeState",
     "InternalEvaluatorError",
     "InvalidActivateAfter",
@@ -165,6 +172,7 @@ __all__ = [
     "NoOpMetrics",
     "NonSerializableEventError",
     "Object",
+    "OpenTelemetryMetrics",
     "ObjectType",
     "Pack",
     "PackConflictError",
@@ -222,4 +230,4 @@ __all__ = [
     "tool",
 ]
 
-__version__ = "1.0.5.post2"
+__version__ = "1.2.0"

{activegraph-1.0.5.post2 → activegraph-1.2.0}/activegraph/cli/main.py

@@ -234,6 +234,17 @@ def cmd_pack_list() -> None:
         "the recorded run was using vs. what's installed today."
     ),
 )
+@click.option(
+    "--memo",
+    is_flag=True,
+    help="Render memo objects in the run using the quickstart/operator format.",
+)
+@click.option(
+    "--search",
+    "search_query",
+    default=None,
+    help="Search event ids, types, actors, and payload JSON for a substring.",
+)
 def cmd_inspect(
     url: str,
     run_id: Optional[str],
@@ -242,19 +253,21 @@ def cmd_inspect(
     event_id: Optional[str],
     behaviors: bool,
     pack_version: bool,
+    memo: bool,
+    search_query: Optional[str],
 ) -> None:
     """Print a status snapshot for a run.
 
-    With ``--event``, ``--behaviors``, or ``--pack-version``, prints only
-    that focused section instead of the full status. The three are
+    With selector flags, prints only that focused section instead of
+    the full status. Selectors are
     mutually exclusive — they're selectors, not filters.
     """
     from activegraph.observability.status import status_to_dict
     from activegraph.runtime.runtime import Runtime
 
-    if sum([bool(event_id), behaviors, pack_version]) > 1:
+    if sum([bool(event_id), behaviors, pack_version, memo, bool(search_query)]) > 1:
         click.echo(
-            "--event, --behaviors, and --pack-version are mutually exclusive.",
+            "--event, --behaviors, --pack-version, --memo, and --search are mutually exclusive.",
             err=True,
         )
         raise SystemExit(EXIT_USAGE_ERROR)
@@ -278,6 +291,12 @@ def cmd_inspect(
     if pack_version:
         _print_pack_versions(rt, as_json)
         return
+    if memo:
+        _print_memos(rt, as_json)
+        return
+    if search_query:
+        _print_search(rt, search_query, as_json)
+        return
 
     status = rt.status(recent=tail)
 
@@ -318,15 +337,7 @@ def _print_event(rt, event_id: str, as_json: bool) -> None:
         click.echo(f"event {event_id!r} not found in run {rt.run_id}", err=True)
         raise SystemExit(EXIT_NOT_FOUND)
     if as_json:
-        click.echo(_json.dumps({
-            "id": target.id,
-            "type": target.type,
-            "actor": target.actor,
-            "frame_id": target.frame_id,
-            "caused_by": target.caused_by,
-            "timestamp": target.timestamp,
-            "payload": target.payload,
-        }, default=str))
+        click.echo(_json.dumps(_event_to_dict(target), default=str))
         return
     click.echo(f"event:       {target.id}")
     click.echo(f"type:        {target.type}")
@@ -401,6 +412,95 @@ def _print_pack_versions(rt, as_json: bool) -> None:
                 click.echo(f"    prompt {prompt_name:24s} hash={short}")
 
 
+def _print_memos(rt, as_json: bool) -> None:
+    """v1.1 CLI follow-on: render memo objects from a run."""
+    from activegraph.cli.renderers import company_name_for_memo, print_memo_section
+
+    memos = [o for o in rt.graph.all_objects() if o.type == "memo"]
+    if as_json:
+        click.echo(_json.dumps([
+            {
+                "company": company_name_for_memo(rt, memo),
+                "object": memo.to_dict(),
+            }
+            for memo in memos
+        ], default=str))
+        return
+    if not memos:
+        click.echo("(no memo objects in this run)")
+        return
+    write = lambda s: click.echo(s)
+    for memo in memos:
+        print_memo_section(write, rt, memo)
+
+
+def _print_search(rt, query: str, as_json: bool) -> None:
+    """v1.1 CLI follow-on: substring search across run events."""
+    q = query.casefold()
+    matches = []
+    for e in rt.graph.events:
+        fields = {
+            "id": e.id,
+            "type": e.type,
+            "actor": e.actor or "",
+            "payload": _json.dumps(e.payload, sort_keys=True, default=str),
+        }
+        matched_fields = [name for name, value in fields.items() if q in value.casefold()]
+        if not matched_fields:
+            continue
+        payload_text = fields["payload"]
+        matches.append(
+            {
+                "id": e.id,
+                "type": e.type,
+                "actor": e.actor,
+                "timestamp": e.timestamp,
+                "matched_fields": matched_fields,
+                "snippet": _search_snippet(payload_text, query),
+            }
+        )
+    if as_json:
+        click.echo(_json.dumps(matches, default=str))
+        return
+    if not matches:
+        click.echo(f"(no matches for {query!r})")
+        return
+    click.echo(f"matches ({len(matches)}):")
+    for m in matches:
+        actor = m["actor"] or "(none)"
+        click.echo(
+            f"  {m['id']:18s} {m['type']:24s} actor={actor} fields={','.join(m['matched_fields'])}"
+        )
+        if m["snippet"]:
+            click.echo(f"    {m['snippet']}")
+
+
+def _event_to_dict(event) -> dict[str, Any]:
+    return {
+        "id": event.id,
+        "type": event.type,
+        "actor": event.actor,
+        "frame_id": event.frame_id,
+        "caused_by": event.caused_by,
+        "timestamp": event.timestamp,
+        "payload": event.payload,
+    }
+
+
+def _search_snippet(text: str, query: str, *, width: int = 120) -> str:
+    idx = text.casefold().find(query.casefold())
+    if idx == -1:
+        return text[:width]
+    start = max(0, idx - width // 3)
+    end = min(len(text), start + width)
+    snippet = text[start:end]
+    if start > 0:
+        snippet = "..." + snippet
+    if end < len(text):
+        snippet += "..."
+    return snippet
+
+
 # ---- replay -------------------------------------------------------------
 
 
@@ -462,6 +562,15 @@ def cmd_replay(url: str, run_id: str, as_json: bool) -> None:
         "so the LLM cache and tool cache write-through new entries."
     ),
 )
+@click.option(
+    "--set",
+    "settings_overrides",
+    multiple=True,
+    help=(
+        "Override a pack setting in the fork. Shape: "
+        "<pack>.<setting>=<value>. Repeat to compose overrides."
+    ),
+)
 @click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
 def cmd_fork(
     url: str,
@@ -470,6 +579,7 @@ def cmd_fork(
     label: Optional[str],
     to_url: Optional[str],
     record: bool,
+    settings_overrides: tuple[str, ...],
     as_json: bool,
 ) -> None:
     """Create a new run by copying events up to and including --at-event."""
@@ -479,6 +589,7 @@ def cmd_fork(
 
     if to_url is None:
         to_url = url
+    parsed_overrides = _parse_fork_settings_overrides(settings_overrides)
     if record:
         # Label suffix is informational; the actual "recording" semantics
         # emerge when the new run is later loaded with replay_strict=False
@@ -499,6 +610,18 @@ def cmd_fork(
         click.echo(str(e), err=True)
         raise SystemExit(EXIT_USAGE_ERROR)
 
+    if parsed_overrides:
+        loaded_packs = _pack_names_loaded_through_event(url, run_id, at_event)
+        missing = sorted(set(parsed_overrides) - loaded_packs)
+        if missing:
+            click.echo(
+                "cannot apply --set override: no pack.loaded event for "
+                + ", ".join(repr(p) for p in missing)
+                + f" exists at or before {at_event!r} in run {run_id!r}",
+                err=True,
+            )
+            raise SystemExit(EXIT_USAGE_ERROR)
+
     new_run_id = IDGen().run()
     try:
         if parsed.scheme == "sqlite":
@@ -527,6 +650,15 @@ def cmd_fork(
         click.echo(str(e), err=True)
         raise SystemExit(EXIT_NOT_FOUND)
 
+    override_event_ids: list[str] = []
+    if parsed_overrides:
+        override_event_ids = _record_fork_settings_overrides(
+            to_url,
+            run_id=new_run_id,
+            caused_by=at_event,
+            overrides=parsed_overrides,
+        )
+
     out = {
         "parent_run_id": run_id,
         "new_run_id": new_run_id,
@@ -534,12 +666,19 @@ def cmd_fork(
         "label": label,
         "events_copied": n,
     }
+    if parsed_overrides:
+        out["settings_overrides"] = {
+            pack: data["overrides"] for pack, data in parsed_overrides.items()
+        }
+        out["settings_override_events"] = override_event_ids
     if as_json:
         if record:
             out["recording"] = True
         click.echo(_json.dumps(out))
         return
     click.echo(f"forked {run_id} at {at_event} -> {new_run_id} ({n} events)")
+    for event_id in override_event_ids:
+        click.echo(f"  settings override recorded: {event_id}")
     if record:
         click.echo(
             "  recording fork: load this run without replay_strict=True to "
@@ -547,6 +686,135 @@ def cmd_fork(
         )
 
 
+def _parse_fork_settings_overrides(
+    raw_values: tuple[str, ...],
+) -> dict[str, dict[str, Any]]:
+    """Parse repeated --set flags into pack-grouped override payloads."""
+    parsed: dict[str, dict[str, Any]] = {}
+    for raw in raw_values:
+        if "=" not in raw:
+            click.echo(
+                f"--set value {raw!r} must have shape <pack>.<setting>=<value>",
+                err=True,
+            )
+            raise SystemExit(EXIT_USAGE_ERROR)
+        key, raw_value = raw.split("=", 1)
+        parts = key.split(".")
+        if len(parts) < 2 or any(not p for p in parts):
+            click.echo(
+                f"--set key {key!r} must have shape <pack>.<setting>",
+                err=True,
+            )
+            raise SystemExit(EXIT_USAGE_ERROR)
+        pack = parts[0]
+        value = _coerce_cli_value(raw_value)
+        entry = parsed.setdefault(pack, {"overrides": {}, "assignments": []})
+        _set_nested_override(entry["overrides"], parts[1:], value, raw)
+        entry["assignments"].append(raw)
+    return parsed
+
+
+def _coerce_cli_value(raw: str) -> Any:
+    """Best-effort string-to-JSON coercion for --set values.
+
+    Pydantic performs final validation when the pack is loaded. This
+    parser only turns obvious JSON scalars/lists/maps into Python values.
+    """
+    lowered = raw.strip().lower()
+    if lowered == "none":
+        return None
+    try:
+        return _json.loads(raw)
+    except ValueError:
+        return raw
+
+
+def _set_nested_override(
+    root: dict[str, Any],
+    path: list[str],
+    value: Any,
+    raw: str,
+) -> None:
+    cursor = root
+    for segment in path[:-1]:
+        existing = cursor.get(segment)
+        if existing is None:
+            nested: dict[str, Any] = {}
+            cursor[segment] = nested
+            cursor = nested
+            continue
+        if not isinstance(existing, dict):
+            click.echo(
+                f"--set value {raw!r} conflicts with an earlier override for "
+                f"{segment!r}",
+                err=True,
+            )
+            raise SystemExit(EXIT_USAGE_ERROR)
+        cursor = existing
+    leaf = path[-1]
+    if isinstance(cursor.get(leaf), dict):
+        click.echo(
+            f"--set value {raw!r} conflicts with an earlier nested override",
+            err=True,
+        )
+        raise SystemExit(EXIT_USAGE_ERROR)
+    cursor[leaf] = value
+
+
+def _pack_names_loaded_through_event(url: str, run_id: str, at_event: str) -> set[str]:
+    store = _open_store_or_die(url, run_id)
+    loaded: set[str] = set()
+    seen_cutoff = False
+    try:
+        for event in store.iter_events():
+            if event.type == "pack.loaded":
+                name = (event.payload or {}).get("name")
+                if isinstance(name, str) and name:
+                    loaded.add(name)
+            if event.id == at_event:
+                seen_cutoff = True
+                break
+    finally:
+        close = getattr(store, "close", None)
+        if close is not None:
+            close()
+    if not seen_cutoff:
+        click.echo(f"event {at_event!r} not found in run {run_id!r}", err=True)
+        raise SystemExit(EXIT_NOT_FOUND)
+    return loaded
+
+
+def _record_fork_settings_overrides(
+    url: str,
+    *,
+    run_id: str,
+    caused_by: str,
+    overrides: dict[str, dict[str, Any]],
+) -> list[str]:
+    from activegraph.core.event import Event
+    from activegraph.runtime.runtime import Runtime
+
+    rt = Runtime.load(url, run_id=run_id)
+    event_ids: list[str] = []
+    for pack, data in overrides.items():
+        event = Event(
+            id=rt.graph.ids.event(),
+            type="pack.settings_overridden",
+            payload={
+                "pack": pack,
+                "overrides": data["overrides"],
+                "assignments": list(data["assignments"]),
+            },
+            actor="runtime",
+            frame_id=rt.frame.id if rt.frame else None,
+            caused_by=caused_by,
+            timestamp=rt.graph.clock.now(),
+        )
+        rt.graph.emit(event)
+        event_ids.append(event.id)
+    return event_ids
+
+
 # ---- diff ---------------------------------------------------------------