Skip to content
ContractSpec
Start here

Package manual · integrations

·Forms, data views and data exchange

integration.governed-data-postgres

Subject-bound PostgreSQL persistence for governed ecosystem projections.

integrationsintegrationv2.0.5experimentalserverbunnode
@lssm-tech/integration.governed-data-postgres
bun add @lssm-tech/integration.governed-data-postgres
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Durable PostgreSQL persistence for the LSSM governed projection gateway.

The adapter stores projection catalog metadata, exact field/purpose grants, payload-free access decisions, revocation events, leased delivery attempts and acknowledgements, and export/erasure job state. Product records and shared projection payloads remain in their source systems and are read only through the governed gateway.

Every subject-bearing table uses forced row-level security. Runtime stores set app.governed_subject_ref inside a short transaction and repeat the subject predicate in every query. The catalog is global metadata and cannot contain a domain payload or secret material.

The package accepts the provider-neutral DatabaseProvider, so the host may bind managed PostgreSQL, a vertical-managed database, or a customer-managed database without changing domain authority.

Catalog entries are immutable by projection id. Exact idempotent replay is accepted; a changed schema, offer, consent copy, or provenance record must use a new projection id so an existing grant cannot silently change meaning.

PostgresGovernedDeliveryWorkerStore claims due work with expiring leases, recovers abandoned leases, records only explicit consumer outcomes, schedules bounded retries, and moves ambiguous effects to a dead letter. Its operator projection omits pairwise subjects and payloads; only terminal failed items can be manually returned to pending.

The rights-job queue stores indexed processor, next-attempt, lease-expiry, and update metadata alongside the schema-validated record. Existing rows are backfilled additively from their payload-free record JSON so scheduled scans do not deserialize complete subject histories merely to find due work.

PostgresGovernedSourceRightsRevocationStore.record and writeOrganizationGrant serialize on one per-subject advisory lock taken first in each transaction. A racing source-rights change either revokes the committed organization grant or is seen by the issuance re-check, which refuses source_rights_stale and writes neither grant nor binding.

scripts/source-rights-lock-proof.sh proves that serialization on a disposable PostgreSQL 17 with five backends and least-privilege NOSUPERUSER NOBYPASSRLS login roles. Ordering is observed through pg_locks/pg_blocking_pids, never timed. The recovery worker role needs SELECT, INSERT and UPDATE on revocation_acknowledgements, because acknowledgement writes upsert. grantPostgresGovernedDataRecoveryWorkerRole(database, role) applies exactly those worker grants to an existing deployment-owned role after migration.

Relationships

THIS PACKAGEintegration.governed-data-postgres12 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

3 declarations

Declared capabilities

Subject-bound governed data state

Store governed projection catalogs, grants, decisions, revocations, acknowledgements, and rights jobs in a subject-scoped PostgreSQL boundary.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • lint:checknode ../../../scripts/biome.cjs check .
  • lint:fixnode ../../../scripts/biome.cjs check --write .
  • prebuildcontractspec-bun-build prebuild
  • testbun test
  • typechecktsgo --noEmit && tsgo --noEmit -p scripts/tsconfig.json
  • proof:rights-lockssh scripts/source-rights-lock-proof.sh