terp-core 0.1.0__tar.gz

terp_core-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_core-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: terp-core
+Version: 0.1.0
+Summary: Terp platform kernel — base classes, ModuleSpec, errors, pagination, DB session seam, secure-by-default config.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.115
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: sqlmodel>=0.0.22
+Provides-Extra: secrets
+Requires-Dist: cryptography>=48.0.1; extra == 'secrets'

terp_core-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-core"
+version = "0.1.0"
+description = "Terp platform kernel — base classes, ModuleSpec, errors, pagination, DB session seam, secure-by-default config."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "fastapi>=0.115",
+    "sqlmodel>=0.0.22",
+    "pydantic-settings>=2.4",
+]
+
+# Config sealing (design §5.4, terp.core.secrets) loads its cipher lazily from the
+# `cryptography` package; an app that never seals config never needs this extra.
+[project.optional-dependencies]
+secrets = ["cryptography>=48.0.1"]
+
+# PEP 420 namespace package: `terp` is shared across distributions, so there is
+# NO src/terp/__init__.py. This distribution owns only `terp.core`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/core"]

terp_core-0.1.0/src/terp/core/__init__.py

@@ -0,0 +1,272 @@
+"""terp.core — the Terp platform kernel (the public API surface).
+
+Importing from ``terp.core`` is the only sanctioned way for a module to use the
+platform. Everything under :mod:`terp.core._internal` is import-forbidden
+outside core; the public names below are the semver contract.
+
+The authoritative import namespace is ``terp.*`` — never ``platform.*`` (it
+shadows a stdlib module).
+"""
+
+from __future__ import annotations
+
+from terp.core.app import BootError, PermissionEnforcer, Principal, create_app, get_principal
+from terp.core.app import enforces_token_revocation, mark_token_revocation_provider
+from terp.core.audit import (
+    AuditAction,
+    AuditPolicy,
+    AuditRecord,
+    DurableAuditSink,
+    bind_audit_actor,
+    current_actor_id,
+    is_durable_audit_sink,
+)
+from terp.core.base_models import (
+    ActorStampedMixin,
+    BaseSchema,
+    BaseTable,
+    BaseUpdateSchema,
+    OwnedMixin,
+    SoftDeleteMixin,
+    TimestampMixin,
+    UUIDPrimaryKeyMixin,
+)
+from terp.core.base_service import BaseService
+from terp.core.cache import (
+    CacheStore,
+    InMemoryCacheStore,
+    configure_cache,
+    get_cache,
+    is_shared_cache_store,
+    mark_shared_cache_store,
+)
+from terp.core.config import Settings, get_settings, settings
+from terp.core.control_plane import ControlPlane
+from terp.core.crud import build_crud_router
+from terp.core.db import SessionDep, get_session
+from terp.core.errors import (
+    AppError,
+    AuthenticationError,
+    ConflictError,
+    InvalidTokenError,
+    NotFoundError,
+    PermissionDeniedError,
+    StaleDataError,
+    ValidationFailedError,
+    build_error_envelope,
+)
+from terp.core.idempotency import (
+    BeginOutcome,
+    IdempotencyStore,
+    InMemoryIdempotencyStore,
+    StoredResponse,
+    is_shared_idempotency_store,
+    mark_shared_idempotency_store,
+)
+from terp.core.events import (
+    EventCatalog,
+    EventDefinition,
+    EventEnvelope,
+    EventError,
+    EventVisibility,
+    emit,
+)
+from terp.core.jobs import (
+    InProcessJobQueue,
+    JobCatalog,
+    JobContext,
+    JobDefinition,
+    JobEnvelope,
+    JobError,
+    JobQueue,
+    JobVisibility,
+    RetryPolicy,
+    enqueue,
+    is_durable_job_queue,
+    mark_durable_job_queue,
+    register_job_tenant_context,
+)
+from terp.core.logging import configure_logging, get_request_id, request_id_ctx
+from terp.core.migrations import (
+    MigrationDiscoveryError,
+    MigrationTree,
+    resolve_all_migration_trees,
+    resolve_migration_target,
+    resolve_migration_trees,
+)
+from terp.core.module_spec import ModuleSpec, Policy, Roles
+from terp.core.object_authz import (
+    ObjectAuthzPredicate,
+    register_object_authz_predicate,
+)
+from terp.core.pagination import (
+    CursorPage,
+    CursorPaginationDep,
+    CursorPaginationParams,
+    Page,
+    PaginationDep,
+    PaginationParams,
+)
+from terp.core.passwords import PasswordPolicy, WeakPasswordError, validate_password
+from terp.core.permissions import (
+    ADMIN,
+    EDITOR,
+    VIEWER,
+    AuthorizationRequirement,
+    Permission,
+    PermissionModel,
+    Role,
+    as_role,
+)
+from terp.core.scheduling import (
+    ScheduleCatalog,
+    ScheduleDefinition,
+    Scheduler,
+    trigger_schedule,
+)
+from terp.core.scoping import ScopePredicate, register_scope_predicate
+from terp.core.secrets import (
+    SecretsError,
+    decrypt_config,
+    encrypt_config,
+    is_sealed_config,
+    mask_config,
+    register_decrypt_call_site,
+)
+from terp.core.security import (
+    CorsPolicy,
+    RateLimit,
+    SecurityConfig,
+    SecurityHeaders,
+    client_ip,
+)
+from terp.core.throttling import (
+    InMemoryThrottleStore,
+    ThrottleStore,
+    is_shared_throttle_store,
+    mark_shared_throttle_store,
+)
+
+__all__ = [
+    "ADMIN",
+    "ActorStampedMixin",
+    "AppError",
+    "AuditAction",
+    "AuditPolicy",
+    "AuditRecord",
+    "AuthenticationError",
+    "AuthorizationRequirement",
+    "BaseSchema",
+    "BaseService",
+    "BaseTable",
+    "BaseUpdateSchema",
+    "BeginOutcome",
+    "BootError",
+    "CacheStore",
+    "ConflictError",
+    "ControlPlane",
+    "CorsPolicy",
+    "CursorPage",
+    "CursorPaginationDep",
+    "CursorPaginationParams",
+    "DurableAuditSink",
+    "EDITOR",
+    "EventCatalog",
+    "EventDefinition",
+    "EventEnvelope",
+    "EventError",
+    "EventVisibility",
+    "IdempotencyStore",
+    "InMemoryCacheStore",
+    "InMemoryIdempotencyStore",
+    "InMemoryThrottleStore",
+    "InProcessJobQueue",
+    "InvalidTokenError",
+    "JobCatalog",
+    "JobContext",
+    "JobDefinition",
+    "JobEnvelope",
+    "JobError",
+    "JobQueue",
+    "JobVisibility",
+    "MigrationDiscoveryError",
+    "MigrationTree",
+    "ModuleSpec",
+    "NotFoundError",
+    "ObjectAuthzPredicate",
+    "OwnedMixin",
+    "Page",
+    "PaginationDep",
+    "PaginationParams",
+    "PasswordPolicy",
+    "Permission",
+    "PermissionDeniedError",
+    "PermissionEnforcer",
+    "PermissionModel",
+    "Policy",
+    "Principal",
+    "RateLimit",
+    "RetryPolicy",
+    "Role",
+    "Roles",
+    "ScheduleCatalog",
+    "ScheduleDefinition",
+    "Scheduler",
+    "ScopePredicate",
+    "SecretsError",
+    "SecurityConfig",
+    "SecurityHeaders",
+    "SessionDep",
+    "Settings",
+    "SoftDeleteMixin",
+    "StaleDataError",
+    "StoredResponse",
+    "ThrottleStore",
+    "TimestampMixin",
+    "UUIDPrimaryKeyMixin",
+    "VIEWER",
+    "ValidationFailedError",
+    "WeakPasswordError",
+    "as_role",
+    "bind_audit_actor",
+    "build_crud_router",
+    "build_error_envelope",
+    "client_ip",
+    "configure_cache",
+    "configure_logging",
+    "create_app",
+    "current_actor_id",
+    "decrypt_config",
+    "emit",
+    "encrypt_config",
+    "enforces_token_revocation",
+    "enqueue",
+    "get_cache",
+    "get_principal",
+    "get_request_id",
+    "get_session",
+    "get_settings",
+    "is_durable_audit_sink",
+    "is_durable_job_queue",
+    "is_sealed_config",
+    "is_shared_cache_store",
+    "is_shared_idempotency_store",
+    "is_shared_throttle_store",
+    "mark_durable_job_queue",
+    "mark_shared_cache_store",
+    "mark_shared_idempotency_store",
+    "mark_shared_throttle_store",
+    "mark_token_revocation_provider",
+    "mask_config",
+    "register_decrypt_call_site",
+    "register_job_tenant_context",
+    "register_object_authz_predicate",
+    "register_scope_predicate",
+    "request_id_ctx",
+    "resolve_all_migration_trees",
+    "resolve_migration_target",
+    "resolve_migration_trees",
+    "settings",
+    "trigger_schedule",
+    "validate_password",
+]

terp_core-0.1.0/src/terp/core/_internal/__init__.py

@@ -0,0 +1,11 @@
+"""``terp.core._internal`` — implementation details, import-forbidden outside core.
+
+Nothing here is part of the semver public surface. Modules (and capabilities
+that did not declare it) must import from :mod:`terp.core` instead. The
+architecture suite fails the build on any ``terp.core._internal`` import from a
+module or sibling.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

terp_core-0.1.0/src/terp/core/_internal/discovery.py

@@ -0,0 +1,148 @@
+"""Filesystem discovery primitive (internal, composition-root use only).
+
+A pure, side-effect-free walk over an app's domain roots. It imports no domain
+code, so it is safe to call from low-level contexts (e.g. Alembic) without
+triggering import side effects. The composition root (a later phase) builds
+router/model/event wiring on top of this.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import pathlib
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+from terp.core.module_spec import ModuleSpec
+
+_CAPABILITY_ENTRY_POINT_GROUP = "terp.capabilities"
+
+# Domain roots in dependency order (lowest layer first).
+DEFAULT_DOMAIN_ROOTS: tuple[str, ...] = ("capabilities", "foundation", "modules")
+
+
+class CapabilityDiscoveryError(RuntimeError):
+    """A capability entry point could not be loaded or is invalid (fail closed at boot).
+
+    Discovery is part of composition, so a broken, mistyped, or name-colliding
+    capability must stop the boot loudly — never crash with a bare traceback, mount
+    a shadowing duplicate, or vanish silently.
+    """
+
+
+@dataclass(frozen=True)
+class DomainPackage:
+    """Metadata for a single discovered domain package."""
+
+    root: str
+    name: str
+    path: pathlib.Path
+    import_path: str
+
+
+def iter_domain_packages(
+    app_root: str | pathlib.Path,
+    *,
+    package: str = "app",
+    roots: Iterable[str] = DEFAULT_DOMAIN_ROOTS,
+) -> list[DomainPackage]:
+    """Return every domain package under *app_root*, grouped by root then sorted.
+
+    Directories whose name starts with ``_`` (e.g. ``_registry``) and
+    non-directories are skipped, keeping discovery deterministic.
+    """
+    base = pathlib.Path(app_root)
+    packages: list[DomainPackage] = []
+    for root in roots:
+        root_dir = base / root
+        if not root_dir.is_dir():
+            continue
+        for child in sorted(root_dir.iterdir()):
+            if not child.is_dir() or child.name.startswith("_"):
+                continue
+            packages.append(
+                DomainPackage(
+                    root=root,
+                    name=child.name,
+                    path=child,
+                    import_path=f"{package}.{root}.{child.name}",
+                )
+            )
+    return packages
+
+
+def iter_capability_specs(names: Sequence[str] | None = None) -> list[ModuleSpec]:
+    """Load installed capability ``ModuleSpec`` entry points.
+
+    Capabilities self-register by declaring a ``terp.capabilities`` entry point
+    that resolves to a :class:`~terp.core.ModuleSpec`. This lets ``create_app``
+    mount a capability's router (and register its models) without any edit to a
+    composition root.
+
+    When *names* is supplied, only those entry points' specs are returned. This
+    keeps discovery profile-shaped: an app may install optional capability
+    packages for libraries or tooling without exposing every installed routed
+    surface. Every installed entry point in the group is still loaded and
+    validated first — filtering selects what mounts, never what is checked —
+    so the duplicate-name guard cannot be bypassed by a filtered profile.
+
+    Fail-closed discovery: an entry point that fails to import, resolves to
+    something other than a ``ModuleSpec``, collides on entry-point name, or
+    collides on ``name`` with another capability raises
+    :class:`CapabilityDiscoveryError` — so a broken or shadowing capability stops
+    the boot loudly instead of crashing with a bare traceback, mounting a
+    duplicate router, or silently disappearing.
+    """
+    wanted = set(names) if names is not None else None
+    specs: list[ModuleSpec] = []
+    entry_points_seen: dict[str, str] = {}
+    provided_by: dict[str, str] = {}
+    installed: set[str] = set()
+    for entry_point in importlib.metadata.entry_points(group=_CAPABILITY_ENTRY_POINT_GROUP):
+        if entry_point.name in entry_points_seen:
+            raise CapabilityDiscoveryError(
+                f"capability entry point name {entry_point.name!r} is provided by two "
+                f"targets ({entry_points_seen[entry_point.name]!r} and {entry_point.value!r}); "
+                "entry point names must be unique so a capability filter cannot mount "
+                "multiple surfaces"
+            )
+        entry_points_seen[entry_point.name] = entry_point.value
+        try:
+            loaded = entry_point.load()
+        except Exception as exc:  # any import-time failure must fail boot, not pass silently
+            raise CapabilityDiscoveryError(
+                f"capability entry point {entry_point.name!r} ({entry_point.value}) "
+                f"failed to load: {exc}"
+            ) from exc
+        if not isinstance(loaded, ModuleSpec):
+            raise CapabilityDiscoveryError(
+                f"capability entry point {entry_point.name!r} ({entry_point.value}) must "
+                f"resolve to a terp.core.ModuleSpec, got {type(loaded).__name__}"
+            )
+        if loaded.name in provided_by:
+            raise CapabilityDiscoveryError(
+                f"capability name {loaded.name!r} is provided by two entry points "
+                f"({provided_by[loaded.name]!r} and {entry_point.name!r}); capability "
+                "names must be unique so a router cannot be shadowed"
+            )
+        provided_by[loaded.name] = entry_point.name
+        installed.add(entry_point.name)
+        if wanted is None or entry_point.name in wanted:
+            specs.append(loaded)
+    if wanted is not None:
+        missing = wanted - installed
+        if missing:
+            raise CapabilityDiscoveryError(
+                "requested capability entry point(s) not installed: "
+                + ", ".join(sorted(missing))
+            )
+    return sorted(specs, key=lambda spec: spec.name)
+
+
+__all__ = [
+    "DEFAULT_DOMAIN_ROOTS",
+    "CapabilityDiscoveryError",
+    "DomainPackage",
+    "iter_capability_specs",
+    "iter_domain_packages",
+]

terp_core-0.1.0/src/terp/core/_internal/engine.py

@@ -0,0 +1,73 @@
+"""Lazy SQLAlchemy engine construction (internal).
+
+Kept out of the public surface so the engine, pool, and URL handling can be
+refactored freely. Public code reaches the database only through
+:data:`terp.core.db.SessionDep`.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import Engine
+from sqlmodel import create_engine
+
+from terp.core.config import settings
+
+_engine: Engine | None = None
+
+
+def _engine_options(database_url: str) -> dict[str, object]:
+    """Engine kwargs: connection-pool tuning for a server DB; SQLite keeps its defaults.
+
+    Pool sizing / recycling / pre-ping apply to a server database (Postgres, MySQL,
+    …). SQLite (dev / test, often in-memory) keeps SQLAlchemy's default pool —
+    ``pool_size`` / ``max_overflow`` do not apply to it, and recycling an in-memory
+    connection would discard the database.
+
+    A PostgreSQL database additionally receives a per-session ``statement_timeout``
+    (``DB_STATEMENT_TIMEOUT_MS``) on every pooled connection, so one runaway query
+    cannot hold a worker + connection forever; other server databases apply their
+    equivalent knob at the database/DSN level.
+
+    The ``per-module`` schema layout (ADR 0070) is a PostgreSQL feature: any other
+    dialect fails closed here, at engine construction, so a misconfigured deployment
+    never opens a connection against a layout its database cannot express.
+    """
+    if settings.DB_SCHEMA_LAYOUT == "per-module" and not database_url.startswith("postgresql"):
+        raise RuntimeError(
+            "DB_SCHEMA_LAYOUT='per-module' requires a PostgreSQL DATABASE_URL; "
+            "schemas are a PostgreSQL feature (ADR 0070)"
+        )
+    if database_url.startswith("sqlite"):
+        return {"echo": False}
+    options: dict[str, object] = {
+        "echo": False,
+        "pool_pre_ping": settings.DB_POOL_PRE_PING,
+        "pool_size": settings.DB_POOL_SIZE,
+        "max_overflow": settings.DB_MAX_OVERFLOW,
+        "pool_timeout": settings.DB_POOL_TIMEOUT,
+        "pool_recycle": settings.DB_POOL_RECYCLE,
+    }
+    if database_url.startswith("postgresql") and settings.DB_STATEMENT_TIMEOUT_MS > 0:
+        options["connect_args"] = {
+            "options": f"-c statement_timeout={settings.DB_STATEMENT_TIMEOUT_MS}"
+        }
+    return options
+
+
+def get_engine() -> Engine:
+    """Return the process-wide engine, creating it on first use."""
+    global _engine
+    if _engine is None:
+        _engine = create_engine(settings.DATABASE_URL, **_engine_options(settings.DATABASE_URL))
+    return _engine
+
+
+def reset_engine() -> None:
+    """Dispose and clear the cached engine (used by tests)."""
+    global _engine
+    if _engine is not None:
+        _engine.dispose()
+        _engine = None
+
+
+__all__ = ["get_engine", "reset_engine"]