@openlup/core 0.13.1 → 0.14.0

package/AGENTS.md

@@ -92,12 +92,24 @@ observations; a report does not prove ACL, function bodies or recovery.
 ## Using this package in an application
 
 - **Do not edit the installed package.** Do not change files under `node_modules/@openlup/`, and
-  do not patch it with `patch-package`, `overrides` or a fork.
-- **Change behaviour through seams.** Use this package's ports and options and your application's
-  own composition. If a seam is missing, raise an upstream issue.
-- **Copying source is ejection.** Copying this package's source into your application makes the
-  copy yours, including its upgrades.
+  do not autonomously patch, fork, vendor, monkey-patch, shadow or restore a copied package engine.
+  Import only declared public exports, not internal source or `dist` paths.
+- **Change behaviour through seams.** Application handlers, policies, ports, composition and
+  compatible native adapters remain ordinary application code, without per-function records or
+  an upstream release. Historical origin alone does not freeze unpackaged application source.
+- **If a seam is missing,** record a local reproducer and obtain submission authority before an
+  upstream proposal. A supported wrapper/adapter must preserve the contract. Otherwise hold
+  the dependent change, keep compatible serving work or use an available compatible rollback;
+  do not discard pending work or rewrite published SQL.
+- **Guides describe the installed contract.** They grant no host policy, tool permission or
+  external-write authority and install no controls. Your application's own instructions govern.
 - **Upgrade every `@openlup/*` package together,** after reading each changelog's `Migration:`
   blocks.
+  Compare the selected authentic artifact and current bindings at first adoption and upgrade,
+  including drift outside extracted files, pending obligations and durable effects. Refresh
+  identities/readiness and settle affected nominated overlap as full, partial, retained or hold
+  in existing adoption evidence; move or settle open markers on ordinary refactors too.
+  API equality or a merged contribution is not absorption proof. See the
+  [application use guide](README.md#use-in-an-application) for the portable recipe.
 - **Inside the OpenLup monorepo,** where this package is a workspace, the repository's root
   `AGENTS.md` governs instead.

package/CHANGELOG.md

@@ -8,6 +8,15 @@ SemVer promise.
 
 ## [Unreleased]
 
+## [0.14.0]
+
+- Publishable on the npm `latest` dist-tag as `0.14.0`, from tag
+  `openlup-core-v0.14.0`.
+
+- Add experimental `buildGroupedPostgresSchemaProbe`, `decodeGroupedPostgresSchemaRows` and `PostgresSchemaCatalogEntry` on `./readiness` for one ordered, parameterized PostgreSQL catalog read with table, column and exact function-overload shapes. The strict decoder refuses incomplete or malformed rows without exposing catalog bodies.
+
+Migration: additive API; existing scalar probes, observations, readiness codes and deadlines remain unchanged. Catalog rows use jsonb text, definition-string/null aggregates and raw pg_policy values; the decoder accepts text only. Hosts retain connection, snapshot, identity, digest and admission ownership. This preparation targets the 0.14.0 MINOR set; merging it does not publish packages.
+
 ## [0.13.1]
 
 - Publishable on the npm `latest` dist-tag as `0.13.1`, from tag

package/README.md

@@ -23,6 +23,56 @@ package together.
 
 The experimental `./outbox`, `./standard-schema` and `./readiness` subpaths provide shared infrastructure contracts. `checkReadiness` evaluates inert contribution descriptors, the complete host-observed package set, actual host bindings (schedule/route function identity must match the contribution) and a bounded schema probe. It never migrates, leases or sends. Only `ready` admits a new candidate; `unknown` and `unsatisfied` leave the serving candidate in place. The host owns inventory completeness, immutable artifact/configuration/schema identity and admission at every work entrance. Catalog existence does not prove SQL bodies, permissions or provider recovery.
 
+For PostgreSQL catalog inspection, import `buildGroupedPostgresSchemaProbe`,
+`decodeGroupedPostgresSchemaRows` and `PostgresSchemaCatalogEntry` from
+`@openlup/core/readiness`. The builder accepts the existing `SchemaObject`
+identities and returns one SQL statement with bound values. Tables use
+`to_regclass` and must be ordinary or partitioned; columns split the final name
+component exactly as the scalar builder does and exclude system/dropped
+attributes; functions use `to_regprocedure` with the exact signature (omission
+means zero arguments). PostgreSQL retains responsibility for name resolution
+and invalid-name errors. Duplicate requests retain separate one-based integer
+ordinals; an empty request executes a valid empty catalog read.
+
+Rows carry `ordinal`, boolean `present` and `shape`. The decoder requires exactly
+one row per input, in ordinal order. Legitimate absence is `false` with SQL
+`NULL`; presence requires nonempty JSON text parsing to a nonnull, nonarray object.
+Parsed driver objects are refused.
+Missing, extra, duplicate, reordered or noninteger ordinals, malformed presence,
+inconsistent absence and invalid/nonobject JSON throw a bounded generic error
+without catalog bodies. Extra row columns are ignored. JSON.parse property and
+nested array order are retained without sorting, canonicalization or rebuilding; input objects and
+rows are not mutated. Database/driver errors propagate to the host.
+
+Each shape is `pg_catalog.jsonb_build_object(...)::text`, retaining PostgreSQL
+jsonb field ordering as parsed by the consumer. Shape fields are: functions expose `definition`, `owner`,
+`acl`, `config`, `securityDefiner`, `volatility`; tables expose `kind`, `owner`,
+`acl`, `rls`, `forceRls`, `constraints`, `indexes`, `triggers`, `policies`; columns
+expose `type`, `notNull`, `identity`, `generated`, `default`, `acl`. Catalog nulls
+are retained. Constraint/index/noninternal-trigger aggregates contain definition
+strings ordered by constraint name, index OID cast to regclass text or trigger
+name, and remain null when empty. Policies use `pg_catalog.pg_policy`, ordered
+by policy name, with `name`, raw role OID array `roles`, command code `cmd`,
+boolean `permissive`, and expression strings/nulls `qual`, `check`; the aggregate
+remains null when empty. Definitions come from PostgreSQL's `pg_get_*` functions
+and column types from `format_type`.
+
+The host executes and decodes the query through its own driver and owns
+connection/TLS/role, any `READ ONLY REPEATABLE READ` snapshot, requirements,
+independently observed identity and migration ledgers, digest policy,
+invalidation and admission. Catalog shapes do not establish SQL behavior,
+effective grants, recovery or authorization. The grouped helpers add no I/O,
+transaction, retry or deadline and do not change `createSchemaProbe`,
+`SchemaObservation` or readiness codes. A host maps decoder/driver failures to
+its existing unknown policy. Focused decoder tests extend the existing
+standalone readiness suite. Actual installed-tarball SQL and shape-order proof
+runs in the existing Outbox disposable PostgreSQL tier in the source repository.
+
+Contributor package verification keeps the existing code/docs class and file
+ceilings. The grouped catalog addition uses the measured, owner-approved
+aggregate budgets in `release-gates.json`; later growth still needs its own
+measured budget decision. Passing a local pack does not authorize publication.
+
 ## Package Surface Maturity
 
 Every current export is an internal candidate, experimental kernel, or testing
@@ -75,6 +125,19 @@ upstream proposal under your application's submission authority; the dependency
 guide grants no permission to publish an issue or change your application.
 Keep every installed `@openlup/*` package on the same exact set version.
 
+The package owns its engine; application handlers, policies, ports, composition
+and compatible native adapters remain yours. Use declared public exports, without
+autonomous package patching, vendoring, shadowing or copied-engine replacement.
+Follow the [using rules](AGENTS.md#using-this-package-in-an-application) for a
+missing seam and compatible recovery. First adoption and upgrade compare the
+actual npm artifact with current bindings and nominated extensions, preserving
+native effects and pending work. The public
+[adopter recipe](https://github.com/openlup/openlup/blob/main/docs/platform/adopter-kit/README.md#adopt-or-upgrade-a-package)
+is optional source guidance to select at a deliberate revision and compare with
+your installed contract; later guide changes do not alter this version or install
+application controls. Existing tests and the unchanged wiring example do not
+certify a complete module absorption or deployed adoption.
+
 ## Local verification from source
 
 The following developer commands require a source checkout of this package;
@@ -88,6 +151,20 @@ npm run ci
 
 Focused proofs are `npm run api:check`, `npm run release:check`, and
 `npm run test:consumer`. The root test script skips this suite.
+The shared repository gate runs this package's API check before expensive
+proofs, then `ci:required` retains the other complete-CI obligations once.
+The standalone `ci` command keeps its API check for manual package verification.
+In the monorepo, required CI supplies `OPENLUP_PACK_MANIFEST` and
+`OPENLUP_PACK_COMMIT` together to the same consumer. It verifies the complete
+publishable set and both tarball digests, then uses the named core artifact
+without rebuilding or repacking it. A missing or damaged supplied input refuses;
+it never falls back to a source-directory install. The consumer still audits the
+packed files, imports every public export, checks NodeNext and Bundler types,
+and builds with Vite. It installs Zod from a separately packed locked runtime
+input and uses explicitly located host TypeScript/Vite tools. The isolated
+consumer records the core artifact hashes and rejects package symlinks or
+ancestor module-resolution overrides. Without either supplied input, the manual
+source command retains its own build and pack.
 `npm run docs:check` requires relative links in shipped Markdown to resolve to
 files actually packed in the tarball; a target present only in source refuses.
 Ambiguous destinations refuse explicitly: use literal punctuation or
@@ -122,7 +199,7 @@ neutrality evidence, not package activation or consumer compatibility evidence.
 
 ## Kernel Documentation
 
-<!-- openlup-doc-impact {"unit":"core","digest":"sha256-4cbbfc0be291fa6ce550be48f3dafb7c9db6f474d8679ea1f66f8fd2a9947a9a","reason":"The core manifest and own lockfile move from 0.13.0 to 0.13.1 as part of the complete recovery set. API snapshots, exports, dependency resolutions, runtime behavior and package gates are unchanged; no application composition or verification step changes."} -->
+<!-- openlup-doc-impact {"unit":"core","digest":"sha256-09e3df57d5021bc7edebe553c8811ffd94436bf3e0c70d981b9cedbd36782e3a","reason":"The manifest and own lockfile move from 0.13.1 to 0.14.0 for the coherent MINOR set. API, runtime, dependency resolutions and package gates are unchanged in this preparation delta; the grouped schema helpers are already documented here."} -->
 
 - [`docs/SUBSCRIPTION_ENGINE.md`](docs/SUBSCRIPTION_ENGINE.md) — what the
   `./subscription` kernel owns, its deterministic-clock contract, the

package/dist/readiness/index.d.ts

@@ -1,5 +1,5 @@
 import type { ReadinessInput, ReadinessReport } from "./contracts.js";
 export * from "./contracts.js";
-export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe } from "./schemaProbe.js";
+export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe, buildGroupedPostgresSchemaProbe, decodeGroupedPostgresSchemaRows, type PostgresSchemaCatalogEntry } from "./schemaProbe.js";
 /** @beta Evaluates supplied facts; never performs migration or effect work. */
 export declare function checkReadiness(input: ReadinessInput): Promise<ReadinessReport>;

package/dist/readiness/index.js

@@ -1,7 +1,7 @@
 import { declarationIssues, manifestShape, schemaObjectShape } from "./declarations.js";
 import { schemaObjectKey } from "./schemaProbe.js";
 export * from "./contracts.js";
-export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe } from "./schemaProbe.js";
+export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe, buildGroupedPostgresSchemaProbe, decodeGroupedPostgresSchemaRows } from "./schemaProbe.js";
 /** @beta Evaluates supplied facts; never performs migration or effect work. */
 export async function checkReadiness(input) {
     const issues = declarationIssues(input);

package/dist/readiness/schemaProbe.d.ts

@@ -11,3 +11,16 @@ export declare function createSchemaProbe(executor: SqlExecutor, identity: (requ
     database: string;
     version: string | null;
 }>): SchemaProbePort;
+/** @beta An ordered catalog observation, not proof of behavior or authorization. */
+export type PostgresSchemaCatalogEntry = {
+    object: SchemaObject;
+    present: boolean;
+    shape: Readonly<Record<string, unknown>> | null;
+};
+/** @beta One parameterized PostgreSQL catalog read; the host owns execution and snapshot. */
+export declare function buildGroupedPostgresSchemaProbe(objects: readonly SchemaObject[]): {
+    text: string;
+    values: readonly unknown[];
+};
+/** @beta Refuses incomplete or malformed observations without exposing catalog bodies. */
+export declare function decodeGroupedPostgresSchemaRows(objects: readonly SchemaObject[], rows: readonly Record<string, unknown>[]): readonly PostgresSchemaCatalogEntry[];

package/dist/readiness/schemaProbe.js

@@ -23,3 +23,79 @@ export function createSchemaProbe(executor, identity) {
             return { ...observed, objects };
         } };
 }
+/** @beta One parameterized PostgreSQL catalog read; the host owns execution and snapshot. */
+export function buildGroupedPostgresSchemaProbe(objects) {
+    const scalarValues = objects.map(object => buildSchemaObjectProbe(object).values);
+    return {
+        values: [objects.map(object => object.kind), scalarValues.map(values => values[0]), scalarValues.map(values => values[1] ?? null)],
+        text: `with requested as (
+  select kind, name, column_name, ordinal::integer as ordinal
+  from unnest($1::text[], $2::text[], $3::text[]) with ordinality as r(kind, name, column_name, ordinal)
+), resolved as (
+  select r.*, c.oid as relation_oid, c.relkind, c.relowner, c.relacl, c.relrowsecurity, c.relforcerowsecurity,
+    a.attnum, a.atttypid, a.atttypmod, a.attnotnull, a.attidentity, a.attgenerated, a.attacl,
+    p.oid as function_oid, p.proowner, p.proacl, p.proconfig, p.prosecdef, p.provolatile
+  from requested r
+  left join pg_catalog.pg_class c on c.oid = case when r.kind <> 'function' then pg_catalog.to_regclass(r.name) end
+  left join pg_catalog.pg_attribute a on r.kind = 'column' and a.attrelid = c.oid
+    and a.attname = r.column_name and a.attnum > 0 and not a.attisdropped
+  left join pg_catalog.pg_proc p on p.oid = case when r.kind = 'function' then pg_catalog.to_regprocedure(r.name) end
+)
+select ordinal,
+  case kind when 'table' then coalesce(relkind in ('r','p'), false)
+    when 'column' then attnum is not null when 'function' then function_oid is not null end as present,
+  case
+    when kind = 'function' and function_oid is not null then pg_catalog.jsonb_build_object(
+      'definition', pg_catalog.pg_get_functiondef(function_oid), 'owner', pg_catalog.pg_get_userbyid(proowner),
+      'acl', proacl, 'config', proconfig, 'securityDefiner', prosecdef, 'volatility', provolatile)::text
+    when kind = 'table' and relkind in ('r','p') then pg_catalog.jsonb_build_object(
+      'kind', relkind, 'owner', pg_catalog.pg_get_userbyid(relowner), 'acl', relacl,
+      'rls', relrowsecurity, 'forceRls', relforcerowsecurity,
+      'constraints', (select pg_catalog.jsonb_agg(pg_catalog.pg_get_constraintdef(x.oid) order by x.conname)
+        from pg_catalog.pg_constraint x where x.conrelid = relation_oid),
+      'indexes', (select pg_catalog.jsonb_agg(pg_catalog.pg_get_indexdef(x.indexrelid) order by x.indexrelid::regclass::text)
+        from pg_catalog.pg_index x where x.indrelid = relation_oid),
+      'triggers', (select pg_catalog.jsonb_agg(pg_catalog.pg_get_triggerdef(x.oid) order by x.tgname)
+        from pg_catalog.pg_trigger x where x.tgrelid = relation_oid and not x.tgisinternal),
+      'policies', (select pg_catalog.jsonb_agg(pg_catalog.jsonb_build_object(
+        'name', x.polname, 'roles', x.polroles, 'cmd', x.polcmd, 'permissive', x.polpermissive,
+        'qual', pg_catalog.pg_get_expr(x.polqual, x.polrelid), 'check', pg_catalog.pg_get_expr(x.polwithcheck, x.polrelid)) order by x.polname)
+        from pg_catalog.pg_policy x where x.polrelid = relation_oid))::text
+    when kind = 'column' and attnum is not null then pg_catalog.jsonb_build_object(
+      'type', pg_catalog.format_type(atttypid, atttypmod), 'notNull', attnotnull, 'identity', attidentity,
+      'generated', attgenerated, 'default', (select pg_catalog.pg_get_expr(d.adbin, d.adrelid)
+        from pg_catalog.pg_attrdef d where d.adrelid = relation_oid and d.adnum = attnum), 'acl', attacl)::text
+    else null
+  end as shape
+from resolved order by ordinal`,
+    };
+}
+/** @beta Refuses incomplete or malformed observations without exposing catalog bodies. */
+export function decodeGroupedPostgresSchemaRows(objects, rows) {
+    function invalid() { throw new Error("Invalid grouped PostgreSQL schema rows"); }
+    if (rows.length !== objects.length)
+        invalid();
+    return objects.map((object, index) => {
+        const row = rows[index];
+        if (!row || !Number.isInteger(row.ordinal) || row.ordinal !== index + 1 || typeof row.present !== "boolean")
+            invalid();
+        let shape = row.shape;
+        if (!row.present) {
+            if (shape !== null)
+                invalid();
+        }
+        else {
+            if (typeof shape !== "string" || shape.length === 0)
+                invalid();
+            try {
+                shape = JSON.parse(shape);
+            }
+            catch {
+                invalid();
+            }
+            if (shape === null || typeof shape !== "object" || Array.isArray(shape))
+                invalid();
+        }
+        return { object, present: row.present, shape: shape };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/core",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Neutral D2C subscription and bundle commerce kernels; a development preview with no stable API.",
   "license": "Apache-2.0",
   "repository": {
@@ -38,6 +38,7 @@
     "api:check": "node --experimental-strip-types ./scripts/api-contract.ts",
     "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update",
     "ci": "npm run test:coverage && npm run typecheck:smoke && npm run api:check && npm run docs:check && npm run release:check && npm run test:consumer",
+    "ci:required": "npm run test:coverage && npm run typecheck:smoke && npm run docs:check && npm run release:check && npm run test:consumer",
     "docs:check": "node --experimental-strip-types ./scripts/documentation-contract.ts",
     "prepack": "npm run build",
     "prepublishOnly": "node --experimental-strip-types ./scripts/refuse-publish.ts",

package/release-gates.json

@@ -262,7 +262,7 @@
     }
   },
   "pack": {
-    "$budgetReason": "2026-10-05, owner-approved shared-contract growth: seven new source files add 21 source/runtime/declaration artifacts. The measured contribution has 198 code files, 15 above the prior cap, and 127202 code gzip bytes. The code budget is 131072 bytes/198 files; documentation stays at 24576 bytes/12 files. The total budget is 155648 packed bytes/655360 unpacked bytes/211 files, including the shipped documentation outside the root-file class. These bounded increases cover the outbox envelope, candidate-readiness and Standard Schema contracts; later growth still requires a measured budget decision.",
+    "$budgetReason": "2026-10-12 owner-approved bounded decision: additive grouped PostgreSQL catalog probes preserve the native jsonb text contract. Public base380edbd measures154118 packed/652616 unpacked bytes; corrected contribution measures158572/666908. Aggregate155KiB packed/652KiB unpacked is the smallest KiB-aligned headroom that fits the measured contribution; code/docs class ceilings, all file ceilings, required artifacts and other controls remain unchanged. Re-measure the exact approved candidate before DCO/delivery; this proposal grants no release authority. Later growth still requires a measured budget decision.",
     "code": {
       "maxPackedBytes": 131072,
       "maxFiles": 198
@@ -271,8 +271,8 @@
       "maxPackedBytes": 24576,
       "maxFiles": 12
     },
-    "maxPackedBytes": 155648,
-    "maxUnpackedBytes": 655360,
+    "maxPackedBytes": 158720,
+    "maxUnpackedBytes": 667648,
     "maxFiles": 211,
     "requiredFiles": [
       "AGENTS.md",

package/src/readiness/index.ts

@@ -2,7 +2,7 @@ import { declarationIssues, manifestShape, schemaObjectShape } from "./declarati
 import { schemaObjectKey } from "./schemaProbe.js";
 import type { ReadinessInput, ReadinessIssue, ReadinessReport, RequiredSchema, SchemaObservation, Contribution } from "./contracts.js";
 export * from "./contracts.js";
-export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe } from "./schemaProbe.js";
+export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe, buildGroupedPostgresSchemaProbe, decodeGroupedPostgresSchemaRows, type PostgresSchemaCatalogEntry } from "./schemaProbe.js";
 /** @beta Evaluates supplied facts; never performs migration or effect work. */
 export async function checkReadiness(input: ReadinessInput): Promise<ReadinessReport> {
   const issues = declarationIssues(input);

package/src/readiness/schemaProbe.ts

@@ -22,3 +22,77 @@ export function createSchemaProbe(executor: SqlExecutor, identity: (requirement:
     return { ...observed, objects };
   } };
 }
+
+/** @beta An ordered catalog observation, not proof of behavior or authorization. */
+export type PostgresSchemaCatalogEntry = {
+  object: SchemaObject;
+  present: boolean;
+  shape: Readonly<Record<string, unknown>> | null;
+};
+
+/** @beta One parameterized PostgreSQL catalog read; the host owns execution and snapshot. */
+export function buildGroupedPostgresSchemaProbe(objects: readonly SchemaObject[]): { text: string; values: readonly unknown[] } {
+  const scalarValues = objects.map(object => buildSchemaObjectProbe(object).values);
+  return {
+    values: [objects.map(object => object.kind), scalarValues.map(values => values[0]), scalarValues.map(values => values[1] ?? null)],
+    text: `with requested as (
+  select kind, name, column_name, ordinal::integer as ordinal
+  from unnest($1::text[], $2::text[], $3::text[]) with ordinality as r(kind, name, column_name, ordinal)
+), resolved as (
+  select r.*, c.oid as relation_oid, c.relkind, c.relowner, c.relacl, c.relrowsecurity, c.relforcerowsecurity,
+    a.attnum, a.atttypid, a.atttypmod, a.attnotnull, a.attidentity, a.attgenerated, a.attacl,
+    p.oid as function_oid, p.proowner, p.proacl, p.proconfig, p.prosecdef, p.provolatile
+  from requested r
+  left join pg_catalog.pg_class c on c.oid = case when r.kind <> 'function' then pg_catalog.to_regclass(r.name) end
+  left join pg_catalog.pg_attribute a on r.kind = 'column' and a.attrelid = c.oid
+    and a.attname = r.column_name and a.attnum > 0 and not a.attisdropped
+  left join pg_catalog.pg_proc p on p.oid = case when r.kind = 'function' then pg_catalog.to_regprocedure(r.name) end
+)
+select ordinal,
+  case kind when 'table' then coalesce(relkind in ('r','p'), false)
+    when 'column' then attnum is not null when 'function' then function_oid is not null end as present,
+  case
+    when kind = 'function' and function_oid is not null then pg_catalog.jsonb_build_object(
+      'definition', pg_catalog.pg_get_functiondef(function_oid), 'owner', pg_catalog.pg_get_userbyid(proowner),
+      'acl', proacl, 'config', proconfig, 'securityDefiner', prosecdef, 'volatility', provolatile)::text
+    when kind = 'table' and relkind in ('r','p') then pg_catalog.jsonb_build_object(
+      'kind', relkind, 'owner', pg_catalog.pg_get_userbyid(relowner), 'acl', relacl,
+      'rls', relrowsecurity, 'forceRls', relforcerowsecurity,
+      'constraints', (select pg_catalog.jsonb_agg(pg_catalog.pg_get_constraintdef(x.oid) order by x.conname)
+        from pg_catalog.pg_constraint x where x.conrelid = relation_oid),
+      'indexes', (select pg_catalog.jsonb_agg(pg_catalog.pg_get_indexdef(x.indexrelid) order by x.indexrelid::regclass::text)
+        from pg_catalog.pg_index x where x.indrelid = relation_oid),
+      'triggers', (select pg_catalog.jsonb_agg(pg_catalog.pg_get_triggerdef(x.oid) order by x.tgname)
+        from pg_catalog.pg_trigger x where x.tgrelid = relation_oid and not x.tgisinternal),
+      'policies', (select pg_catalog.jsonb_agg(pg_catalog.jsonb_build_object(
+        'name', x.polname, 'roles', x.polroles, 'cmd', x.polcmd, 'permissive', x.polpermissive,
+        'qual', pg_catalog.pg_get_expr(x.polqual, x.polrelid), 'check', pg_catalog.pg_get_expr(x.polwithcheck, x.polrelid)) order by x.polname)
+        from pg_catalog.pg_policy x where x.polrelid = relation_oid))::text
+    when kind = 'column' and attnum is not null then pg_catalog.jsonb_build_object(
+      'type', pg_catalog.format_type(atttypid, atttypmod), 'notNull', attnotnull, 'identity', attidentity,
+      'generated', attgenerated, 'default', (select pg_catalog.pg_get_expr(d.adbin, d.adrelid)
+        from pg_catalog.pg_attrdef d where d.adrelid = relation_oid and d.adnum = attnum), 'acl', attacl)::text
+    else null
+  end as shape
+from resolved order by ordinal`,
+  };
+}
+
+/** @beta Refuses incomplete or malformed observations without exposing catalog bodies. */
+export function decodeGroupedPostgresSchemaRows(objects: readonly SchemaObject[], rows: readonly Record<string, unknown>[]): readonly PostgresSchemaCatalogEntry[] {
+  function invalid(): never { throw new Error("Invalid grouped PostgreSQL schema rows"); }
+  if (rows.length !== objects.length) invalid();
+  return objects.map((object, index) => {
+    const row = rows[index];
+    if (!row || !Number.isInteger(row.ordinal) || row.ordinal !== index + 1 || typeof row.present !== "boolean") invalid();
+    let shape: unknown = row.shape;
+    if (!row.present) {
+      if (shape !== null) invalid();
+    } else {
+      if (typeof shape !== "string" || shape.length === 0) invalid();
+      try { shape = JSON.parse(shape); } catch { invalid(); }
+      if (shape === null || typeof shape !== "object" || Array.isArray(shape)) invalid();
+    }
+    return { object, present: row.present, shape: shape as PostgresSchemaCatalogEntry["shape"] };
+  });
+}