fgraph 1.0.4__tar.gz → 1.2.0__tar.gz

{fgraph-1.0.4 → fgraph-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fgraph
-Version: 1.0.4
+Version: 1.2.0
 Summary: Embedded temporal fact store in a single SQLite file
 Author: Médéric Hurier
 License-Expression: MIT

{fgraph-1.0.4 → fgraph-1.2.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["uv_build>=0.12.0,<0.13.0"]
+requires = ["uv_build>=0.12.5,<0.13.0"]
 build-backend = "uv_build"
 
 [project]
 name = "fgraph"
-version = "1.0.4"
+version = "1.2.0"
 description = "Embedded temporal fact store in a single SQLite file"
 readme = "README.md"
 requires-python = ">=3.12"

{fgraph-1.0.4 → fgraph-1.2.0}/pyproject.toml.orig

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["uv_build>=0.12.0,<0.13.0"]
+requires = ["uv_build>=0.12.5,<0.13.0"]
 build-backend = "uv_build"
 
 [project]
 name = "fgraph"
-version = "1.0.4"
+version = "1.2.0"
 description = "Embedded temporal fact store in a single SQLite file"
 readme = "README.md"
 requires-python = ">=3.12"

{fgraph-1.0.4 → fgraph-1.2.0}/src/fgraph/__init__.py

@@ -34,4 +34,4 @@ __all__ = [
     "restore_backup",
 ]
 
-__version__ = "1.0.4"
+__version__ = "1.2.0"

{fgraph-1.0.4 → fgraph-1.2.0}/src/fgraph/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import os
 import sys
 from collections.abc import Iterator
 from contextlib import contextmanager
@@ -14,6 +15,7 @@ from typing import Annotated, Any, TextIO
 
 import click
 import typer
+from typer._click.core import ParameterSource
 from typer._click.exceptions import Exit as TyperExit
 from typer._click.exceptions import UsageError as TyperUsageError
 
@@ -22,11 +24,16 @@ from fgraph.errors import FGraphError
 from fgraph.errors import TypeError as FGraphTypeError
 from fgraph.jsonio import loads
 from fgraph.store import DEFAULT_QUERY_BUDGET, GENESIS_TX, Db
-from fgraph.values import _canonical_json_document
+from fgraph.values import INT64_MAX, INT64_MIN, _canonical_json_document
 
 app = typer.Typer(no_args_is_help=True, pretty_exceptions_enable=False, help="Temporal facts in one SQLite file.")
 
-DbOption = Annotated[str | None, typer.Option("--db", envvar="FGRAPH_DB", help="SQLite database path.")]
+DEFAULT_DATABASE_PATH = "facts.fgraph"
+LEGACY_DEFAULT_DATABASE_PATH = "fgraph.db"
+
+# The callback alone reads FGRAPH_DB. Command-local --db remains available, but
+# an absent local option must not override a global explicit value with the env.
+DbOption = Annotated[str | None, typer.Option("--db", help="SQLite database path.")]
 JsonOption = Annotated[bool, typer.Option("--json", help="Emit canonical machine-readable JSON.")]
 FilterOption = Annotated[list[str] | None, typer.Option("--filter", help="JSON [attribute,value], repeatable.")]
 EmbedOption = Annotated[str | None, typer.Option("--embed-cmd")]
@@ -35,7 +42,8 @@ ArgsOption = Annotated[str | None, typer.Option("--args", help="Canonical JSON o
 
 @dataclass(frozen=True, slots=True)
 class _Options:
-    db: str = "fgraph.db"
+    db: str = DEFAULT_DATABASE_PATH
+    db_is_implicit: bool = True
     json_output: bool = False
     query_budget: int = DEFAULT_QUERY_BUDGET
 
@@ -46,7 +54,7 @@ _CURRENT_OPTIONS: ContextVar[_Options | None] = ContextVar("fgraph_cli_options",
 @app.callback()
 def _common(
     ctx: typer.Context,
-    db: Annotated[str, typer.Option("--db", envvar="FGRAPH_DB", help="SQLite database path.")] = "fgraph.db",
+    db: Annotated[str, typer.Option("--db", envvar="FGRAPH_DB", help="SQLite database path.")] = DEFAULT_DATABASE_PATH,
     json_output: JsonOption = False,
     query_budget: Annotated[
         int,
@@ -58,7 +66,14 @@ def _common(
     ] = DEFAULT_QUERY_BUDGET,
 ) -> None:
     """Configure options shared by every command."""
-    options = _Options(db=db, json_output=json_output, query_budget=query_budget)
+    db_source = ctx.get_parameter_source("db")
+    empty_environment = db_source is ParameterSource.DEFAULT and os.environ.get("FGRAPH_DB") == ""
+    options = _Options(
+        db="" if empty_environment else db,
+        db_is_implicit=db_source is ParameterSource.DEFAULT and not empty_environment,
+        json_output=json_output,
+        query_budget=query_budget,
+    )
     ctx.obj = options
     _CURRENT_OPTIONS.set(options)
 
@@ -68,13 +83,53 @@ def _options() -> _Options:
 
 
 def _open(path: str | None, *, read_only: bool = False) -> Db:
+    options = _options()
+    selected_path = options.db if path is None else path
+    if selected_path == "":
+        raise fgraph.FormatError(
+            f"database path is empty; pass --db PATH or unset FGRAPH_DB to use {DEFAULT_DATABASE_PATH}"
+        )
+    if path is None and options.db_is_implicit:
+        selected_path = _resolve_implicit_database_path()
     return fgraph.connect(
-        path or _options().db,
+        selected_path,
         read_only=read_only,
-        query_budget=_options().query_budget,
+        query_budget=options.query_budget,
     )
 
 
+def _path_entry_exists(path: Path, *, description: str) -> bool:
+    try:
+        path.lstat()
+    except FileNotFoundError:
+        return False
+    except OSError as exc:
+        raise fgraph.FormatError(
+            f"cannot inspect {description} database path {path!s}; check directory permissions"
+        ) from exc
+    return True
+
+
+def _resolve_implicit_database_path() -> str:
+    legacy = Path(LEGACY_DEFAULT_DATABASE_PATH)
+    if not _path_entry_exists(legacy, description="legacy"):
+        return DEFAULT_DATABASE_PATH
+
+    current = Path(DEFAULT_DATABASE_PATH)
+    if not _path_entry_exists(current, description="default"):
+        return LEGACY_DEFAULT_DATABASE_PATH
+    try:
+        with fgraph.connect(current, read_only=True):
+            pass
+    except FGraphError as exc:
+        raise fgraph.FormatError(
+            f"legacy default database {legacy!s} exists and {current!s} is not an initialized "
+            f"fgraph database; use --db {legacy!s} to keep using the legacy file or explicitly "
+            f"pass --db {current!s} to select the new default"
+        ) from exc
+    return DEFAULT_DATABASE_PATH
+
+
 def run_mcp(graph: Any, *, read_only: bool, embed_cmd: str | None) -> None:
     """Load the optional MCP runtime only when the command is invoked."""
     from fgraph.mcp_server import run
@@ -98,6 +153,28 @@ def _reference(value: str) -> str | int:
         return value
 
 
+def _transaction_integer(value: int, *, context: str) -> int:
+    if not INT64_MIN <= value <= INT64_MAX:
+        raise FGraphTypeError(f"{context} {value!r} is outside the signed 64-bit integer range")
+    return value
+
+
+def _exclusive_flags(
+    positive: bool,
+    negative: bool,
+    *,
+    positive_name: str,
+    negative_name: str,
+) -> bool | None:
+    if positive and negative:
+        raise TyperUsageError(f"{positive_name} and {negative_name} are mutually exclusive")
+    if positive:
+        return True
+    if negative:
+        return False
+    return None
+
+
 def _read_argument(value: str) -> str:
     if value == "-":
         return sys.stdin.read()
@@ -112,25 +189,14 @@ def _read_argument(value: str) -> str:
     return value
 
 
-def _input_text(source: str, *, context: str) -> str:
-    if source == "-":
-        return sys.stdin.read()
-    try:
-        return Path(source).read_text(encoding="utf-8")
-    except (OSError, UnicodeError) as exc:
-        raise fgraph.FormatError(
-            f"{context} file {source!r} cannot be read as UTF-8; check the path and permissions"
-        ) from exc
-
-
 @contextmanager
-def _input_lines(source: str, *, context: str) -> Iterator[Iterator[str]]:
+def _input_lines(source: str, *, context: str) -> Iterator[TextIO]:
     if source == "-":
-        yield iter(sys.stdin)
+        yield sys.stdin
         return
     try:
         with Path(source).open(encoding="utf-8") as stream:
-            yield iter(stream)
+            yield stream
     except (OSError, UnicodeError) as exc:
         raise fgraph.FormatError(
             f"{context} file {source!r} cannot be read as UTF-8; check the path and permissions"
@@ -216,9 +282,9 @@ def add(
 ) -> None:
     """Transact inline JSON, @file JSON, or stdin JSON/NDJSON with '-'."""
     if operation_id is not None and operation_id_prefix is not None:
-        raise FGraphTypeError("choose --operation-id for one transaction or --operation-id-prefix for batches")
+        raise TyperUsageError("choose --operation-id for one transaction or --operation-id-prefix for batches")
     if operation_id_prefix is not None and batch_size is None:
-        raise FGraphTypeError("--operation-id-prefix requires --batch-size")
+        raise TyperUsageError("--operation-id-prefix requires --batch-size")
     if batch_size is not None:
         _add_batches(
             data,
@@ -234,6 +300,8 @@ def add(
     payloads = _payloads(data, context="add input")
     if operation_id is not None and len(payloads) > 1:
         raise FGraphTypeError("--operation-id requires one JSON transaction, not NDJSON")
+    if if_basis_tx is not None and len(payloads) > 1:
+        raise FGraphTypeError("--if-basis-tx cannot span multiple transactions; use idempotent operation ids")
     with _open(db) as graph:
         reports = [
             graph.transact(
@@ -473,6 +541,7 @@ def transaction_receipt(
     json_output: JsonOption = False,
 ) -> None:
     """Print one durable operation/event receipt."""
+    transaction = _transaction_integer(transaction, context="transaction id")
     with _open(db, read_only=True) as graph:
         _emit(graph.receipt(transaction), json_output)
 
@@ -480,6 +549,8 @@ def transaction_receipt(
 @app.command()
 def diff(t1: int, t2: int, db: DbOption = None, json_output: JsonOption = False) -> None:
     """Print facts asserted/retracted in a transaction window."""
+    t1 = _transaction_integer(t1, context="start transaction")
+    t2 = _transaction_integer(t2, context="end transaction")
     with _open(db, read_only=True) as graph:
         _emit(graph.diff(t1, t2), json_output)
 
@@ -489,9 +560,12 @@ def declare(
     attr: str,
     type: str | None = typer.Option(None, "--type"),  # noqa: A002
     ref: bool = False,
-    many: bool | None = typer.Option(None, "--many/--one"),
-    unique: bool | None = typer.Option(None, "--unique/--not-unique"),
-    nohistory: bool | None = typer.Option(None, "--nohistory/--history"),
+    many: bool = typer.Option(False, "--many"),
+    one: bool = typer.Option(False, "--one"),
+    unique: bool = typer.Option(False, "--unique"),
+    not_unique: bool = typer.Option(False, "--not-unique"),
+    nohistory: bool = typer.Option(False, "--nohistory"),
+    history: bool = typer.Option(False, "--history"),
     dims: int | None = None,
     doc: str | None = None,
     vector_model: Annotated[str | None, typer.Option("--vector-model")] = None,
@@ -501,15 +575,28 @@ def declare(
     json_output: JsonOption = False,
 ) -> None:
     """Declare optional attribute behavior."""
+    many_value = _exclusive_flags(many, one, positive_name="--many", negative_name="--one")
+    unique_value = _exclusive_flags(
+        unique,
+        not_unique,
+        positive_name="--unique",
+        negative_name="--not-unique",
+    )
+    nohistory_value = _exclusive_flags(
+        nohistory,
+        history,
+        positive_name="--nohistory",
+        negative_name="--history",
+    )
     with _open(db) as graph:
         _emit(
             graph.declare(
                 attr,
                 type=type,
                 ref=ref,
-                many=many,
-                unique=unique,
-                nohistory=nohistory,
+                many=many_value,
+                unique=unique_value,
+                nohistory=nohistory_value,
                 dims=dims,
                 doc=doc,
                 vector_model=vector_model,
@@ -525,20 +612,27 @@ def shape_command(
     name: str,
     required: Annotated[list[str] | None, typer.Option("--required")] = None,
     allowed: Annotated[list[str] | None, typer.Option("--allowed")] = None,
-    closed: Annotated[bool, typer.Option("--closed/--open")] = False,
+    closed: Annotated[bool, typer.Option("--closed")] = False,
+    open_shape: Annotated[bool, typer.Option("--open")] = False,
     operation_id: Annotated[str | None, typer.Option("--operation-id")] = None,
     if_basis_tx: Annotated[int | None, typer.Option("--if-basis-tx")] = None,
     db: DbOption = None,
     json_output: JsonOption = False,
 ) -> None:
     """Create or replace a required/allowed attribute shape."""
+    closed_value = _exclusive_flags(
+        closed,
+        open_shape,
+        positive_name="--closed",
+        negative_name="--open",
+    )
     with _open(db) as graph:
         _emit(
             graph.declare_shape(
                 name,
                 required=required or (),
                 allowed=allowed or (),
-                closed=closed,
+                closed=closed_value or False,
                 operation_id=operation_id,
                 if_basis_tx=if_basis_tx,
             ),
@@ -616,9 +710,7 @@ def apply_command(
 def snapshot_command(db: DbOption = None) -> None:
     """Write a checksummed exact logical snapshot to stdout."""
     with _open(db, read_only=True) as graph:
-        output = graph.snapshot()
-        if output is not None:
-            typer.echo(output, nl=False)
+        graph.snapshot(sys.stdout)
 
 
 @app.command("restore")
@@ -628,8 +720,8 @@ def restore_command(
     json_output: JsonOption = False,
 ) -> None:
     """Restore a snapshot/1 stream into a pristine database."""
-    with _open(db) as graph:
-        graph.restore(_input_text(source, context="snapshot"))
+    with _input_lines(source, context="snapshot") as lines, _open(db) as graph:
+        graph.restore(lines)
         _emit({"ok": True, "basis_tx": graph.schema()["basis_tx"]}, json_output)
 
 
@@ -642,6 +734,7 @@ def undo(
     json_output: JsonOption = False,
 ) -> None:
     """Apply an audited compensating transaction."""
+    tx = _transaction_integer(tx, context="transaction id")
     with _open(db) as graph:
         _emit(
             graph.undo(
@@ -685,7 +778,7 @@ def tail(
             for record in graph.follow(since):
                 typer.echo(_canonical_json_document(record))
         else:
-            for record in graph.event_records(since):
+            for _transaction, record in graph._iter_event_records(since):  # noqa: SLF001
                 typer.echo(_canonical_json_document(record))
 
 

{fgraph-1.0.4 → fgraph-1.2.0}/src/fgraph/mcp_server.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import base64
 import os
 import signal
 import subprocess
@@ -22,7 +23,7 @@ from mcp.server.mcpserver.exceptions import ResourceError, ToolError
 from mcp.types import ToolAnnotations
 
 from fgraph._embed_runner import START_ERROR
-from fgraph.errors import FGraphError, ReadOnly, TooLarge
+from fgraph.errors import Conflict, FGraphError, ReadOnly, TooLarge
 from fgraph.errors import TypeError as FGraphTypeError
 from fgraph.models import TxReport
 from fgraph.store import GENESIS_TX, Db
@@ -33,6 +34,8 @@ _EMBED_TIMEOUT_MESSAGE = "embed command timed out after 60 seconds; use a bounde
 _MAX_TOOL_ITEMS = 100
 _MAX_ENTITY_ATTRIBUTES = 32
 _MAX_RESPONSE_BYTES = 256 * 1024
+_CHANGES_PAGE_BYTES = 192 * 1024
+_EVENT_CHUNK_BYTES = 128 * 1024
 
 
 def _tool_errors[**P, R](handler: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
@@ -180,6 +183,62 @@ def _continued_resource_uri(authority: str, cursor: str, *, path: str | None = N
     return f"fgraph://{authority}{suffix}?{urlencode(query)}"
 
 
+def _resource_integer(value: Any, name: str, *, minimum: int, maximum: int) -> int:
+    if not isinstance(value, str) or not value.isascii() or not value.isdigit():
+        raise FGraphTypeError(f"event {name} must be a canonical decimal integer")
+    parsed = int(value)
+    if value != str(parsed) or not minimum <= parsed <= maximum:
+        raise FGraphTypeError(f"event {name} is outside its valid range")
+    return parsed
+
+
+def _event_coordinates(db: Db, event: Any, basis: Any, offset: Any, digest: Any) -> tuple[str, int, int, str]:
+    if not isinstance(event, str):
+        raise FGraphTypeError("event id must be a canonical RFC 4122 UUID")
+    try:
+        parsed_event = uuid.UUID(event)
+    except ValueError as exc:
+        raise FGraphTypeError("event id must be a canonical RFC 4122 UUID") from exc
+    if event != str(parsed_event) or parsed_event.variant != uuid.RFC_4122:
+        raise FGraphTypeError("event id must be a canonical RFC 4122 UUID")
+    pinned_basis = _resource_integer(basis, "basis", minimum=GENESIS_TX, maximum=_basis(db))
+    basis_row = db._connection.execute(  # noqa: SLF001
+        "SELECT 1 FROM fgraph_events WHERE tx=?",
+        (pinned_basis,),
+    ).fetchone()
+    if basis_row is None:
+        raise FGraphTypeError("event basis must identify a transaction receipt")
+    chunk_offset = _resource_integer(offset, "offset", minimum=0, maximum=INT64_MAX)
+    if (
+        not isinstance(digest, str)
+        or len(digest) != 64
+        or any(character not in "0123456789abcdef" for character in digest)
+    ):
+        raise FGraphTypeError("event digest must be 32-byte lowercase hexadecimal")
+    return event, pinned_basis, chunk_offset, digest
+
+
+def _event_resource_uri(event: str, basis: int, offset: int, digest: str) -> str:
+    return f"fgraph://event/{quote(event, safe='')}?" + urlencode({"basis": basis, "offset": offset, "digest": digest})
+
+
+def _event_payload(db: Db, event: str, basis: int, digest: str) -> bytes:
+    row = db._connection.execute(  # noqa: SLF001
+        "SELECT ev.event_hash,ev.event_data FROM fgraph_events ev "
+        "JOIN fgraph_ids i ON i.id=ev.tx WHERE i.gid=? AND ev.tx<=?",
+        (uuid.UUID(event).bytes, basis),
+    ).fetchone()
+    if row is None:
+        raise Conflict(f"event {event!r} is not visible at basis {basis}")
+    event_hash = bytes(row["event_hash"])
+    if len(event_hash) != 32 or digest != event_hash.hex():
+        raise Conflict("event digest does not match the pinned event receipt")
+    if row["event_data"] is None:
+        raise Conflict("event payload is unavailable because the event was excised")
+    db._decode_event_data(event, event_hash, row["event_data"])  # noqa: SLF001
+    return str(row["event_data"]).encode()
+
+
 def _schema_page(
     snapshot: dict[str, Any],
     offset: int,
@@ -392,7 +451,7 @@ def create_server(
             "pages, preserve returned basis_tx for follow-up reads, and supply stable operation_id plus "
             "if_basis_tx for retry-safe writes. The server is read-only unless explicitly started with write access."
         ),
-        version="1.0.4",
+        version="1.2.0",
     )
     read_annotations = ToolAnnotations(
         read_only_hint=True,
@@ -756,6 +815,37 @@ def create_server(
         receipt["truncated"] = len(facts) > _MAX_TOOL_ITEMS
         return _resource_result(receipt)
 
+    @server.resource(
+        "fgraph://event/{event}{?basis,offset,digest}",
+        name="fgraph event",
+        description="One basis- and digest-pinned canonical event payload in bounded byte chunks.",
+        mime_type="application/json",
+    )
+    @_resource_errors
+    async def event_resource(
+        event: str,
+        basis: str = "",
+        offset: str = "0",
+        digest: str = "",
+    ) -> dict[str, Any]:
+        event, pinned_basis, chunk_offset, digest = _event_coordinates(db, event, basis, offset, digest)
+        payload = _event_payload(db, event, pinned_basis, digest)
+        if chunk_offset >= len(payload):
+            raise FGraphTypeError("event offset is outside the canonical event payload")
+        chunk = payload[chunk_offset : chunk_offset + _EVENT_CHUNK_BYTES]
+        next_offset = chunk_offset + len(chunk)
+        result = {
+            "basis_tx": pinned_basis,
+            "event": event,
+            "event_hash": digest,
+            "offset": chunk_offset,
+            "encoding": "base64",
+            "data": base64.b64encode(chunk).decode("ascii"),
+        }
+        if next_offset < len(payload):
+            result["next_uri"] = _event_resource_uri(event, pinned_basis, next_offset, digest)
+        return _resource_result(result)
+
     @server.resource(
         "fgraph://changes{?since,cursor}",
         name="fgraph changes",
@@ -776,16 +866,54 @@ def create_server(
         if basis is None:
             basis = _basis(db)
             position = boundary
+        if position is None:
+            raise FGraphTypeError("changes cursor has no transaction position; restart pagination")
         rows = db._connection.execute(  # noqa: SLF001
             "SELECT tx FROM fgraph_events WHERE tx>? AND tx<=? ORDER BY tx LIMIT ?",
             (position, basis, _MAX_TOOL_ITEMS + 1),
-        ).fetchall()
-        records = [db._event_record_for_tx(int(row["tx"])) for row in rows]  # noqa: SLF001
-        next_cursor = None
-        if len(records) > _MAX_TOOL_ITEMS:
-            next_cursor = _changes_cursor(db, basis, int(rows[_MAX_TOOL_ITEMS - 1]["tx"]), since)
-        result = {"basis_tx": basis, "events": records[:_MAX_TOOL_ITEMS]}
-        if next_cursor is not None:
+        )
+        records: list[dict[str, Any]] = []
+        last_position = position
+        next_position: int | None = None
+        oversized_event: dict[str, Any] | None = None
+        event_bytes = 0
+        for row in rows:
+            transaction = int(row["tx"])
+            if len(records) == _MAX_TOOL_ITEMS:
+                next_position = last_position
+                break
+            record = db._event_record_for_tx(transaction)  # noqa: SLF001
+            raw = _canonical_json_document(record).encode()
+            if len(raw) <= _CHANGES_PAGE_BYTES and event_bytes + len(raw) <= _CHANGES_PAGE_BYTES:
+                records.append(record)
+                event_bytes += len(raw)
+                last_position = transaction
+                continue
+            if records:
+                next_position = last_position
+                break
+            event_hash_row = db._connection.execute(  # noqa: SLF001
+                "SELECT event_hash FROM fgraph_events WHERE tx=?",
+                (transaction,),
+            ).fetchone()
+            if event_hash_row is None or len(bytes(event_hash_row["event_hash"])) != 32:
+                raise FGraphTypeError("oversized event has no valid event hash")
+            event_hash = bytes(event_hash_row["event_hash"]).hex()
+            oversized_event = {
+                "event": record["event"],
+                "event_hash": event_hash,
+                "bytes": len(raw),
+                "uri": _event_resource_uri(str(record["event"]), basis, 0, event_hash),
+            }
+            last_position = transaction
+            if transaction < basis:
+                next_position = transaction
+            break
+        result = {"basis_tx": basis, "events": records}
+        if oversized_event is not None:
+            result["oversized_event"] = oversized_event
+        if next_position is not None:
+            next_cursor = _changes_cursor(db, basis, next_position, since)
             result["next_uri"] = _continued_resource_uri("changes", next_cursor, since=since)
         return _resource_result(result)