@dudousxd/nestjs-catalog 0.5.0 → 0.7.0

package/dist/catalog.environment.d.ts

@@ -94,13 +94,24 @@ export interface CatalogEnvironment {
      */
     rank: number;
     /**
-     * Whether this environment refuses changes that did not arrive as a reviewed
-     * promotion.
+     * A declaration that this environment is one where changes are supposed to
+     * arrive as a reviewed promotion. True for production.
      *
-     * True for production. It does not lock the environment — an operator can
-     * still fix something by hand — it means the API demands the explicit
-     * confirmation described on {@link CatalogPromotionApproval} rather than
-     * accepting a plan somebody generated in another tab ten minutes ago.
+     * **Advisory. Nothing in this library refuses anything because of it.** No
+     * guard, no store and no plan reads this field; the only code that does is the
+     * console, which paints the environment switcher amber so that "am I about to
+     * do this to production" is answerable at a glance. That is worth having and
+     * it is worth not overstating — a flag documented as an enforcement point,
+     * enforced nowhere, is worse than no flag, because it invites a host to
+     * believe the refusal already exists.
+     *
+     * Kept rather than removed because the enforcement it describes cannot live
+     * here. The library has no apply endpoint and no opinion about who may approve
+     * what — see {@link CatalogPromotionPlan.fingerprint} for the same division —
+     * so the refusal belongs to whatever host exposes promotion over HTTP. This
+     * field is how that host learns which environments to demand
+     * {@link CatalogPromotionApproval} for, without every deployment restating its
+     * own list of environment names in a guard.
      */
     protected: boolean;
 }
@@ -173,17 +184,40 @@ export declare function catalogDatabaseNameFor(base: string, environmentId: Cata
  * It stops being enough the moment anyone asks a governance question across
  * environments — "everything this person did this week" has to be answerable
  * without the reader having to remember which of three lists they are looking
- * at — so the environment is stamped onto every event as it leaves its store.
+ * at.
  *
  * Stamped on read rather than stored in a column on purpose: a stored column
  * can be wrong, because nothing in the database stops a row in the production
  * table saying `environment: "dev"`. A value derived from which connection the
  * row was read through cannot be.
+ *
+ * Which is also why the stamping does not happen here, and cannot. This package
+ * knows what an environment *is*; it has no connection and no scope, so it can
+ * only supply the shape and the function. The stamp is applied by the one reader
+ * that resolved an environment in order to do the read at all —
+ * `RoutingWorkspaceStore.listEvents` in the MikroORM store package, which widens
+ * its return type to this intersection. A read that went straight to a store,
+ * with no environment resolved anywhere above it, is *not* stamped, and that is
+ * the honest answer rather than a gap: nothing in that call knew which world it
+ * was reading, so anything written into the field would be a guess.
  */
 export interface EnvironmentStampedAuditEvent {
     environment: CatalogEnvironmentId;
 }
-/** Stamps a batch of events with the environment they were read from. */
+/**
+ * Stamps a batch of events with the environment they were read from.
+ *
+ * A separate function taking the id as an argument rather than a method
+ * somewhere, so the caller has to have the environment in hand to call it. There
+ * is no default and nothing to look up — the id comes from the same resolution
+ * that chose the connection, which is what makes the stamp a fact about the read
+ * rather than a label somebody attached afterwards.
+ *
+ * Generic over the event rather than typed to `CatalogAuditEvent`, which lives
+ * in `catalog.workspace.ts` and would make this file depend on the workspace
+ * vocabulary to say something true of any row. Nothing here needs to know more
+ * about an event than that it is an object.
+ */
 export declare function stampEnvironment<T>(environment: CatalogEnvironmentId, events: readonly T[]): Array<T & EnvironmentStampedAuditEvent>;
 /** What a promotion is allowed to carry. */
 export declare const PROMOTABLE_KINDS: readonly ["objectType", "transform", "workflow", "connector"];
@@ -257,6 +291,45 @@ export interface PromotableObjectType {
         unit?: string;
         classification?: string;
     }>;
+    /**
+     * The links the type declares, in the shape they are stored in.
+     *
+     * Absent from this interface until it was noticed that a promoted type arrived
+     * complete in every visible way — right properties, right table, right owner —
+     * and sat in the target's graph as an island. Nothing errored, nothing was
+     * reported, and the plan the operator approved said "nothing to promote" for a
+     * release whose only content was a link.
+     *
+     * Spelled out here rather than imported from the store package, which is the
+     * same reason `properties` is: the dependency runs the other way, and this
+     * side is the one both a MikroORM environment and anything else that ever
+     * holds a catalog have to satisfy. `kind` is a bare `string` for the reason the
+     * stored row gives — what comes back out of a JSON column is whatever some
+     * earlier version of some publisher put in, and it is narrowed where it is
+     * read, not asserted here.
+     *
+     * Optional, and read as `[]` wherever it is used. An environment whose rows
+     * predate the relations column holds `NULL` there, and requiring the field
+     * would force every hand-built promotable set to name something it has nothing
+     * to say about. "Absent" and "empty" are deliberately the same statement here,
+     * unlike on the publish wire: this shape is built by `readPromotable` in this
+     * process rather than arriving from a client of unknown vintage, and the plan
+     * an operator approves has to describe exactly what the apply will do. See
+     * `promoteType`.
+     */
+    relations?: Array<{
+        name: string;
+        displayName: string;
+        description?: string;
+        kind: string;
+        targetType: string;
+        localKey?: string;
+        nullable: boolean;
+        hidden: boolean;
+        position: number;
+        owner: boolean;
+        inverseName?: string;
+    }>;
 }
 export interface PromotableTransform {
     id: string;
@@ -375,9 +448,22 @@ export interface CatalogPromotionPlan {
      * The point of a preview is that somebody read it. Without a fingerprint the
      * apply call is a fresh promotion that happens to have been preceded by a
      * preview, and anything that changed in between — a colleague editing the
-     * transform, a connector deleted — goes in unreviewed. The apply endpoint
-     * demands this value back, recomputes the plan, and refuses if the two
-     * differ. That is what turns "we show a diff" into "you approved this diff".
+     * transform, a connector deleted — goes in unreviewed.
+     *
+     * **The check is the host's, and this library does not perform it.** There is
+     * no apply endpoint here: `applyPromotion` is exported for a host to call, and
+     * it does not recompute the plan or compare anything to this value. The
+     * expectation, stated the same way where the apply lives, is that the caller
+     * re-runs {@link planPromotion} immediately before applying and confirms the
+     * fingerprint still matches what the reviewer approved. It lives with the
+     * caller because it is a policy decision about who may approve what, and
+     * `applyPromotion` is the mechanism rather than the policy.
+     *
+     * So this field is what makes that check *possible* — a stable name for one
+     * reviewed set of changes, computed from the effect and not the clock — and
+     * not, on its own, the check. A host that carries the value from preview to
+     * apply and never compares it has a promotion nobody approved, and nothing in
+     * this package will say so.
      */
     fingerprint: string;
 }
@@ -394,7 +480,13 @@ export interface CatalogPromotionPlan {
  * which environment the row belongs to.
  */
 export declare const PROMOTION_AUDIT_EVENT = "promotion.applied";
-/** What an apply call must present to prove which plan was approved. */
+/**
+ * What a host's apply call asks for, to prove which plan was approved.
+ *
+ * A shape rather than a check — see {@link CatalogPromotionPlan.fingerprint} for
+ * why the comparison lives with the caller. Written down here so that every host
+ * demands the same two things and an audit row means the same thing in each.
+ */
 export interface CatalogPromotionApproval {
     fingerprint: string;
     /** Free text the operator typed. Recorded in the audit trail, never parsed. */

package/dist/catalog.environment.js

@@ -216,7 +216,20 @@ function durableKeyspaceFor(environmentId, prefix = 'catalog') {
 function catalogDatabaseNameFor(base, environmentId) {
     return `${base}_${assertEnvironmentId(environmentId)}`;
 }
-/** Stamps a batch of events with the environment they were read from. */
+/**
+ * Stamps a batch of events with the environment they were read from.
+ *
+ * A separate function taking the id as an argument rather than a method
+ * somewhere, so the caller has to have the environment in hand to call it. There
+ * is no default and nothing to look up — the id comes from the same resolution
+ * that chose the connection, which is what makes the stamp a fact about the read
+ * rather than a label somebody attached afterwards.
+ *
+ * Generic over the event rather than typed to `CatalogAuditEvent`, which lives
+ * in `catalog.workspace.ts` and would make this file depend on the workspace
+ * vocabulary to say something true of any row. Nothing here needs to know more
+ * about an event than that it is an object.
+ */
 function stampEnvironment(environment, events) {
     return events.map((event) => ({ ...event, environment }));
 }
@@ -719,5 +732,55 @@ function diffObjectType(existing, incoming) {
             to: gone,
         });
     }
+    diffs.push(...diffRelations(existing, incoming));
+    return diffs;
+}
+/**
+ * The links, compared the same way the properties above are — and named
+ * differently on purpose.
+ *
+ * **Why this exists at all.** Without it a promotion whose only difference is a
+ * link reports `unchanged`, so the plan says there is nothing to promote and the
+ * apply, driven by that plan, does nothing. The change is real, the operator is
+ * shown an empty diff, and the link stays behind in dev. A plan is what somebody
+ * approves; a change invisible in the plan is a change nobody approved.
+ *
+ * **`relations.removed`, not `relations.absentFromSource`.** The properties
+ * above borrow the softer word because nothing acts on them: `ensureType` is
+ * additive, so a column that vanished from the source keeps its data in the
+ * target. A link that vanished really is deleted there — `promoteType` assigns
+ * the source's links rather than merging them, because a link holds no data and
+ * keeping one the source deliberately dropped means the target asserts a join
+ * the schema no longer has. The field name has to say which of those two a
+ * reviewer is looking at.
+ *
+ * **`to` repeats the removed names rather than being empty.** The fingerprint an
+ * approval is compared against hashes each field's `to` value; an empty one
+ * would make "drops the link to Base" and "drops the link to Depot" hash
+ * identically, so a plan approved for one would be applicable as the other.
+ */
+function diffRelations(existing, incoming) {
+    const diffs = [];
+    // `?? []` on both sides, so an environment predating the relations column
+    // compares as holding none rather than as differing from everything.
+    const before = new Map((existing?.relations ?? []).map((relation) => [relation.name, relation]));
+    const after = new Map((incoming.relations ?? []).map((relation) => [relation.name, relation]));
+    const added = [...after.keys()].filter((name) => !before.has(name));
+    const changed = [...after.entries()]
+        .filter(([name, relation]) => {
+        const previous = before.get(name);
+        return previous !== undefined && stable(previous) !== stable(relation);
+    })
+        .map(([name]) => name);
+    const removed = [...before.keys()].filter((name) => !after.has(name));
+    if (added.length) {
+        diffs.push({ field: 'relations.added', from: [], to: added });
+    }
+    if (changed.length) {
+        diffs.push({ field: 'relations.changed', from: changed, to: changed });
+    }
+    if (removed.length) {
+        diffs.push({ field: 'relations.removed', from: removed, to: removed });
+    }
     return diffs;
 }

package/dist/catalog.events.d.ts

@@ -14,15 +14,16 @@
  */
 export declare const CATALOG_LIB = "catalog";
 /** Every event name this package emits. Exported so a watcher can claim them. */
-export declare const CATALOG_EVENTS: readonly ["schema.changed", "snapshot.written", "snapshot.committed", "snapshot.dropped", "type.curated", "connector.run.started", "connector.run.finished", "transform.changed", "workflow.changed"];
+export declare const CATALOG_EVENTS: readonly ["schema.changed", "snapshot.written", "snapshot.committed", "snapshot.dropped", "type.curated", "connector.run.started", "connector.run.finished", "transform.changed", "workflow.changed", "query.shared", "dashboard.shared"];
 export type CatalogEvent = (typeof CATALOG_EVENTS)[number];
 /**
  * Where each event sits in the life of one load.
  *
  * This exists because a timestamp is not enough to order a trace. A fast load
  * emits its whole story inside a single tick of whatever clock the recorder
- * writes — the bundled MySQL store keeps whole seconds — so sorting by time
- * alone leaves the events in insertion order, and insertion order is arbitrary.
+ * writes — the bundled MySQL store keeps milliseconds, and a commit of a few
+ * hundred rows lands well inside one — so sorting by time alone leaves the
+ * events in insertion order, and insertion order is arbitrary.
  * The observed result is a trace that reads `finished → written → committed →
  * started`: causally impossible, rendered with total confidence. Sorting by
  * time *and then* by this rank puts a same-tick story back in the only order it
@@ -142,6 +143,69 @@ export interface CatalogEventPayloads {
         nodeCount: number;
         changedBy: string;
     };
+    /**
+     * A saved query started or stopped being fetchable through the embed API.
+     *
+     * The single act that hands an outside application data from this catalog, and
+     * for a long time the only one that left no trace: `SavedQuery.shared` is the
+     * whole embed boundary, it is set by a person, and nothing recorded that they
+     * had set it.
+     *
+     * One event for both directions rather than a `query.unshared` beside it,
+     * following `connector.run.finished`: anybody watching for shares has to watch
+     * for revocations too — a trail that records only the grants cannot answer
+     * "was this still shared last Tuesday", which is the question an incident
+     * actually asks. The direction is in {@link shared}.
+     *
+     * Emitted on the transition only. A save that leaves the flag where it was is
+     * not a sharing decision, and a trail that logged every keystroke on a query
+     * would be a trail nobody reads.
+     *
+     * **Deleting a shared query is one of those transitions**, and it emits here
+     * rather than under a name of its own. The question this event answers is
+     * "when did this stop being reachable from outside", and anybody asking it
+     * filters on `query.shared` and reads the last entry. A separate
+     * `query.deleted` would leave that filter reporting `shared: true` forever
+     * for something nobody can fetch — the revocation would be in a channel the
+     * asker did not subscribe to, which is the same absence this event exists to
+     * remove. {@link deleted} says which kind of ending it was.
+     */
+    'query.shared': {
+        savedQueryId: string;
+        /** As it read at the moment of the change, so the trail is legible alone. */
+        name: string;
+        /** True when access was granted, false when it was taken back. */
+        shared: boolean;
+        /**
+         * Who decided. The host-resolved principal where there is one, and named
+         * `principalId` because that is the field a recorder lifts into the audit
+         * table's indexed column — spell it anything else and the entry lands
+         * attributed to nobody.
+         */
+        principalId: string;
+        /**
+         * Set only when the revocation was a deletion. Absent means the thing still
+         * exists and was merely un-shared.
+         *
+         * Typed as `true` rather than `boolean` so the flag cannot be written the
+         * other way round: "not a deletion" is the absence of this key, matching
+         * how the rest of these payloads treat a fact that did not happen.
+         *
+         * Worth carrying rather than leaving to be looked up, because after a
+         * deletion there is nothing left to look up. An entry that said only
+         * `shared: false` would send its reader to a row that is gone, and the
+         * empty result reads as a broken trail rather than as the answer.
+         */
+        deleted?: true;
+    };
+    /** The same decision, about a whole board. See {@link CatalogEventPayloads['query.shared']}. */
+    'dashboard.shared': {
+        dashboardId: string;
+        name: string;
+        shared: boolean;
+        principalId: string;
+        deleted?: true;
+    };
 }
 /**
  * Teach the diagnostics channel what this library puts on it.

package/dist/catalog.events.js

@@ -31,14 +31,17 @@ exports.CATALOG_EVENTS = [
     'connector.run.finished',
     'transform.changed',
     'workflow.changed',
+    'query.shared',
+    'dashboard.shared',
 ];
 /**
  * Where each event sits in the life of one load.
  *
  * This exists because a timestamp is not enough to order a trace. A fast load
  * emits its whole story inside a single tick of whatever clock the recorder
- * writes — the bundled MySQL store keeps whole seconds — so sorting by time
- * alone leaves the events in insertion order, and insertion order is arbitrary.
+ * writes — the bundled MySQL store keeps milliseconds, and a commit of a few
+ * hundred rows lands well inside one — so sorting by time alone leaves the
+ * events in insertion order, and insertion order is arbitrary.
  * The observed result is a trace that reads `finished → written → committed →
  * started`: causally impossible, rendered with total confidence. Sorting by
  * time *and then* by this rank puts a same-tick story back in the only order it
@@ -64,6 +67,16 @@ exports.CATALOG_EVENT_PHASE = {
     // be complete is exactly the mechanism that will fail the build the day a new
     // event is added and nobody thinks about where it belongs.
     'type.curated': 2,
+    // Sharing carries no snapshot id either, for the same reason curation does
+    // not: it is a standalone act on a saved query or a board, not a step of any
+    // load. So these ranks are never consulted, and they are written out for the
+    // reason the note above gives — the `Record` has to be complete, and that is
+    // what makes the build fail the day an event is added and nobody thinks about
+    // where it belongs. Ranked beside curation because they are the same kind of
+    // thing: a person deciding something about the catalog rather than data moving
+    // through it.
+    'query.shared': 2,
+    'dashboard.shared': 2,
     'schema.changed': 3,
     'snapshot.written': 4,
     'snapshot.committed': 5,

package/dist/catalog.pipeline.d.ts

@@ -84,6 +84,25 @@ export interface CatalogConnector {
      * view atomically. `incremental` reads only what changed since the last run
      * and carries the rest forward, which is cheaper but needs the source to
      * offer a watermark and the type to have a primary key to merge on.
+     *
+     * **`incremental` is blind to deletes, and that is structural rather than a
+     * gap in any particular fetcher.** A run asks its source for what changed
+     * since a watermark; a row physically removed from the source never changes
+     * again, so it is never returned again, so the carry-forward copies it into
+     * every subsequent snapshot indefinitely. Nothing goes wrong at any single
+     * step — the catalog simply never finds out, and every count and dashboard
+     * built on the type is quietly wrong from then on.
+     *
+     * Because that failure is silent, the pipeline **refuses an incremental load
+     * of a type for which no reconciliation strategy has been declared**: a full
+     * read on an interval, a source that soft-deletes where the watermark can see
+     * it, or an explicit "stale rows are acceptable here, because …". The
+     * declaration is per object type and lives in the host's
+     * `CATALOG_LOAD_EXPECTATIONS` (see `load-expectations.ts` in
+     * `@dudousxd/nestjs-catalog-pipeline`), because it is a statement about the
+     * data rather than about the connector reading it — the same type loaded by a
+     * workflow sink or by an application POSTing to the publish API has exactly
+     * the same problem.
      */
     mode?: 'full' | 'incremental';
     /**

package/dist/catalog.principal.d.ts

@@ -16,6 +16,7 @@
  * to survive into the audit trail, because "the console renamed this column" is
  * not an answer anybody accepts.
  */
+import type { CatalogObjectPage } from './catalog.types';
 export type CatalogScope = 
 /** Read object metadata and rows. */
 'catalog:read'
@@ -118,7 +119,9 @@ export interface CatalogPrincipal {
     readTypes?: string[];
     /**
      * Classifications this principal may see. A column marked with anything
-     * outside this list is dropped from its reads.
+     * outside this list is to be dropped from its reads — *by whoever serves
+     * them*, which is not this library. See the note above {@link mayWrite} on
+     * who enforces, and {@link readableObjectPage} for the drop itself.
      *
      * Undefined means "no classified columns", not "all of them" — the safe
      * default for a caller nobody has thought about yet.
@@ -198,12 +201,57 @@ export declare function expandScopes(scopes: CatalogScope[]): CatalogScope[];
  * something that happens because an administrator logged in.
  */
 export declare function delegatePrincipal(application: CatalogPrincipal, actor: CatalogActor, grants: CatalogGrants): CatalogPrincipal;
+/** Enforced by the library, because the publish API is handed a principal. */
 export declare function mayWrite(principal: CatalogPrincipal, typeName: string): boolean;
+/**
+ * Whether this principal may read a type at all.
+ *
+ * A predicate for a host to apply, not something the catalog's own read routes
+ * consult — see the note above. `readableObjectPage` is the ready-made
+ * application of it.
+ */
 export declare function mayRead(principal: CatalogPrincipal, typeName: string): boolean;
 /**
  * Whether a column is visible to this principal.
  *
  * Unclassified columns are visible to everyone; a classified one requires the
  * principal to name that classification. Absence is denial.
+ *
+ * The same caveat as {@link mayRead}: answering the question is all this does.
+ * No read path in this library asks it.
  */
 export declare function maySeeClassification(principal: CatalogPrincipal, classification: string | undefined): boolean;
+/**
+ * A page of objects as this principal is allowed to see it: the page, minus
+ * every column carrying a classification they do not hold — and `null` when
+ * they may not read the type at all.
+ *
+ * This exists so that "who applies `mayRead` and `maySeeClassification`?" has an
+ * answer a host can call rather than a rule a host has to re-derive. Wrap the
+ * service:
+ *
+ * ```ts
+ * const page = await this.catalog.readObjects(name, query);
+ * const visible = readableObjectPage(principal, page);
+ * if (!visible) throw new ForbiddenException(`${principal.id} may not read ${name}.`);
+ * return visible;
+ * ```
+ *
+ * `null` rather than a thrown exception because the status code is the host's
+ * decision: a 403 confirms to the caller that the type exists, and a deployment
+ * that considers the type list itself sensitive would rather answer 404. `null`
+ * rather than an empty page because a page with no columns is what a type whose
+ * every column is hidden legitimately returns, and a denial must not be
+ * mistakable for one.
+ *
+ * Hidden values are **deleted** from each row rather than blanked. A key present
+ * with `null` asserts that the column exists and happens to be empty, which for
+ * a classified column is itself a disclosure.
+ *
+ * What it does not do: rows can carry keys no column declares, because
+ * `readObjects` always fetches the primary key so a UI has a row identity even
+ * when that key is hidden. Those survive. This removes what a classification
+ * hides; it is not a whitelist, and a classified column that is also part of a
+ * hidden primary key is outside what a page alone can express.
+ */
+export declare function readableObjectPage(principal: CatalogPrincipal, page: CatalogObjectPage): CatalogObjectPage | null;

package/dist/catalog.principal.js

@@ -27,6 +27,7 @@ exports.delegatePrincipal = delegatePrincipal;
 exports.mayWrite = mayWrite;
 exports.mayRead = mayRead;
 exports.maySeeClassification = maySeeClassification;
+exports.readableObjectPage = readableObjectPage;
 /** Every scope, in one place, so `catalog:admin` can be expanded exactly. */
 const ALL_SCOPES = [
     'catalog:read',
@@ -222,9 +223,45 @@ function matches(list, typeName) {
         return false;
     return list.includes('*') || list.includes(typeName);
 }
+// -----------------------------------------------------------------------------
+// The grant predicates, and who is expected to call them.
+//
+// **This library declares and evaluates; the host enforces.** The same split
+// `catalog.route-auth.ts` states for scopes holds for grants: nothing in this
+// package ever turns a request into a principal. `CatalogPrincipalResolver` is
+// an interface with one bundled development implementation, no guard ships here,
+// and the `request.principal` that `publish.controller.ts` reads is put there by
+// a guard the host wrote — the error it throws even names a class this repo does
+// not contain.
+//
+// The asymmetry between write and read is real and is not the bug it looks like.
+// `mayWrite` is called inside the library, in `publish.service.ts`, for exactly
+// one reason: the publish API takes a `CatalogPrincipal` as an argument, so it
+// has one in hand. The read path does not. `CatalogService.readObjects` has no
+// principal parameter, `GET /catalog/objects/:name` has none to give it, and so
+// `mayRead` and `maySeeClassification` are called nowhere in this repository at
+// runtime. That is the design: a library that filtered reads would need a
+// principal on every read, which means shipping a guard, which means having an
+// opinion about the host's identity provider.
+//
+// What was wrong was not the mechanism but the prose around it. A host reading
+// "classifications this principal may see" is entitled to assume something drops
+// the columns, and nothing does. So, stated once, here: **the read path applies
+// no grants and no classification filtering, and a host that wants either calls
+// `readableObjectPage` itself.** Anyone about to "wire this up" should change
+// that sentence rather than quietly making it false.
+// -----------------------------------------------------------------------------
+/** Enforced by the library, because the publish API is handed a principal. */
 function mayWrite(principal, typeName) {
     return hasScope(principal, 'catalog:write') && matches(principal.writeTypes, typeName);
 }
+/**
+ * Whether this principal may read a type at all.
+ *
+ * A predicate for a host to apply, not something the catalog's own read routes
+ * consult — see the note above. `readableObjectPage` is the ready-made
+ * application of it.
+ */
 function mayRead(principal, typeName) {
     if (!hasScope(principal, 'catalog:read'))
         return false;
@@ -237,9 +274,64 @@ function mayRead(principal, typeName) {
  *
  * Unclassified columns are visible to everyone; a classified one requires the
  * principal to name that classification. Absence is denial.
+ *
+ * The same caveat as {@link mayRead}: answering the question is all this does.
+ * No read path in this library asks it.
  */
 function maySeeClassification(principal, classification) {
     if (!classification)
         return true;
     return principal.classifications?.includes(classification) ?? false;
 }
+/**
+ * A page of objects as this principal is allowed to see it: the page, minus
+ * every column carrying a classification they do not hold — and `null` when
+ * they may not read the type at all.
+ *
+ * This exists so that "who applies `mayRead` and `maySeeClassification`?" has an
+ * answer a host can call rather than a rule a host has to re-derive. Wrap the
+ * service:
+ *
+ * ```ts
+ * const page = await this.catalog.readObjects(name, query);
+ * const visible = readableObjectPage(principal, page);
+ * if (!visible) throw new ForbiddenException(`${principal.id} may not read ${name}.`);
+ * return visible;
+ * ```
+ *
+ * `null` rather than a thrown exception because the status code is the host's
+ * decision: a 403 confirms to the caller that the type exists, and a deployment
+ * that considers the type list itself sensitive would rather answer 404. `null`
+ * rather than an empty page because a page with no columns is what a type whose
+ * every column is hidden legitimately returns, and a denial must not be
+ * mistakable for one.
+ *
+ * Hidden values are **deleted** from each row rather than blanked. A key present
+ * with `null` asserts that the column exists and happens to be empty, which for
+ * a classified column is itself a disclosure.
+ *
+ * What it does not do: rows can carry keys no column declares, because
+ * `readObjects` always fetches the primary key so a UI has a row identity even
+ * when that key is hidden. Those survive. This removes what a classification
+ * hides; it is not a whitelist, and a classified column that is also part of a
+ * hidden primary key is outside what a page alone can express.
+ */
+function readableObjectPage(principal, page) {
+    if (!mayRead(principal, page.type))
+        return null;
+    const hidden = page.columns
+        .filter((column) => !maySeeClassification(principal, column.classification))
+        .map((column) => column.name);
+    if (hidden.length === 0)
+        return page;
+    return {
+        ...page,
+        columns: page.columns.filter((column) => !hidden.includes(column.name)),
+        rows: page.rows.map((row) => {
+            const visible = { ...row };
+            for (const name of hidden)
+                delete visible[name];
+            return visible;
+        }),
+    };
+}