feat(meta): add scope block to _meta introspection plugin

[pyramation]

Summary

Adds a scope block to each table in the graphile _meta query, exposing the constructive-db provisioning scope so codegen can auto-inject scope keys (databaseId/orgId), group generated clients/CLI/docs by tier, and pick the right RLS/JWT context for seeds. Follows the storage/search precedent (smart tag → builder → Meta* GraphQL type).

The @scope smart tag is the sole source of truth — no column-name inference. Key columns are named freely by each generator, so guessing them (entity_id/owner_id/${scope}_id) is brittle. Instead the DB emits everything and the plugin reads it verbatim.

New GraphQL shape on MetaTable:

scope {
  scope        # 'platform' | 'app' | 'database' | entity scope e.g. 'org'
  tier         # 'global' | 'database' | 'entity'
  keyColumn    # inflected key col e.g. 'databaseId'/'orgId', null for global
  entityTable  # SQL name of entity table for entity scopes, else null
  source       # always 'smartTag'
}

Detection (scope-meta-builders.ts → buildScopeMeta):

const tags = codec.extensions?.tags;
if (!tags?.scope) return null;              // no tag → null, never guess
if (!isValidTier(tags.scopeTier)) throw;    // DB must supply the tier
return {
  scope: tags.scope,
  tier: tags.scopeTier,                      // 'global' | 'database' | 'entity'
  keyColumn: tags.scopeKey ? inflect(tags.scopeKey) : null,  // verbatim
  entityTable: tags.scopeEntityTable ?? null,
  source: 'smartTag',
};

Changes

• types.ts — ScopeMeta interface + ScopeTier type; scope: ScopeMeta | null on TableMeta; source: 'smartTag'.
• scope-meta-builders.ts (new) — buildScopeMeta, tag-only, no inference; throws on a @scope tag missing a valid scopeTier.
• table-meta-builder.ts — wire buildScopeMeta into buildTableMeta.
• graphql-meta-field.ts — MetaScope object type + nullable scope field on MetaTableType.
• Tests — meta-schema.test.ts covers database/global/entity tags (entity uses a freely-named key tenant_ref read verbatim), null-when-untagged (even with a database_id column present), and the missing-scopeTier throw. Regenerated downstream introspection/SDL snapshots (graphql/test, graphql/server-test).
• graphile-meta skill — documents the "DB emits all fields; plugin reads verbatim; never guess columns" contract.

Follow-up (separate constructive-db PR)

Emit the tag from apply_scope_fields.sql:

PERFORM metaschema.append_table_smart_tags(
  v_table_id,
  jsonb_build_object('scope', v_scope, 'scopeTier', v_tier,
                     'scopeKey', v_key_col, 'scopeEntityTable', v_entity_table)
);

Until that lands, _meta.scope is null for all tables (the tag isn't emitted yet) — which is the correct, non-brittle default.

Link to Devin session: https://app.devin.ai/sessions/819d1e4face6493393be40f35a48af33
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring