dockflow-core 0.2.0__tar.gz

dockflow_core-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dockflow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dockflow_core-0.2.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: dockflow-core
+Version: 0.2.0
+Summary: Domain-independent shared primitives for Dockflow
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: psycopg[binary]>=3.3.6,<4 ; extra == 'postgresql'
+Requires-Python: >=3.12
+Provides-Extra: postgresql
+Description-Content-Type: text/markdown
+
+# Dockflow Core
+
+Domain-independent primitives shared by Dockflow CLI, Pipelines and Artifacts:
+SQLite/PostgreSQL adapters, caller-defined schema initialization/versioning,
+generic locks, common errors, portable JSON encoding, stream hashing and durable
+filesystem operations. Core imports no consuming package and owns no domain
+schema, models, queries or persistence policy.
+
+Install `dockflow-core==0.2.0`, or `dockflow-core[postgresql]==0.2.0` for
+PostgreSQL support. The SQLite implementation uses the Python standard library.
+Optional drivers and connections are initialized only by explicit operations.
+
+Consumers supply `Schema` definitions and retain their own queries and policies.
+Several independently versioned schemas can share one physical database.
+
+This package follows the shared Dockflow application version and MIT license.
+Development includes AI assistance. See the repository documentation for
+configuration and deployment requirements.

dockflow_core-0.2.0/README.md

@@ -0,0 +1,18 @@
+# Dockflow Core
+
+Domain-independent primitives shared by Dockflow CLI, Pipelines and Artifacts:
+SQLite/PostgreSQL adapters, caller-defined schema initialization/versioning,
+generic locks, common errors, portable JSON encoding, stream hashing and durable
+filesystem operations. Core imports no consuming package and owns no domain
+schema, models, queries or persistence policy.
+
+Install `dockflow-core==0.2.0`, or `dockflow-core[postgresql]==0.2.0` for
+PostgreSQL support. The SQLite implementation uses the Python standard library.
+Optional drivers and connections are initialized only by explicit operations.
+
+Consumers supply `Schema` definitions and retain their own queries and policies.
+Several independently versioned schemas can share one physical database.
+
+This package follows the shared Dockflow application version and MIT license.
+Development includes AI assistance. See the repository documentation for
+configuration and deployment requirements.

dockflow_core-0.2.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "dockflow-core"
+version = "0.2.0"
+description = "Domain-independent shared primitives for Dockflow"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+[project.optional-dependencies]
+postgresql = ["psycopg[binary]>=3.3.6,<4"]
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12"]
+build-backend = "uv_build"

dockflow_core-0.2.0/src/dockflow_core/__init__.py

@@ -0,0 +1,8 @@
+"""Domain-independent Dockflow primitives; imports perform no external I/O."""
+
+from .coordination import LockScope
+from .database import Database, database
+from .errors import DockflowError
+from .schema import Schema
+
+__all__ = ["Database", "DockflowError", "LockScope", "Schema", "database"]

dockflow_core-0.2.0/src/dockflow_core/canonical.py

@@ -0,0 +1,114 @@
+"""Portable JSON validation, serialization and deterministic typed encoding."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import struct
+from typing import Any
+
+MAX_INTEGER = 2**53 - 1
+
+
+def _string(value: str) -> str:
+    try:
+        value.encode("utf-8", errors="strict")
+    except UnicodeError as exc:
+        raise ValueError("JSON strings cannot contain unpaired surrogates") from exc
+    return value
+
+
+def canonical_tree(
+    value: Any, *, typed_keys: bool = False, strict_types: bool = False
+) -> list[Any]:
+    """Encode a portable JSON value without losing its numeric type or -0.0."""
+
+    def is_kind(kind):
+        return type(value) is kind if strict_types else isinstance(value, kind)
+
+    def encode(item):
+        return canonical_tree(item, typed_keys=typed_keys, strict_types=strict_types)
+
+    if value is None:
+        return ["null"]
+    if is_kind(bool):
+        return ["bool", value]
+    if is_kind(int):
+        if abs(value) > MAX_INTEGER:
+            raise ValueError("JSON integer exceeds the portable 53-bit range")
+        return ["int", str(value)]
+    if is_kind(float):
+        if not math.isfinite(value):
+            raise ValueError("JSON numbers must be finite")
+        return ["float64", struct.pack(">d", value).hex()]
+    if is_kind(str):
+        return ["string", _string(value)]
+    if is_kind(list):
+        return ["array", [encode(item) for item in value]]
+    if is_kind(dict):
+        if any(
+            (type(key) is not str if strict_types else not isinstance(key, str))
+            for key in value
+        ):
+            raise ValueError("JSON object keys must be strings")
+        return [
+            "object",
+            [
+                [encode(key) if typed_keys else _string(key), encode(value[key])]
+                for key in sorted(value)
+            ],
+        ]
+    raise ValueError(f"Unsupported JSON value type: {type(value).__name__}")
+
+
+def validate_json(value: Any) -> None:
+    canonical_tree(value)
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return json.dumps(
+        canonical_tree(value), ensure_ascii=False, separators=(",", ":")
+    ).encode("utf-8")
+
+
+def digest(value: Any) -> str:
+    return hashlib.sha256(canonical_bytes(value)).hexdigest()
+
+
+def json_bytes(value: Any) -> bytes:
+    """Serialize validated ordinary JSON, preserving portable parameter types."""
+    validate_json(value)
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+
+
+def loads(source: str | bytes) -> Any:
+    """Strict JSON parsing shared by durable records and external boundaries."""
+
+    def pairs(items: list[tuple[str, Any]]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for key, value in items:
+            if key in result:
+                raise ValueError(f"Duplicate JSON object key: {key}")
+            result[key] = value
+        return result
+
+    def constant(value: str) -> None:
+        raise ValueError(f"Non-finite JSON number: {value}")
+
+    result = json.loads(source, object_pairs_hook=pairs, parse_constant=constant)
+    validate_json(result)
+    return result
+
+
+def stable_json_bytes(value: Any) -> bytes:
+    """Sorted finite JSON with ASCII escaping, without a typed identity envelope."""
+    return json.dumps(
+        value, sort_keys=True, separators=(",", ":"), allow_nan=False
+    ).encode()

dockflow_core-0.2.0/src/dockflow_core/coordination.py

@@ -0,0 +1,22 @@
+"""Generic lock scopes; consumers supply namespace and identity semantics."""
+
+from .database import Database
+
+
+class LockScope:
+    def __init__(self, database: Database, namespace: str, identity: str):
+        self.database = database
+        self.key = database.lock_key(namespace, identity)
+        self.mutation_key = database.lock_key(namespace + ":mutation", identity)
+
+    def gate(self, connection) -> None:
+        self.database.transaction_lock(connection, self.key, shared=True)
+
+    def serialize(self, connection) -> None:
+        self.database.transaction_lock(connection, self.mutation_key)
+
+    def try_exclusive(self, connection) -> bool:
+        return self.database.try_lock(connection, self.key)
+
+    def release_exclusive(self, connection) -> None:
+        self.database.unlock(connection, self.key)

dockflow_core-0.2.0/src/dockflow_core/database.py

@@ -0,0 +1,501 @@
+"""Domain-independent database backend boundary.
+
+Connections, SQL dialect, durability, schema and driver failure classification
+live here. Callers retain their transaction/retry policies and decide whether an
+uncertain commit invalidates their session or an idempotent operation may retry.
+No connection is shared by workers.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import errno
+import hashlib
+import importlib
+import math
+import os
+import re
+import sqlite3
+import stat
+import time
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from .errors import DockflowError
+from .locking import owner_lock as _owner_lock
+from .schema import Schema
+
+
+class OwnerConflict(Exception):
+    """Another process holds the requested database lock."""
+
+
+class Database(ABC):
+    backend: str
+    binary_type: str
+    write_begin: str
+    snapshot_begin: str
+    row_lock: str
+    clock_expression: str
+
+    def __init__(self, options: dict):
+        self.options = dict(options)
+
+    @abstractmethod
+    def connect(
+        self, *, readonly=False, mapping=False, timeout=5.0, create=True
+    ) -> Any:
+        """Open an autocommit connection, without opening a transaction."""
+
+    @abstractmethod
+    def prepare(self) -> None:
+        """Prepare durable storage only for an authorized mutating operation."""
+
+    @abstractmethod
+    def tables(self, connection) -> set[str]: ...
+
+    @abstractmethod
+    def indexes(self, connection) -> set[str]: ...
+
+    @abstractmethod
+    def owner_connection(
+        self, lock_id: int, *, exclusive: bool = False
+    ) -> tuple[Any, Any]: ...
+
+    supports_shared_owners = False
+
+    @staticmethod
+    def lock_key(namespace: str, identity: str) -> int:
+        """Derive a stable signed advisory key from caller-owned names."""
+        encoded_namespace = namespace.encode()
+        framed = (
+            str(len(encoded_namespace)).encode()
+            + b":"
+            + encoded_namespace
+            + identity.encode()
+        )
+        return int.from_bytes(
+            hashlib.sha256(framed).digest()[:8],
+            "big",
+            signed=True,
+        )
+
+    def transaction_lock(self, connection, key: int, *, shared=False) -> None:
+        """SQLite's write transaction already serializes writers."""
+        return None
+
+    def try_lock(self, connection, key: int, *, shared=False) -> bool:
+        return True
+
+    def unlock(self, connection, key: int, *, shared=False) -> None:
+        return None
+
+    def sql(self, statement: str) -> str:
+        return statement
+
+    def execute(self, connection, statement: str, parameters=()):
+        return connection.execute(self.sql(statement), parameters)
+
+    def json_text(self, column: str, path: str) -> str:
+        """Internal scalar query view; never coerce canonical stored JSON."""
+        import re
+
+        if not re.fullmatch(
+            r"[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?", column
+        ) or not re.fullmatch(r"[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*", path):
+            raise ValueError("Invalid internal JSON query path")
+        if self.backend == "postgresql":
+            return f"({column}::jsonb #>> '{{{path.replace('.', ',')}}}')"
+        return f"CAST(json_extract(CAST({column} AS TEXT), '$.{path}') AS TEXT)"
+
+    def text_order(self, expression: str) -> str:
+        collation = '"C"' if self.backend == "postgresql" else "BINARY"
+        return f"({expression} COLLATE {collation})"
+
+    def begin(self, connection, *, readonly=False):
+        connection.execute(self.snapshot_begin if readonly else self.write_begin)
+
+    def schema_exists(self, connection, schema: Schema) -> bool:
+        if "dockflow_schema_components" not in self.tables(connection):
+            return False
+        return (
+            self.execute(
+                connection,
+                "SELECT version FROM dockflow_schema_components WHERE name=?",
+                (schema.name,),
+            ).fetchone()
+            is not None
+        )
+
+    def validate_schema(self, connection, schema: Schema) -> None:
+        if not self.schema_exists(connection, schema):
+            raise DockflowError("Database schema is missing", "CONFLICT", 409)
+        row = self.execute(
+            connection,
+            "SELECT version FROM dockflow_schema_components WHERE name=?",
+            (schema.name,),
+        ).fetchone()
+        version = row["version"] if isinstance(row, dict) else row[0]
+        if version != schema.version:
+            raise DockflowError("Unsupported database schema version", "CONFLICT", 409)
+        if not schema.tables <= self.tables(
+            connection
+        ) or not schema.indexes <= self.indexes(connection):
+            raise DockflowError(
+                "Database schema is incomplete; restore a verified backup",
+                "CONFLICT",
+                409,
+            )
+
+    def schema_lock(self, connection):
+        """The SQLite write transaction already serializes schema creation."""
+        return None
+
+    def initialize_schema(self, connection, schema: Schema) -> None:
+        """Initialize only the supplied definition inside a caller write transaction."""
+        self.schema_lock(connection)
+        if self.schema_exists(connection, schema):
+            self.validate_schema(connection, schema)
+            return
+        tables = self.tables(connection)
+        registry = "dockflow_schema_components"
+        if schema.tables & tables or (
+            self.backend == "sqlite" and tables and registry not in tables
+        ):
+            raise DockflowError(
+                "Unregistered database objects conflict; select fresh state",
+                "CONFLICT",
+                409,
+            )
+        connection.execute(
+            "CREATE TABLE IF NOT EXISTS dockflow_schema_components (name TEXT PRIMARY KEY, version INTEGER NOT NULL CHECK(version>0))"
+        )
+        for statement in schema.statements:
+            connection.execute(statement.format(binary=self.binary_type))
+        if schema.initialize is not None:
+            schema.initialize(self, connection)
+        self.execute(
+            connection,
+            "INSERT INTO dockflow_schema_components VALUES (?,?)",
+            (schema.name, schema.version),
+        )
+        self.validate_schema(connection, schema)
+
+    @contextlib.contextmanager
+    def snapshot(self):
+        connection = None
+        try:
+            connection = self.connect(readonly=True)
+            if connection is None:
+                raise DockflowError("Database snapshot is missing", "NOT_FOUND", 404)
+            self.begin(connection, readonly=True)
+            yield connection
+        except DockflowError:
+            raise
+        except Exception:
+            raise DockflowError(
+                "Cannot read Dockflow database snapshot", "UNAVAILABLE", 503
+            ) from None
+        finally:
+            if connection is not None:
+                connection.close()
+
+    @staticmethod
+    def unique_error(error) -> bool:
+        return (
+            isinstance(error, sqlite3.IntegrityError)
+            or getattr(error, "sqlstate", None) == "23505"
+        )
+
+    @staticmethod
+    def retryable_error(error) -> bool:
+        code = getattr(error, "sqlstate", None)
+        return (
+            (
+                isinstance(error, sqlite3.OperationalError)
+                and getattr(error, "sqlite_errorcode", 0) & 0xFF
+                in {sqlite3.SQLITE_BUSY, sqlite3.SQLITE_LOCKED}
+            )
+            or code in {"40001", "40P01", "55P03", "57014"}
+            or (
+                (code is None or code.startswith("08"))
+                and type(error).__name__ in {"OperationalError", "InterfaceError"}
+                and not isinstance(error, sqlite3.Error)
+            )
+        )
+
+
+class SQLiteDatabase(Database):
+    backend = "sqlite"
+    binary_type = "BLOB"
+    write_begin = "BEGIN IMMEDIATE"
+    snapshot_begin = "BEGIN"
+    row_lock = ""
+    clock_expression = "(julianday('now') - 2440587.5) * 86400.0"
+
+    def connect(self, *, readonly=False, mapping=False, timeout=5.0, create=True):
+        # Several publishers may initialize a fresh SQLite file simultaneously.
+        # Switching to WAL can report BUSY without honoring busy_timeout. Retry
+        # only connection setup, before the caller has executed any transaction.
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                return self._connect_once(
+                    readonly=readonly, mapping=mapping, timeout=timeout, create=create
+                )
+            except sqlite3.OperationalError as error:
+                if not self.retryable_error(error) or time.monotonic() >= deadline:
+                    raise
+                time.sleep(0.01)
+
+    def _connect_once(self, *, readonly=False, mapping=False, timeout=5.0, create=True):
+        path = Path(self.options["database"]).absolute()
+        if not path.exists() and (readonly or not create):
+            if readonly:
+                return None
+            raise DockflowError(
+                "Dockflow database is uninitialized", "UNAVAILABLE", 503
+            )
+        connection = sqlite3.connect(
+            path.as_uri()
+            + ("?mode=ro" if readonly else "?mode=rwc" if create else "?mode=rw"),
+            uri=True,
+            timeout=timeout,
+            isolation_level=None,
+            check_same_thread=False,
+        )
+        try:
+            if mapping:
+                connection.row_factory = sqlite3.Row
+            connection.execute("PRAGMA foreign_keys=ON")
+            if not readonly:
+                if connection.execute("PRAGMA journal_mode=WAL").fetchone()[0] != "wal":
+                    raise DockflowError(
+                        "Dockflow database requires SQLite WAL", "UNAVAILABLE", 503
+                    )
+                connection.execute("PRAGMA synchronous=FULL")
+            return connection
+        except BaseException:
+            connection.close()
+            raise
+
+    def prepare(self):
+        from .filesystem import reject_symlinks
+
+        path = Path(self.options["database"])
+        try:
+            reject_symlinks(path)
+        except ValueError:
+            raise DockflowError("Database paths cannot contain symlinks") from None
+        reject_network_sqlite(path.absolute())
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    def tables(self, connection):
+        return {
+            row["name"] if isinstance(row, dict) else row[0]
+            for row in connection.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"
+            ).fetchall()
+        }
+
+    def indexes(self, connection):
+        return {
+            row[0]
+            for row in connection.execute(
+                "SELECT name FROM sqlite_master WHERE type='index'"
+            ).fetchall()
+        }
+
+    def owner_connection(self, lock_id, *, exclusive=False):
+        self.prepare()
+        path = Path(self.options["database"])
+        lock_path = (
+            path.with_suffix(path.suffix + ".owner") if os.name == "nt" else path
+        )
+        descriptor = os.open(
+            lock_path,
+            os.O_RDWR
+            | os.O_CREAT
+            | getattr(os, "O_NOFOLLOW", 0)
+            | getattr(os, "O_NONBLOCK", 0)
+            | getattr(os, "O_CLOEXEC", 0),
+            0o600,
+        )
+        if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+            os.close(descriptor)
+            raise DockflowError(
+                "Database ownership requires a regular database file",
+                "UNAVAILABLE",
+                503,
+            )
+        stream = os.fdopen(descriptor, "r+b")
+        try:
+            try:
+                _owner_lock(stream, acquire=True)
+            except OSError as error:
+                if error.errno in {errno.EACCES, errno.EAGAIN, errno.EWOULDBLOCK}:
+                    raise OwnerConflict from None
+                raise
+            return self.connect(), stream
+        except BaseException:
+            stream.close()
+            raise
+
+
+class PostgreSQLDatabase(Database):
+    supports_shared_owners = True
+    backend = "postgresql"
+    binary_type = "BYTEA"
+    write_begin = "BEGIN ISOLATION LEVEL READ COMMITTED"
+    snapshot_begin = "BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY"
+    row_lock = " FOR UPDATE"
+    clock_expression = "EXTRACT(EPOCH FROM clock_timestamp())"
+
+    def connect(self, *, readonly=False, mapping=False, timeout=5.0, create=True):
+        try:
+            module = importlib.import_module("psycopg")
+        except ImportError:
+            raise DockflowError(
+                "Install dockflow-core[postgresql] for PostgreSQL",
+                "UNAVAILABLE",
+                503,
+            ) from None
+        dsn = os.environ.get(self.options["dsn_env"])
+        if not dsn:
+            raise DockflowError(
+                "Database DSN environment variable is missing or empty",
+                "UNAVAILABLE",
+                503,
+            )
+        milliseconds = max(1, int(timeout * 1000))
+        return module.connect(
+            dsn,
+            autocommit=True,
+            connect_timeout=max(1, math.ceil(timeout)),
+            options=f"-c statement_timeout={milliseconds} -c lock_timeout={milliseconds} -c synchronous_commit=on",
+            row_factory=importlib.import_module("psycopg.rows").dict_row
+            if mapping
+            else importlib.import_module("psycopg.rows").tuple_row,
+        )
+
+    def prepare(self):
+        pass
+
+    def sql(self, statement):
+        return statement.replace("?", "%s")
+
+    def tables(self, connection):
+        return {
+            row["tablename"] if isinstance(row, dict) else row[0]
+            for row in connection.execute(
+                "SELECT tablename FROM pg_catalog.pg_tables WHERE schemaname=current_schema()"
+            ).fetchall()
+        }
+
+    def indexes(self, connection):
+        return {
+            row["indexname"] if isinstance(row, dict) else row[0]
+            for row in connection.execute(
+                "SELECT indexname FROM pg_catalog.pg_indexes WHERE schemaname=current_schema()"
+            ).fetchall()
+        }
+
+    def schema_lock(self, connection):
+        self.execute(
+            connection,
+            "SELECT pg_advisory_xact_lock(?)",
+            (self.lock_key("dockflow-core", "schema-registry-v1"),),
+        )
+
+    def transaction_lock(self, connection, key, *, shared=False):
+        function = "pg_advisory_xact_lock_shared" if shared else "pg_advisory_xact_lock"
+        self.execute(connection, f"SELECT {function}(?)", (key,))
+
+    def try_lock(self, connection, key, *, shared=False):
+        function = "pg_try_advisory_lock_shared" if shared else "pg_try_advisory_lock"
+        return self.execute(connection, f"SELECT {function}(?)", (key,)).fetchone()[0]
+
+    def unlock(self, connection, key, *, shared=False):
+        function = "pg_advisory_unlock_shared" if shared else "pg_advisory_unlock"
+        self.execute(connection, f"SELECT {function}(?)", (key,))
+
+    def owner_connection(self, lock_id, *, exclusive=False):
+        connection = self.connect()
+        try:
+            function = (
+                "pg_try_advisory_lock" if exclusive else "pg_try_advisory_lock_shared"
+            )
+            if not self.execute(
+                connection, f"SELECT {function}(?)", (lock_id,)
+            ).fetchone()[0]:
+                raise OwnerConflict
+            return connection, None
+        except BaseException:
+            connection.close()
+            raise
+
+
+def database(options: dict) -> Database:
+    backends = {"sqlite": SQLiteDatabase, "postgresql": PostgreSQLDatabase}
+    try:
+        cls = backends[options["backend"]]
+    except (KeyError, TypeError):
+        raise DockflowError("Unsupported database backend") from None
+    return cls(options)
+
+
+def reject_network_sqlite(path: Path) -> None:
+    """Reject known Linux network mounts; other platforms require operator care."""
+    mounts = Path("/proc/mounts")
+    if not mounts.exists():
+        return
+    try:
+        rows = [line.split() for line in mounts.read_text().splitlines()]
+    except OSError:
+        return
+    matching = [
+        (Path(row[1].replace("\\040", " ")), row[2])
+        for row in rows
+        if len(row) >= 3 and path.is_relative_to(Path(row[1].replace("\\040", " ")))
+    ]
+    if matching:
+        _, filesystem = max(matching, key=lambda row: len(row[0].parts))
+        if filesystem in {
+            "nfs",
+            "nfs4",
+            "cifs",
+            "smbfs",
+            "9p",
+            "ceph",
+            "afs",
+            "fuse.sshfs",
+            "fuse.s3fs",
+            "fuse.rclone",
+            "glusterfs",
+            "lustre",
+        }:
+            raise DockflowError("SQLite requires a local filesystem")
+
+
+def configured_database(options: dict | Database) -> Database:
+    if isinstance(options, Database):
+        return options
+    if not isinstance(options, dict):
+        raise DockflowError("Database configuration must be an object")
+    backend = options.get("backend")
+    field = "database" if backend == "sqlite" else "dsn_env"
+    if (
+        not isinstance(backend, str)
+        or backend not in {"sqlite", "postgresql"}
+        or set(options) != {"backend", field}
+        or not isinstance(options.get(field), str)
+        or not options[field]
+    ):
+        raise DockflowError("Expected SQLite database path or PostgreSQL dsn_env")
+    if backend == "sqlite":
+        if not Path(options[field]).is_absolute():
+            raise DockflowError("Database path must be absolute")
+    elif not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", options[field]):
+        raise DockflowError("Database dsn_env must name an environment variable")
+    return database(options)

dockflow_core-0.2.0/src/dockflow_core/errors.py

@@ -0,0 +1,27 @@
+"""Errors shared by the core and interface adapters."""
+
+import uuid
+
+
+class DockflowError(Exception):
+    def __init__(
+        self,
+        message: str,
+        code: str = "INVALID_ARGUMENT",
+        status: int = 400,
+        details: list[dict] | None = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.details = details or []
+        self.request_id = str(uuid.uuid4())
+
+    def as_dict(self) -> dict:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "details": self.details,
+            "request_id": self.request_id,
+        }

dockflow_core-0.2.0/src/dockflow_core/filesystem.py

@@ -0,0 +1,56 @@
+"""Content and durability primitives with no storage or domain policy."""
+
+import hashlib
+import os
+import uuid
+from pathlib import Path
+from typing import BinaryIO
+
+
+def reject_symlinks(path: Path) -> None:
+    path = path.absolute()
+    for candidate in (path, *path.parents):
+        if candidate.is_symlink():
+            raise ValueError("Paths cannot contain symlinks")
+
+
+def hash_stream(stream: BinaryIO) -> tuple[int, str]:
+    count = 0
+    digest = hashlib.sha256()
+    while chunk := stream.read(1024 * 1024):
+        count += len(chunk)
+        digest.update(chunk)
+    return count, digest.hexdigest()
+
+
+def fsync_directory(path: Path) -> None:
+    if os.name != "nt":
+        descriptor = os.open(
+            path,
+            os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
+        )
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+
+
+def fsync_ancestors(path: Path) -> None:
+    """Flush every potentially new directory entry, starting at the leaf."""
+    for directory in (path, *path.parents):
+        fsync_directory(directory)
+
+
+def atomic_write(path: Path, data: bytes) -> None:
+    """Replace a file and durably acknowledge its new directory entry."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+    try:
+        with temporary.open("xb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+        fsync_directory(path.parent)
+    finally:
+        temporary.unlink(missing_ok=True)

dockflow_core-0.2.0/src/dockflow_core/locking.py

@@ -0,0 +1,26 @@
+"""Portable local database file ownership and path validation."""
+
+import errno
+import os
+from typing import Any
+
+
+def owner_lock(stream: Any, *, acquire: bool) -> None:
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            # A byte-range lock may extend beyond EOF. Never write before exclusion.
+            stream.seek(0)
+            msvcrt.locking(
+                stream.fileno(), msvcrt.LK_NBLCK if acquire else msvcrt.LK_UNLCK, 1
+            )
+        else:
+            import fcntl
+
+            fcntl.flock(
+                stream.fileno(),
+                fcntl.LOCK_EX | fcntl.LOCK_NB if acquire else fcntl.LOCK_UN,
+            )
+    except ImportError as exc:
+        raise OSError(errno.ENOSYS, "OS locking backend unavailable") from exc

dockflow_core-0.2.0/src/dockflow_core/schema.py

@@ -0,0 +1,35 @@
+"""Consumer-supplied schema descriptions, without a registry of consumers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .database import Database
+
+
+@dataclass(frozen=True)
+class Schema:
+    name: str
+    version: int
+    statements: tuple[str, ...]
+    tables: frozenset[str]
+    indexes: frozenset[str] = frozenset()
+    initialize: Callable[[Database, Any], None] | None = None
+
+    def __post_init__(self):
+        if (
+            not re.fullmatch(r"[a-z][a-z0-9_-]*", self.name)
+            or type(self.version) is not int
+            or self.version < 1
+            or not self.tables
+            or any(
+                not re.fullmatch(r"[a-z_][a-z0-9_]*", name)
+                for name in self.tables | self.indexes
+            )
+            or "dockflow_schema_components" in self.tables
+        ):
+            raise ValueError("Invalid schema definition")

dockflow_core-0.2.0/src/dockflow_core/time.py

@@ -0,0 +1,7 @@
+"""UTC timestamps for shared serialized boundaries."""
+
+from datetime import UTC, datetime
+
+
+def utc_now() -> str:
+    return datetime.now(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")