Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Adapters And Runtime Boundaries

AHRI_TRE_RS keeps infrastructure behind adapter crates so the workflow model can stay stable while PostgreSQL, DuckDB, OAuth, and runtime packaging details evolve.

PostgreSQL Metadata

PostgreSQL is the metadata store. The metadata adapter boundary is owned by ahri_tre_pgmeta.

The adapter is responsible for:

  • connecting from explicit PostgreSQL server and authentication inputs resolved by the Trusted runtime
  • bootstrapping and checking the canonical metadata schema
  • exposing typed read models for studies, governance, domains, variables, assets, versions, datasets, datafiles, transformations, tags, and mappings
  • exposing write primitives with operation-specific errors
  • keeping SQL and schema details out of domain records and application request types

Application workflows should call metadata capabilities through the app and adapter boundaries. Shared type crates should not hold live connections, transactions, libpq handles, or connection pools.

Datastore identity binding is datastore-local metadata, not a separate repository service. Ordinary opens connect to the PostgreSQL database named by logical Datastore identifier, read the binding from that database, and verify the binding before returning a runtime capability. Privileged creation obtains physical database authority only from Application configuration inside the Trusted runtime.

PostgreSQL OAuth

OAuth/OIDC session semantics are separated from PostgreSQL wiring.

ahri_tre_orcid owns pure OAuth/OIDC contract types and validation semantics. The Trusted runtime owns reusable authentication artifacts through owner-bound Managed-secret capabilities; public records retain only safe identity and exact-version provenance.

ahri_tre_libpq_oauth owns the PostgreSQL 18 libpq bearer-token bridge. It installs the required authdata hook, passes the selected ID token to libpq, and returns a redacted PostgreSQL metadata connection only after the connection has succeeded.

This split is deliberate. Authentication flow code should not leak into the metadata read/write model, and metadata SQL should not know how a token was obtained.

DuckDB, DuckLake, And Lake Locations

DuckDB plus DuckLake is the analytical lake side of the runtime. The lake adapter boundary is owned by ahri_tre_lake.

Runtime code must not embed Restricted local references. Configured creation passes the container-visible filesystem base or object namespace to the Lake adapter, which derives the Datastore-owned path. Ordinary identity-bound opens receive the persisted Lake location instead of reading ambient path variables.

The lake adapter is responsible for:

  • creating and validating the local lake layout
  • loading DuckDB extensions needed by the Lake location
  • attaching DuckLake through PostgreSQL-backed catalog credentials, preferably materialized as session-local managed secrets resolved from the datastore binding
  • detecting persisted DuckLake encryption behavior
  • returning health information and diagnostics to the application layer
  • executing lake operations without moving DuckDB/DuckLake details into domain crates

The application layer coordinates metadata and lake work. It must treat cross-store operations as workflow steps with observable outcomes, not as implicit ACID transactions across PostgreSQL and DuckLake.

Configuration and Secret capabilities

ahri_tre_config owns Application and Client parsing, validation, selection, Effective projection, origin tracking, and fingerprints. The Trusted runtime retains one immutable bootstrap state containing the Effective configuration, the startup Injected-secret snapshot, and the startup Managed-secret snapshot. A separate narrow Managed-store capability permits re-resolution only for a newly authorized operation. The runtime passes resolved settings and narrow Secret capabilities to adapters; adapters do not reopen documents or recover authority from process environment.

Ordinary operations use logical Datastore and Execution-profile identifiers. The Trusted runtime resolves those identifiers against its Application snapshot, authorizes the request, and supplies only the selected physical inputs. User-side Managed runtimes and bindings receive the Client bootstrap, not server topology or Secret references.

See Configuration And Secrets for selection, projection, fingerprint, and ownership rules.