graphile-storage-registry 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# graphile-storage-registry
+
+Registry-derived storage plane discovery for PostGraphile v5.
+
+A storage plane is a `@storageFiles` table and the `@storageBuckets` table it
+writes into. This package pairs them through their **actual foreign-key
+relations** in the Graphile registry (`pgRegistry.pgRelations`) — never through
+table names — and derives the canonical upload surface names from the schema's
+own inflection, so no physical name is ever load-bearing.
+
+## Usage
+
+```ts
+import { discoverStoragePlanes, uploadSurfaceNames } from 'graphile-storage-registry';
+
+const planes = discoverStoragePlanes(build.input.pgRegistry);
+for (const plane of planes) {
+  const names = uploadSurfaceNames(build.inflection, plane.filesCodec);
+  // names.uploadMutation === 'uploadAppFile', names.bulkUploadMutation === 'uploadAppFiles', …
+}
+```
+
+`discoverStoragePlanes` throws at schema build when a tagged storage table
+cannot be paired:
+
+- `STORAGE_PLANE_UNPAIRED` — a `@storageFiles` table with no FK to a
+  `@storageBuckets` table, or a `@storageBuckets` table referenced by no files
+  table.
+- `STORAGE_PLANE_AMBIGUOUS` — a files table with FKs to more than one buckets
+  table.
+
+A plane is entity-keyed when its buckets table carries an `owner_id` attribute
+(`plane.hasOwnerId`) — a registry fact, never inferred from the plane's scope
+name.
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.d.ts

@@ -0,0 +1,4 @@
+export type { StorageInflection, UploadSurfaceNames } from './naming';
+export { DOWNLOAD_URL_FIELD, uploadSurfaceNames } from './naming';
+export type { StorageCodec, StorageCodecAttributes, StorageCodecRelation, StoragePgRegistry, StoragePlanePair, } from './pairing';
+export { discoverStoragePlanes, pairStoragePlane } from './pairing';

package/esm/index.js

@@ -0,0 +1,2 @@
+export { DOWNLOAD_URL_FIELD, uploadSurfaceNames } from './naming';
+export { discoverStoragePlanes, pairStoragePlane } from './pairing';

package/esm/naming.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical names of a storage plane's upload surface.
+ *
+ * The presigned-url plugin emits these fields and types; anything that reports
+ * or consumes the surface (the `_meta` storage section, dynamic clients) must
+ * derive the same names from the same inflection facts. This module is the one
+ * definition of that derivation, so the emitter and the reporters cannot
+ * disagree.
+ */
+import type { StorageCodec } from './pairing';
+/**
+ * The computed field the download plugin adds to every files type. One
+ * definition so the emitter (download-url-field.ts) and the reporters
+ * (`_meta`, dynamic clients) cannot disagree.
+ */
+export declare const DOWNLOAD_URL_FIELD = "downloadUrl";
+/** The slice of `build.inflection` the naming derivation reads. */
+export interface StorageInflection {
+    tableType(codec: StorageCodec): string;
+}
+/** The GraphQL names of one plane's upload surface. */
+export interface UploadSurfaceNames {
+    /** GraphQL type name of the files table (e.g. `AppFile`). */
+    filesTypeName: string;
+    /** Single upload mutation field (e.g. `uploadAppFile`). */
+    uploadMutation: string;
+    /** Input type of the single upload mutation (e.g. `UploadAppFileInput`). */
+    uploadInputType: string;
+    /** Payload type of the single upload mutation (e.g. `UploadAppFilePayload`). */
+    uploadPayloadType: string;
+    /** Bulk upload mutation field (e.g. `uploadAppFiles`). */
+    bulkUploadMutation: string;
+    /** Input type of the bulk upload mutation (e.g. `UploadAppFileBulkInput`). */
+    bulkUploadInputType: string;
+    /** Payload type of the bulk upload mutation (e.g. `UploadAppFileBulkPayload`). */
+    bulkUploadPayloadType: string;
+    /** Per-file input type inside the bulk input (e.g. `UploadAppFileBulkFileInput`). */
+    bulkUploadFileInputType: string;
+    /** Per-file payload type inside the bulk payload (e.g. `UploadAppFileBulkFilePayload`). */
+    bulkUploadFilePayloadType: string;
+}
+/**
+ * Derive the upload surface names for a plane's files codec.
+ */
+export declare function uploadSurfaceNames(inflection: StorageInflection, filesCodec: StorageCodec): UploadSurfaceNames;

package/esm/naming.js

@@ -0,0 +1,32 @@
+/**
+ * Canonical names of a storage plane's upload surface.
+ *
+ * The presigned-url plugin emits these fields and types; anything that reports
+ * or consumes the surface (the `_meta` storage section, dynamic clients) must
+ * derive the same names from the same inflection facts. This module is the one
+ * definition of that derivation, so the emitter and the reporters cannot
+ * disagree.
+ */
+/**
+ * The computed field the download plugin adds to every files type. One
+ * definition so the emitter (download-url-field.ts) and the reporters
+ * (`_meta`, dynamic clients) cannot disagree.
+ */
+export const DOWNLOAD_URL_FIELD = 'downloadUrl';
+/**
+ * Derive the upload surface names for a plane's files codec.
+ */
+export function uploadSurfaceNames(inflection, filesCodec) {
+    const filesTypeName = inflection.tableType(filesCodec);
+    return {
+        filesTypeName,
+        uploadMutation: `upload${filesTypeName}`,
+        uploadInputType: `Upload${filesTypeName}Input`,
+        uploadPayloadType: `Upload${filesTypeName}Payload`,
+        bulkUploadMutation: `upload${filesTypeName}s`,
+        bulkUploadInputType: `Upload${filesTypeName}BulkInput`,
+        bulkUploadPayloadType: `Upload${filesTypeName}BulkPayload`,
+        bulkUploadFileInputType: `Upload${filesTypeName}BulkFileInput`,
+        bulkUploadFilePayloadType: `Upload${filesTypeName}BulkFilePayload`,
+    };
+}

package/esm/pairing.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Registry-derived storage plane discovery.
+ *
+ * A storage plane is a `@storageFiles` table and the `@storageBuckets` table it
+ * writes into. The pairing fact is the files table's foreign key to the buckets
+ * table — a relation the Graphile registry already carries — so it is read from
+ * `pgRegistry.pgRelations`, never derived from table names. Physical naming
+ * (`app_files`/`app_buckets` vs unprefixed `files`/`buckets`) is a rendering
+ * choice and carries no meaning here.
+ *
+ * A `@storageFiles` codec that cannot be paired through a real FK relation is a
+ * provisioning bug, and discovery throws at schema build rather than silently
+ * emitting a schema with no upload surface for that plane.
+ */
+/** The attributes shape shared by pg codecs. */
+export interface StorageCodecAttributes {
+    [attributeName: string]: unknown;
+}
+/**
+ * The slice of a Graphile pg codec that storage discovery reads. Structural on
+ * purpose: callers pass real codecs from `build.input.pgRegistry`, and this
+ * package stays free of graphile-build peer dependencies.
+ */
+export interface StorageCodec {
+    name: string;
+    attributes?: StorageCodecAttributes;
+    extensions?: {
+        pg?: {
+            schemaName?: string;
+            name?: string;
+        };
+        tags?: {
+            storageFiles?: unknown;
+            storageBuckets?: unknown;
+            [tag: string]: unknown;
+        };
+    };
+}
+/** The slice of a registry relation entry that storage discovery reads. */
+export interface StorageCodecRelation {
+    isReferencee?: boolean;
+    localAttributes: readonly string[];
+    remoteAttributes: readonly string[];
+    remoteResource?: {
+        codec?: StorageCodec;
+    };
+}
+/** The slice of `build.input.pgRegistry` that storage discovery reads. */
+export interface StoragePgRegistry {
+    pgCodecs: Record<string, StorageCodec>;
+    pgRelations: Record<string, Record<string, StorageCodecRelation>>;
+}
+/**
+ * A discovered storage plane: the files codec, the buckets codec its FK names,
+ * and the facts a plugin needs to shape the plane's GraphQL surface.
+ */
+export interface StoragePlanePair {
+    filesCodec: StorageCodec;
+    bucketsCodec: StorageCodec;
+    /** Registry name of the FK relation on the files codec (e.g. `bucketsByMyBucketId`). */
+    relationName: string;
+    /** FK attribute(s) on the files table referencing the buckets table (e.g. `['bucket_id']`). */
+    fkAttributes: string[];
+    /**
+     * Whether the plane is entity-keyed: the buckets table carries an `owner_id`
+     * attribute (a registry fact — never inferred from the plane's scope name).
+     */
+    hasOwnerId: boolean;
+}
+/**
+ * Pair one `@storageFiles` codec with its `@storageBuckets` codec through the
+ * registry's FK relations.
+ *
+ * Reads the codec's forward relations (`isReferencee` false — the files table
+ * holds the FK) and keeps those whose remote codec is tagged `@storageBuckets`.
+ * Exactly one such relation must exist; zero or several is a malformed plane
+ * and throws.
+ */
+export declare function pairStoragePlane(filesCodec: StorageCodec, pgRegistry: StoragePgRegistry): StoragePlanePair;
+/**
+ * Discover every storage plane in the registry.
+ *
+ * Pairs each `@storageFiles` codec through {@link pairStoragePlane}, then
+ * verifies no `@storageBuckets` codec was left unpaired — a buckets table with
+ * no files table referencing it is the same provisioning bug from the other
+ * side, and throws rather than being silently ignored.
+ */
+export declare function discoverStoragePlanes(pgRegistry: StoragePgRegistry): StoragePlanePair[];

package/esm/pairing.js

@@ -0,0 +1,98 @@
+/**
+ * Registry-derived storage plane discovery.
+ *
+ * A storage plane is a `@storageFiles` table and the `@storageBuckets` table it
+ * writes into. The pairing fact is the files table's foreign key to the buckets
+ * table — a relation the Graphile registry already carries — so it is read from
+ * `pgRegistry.pgRelations`, never derived from table names. Physical naming
+ * (`app_files`/`app_buckets` vs unprefixed `files`/`buckets`) is a rendering
+ * choice and carries no meaning here.
+ *
+ * A `@storageFiles` codec that cannot be paired through a real FK relation is a
+ * provisioning bug, and discovery throws at schema build rather than silently
+ * emitting a schema with no upload surface for that plane.
+ */
+function hasTag(codec, tag) {
+    return !!codec.attributes && !!codec.extensions?.tags?.[tag];
+}
+function codecSqlName(codec) {
+    const schema = codec.extensions?.pg?.schemaName;
+    const table = codec.extensions?.pg?.name ?? codec.name;
+    return schema ? `${schema}.${table}` : table;
+}
+/**
+ * Pair one `@storageFiles` codec with its `@storageBuckets` codec through the
+ * registry's FK relations.
+ *
+ * Reads the codec's forward relations (`isReferencee` false — the files table
+ * holds the FK) and keeps those whose remote codec is tagged `@storageBuckets`.
+ * Exactly one such relation must exist; zero or several is a malformed plane
+ * and throws.
+ */
+export function pairStoragePlane(filesCodec, pgRegistry) {
+    const relations = pgRegistry.pgRelations[filesCodec.name] ?? {};
+    const bucketRelations = Object.entries(relations).filter(([, relation]) => !relation.isReferencee &&
+        relation.remoteResource?.codec &&
+        hasTag(relation.remoteResource.codec, 'storageBuckets'));
+    if (bucketRelations.length === 0) {
+        throw new Error(`STORAGE_PLANE_UNPAIRED: @storageFiles table ${codecSqlName(filesCodec)} has no ` +
+            `foreign key to a @storageBuckets table in the registry. A files table must ` +
+            `reference its buckets table; check the storage module's generated FK and the ` +
+            `@storageBuckets smart tag on the buckets table.`);
+    }
+    if (bucketRelations.length > 1) {
+        const targets = bucketRelations
+            .map(([, relation]) => codecSqlName(relation.remoteResource.codec))
+            .join(', ');
+        throw new Error(`STORAGE_PLANE_AMBIGUOUS: @storageFiles table ${codecSqlName(filesCodec)} has ` +
+            `foreign keys to ${bucketRelations.length} @storageBuckets tables (${targets}); ` +
+            `a files table must reference exactly one buckets table.`);
+    }
+    const [relationName, relation] = bucketRelations[0];
+    const bucketsCodec = relation.remoteResource.codec;
+    return {
+        filesCodec,
+        bucketsCodec,
+        relationName,
+        fkAttributes: [...relation.localAttributes],
+        hasOwnerId: !!bucketsCodec.attributes?.owner_id,
+    };
+}
+/**
+ * Discover every storage plane in the registry.
+ *
+ * Pairs each `@storageFiles` codec through {@link pairStoragePlane}, then
+ * verifies no `@storageBuckets` codec was left unpaired — a buckets table with
+ * no files table referencing it is the same provisioning bug from the other
+ * side, and throws rather than being silently ignored.
+ */
+export function discoverStoragePlanes(pgRegistry) {
+    const codecs = Object.values(pgRegistry.pgCodecs);
+    const filesCodecs = codecs.filter((codec) => hasTag(codec, 'storageFiles'));
+    const bucketsCodecs = codecs.filter((codec) => hasTag(codec, 'storageBuckets'));
+    const pairs = filesCodecs.map((filesCodec) => pairStoragePlane(filesCodec, pgRegistry));
+    const bucketsPairCounts = new Map();
+    for (const pair of pairs) {
+        const existing = bucketsPairCounts.get(pair.bucketsCodec) ?? [];
+        existing.push(pair);
+        bucketsPairCounts.set(pair.bucketsCodec, existing);
+    }
+    for (const [bucketsCodec, bucketPairs] of bucketsPairCounts) {
+        if (bucketPairs.length > 1) {
+            const sources = bucketPairs.map((pair) => codecSqlName(pair.filesCodec)).join(', ');
+            throw new Error(`STORAGE_PLANE_AMBIGUOUS: @storageBuckets table ${codecSqlName(bucketsCodec)} is ` +
+                `referenced by ${bucketPairs.length} @storageFiles tables (${sources}); every ` +
+                `buckets table must be the FK target of exactly one files table.`);
+        }
+    }
+    const pairedBuckets = new Set(pairs.map((pair) => pair.bucketsCodec));
+    const orphanBuckets = bucketsCodecs.filter((codec) => !pairedBuckets.has(codec));
+    if (orphanBuckets.length > 0) {
+        const names = orphanBuckets.map(codecSqlName).join(', ');
+        throw new Error(`STORAGE_PLANE_UNPAIRED: @storageBuckets table(s) ${names} are referenced by no ` +
+            `@storageFiles table. Every buckets table must be the FK target of exactly one ` +
+            `files table; check the storage module's generated FK and the @storageFiles ` +
+            `smart tag on the files table.`);
+    }
+    return pairs;
+}

package/index.d.ts

@@ -0,0 +1,4 @@
+export type { StorageInflection, UploadSurfaceNames } from './naming';
+export { DOWNLOAD_URL_FIELD, uploadSurfaceNames } from './naming';
+export type { StorageCodec, StorageCodecAttributes, StorageCodecRelation, StoragePgRegistry, StoragePlanePair, } from './pairing';
+export { discoverStoragePlanes, pairStoragePlane } from './pairing';

package/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pairStoragePlane = exports.discoverStoragePlanes = exports.uploadSurfaceNames = exports.DOWNLOAD_URL_FIELD = void 0;
+var naming_1 = require("./naming");
+Object.defineProperty(exports, "DOWNLOAD_URL_FIELD", { enumerable: true, get: function () { return naming_1.DOWNLOAD_URL_FIELD; } });
+Object.defineProperty(exports, "uploadSurfaceNames", { enumerable: true, get: function () { return naming_1.uploadSurfaceNames; } });
+var pairing_1 = require("./pairing");
+Object.defineProperty(exports, "discoverStoragePlanes", { enumerable: true, get: function () { return pairing_1.discoverStoragePlanes; } });
+Object.defineProperty(exports, "pairStoragePlane", { enumerable: true, get: function () { return pairing_1.pairStoragePlane; } });

package/naming.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical names of a storage plane's upload surface.
+ *
+ * The presigned-url plugin emits these fields and types; anything that reports
+ * or consumes the surface (the `_meta` storage section, dynamic clients) must
+ * derive the same names from the same inflection facts. This module is the one
+ * definition of that derivation, so the emitter and the reporters cannot
+ * disagree.
+ */
+import type { StorageCodec } from './pairing';
+/**
+ * The computed field the download plugin adds to every files type. One
+ * definition so the emitter (download-url-field.ts) and the reporters
+ * (`_meta`, dynamic clients) cannot disagree.
+ */
+export declare const DOWNLOAD_URL_FIELD = "downloadUrl";
+/** The slice of `build.inflection` the naming derivation reads. */
+export interface StorageInflection {
+    tableType(codec: StorageCodec): string;
+}
+/** The GraphQL names of one plane's upload surface. */
+export interface UploadSurfaceNames {
+    /** GraphQL type name of the files table (e.g. `AppFile`). */
+    filesTypeName: string;
+    /** Single upload mutation field (e.g. `uploadAppFile`). */
+    uploadMutation: string;
+    /** Input type of the single upload mutation (e.g. `UploadAppFileInput`). */
+    uploadInputType: string;
+    /** Payload type of the single upload mutation (e.g. `UploadAppFilePayload`). */
+    uploadPayloadType: string;
+    /** Bulk upload mutation field (e.g. `uploadAppFiles`). */
+    bulkUploadMutation: string;
+    /** Input type of the bulk upload mutation (e.g. `UploadAppFileBulkInput`). */
+    bulkUploadInputType: string;
+    /** Payload type of the bulk upload mutation (e.g. `UploadAppFileBulkPayload`). */
+    bulkUploadPayloadType: string;
+    /** Per-file input type inside the bulk input (e.g. `UploadAppFileBulkFileInput`). */
+    bulkUploadFileInputType: string;
+    /** Per-file payload type inside the bulk payload (e.g. `UploadAppFileBulkFilePayload`). */
+    bulkUploadFilePayloadType: string;
+}
+/**
+ * Derive the upload surface names for a plane's files codec.
+ */
+export declare function uploadSurfaceNames(inflection: StorageInflection, filesCodec: StorageCodec): UploadSurfaceNames;

package/naming.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Canonical names of a storage plane's upload surface.
+ *
+ * The presigned-url plugin emits these fields and types; anything that reports
+ * or consumes the surface (the `_meta` storage section, dynamic clients) must
+ * derive the same names from the same inflection facts. This module is the one
+ * definition of that derivation, so the emitter and the reporters cannot
+ * disagree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOWNLOAD_URL_FIELD = void 0;
+exports.uploadSurfaceNames = uploadSurfaceNames;
+/**
+ * The computed field the download plugin adds to every files type. One
+ * definition so the emitter (download-url-field.ts) and the reporters
+ * (`_meta`, dynamic clients) cannot disagree.
+ */
+exports.DOWNLOAD_URL_FIELD = 'downloadUrl';
+/**
+ * Derive the upload surface names for a plane's files codec.
+ */
+function uploadSurfaceNames(inflection, filesCodec) {
+    const filesTypeName = inflection.tableType(filesCodec);
+    return {
+        filesTypeName,
+        uploadMutation: `upload${filesTypeName}`,
+        uploadInputType: `Upload${filesTypeName}Input`,
+        uploadPayloadType: `Upload${filesTypeName}Payload`,
+        bulkUploadMutation: `upload${filesTypeName}s`,
+        bulkUploadInputType: `Upload${filesTypeName}BulkInput`,
+        bulkUploadPayloadType: `Upload${filesTypeName}BulkPayload`,
+        bulkUploadFileInputType: `Upload${filesTypeName}BulkFileInput`,
+        bulkUploadFilePayloadType: `Upload${filesTypeName}BulkFilePayload`,
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "graphile-storage-registry",
+  "version": "0.1.0",
+  "description": "Registry-derived storage plane discovery for PostGraphile v5 — pairs @storageFiles/@storageBuckets codecs through their actual foreign-key relations and derives the canonical upload surface names, so no table name is ever load-bearing",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "makage": "^0.3.0"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "storage",
+    "registry",
+    "plugin",
+    "postgres",
+    "graphql"
+  ],
+  "gitHead": "d10fe91ede80a4c2dfe2c1c6dcf6fe7193784eba"
+}

package/pairing.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Registry-derived storage plane discovery.
+ *
+ * A storage plane is a `@storageFiles` table and the `@storageBuckets` table it
+ * writes into. The pairing fact is the files table's foreign key to the buckets
+ * table — a relation the Graphile registry already carries — so it is read from
+ * `pgRegistry.pgRelations`, never derived from table names. Physical naming
+ * (`app_files`/`app_buckets` vs unprefixed `files`/`buckets`) is a rendering
+ * choice and carries no meaning here.
+ *
+ * A `@storageFiles` codec that cannot be paired through a real FK relation is a
+ * provisioning bug, and discovery throws at schema build rather than silently
+ * emitting a schema with no upload surface for that plane.
+ */
+/** The attributes shape shared by pg codecs. */
+export interface StorageCodecAttributes {
+    [attributeName: string]: unknown;
+}
+/**
+ * The slice of a Graphile pg codec that storage discovery reads. Structural on
+ * purpose: callers pass real codecs from `build.input.pgRegistry`, and this
+ * package stays free of graphile-build peer dependencies.
+ */
+export interface StorageCodec {
+    name: string;
+    attributes?: StorageCodecAttributes;
+    extensions?: {
+        pg?: {
+            schemaName?: string;
+            name?: string;
+        };
+        tags?: {
+            storageFiles?: unknown;
+            storageBuckets?: unknown;
+            [tag: string]: unknown;
+        };
+    };
+}
+/** The slice of a registry relation entry that storage discovery reads. */
+export interface StorageCodecRelation {
+    isReferencee?: boolean;
+    localAttributes: readonly string[];
+    remoteAttributes: readonly string[];
+    remoteResource?: {
+        codec?: StorageCodec;
+    };
+}
+/** The slice of `build.input.pgRegistry` that storage discovery reads. */
+export interface StoragePgRegistry {
+    pgCodecs: Record<string, StorageCodec>;
+    pgRelations: Record<string, Record<string, StorageCodecRelation>>;
+}
+/**
+ * A discovered storage plane: the files codec, the buckets codec its FK names,
+ * and the facts a plugin needs to shape the plane's GraphQL surface.
+ */
+export interface StoragePlanePair {
+    filesCodec: StorageCodec;
+    bucketsCodec: StorageCodec;
+    /** Registry name of the FK relation on the files codec (e.g. `bucketsByMyBucketId`). */
+    relationName: string;
+    /** FK attribute(s) on the files table referencing the buckets table (e.g. `['bucket_id']`). */
+    fkAttributes: string[];
+    /**
+     * Whether the plane is entity-keyed: the buckets table carries an `owner_id`
+     * attribute (a registry fact — never inferred from the plane's scope name).
+     */
+    hasOwnerId: boolean;
+}
+/**
+ * Pair one `@storageFiles` codec with its `@storageBuckets` codec through the
+ * registry's FK relations.
+ *
+ * Reads the codec's forward relations (`isReferencee` false — the files table
+ * holds the FK) and keeps those whose remote codec is tagged `@storageBuckets`.
+ * Exactly one such relation must exist; zero or several is a malformed plane
+ * and throws.
+ */
+export declare function pairStoragePlane(filesCodec: StorageCodec, pgRegistry: StoragePgRegistry): StoragePlanePair;
+/**
+ * Discover every storage plane in the registry.
+ *
+ * Pairs each `@storageFiles` codec through {@link pairStoragePlane}, then
+ * verifies no `@storageBuckets` codec was left unpaired — a buckets table with
+ * no files table referencing it is the same provisioning bug from the other
+ * side, and throws rather than being silently ignored.
+ */
+export declare function discoverStoragePlanes(pgRegistry: StoragePgRegistry): StoragePlanePair[];

package/pairing.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Registry-derived storage plane discovery.
+ *
+ * A storage plane is a `@storageFiles` table and the `@storageBuckets` table it
+ * writes into. The pairing fact is the files table's foreign key to the buckets
+ * table — a relation the Graphile registry already carries — so it is read from
+ * `pgRegistry.pgRelations`, never derived from table names. Physical naming
+ * (`app_files`/`app_buckets` vs unprefixed `files`/`buckets`) is a rendering
+ * choice and carries no meaning here.
+ *
+ * A `@storageFiles` codec that cannot be paired through a real FK relation is a
+ * provisioning bug, and discovery throws at schema build rather than silently
+ * emitting a schema with no upload surface for that plane.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pairStoragePlane = pairStoragePlane;
+exports.discoverStoragePlanes = discoverStoragePlanes;
+function hasTag(codec, tag) {
+    return !!codec.attributes && !!codec.extensions?.tags?.[tag];
+}
+function codecSqlName(codec) {
+    const schema = codec.extensions?.pg?.schemaName;
+    const table = codec.extensions?.pg?.name ?? codec.name;
+    return schema ? `${schema}.${table}` : table;
+}
+/**
+ * Pair one `@storageFiles` codec with its `@storageBuckets` codec through the
+ * registry's FK relations.
+ *
+ * Reads the codec's forward relations (`isReferencee` false — the files table
+ * holds the FK) and keeps those whose remote codec is tagged `@storageBuckets`.
+ * Exactly one such relation must exist; zero or several is a malformed plane
+ * and throws.
+ */
+function pairStoragePlane(filesCodec, pgRegistry) {
+    const relations = pgRegistry.pgRelations[filesCodec.name] ?? {};
+    const bucketRelations = Object.entries(relations).filter(([, relation]) => !relation.isReferencee &&
+        relation.remoteResource?.codec &&
+        hasTag(relation.remoteResource.codec, 'storageBuckets'));
+    if (bucketRelations.length === 0) {
+        throw new Error(`STORAGE_PLANE_UNPAIRED: @storageFiles table ${codecSqlName(filesCodec)} has no ` +
+            `foreign key to a @storageBuckets table in the registry. A files table must ` +
+            `reference its buckets table; check the storage module's generated FK and the ` +
+            `@storageBuckets smart tag on the buckets table.`);
+    }
+    if (bucketRelations.length > 1) {
+        const targets = bucketRelations
+            .map(([, relation]) => codecSqlName(relation.remoteResource.codec))
+            .join(', ');
+        throw new Error(`STORAGE_PLANE_AMBIGUOUS: @storageFiles table ${codecSqlName(filesCodec)} has ` +
+            `foreign keys to ${bucketRelations.length} @storageBuckets tables (${targets}); ` +
+            `a files table must reference exactly one buckets table.`);
+    }
+    const [relationName, relation] = bucketRelations[0];
+    const bucketsCodec = relation.remoteResource.codec;
+    return {
+        filesCodec,
+        bucketsCodec,
+        relationName,
+        fkAttributes: [...relation.localAttributes],
+        hasOwnerId: !!bucketsCodec.attributes?.owner_id,
+    };
+}
+/**
+ * Discover every storage plane in the registry.
+ *
+ * Pairs each `@storageFiles` codec through {@link pairStoragePlane}, then
+ * verifies no `@storageBuckets` codec was left unpaired — a buckets table with
+ * no files table referencing it is the same provisioning bug from the other
+ * side, and throws rather than being silently ignored.
+ */
+function discoverStoragePlanes(pgRegistry) {
+    const codecs = Object.values(pgRegistry.pgCodecs);
+    const filesCodecs = codecs.filter((codec) => hasTag(codec, 'storageFiles'));
+    const bucketsCodecs = codecs.filter((codec) => hasTag(codec, 'storageBuckets'));
+    const pairs = filesCodecs.map((filesCodec) => pairStoragePlane(filesCodec, pgRegistry));
+    const bucketsPairCounts = new Map();
+    for (const pair of pairs) {
+        const existing = bucketsPairCounts.get(pair.bucketsCodec) ?? [];
+        existing.push(pair);
+        bucketsPairCounts.set(pair.bucketsCodec, existing);
+    }
+    for (const [bucketsCodec, bucketPairs] of bucketsPairCounts) {
+        if (bucketPairs.length > 1) {
+            const sources = bucketPairs.map((pair) => codecSqlName(pair.filesCodec)).join(', ');
+            throw new Error(`STORAGE_PLANE_AMBIGUOUS: @storageBuckets table ${codecSqlName(bucketsCodec)} is ` +
+                `referenced by ${bucketPairs.length} @storageFiles tables (${sources}); every ` +
+                `buckets table must be the FK target of exactly one files table.`);
+        }
+    }
+    const pairedBuckets = new Set(pairs.map((pair) => pair.bucketsCodec));
+    const orphanBuckets = bucketsCodecs.filter((codec) => !pairedBuckets.has(codec));
+    if (orphanBuckets.length > 0) {
+        const names = orphanBuckets.map(codecSqlName).join(', ');
+        throw new Error(`STORAGE_PLANE_UNPAIRED: @storageBuckets table(s) ${names} are referenced by no ` +
+            `@storageFiles table. Every buckets table must be the FK target of exactly one ` +
+            `files table; check the storage module's generated FK and the @storageFiles ` +
+            `smart tag on the files table.`);
+    }
+    return pairs;
+}