Remove obsolete enrichment snapshot contract (#221)

Drops the short-lived commongrid enrichment snapshot objects that were
introduced before the architecture pivot to direct REST consumption.
Consumers should call CommonGrid's public APIs directly with caching;
CommonGrid should not mirror its utility facts through a database view for
private downstream systems.

This migration idempotently removes:
- commongrid.v_crm_org_enrichment
- commongrid.v_utility_enrichment
- commongrid.v_utilities_enriched
- commongrid.enrichment_schema

It intentionally keeps the commongrid schema and internal_api_consumer
role, which remain useful as the generic server-to-server contract
namespace for utility-name resolution and lifecycle signals.

Also scrubs obsolete private-spec references from public SQL/test comments.

Validation:
- Applied migration against Neon successfully; commongrid has no tables,
  views, or functions after cleanup
- npm run build passes
- npm run openapi:check passes

Co-authored-by: texture-coding-agent <coding-agent@texturehq.com>

Author: texture-fleet-agent[bot]

drizzle/0008_resolve_utility_by_name_function.sql

@@ -1,5 +1,5 @@
 -- Migration: Add fn_resolve_utility_by_name SQL function (M3)
--- Spec: TextureHQ/mono#10142 (specs/relay/commongrid-nisc-matcher.md)
+-- Public server-to-server utility matching contract.
 -- SECURITY INVOKER function with pinned search_path
 -- Implements: override-lookup → exact normalized name → domain match → trigram fuzzy cascade
 -- Returns: contract JSONB with {eia_id, confidence, match_source, candidates[top 5], resolver_version}

drizzle/0009_utility_cache_and_overrides_tables.sql

@@ -1,5 +1,5 @@
 -- Migration: Add utility_resolver_cache + utility_name_manual_overrides tables (M4)
--- Spec: TextureHQ/mono#10142 (specs/relay/commongrid-nisc-matcher.md)
+-- Public server-to-server utility matching contract.
 -- Creates two admin tables to support M3 fn_resolve_utility_by_name:
 --   1. utility_name_manual_overrides: admin-curated mappings for ambiguous/new utilities
 --   2. utility_resolver_cache: read-only cache keyed by sha256(lower(name)|state|domain)

drizzle/0010_fix_crm_org_enrichment_view.sql

@@ -1,7 +1,7 @@
--- Migration: fix commongrid.v_crm_org_enrichment view + enrichment_schema sidecar (M2)
+-- Migration: fix commongrid.v_utility_enrichment view + enrichment_schema sidecar (M2)
 --
 -- Supersedes the earlier drizzle/0007_enrichment_schema_and_view.sql draft.
--- That draft created public.enrichment_schema + public.v_crm_org_enrichment
+-- That draft created public.enrichment_schema + public.v_utility_enrichment
 -- with non-existent source columns and would have failed to apply; we
 -- defensively DROP anything it may have landed in environments where it was
 -- partially run, then create the correct commongrid.* objects.
@@ -14,7 +14,7 @@ BEGIN;
 -- ---------------------------------------------------------------------------
 -- 0. Clean up partial drafts, if any.
 -- ---------------------------------------------------------------------------
-DROP VIEW  IF EXISTS public.v_crm_org_enrichment;
+DROP VIEW  IF EXISTS public.v_utility_enrichment;
 DROP TABLE IF EXISTS public.enrichment_schema;
 DROP VIEW  IF EXISTS commongrid.v_utilities_enriched;
 
@@ -43,7 +43,7 @@ GRANT USAGE ON SCHEMA commongrid TO internal_api_consumer;
 --    Source of truth is public.utilities joined to territory geometry via
 --    regions + territories. Active, non-deleted utilities with an EIA id only.
 -- ---------------------------------------------------------------------------
-CREATE OR REPLACE VIEW commongrid.v_crm_org_enrichment AS
+CREATE OR REPLACE VIEW commongrid.v_utility_enrichment AS
 SELECT
   u.eia_id                                              AS eia_utility_id,
   u.slug                                                AS commongrid_utility_slug,
@@ -89,15 +89,15 @@ WHERE u.deleted_at IS NULL
   AND u.status = 'ACTIVE'
   AND u.eia_id IS NOT NULL;
 
-COMMENT ON VIEW commongrid.v_crm_org_enrichment IS
+COMMENT ON VIEW commongrid.v_utility_enrichment IS
   'Versioned utility enrichment view for internal API consumers. Shape is '
   'documented in commongrid.enrichment_schema. Additive-only: new columns '
   'may be appended with a minor-version bump; removals or renames require a '
   'major-version bump with advance notice.';
 
 -- ---------------------------------------------------------------------------
 -- 4. Versioning sidecar. Singleton table that records the current shape and
---    version of v_crm_org_enrichment so consumers can pin a known contract
+--    version of v_utility_enrichment so consumers can pin a known contract
 --    and fail loud on drift.
 -- ---------------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS commongrid.enrichment_schema (
@@ -111,7 +111,7 @@ CREATE TABLE IF NOT EXISTS commongrid.enrichment_schema (
 
 COMMENT ON TABLE commongrid.enrichment_schema IS
   'Singleton. Records the current (major, minor) version and column manifest '
-  'of commongrid.v_crm_org_enrichment so internal API consumers can detect drift.';
+  'of commongrid.v_utility_enrichment so internal API consumers can detect drift.';
 
 -- ---------------------------------------------------------------------------
 -- 5. Seed / refresh v1.0 manifest. Mirrors the columns and nullability of
@@ -141,7 +141,7 @@ VALUES (
     {"name":"territory_geojson_url","type":"text","nullable":true},
     {"name":"updated_at","type":"timestamptz","nullable":false}
   ]'::jsonb,
-  'v1.0 manifest for commongrid.v_crm_org_enrichment. Additive changes bump version_minor; breaking changes bump version_major.'
+  'v1.0 manifest for commongrid.v_utility_enrichment. Additive changes bump version_minor; breaking changes bump version_major.'
 )
 ON CONFLICT (id) DO UPDATE
 SET version_major   = EXCLUDED.version_major,
@@ -153,7 +153,7 @@ SET version_major   = EXCLUDED.version_major,
 -- ---------------------------------------------------------------------------
 -- 6. Read-only grants on the two publicly-contracted objects only.
 -- ---------------------------------------------------------------------------
-GRANT SELECT ON commongrid.v_crm_org_enrichment TO internal_api_consumer;
+GRANT SELECT ON commongrid.v_utility_enrichment TO internal_api_consumer;
 GRANT SELECT ON commongrid.enrichment_schema    TO internal_api_consumer;
 
 COMMIT;

drizzle/0011_drop_enrichment_snapshot_contract.sql

@@ -0,0 +1,20 @@
+-- Drop obsolete utility-enrichment snapshot contract.
+--
+-- The public API should be the source of truth for utility facts. Consumers
+-- should call the REST endpoints directly with caching instead of mirroring
+-- CommonGrid data through a database view. This migration removes the
+-- short-lived enrichment snapshot objects while keeping the commongrid schema
+-- and internal_api_consumer role for generic server-to-server contract objects
+-- such as utility-name resolution and lifecycle signals.
+
+BEGIN;
+
+REVOKE ALL ON commongrid.v_crm_org_enrichment FROM internal_api_consumer;
+REVOKE ALL ON commongrid.enrichment_schema FROM internal_api_consumer;
+
+DROP VIEW IF EXISTS commongrid.v_crm_org_enrichment;
+DROP VIEW IF EXISTS commongrid.v_utility_enrichment;
+DROP VIEW IF EXISTS commongrid.v_utilities_enriched;
+DROP TABLE IF EXISTS commongrid.enrichment_schema;
+
+COMMIT;

drizzle/meta/_journal.json

@@ -50,6 +50,13 @@
       "when": 1778250000000,
       "tag": "0007_commongrid_schema_and_internal_consumer_role",
       "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1778252377890,
+      "tag": "0011_drop_enrichment_snapshot_contract",
+      "breakpoints": true
     }
   ]
-}
+}

scripts/resolver-sanity.vitest.ts

@@ -1,6 +1,6 @@
 /**
  * M5: Resolver sanity fixture + CI test
- * Spec: TextureHQ/mono#10142 (specs/relay/commongrid-nisc-matcher.md)
+ * Public server-to-server utility matching contract.
  *
  * Fixture: ~30 known co-op names mapped to expected eia_id
  * Test assertion: >= 90% recall at confidence >= 0.90, 0 false positives at that threshold