<!-- AUTO-GENERATED:reference -->
---
title: API Reference
description: Complete API reference for @primebrick/dal-pg — every exported symbol.
---

# API Reference

Every exported symbol from `@primebrick/dal-pg`, rendered mechanically from the
TypeDoc extraction. This page is regenerated from `docs/dev-guide/_extracted/api.json`
on every `pnpm extract-docs` run — do not edit by hand.

## Classes

### `AuditLogEntity`

AuditLogEntity — generic audit trail entity.

Maps to any audit table (customers_audit, organizations_audit, user_profiles_audit, etc.)
via the `tableName` override option on finders/writers.

All audit tables share the same column structure:
  id          bigint identity PK
  entity_id   bigint (the audited entity's ID)
  entity_uuid uuid    (the audited entity's UUID)
  action      text    (INSERT, UPDATE, SOFT_DELETE, HARD_DELETE, RESTORE)
  changed_at  timestamptz
  changed_by  text    (actor UUID or "system")
  version     integer
  delta       jsonb   (field-level old/new diff)

This entity has NO

| Property | Type | Description |
|----------|------|-------------|
| id | `bigint` |  |
| entity_id | `bigint` |  |
| entity_uuid | `string` |  |
| action | `string` |  |
| changed_at | `Date` |  |
| changed_by | `string` |  |
| version | `number` |  |
| delta | `Record<string, { old: unknown; new: unknown }>` |  |

### `BulkTimeoutError`

Thrown when a bulk write exceeds its wall-clock budget
(`DalConfig.bulkTimeoutMs` or `BulkOptions.timeoutMs`). The surrounding
transaction is rolled back — no partial writes survive.

Code: `ERR06`. TS-originated (the JS deadline fires between
statements; a slow single statement is bounded by `SET LOCAL
statement_timeout` → PG `57014` query_canceled). HTTP 408.

| Property | Type | Description |
|----------|------|-------------|
| code | `"ERR06"` |  |

#### `BulkTimeoutError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `ConfigEntityBase`

ConfigEntityBase — standard dictionary-style config table entity.

Every Primebrick config table (BE `auth_configurations`, microservice `config`)
extends this base class to get the standard column set without copy-paste.

Columns:
  key            varchar(100) NOT NULL UNIQUE — stable snake_case setting key
  value          text nullable                 — raw TEXT; null = "not set"
  type           varchar(50)  NOT NULL         — ConfigType (drives SDK coercion + FE widget)
  type_config    text nullable                 — JSONB-text extra per-type config (badge values, list API URL, etc.)
  label_key      varchar(100) nullable         — i18n key for the setting title
  description_key varchar(100) nullable        — i18n key for the explanatory text
  reserved       boolean NOT NULL DEFAULT false — if true: editable but not deletable
  group_key      varchar(100) nullable         — UI grouping key (null/empty = ungrouped, top of list)

Plus standard audit columns (created_at/by, updated_at/by, version, deleted_at/by).

The consumer creates a concrete subclass:
  @Entity("config", "public")
  export class ConfigEntryEntity extends ConfigEntityBase &#123;&#125;

This class is DB-agnostic — it does NOT import from @primebrick/sdk.
The SDK's IConfigEntity interface mirrors the field names for port-level use.

| Property | Type | Description |
|----------|------|-------------|
| id | `bigint` |  |
| uuid | `string` |  |
| key | `string` | Unique config key (e.g. "oidc_issuer_url", "enable_mfa"). Never renamed after release. |
| value | `string \| null` | Raw TEXT value. null means "the row exists but the value is not set". |
| type | `string` | Config value type — drives SDK coercion and FE widget selection. |
| type_config | `string \| null` | JSONB-text extra per-type configuration (e.g. badge inline values, list API URL). |
| label_key | `string` | i18n key for the setting title. |
| description_key | `string` | i18n key for the explanatory description. |
| reserved | `boolean` | If true, the row is system-critical: editable but not deletable. |
| group_key | `string \| null` | Optional grouping key for UI display. null/empty = ungrouped (top of list). |
| created_at | `Date` |  |
| created_by | `string` |  |
| updated_at | `Date` |  |
| updated_by | `string` |  |
| version | `number` |  |
| deleted_at | `Date` |  |
| deleted_by | `string` |  |

### `Dal`

| Property | Type | Description |
|----------|------|-------------|
| config | `Required<Pick<DalConfig, "connectionString" \| "schemas" \| "max" \| "statementTimeoutMs" \| "bulkTimeoutMs" \| "connectionTimeoutMillis" \| "idleTimeoutMillis" \| "applicationName">> & Pick<DalConfig, "sharedTables" \| "maxUses" \| "repoDecorator">` | The resolved configuration (defaults merged with user-provided config). |

#### `Dal(config)`

| Parameter | Type | Description |
|-----------|------|-------------|
| config | `DalConfig` |  |

#### `Dal.getPool(): Pool`

The underlying pg.Pool. Exposed for snapshot/migration tooling that needs raw access.

#### `Dal.close(timeoutMs): Promise<void>`

Graceful shutdown — drains the pool with a timeout deadline.

- Re-entrant: concurrent calls return immediately (the first call wins).
- Timeout: if pool.end() doesn't complete within timeoutMs, the promise
  resolves anyway (the pool is left to be reaped by the OS/TCP stack).
- Error containment: if pool.end() throws, the error is logged and swallowed.
- Does NOT install process.on() handlers — that is a consumer-side concern.

| Parameter | Type | Description |
|-----------|------|-------------|
| timeoutMs | `number` | Maximum time to wait for pool.end() to complete. Default: 10000. |

#### `Dal.findById(entity, id, options): Promise<TResult \| null>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| id | `string \| bigint` |  |
| options | `FindByIdOptions` |  |

#### `Dal.findByUUID(entity, uuid, options): Promise<TResult \| null>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| uuid | `string` |  |
| options | `FindByUUIDOptions` |  |

#### `Dal.find(entity, fields, options): Promise<TResult \| null>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `Dal.findAll(entity, fields, options): Promise<AsyncIterable<TResult, any, any> \| TResult[]>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `Dal.findByPage(entity, page, recordsPerPage, fields, options): Promise<PaginatedEntity<TResult>>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| page | `number` |  |
| recordsPerPage | `number` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `Dal.count(entity): Promise<bigint>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |

#### `Dal.vectorSearch(entity, vectorField, queryVector, options): Promise<TResult & { similarity: number; distance: number }[]>`

pgvector nearest-neighbour search — see `Repository.vectorSearch`.
`ORDER BY <vectorField> <op> $n::vector LIMIT <topK>` with the query
vector bound as a parameter (HNSW/ivfflat-safe). `similarity` score for
cosine (`<=>`), raw `distance` for other operators.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| vectorField | `FieldRef<TEntity, keyof TEntity & string>` |  |
| queryVector | `string \| number[]` |  |
| options | `VectorSearchOptions<TEntity>` |  |

#### `Dal.add(entity, row, options): Promise<TResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| row | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `AuditableWriteOptions<TEntity>` |  |

#### `Dal.update(entity, updates, options): Promise<TResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| updates | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Dal.delete(entity, match, options): Promise<TResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Dal.restore(entity, match, options): Promise<TResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Dal.hardDelete(entity, match, options): Promise<TResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Dal.addMany(entity, rows, options): Promise<BulkResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| rows | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & BulkOptions` |  |

#### `Dal.hardDeleteMany(entity, matches, options): Promise<BulkResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| matches | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity> & BulkOptions` |  |

#### `Dal.restoreMany(entity, matches, options): Promise<BulkResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| matches | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity> & BulkOptions` |  |

#### `Dal.updateMany(entity, updates, options): Promise<BulkResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| updates | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity> & BulkOptions` |  |

#### `Dal.deleteMany(entity, matches, options): Promise<BulkResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| matches | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Dal.entityService(cfg): EntityService<TEntity>`

The public path to the generic entity-service worker. The gateway
injects its own (schema-domain-guarded, pool-scoped) Repository — the
consumer never sees it. `cfg.repo` exists only as a decorator seam
(e.g. BE `withCache`): leave it unset for the standard wiring.

| Parameter | Type | Description |
|-----------|------|-------------|
| cfg | `EntityServiceConfig<TEntity>` |  |

#### `Dal.tableAuditPort(): AuditPort`

The standard `{table}_audit` writer port, bound to the gateway
Repository. Use for adapters that need an AuditPort without exposing
the Repository itself.

#### `Dal.serverVersion(): Promise<{ server_version: string; version: string }>`

Server version + connectivity probe in one call. A successful response
already proves the connection is alive — there is deliberately no
separate `ping()` (a dedicated `SELECT 1` would be a redundant round-trip).
Throws on connectivity/timeout failure.

#### `Dal.transaction(fn, options): Promise<TResult>`

Atomic multi-statement work — `BEGIN`/`COMMIT`/`ROLLBACK` around a
tx-scoped Repository. Use for cascades, multi-write units, and any
sequence that must commit or fail as one. Post-commit side effects
(cache invalidation, events) belong AFTER this resolves, never inside.

| Parameter | Type | Description |
|-----------|------|-------------|
| fn | `(txRepo: Repository) => Promise<TResult>` |  |
| options | `TimeoutOverrideOptions` |  |

#### `Dal.beginTransaction(options): DeferredTransaction`

Deferred fluent transaction — buffer repository ops (`tx.add`, `tx.update`,
`tx.find`, …) without executing, then `tx.commit()` compiles and runs them
as ONE data-modifying CTE statement. Atomicity is PostgreSQL's
single-statement guarantee — no BEGIN/COMMIT/ROLLBACK and no rollback
path exist in this mode. Inter-op values flow via `Deferred.ref()`;
conditional TS logic on mid-flow results stays in `transaction(fn)`.

| Parameter | Type | Description |
|-----------|------|-------------|
| options | `TimeoutOverrideOptions` |  |

#### `Dal.truncate(entity, options): Promise<void>`

Physical table reset — delegates to `Repository.truncate` (entity-resolved,
schema-domain guarded). For auditable tables prefer soft-delete; TRUNCATE
is for caches, KB stores, and test teardown.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| options | `{ restartIdentity: boolean; cascade: boolean }` |  |

#### `Dal.partitionMaintenance(entities, options): Promise<PartitionMaintenanceReport>`

pg_partman retention executor — metadata-driven, identical for every
service. Purges `@PartitionChildOf` children of expired parents (before
the partition drop), removes expired strays from the default partition,
then runs `partman.run_maintenance_proc()`. Called by the service's
`jobs.due.system.<svc>.partition-maintenance` consumer.

| Parameter | Type | Description |
|-----------|------|-------------|
| entities | `readonly EntityClass[]` | the service's entity registry (only `@PartitionField`
  entities participate; everything else is ignored) |
| options | `TimeoutOverrideOptions` |  |

### `DalError`

Generic DAL error with a stable `code` field.

| Property | Type | Description |
|----------|------|-------------|
| code | `string` |  |

#### `DalError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `Decimal`

### `DecimalError`

Errors raised by @primebrick/decimal.

### `Deferred`

Handle for a buffered operation's future result. NOT a Promise — awaiting
it pre-commit would deadlock (commit is never reached), so it deliberately
exposes no `then`. Read `.value` only after `await tx.commit()`.

#### `Deferred.ref(field): DeferredFieldRef<T[K]>`

Reference a RETURNING/SELECT column of this op for use in a LATER op.

| Parameter | Type | Description |
|-----------|------|-------------|
| field | `K` |  |

### `DeferredFieldRef`

Opaque marker produced by `Deferred.ref("field")` — embeddable in a later
op's payload/match values. At compile time the `$n` it would occupy is
rewritten to `(SELECT "field" FROM "__rN")` over the source op's RETURNING
branch. Never a bound parameter — survives `jsValueToPgParam` untouched.

### `DeferredTransaction`

#### `DeferredTransaction.add(entity, row, options): Deferred<TResult>`

Buffer an insert — see `Repository.add`. `options.audit` is rejected.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| row | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `AuditableWriteOptions<TEntity>` |  |

#### `DeferredTransaction.update(entity, updates, options): Deferred<TResult>`

Buffer an update — see `Repository.update`. `options.audit` is rejected.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| updates | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `DeferredTransaction.delete(entity, match, options): Deferred<TResult>`

Buffer a soft-delete — see `Repository.delete`. `options.audit` is rejected.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `DeferredTransaction.restore(entity, match, options): Deferred<TResult>`

Buffer a restore — see `Repository.restore`. `options.audit` is rejected.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `DeferredTransaction.hardDelete(entity, match, options): Deferred<TResult>`

Buffer a hard delete — see `Repository.hardDelete`. `options.audit` is rejected.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `DeferredTransaction.find(entity, fields, options): Deferred<TResult \| null>`

Buffer a single-row find — see `Repository.find`.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `DeferredTransaction.findByUUID(entity, uuid, options): Deferred<TResult \| null>`

Buffer a find-by-uuid — see `Repository.findByUUID`.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| uuid | `string` |  |
| options | `FindByUUIDOptions` |  |

#### `DeferredTransaction.findById(entity, id, options): Deferred<TResult \| null>`

Buffer a find-by-id — see `Repository.findById`.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| id | `string \| bigint` |  |
| options | `FindByIdOptions` |  |

#### `DeferredTransaction.findAll(entity, fields, options): Deferred<TResult[]>`

Buffer a findAll — see `Repository.findAll` (`stream` rejected).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `DeferredTransaction.findByPage(entity, page, recordsPerPage, fields, options): Deferred<PaginatedEntity<TResult>>`

Buffer a paged find — see `Repository.findByPage`.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| page | `number` |  |
| recordsPerPage | `number` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `DeferredTransaction.count(entity, options): Deferred<bigint>`

Buffer a count — see `Repository.count`.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| options | `{ tableName: string }` |  |

#### `DeferredTransaction.vectorSearch(entity, vectorField, queryVector, options): Deferred<TResult & { similarity: number; distance: number }[]>`

Buffer a pgvector search — see `Repository.vectorSearch`.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| vectorField | `FieldRef<TEntity, keyof TEntity & string>` |  |
| queryVector | `string \| number[]` |  |
| options | `VectorSearchOptions<TEntity>` |  |

#### `DeferredTransaction.commit(): Promise<void>`

Compile every buffered op into ONE statement and execute it. Atomicity
is the statement's own: a failure anywhere (constraint, pg_raise guard,
abort branch, timeout) rolls back every branch — no rollback code exists
because none is needed. Resolves when all `Deferred` handles are
materialized; rejects with the first failure.

#### `DeferredTransaction.discard()`

Abandon the buffer without executing anything. Nothing has run yet by
design — this simply invalidates the transaction and its Deferred handles.

### `DeletedRecordConflictError`

Unique-constraint conflict on a soft-deleted row — the row exists with
`deleted_at` set and must be restored, never duplicated.

PG-originated via `pg_raise('ERR05', ...)`; the existing row's `uuid`
travels in the error `detail` so consumers can offer a direct restore.
This class is provided for ergonomic `instanceof` checks.

Code: `ERR05`. HTTP 409.

| Property | Type | Description |
|----------|------|-------------|
| code | `"ERR05"` |  |

#### `DeletedRecordConflictError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `DomainService`

The contract every entity service must satisfy — enforced on the router.

| Property | Type | Description |
|----------|------|-------------|
| cfg | `EntityServiceConfig<TEntity>` |  |

#### `DomainService(cfg)`

| Parameter | Type | Description |
|-----------|------|-------------|
| cfg | `EntityServiceConfig<TEntity>` |  |

#### `DomainService.buildConfig(): EntityServiceConfig<TEntity>`

Subclass seam for config enrichment (auditPort / actor / userEntity
injection). Runs once, inside the lazy `svc` resolution — `this.dal`
is available here.

#### `DomainService.list(query): Promise<EntityListResult<TEntity>>`

| Parameter | Type | Description |
|-----------|------|-------------|
| query | `EntityListQuery` |  |

#### `DomainService.get(uuid): Promise<TEntity>`

| Parameter | Type | Description |
|-----------|------|-------------|
| uuid | `string` |  |

#### `DomainService.create(body, tx): Promise<TEntity>`

| Parameter | Type | Description |
|-----------|------|-------------|
| body | `Record<string, unknown>` |  |
| tx | `Repository` |  |

#### `DomainService.update(uuid, body, tx): Promise<TEntity>`

| Parameter | Type | Description |
|-----------|------|-------------|
| uuid | `string` |  |
| body | `Record<string, unknown> & { version: number }` |  |
| tx | `Repository` |  |

#### `DomainService.delete(uuid, version): Promise<TEntity>`

| Parameter | Type | Description |
|-----------|------|-------------|
| uuid | `string` |  |
| version | `number` |  |

#### `DomainService.restore(uuid, version): Promise<TEntity>`

| Parameter | Type | Description |
|-----------|------|-------------|
| uuid | `string` |  |
| version | `number` |  |

#### `DomainService.purge(uuid, version): Promise<TEntity>`

| Parameter | Type | Description |
|-----------|------|-------------|
| uuid | `string` |  |
| version | `number` |  |

#### `DomainService.duplicate(uuids): Promise<DuplicateResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| uuids | `string[]` |  |

#### `DomainService.bulkDelete(items): Promise<unknown>`

| Parameter | Type | Description |
|-----------|------|-------------|
| items | `BulkItem[]` |  |

#### `DomainService.bulkRestore(items): Promise<unknown>`

| Parameter | Type | Description |
|-----------|------|-------------|
| items | `BulkItem[]` |  |

#### `DomainService.audit(uuid, page, limit): Promise<unknown>`

| Parameter | Type | Description |
|-----------|------|-------------|
| uuid | `string` |  |
| page | `number` |  |
| limit | `number` |  |

#### `DomainService.stream(query): AsyncGenerator<TEntity>`

| Parameter | Type | Description |
|-----------|------|-------------|
| query | `EntityListQuery` |  |

### `DuplicateRecordError`

Unique-constraint conflict on a live row.

Normally PG-originated: the `add()` conflict-reporting CTE calls
`pg_raise('ERR04', ...)`, and node-postgres propagates it as a
`DatabaseError` with `err.code === 'ERR04'` and a jsonb `err.detail`
(`{ entity, table, uuid, constraint }`). The DAL throws this class only
when the conflict cannot be attributed to any identifiable row (unique
group whose attempted values are all DB-generated, e.g. a payload-less
`uuid`). Provided in both cases for ergonomic `instanceof` checks.

Code: `ERR04`. HTTP 409.

| Property | Type | Description |
|----------|------|-------------|
| code | `"ERR04"` |  |

#### `DuplicateRecordError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `EntityBase`

Composition root — empty on purpose. `extends Mixin(EntityBase)`.

### `ManifestError`

| Property | Type | Description |
|----------|------|-------------|
| code | `string` |  |

#### `ManifestError(code, message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| code | `string` |  |
| message | `string` |  |

### `MissingVersionError`

Thrown when an auditable-entity write (update/upsert-ON-CONFLICT/delete/restore/hardDelete)
is attempted without a `version` field in the payload.

Code: `ERR02`. TS-originated. HTTP 400.

| Property | Type | Description |
|----------|------|-------------|
| code | `"ERR02"` |  |
| detail | `unknown` | Structured per-row detail for bulk ops (entity, table, missing count, rows[]). |

#### `MissingVersionError(message, detail)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |
| detail | `unknown` |  |

### `MultipleRowsError`

Thrown when a single-row finder (`findById`, `find`) returns more than one row.

| Property | Type | Description |
|----------|------|-------------|
| code | `"MULTIPLE_ROWS"` |  |

#### `MultipleRowsError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `NotFoundError`

Thrown when a finder returns zero rows and `throwIfNotFound` is true (the default).

| Property | Type | Description |
|----------|------|-------------|
| code | `"NOT_FOUND"` |  |

#### `NotFoundError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `OptimisticLockError`

TS wrapper for the PG-originated `ERR01` optimistic concurrency violation.

The DAL does NOT throw this class in the happy/conflict path — PostgreSQL
raises `RAISE EXCEPTION ... USING ERRCODE = 'ERR01'` and node-postgres
propagates it as a `DatabaseError` with `err.code === 'ERR01'`. This class
is provided only for ergonomic `instanceof` checks if a consumer wants to
normalize PG errors into TS errors at a boundary.

Code: `ERR01`. PG-originated. HTTP 409.

| Property | Type | Description |
|----------|------|-------------|
| code | `"ERR01"` |  |

#### `OptimisticLockError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `RecordVanishedError`

Thrown when an auditable-entity write matches zero rows AND a disambiguation
SELECT confirms the row no longer exists (was hard-deleted by another writer).

Code: `ERR03`. TS-originated. HTTP 404.

Distinct from `NotFoundError` (which is for finders): `ERR03` specifically
means "the row existed when you read it but is now gone".

| Property | Type | Description |
|----------|------|-------------|
| code | `"ERR03"` |  |

#### `RecordVanishedError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `Repository`

#### `Repository(db, token, bulkTimeoutMs)`

| Parameter | Type | Description |
|-----------|------|-------------|
| db | `Queryable` |  |
| token | `typeof REPO_INTERNAL` |  |
| bulkTimeoutMs | `number` | Whole-operation wall-clock budget (ms) for every
  *Many method — the transaction must complete within this bound or it is
  aborted and rolled back. `0`/`undefined` disables the budget.
  Per-call override: `BulkOptions.timeoutMs`. |

#### `Repository.findById(entity, id, options): Promise<TResult \| null>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| id | `string \| bigint` |  |
| options | `FindByIdOptions` |  |

#### `Repository.findByUUID(entity, uuid, options): Promise<TResult \| null>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| uuid | `string` |  |
| options | `FindByUUIDOptions` |  |

#### `Repository.find(entity, fields, options): Promise<TResult \| null>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `Repository.findAll(entity, fields, options): Promise<AsyncIterable<TResult, any, any> \| TResult[]>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `Repository.vectorSearch(entity, vectorField, queryVector, options): Promise<TResult & { similarity: number; distance: number }[]>`

pgvector nearest-neighbour search — the DAL-native replacement for raw
`<=>`-style similarity queries.

Emits `ORDER BY <vectorField> <op> $n::vector LIMIT <topK>` with the
query vector always bound as a parameter (required for HNSW/ivfflat
index usage — never interpolated). Entity-generic: schema, tableName
override, filters, projections and soft-delete scoping behave exactly
like `findAll`.

The result carries a `similarity` score column when `distance` is the
default `"<=>"` (cosine — `1 - distance`, higher = closer). For other
operators the projected column is `distance` (raw distance, lower =
closer).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| vectorField | `FieldRef<TEntity, keyof TEntity & string>` |  |
| queryVector | `string \| number[]` |  |
| options | `VectorSearchOptions<TEntity>` |  |

#### `Repository.findByPage(entity, page, recordsPerPage, fields, options): Promise<PaginatedEntity<TResult>>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| page | `number` |  |
| recordsPerPage | `number` |  |
| fields | `FieldProjector[] \| null` |  |
| options | `FindOptions` |  |

#### `Repository.count(entity, options): Promise<bigint>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| options | `{ tableName: string }` |  |

#### `Repository.truncate(entity, options): Promise<void>`

Physical table reset — `TRUNCATE TABLE <schema>.<table>` resolved through
entity metadata, like every other entity op: the schema-domain guard
applies (entities outside the declared domain throw before any SQL).
For auditable tables prefer soft-delete; TRUNCATE is for caches, KB
stores, and test teardown.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| options | `{ restartIdentity: boolean; cascade: boolean }` |  |

#### `Repository.add(entity, row, options): Promise<TResult>`

Add — auditable entity (actor required).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| row | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `AuditableWriteOptions<TEntity>` |  |

#### `Repository.update(entity, updates, options): Promise<TResult>`

Update — auditable entity (actor required).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| updates | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Repository.delete(entity, match, options): Promise<TResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Repository.restore(entity, match, options): Promise<TResult>`

Restore — auditable+deletable entity (actor required).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Repository.hardDelete(entity, match, options): Promise<TResult>`

Hard-delete — auditable entity (actor required for audit log).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| match | `Partial<Record<keyof TEntity & string, unknown>>` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Repository.clone(entity, sourceUuid, options): Promise<TEntity>`

Clone an entity record by UUID.

Fetches the source record (including soft-deleted), builds a new row with:
- PK column excluded (DB auto-generates)
- Unique columns excluded (including uuid — a new uuid is generated)
-

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| sourceUuid | `string` |  |
| options | `AuditableWriteOptions` |  |

#### `Repository.addMany(entity, rows, options): Promise<BulkResult>`

Bulk add — auditable entity (actor required).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| rows | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & BulkOptions` |  |

#### `Repository.deleteMany(entity, matches, options): Promise<BulkResult>`

Bulk soft-delete — auditable+deletable entity (actor required).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| matches | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity>` |  |

#### `Repository.hardDeleteMany(entity, matches, options): Promise<BulkResult>`

Bulk hard-delete — auditable entity (actor required for audit).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| matches | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity> & BulkOptions` |  |

#### `Repository.restoreMany(entity, matches, options): Promise<BulkResult>`

Bulk restore — auditable+deletable entity (actor required).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| matches | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity> & BulkOptions` |  |

#### `Repository.updateMany(entity, updates, options): Promise<BulkResult>`

Bulk update — auditable entity (actor required).

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass & () => TEntity` |  |
| updates | `Partial<Record<keyof TEntity & string, unknown>>[]` |  |
| options | `WriteOptions<Record<string, unknown>> & { actor: string } & MatchByOptions<TEntity> & BulkOptions` |  |

### `SchemaDomainViolationError`

Schema sovereignty domain — the set of PostgreSQL schemas a service is
allowed to touch, declared via `DATABASE_SCHEMA` and pushed here by the
`Dal` constructor (`getDal({ schemas })`).

Enforcement points:
- boot: `assertEntitySchemaDomain` (schema-domain-assert.ts) — every
  registered

| Property | Type | Description |
|----------|------|-------------|
| code | `"SCHEMA_DOMAIN_VIOLATION"` |  |
| details | `{ entity: string; schema: string; allowed: string[] }` |  |

#### `SchemaDomainViolationError(message, details)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |
| details | `{ entity: string; schema: string; allowed: string[] }` |  |

### `TranslationEntityBase`

TranslationEntityBase — standard i18n translations table entity.

Schema = module boundary. Each module creates a concrete subclass with its
own schema. The DAL's Repository resolves the schema natively via
getQualifiedTableName(entity) — no raw SQL, no string interpolation.

BE creates entity classes for all modules it manages:
  @Entity("translations", "public")
  export class AppTranslationEntity extends TranslationEntityBase &#123;&#125;

  @Entity("translations", "system")
  export class SystemTranslationEntity extends TranslationEntityBase &#123;&#125;

  @Entity("translations", "emailsender")
  export class EmailsenderTranslationEntity extends TranslationEntityBase &#123;&#125;

The BE's central CRUD handler maps module code → entity class → Repository.
US microservices do NOT create entity classes — the BE manages their schemas.

Columns:
  key       varchar(255) NOT NULL — full dot-path (e.g. 'app.auth.login.title')
  language  varchar(10)  NOT NULL — BCP 47 tag (e.g. 'it-IT')
  value     text         NOT NULL — translated string

Composite unique: (key, language) — non-partial index: a soft-deleted row
still reserves the key; recreating it surfaces a conflict (ERR05 → restore),
never a deleted+live duplicate.

Plus standard audit columns (created_at/by, updated_at/by, version, deleted_at/by).

| Property | Type | Description |
|----------|------|-------------|
| created_at | `Date` |  |
| created_by | `string` |  |
| updated_at | `Date` |  |
| updated_by | `string` |  |
| version | `number` |  |
| deleted_at | `Date` |  |
| deleted_by | `string` |  |
| id | `bigint` |  |
| uuid | `string` |  |
| key | `string` | Full dot-path translation key (e.g. 'app.auth.login.title'). |
| language | `string` | BCP 47 language tag (e.g. 'it-IT', 'en-GB'). |
| value | `string` | Translated string value. |

### `UnknownColumnError`

Thrown when a write operation (add, update) receives a property not in entity metadata.

| Property | Type | Description |
|----------|------|-------------|
| code | `"UNKNOWN_COLUMN"` |  |

#### `UnknownColumnError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `ValidationError`

Thrown when a validation check fails (e.g. empty updates object, missing actor).

| Property | Type | Description |
|----------|------|-------------|
| code | `"VALIDATION"` |  |

#### `ValidationError(message)`

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` |  |

### `Vector`

`Vector` — runtime-identifiable `number[]` for pgvector `vector(N)` columns.

A real class (not a brand) so the DAL can detect it with `instanceof` —
array subclasses ARE `number[]`-assignable but carry runtime identity.
That identity is load-bearing: `vector` params bind as the `'[v1,v2,…]'`
literal, while plain `number[]` binds as a Postgres array `'{v1,v2,…}'`.

In entities, `embedding: Vector` maps to `vector`; `@Column({ length: N })`
sets the dimension (`vector(N)`).

#### `Vector.toString(): string`

`'[1,2,3]'` — the pgvector text input/output literal.

#### `Vector.from(v): Vector`

Parse the pgvector literal `'[v1,v2,…]'` (or a plain number array).

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `string \| readonly number[] \| Vector` |  |

#### `Vector.fromNumbers(v): Vector`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `readonly number[]` |  |

## Interfaces

### `AdvancedFilter`

One advanced-filter entry (filters sheet / `filters[i][...]` URL params).

| Field | Type | Description |
|-------|------|-------------|
| id | `string` |  |
| field | `string` |  |
| operator | `FilterOperator` |  |
| value | `unknown` |  |

### `AggregateDecl`

Declarative aggregate rollup projected into list rows.

| Field | Type | Description |
|-------|------|-------------|
| name | `string` | Output column name, e.g. "user_count". |
| expr | `string` | Aggregate SQL expression over the join alias, e.g. "COUNT(u.id)". |
| cast | `string` | Optional result cast — emitted as `CAST(<expr> [FILTER...] AS <cast>)`. |
| join | `{ entity: EntityClass; alias: string; base: string; joined: string; extra: string }` | LEFT join feeding the aggregate. |

### `AuditPageOptions`

| Field | Type | Description |
|-------|------|-------------|
| tableName | `string` | e.g. "customers_audit" — the partition parent table name. |
| entityUuid | `string` |  |
| page | `number` |  |
| limit | `number` |  |

### `AuditPageResult`

| Field | Type | Description |
|-------|------|-------------|
| data | `AuditRow[]` |  |
| pagination | `{ page: number; limit: number; total: bigint; hasMore: boolean }` |  |

### `AuditPort`

Audit port — consumers inject their own audit writer.
The DAL calls `writeAudit` fire-and-forget (`.catch(logger?.error ?? noop)`).

### `AuditRow`

| Field | Type | Description |
|-------|------|-------------|
| id | `bigint` |  |
| entity_id | `bigint` |  |
| entity_uuid | `string` |  |
| action | `string` |  |
| changed_at | `string` |  |
| changed_by | `string` |  |
| changed_by_display_name | `string \| null` |  |
| changed_by_idp_code | `string \| null` |  |
| version | `number` |  |
| delta | `Record<string, unknown>` |  |

### `BulkItem`

| Field | Type | Description |
|-------|------|-------------|
| uuid | `string` |  |
| version | `number` |  |

### `CollaborationMeta`

Collaboration fragment injected by `assembleMeta` at serve time.

| Field | Type | Description |
|-------|------|-------------|
| enabled | `boolean` |  |
| expose_editing_value | `boolean` |  |

### `DalConfig`

Configuration for the Dal gateway.

| Field | Type | Description |
|-------|------|-------------|
| connectionString | `string` | PostgreSQL connection string. Required. |
| schemas | `string[]` | Declared schema domain — the ONLY PostgreSQL schemas this service may
touch (from `DATABASE_SCHEMA`). `schemas[0]` is the owned/primary schema
(patch registry, config_entries live here). Entity operations resolving
outside this set throw SchemaDomainViolationError. Required. |
| sharedTables | `string[]` | Shared table names exempt from the schema-domain check — governed
cross-schema table contracts where every module schema carries the
same table and a designated manager reaches all of them. Today only
`translations` (the BE i18n gateway manages `<module>.translations`
for every registered module). The entity's schema pin still applies —
only the domain check is bypassed, for that table name only. |
| max | `number` | Maximum pool size. Default: 10.
 Formula: max ≤ (PG max_connections − reserved) / service_instances.
 The lib cannot pick this for you, but it documents it. |
| statementTimeoutMs | `number` | Per-statement timeout in ms, set via SET statement_timeout on every connection.
 Default: 30000. Set to 0 to disable.
 This is the full wall-clock (command arrival → server completion → all rows transmitted). |
| bulkTimeoutMs | `number` | Maximum wall-clock budget in ms for a single *Many operation
 (addMany/upsertMany/updateMany/deleteMany). The whole transaction must
 complete within this budget — on expiry the work is aborted and the
 transaction rolled back (no partial writes).
 Default: 1800000 (30 min). Per-call override: `BulkOptions.timeoutMs`.
 Set to 0 to disable. |
| connectionTimeoutMillis | `number` | Time to wait when acquiring a connection from the pool before erroring.
 Default: 5000. Fail fast when pool exhausted — don't let requests queue forever. |
| idleTimeoutMillis | `number` | How long an idle connection is kept before closing. Default: 30000 (pg default). |
| maxUses | `number` | Optional: recycle connections after N uses to clear per-session state.
 Default: undefined (off). |
| applicationName | `string` | Optional application_name for PG logging/observability. Default: "primebrick-dal". |
| repoDecorator | `(repo: Repository) => Repository` | Optional decorator applied to the Dal's internal root Repository at
construction — the governed seam for cross-cutting behavior such as
entity caching (`withCache`). The decorated repo backs `dal.entityService`,
`dal.tableAuditPort`, and every entity proxy on this instance, so the
decoration applies uniformly without consumers building their own
repositories. Tx-scoped repositories handed to `dal.transaction(fn)`
callbacks are NOT decorated — writes inside an open transaction must
not trigger cache writes/invalidation before commit. |

### `DuplicateResult`

| Field | Type | Description |
|-------|------|-------------|
| uuids | `string[]` |  |
| errors | `{ uuid: string; error: string }[]` |  |

### `EntityActionEndpoint`

Backing route of an `EntityAction` — emitted by the BE route scan.

| Field | Type | Description |
|-------|------|-------------|
| method | `string` | HTTP method of the backing route (`GET`, `POST`, `PUT`, `DELETE`, ...). |
| path | `string` | Full registered API path with `:param` placeholders verbatim
 (e.g. `/api/v1/auth/users/:uuid/restore`). Consumers substitute
 placeholders from the row (`:uuid` ← `meta.uid`). |

### `EntityListQuery`

| Field | Type | Description |
|-------|------|-------------|
| search | `string` |  |
| search_in | `string[]` |  |
| sort_key | `string` |  |
| sort_dir | `"asc" \| "desc"` |  |
| page | `number` |  |
| page_size | `number` |  |
| filters | `ListFilterCondition[]` |  |
| connector | `"AND" \| "OR"` |  |
| deleted_records | `"EXCLUDED" \| "ONLY" \| "INCLUDED"` |  |

### `EntityListResult`

| Field | Type | Description |
|-------|------|-------------|
| rows | `TEntity[]` |  |
| page | `number` |  |
| page_size | `number` |  |
| total | `bigint` |  |

### `EntityMeta`

Static entity meta — the shape every `*.meta.ts` file MUST satisfy.
The schema is CLOSED for authored metas: undeclared properties are
compile errors, so new meta props require extending this type first.

| Field | Type | Description |
|-------|------|-------------|
| entity | `string` | Entity name, snake_case singular (e.g. `user_profile`). |
| translation_key | `string` | i18n prefix, snake_case singular — used to build dynamic keys. |
| entities_ns | `string` | Namespace OWNING this entity's label keys — the module's own namespace
(`job` → `job.entities.<translation_key>.*`). Absent → `system`
(BE/core-owned entities keep `system.entities.*`).
This is a READ-side reference declared by the owning module — the
namespace write boundary (see `translation-keys.ts`) guarantees the
keys actually live in that module's `<code>.translations` schema. |
| title_key | `string` | Optional i18n key overriding the canonical page title.
When absent, list/create/edit titles are built from the generic
`system.entities.page_title.{list\|create\|edit}` templates interpolated
with `system.entities.<translation_key>.{plural\|singular}`.
Set only for custom pages needing a bespoke title — CRUD entity metas
must not declare it. |
| uid | `string` | Field key holding the entity primary key (usually `uuid`). |
| display_field | `string` | Canonical display field — the column key identifying the entity's
 human-readable label. Drives first-column/sticky table identity and
 default display resolution. |
| display_name | `string` | Display expression template (`${field}` syntax, dot-paths allowed).
OPTIONAL here: `assembleMeta` materializes it as
`"${" + display_field + "}"` when absent — it is always present in the
served response. Used automatically for edit-page titles; reusable for
comboboxes, lists, chips. |
| actions_overrides | `ActionsOverrides` | Per-op enable overrides — may ONLY toggle `enabled` on route-backed
 ops; a missing route already produces `enabled: false`. |
| columns | `MetaColumn[]` | Entity field dictionary (root-level, transversal). |
| table | `TableMeta` | Table options — omit when the entity has no table page
 (e.g. a self-service form meta). |

### `EntityService`

The contract every entity service must satisfy — enforced on the router.

### `EntityServiceConfig`

| Field | Type | Description |
|-------|------|-------------|
| entity | `EntityClass & () => object` | Newable entity class (DB row shape). |
| repo | `Repository` | Repository — INTERNAL injection point only. `dal.entityService(cfg)`
 supplies the gateway-owned instance; callers of the free
 `makeEntityService` (tests, decorators such as BE `withCache`) must
 pass one explicitly. Consumer configs MUST NOT set it — a missing
 `repo` is a hard error, not a fallback. |
| auditPort | `AuditPort` | Audit port — defaults to `makeTableAuditPort(repo)` (the standard
 `{table}_audit` writer). Override only for ports with extra side
 effects (e.g. the BE entity-changed marker publisher). |
| actor | `() => string` | Actor supplier for audit stamping (e.g. SDK `requireActor`). |
| userEntity | `EntityClass` | Optional auditable display-name join target (BE: UserProfileEntity). |
| auditTableName | `string` | Audit trail table override — default `${tableName}_audit`. |
| list | `{ searchableKeys: readonly string[]; filterableKeys: ReadonlySet<string>; defaultSort: { key: string; dir: "asc" \| "desc" }; extraFilters: (q: EntityListQuery) => FilterExpr[]; aggregates: AggregateDecl[] }` |  |
| hooks | `{ afterWrite: (op: EntityAction, entity: TEntity) => void \| Promise<void>; beforeCreate: (body: Record<string, unknown>) => Record<string, unknown> \| Promise<Record<string, unknown>>; beforeUpdate: (uuid: string, body: Record<string, unknown>) => Record<string, unknown> \| Promise<Record<string, unknown>> }` |  |

### `IAuditableEntity`

Entity has audit stamps (created_at/by, updated_at/by, version).
Does NOT imply soft-delete — auditable and deletable are independent
capabilities; compose with `IAuditableEntity & IDeletableEntity` where
both are required (the Dal write-path signatures already do this).

| Field | Type | Description |
|-------|------|-------------|
| created_at | `Date` |  |
| created_by | `string` |  |
| updated_at | `Date` |  |
| updated_by | `string` |  |
| version | `number` |  |

### `IClonableEntity`

Entity supports cloning (cloned_from stores UUID of source record).

| Field | Type | Description |
|-------|------|-------------|
| cloned_from | `string` |  |

### `IDeletableEntity`

Entity supports soft-delete (deleted_at / deleted_by).

| Field | Type | Description |
|-------|------|-------------|
| deleted_at | `Date` |  |
| deleted_by | `string` |  |

### `IExposableEntity`

Entity has a public UUID safe to expose outside the system.

| Field | Type | Description |
|-------|------|-------------|
| uuid | `string` |  |

### `ListFilterParamsOptions`

| Field | Type | Description |
|-------|------|-------------|
| filterValues | `Record<string, unknown>` | Toolbar quick-filter values keyed by column key. |
| columns | `readonly MetaColumn[]` | Entity columns (needed to map filterValues to the right operator). |
| advancedFilters | `readonly AdvancedFilter[]` | FiltersPanel conditions. |
| connector | `string` | Global connector for advanced filters (`AND` | `OR`). |

### `ListResponse`

The paged list response returned by every entity list endpoint.
`total` is a `bigint` — parse JSON responses with a bigint-aware parser
(`extJsonParse` from `@primebrick/sdk`), never `JSON.parse`.

| Field | Type | Description |
|-------|------|-------------|
| rows | `TRow[]` |  |
| page | `number` |  |
| page_size | `number` |  |
| total | `bigint` |  |

### `LoggerPort`

Logger port — consumers inject their own logger.

### `PartitionMaintenanceReport`

| Field | Type | Description |
|-------|------|-------------|
| parents | `PartitionParentReport[]` |  |
| maintenance_ran | `boolean` | Whether `partman.run_maintenance_proc()` ran. |

### `PartitionParentReport`

| Field | Type | Description |
|-------|------|-------------|
| table | `string` | `"schema"."table"` of the partitioned parent. |
| partition_column | `string` |  |
| retention | `string \| null` | Effective retention interval actually applied (part_config wins). |
| children_purged | `Record<string, number>` | `"schema"."child"` → rows deleted for expired parents. |
| strays_deleted | `number` | Expired rows removed from the default partition (never dropped). |
| partitions_before | `number` | Live partition count before/after `run_maintenance_proc()`. |
| partitions_after | `number` |  |
| skipped | `string` | Set when the parent was skipped — reason string. |

### `RowCustomAction`

UI configuration for a non-standard row CTA (route-backed bare op).

| Field | Type | Description |
|-------|------|-------------|
| action_name | `string` | Action/op name — matches the bare op derived from the route
 (e.g. `change_password`). |
| translation_key | `string` | i18n key for the CTA label. |
| icon | `string` | Icon name (Lucide in the reference FE). |
| text_color | `string` | Optional CSS color class for the label. |
| disabled_when_deleted | `boolean` | Disable the CTA on soft-deleted rows. |
| required_permission | `string \| string[]` | Permission required to see/use the action (filtered client-side
 against the user's permission set). |

### `SnapshotQueryable`

Minimal queryable shape — pg.Pool, pg.PoolClient, or any adapter.

### `TableMeta`

Table options — present only on entities with a table page.

| Field | Type | Description |
|-------|------|-------------|
| default_view | `ViewName` | Initial view (default "table"). |
| default_sort | `{ key: string; dir: SortDir }` |  |
| default_page_size | `number` |  |
| page_size_options | `number[]` |  |
| row_custom_actions | `RowCustomAction[]` | UI config for non-standard row actions (e.g. change password).
 Standard ops (edit/delete/duplicate/preview) are derived from
 `meta.actions` — never declared here. |
| filter_presets | `readonly FilterPreset[]` | Mutually-exclusive preset WHERE filters — each rendered as its own
 toolbar control; the active option's conditions AND into every list
 request (see FilterPreset). |

### `TimeoutOverrideOptions`

Per-operation timeout override for dedicated-client work
 (`transaction`, `partitionMaintenance`).

| Field | Type | Description |
|-------|------|-------------|
| timeoutMs | `number` | Override statement_timeout (ms). Transaction-scoped for `transaction`
 (SET LOCAL, auto-resets at COMMIT/ROLLBACK); connection-scoped with
 session-default restore for `partitionMaintenance`. |

## Types & Enums

### `AuditableFieldType`

| Member | Value |
|--------|-------|
| CREATED_AT | "CREATED_AT" |
| CREATED_BY | "CREATED_BY" |
| UPDATED_AT | "UPDATED_AT" |
| UPDATED_BY | "UPDATED_BY" |
| VERSION | "VERSION" |

### `AuditAction`

Audit action enum (mirrors BE's AuditAction).

| Member | Value |
|--------|-------|
| INSERT | "INSERT" |
| UPDATE | "UPDATE" |
| SOFT_DELETE | "SOFT_DELETE" |
| HARD_DELETE | "HARD_DELETE" |
| RESTORE | "RESTORE" |
| CLONE | "CLONE" |

### `DeletableFieldType`

| Member | Value |
|--------|-------|
| DELETED_AT | "DELETED_AT" |
| DELETED_BY | "DELETED_BY" |

### `SynchronizableFieldType`

| Member | Value |
|--------|-------|
| LAST_SYNCED_AT | "LAST_SYNCED_AT" |

### `ActionsOverrides`

Per-op enable overrides — may ONLY toggle `enabled` on route-backed ops.

**Type:** `Record<string, { enabled: boolean }>`

### `AuditableWriteOptions`

Write options for auditable entities — actor is required.

**Type:** `WriteOptions<TEntity> & { actor: string }`

### `AuditParams`

Parameters passed to `AuditPort.writeAudit`.

### `BulkOptions`

Bulk operation options (batch size, timeout).

### `BulkResult`

Result summary of a bulk write (addMany/upsertMany/updateMany/deleteMany).

### `ColumnOptions`

### `ColumnPgPersistenceHints`

### `DalErrorCode`

**Type:** `typeof DalErrorCodes[keyof typeof DalErrorCodes]`

### `DecimalInput`

Anything coercion functions accept: Decimal, native number, bigint, or a decimal string.

**Type:** `Decimal \| number \| bigint \| string`

### `DeletionFilterMode`

Soft-deletion visibility mode — maps to the `deleted_records` list param
on the wire (`non_deleted` → `EXCLUDED`, `deleted` → `ONLY`,
`all` → `INCLUDED`; absent param means the BE default, currently
`EXCLUDED`).

**Type:** `"non_deleted" \| "deleted" \| "all"`

### `EntityAction`

**Type:** `"meta" \| "list" \| "export" \| "create" \| "duplicate" \| "bulkDelete" \| "bulkRestore" \| "get" \| "update" \| "delete" \| "purge" \| "restore" \| "audit"`

### `EntityActionSentinel`

Sentinel gates a route may declare instead of concrete permissions.
Values mirror the `Permission` enum in `@primebrick/sdk`.

**Type:** `"_public" \| "_authenticated_user" \| "_authenticated_admin"`

### `EntityAnnotationInfo`

Per-property type facts extracted from source.

### `EntityAnnotationMap`

Result of `extractEntityAnnotations` — keyed by class name.

### `EntityClass`

Entity metadata via legacy TypeScript decorators (WeakMap "reflection").

**Convention:** every "data" property on the class `prototype` is a SQL column
with a name equal to the property name (snake_case). `@Column()` is only needed
for: `sqlName` / `pgType` / `nullable`, or a short alias for the column name.

- `@Entity()` — table name; optional argument if different from class name.
- `@Key()` — primary key (one column only).
- `@Unique()` — unique index (DDL patch).
- `@IsNotColumn()` — excludes the property from persistence meta & DAL queries.
- `@AuditableField(type)` — marks a field as audit (created_at, created_by, etc.).
- `@DeletableField(type)` — marks a field as soft-delete (deleted_at, deleted_by).
- `@CloneField()` — marks a field as clone tracking (cloned_from).
- `@AuditTrail()` — marks the entity as having an audit trail table.

**Type:** `(args: any[]) => object`

### `EntityColumnTypeHints`

### `EntityCtor`

Entity capability mixins — declare shared audit/deletable columns ONCE,
compose them per-entity instead of copy-pasting decorated fields.

Auditable and deletable are ORTHOGONAL capabilities:
  - audit-only  (hard delete): `class ApiKey extends Auditable(EntityBase)`
  - delete-only:               `class Tag extends Deletable(EntityBase)`
  - both (soft delete):        `class Customer extends Deletable(Auditable(EntityBase))`
  - neither:                   `class Telemetry extends EntityBase`

The concrete entity still owns `@Entity(table)` and the opt-in
`@AuditTrail()` (audit-log table — separate decision from audit columns).
Field decorators on each anonymous mixin class register on that
constructor; `getEntityPersistenceMeta` merges the whole prototype chain
parent-first (see collectMetaChain), so subclass fields always win.

Extra per-entity capabilities (`IExposableEntity`, `IClonableEntity`, …)
keep their `implements` on the concrete class — they are pure type
contracts, not column sets.

**Type:** `(args: any[]) => object`

### `EntityMetaResponse`

The served `GET /api/v1/entities/{entity}/meta` response:
static meta + runtime-injected `display_name`, `actions`, `collaboration`.

**Type:** `EntityMeta & { display_name: string; actions: EntityAction[]; collaboration: CollaborationMeta }`

### `EntityPersistenceMeta`

Serializable persistence metadata (for JSON compare with DB introspection).

### `EntityTypeWarning`

Advisory warning — never fails a build, printed by `primebrick-db`.

### `ExprOperand`

A parameterized SQL operand for `Filter.expr` — `?` markers inside `sql`
are replaced by `$n` bound parameters in order of appearance.

`sql` is a trusted literal (never interpolated user input); `params`
carries the only dynamic data. Example:
  `{ sql: "to_tsvector(?, d.content)", params: ["simple"] }`

### `FieldProjector`

**Type:** `{ kind: "field"; field: FieldRef<any, any>; alias: string } \| { kind: "expr"; expr: string; alias: string; params: unknown[] }`

### `FieldRef`

### `FilterCondition`

One WHERE condition of a filter preset — serialized verbatim as a
`filters[i]` entry on the `/list` query string (same vocabulary as
`AdvancedFilter` conditions: field/op/value).

### `FilterExpr`

**Type:** `{ kind: "field_value"; left: FieldRef<any, any>; op: SqlOperator; right: unknown; operand: SqlExpressionOperand } \| { kind: "field_field"; left: FieldRef<any, any>; op: SqlOperator; right: FieldRef<any, any>; operand: SqlExpressionOperand } \| { kind: "raw"; left: string; op: SqlOperator; right: string; operand: SqlExpressionOperand } \| { kind: "expr"; left: ExprOperand; op: SqlOperator; right: ExprOperand; operand: SqlExpressionOperand } \| { kind: "group"; filters: FilterExpr[]; operand: SqlExpressionOperand; connector: SqlExpressionOperand }`

### `FilterOperator`

Filter operators available for advanced filters.

**Type:** `"=" \| "!=" \| ">" \| "<" \| ">=" \| "<=" \| "contains" \| "startsWith" \| "endsWith" \| "BETWEEN"`

### `FilterPreset`

A mutually-exclusive preset filter group rendered as its own control in
the table toolbar (tandem with the deletion-filter group). Exactly one
option is always active — there is no "clear" affordance. Declared in
`meta.table.filter_presets`; example: a `schedule_type` scope selector
(recurring / once / all) on a jobs table.

### `FilterPresetOption`

A single selectable option of a table filter preset.

### `FindByIdOptions`

Options for `findById`.

### `FindByUUIDOptions`

Options for `findByUUID`.

### `FindOptions`

Options for `find`, `findAll`, `findByPage`.

### `ForeignKeyAction`

**Type:** `"restrict" \| "cascade" \| "set_null" \| "set_default" \| "no_action"`

### `ForeignKeyOptions`

Options for `@ForeignKey()` — REFERENCES target entity column.

### `GroupByOperand`

GROUP BY operand — either an entity field reference or a parameterized
SQL expression (`?` markers bind `params` in order). Expressions are
required for grouping over computed values like `date_trunc(?, created_at)`.
Non-aggregate `field` projections are auto-added to GROUP BY by the
builder; expression projections must be listed here explicitly when they
are the grouping key.

**Type:** `FieldRef<any, any> \| { kind: "expr"; sql: string; params: unknown[] }`

### `HostApiFn`

`ctx.components.hostApi` — the host's authenticated full-path fetch
(`apiFetch`): reaches BE-owned `/api/v1/…` endpoints that `ctx.api`
(ws-bound to the owning service) cannot. Remote pages bind it through
`bindRemoteCtx(ctx)` → `getServiceApi('host')`.

**Type:** `(path: string, init: RequestInit) => Promise<Response>`

### `HostMountHandle`

Handle returned by `ModulePageHost.mount_host` — imperative channel to a
host-mounted component root.

### `IndexMethod`

**Type:** `"btree" \| "hash" \| "gin" \| "gist" \| "spgist" \| "brin" \| "hnsw"`

### `IndexOptions`

Options for `@Index()` — plain (non-unique) secondary indexes of any PG access method.

### `ISODate`

**Type:** `string & { [isoDateBrand]: "ISODate" }`

### `ISOTime`

**Type:** `string & { [isoTimeBrand]: "ISOTime" }`

### `JoinExpr`

### `KeyOptions`

### `LikelyRename`

### `ListConnector`

Global connector joining the advanced-filter group.

**Type:** `"AND" \| "OR"`

### `ListFilterCondition`

### `ListFilterOptions`

### `MatchByOptions`

Options for match-by operations (update, delete, restore, hardDelete, *Many).

### `MetaColumn`

Entity field descriptor — the root-level `columns` dictionary.
Transversal to every page type: table cells, form tooltips, labels.

Declared as a type alias (not interface): object literal types get an
implicit index signature, keeping `MetaColumn` assignable to
`Record<string, unknown>` — host/remotes pass columns through generic
cell-snippet args typed as `Record<string, unknown>`.

### `MetaColumnType`

UI column renderer type. NOTE: this is the UI type, not the DB type —
 e.g. `roles` is `"text"` here but `jsonb` on disk (never ILIKE-searchable).

**Type:** `"text" \| "badge" \| "boolean" \| "color" \| "date" \| "datetime" \| "number" \| "sparkline"`

### `MfaStepUpFn`

`ctx.components.mfaStepUp` — host-bound step-up MFA bridge. The remote
calls it exactly like the host's `useMfaStepUp().executeWithToken`:
`requestFn` runs once with `token = null`; on a `403` response carrying
`mfa_step_up_required` the host shows ITS OWN step-up dialog (host root,
host runtime — nothing crosses the boundary), awaits verification, then
retries `requestFn` with the action-authorization token. The promise
resolves with the final Response — success or failure.

**Type:** `(requestFn: (token: string \| null) => Promise<Response>, context: { action: string; target_resource: string }) => Promise<Response>`

### `MigrationEngineOptions`

Migration engine — apply side. Generation side lives in schema-diff/.

### `MigrationMode`

Migration engine — apply side. Generation side lives in schema-diff/.

**Type:** `"apply" \| "check" \| "off"`

### `MigrationRunResult`

Migration engine — apply side. Generation side lives in schema-diff/.

### `ModuleHostBase`

Host-side context base handed to EVERY remote mount — pages
(`mountPage`) and sheets (`mountSheet`) alike. Versioned via
`host_version` — remote chunks can refuse incompatible hosts.

HARD CONSTRAINT — plain values and functions ONLY: Svelte rune state
(`$state`/`$derived`/`$effect`) is bundle-local and cannot cross this
boundary. UI building blocks come from `@primebrick/ui` bundled inside
the remote chunk, not from ctx; `components` is reserved for the few
host-coupled cases (see `components` doc).

### `ModuleHostComponents`

`ctx.components` — the reserved well-known keys plus open caller-provided
entries. `remote` is assigned by the host loader after the chunk
resolves; `mfaStepUp`/`openSheet`/`hostApi` are built-ins the host
always provides (a caller may override them in tests).

### `ModuleNavDeclaration`

A module's self-described navigation declaration — the payload a service
publishes in `service.register` (`endpoints.nav`) so the FE can render
the module's sidebar nav and the census can resolve its routes WITHOUT
the BE hardcoding another module's pages. This is the wiring that lets
each module present its own nav — a remote page is owned by the service
that ships it, never declared inside a host module's registry.

`route_prefixes` drive active-module resolution (longest-prefix match —
a page under a shared prefix like `/system/jobs` resolves to the owning
module, not to the module owning the broader `/system` prefix).

### `ModuleNavLink`

One sidebar navigation link contributed by a module. `children` is the
collapsible-group mechanism (the shell renders children under the parent).

### `ModuleNotifyInput`

Notification payload accepted by `ctx.notify` — the minimal shape of the
host's `pushNotification` input. Plain values only.

### `ModulePageHost`

Host ctx handed to a remote page's `mountPage(el, ctx)` — the shared
ModuleHostBase plus the page's own route axis (`nav`/`meta`).

**Type:** `ModuleHostBase & { nav: PageRouteDeclaration; meta: EntityMeta }`

### `ModuleSheetDecl`

A remote sheet panel declared by a service inside `endpoints.nav.sheets`
— the sheet analogue of a remote PageRouteDeclaration: the host
owns the sheet ENGINE (open/close/chrome/state), the owning service owns
the CONTENT — an `esm-mount` chunk exporting `mountSheet(el, ctx)`,
mounted at runtime into the host's global sheet surface.

`key` is the open-sheet address, `<module>.<name>` namespaced so a
declared key can never collide across services (enforced at enrollment
by the nav-declaration validator). Anyone holding the key can open it —
host `openSheet`, `ctx.components.openSheet` — visibility is gated by
`access`, never by import reachability.

### `ModuleSheetDefaults`

Chrome defaults a sheet declaration may suggest. The caller's `openSheet`
options always win over these — they are a hint, not a policy.
`content_class` maps to the host engine's `contentClass` option.

### `ModuleSheetHost`

Host ctx handed to a remote sheet's `mountSheet(el, ctx)` — the shared
ModuleHostBase plus the `sheet` control surface: the declared
key, the caller's props (opaque at the boundary — the owning module
knows their shape), the current chrome, and the commands to mutate the
host-owned frame. No `nav`/`meta` — a sheet is not a route; domain
context arrives through `sheet.props`.

**Type:** `ModuleHostBase & { sheet: { key: string; props: Record<string, unknown>; side: ModuleSheetSide; modal: boolean; close: () => void; replace: (props: Record<string, unknown>) => void; setExpanded: (expanded: boolean) => void } }`

### `ModuleSheetSide`

Sheet side — the two chrome slots the host sheet engine owns.

**Type:** `"left" \| "right"`

### `MountPageFn`

The `esm-mount` chunk's entry contract — `export function mountPage(el, ctx)`.
May return the `mount()` result (disposed via `unmount()`), a custom dispose
function, or a promise of either.

**Type:** `(el: HTMLElement, ctx: ModulePageHost) => unknown`

### `MountSectionFn`

A chunk's section-mount export — same host ctx as `mountPage`, plus the
section's own declaration (`id`, `props`, placement) as third argument.

**Type:** `(el: HTMLElement, ctx: ModulePageHost, section: PageSectionDecl) => unknown`

### `MountSheetFn`

The sheet chunk's entry contract — `export function mountSheet(el, ctx)`.
The chunk is declared in `endpoints.nav.sheets[]` (ModuleSheetDecl)
and mounted inside the host's global sheet surface. Same dispose rules as
MountPageFn.

**Type:** `(el: HTMLElement, ctx: ModuleSheetHost) => unknown`

### `OnConflictMode`

Insert conflict semantics for `add()`.

**Type:** `"raise" \| "ignore"`

### `OpenSheetFn`

`ctx.components.openSheet` — opens a sheet panel by key: a host-registered
panel (`shell.*`/`entity.*`/`config.*`) or a remote-declared sheet
(`<module>.<name>` from `nav.sheets[]`, mounted at runtime). The panel
registry, remote declarations and sheet state all live in the host — a
remote page requests the panel, it never ships the engine. `props` are
plain values (callback fns are allowed — they cross the boundary);
`options` are the host's sheet options (`side`, `contentClass`, `modal`,
`keepMountedState`). Unknown keys are rejected with a host notification —
the remote cannot smuggle an undeclared panel.

**Type:** `(panelKey: string, props: Record<string, unknown>, options: Record<string, unknown>) => void`

### `PageLayoutDecl`

Spatial arrangement of a page's sections — ONE archetype: CSS grid.
A vertical stack is the degenerate case (`columns` defaults to `"1fr"`,
sections auto-flow in declaration order); a split is `columns: "280px
1fr"`; a dashboard is `columns: "repeat(3, 1fr)"` + per-section `span`.
New container classes, when genuinely needed, arrive as new optional
fields — the contract never grows a second placement vocabulary.

### `PageRouteComponentFormat`

Remote component delivery format. Extensible — new literals are additive
and non-breaking. `esm-mount`: a precompiled ESM chunk that exports
`mountPage(el, ctx)` (or a default component as fallback).

**Type:** `"esm-mount"`

### `PageRouteDeclaration`

One declared frontend route owned by a module. Modules MUST declare every
FE path they own that is not deducible from nav links or entity
conventions — the AI route census (derived from the consolidated
`GET /api/v1/modules` discovery payload) depends on it.
`param` marks dynamic segments using the FE convention ([uuid], [code]).

### `PageRouteKind`

Page archetype vocabulary — what the route renders, regardless of delivery.

**Type:** `"list" \| "detail" \| "create" \| "page"`

### `PageRouteProps`

`page_props` — free-form per-route metadata with a typed `layout` axis.

### `PageSectionDecl`

One mountable block inside a `layout` — placement is grid-cell based.

### `PageSectionSource`

Section mount target — `remote:<export>` = a named mount export of the
page's own chunk (`mod.mountModels(el, ctx, section)`); `host:<key>` = a
component registered in the host's section registry. The `remote:` form is
the default for module-owned blocks; `host:` composes host-owned building
blocks without shipping a chunk at all.

**Type:** `templateLiteral \| templateLiteral`

### `PaginatedEntity`

Paginated result wrapper.

### `PartitionChildOfOptions`

Options for `@PartitionChildOf()` — declares membership in a partitioned
 parent's atomic delete/retention unit.

### `PartitionFieldOptions`

Options for `@PartitionField()` — the RANGE partition key declaration.

### `PatchManifest`

### `PatchRegistryRow`

### `PatchSegment`

### `PatchStatus`

**Type:** `"pending" \| "applied" \| "failed" \| "pending_review" \| "approved" \| "resolved_manual"`

### `PgColumnType`

`pgType` values legal in `@Column({ pgType })`.

**Type:** `PgScalarType \| templateLiteral \| templateLiteral \| "vector"`

### `PgScalarType`

`PgColumnType` — the canonical PostgreSQL column type vocabulary for
`@Column({ pgType })` and the entity type contract.

A closed union, not a free `string`: aliases like
`"timestamp with time zone"` (write `timestamptz`) or `"character varying"`
(write `varchar`) are compile errors, so the diff/snapshot pipeline never
sees spelling variants.

Type modifiers are NEVER written inside `pgType`: `varchar(N)` comes from
`length`, `numeric(p,s)` from `precision`/`scale`, `vector(N)` from
`length` on a `Vector` prop. `pgType` carries the BASE name only
(`vector(N)` literal is allowed for readability but `length` wins).

**Type:** `"text" \| "varchar" \| "char" \| "citext" \| "uuid" \| "smallint" \| "int2" \| "integer" \| "int" \| "int4" \| "bigint" \| "int8" \| "real" \| "float4" \| "double precision" \| "float8" \| "numeric" \| "decimal" \| "boolean" \| "bool" \| "date" \| "time" \| "timetz" \| "timestamp" \| "timestamptz" \| "interval" \| "inet" \| "cidr" \| "macaddr" \| "macaddr8" \| "json" \| "jsonb" \| "bytea" \| "xml" \| "tsvector"`

### `RemoteDepsManifest`

`<chunk>.deps.json` — emitted next to each remote chunk at build time,
declaring the vendor specifiers/versions it was compiled against.

### `RenameAmbiguity`

### `RenameHeuristicResult`

### `RoundingMode`

**Type:** `"UP" \| "DOWN" \| "CEILING" \| "FLOOR" \| "HALF_UP" \| "HALF_DOWN" \| "HALF_EVEN"`

### `SchemaColumnMeta`

Shared shapes for entity vs database schema snapshots (used by compare + heuristics).

### `SchemaDomain`

### `SchemaMetaDiffV1`

**Type:** `SchemaMetaDiffV2`

### `SchemaMetaDiffV2`

### `SchemaSnapshot`

Schema-diff: canonical entity-vs-database snapshot machinery.
Generation side of the migration engine (migrations/ is the apply side).

### `SchemaTableMeta`

Schema-diff: canonical entity-vs-database snapshot machinery.
Generation side of the migration engine (migrations/ is the apply side).

### `SelectQueryInput`

### `SnakeCaseSingular`

Branded type that enforces snake_case singular (no uppercase letters).
Used for `translation_key` in entity meta — the i18n key prefix.

The brand is applied via `asSnakeCaseSingular()`, which performs a
runtime check rejecting strings containing A-Z. This catches camelCase
(`userProfile`), PascalCase (`RoleMapping`), and UPPER_CASE
(`USER_PROFILE`) at both compile time and runtime.

**Type:** `string & { __snakeCaseSingularBrand: unique symbol }`

### `SortDir`

Sort direction for server-side list queries and header UI.

**Type:** `"asc" \| "desc"`

### `SortingExpr`

**Type:** `{ field: FieldRef<any, any>; dir: SqlSortDirection } \| { kind: "alias"; alias: string; dir: SqlSortDirection } \| { kind: "expr"; sql: string; params: unknown[]; dir: SqlSortDirection }`

### `SqlExpressionOperand`

**Type:** `"AND" \| "OR"`

### `SqlJoinType`

**Type:** `"INNER" \| "LEFT" \| "RIGHT"`

### `SqlOperator`

**Type:** `"=" \| "!=" \| "<>" \| "<" \| "<=" \| ">" \| ">=" \| "ILIKE" \| "LIKE" \| "IN" \| "NOT IN" \| "BETWEEN" \| "IS" \| "IS NOT" \| "<=>" \| "<->" \| "<#>" \| "<+>" \| "<~>" \| "<%>" \| "@@"`

### `SqlQuery`

### `SqlSortDirection`

**Type:** `"ASC" \| "DESC"`

### `StandardOp`

**Type:** `typeof STANDARD_OPS[number]`

### `TooltipPriority`

Tooltip visual severity — drives icon and title color in priority
 tooltip renderers.

**Type:** `"INFORMATION" \| "WARNING" \| "ERROR" \| "QUESTION" \| "HINT" \| "SUCCESS"`

### `TrustedKey`

### `UniqueOptions`

Unique constraint options for composite unique indexes.

### `UpsertOptions`

Upsert-specific options.

### `UUID`

**Type:** `string & { [uuidBrand]: "UUID" }`

### `VectorDistanceOp`

pgvector distance operator for `vectorSearch` — `<=>` cosine, `<->` L2, `<#>` inner product, `<+>` L1.

**Type:** `"<=>" \| "<->" \| "<#>" \| "<+>"`

### `VectorHybridInput`

### `VectorSearchOptions`

Options for `Repository.vectorSearch` — entity-generic like `FindOptions`.

### `VendorManifest`

Host `vendor-manifest.json` — specifier → published vendor asset.

**Type:** `Record<string, { url: string; version: string }>`

### `VendorMismatch`

**Type:** `{ specifier: string; kind: "missing"; required: string } \| { specifier: string; kind: "version"; required: string; provided: string }`

### `VendorResolution`

**Type:** `"external" \| "reject" \| "bundle"`

### `VendorSpecifier`

**Type:** `typeof VENDOR_SPECIFIERS[number]`

### `ViewName`

Table view names supported by entity list pages.

**Type:** `"table" \| "cards" \| "cards_list"`

### `WithAuditableDisplayNames`

Adds display name fields to a row type for auditable entities.
Use this to type the result of queries that include auditable joins.

**Type:** `T & { created_by_name: string; updated_by_name: string; deleted_by_name: string }`

### `WithCreatorDisplayName`

Adds only creator display name (for cases where you only need created_by).

**Type:** `T & { created_by_name: string }`

### `WithDeletedRecords`

Controls how soft-deleted rows (deleted_at IS NOT NULL) are handled in finders.

**Type:** `"EXCLUDED" \| "ONLY" \| "INCLUDED"`

### `WithUpdaterDisplayName`

Adds only updater display name (for cases where you only need updated_by).

**Type:** `T & { updated_by_name: string }`

### `WriteOptions`

Base write options — no actor (for non-auditable entities).

## Constants

### `DalErrorCodes`

Stable error codes for DAL optimistic concurrency control.

These codes are used as PostgreSQL SQLSTATE values (via `RAISE EXCEPTION
USING ERRCODE = 'ERR01'`) and as TS `DalError.code` values. Consumers (BE,
US, FE) branch on the string literal (e.g. `err.code === 'ERR01'`) so that
PG-originated errors and TS-originated errors share the same code.

Convention: `ERR` + 2 digits. The `ER` class is outside the SQL-standard
SQLSTATE classes (`00`–`99`), so PostgreSQL accepts it as a custom code.

**Type:** `{ ERR01: "ERR01"; ERR02: "ERR02"; ERR03: "ERR03"; ERR04: "ERR04"; ERR05: "ERR05"; ERR06: "ERR06"; ERR07: "ERR07"; ERR08: "ERR08"; ERR09: "ERR09"; ERR10: "ERR10" }`

| Field | Value |
|-------|-------|
| ERR01 | "ERR01" |
| ERR02 | "ERR02" |
| ERR03 | "ERR03" |
| ERR04 | "ERR04" |
| ERR05 | "ERR05" |
| ERR06 | "ERR06" |
| ERR07 | "ERR07" |
| ERR08 | "ERR08" |
| ERR09 | "ERR09" |
| ERR10 | "ERR10" |

### `decimalFromPG`

Alias of `dec()` — parse a PostgreSQL `numeric`/`decimal` text value.

**Type:** `typeof dec`

### `Filter`

**Type:** `{ fieldValue: ; fieldField: ; raw: ; expr: ; group:  }`

| Field | Value |
|-------|-------|
| fieldValue | "" |
| fieldField | "" |
| raw | "" |
| expr | "" |
| group | "" |

### `fromString`

**Type:** `typeof dec`

### `fromWire`

Alias of `dec()` — tolerates the `"…d"` wire suffix.

**Type:** `typeof dec`

### `GroupBy`

**Type:** `{ expr:  }`

| Field | Value |
|-------|-------|
| expr | "" |

### `Join`

**Type:** `{ on:  }`

| Field | Value |
|-------|-------|
| on | "" |

### `KEYS_FILENAME`

**Type:** `"keys.json"`

### `MANIFEST_FILENAME`

**Type:** `"MANIFEST.json"`

### `NUMERIC_MIN_SIG_DIGITS`

Minimum significant digits preserved by automatic `div` scale — mirrors
PostgreSQL `NUMERIC_MIN_SIG_DIGITS` (16). See `pgDivScale`.

**Type:** `16`

### `ONE`

**Type:** `Decimal`

### `PATCH_REGISTRY_TABLE`

Per-service-schema patch registry (v2).

Each service owns `<svc_schema>.primebrick_database_patches` — the registry is
domain data of the owning microservice, not a shared global table.
The DDL is self-bootstrapping: the engine runs it unconditionally before any
read, so an empty database upgrades itself.

**Type:** `"primebrick_database_patches"`

### `Project`

**Type:** `{ field: ; expr:  }`

| Field | Value |
|-------|-------|
| field | "" |
| expr | "" |

### `RENAME_HEURISTIC_AGENT_INSTRUCTION`

**Type:** `"renameHeuristicUserReviewRequired is true: ambiguous rename candidates were detected. You MUST ask the user which renames (if any) to apply before running suggested ALTER ... RENAME COLUMN or generating migrations from likelyRenames."`

### `RENAME_MATCH_RULE_LABELS`

Ordered strict → loose; documented for consumers of `diff-entities-vs-database.json`.

**Type:** `readonly string[]`

### `Sort`

**Type:** `{ by: ; byAlias: ; byExpr:  }`

| Field | Value |
|-------|-------|
| by | "" |
| byAlias | "" |
| byExpr | "" |

### `STANDARD_OPS`

The canonical vocabulary of standard entity ops. Every op is always
present in `meta.actions` — ops whose route is not registered are emitted
with `enabled: false` (explicitly unavailable) instead of being omitted.

**Type:** `readonly ["list", "meta", "get", "create.single", "update.single", "delete.single", "purge.single", "restore.single", "read.audit", "export", "delete.bulk", "restore.bulk", "duplicate.bulk"]`

### `TEN`

**Type:** `Decimal`

### `VENDOR_BLOCKED_PACKAGES`

Packages that MUST NOT be imported raw inside a remote chunk — they are
already served through a sanctioned vendor specifier (e.g. transformers is
vendored behind `@primebrick/ui/vendor/transformers`). A raw import would bundle
a second runtime copy (split caches, split env config) — reject it.

**Type:** `readonly ["@huggingface/transformers", "clsx", "tailwind-merge", "tailwind-variants", "@lucide/svelte", "bits-ui"]`

### `VENDOR_SPECIFIERS`

Closed allowlist of bare specifiers remote chunks may import. A
package's specifiers normally union into ONE bundle file so the browser
dedupes by URL — a single runtime instance is guaranteed. Exception:
`svelte`'s public subpaths (events/reactivity/store/attachments) get
their own files — their export names collide with the internal signal
API (`get`/`derived` exist in both), and a flat union module cannot hold
both. Shared internals still dedupe through the bundler's shared chunks.

**Type:** `readonly ["svelte", "svelte/internal/client", "svelte/internal/disclose-version", "svelte/internal/flags/legacy", "svelte/events", "svelte/reactivity", "svelte/store", "svelte/attachments", "svelte/motion", "svelte/easing", "@primebrick/core", "@primebrick/ui", "@primebrick/ui/vendor/transformers", "@primebrick/ui/vendor/clsx", "@primebrick/ui/vendor/tailwind-merge", "@primebrick/ui/vendor/tailwind-variants", "@primebrick/ui/vendor/lucide", "@primebrick/ui/vendor/bits-ui"]`

### `ZERO`

**Type:** `Decimal`

## Functions

### `abs(d): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `add(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `allowedKeyNamespaces(moduleCode): ReadonlySet<string>`

Namespaces a module's meta/nav declarations may REFERENCE — the module's
own namespace plus the CORE vocabularies (`app`, `system`).

| Parameter | Type | Description |
|-----------|------|-------------|
| moduleCode | `string` |  |

### `appendListFilterParams(params, opts, startIdx): number`

| Parameter | Type | Description |
|-----------|------|-------------|
| params | `URLSearchParams` |  |
| opts | `ListFilterParamsOptions` |  |
| startIdx | `number` |  |

### `approvePendingReview(pool, schema, patchName, actor, note): Promise<boolean>`

pending_review → approved for ONE named patch: the engine treats an
`approved` row as review-cleared and applies the file on the next run.

| Parameter | Type | Description |
|-----------|------|-------------|
| pool | `Pool` |  |
| schema | `string` |  |
| patchName | `string` |  |
| actor | `string` |  |
| note | `string` |  |

### `assertEntitySchemaDomain(entities, schemas, sharedTables): void`

Boot-time check: every registered entity must resolve inside `schemas`
(an explicit

| Parameter | Type | Description |
|-----------|------|-------------|
| entities | `readonly unknown[]` |  |
| schemas | `readonly string[]` |  |
| sharedTables | `readonly string[]` |  |

### `assertPgTypeCompatible(annotation, explicitPgType, propertyKey): void`

Throws when an explicit `pgType` is incompatible with the declared TS
annotation family (e.g. `UUID` + `pgType:"text"`, `number` + `pgType:
"int8"`). Unmappable families pass — the explicit type is their contract.

| Parameter | Type | Description |
|-----------|------|-------------|
| annotation | `EntityAnnotationInfo` |  |
| explicitPgType | `string` |  |
| propertyKey | `string` |  |

### `asSnakeCaseSingular(value): SnakeCaseSingular`

Branded constructor for SnakeCaseSingular.
 Throws if the value contains uppercase letters
 (camelCase/PascalCase/UPPER_CASE).

| Parameter | Type | Description |
|-----------|------|-------------|
| value | `string` |  |

### `Auditable(Base): { prototype: AuditableEntity<any> } & TBase`

Adds created_at / created_by / updated_at / updated_by / version
(optimistic-lock column). Does NOT add soft-delete — compose `Deletable`
when the entity needs it.

| Parameter | Type | Description |
|-----------|------|-------------|
| Base | `TBase` |  |

### `AuditableField(what): PropertyDecorator`

Marks a field as auditable (created_at, created_by, updated_at, updated_by, version).

| Parameter | Type | Description |
|-----------|------|-------------|
| what | `AuditableFieldType` |  |

### `AuditTrail(): ClassDecorator`

Marks an entity as having an audit trail table.

### `AuditTrailEntity(options): ClassDecorator`

Marks a class as BEING an audit trail entity (e.g., AuditLogEntity).
Distinct from @AuditTrail() which marks an entity as HAVING an audit trail.
The changedByColumn specifies which property holds the actor (default: "changed_by").

| Parameter | Type | Description |
|-----------|------|-------------|
| options | `{ changedByColumn: string }` |  |

### `buildAuditableJoins(entity, userEntity): JoinExpr[]`

Standard join configuration for auditable entities.
Automatically adds LEFT JOINs to the user entity table for created_by, updated_by, deleted_by fields.

Uses regex guardrail pattern to only join when the field contains a valid UUID.
This prevents errors when the field contains non-UUID values like "system".

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` | The entity class implementing IAuditableEntity |
| userEntity | `EntityClass` | The user entity class (e.g. UserProfileEntity) that has a `uuid` and `display_name` column |

### `buildAuditableJoinsSelective(entity, userEntity, options): JoinExpr[]`

Enhanced version that allows selective joins (e.g., only creator and updater).
Useful when you only need specific audit fields to reduce query overhead.

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` | The entity class implementing IAuditableEntity |
| userEntity | `EntityClass` | The user entity class (e.g. UserProfileEntity) |
| options | `{ includeCreator: boolean; includeUpdater: boolean; includeDeleter: boolean }` | Configuration for which joins to include |

### `buildAuditTrailJoins(auditEntity, userEntity): { joins: JoinExpr[]; projections: FieldProjector[] }`

Build LEFT JOIN + projections for audit trail entities (AuditLogEntity).

Audit trail entities have a single `changed_by` column (not created_by/updated_by/deleted_by).
This function joins the user entity to resolve `changed_by` into `display_name` and `idp_code`.

Uses `castRightTo: "uuid"` + `castLeftTo: "uuid"` to trigger the regex guardrail
(`changed_by ~ '^[0-9a-fA-F-]{36}$'`) automatically in renderJoins().
This prevents errors when `changed_by` contains non-UUID values like "system".

Distinct from buildAuditableJoins() which uses castRightTo: "text" (no guardrail, text = text).
buildAuditTrailJoins() uses castRightTo: "uuid" + castLeftTo: "uuid" (guardrail + uuid = uuid).

| Parameter | Type | Description |
|-----------|------|-------------|
| auditEntity | `EntityClass` | The audit trail entity class (e.g., AuditLogEntity) |
| userEntity | `EntityClass` | The user entity class (e.g., UserProfileEntity) with uuid, display_name, idp_code columns |

### `buildDatabaseSnapshot(db, tables, generatedAt): Promise<SchemaSnapshot>`

Introspect given tables into the same SchemaSnapshot shape as entities.
Uses `pg_attribute` / `pg_type` / `format_type` (pg-diff-api CatalogApi style) so PostGIS
and other UDTs surface with real `typname` / `typcategory`, not only `information_schema.data_type`.

The caller owns the connection: pass a Pool (read-only fan-out) or a reserved client.

| Parameter | Type | Description |
|-----------|------|-------------|
| db | `SnapshotQueryable` |  |
| tables | `{ schema: string; name: string }[]` |  |
| generatedAt | `string` |  |

### `buildEntitySnapshot(registry, opts, generatedAt): SchemaSnapshot`

Canonical entity-intent snapshot for a service's entity registry.
Parameterized on the registry — no service-specific imports live here.

| Parameter | Type | Description |
|-----------|------|-------------|
| registry | `readonly EntityClass[]` |  |
| opts | `BuildEntitySnapshotOptions` |  |
| generatedAt | `string` |  |

### `buildPatchFilename(diff, d): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| diff | `SchemaMetaDiffV2` |  |
| d | `Date` |  |

### `buildSelectQuery(input): SqlQuery`

| Parameter | Type | Description |
|-----------|------|-------------|
| input | `SelectQueryInput` |  |

### `buildSqlPatchFromMetaDiff(entitySnap, diff): string`

Best-effort SQL to move **TARGET database** toward **entity** intent.
Destructive changes (DROP) are never emitted — DB-only objects are WARN comments.

| Parameter | Type | Description |
|-----------|------|-------------|
| entitySnap | `SchemaSnapshot` |  |
| diff | `SchemaMetaDiffV2` |  |

### `buildVectorSearchQuery(input): SqlQuery`

| Parameter | Type | Description |
|-----------|------|-------------|
| input | `VectorHybridInput` |  |

### `calculateDelta(oldEntity, newEntity): Record<string, { old: unknown; new: unknown }>`

Calculate delta between old and new records for audit.

| Parameter | Type | Description |
|-----------|------|-------------|
| oldEntity | `Record<string, unknown>` |  |
| newEntity | `Record<string, unknown>` |  |

### `calculateDeltaWithForcedFields(oldEntity, newEntity, forceFields): Record<string, { old: unknown; new: unknown }>`

Calculate delta and force include specific fields even when unchanged.

| Parameter | Type | Description |
|-----------|------|-------------|
| oldEntity | `Record<string, unknown>` |  |
| newEntity | `Record<string, unknown>` |  |
| forceFields | `string[]` |  |

### `canonicalJson(value): string`

Stable JSON: object keys sorted recursively so signatures are deterministic.

| Parameter | Type | Description |
|-----------|------|-------------|
| value | `unknown` |  |

### `canonicalPgType(t): string`

Fold alias spellings to canonical names (`integer` → `int4`, …).

| Parameter | Type | Description |
|-----------|------|-------------|
| t | `string` |  |

### `ceil(d): Decimal`

Smallest integer `>= d`.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `checkDrift(registry, db, opts): Promise<SchemaMetaDiffV2>`

| Parameter | Type | Description |
|-----------|------|-------------|
| registry | `readonly EntityClass[]` |  |
| db | `SnapshotQueryable` |  |
| opts | `BuildEntitySnapshotOptions` |  |

### `classifyRenamePair(eMeta, dMeta): { matchTier: number; reasons: string[] } \| null`

Assigns the single strictest tier that applies, or `null` if no rule matches.

| Parameter | Type | Description |
|-----------|------|-------------|
| eMeta | `SchemaColumnMeta` |  |
| dMeta | `SchemaColumnMeta` |  |

### `CloneField(): PropertyDecorator`

Marks a field as clone tracking (cloned_from). Stores UUID of the source record.

### `cmp(a, b): -1 \| 0 \| 1`

Numeric comparison ignoring scale: `cmp(1.0, 1.00) === 0`. Returns -1 | 0 | 1.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `collectEntityTypeWarnings(registry, annotations): EntityTypeWarning[]`

Advisory authoring warnings across a registry — `*_uuid` columns that do
not resolve to `uuid`, and `pgType` declarations that restate the inferred
default. Requires the static annotation map; warnings never fail a gate.

| Parameter | Type | Description |
|-----------|------|-------------|
| registry | `readonly EntityClass[]` |  |
| annotations | `EntityAnnotationMap` |  |

### `Column(sqlName): PropertyDecorator`

Override SQL name / `pgType` / `nullable` only; otherwise the property is already a column by convention.

| Parameter | Type | Description |
|-----------|------|-------------|
| sqlName | `string` |  |

### `columnHintsFromMetaColumn(col): ColumnPgPersistenceHints`

| Parameter | Type | Description |
|-----------|------|-------------|
| col | `{ propertyKey: string; sqlName: string; isKey: boolean; isUnique: boolean; uniqueIndexName: string; uniqueIndexOrder: number; nullable: boolean; pgType: string; jsType: "vector" \| "decimal" \| "instant"; defaultSql: string; length: number; precision: number; scale: number; inferredPgType: string; usePostgresIdentity: boolean; isAuditable: boolean; auditableType: AuditableFieldType; isDeletable: boolean; deletableType: DeletableFieldType; isSynchronizable: boolean; synchronizableType: SynchronizableFieldType; isClone: boolean; castInJoin: string; isPartition: boolean; partitionOpts: PartitionFieldOptions }` |  |

### `columnTypeWarnings(entityName, h, resolved): EntityTypeWarning[]`

Authoring warnings for one column:
- `uuid-name` — a `*_uuid`/`uuid` column resolving to a non-uuid type.
  The name SAYS uuid; either the column should be `uuid` (retype the prop
  to `UUID` or set `pgType:"uuid"`) or the name lies.
- `redundant-pgType` — explicit `pgType` equal to what the annotation
  already infers; drop it (we never spell out the default).

| Parameter | Type | Description |
|-----------|------|-------------|
| entityName | `string` |  |
| h | `EntityColumnTypeHints` |  |
| resolved | `string` |  |

### `comparablePgType(meta): string`

Build a stable string for equality checks across entity hints and catalog introspection.

| Parameter | Type | Description |
|-----------|------|-------------|
| meta | `Pick<SchemaColumnMeta, "typname" \| "typcategory" \| "dataType" \| "formatType">` |  |

### `compareSnapshots(entitySnap, dbSnap): SchemaMetaDiffV2`

| Parameter | Type | Description |
|-----------|------|-------------|
| entitySnap | `SchemaSnapshot` |  |
| dbSnap | `SchemaSnapshot` |  |

### `configureSchemaDomain(schemas, sharedTables): SchemaDomain`

Called once by the Dal constructor. Re-calls replace the domain (tests).

| Parameter | Type | Description |
|-----------|------|-------------|
| schemas | `string[]` |  |
| sharedTables | `string[]` |  |

### `createStream(db, text, values): AsyncIterable<TResult>`

Creates an AsyncIterable from a SQL query using pg-query-stream.

| Parameter | Type | Description |
|-----------|------|-------------|
| db | `Queryable` | The pg Pool or PoolClient |
| text | `string` | SQL query text |
| values | `unknown[]` | Parameter values |

### `dec(input): Decimal`

`Decimal` — pass-through. `string` — parsed (PG text form or `"…d"` wire form). `number` — via shortest round-trip `toString` so `0.1` stays `"0.1"`. `bigint` — scale 0.

| Parameter | Type | Description |
|-----------|------|-------------|
| input | `DecimalInput` |  |

### `decimalToPG(d): string`

PostgreSQL parameter form — plain canonical decimal string, no `d` suffix.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `defaultSearchGate(trimmed): boolean`

search-gate — canonical "should this search query hit the server" predicate.

Mirrors the backend list-search gate: ≥3 "real" characters, or an escaped
wildcard (`\*` / `\?`) with ≥1 real char. Prevents per-keystroke queries
while still allowing single-char wildcard searches.

Canonical home for both the host FE and remote module pages — the gate
must match the server-side rule byte-for-byte.

| Parameter | Type | Description |
|-----------|------|-------------|
| trimmed | `string` | the search string, already `.trim()`ed by the caller |

### `defaultVisibleColumnKeys(columns): string[]`

Keys visible by default — from column flags.

| Parameter | Type | Description |
|-----------|------|-------------|
| columns | `MetaColumn[]` |  |

### `Deletable(Base): { prototype: DeletableEntity<any> } & TBase`

Adds deleted_at / deleted_by — soft-delete markers.

| Parameter | Type | Description |
|-----------|------|-------------|
| Base | `TBase` |  |

### `DeletableField(what): PropertyDecorator`

Marks a field as deletable (deleted_at, deleted_by).

| Parameter | Type | Description |
|-----------|------|-------------|
| what | `DeletableFieldType` |  |

### `diffVendorRequirements(requires, manifest): VendorMismatch[]`

Vendor compatibility check — exact-match policy. A remote chunk compiled
against a different version of a vendored package is incompatible:
`svelte/internal/*` is not a stable API and each union bundle's export set
may change between versions. The remedy is rebuilding the remote chunk —
a semver-tolerant handshake would only defer an opaque import failure.

| Parameter | Type | Description |
|-----------|------|-------------|
| requires | `Record<string, string>` |  |
| manifest | `VendorManifest` |  |

### `div(a, b, opts): Decimal`

`a / b`. Without `scale`, the result uses the PostgreSQL `numeric`
division rule (`pgDivScale` — e.g. `1/3` → scale 20, `10/4` → 16), so
Decimal↔DB computations compare equal digit-for-digit. Rounding defaults
to `HALF_UP`. When the true quotient does not terminate at the target
scale the result is flagged `periodic` (`isPeriodic(d)` → true).

  div(1, 3)            // 0.33333333333333333333 — periodic
  div(10, 4)           // 2.5000000000000000
  div(1, 3, 2)         // 0.33
  div(a, b, &#123; scale: 6, rounding: "HALF_EVEN" &#125;)

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |
| opts | `number \| { scale: number; rounding: RoundingMode }` |  |

### `effectivePgStorageType(h): string`

Effective storage type in PostgreSQL (explicit `pgType` wins over inference).

| Parameter | Type | Description |
|-----------|------|-------------|
| h | `ColumnPgPersistenceHints` |  |

### `Entity(tableName, schema): (ctor: T) => T`

Maps the class to a DB table. Optional argument overrides the table name;
if omitted, the table name equals the class name.

| Parameter | Type | Description |
|-----------|------|-------------|
| tableName | `string` |  |
| schema | `string` |  |

### `entityDateToApiIso(value): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| value | `Date` |  |

### `eq(a, b): boolean`

Numeric equality ignoring scale — `eq(1.0, 1.00)` is `true`.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `extJsonParse(text): T`

Parse an Ext-JSON string.

ALL integers are returned as native `bigint` (via reviver).
Floats (values with decimal point or scientific notation) are `number`.
Strings, booleans, null are unaffected.

| Parameter | Type | Description |
|-----------|------|-------------|
| text | `string` |  |

### `extJsonStringify(data): string`

Serialize a value to an Ext-JSON string.
BigInt values serialize as JSON numbers (42n → "42"); floats stay numbers.

Use for request bodies carrying bigint values — the BE's ext-json body
parser revives them to native `bigint`.

| Parameter | Type | Description |
|-----------|------|-------------|
| data | `unknown` |  |

### `extractEntityAnnotations(entryFile): Promise<EntityAnnotationMap>`

Build the annotation map for every class reachable from `entryFile`
(usually the entity registry module). `compilerOptions` are taken from the
nearest `tsconfig.json` so path aliases resolve correctly.

| Parameter | Type | Description |
|-----------|------|-------------|
| entryFile | `string` |  |

### `field(entity, key): FieldRef<TEntity, K>`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| key | `K` |  |

### `findAuditPage(repo, opts): Promise<AuditPageResult>`

Page through an entity audit table, newest first.
`userEntity` — optional auditable-display-name join target (BE:
`UserProfileEntity`). Without it, display-name columns are null.

| Parameter | Type | Description |
|-----------|------|-------------|
| repo | `AuditQueryable` |  |
| opts | `AuditPageOptions & { userEntity: EntityClass }` |  |

### `findLikelyRenames(schema, table, entityOnly, databaseOnly, entityColumns, databaseColumns): RenameHeuristicResult`

Greedy 1:1 matching: process tiers 0→n, within each tier stable order, no floats.
Uses ordinal indexing to avoid scanning all DB-only columns for every entity-only column.

| Parameter | Type | Description |
|-----------|------|-------------|
| schema | `string` |  |
| table | `string` |  |
| entityOnly | `string[]` |  |
| databaseOnly | `string[]` |  |
| entityColumns | `Record<string, SchemaColumnMeta>` |  |
| databaseColumns | `Record<string, SchemaColumnMeta>` |  |

### `floor(d): Decimal`

Largest integer `<= d`.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `ForeignKey(target, opts): PropertyDecorator`

Declares a FOREIGN KEY constraint referencing another entity's column.
`target` is a lazy thunk (`() => CustomerEntity`) so circular entity
references resolve at meta-read time, not class-eval time.
Minimal form `@ForeignKey(() => CustomerEntity)` references the target's
`@Key()` column with `ON DELETE RESTRICT` / `ON UPDATE NO ACTION` —
the zero-option path is the safest behavior.
Note: a partitioned parent (`@PartitionField`) cannot be a plain FK target
unless the referenced unique constraint includes the partition key —
meta validation throws and points to `@PartitionChildOf` for that shape.

| Parameter | Type | Description |
|-----------|------|-------------|
| target | `() => EntityClass` |  |
| opts | `ForeignKeyOptions` |  |

### `fromBigInt(v, scale): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `bigint` |  |
| scale | `number` |  |

### `fromNumber(n): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| n | `number` |  |

### `getColumnName(ctor, propertyKey): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| ctor | `EntityClass` |  |
| propertyKey | `string \| symbol` |  |

### `getDal(config): Dal`

Returns the process-wide singleton Dal instance. Creates it on first call.

- First call: requires `config`, creates the singleton.
- Subsequent calls with NO config: returns the existing instance.
- Subsequent calls with the SAME connectionString: returns the existing instance.
- Subsequent calls with a DIFFERENT connectionString: throws (prevents accidental
  double-init with wrong params).

For multi-DB: construct `new Dal(config)` directly (bypasses the singleton).

| Parameter | Type | Description |
|-----------|------|-------------|
| config | `DalConfig` |  |

### `getEntityName(ctor): string`

Logical entity name: the class name (e.g. `CustomerEntity`).

| Parameter | Type | Description |
|-----------|------|-------------|
| ctor | `EntityClass` |  |

### `getEntityPersistenceMeta(ctor, tableSchema): EntityPersistenceMeta`

Snapshot fragment for one

| Parameter | Type | Description |
|-----------|------|-------------|
| ctor | `EntityClass` |  |
| tableSchema | `string` |  |

### `getOperatorsForColumnType(columnType): FilterOperator[]`

Operators available for a given column UI type.

| Parameter | Type | Description |
|-----------|------|-------------|
| columnType | `string` |  |

### `getPrimaryKeyColumn(ctor): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| ctor | `EntityClass` |  |

### `getQualifiedTableName(ctor): string`

Returns a schema-qualified table reference for SQL generation.
When the entity has an explicit @Entity("table", "schema") override,
returns `"schema"."table"`. Otherwise returns just `"table"` (relies on search_path).

| Parameter | Type | Description |
|-----------|------|-------------|
| ctor | `EntityClass` |  |

### `getSchemaDomain(): SchemaDomain \| null`

### `getTableName(ctor): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| ctor | `EntityClass` |  |

### `hydrateEntityDateFieldsFromJson(instance, meta): void`

After `Object.assign` from JSON, restore column-typed values on the
entity: `instant` → `Date`, `decimal` → `Decimal` (wire `"N.Nd"` or a
bare numeric string), `vector` → `Vector`.

| Parameter | Type | Description |
|-----------|------|-------------|
| instance | `T` |  |
| meta | `EntityPersistenceMeta` |  |

### `Index(): PropertyDecorator`

Declares a secondary (non-unique) index. Bare `@Index()` → single-column
btree auto-named `<table>_<col>_idx`. Same `name` on multiple columns →
composite index ordered by `order`. Supports every PG access method:
`@Index({ using: 'hnsw', opclass: 'vector_cosine_ops' })`,
`@Index({ where: 'deleted_at IS NULL' })` for partial indexes.
Unique indexes stay on `@Unique()`.

### `isDecimal(v): v is Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `unknown` |  |

### `isDriftClean(diff): boolean`

True when the diff contains only database-only objects (extras we never
drop) — i.e. no unapplied entity intent remains.

| Parameter | Type | Description |
|-----------|------|-------------|
| diff | `SchemaMetaDiffV2` |  |

### `isEntityClass(value): value is EntityClass`

| Parameter | Type | Description |
|-----------|------|-------------|
| value | `unknown` |  |

### `isEntityOpEnabled(actions, op): boolean`

Pure enablement check — true when `op` exists in the served `actions`
array and carries `enabled: true`. FAIL-CLOSED: when `actions` is absent
(meta without actions — contract violation) the op is not enabled.

This deliberately does NOT evaluate user permissions — that step lives in
the consumer (e.g. FE `isEntityOpAllowed` composes this with the session
permission check).

| Parameter | Type | Description |
|-----------|------|-------------|
| actions | `readonly EntityAction[] \| undefined` |  |
| op | `string` |  |

### `isISODate(v): v is ISODate`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `unknown` |  |

### `isISOTime(v): v is ISOTime`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `unknown` |  |

### `isLogicalJsDateColumn(h): boolean`

Column carries a `Date`-valued property — an audit/deletable/sync `*_AT`
field, an `instant` codec hint, or an explicit timestamptz/timestamp
pgType. `date`/`time`/`timetz` columns are `ISODate`/`ISOTime` strings —
NOT Dates — by contract.

| Parameter | Type | Description |
|-----------|------|-------------|
| h | `ColumnPgPersistenceHints` |  |

### `IsNotColumn(): PropertyDecorator`

Excludes the property from meta schema / migration and from future DAL queries.

### `isoDateFromUTCDate(d): ISODate`

`Date` → `ISODate` using the date's UTC calendar day.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `Date` |  |

### `isPeriodic(d): boolean`

`true` when the value was produced by a truncated non-terminating division.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `isSnakeCaseSingular(value): value is SnakeCaseSingular`

Runtime validator for SnakeCaseSingular — rejects strings with
 uppercase letters. Use in meta-loading code to catch BE meta that
 violates the convention.

| Parameter | Type | Description |
|-----------|------|-------------|
| value | `string` |  |

### `isUUID(v): v is UUID`

Type guard — validates RFC 4122 layout (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, hex).

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `unknown` |  |

### `jsValueToPgParam(value, h): unknown`

Value to pass to `node-pg` query parameters.
`Date` → passthrough (timestamptz) or `YYYY-MM-DD` (SQL `date`);
`Decimal` → plain numeric string; `Vector`/`number[]` → `'[…]'` literal;
jsonb payloads → JSON string (nested bigint → number — jsonb numerics are
doubles anyway and BigInt breaks JSON.stringify).

| Parameter | Type | Description |
|-----------|------|-------------|
| value | `unknown` |  |
| h | `ColumnPgPersistenceHints` |  |

### `Key(): PropertyDecorator`

Marks the single-column primary key.

### `keyNamespaceOf(key): string \| null`

First dotted segment of a translation key — `job.entities.x` → `job`.

| Parameter | Type | Description |
|-----------|------|-------------|
| key | `string` |  |

### `listEntityPersistencePropertyKeys(ctor): string[]`

Property keys that map to SQL columns (implicit + decorated).

| Parameter | Type | Description |
|-----------|------|-------------|
| ctor | `EntityClass` |  |

### `loadKeyring(keysPath): TrustedKey[]`

| Parameter | Type | Description |
|-----------|------|-------------|
| keysPath | `string` |  |

### `loadManifest(manifestPath): PatchManifest \| null`

| Parameter | Type | Description |
|-----------|------|-------------|
| manifestPath | `string` |  |

### `lookupEntityAnnotation(map, className, prop): EntityAnnotationInfo \| undefined`

Walk the `extends` chain (subclass first — wins on conflicts, matching the
decorator-merge semantics of `getEntityPersistenceMeta`). Returns the
annotation info for `prop` on `className`, or `undefined` when the chain
declares no such property.

| Parameter | Type | Description |
|-----------|------|-------------|
| map | `EntityAnnotationMap` |  |
| className | `string` |  |
| prop | `string` |  |

### `makeEntityService(cfg): EntityService<TEntity>`

| Parameter | Type | Description |
|-----------|------|-------------|
| cfg | `EntityServiceConfig<TEntity>` |  |

### `makeTableAuditPort(repo): AuditPort`

`makeTableAuditPort` — writes audit log rows to `{tableName}_audit` via the
given repository. This is the service-side counterpart of the BE's
`EntityAuditPort`, minus the Redis/NATS entity-changed markers (those
belong to gateway collaboration infra). The audit row write itself is
always performed.

| Parameter | Type | Description |
|-----------|------|-------------|
| repo | `Repository` |  |

### `manifestPaths(dbMetaDir): { manifestPath: string; keysPath: string }`

Resolve manifest + keyring paths for a service's db-meta dir.

| Parameter | Type | Description |
|-----------|------|-------------|
| dbMetaDir | `string` |  |

### `max(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `min(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `mod(a, b): Decimal`

`a mod b` — remainder of truncated division at the common scale.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `mul(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `neg(d): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `normalize(d): Decimal`

Strip trailing fractional zeros — `1.230` → `1.23`, `12.000` → `12`.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `normalizePatchEol(body): string`

Patch integrity hashes are EOL-insensitive: a Windows checkout may
materialize CRLF while the committed blob and the signed MANIFEST are LF.
Normalize before hashing so manifest verification and the patch registry
are platform-stable.

| Parameter | Type | Description |
|-----------|------|-------------|
| body | `string` |  |

### `orderedColumns(columns): MetaColumn[]`

Columns in display order: sticky group → normal group → audited group,
each sorted by `order`.

| Parameter | Type | Description |
|-----------|------|-------------|
| columns | `readonly MetaColumn[] \| null \| undefined` |  |

### `parseDecimal(input): Decimal`

Parse a decimal string into unscaled form.
Accepts: `"12"`, `"-0.5"`, `".5"`, `"5."`, `"1.5e3"`, `"1E-3"`, `"+4"`.
Rejects: `NaN`, `Infinity`, empty strings, hex, non-numeric garbage.
Scale is preserved as written (`"1.230"` → scale 3).

| Parameter | Type | Description |
|-----------|------|-------------|
| input | `string` |  |

### `parsePatchPragmas(raw): { requiresReview: boolean; noTransaction: boolean }`

Parse the `-- pb:*` pragma header of a patch file.

| Parameter | Type | Description |
|-----------|------|-------------|
| raw | `string` |  |

### `parsePatchSegments(raw): PatchSegment[]`

Split a patch file into execution segments. Default content is transactional
(`tx`); statements inside `-- pb:begin-no-transaction` … `-- pb:end-no-transaction`
run per-statement in autocommit (for CREATE INDEX CONCURRENTLY & friends).
Whole-file `-- pb:no-transaction` is equivalent to wrapping everything.

| Parameter | Type | Description |
|-----------|------|-------------|
| raw | `string` |  |

### `PartitionChildOf(opts): ClassDecorator`

Declares this entity a logical child of a `@PartitionField`-partitioned
parent: it joins the parent's atomic delete and retention purge unit.
Needed because a partitioned parent cannot host a plain FOREIGN KEY
(unique constraints must contain the partition key) — the relationship
is application-level, enforced by the repository cascade and the
partition-maintenance purge. Entities that merely REFERENCE a parent
(telemetry, logs) simply don't declare this.

| Parameter | Type | Description |
|-----------|------|-------------|
| opts | `PartitionChildOfOptions` |  |

### `PartitionField(opts): PropertyDecorator`

Marks a column as the RANGE partition key of the table (pg_partman,
monthly/daily/…). Exactly ONE per entity. The column must be NOT NULL and
date/timestamptz-typed; every unique group and the primary key emitted in
DDL must include it (PostgreSQL requirement) — `getEntityPersistenceMeta`
validates this and throws otherwise, so a partitioned entity can never
produce an invalid table definition.

| Parameter | Type | Description |
|-----------|------|-------------|
| opts | `PartitionFieldOptions` |  |

### `patchNameFromFilename(filename): string`

The registry identity of a patch is its filename minus the `.sql` extension.

| Parameter | Type | Description |
|-----------|------|-------------|
| filename | `string` |  |

### `patchRegistryDdl(schema): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| schema | `string` |  |

### `patchSlugFromDiff(diff): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| diff | `SchemaMetaDiffV2` |  |

### `pgDivScale(a, b): number`

PostgreSQL-faithful result scale for `x / y` (mirrors `select_div_scale`):
`max(16 - 4·qweight, x.scale, y.scale)` — 16 significant digits minimum.
Verified live: `1/3`→20, `10/4`→16, `1.00/8`→20, `2/1`→16, `100/3`→16.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `pgTypeFromAnnotation(a): string \| null`

Annotation → base pg type. Returns `null` for unmappable annotations —
the caller decides whether that's an error (schema pipeline) or a
non-authoritative runtime hint.

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `EntityAnnotationInfo` |  |

### `pgValueToJsValue(value, h): unknown`

Normalise a driver value into the entity-side type: `Date` for date-like
columns, `Decimal` for numeric columns, `Vector` for vector columns.
Driver-native shapes (pg already returns `Date`/`bigint`/arrays) pass
through unchanged.

| Parameter | Type | Description |
|-----------|------|-------------|
| value | `unknown` |  |
| h | `ColumnPgPersistenceHints` |  |

### `pow10(n): bigint`

| Parameter | Type | Description |
|-----------|------|-------------|
| n | `number` |  |

### `quoteIdent(ident): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| ident | `string` |  |

### `registryStatus(pool, schema): Promise<PatchRegistryRow[]>`

| Parameter | Type | Description |
|-----------|------|-------------|
| pool | `Pool` |  |
| schema | `string` |  |

### `rescale(d, newScale, mode): Decimal`

Re-express `d` at `newScale`. Growing is exact; shrinking applies `mode`
(default `HALF_UP`, matching PostgreSQL `round()`).

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |
| newScale | `number` |  |
| mode | `RoundingMode` |  |

### `resetDal(): Promise<void>`

Resets the singleton. Closes the existing instance if any.
Intended for tests — call in afterAll to release the pool.

### `resetSchemaDomain(): void`

Test hook — clears the configured domain.

### `resolveEntitySchema(meta, fallback): string`

Resolve the effective schema of an entity: the explicit

| Parameter | Type | Description |
|-----------|------|-------------|
| meta | `{ tableSchema: string; tableName: string }` |  |
| fallback | `string` |  |

### `resolveManually(pool, schema, patchName, actor, note): Promise<boolean>`

Operator escape hatch: mark a failed/pending patch as manually resolved.

| Parameter | Type | Description |
|-----------|------|-------------|
| pool | `Pool` |  |
| schema | `string` |  |
| patchName | `string` |  |
| actor | `string` |  |
| note | `string` |  |

### `resolvePgTypeForSchema(h): string`

Authoritative resolve for the schema pipeline: explicit `pgType`, else
semantic decorator pin, else annotation inference. Throws when none can
produce a type — an unmappable entity property must never silently
become `text`.

| Parameter | Type | Description |
|-----------|------|-------------|
| h | `EntityColumnTypeHints` |  |

### `resolvePresetConditions(presets, selections): FilterCondition[]`

Flatten the WHERE conditions of every preset's ACTIVE option — the
conditions AND-ed into every `/list` call. `selections` maps
preset.id → option id; invalid/absent ids resolve per
resolvePresetSelection.

| Parameter | Type | Description |
|-----------|------|-------------|
| presets | `readonly FilterPreset[] \| undefined` |  |
| selections | `Record<string, string>` |  |

### `resolvePresetSelection(preset, selected): string`

Resolve a preset's active option id — the caller-provided selection when
it names a declared option, otherwise `default_option` (itself falling
back to the first option when misconfigured, keeping the always-one
invariant rather than failing closed).

| Parameter | Type | Description |
|-----------|------|-------------|
| preset | `FilterPreset` |  |
| selected | `string \| undefined` |  |

### `resolveVendorSpecifier(specifier): VendorResolution`

How a remote chunk's bundler must treat a bare import specifier. Both the
host vendor build and every module chunk build derive behavior from this
single function so the plane stays deterministic.

| Parameter | Type | Description |
|-----------|------|-------------|
| specifier | `string` |  |

### `retryFailedPatches(pool, schema, actor): Promise<number>`

failed → pending: next runMigrations retries them (and past them, in order).

| Parameter | Type | Description |
|-----------|------|-------------|
| pool | `Pool` |  |
| schema | `string` |  |
| actor | `string` |  |

### `round(d, scale, mode): Decimal`

Round to `scale` fractional digits (default `HALF_UP`).

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |
| scale | `number` |  |
| mode | `RoundingMode` |  |

### `runMigrations(opts): Promise<MigrationRunResult>`

| Parameter | Type | Description |
|-----------|------|-------------|
| opts | `MigrationEngineOptions` |  |

### `runPartitionMaintenance(client, entities): Promise<PartitionMaintenanceReport>`

| Parameter | Type | Description |
|-----------|------|-------------|
| client | `PoolClient` |  |
| entities | `readonly EntityClass[]` |  |

### `sanitizeVisibleKeys(visibleKeys, columns): string[]`

Drop unknown keys and fall back to defaults when nothing left.

| Parameter | Type | Description |
|-----------|------|-------------|
| visibleKeys | `string[]` |  |
| columns | `MetaColumn[]` |  |

### `searchableTextColumns(columns): MetaColumn[]`

Text-physical searchable columns — the scope selector + default
 "all fields" search set.

| Parameter | Type | Description |
|-----------|------|-------------|
| columns | `MetaColumn[]` |  |

### `serviceApiBase(listBasePath): string`

Service API base of an entity list basePath — strips the trailing
`/entities/<entity>` segment so service-relative endpoints declared in
meta (e.g. sparkline `endpoint: "/actions/job-run-stats"`) resolve to
`/ws/<svc>/api/v1/actions/…` or `/api/v1/actions/…` for BE entities.

| Parameter | Type | Description |
|-----------|------|-------------|
| listBasePath | `string` |  |

### `sha256Hex(body): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| body | `string` |  |

### `signManifest(manifest, privateKeyB64): PatchManifest`

Sign a manifest body (entries already updated) with a PEM/DER private key.

| Parameter | Type | Description |
|-----------|------|-------------|
| manifest | `Omit<PatchManifest, "signature">` |  |
| privateKeyB64 | `string` |  |

### `signum(d): -1 \| 0 \| 1`

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `slugifyPatchSegment(s): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| s | `string` |  |

### `specifierTopPackage(specifier): string`

Top-level npm package of a specifier ('svelte/internal/client' → 'svelte').

| Parameter | Type | Description |
|-----------|------|-------------|
| specifier | `string` |  |

### `splitSqlStatements(sql): string[]`

Top-level SQL statement splitter for `-- pb:no-transaction` segments.

Needed because node-pg's simple query protocol executes a multi-statement
string in a single implicit transaction — to get per-statement autocommit
(required for CREATE INDEX CONCURRENTLY etc.) statements must be sent
separately. Handles: single/double-quoted strings, dollar-quoted bodies
($$…$$, $tag$…$tag$), line comments, block comments.

| Parameter | Type | Description |
|-----------|------|-------------|
| sql | `string` |  |

### `strictEq(a, b): boolean`

Exact structural equality — value AND scale must match (`strictEq(1.0, 1.00)` is `false`).

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `sub(a, b): Decimal`

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `DecimalInput` |  |
| b | `DecimalInput` |  |

### `SynchronizableField(what): PropertyDecorator`

Marks a field as synchronizable (last_synced_at).

| Parameter | Type | Description |
|-----------|------|-------------|
| what | `SynchronizableFieldType` |  |

### `syncImplicitEntityColumns(ctor): void`

Registers every implicit column + `design:type` / nullability when not already set by decorators.

| Parameter | Type | Description |
|-----------|------|-------------|
| ctor | `Function` |  |

### `tableKey(schema, name): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| schema | `string` |  |
| name | `string` |  |

### `toISODate(v): ISODate`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `string` |  |

### `toISOTime(v): ISOTime`

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `string` |  |

### `toUUID(v): UUID`

Validating constructor — throws on malformed input. Use at system boundaries (request bodies, env, user input).

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `string` |  |

### `toWire(d): string`

Wire form — `"…d"` suffixed string.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `translateFilterConditions(entity, conditions, options): FilterExpr[] \| null`

| Parameter | Type | Description |
|-----------|------|-------------|
| entity | `EntityClass` |  |
| conditions | `ListFilterCondition[] \| null \| undefined` |  |
| options | `ListFilterOptions` |  |

### `translationKeyNamespace(schema): string`

Owning PG schema → the only translation-key namespace writable there.

| Parameter | Type | Description |
|-----------|------|-------------|
| schema | `string` |  |

### `trunc(d): Decimal`

Integer part, toward zero.

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `DecimalInput` |  |

### `trustedISODate(v): ISODate`

Zero-cost cast for trusted sources (DB rows).

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `string` |  |

### `trustedISOTime(v): ISOTime`

Zero-cost cast for trusted sources (DB rows).

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `string` |  |

### `trustedUUID(v): UUID`

Zero-cost cast for trusted sources (DB rows, values already validated upstream). Named explicitly so reviews can spot it.

| Parameter | Type | Description |
|-----------|------|-------------|
| v | `string` |  |

### `typesCompatibleForRename(a, b): boolean`

True if two metas are “same enough” for rename pairing (not for strict migration).

| Parameter | Type | Description |
|-----------|------|-------------|
| a | `SchemaColumnMeta` |  |
| b | `SchemaColumnMeta` |  |

### `Unique(): PropertyDecorator`

Unique constraint (PostgreSQL: unique index in generated patches).

### `utcTimestampForFilename(d): string`

| Parameter | Type | Description |
|-----------|------|-------------|
| d | `Date` |  |

### `verifyManifest(manifest, keyring, allowedTrust): TrustedKey`

Verify manifest signature against the keyring (filtered by allowed trust levels).

| Parameter | Type | Description |
|-----------|------|-------------|
| manifest | `PatchManifest` |  |
| keyring | `TrustedKey[]` |  |
| allowedTrust | `readonly "release" \| "dev"[]` |  |

### `writeManifest(manifestPath, manifest): void`

Write manifest (used by compare/sign tooling).

| Parameter | Type | Description |
|-----------|------|-------------|
| manifestPath | `string` |  |
| manifest | `PatchManifest` |  |

<!-- END -->