Skip to content

Add CNC-owned Graphile build-state retirement - #1722

Draft
Zetazzz wants to merge 1 commit into
feat/cnc-scoped-introspectionfrom
feat/cnc-build-state-retirement
Draft

Add CNC-owned Graphile build-state retirement#1722
Zetazzz wants to merge 1 commit into
feat/cnc-scoped-introspectionfrom
feat/cnc-build-state-retirement

Conversation

@Zetazzz

@Zetazzz Zetazzz commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Summary

This is the third PR in the replacement performance stack:

  1. Add a reusable Graphile performance harness #1716 — generic fresh-process performance harness
  2. Add CNC-owned scoped PostgreSQL introspection #1719 — CNC-owned scoped PostgreSQL introspection
  3. this PR — CNC-owned build-state retirement

It adds an opt-in BuildStateRetirementPlugin in normal CNC source. ConstructivePreset installs that plugin explicitly; Graphile's defaultPreset remains unchanged.

Architecture boundary

Crystal #1 remains an independent upstream proposal for only the neutral build.registerAfterSchemaValidation(callback) lifecycle API. The graphile-build dist patch here mirrors that API because the current installed release does not contain it.

All concrete retirement behavior stays in CNC:

  • normal CNC source decides whether and when retirement runs;
  • the graphile-build pnpm patch owns the private retirement state machine, core/Behavior cleanup, disposer registration, fail-closed guards, aggregate-error handling, and GRAPHILE_BUILD_STATE_RELEASED;
  • the graphile-build-pg pnpm patch adds owner cleanup only for PgBasics, PgCodecs, and PgPolymorphism;
  • normal CNC owners clean up graphile-search and graphile-connection-filter state;
  • graphile-meta snapshots runtime metadata onto the finalized schema before build state is retired.

No ReleaseBuildStatePlugin is imported or exported. No retirement behavior is added to Graphile's default preset. No pg-many-to-many change is included, and the graphile-build-pg patch contains no scoped-introspection hunks.

Performance harness integration

The generic harness from #1716 is extended with four attribution cases without loading ConstructivePreset:

  • stock
  • scoped
  • retire
  • scoped-retire

Each arm installs only its requested scoped-introspection and/or retirement plugin.

Validation

  • graphile-settings non-integration unit suites: 12 suites / 74 tests
  • build-state retirement contract tests cover opt-in/default behavior, validation failure, reverse disposer order, aggregate errors/fail-closed state, guards, and runtime execution
  • graphile-build-pg owner cleanup: PgBasics, PgCodecs, PgPolymorphism
  • graphile-search and graphile-connection-filter owner cleanup tests
  • graphile-meta: 131 tests / 3 snapshots
  • performance harness: 7 suites / 9 tests
  • affected packages: CJS and ESM builds pass
  • affected packages: ESLint passes with no new errors (existing warnings remain)
  • pnpm install --frozen-lockfile --offline passes
  • real PostgreSQL ConstructivePreset integration: runtime query succeeds and captured build state is released
  • real PostgreSQL four-arm smoke run:
    • all four runs succeeded in unique processes
    • all runtime validations passed
    • all schema hashes matched
    • stock/scoped retained state
    • retire/scoped-retire released state
    • generated report contained no database URL or credential material

Patch lifecycle

The neutral lifecycle portion can be removed when an equivalent API is available in the installed Graphile release. The concrete retirement implementation remains CNC-owned until suitable upstream ownership APIs exist.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant