graphile-settings 5.15.1 → 5.16.0

package/esm/plugins/meta-schema/graphql-meta-field.js

@@ -1,4 +1,4 @@
-import { GraphQLBoolean, GraphQLFloat, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLString, } from 'graphql';
+import { GraphQLBoolean, GraphQLFloat, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLString } from 'graphql';
 function nn(type) {
     return new GraphQLNonNull(type);
 }
@@ -15,16 +15,16 @@ function createMetaSchemaType() {
             isArray: { type: nn(GraphQLBoolean) },
             isNotNull: { type: GraphQLBoolean },
             hasDefault: { type: GraphQLBoolean },
-            subtype: { type: GraphQLString },
-        }),
+            subtype: { type: GraphQLString }
+        })
     });
     const MetaEnumType = new GraphQLObjectType({
         name: 'MetaEnum',
         description: 'Information about a PostgreSQL enum type',
         fields: () => ({
             name: { type: nn(GraphQLString), description: 'The PostgreSQL enum type name' },
-            values: { type: nnList(GraphQLString), description: 'Allowed values for this enum' },
-        }),
+            values: { type: nnList(GraphQLString), description: 'Allowed values for this enum' }
+        })
     });
     const MetaFieldType = new GraphQLObjectType({
         name: 'MetaField',
@@ -37,8 +37,8 @@ function createMetaSchemaType() {
             isPrimaryKey: { type: nn(GraphQLBoolean) },
             isForeignKey: { type: nn(GraphQLBoolean) },
             description: { type: GraphQLString },
-            enumValues: { type: MetaEnumType, description: 'Enum metadata if this field has an enum type' },
-        }),
+            enumValues: { type: MetaEnumType, description: 'Enum metadata if this field has an enum type' }
+        })
     });
     const MetaIndexType = new GraphQLObjectType({
         name: 'MetaIndex',
@@ -48,31 +48,31 @@ function createMetaSchemaType() {
             isUnique: { type: nn(GraphQLBoolean) },
             isPrimary: { type: nn(GraphQLBoolean) },
             columns: { type: nnList(GraphQLString) },
-            fields: { type: new GraphQLList(nn(MetaFieldType)) },
-        }),
+            fields: { type: new GraphQLList(nn(MetaFieldType)) }
+        })
     });
     const MetaPrimaryKeyConstraintType = new GraphQLObjectType({
         name: 'MetaPrimaryKeyConstraint',
         description: 'Information about a primary key constraint',
         fields: () => ({
             name: { type: nn(GraphQLString) },
-            fields: { type: nnList(MetaFieldType) },
-        }),
+            fields: { type: nnList(MetaFieldType) }
+        })
     });
     const MetaUniqueConstraintType = new GraphQLObjectType({
         name: 'MetaUniqueConstraint',
         description: 'Information about a unique constraint',
         fields: () => ({
             name: { type: nn(GraphQLString) },
-            fields: { type: nnList(MetaFieldType) },
-        }),
+            fields: { type: nnList(MetaFieldType) }
+        })
     });
     const MetaRefTableType = new GraphQLObjectType({
         name: 'MetaRefTable',
         description: 'Reference to a related table',
         fields: () => ({
-            name: { type: nn(GraphQLString) },
-        }),
+            name: { type: nn(GraphQLString) }
+        })
     });
     const MetaForeignKeyConstraintType = new GraphQLObjectType({
         name: 'MetaForeignKeyConstraint',
@@ -83,8 +83,8 @@ function createMetaSchemaType() {
             referencedTable: { type: nn(GraphQLString) },
             referencedFields: { type: nnList(GraphQLString) },
             refFields: { type: new GraphQLList(nn(MetaFieldType)) },
-            refTable: { type: MetaRefTableType },
-        }),
+            refTable: { type: MetaRefTableType }
+        })
     });
     const MetaConstraintsType = new GraphQLObjectType({
         name: 'MetaConstraints',
@@ -92,8 +92,8 @@ function createMetaSchemaType() {
         fields: () => ({
             primaryKey: { type: MetaPrimaryKeyConstraintType },
             unique: { type: nnList(MetaUniqueConstraintType) },
-            foreignKey: { type: nnList(MetaForeignKeyConstraintType) },
-        }),
+            foreignKey: { type: nnList(MetaForeignKeyConstraintType) }
+        })
     });
     const MetaInflectionType = new GraphQLObjectType({
         name: 'MetaInflection',
@@ -110,8 +110,8 @@ function createMetaSchemaType() {
             createInputType: { type: nn(GraphQLString) },
             createPayloadType: { type: nn(GraphQLString) },
             updatePayloadType: { type: GraphQLString },
-            deletePayloadType: { type: nn(GraphQLString) },
-        }),
+            deletePayloadType: { type: nn(GraphQLString) }
+        })
     });
     const MetaQueryType = new GraphQLObjectType({
         name: 'MetaQuery',
@@ -121,8 +121,8 @@ function createMetaSchemaType() {
             one: { type: GraphQLString },
             create: { type: GraphQLString },
             update: { type: GraphQLString },
-            delete: { type: GraphQLString },
-        }),
+            delete: { type: GraphQLString }
+        })
     });
     const MetaBelongsToRelationType = new GraphQLObjectType({
         name: 'MetaBelongsToRelation',
@@ -132,8 +132,8 @@ function createMetaSchemaType() {
             isUnique: { type: nn(GraphQLBoolean) },
             type: { type: GraphQLString },
             keys: { type: nnList(MetaFieldType) },
-            references: { type: nn(MetaRefTableType) },
-        }),
+            references: { type: nn(MetaRefTableType) }
+        })
     });
     const MetaHasRelationType = new GraphQLObjectType({
         name: 'MetaHasRelation',
@@ -143,8 +143,8 @@ function createMetaSchemaType() {
             isUnique: { type: nn(GraphQLBoolean) },
             type: { type: GraphQLString },
             keys: { type: nnList(MetaFieldType) },
-            referencedBy: { type: nn(MetaRefTableType) },
-        }),
+            referencedBy: { type: nn(MetaRefTableType) }
+        })
     });
     const MetaManyToManyRelationType = new GraphQLObjectType({
         name: 'MetaManyToManyRelation',
@@ -159,8 +159,8 @@ function createMetaSchemaType() {
             junctionRightKeyAttributes: { type: nnList(MetaFieldType) },
             leftKeyAttributes: { type: nnList(MetaFieldType) },
             rightKeyAttributes: { type: nnList(MetaFieldType) },
-            rightTable: { type: nn(MetaRefTableType) },
-        }),
+            rightTable: { type: nn(MetaRefTableType) }
+        })
     });
     const MetaRelationsType = new GraphQLObjectType({
         name: 'MetaRelations',
@@ -170,16 +170,16 @@ function createMetaSchemaType() {
             has: { type: nnList(MetaHasRelationType) },
             hasOne: { type: nnList(MetaHasRelationType) },
             hasMany: { type: nnList(MetaHasRelationType) },
-            manyToMany: { type: nnList(MetaManyToManyRelationType) },
-        }),
+            manyToMany: { type: nnList(MetaManyToManyRelationType) }
+        })
     });
     const MetaStorageType = new GraphQLObjectType({
         name: 'MetaStorage',
         description: 'Storage metadata for a table',
         fields: () => ({
             isFilesTable: { type: nn(GraphQLBoolean), description: 'Whether this table is a storage files table' },
-            isBucketsTable: { type: nn(GraphQLBoolean), description: 'Whether this table is a storage buckets table' },
-        }),
+            isBucketsTable: { type: nn(GraphQLBoolean), description: 'Whether this table is a storage buckets table' }
+        })
     });
     const MetaSearchConfigType = new GraphQLObjectType({
         name: 'MetaSearchConfig',
@@ -190,20 +190,20 @@ function createMetaSchemaType() {
                 description: 'JSON-encoded per-adapter score weights',
                 resolve(source) {
                     return source.weights ? JSON.stringify(source.weights) : null;
-                },
+                }
             },
             boostRecent: { type: nn(GraphQLBoolean), description: 'Whether recency boosting is enabled' },
             boostRecencyField: { type: GraphQLString, description: 'Field used for recency decay' },
-            boostRecencyDecay: { type: GraphQLFloat, description: 'Exponential decay factor per day' },
-        }),
+            boostRecencyDecay: { type: GraphQLFloat, description: 'Exponential decay factor per day' }
+        })
     });
     const MetaSearchColumnType = new GraphQLObjectType({
         name: 'MetaSearchColumn',
         description: 'A searchable column with its algorithm',
         fields: () => ({
             name: { type: nn(GraphQLString), description: 'Column name (camelCase)' },
-            algorithm: { type: nn(GraphQLString), description: 'Search algorithm: tsvector, bm25, trgm, or vector' },
-        }),
+            algorithm: { type: nn(GraphQLString), description: 'Search algorithm: tsvector, bm25, trgm, or vector' }
+        })
     });
     const MetaSearchType = new GraphQLObjectType({
         name: 'MetaSearch',
@@ -212,31 +212,42 @@ function createMetaSchemaType() {
             algorithms: { type: nnList(GraphQLString), description: 'Active search algorithms on this table' },
             columns: { type: nnList(MetaSearchColumnType), description: 'Searchable columns with their algorithm' },
             hasUnifiedSearch: { type: nn(GraphQLBoolean), description: 'Whether unifiedSearch composite filter is available' },
-            config: { type: MetaSearchConfigType, description: 'Per-table search configuration' },
-        }),
+            config: { type: MetaSearchConfigType, description: 'Per-table search configuration' }
+        })
     });
     const MetaI18nFieldType = new GraphQLObjectType({
         name: 'MetaI18nField',
         description: 'A translatable field',
         fields: () => ({
             name: { type: nn(GraphQLString), description: 'GraphQL field name' },
-            type: { type: nn(GraphQLString), description: 'PostgreSQL column type (text, citext)' },
-        }),
+            type: { type: nn(GraphQLString), description: 'PostgreSQL column type (text, citext)' }
+        })
     });
     const MetaI18nType = new GraphQLObjectType({
         name: 'MetaI18n',
         description: 'i18n metadata for a table with @i18n tag',
         fields: () => ({
             translationTable: { type: nn(GraphQLString), description: 'Name of the translation table' },
-            translatableFields: { type: nnList(MetaI18nFieldType), description: 'Fields that are translatable' },
-        }),
+            translatableFields: { type: nnList(MetaI18nFieldType), description: 'Fields that are translatable' }
+        })
     });
     const MetaRealtimeType = new GraphQLObjectType({
         name: 'MetaRealtime',
         description: 'Realtime metadata for a table with @realtime tag',
         fields: () => ({
-            subscriptionFieldName: { type: nn(GraphQLString), description: 'The generated subscription field name (e.g. onPostChanged)' },
-        }),
+            subscriptionFieldName: { type: nn(GraphQLString), description: 'The generated subscription field name (e.g. onPostChanged)' }
+        })
+    });
+    const MetaScopeType = new GraphQLObjectType({
+        name: 'MetaScope',
+        description: 'Provisioning scope metadata for a table',
+        fields: () => ({
+            scope: { type: nn(GraphQLString), description: "Provisioning scope: 'platform', 'app', 'database', or an entity scope (e.g. 'org')" },
+            tier: { type: nn(GraphQLString), description: "Coarse bucket: 'global', 'database', or 'entity'" },
+            keyColumn: { type: GraphQLString, description: 'Inflected scope key column (e.g. databaseId, orgId), null for global tiers' },
+            entityTable: { type: GraphQLString, description: 'SQL name of the entity table for entity scopes, else null' },
+            source: { type: nn(GraphQLString), description: "Provenance of the scope metadata (always 'smartTag')" }
+        })
     });
     const MetaTableType = new GraphQLObjectType({
         name: 'MetaTable',
@@ -257,14 +268,15 @@ function createMetaSchemaType() {
             search: { type: MetaSearchType, description: 'Search metadata (null if no search configured)' },
             i18n: { type: MetaI18nType, description: 'i18n metadata (null if no @i18n tag)' },
             realtime: { type: MetaRealtimeType, description: 'Realtime metadata (null if no @realtime tag)' },
-        }),
+            scope: { type: MetaScopeType, description: 'Provisioning scope metadata (null if no @scope tag)' }
+        })
     });
     return new GraphQLObjectType({
         name: 'MetaSchema',
         description: 'Root meta schema type',
         fields: () => ({
-            tables: { type: nnList(MetaTableType) },
-        }),
+            tables: { type: nnList(MetaTableType) }
+        })
     });
 }
 export function extendQueryWithMetaField(fields, tablesMeta) {
@@ -274,10 +286,10 @@ export function extendQueryWithMetaField(fields, tablesMeta) {
         description: 'Metadata about the database schema, including tables, fields, indexes, and constraints. Useful for code generation tools.',
         resolve() {
             return { tables: tablesMeta };
-        },
+        }
     };
     return {
         ...fields,
-        _meta: metaField,
+        _meta: metaField
     };
 }

package/esm/plugins/meta-schema/scope-meta-builders.d.ts

@@ -0,0 +1,15 @@
+import type { PgCodec, ScopeMeta } from './types';
+/**
+ * Detect provisioning scope metadata for a table.
+ *
+ * The `@scope` smart tag emitted by the constructive-db generators is the sole
+ * source of truth. `apply_scope_fields` knows the exact scope, tier, key column,
+ * and entity table, and emits them via
+ * `metaschema.append_table_smart_tags(id, { scope, scopeTier, scopeKey, scopeEntityTable })`.
+ * PostGraphile surfaces these as `codec.extensions.tags.*`.
+ *
+ * There is NO inference from column names — a table without the tag returns
+ * `null` (the same convention as every other nullable metadata block). This
+ * avoids guessing key columns, whose names are chosen freely by each generator.
+ */
+export declare function buildScopeMeta(codec: PgCodec, inflectAttr: (attrName: string, codec: PgCodec) => string): ScopeMeta | null;

package/esm/plugins/meta-schema/scope-meta-builders.js

@@ -0,0 +1,40 @@
+const VALID_TIERS = new Set(['global', 'database', 'entity']);
+function readString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Detect provisioning scope metadata for a table.
+ *
+ * The `@scope` smart tag emitted by the constructive-db generators is the sole
+ * source of truth. `apply_scope_fields` knows the exact scope, tier, key column,
+ * and entity table, and emits them via
+ * `metaschema.append_table_smart_tags(id, { scope, scopeTier, scopeKey, scopeEntityTable })`.
+ * PostGraphile surfaces these as `codec.extensions.tags.*`.
+ *
+ * There is NO inference from column names — a table without the tag returns
+ * `null` (the same convention as every other nullable metadata block). This
+ * avoids guessing key columns, whose names are chosen freely by each generator.
+ */
+export function buildScopeMeta(codec, inflectAttr) {
+    const tags = codec.extensions?.tags;
+    const scope = readString(tags?.scope);
+    if (!scope)
+        return null;
+    const rawTier = readString(tags.scopeTier);
+    const tier = rawTier && VALID_TIERS.has(rawTier)
+        ? rawTier
+        : null;
+    if (!tier) {
+        throw new Error(`@scope tag on codec "${codec.name}" is missing a valid scopeTier ` +
+            `(expected one of global|database|entity, got ${JSON.stringify(rawTier)})`);
+    }
+    const keyColumn = readString(tags.scopeKey);
+    const entityTable = readString(tags.scopeEntityTable);
+    return {
+        scope,
+        tier,
+        keyColumn: keyColumn ? inflectAttr(keyColumn, codec) : null,
+        entityTable,
+        source: 'smartTag'
+    };
+}

package/esm/plugins/meta-schema/table-meta-builder.js

@@ -1,10 +1,11 @@
-import { buildForeignKeyConstraints, buildIndexes, buildPrimaryKey, buildUniqueConstraints, } from './constraint-meta-builders';
+import { buildForeignKeyConstraints, buildIndexes, buildPrimaryKey, buildUniqueConstraints } from './constraint-meta-builders';
 import { buildInflectionMeta, buildQueryMeta, resolveTableType } from './name-meta-builders';
-import { buildBelongsToRelations, buildManyToManyRelations, buildReverseRelations, } from './relation-meta-builders';
-import { buildStorageMeta, buildSearchMeta, buildI18nMeta, buildRealtimeMeta } from './storage-search-meta-builders';
+import { buildBelongsToRelations, buildManyToManyRelations, buildReverseRelations } from './relation-meta-builders';
+import { buildScopeMeta } from './scope-meta-builders';
+import { buildI18nMeta, buildRealtimeMeta, buildSearchMeta, buildStorageMeta } from './storage-search-meta-builders';
+import { createBuildContext } from './table-meta-context';
+import { getConfiguredSchemas, getRelations, getSchemaName, getUniques, isTableResource } from './table-resource-utils';
 import { buildFieldMeta } from './type-mappings';
-import { createBuildContext, } from './table-meta-context';
-import { getConfiguredSchemas, getRelations, getSchemaName, getUniques, isTableResource, } from './table-resource-utils';
 function buildTableMeta(resource, schemaName, context) {
     const codec = resource.codec;
     const attributes = codec.attributes;
@@ -27,7 +28,7 @@ function buildTableMeta(resource, schemaName, context) {
     }
     const fields = Object.entries(attributes).map(([attrName, attr]) => buildFieldMeta(context.inflectAttr(attrName, codec), attr, context.build, {
         isPrimaryKey: pkAttrNames.has(attrName),
-        isForeignKey: fkAttrNames.has(attrName),
+        isForeignKey: fkAttrNames.has(attrName)
     }));
     const indexes = buildIndexes(codec, attributes, uniques, context);
     const primaryKey = buildPrimaryKey(codec, attributes, uniques, context);
@@ -36,7 +37,7 @@ function buildTableMeta(resource, schemaName, context) {
     const constraints = {
         primaryKey,
         unique: uniqueConstraints,
-        foreignKey: foreignKeyConstraints,
+        foreignKey: foreignKeyConstraints
     };
     const belongsTo = buildBelongsToRelations(codec, attributes, uniques, relations, context);
     const { hasOne, hasMany } = buildReverseRelations(codec, attributes, relations, context);
@@ -46,13 +47,14 @@ function buildTableMeta(resource, schemaName, context) {
         has: [...hasOne, ...hasMany],
         hasOne,
         hasMany,
-        manyToMany,
+        manyToMany
     };
     const tableType = resolveTableType(context.build, codec);
     const storage = buildStorageMeta(codec);
     const search = buildSearchMeta(codec, context.build, context.inflectAttr);
     const i18n = buildI18nMeta(codec, context.build, context.inflectAttr);
     const realtime = buildRealtimeMeta(codec, context.build);
+    const scope = buildScopeMeta(codec, context.inflectAttr);
     return {
         name: tableType,
         schemaName,
@@ -69,6 +71,7 @@ function buildTableMeta(resource, schemaName, context) {
         search,
         i18n,
         realtime,
+        scope
     };
 }
 export function collectTablesMeta(build) {

package/esm/plugins/meta-schema/types.d.ts

@@ -14,6 +14,21 @@ export interface TableMeta {
     search: SearchMeta | null;
     i18n: I18nMeta | null;
     realtime: RealtimeMeta | null;
+    scope: ScopeMeta | null;
+}
+/** Coarse provisioning tier a table's scope belongs to. */
+export type ScopeTier = 'global' | 'database' | 'entity';
+export interface ScopeMeta {
+    /** The provisioning scope, e.g. 'platform', 'app', 'database', 'org', 'user' */
+    scope: string;
+    /** Coarse bucket: global (platform/app), database, or entity */
+    tier: ScopeTier;
+    /** Inflected scope key column (e.g. 'databaseId', 'orgId'), or null for global tiers */
+    keyColumn: string | null;
+    /** SQL name of the entity table for entity scopes, else null */
+    entityTable: string | null;
+    /** Provenance of the scope metadata. Always the @scope smart tag. */
+    source: 'smartTag';
 }
 export interface StorageMeta {
     /** Whether this table is tagged as a storage files table */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-settings",
-  "version": "5.15.1",
+  "version": "5.16.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "graphile settings",
   "main": "index.js",
@@ -31,16 +31,16 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1052.0",
     "@constructive-io/bucket-provisioner": "^0.14.0",
-    "@constructive-io/graphql-env": "^3.16.1",
-    "@constructive-io/graphql-types": "^3.14.1",
-    "@constructive-io/s3-streamer": "^2.29.1",
+    "@constructive-io/graphql-env": "^3.16.2",
+    "@constructive-io/graphql-types": "^3.14.2",
+    "@constructive-io/s3-streamer": "^2.29.2",
     "@constructive-io/s3-utils": "^2.20.0",
     "@constructive-io/upload-names": "^2.19.0",
     "@dataplan/json": "1.0.0",
     "@dataplan/pg": "1.0.3",
     "@graphile-contrib/pg-many-to-many": "2.0.0-rc.2",
     "@pgpmjs/logger": "^2.14.0",
-    "@pgpmjs/types": "^2.35.0",
+    "@pgpmjs/types": "^2.35.1",
     "@pgsql/quotes": "^17.1.0",
     "cors": "^2.8.6",
     "express": "^5.2.1",
@@ -49,17 +49,17 @@
     "graphile-bucket-provisioner-plugin": "0.14.0",
     "graphile-build": "5.0.2",
     "graphile-build-pg": "5.0.2",
-    "graphile-bulk-mutations": "^0.9.1",
+    "graphile-bulk-mutations": "^0.9.2",
     "graphile-config": "1.0.1",
-    "graphile-connection-filter": "^1.16.1",
-    "graphile-i18n": "^1.6.1",
-    "graphile-llm": "^0.19.1",
-    "graphile-ltree": "^1.14.1",
-    "graphile-pg-aggregates": "^1.10.1",
-    "graphile-postgis": "^2.23.1",
+    "graphile-connection-filter": "^1.16.2",
+    "graphile-i18n": "^1.6.2",
+    "graphile-llm": "^0.19.2",
+    "graphile-ltree": "^1.14.2",
+    "graphile-pg-aggregates": "^1.10.2",
+    "graphile-postgis": "^2.23.2",
     "graphile-presigned-url-plugin": "^0.22.1",
     "graphile-realtime-subscriptions": "^0.10.0",
-    "graphile-search": "^1.21.1",
+    "graphile-search": "^1.21.2",
     "graphile-upload-plugin": "^2.14.0",
     "graphile-utils": "5.0.1",
     "graphql": "16.13.0",
@@ -77,7 +77,7 @@
     "@types/express": "^5.0.6",
     "@types/pg": "^8.20.0",
     "@types/request-ip": "^0.0.41",
-    "graphile-test": "^4.21.1",
+    "graphile-test": "^4.21.2",
     "makage": "^0.3.0",
     "nodemon": "^3.1.14",
     "ts-node": "^10.9.2"
@@ -89,5 +89,5 @@
     "constructive",
     "graphql"
   ],
-  "gitHead": "dd2accb683fe20c7278a0d58fd36a04a3b07ac63"
+  "gitHead": "e53a570a4a70987e82dc074bd73501971fd82828"
 }

package/plugins/meta-schema/graphql-meta-field.js

@@ -18,16 +18,16 @@ function createMetaSchemaType() {
             isArray: { type: nn(graphql_1.GraphQLBoolean) },
             isNotNull: { type: graphql_1.GraphQLBoolean },
             hasDefault: { type: graphql_1.GraphQLBoolean },
-            subtype: { type: graphql_1.GraphQLString },
-        }),
+            subtype: { type: graphql_1.GraphQLString }
+        })
     });
     const MetaEnumType = new graphql_1.GraphQLObjectType({
         name: 'MetaEnum',
         description: 'Information about a PostgreSQL enum type',
         fields: () => ({
             name: { type: nn(graphql_1.GraphQLString), description: 'The PostgreSQL enum type name' },
-            values: { type: nnList(graphql_1.GraphQLString), description: 'Allowed values for this enum' },
-        }),
+            values: { type: nnList(graphql_1.GraphQLString), description: 'Allowed values for this enum' }
+        })
     });
     const MetaFieldType = new graphql_1.GraphQLObjectType({
         name: 'MetaField',
@@ -40,8 +40,8 @@ function createMetaSchemaType() {
             isPrimaryKey: { type: nn(graphql_1.GraphQLBoolean) },
             isForeignKey: { type: nn(graphql_1.GraphQLBoolean) },
             description: { type: graphql_1.GraphQLString },
-            enumValues: { type: MetaEnumType, description: 'Enum metadata if this field has an enum type' },
-        }),
+            enumValues: { type: MetaEnumType, description: 'Enum metadata if this field has an enum type' }
+        })
     });
     const MetaIndexType = new graphql_1.GraphQLObjectType({
         name: 'MetaIndex',
@@ -51,31 +51,31 @@ function createMetaSchemaType() {
             isUnique: { type: nn(graphql_1.GraphQLBoolean) },
             isPrimary: { type: nn(graphql_1.GraphQLBoolean) },
             columns: { type: nnList(graphql_1.GraphQLString) },
-            fields: { type: new graphql_1.GraphQLList(nn(MetaFieldType)) },
-        }),
+            fields: { type: new graphql_1.GraphQLList(nn(MetaFieldType)) }
+        })
     });
     const MetaPrimaryKeyConstraintType = new graphql_1.GraphQLObjectType({
         name: 'MetaPrimaryKeyConstraint',
         description: 'Information about a primary key constraint',
         fields: () => ({
             name: { type: nn(graphql_1.GraphQLString) },
-            fields: { type: nnList(MetaFieldType) },
-        }),
+            fields: { type: nnList(MetaFieldType) }
+        })
     });
     const MetaUniqueConstraintType = new graphql_1.GraphQLObjectType({
         name: 'MetaUniqueConstraint',
         description: 'Information about a unique constraint',
         fields: () => ({
             name: { type: nn(graphql_1.GraphQLString) },
-            fields: { type: nnList(MetaFieldType) },
-        }),
+            fields: { type: nnList(MetaFieldType) }
+        })
     });
     const MetaRefTableType = new graphql_1.GraphQLObjectType({
         name: 'MetaRefTable',
         description: 'Reference to a related table',
         fields: () => ({
-            name: { type: nn(graphql_1.GraphQLString) },
-        }),
+            name: { type: nn(graphql_1.GraphQLString) }
+        })
     });
     const MetaForeignKeyConstraintType = new graphql_1.GraphQLObjectType({
         name: 'MetaForeignKeyConstraint',
@@ -86,8 +86,8 @@ function createMetaSchemaType() {
             referencedTable: { type: nn(graphql_1.GraphQLString) },
             referencedFields: { type: nnList(graphql_1.GraphQLString) },
             refFields: { type: new graphql_1.GraphQLList(nn(MetaFieldType)) },
-            refTable: { type: MetaRefTableType },
-        }),
+            refTable: { type: MetaRefTableType }
+        })
     });
     const MetaConstraintsType = new graphql_1.GraphQLObjectType({
         name: 'MetaConstraints',
@@ -95,8 +95,8 @@ function createMetaSchemaType() {
         fields: () => ({
             primaryKey: { type: MetaPrimaryKeyConstraintType },
             unique: { type: nnList(MetaUniqueConstraintType) },
-            foreignKey: { type: nnList(MetaForeignKeyConstraintType) },
-        }),
+            foreignKey: { type: nnList(MetaForeignKeyConstraintType) }
+        })
     });
     const MetaInflectionType = new graphql_1.GraphQLObjectType({
         name: 'MetaInflection',
@@ -113,8 +113,8 @@ function createMetaSchemaType() {
             createInputType: { type: nn(graphql_1.GraphQLString) },
             createPayloadType: { type: nn(graphql_1.GraphQLString) },
             updatePayloadType: { type: graphql_1.GraphQLString },
-            deletePayloadType: { type: nn(graphql_1.GraphQLString) },
-        }),
+            deletePayloadType: { type: nn(graphql_1.GraphQLString) }
+        })
     });
     const MetaQueryType = new graphql_1.GraphQLObjectType({
         name: 'MetaQuery',
@@ -124,8 +124,8 @@ function createMetaSchemaType() {
             one: { type: graphql_1.GraphQLString },
             create: { type: graphql_1.GraphQLString },
             update: { type: graphql_1.GraphQLString },
-            delete: { type: graphql_1.GraphQLString },
-        }),
+            delete: { type: graphql_1.GraphQLString }
+        })
     });
     const MetaBelongsToRelationType = new graphql_1.GraphQLObjectType({
         name: 'MetaBelongsToRelation',
@@ -135,8 +135,8 @@ function createMetaSchemaType() {
             isUnique: { type: nn(graphql_1.GraphQLBoolean) },
             type: { type: graphql_1.GraphQLString },
             keys: { type: nnList(MetaFieldType) },
-            references: { type: nn(MetaRefTableType) },
-        }),
+            references: { type: nn(MetaRefTableType) }
+        })
     });
     const MetaHasRelationType = new graphql_1.GraphQLObjectType({
         name: 'MetaHasRelation',
@@ -146,8 +146,8 @@ function createMetaSchemaType() {
             isUnique: { type: nn(graphql_1.GraphQLBoolean) },
             type: { type: graphql_1.GraphQLString },
             keys: { type: nnList(MetaFieldType) },
-            referencedBy: { type: nn(MetaRefTableType) },
-        }),
+            referencedBy: { type: nn(MetaRefTableType) }
+        })
     });
     const MetaManyToManyRelationType = new graphql_1.GraphQLObjectType({
         name: 'MetaManyToManyRelation',
@@ -162,8 +162,8 @@ function createMetaSchemaType() {
             junctionRightKeyAttributes: { type: nnList(MetaFieldType) },
             leftKeyAttributes: { type: nnList(MetaFieldType) },
             rightKeyAttributes: { type: nnList(MetaFieldType) },
-            rightTable: { type: nn(MetaRefTableType) },
-        }),
+            rightTable: { type: nn(MetaRefTableType) }
+        })
     });
     const MetaRelationsType = new graphql_1.GraphQLObjectType({
         name: 'MetaRelations',
@@ -173,16 +173,16 @@ function createMetaSchemaType() {
             has: { type: nnList(MetaHasRelationType) },
             hasOne: { type: nnList(MetaHasRelationType) },
             hasMany: { type: nnList(MetaHasRelationType) },
-            manyToMany: { type: nnList(MetaManyToManyRelationType) },
-        }),
+            manyToMany: { type: nnList(MetaManyToManyRelationType) }
+        })
     });
     const MetaStorageType = new graphql_1.GraphQLObjectType({
         name: 'MetaStorage',
         description: 'Storage metadata for a table',
         fields: () => ({
             isFilesTable: { type: nn(graphql_1.GraphQLBoolean), description: 'Whether this table is a storage files table' },
-            isBucketsTable: { type: nn(graphql_1.GraphQLBoolean), description: 'Whether this table is a storage buckets table' },
-        }),
+            isBucketsTable: { type: nn(graphql_1.GraphQLBoolean), description: 'Whether this table is a storage buckets table' }
+        })
     });
     const MetaSearchConfigType = new graphql_1.GraphQLObjectType({
         name: 'MetaSearchConfig',
@@ -193,20 +193,20 @@ function createMetaSchemaType() {
                 description: 'JSON-encoded per-adapter score weights',
                 resolve(source) {
                     return source.weights ? JSON.stringify(source.weights) : null;
-                },
+                }
             },
             boostRecent: { type: nn(graphql_1.GraphQLBoolean), description: 'Whether recency boosting is enabled' },
             boostRecencyField: { type: graphql_1.GraphQLString, description: 'Field used for recency decay' },
-            boostRecencyDecay: { type: graphql_1.GraphQLFloat, description: 'Exponential decay factor per day' },
-        }),
+            boostRecencyDecay: { type: graphql_1.GraphQLFloat, description: 'Exponential decay factor per day' }
+        })
     });
     const MetaSearchColumnType = new graphql_1.GraphQLObjectType({
         name: 'MetaSearchColumn',
         description: 'A searchable column with its algorithm',
         fields: () => ({
             name: { type: nn(graphql_1.GraphQLString), description: 'Column name (camelCase)' },
-            algorithm: { type: nn(graphql_1.GraphQLString), description: 'Search algorithm: tsvector, bm25, trgm, or vector' },
-        }),
+            algorithm: { type: nn(graphql_1.GraphQLString), description: 'Search algorithm: tsvector, bm25, trgm, or vector' }
+        })
     });
     const MetaSearchType = new graphql_1.GraphQLObjectType({
         name: 'MetaSearch',
@@ -215,31 +215,42 @@ function createMetaSchemaType() {
             algorithms: { type: nnList(graphql_1.GraphQLString), description: 'Active search algorithms on this table' },
             columns: { type: nnList(MetaSearchColumnType), description: 'Searchable columns with their algorithm' },
             hasUnifiedSearch: { type: nn(graphql_1.GraphQLBoolean), description: 'Whether unifiedSearch composite filter is available' },
-            config: { type: MetaSearchConfigType, description: 'Per-table search configuration' },
-        }),
+            config: { type: MetaSearchConfigType, description: 'Per-table search configuration' }
+        })
     });
     const MetaI18nFieldType = new graphql_1.GraphQLObjectType({
         name: 'MetaI18nField',
         description: 'A translatable field',
         fields: () => ({
             name: { type: nn(graphql_1.GraphQLString), description: 'GraphQL field name' },
-            type: { type: nn(graphql_1.GraphQLString), description: 'PostgreSQL column type (text, citext)' },
-        }),
+            type: { type: nn(graphql_1.GraphQLString), description: 'PostgreSQL column type (text, citext)' }
+        })
     });
     const MetaI18nType = new graphql_1.GraphQLObjectType({
         name: 'MetaI18n',
         description: 'i18n metadata for a table with @i18n tag',
         fields: () => ({
             translationTable: { type: nn(graphql_1.GraphQLString), description: 'Name of the translation table' },
-            translatableFields: { type: nnList(MetaI18nFieldType), description: 'Fields that are translatable' },
-        }),
+            translatableFields: { type: nnList(MetaI18nFieldType), description: 'Fields that are translatable' }
+        })
     });
     const MetaRealtimeType = new graphql_1.GraphQLObjectType({
         name: 'MetaRealtime',
         description: 'Realtime metadata for a table with @realtime tag',
         fields: () => ({
-            subscriptionFieldName: { type: nn(graphql_1.GraphQLString), description: 'The generated subscription field name (e.g. onPostChanged)' },
-        }),
+            subscriptionFieldName: { type: nn(graphql_1.GraphQLString), description: 'The generated subscription field name (e.g. onPostChanged)' }
+        })
+    });
+    const MetaScopeType = new graphql_1.GraphQLObjectType({
+        name: 'MetaScope',
+        description: 'Provisioning scope metadata for a table',
+        fields: () => ({
+            scope: { type: nn(graphql_1.GraphQLString), description: "Provisioning scope: 'platform', 'app', 'database', or an entity scope (e.g. 'org')" },
+            tier: { type: nn(graphql_1.GraphQLString), description: "Coarse bucket: 'global', 'database', or 'entity'" },
+            keyColumn: { type: graphql_1.GraphQLString, description: 'Inflected scope key column (e.g. databaseId, orgId), null for global tiers' },
+            entityTable: { type: graphql_1.GraphQLString, description: 'SQL name of the entity table for entity scopes, else null' },
+            source: { type: nn(graphql_1.GraphQLString), description: "Provenance of the scope metadata (always 'smartTag')" }
+        })
     });
     const MetaTableType = new graphql_1.GraphQLObjectType({
         name: 'MetaTable',
@@ -260,14 +271,15 @@ function createMetaSchemaType() {
             search: { type: MetaSearchType, description: 'Search metadata (null if no search configured)' },
             i18n: { type: MetaI18nType, description: 'i18n metadata (null if no @i18n tag)' },
             realtime: { type: MetaRealtimeType, description: 'Realtime metadata (null if no @realtime tag)' },
-        }),
+            scope: { type: MetaScopeType, description: 'Provisioning scope metadata (null if no @scope tag)' }
+        })
     });
     return new graphql_1.GraphQLObjectType({
         name: 'MetaSchema',
         description: 'Root meta schema type',
         fields: () => ({
-            tables: { type: nnList(MetaTableType) },
-        }),
+            tables: { type: nnList(MetaTableType) }
+        })
     });
 }
 function extendQueryWithMetaField(fields, tablesMeta) {
@@ -277,10 +289,10 @@ function extendQueryWithMetaField(fields, tablesMeta) {
         description: 'Metadata about the database schema, including tables, fields, indexes, and constraints. Useful for code generation tools.',
         resolve() {
             return { tables: tablesMeta };
-        },
+        }
     };
     return {
         ...fields,
-        _meta: metaField,
+        _meta: metaField
     };
 }

package/plugins/meta-schema/scope-meta-builders.d.ts

@@ -0,0 +1,15 @@
+import type { PgCodec, ScopeMeta } from './types';
+/**
+ * Detect provisioning scope metadata for a table.
+ *
+ * The `@scope` smart tag emitted by the constructive-db generators is the sole
+ * source of truth. `apply_scope_fields` knows the exact scope, tier, key column,
+ * and entity table, and emits them via
+ * `metaschema.append_table_smart_tags(id, { scope, scopeTier, scopeKey, scopeEntityTable })`.
+ * PostGraphile surfaces these as `codec.extensions.tags.*`.
+ *
+ * There is NO inference from column names — a table without the tag returns
+ * `null` (the same convention as every other nullable metadata block). This
+ * avoids guessing key columns, whose names are chosen freely by each generator.
+ */
+export declare function buildScopeMeta(codec: PgCodec, inflectAttr: (attrName: string, codec: PgCodec) => string): ScopeMeta | null;

package/plugins/meta-schema/scope-meta-builders.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildScopeMeta = buildScopeMeta;
+const VALID_TIERS = new Set(['global', 'database', 'entity']);
+function readString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Detect provisioning scope metadata for a table.
+ *
+ * The `@scope` smart tag emitted by the constructive-db generators is the sole
+ * source of truth. `apply_scope_fields` knows the exact scope, tier, key column,
+ * and entity table, and emits them via
+ * `metaschema.append_table_smart_tags(id, { scope, scopeTier, scopeKey, scopeEntityTable })`.
+ * PostGraphile surfaces these as `codec.extensions.tags.*`.
+ *
+ * There is NO inference from column names — a table without the tag returns
+ * `null` (the same convention as every other nullable metadata block). This
+ * avoids guessing key columns, whose names are chosen freely by each generator.
+ */
+function buildScopeMeta(codec, inflectAttr) {
+    const tags = codec.extensions?.tags;
+    const scope = readString(tags?.scope);
+    if (!scope)
+        return null;
+    const rawTier = readString(tags.scopeTier);
+    const tier = rawTier && VALID_TIERS.has(rawTier)
+        ? rawTier
+        : null;
+    if (!tier) {
+        throw new Error(`@scope tag on codec "${codec.name}" is missing a valid scopeTier ` +
+            `(expected one of global|database|entity, got ${JSON.stringify(rawTier)})`);
+    }
+    const keyColumn = readString(tags.scopeKey);
+    const entityTable = readString(tags.scopeEntityTable);
+    return {
+        scope,
+        tier,
+        keyColumn: keyColumn ? inflectAttr(keyColumn, codec) : null,
+        entityTable,
+        source: 'smartTag'
+    };
+}

package/plugins/meta-schema/table-meta-builder.js

@@ -4,10 +4,11 @@ exports.collectTablesMeta = collectTablesMeta;
 const constraint_meta_builders_1 = require("./constraint-meta-builders");
 const name_meta_builders_1 = require("./name-meta-builders");
 const relation_meta_builders_1 = require("./relation-meta-builders");
+const scope_meta_builders_1 = require("./scope-meta-builders");
 const storage_search_meta_builders_1 = require("./storage-search-meta-builders");
-const type_mappings_1 = require("./type-mappings");
 const table_meta_context_1 = require("./table-meta-context");
 const table_resource_utils_1 = require("./table-resource-utils");
+const type_mappings_1 = require("./type-mappings");
 function buildTableMeta(resource, schemaName, context) {
     const codec = resource.codec;
     const attributes = codec.attributes;
@@ -30,7 +31,7 @@ function buildTableMeta(resource, schemaName, context) {
     }
     const fields = Object.entries(attributes).map(([attrName, attr]) => (0, type_mappings_1.buildFieldMeta)(context.inflectAttr(attrName, codec), attr, context.build, {
         isPrimaryKey: pkAttrNames.has(attrName),
-        isForeignKey: fkAttrNames.has(attrName),
+        isForeignKey: fkAttrNames.has(attrName)
     }));
     const indexes = (0, constraint_meta_builders_1.buildIndexes)(codec, attributes, uniques, context);
     const primaryKey = (0, constraint_meta_builders_1.buildPrimaryKey)(codec, attributes, uniques, context);
@@ -39,7 +40,7 @@ function buildTableMeta(resource, schemaName, context) {
     const constraints = {
         primaryKey,
         unique: uniqueConstraints,
-        foreignKey: foreignKeyConstraints,
+        foreignKey: foreignKeyConstraints
     };
     const belongsTo = (0, relation_meta_builders_1.buildBelongsToRelations)(codec, attributes, uniques, relations, context);
     const { hasOne, hasMany } = (0, relation_meta_builders_1.buildReverseRelations)(codec, attributes, relations, context);
@@ -49,13 +50,14 @@ function buildTableMeta(resource, schemaName, context) {
         has: [...hasOne, ...hasMany],
         hasOne,
         hasMany,
-        manyToMany,
+        manyToMany
     };
     const tableType = (0, name_meta_builders_1.resolveTableType)(context.build, codec);
     const storage = (0, storage_search_meta_builders_1.buildStorageMeta)(codec);
     const search = (0, storage_search_meta_builders_1.buildSearchMeta)(codec, context.build, context.inflectAttr);
     const i18n = (0, storage_search_meta_builders_1.buildI18nMeta)(codec, context.build, context.inflectAttr);
     const realtime = (0, storage_search_meta_builders_1.buildRealtimeMeta)(codec, context.build);
+    const scope = (0, scope_meta_builders_1.buildScopeMeta)(codec, context.inflectAttr);
     return {
         name: tableType,
         schemaName,
@@ -72,6 +74,7 @@ function buildTableMeta(resource, schemaName, context) {
         search,
         i18n,
         realtime,
+        scope
     };
 }
 function collectTablesMeta(build) {

package/plugins/meta-schema/types.d.ts

@@ -14,6 +14,21 @@ export interface TableMeta {
     search: SearchMeta | null;
     i18n: I18nMeta | null;
     realtime: RealtimeMeta | null;
+    scope: ScopeMeta | null;
+}
+/** Coarse provisioning tier a table's scope belongs to. */
+export type ScopeTier = 'global' | 'database' | 'entity';
+export interface ScopeMeta {
+    /** The provisioning scope, e.g. 'platform', 'app', 'database', 'org', 'user' */
+    scope: string;
+    /** Coarse bucket: global (platform/app), database, or entity */
+    tier: ScopeTier;
+    /** Inflected scope key column (e.g. 'databaseId', 'orgId'), or null for global tiers */
+    keyColumn: string | null;
+    /** SQL name of the entity table for entity scopes, else null */
+    entityTable: string | null;
+    /** Provenance of the scope metadata. Always the @scope smart tag. */
+    source: 'smartTag';
 }
 export interface StorageMeta {
     /** Whether this table is tagged as a storage files table */