@stonecrop/schema 0.16.3 → 0.16.5

package/dist/schema.d.ts

@@ -23,6 +23,15 @@ export declare const ActionDefinition: z.ZodObject<{
  */
 export declare type ActionDefinition = z.infer<typeof ActionDefinition>;
 
+/**
+ * A doctype as it exists on disk: a plain object that may carry keys this package does not model
+ * (`handler` on an action, `filterFunction` on a field, whatever an app has added). Typing it
+ * loosely is what lets the merge round-trip those keys untouched instead of dropping them.
+ *
+ * @public
+ */
+export declare type AuthoredDoctype = Record<string, unknown>;
+
 /**
  * Build a merged scalar map from the built-in maps and user-provided custom scalars.
  * Precedence (highest to lowest): customScalars → GQL_SCALAR_MAP → WELL_KNOWN_SCALARS
@@ -295,7 +304,7 @@ export declare const COMPONENT_LINK_EXPANSION: Record<string, LinkExpansion>;
  *
  * @public
  */
-export declare type ComponentCategory = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | 'code' | 'link' | 'attach' | 'quantity';
+export declare type ComponentCategory = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | 'code' | 'link' | 'attach' | 'quantity' | 'currency';
 
 /**
  * Resolve a component's semantic category, or `undefined` for an unknown (custom) component —
@@ -464,6 +473,36 @@ export declare interface DoctypeContext {
     [key: string]: unknown;
 }
 
+/**
+ * What generation found that the authored doctype does not agree with. Every bucket is advisory —
+ * nothing here is applied automatically.
+ *
+ * @public
+ */
+export declare interface DoctypeDrift {
+    /** The authored doctype's name. */
+    doctype: string;
+    /**
+     * `clean` — the authored primary key is the one generation would derive.
+     * `partial` — the doctype declares an identity generation cannot derive, so identity was left alone.
+     */
+    mode: 'clean' | 'partial';
+    /** Why the mode is `partial`, when it is. */
+    reason?: string;
+    /** Fieldnames confirmed against the schema and stamped. */
+    tagged: string[];
+    /** Authored fields with no matching schema field — app components, fieldsets, or stale entries. */
+    orphan: string[];
+    /** Schema fields absent from the doctype. Usually deliberate curation, occasionally an oversight. */
+    omitted: string[];
+    /** `fieldname: authored=… schema=…` where the chosen component differs from the scalar mapping. */
+    componentDrift: string[];
+    /** `fieldname: authored=… schema=…` where nullability disagrees. */
+    requiredDrift: string[];
+    /** Identity properties that differ. These are the ones a human must adjudicate. */
+    identityDrift: string[];
+}
+
 /**
  * Union of all authoring-time field variants.
  * Use `kind` to discriminate: `'field'` | `'fieldset'` | `'table'`.
@@ -676,6 +715,52 @@ export declare const FieldValidation: z.ZodObject<{
  */
 export declare type FieldValidation = z.infer<typeof FieldValidation>;
 
+/**
+ * Render a drift report as human-readable lines. Empty when generation agrees with the doctype.
+ *
+ * @param drift - a report from {@link mergeIntrospectedDoctype}
+ * @returns one line per finding, ready to print
+ *
+ * @public
+ */
+export declare function formatDoctypeDrift(drift: DoctypeDrift): string[];
+
+/**
+ * Find the field a doctype marks as its primary key, or `undefined` when none is marked.
+ *
+ * This is the single definition of "which field identifies a record". Both sides depend on it:
+ * the middleware builds the SQL identity predicate from it, and the client resolves a record's
+ * route/store key from it. Call this; never re-derive the rule at the call site, or the two will
+ * drift and the client will key records by a column the server never queried.
+ *
+ * Two deliberate limits, both matching the shape `primaryKey` actually has:
+ * - Only **top-level** fields are scanned. `primaryKey` is a `ValueField` flag and a fieldset's
+ *   children are not identity columns, so a nested match would be an authoring error, not a PK.
+ * - The **first** match wins. Nothing in the schema enforces exactly one `primaryKey: true`, and
+ *   there is no composite-key representation — a doctype with several is already malformed, and
+ *   picking the first is what the middleware has always done.
+ *
+ * @param fields - the doctype's top-level fields
+ * @returns the primary-key field, or `undefined` for a PK-less doctype
+ * @public
+ */
+export declare function getPrimaryKeyField(fields: readonly DoctypeField[]): ValueField | undefined;
+
+/**
+ * Resolve a record's identity value using the doctype's declared primary key.
+ *
+ * Falls back to `record.id` when the doctype declares no `primaryKey`. That fallback is
+ * load-bearing, not defensive: surrogate-key doctypes carry an `id` column and never mark a
+ * primary key, and PostGraphile renames a single-column `id` PK to `rowId` — so the declared
+ * field and `id` are both real sources, in that order.
+ *
+ * @param fields - the doctype's top-level fields
+ * @param record - the record to read the identity from
+ * @returns the identity as a string, or `undefined` when neither source yields a usable value
+ * @public
+ */
+export declare function getRecordIdentity(fields: readonly DoctypeField[], record: Record<string, unknown>): string | undefined;
+
 /**
  * Options for fetching a single record
  * @public
@@ -760,19 +845,28 @@ export declare interface GraphQLConversionOptions {
      */
     include?: string[];
     /**
-     * Per-type, per-field overrides for the converted field definitions.
-     * Outer key is the GraphQL type name, inner key is the field name.
+     * Emit a doctype under a different name than its GraphQL type. Key is the GraphQL type name,
+     * value is the doctype `name`; `slug` is derived from the value.
+     *
+     * This exists for the case where a doctype is not one-to-one with a table — a second view over
+     * an existing type, say, distinguished only by presentation. Without it the converter can only
+     * ever name a doctype after its type.
+     *
+     * Keep it consistent with the middleware's `tables` option, which maps the resulting doctype
+     * name to its SQL target.
      *
      * @example
      * ```typescript
-     * {
-     *   SalesOrder: {
-     *     totalAmount: { component: 'ANumericInput', align: 'right' }
-     *   }
-     * }
+     * { Plan: 'Planner' }   // emits a doctype named Planner, slug 'planner', from type Plan
      * ```
      */
-    typeOverrides?: Record<string, Record<string, Omit<Partial<ValueField>, 'kind'>>>;
+    doctypeNames?: Record<string, string>;
+    /**
+     * Called with any advisory message raised during conversion — currently only the
+     * un-normalized-PostGraphile warning. Left to the caller so the library never writes to the
+     * console itself.
+     */
+    onWarning?: (message: string) => void;
     /**
      * Map custom or non-standard GraphQL scalar types to the component that renders them.
      * Merged with the built-in scalar maps (GQL_SCALAR_MAP + WELL_KNOWN_SCALARS).
@@ -853,6 +947,20 @@ export declare type InteractionMode = 'edit' | 'read' | 'display';
  */
 export declare const INTERNAL_SCALARS: Set<string>;
 
+/**
+ * The field properties a `source: 'introspected'` marker freezes — the ones the database owns.
+ *
+ * This is the single definition of the identity set. The docbuilder greys these inputs on an
+ * introspected field, and the converter's merge refuses to rewrite them. Stating it twice is how
+ * the two drift, so both read this constant.
+ *
+ * Everything absent from this list is author-owned, `component` most importantly: it chooses the
+ * widget, which is an authoring decision the database has no opinion about.
+ *
+ * @public
+ */
+export declare const INTROSPECTED_IDENTITY_PROPS: readonly ["fieldname", "primaryKey", "required", "options", "cardinality", "doctype"];
+
 /**
  * Input source for the GraphQL schema converter.
  * Accepts either a standard GraphQL introspection result or an SDL string.
@@ -956,6 +1064,32 @@ export declare type LinkExpansion = 'inline' | 'expand';
  */
 export declare type LinkRenderMode = 'inline' | 'record' | 'table';
 
+/**
+ * Verify an authored doctype against freshly generated output and stamp provenance.
+ *
+ * @param authored - the doctype as it exists on disk; every key not named below is preserved verbatim
+ * @param generated - `convertGraphQLSchema` output for the corresponding GraphQL type
+ * @returns the doctype to write, plus a drift report
+ *
+ * @example
+ * ```ts
+ * const [generated] = convertGraphQLSchema(introspection, { include: ['Uom'] })
+ * const { doctype, drift } = mergeIntrospectedDoctype(JSON.parse(onDisk), generated)
+ * if (drift.identityDrift.length) console.warn(drift.identityDrift.join('\n'))
+ * ```
+ *
+ * @public
+ */
+export declare function mergeIntrospectedDoctype(authored: AuthoredDoctype, generated: ConvertedGraphQLDoctype): MergeResult;
+
+/** Outcome of a merge: the doctype to write, plus what generation disagreed with. @public */
+export declare interface MergeResult {
+    /** The authored doctype with `source` markers added and nothing else changed. */
+    doctype: AuthoredDoctype;
+    /** Advisory report. Never applied. */
+    drift: DoctypeDrift;
+}
+
 /**
  * Recursively injects the `kind` discriminant into a raw field object and, for fieldsets,
  * into each of its nested `schema` children — mirroring exactly what Zod's `preprocess`

package/dist/src/cli.js

@@ -16,7 +16,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { getIntrospectionQuery } from 'graphql';
-import { convertGraphQLSchema } from './converter/index';
+import { convertGraphQLSchema, formatDoctypeDrift, mergeIntrospectedDoctype } from './converter/index';
 import { validateDoctype } from './validation';
 /**
  * Fetch an introspection result from a live GraphQL endpoint.
@@ -58,9 +58,10 @@ async function main() {
             output: { type: 'string', short: 'o' },
             include: { type: 'string' },
             exclude: { type: 'string' },
-            overrides: { type: 'string' },
+            names: { type: 'string' },
             'custom-scalars': { type: 'string' },
             'include-unmapped': { type: 'boolean', default: false },
+            check: { type: 'boolean', default: false },
             help: { type: 'boolean', short: 'h' },
         },
     });
@@ -95,11 +96,11 @@ async function main() {
     if (values.exclude) {
         options.exclude = values.exclude.split(',').map(s => s.trim());
     }
-    if (values.overrides) {
-        const overridesPath = resolve(values.overrides);
-        const overridesContent = readFileSync(overridesPath, 'utf-8');
-        options.typeOverrides = JSON.parse(overridesContent);
+    if (values.names) {
+        const namesPath = resolve(values.names);
+        options.doctypeNames = JSON.parse(readFileSync(namesPath, 'utf-8'));
     }
+    options.onWarning = message => console.warn(`  WARN: ${message}`);
     if (values['custom-scalars']) {
         const scalarsPath = resolve(values['custom-scalars']);
         const scalarsContent = readFileSync(scalarsPath, 'utf-8');
@@ -134,13 +135,35 @@ async function main() {
     }
     let warnings = 0;
     let errors = 0;
-    for (const doctype of doctypes) {
-        const fileName = `${doctype.slug}.json`;
+    let changed = 0;
+    const driftLines = [];
+    for (const generated of doctypes) {
+        const fileName = `${generated.slug}.json`;
         const filePath = join(outputDir, fileName);
-        const json = JSON.stringify(doctype, null, '\t');
-        writeFileSync(filePath, json + '\n', 'utf-8');
+        // When a doctype already exists it is the source of truth: generation confirms it and adds
+        // provenance markers, and reports anything it disagrees with rather than applying it. A
+        // doctype legitimately declares identity the schema cannot express — most often a natural
+        // key that is a UNIQUE constraint, not the table's PRIMARY KEY — and overwriting that would
+        // silently re-key the doctype on every run. A first generation has nothing to merge into,
+        // so converter output is written verbatim.
+        let output = generated;
+        if (existsSync(filePath)) {
+            const { doctype: merged, drift } = mergeIntrospectedDoctype(JSON.parse(readFileSync(filePath, 'utf-8')), generated);
+            output = merged;
+            driftLines.push(...formatDoctypeDrift(drift));
+        }
+        // Serialize the merged object directly. Never round-trip it through the Zod parser first:
+        // that runs in strip mode and would silently drop every key this package does not model,
+        // `handler` on an action being the one consumers actually rely on.
+        const json = JSON.stringify(output, null, '\t') + '\n';
+        const unchanged = existsSync(filePath) && readFileSync(filePath, 'utf-8') === json;
+        if (!unchanged)
+            changed++;
+        if (!values.check && !unchanged) {
+            writeFileSync(filePath, json, 'utf-8');
+        }
         // Validate the output
-        const validation = validateDoctype(doctype);
+        const validation = validateDoctype(output);
         if (!validation.success) {
             errors++;
             console.error(`  ERROR: ${fileName} failed validation:`);
@@ -150,7 +173,7 @@ async function main() {
         }
         else {
             // Check for unmapped fields
-            const unmappedFields = doctype.fields.filter((f) => f._unmapped);
+            const unmappedFields = generated.fields.filter((f) => f._unmapped);
             if (unmappedFields.length > 0) {
                 warnings++;
                 console.warn(`  WARN: ${fileName} has ${unmappedFields.length} unmapped field(s): ${unmappedFields
@@ -159,10 +182,16 @@ async function main() {
             }
         }
     }
-    console.log(`\nGenerated ${doctypes.length} doctype(s) in ${outputDir}` +
+    if (driftLines.length > 0) {
+        console.log('\nDrift between the authored doctypes and the schema (reported, not applied):');
+        for (const line of driftLines)
+            console.log(line);
+    }
+    console.log(`\n${values.check ? 'Checked' : 'Generated'} ${doctypes.length} doctype(s) in ${outputDir}` +
+        (changed ? ` (${changed} ${values.check ? 'would change' : 'written'})` : ' (all up to date)') +
         (warnings ? ` (${warnings} with warnings)` : '') +
         (errors ? ` (${errors} with errors)` : ''));
-    if (errors > 0) {
+    if (errors > 0 || (values.check && changed > 0)) {
         process.exit(1);
     }
 }
@@ -184,11 +213,16 @@ OUTPUT:
 OPTIONS:
   --include <types>            Comma-separated list of type names to include
   --exclude <types>            Comma-separated list of type names to exclude
-  --overrides <file>           JSON file with per-type field overrides
+  --names <file>               JSON file mapping GraphQL type name to doctype name
   --custom-scalars <file>      JSON file mapping custom scalar names to field templates
   --include-unmapped           Include _graphqlType metadata on unmapped fields
+  --check                      Report drift and exit non-zero if anything would change; write nothing
   --help, -h                   Show this help message
 
+NOTE: an existing doctype file is the source of truth. Regeneration verifies it against the
+schema and adds 'source: introspected' markers; it reports disagreements rather than
+overwriting them, so hand-curation survives. Use --check in CI.
+
 EXAMPLES:
   # From a live PostGraphile server
   stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas

package/dist/src/component-meta.d.ts

@@ -9,7 +9,7 @@
  *
  * @public
  */
-export type ComponentCategory = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | 'code' | 'link' | 'attach' | 'quantity';
+export type ComponentCategory = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | 'code' | 'link' | 'attach' | 'quantity' | 'currency';
 /**
  * Canonical component → semantic category. Only the components Stonecrop ships with appear here;
  * custom/unknown component names have no category and consumers fall back to their default.

package/dist/src/component-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-meta.d.ts","sourceRoot":"","sources":["../../src/component-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAC5B,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAA;AAEzG;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAgBhE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEnF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAIlE,CAAA;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEpF;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAClD,cAAc,CAAC,EAAE,MAAM,GACrB,cAAc,CAGhB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAEtC,CAAA"}
+{"version":3,"file":"component-meta.d.ts","sourceRoot":"","sources":["../../src/component-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAC5B,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAA;AAEtH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAiBhE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEnF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAIlE,CAAA;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEpF;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAClD,cAAc,CAAC,EAAE,MAAM,GACrB,cAAc,CAGhB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAEtC,CAAA"}

package/dist/src/component-meta.js

@@ -19,6 +19,7 @@ export const COMPONENT_CATEGORY = {
     AFormLink: 'link',
     AFileAttach: 'attach',
     AQuantityInput: 'quantity',
+    ACurrencyInput: 'currency',
 };
 /**
  * Resolve a component's semantic category, or `undefined` for an unknown (custom) component —

package/dist/src/converter/index.d.ts

@@ -43,5 +43,7 @@ export { convertGraphQLSchema as default };
 export type { IntrospectionSource, GraphQLConversionOptions, GraphQLConversionFieldMeta, ConvertedGraphQLDoctype, } from './types';
 export { GQL_SCALAR_MAP, WELL_KNOWN_SCALARS, INTERNAL_SCALARS, buildScalarMap } from './scalars';
 export { defaultIsEntityType, defaultIsEntityField, classifyFieldType } from './heuristics';
+export { mergeIntrospectedDoctype, formatDoctypeDrift } from './merge';
+export type { AuthoredDoctype, DoctypeDrift, MergeResult } from './merge';
 export { toSlug, toPascalCase, pascalToSnake, snakeToCamel, camelToSnake, snakeToLabel, camelToLabel } from '../naming';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/converter/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/converter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAIrG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,wBAA6B,GACpC,uBAAuB,EAAE,CA+H3B;AAwBD,OAAO,EAAE,oBAAoB,IAAI,OAAO,EAAE,CAAA;AAG1C,YAAY,EACX,mBAAmB,EACnB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhG,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAG3F,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/converter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAIrG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,wBAA6B,GACpC,uBAAuB,EAAE,CAkJ3B;AAwBD,OAAO,EAAE,oBAAoB,IAAI,OAAO,EAAE,CAAA;AAG1C,YAAY,EACX,mBAAmB,EACnB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhG,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAG3F,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AACtE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAGzE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/src/converter/index.js

@@ -86,8 +86,18 @@ export function convertGraphQLSchema(source, options = {}) {
         if (!isObjectType(type))
             continue;
         const fields = type.getFields();
-        const typeOverrides = options.typeOverrides?.[typeName];
-        const entityFields = Object.entries(fields).filter(([fieldName, field]) => isEntityField(fieldName, field, type));
+        // A type carrying BOTH `id` and `rowId` is PostGraphile Amber with its default inflection:
+        // the Relay global identifier has taken `id`, displacing the real column to `rowId`. Neither
+        // name can be emitted as-is — `id` is an opaque node id, and `rowId` does not name a column.
+        // Refuse to guess: drop the Relay field and tell the caller to fix it at the inflector, where
+        // it belongs. Normalizing here would bake a database fact into the doctype.
+        const isUnnormalizedPostGraphile = 'id' in fields && 'rowId' in fields;
+        if (isUnnormalizedPostGraphile) {
+            options.onWarning?.(`${typeName}: schema exposes both 'id' (Relay identifier) and 'rowId' (the real column). ` +
+                `Skipping 'id' and emitting 'rowId' verbatim — no primary key can be derived. ` +
+                `Override the '_attributeName' and 'nodeIdFieldName' inflectors so the column keeps its own name.`);
+        }
+        const entityFields = Object.entries(fields).filter(([fieldName, field]) => isEntityField(fieldName, field, type) && !(isUnnormalizedPostGraphile && fieldName === 'id'));
         // oxlint-disable-next-line oxc/no-map-spread -- ...custom spread required; Object.assign cannot preserve the metadata-carrying inferred union type from classifyField
         const allClassifiedFields = entityFields.map(([fieldName, field]) => {
             // Check for full custom classification first
@@ -104,13 +114,14 @@ export function convertGraphQLSchema(source, options = {}) {
                 }
             }
             // Default classification
-            const classified = classifyFieldType(fieldName, field, entityTypes, options);
-            // Apply per-field overrides
-            if (typeOverrides?.[fieldName]) {
-                return Object.assign(classified, typeOverrides[fieldName]);
-            }
-            return classified;
+            return classifyFieldType(fieldName, field, entityTypes, options);
         });
+        // Derive the primary key, but only for the one case SDL actually settles: a non-null `id`
+        // that is a plain scalar. A natural key is typically a UNIQUE constraint indistinguishable
+        // from any other column here, and a table may carry several — so anything else is left for
+        // the author to declare. Emitting a guess would be worse than emitting nothing, because the
+        // middleware builds its identity predicate from this and the client keys records by it.
+        const primaryKeyFieldname = allClassifiedFields.find(field => field.fieldname === 'id' && field.required && !field.doctype && !field._isLink)?.fieldname;
         // Separate scalar fields from link fields
         const links = {};
         const convertedFields = allClassifiedFields
@@ -124,21 +135,22 @@ export function convertGraphQLSchema(source, options = {}) {
             }
             return true;
         })
-            // Clean up internal metadata unless requested, and stamp provenance.
-            // Stamped last so every classification path (default, classifyField,
-            // typeOverrides) carries the marker — the docbuilder's identity lock
-            // keys off it, and an override must not be able to unset it.
+            // Clean up internal metadata unless requested, and stamp identity + provenance.
+            // Stamped last so every classification path (default, classifyField) carries the marker —
+            // the docbuilder's identity lock keys off it, and no classifier may unset it.
             .map(field => {
+            const identity = field.fieldname === primaryKeyFieldname ? { primaryKey: true } : {};
             if (!options.includeUnmappedMeta) {
                 const { _graphqlType, _unmapped, _isLink, ...clean } = field;
-                return Object.assign(clean, { source: 'introspected' });
+                return Object.assign(clean, identity, { source: 'introspected' });
             }
             const { _isLink, ...rest } = field;
-            return Object.assign(rest, { source: 'introspected' });
+            return Object.assign(rest, identity, { source: 'introspected' });
         });
+        const doctypeName = options.doctypeNames?.[typeName] ?? typeName;
         const doctype = {
-            name: typeName,
-            slug: toSlug(typeName),
+            name: doctypeName,
+            slug: toSlug(doctypeName),
             fields: convertedFields,
         };
         if (Object.keys(links).length > 0) {
@@ -175,5 +187,7 @@ export { convertGraphQLSchema as default };
 export { GQL_SCALAR_MAP, WELL_KNOWN_SCALARS, INTERNAL_SCALARS, buildScalarMap } from './scalars';
 // Heuristics
 export { defaultIsEntityType, defaultIsEntityField, classifyFieldType } from './heuristics';
+// Merge — verifies an authored doctype against the schema and stamps provenance
+export { mergeIntrospectedDoctype, formatDoctypeDrift } from './merge';
 // Naming utilities
 export { toSlug, toPascalCase, pascalToSnake, snakeToCamel, camelToSnake, snakeToLabel, camelToLabel } from '../naming';

package/dist/src/converter/merge.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Merge introspected schema facts into an already-authored doctype.
+ *
+ * The authored doctype is the source of truth. Generation **verifies** it and stamps provenance;
+ * it does not overwrite. That polarity is deliberate and load-bearing — a doctype legitimately
+ * declares a `primaryKey` the schema cannot express. A natural business key is very often a
+ * `UNIQUE` constraint rather than the table's `PRIMARY KEY`, and where a table carries several
+ * uniques no rule can pick between them. Overwriting identity from the schema would silently
+ * re-key such a doctype on every regeneration and break the handlers that key on the old value.
+ *
+ * So divergence is **reported, never applied** — a human decides. The only mutation this performs
+ * is adding `source: 'introspected'` to fields confirmed to exist in the GraphQL schema.
+ *
+ * @packageDocumentation
+ */
+import type { ConvertedGraphQLDoctype } from './types';
+/**
+ * A doctype as it exists on disk: a plain object that may carry keys this package does not model
+ * (`handler` on an action, `filterFunction` on a field, whatever an app has added). Typing it
+ * loosely is what lets the merge round-trip those keys untouched instead of dropping them.
+ *
+ * @public
+ */
+export type AuthoredDoctype = Record<string, unknown>;
+/**
+ * What generation found that the authored doctype does not agree with. Every bucket is advisory —
+ * nothing here is applied automatically.
+ *
+ * @public
+ */
+export interface DoctypeDrift {
+    /** The authored doctype's name. */
+    doctype: string;
+    /**
+     * `clean` — the authored primary key is the one generation would derive.
+     * `partial` — the doctype declares an identity generation cannot derive, so identity was left alone.
+     */
+    mode: 'clean' | 'partial';
+    /** Why the mode is `partial`, when it is. */
+    reason?: string;
+    /** Fieldnames confirmed against the schema and stamped. */
+    tagged: string[];
+    /** Authored fields with no matching schema field — app components, fieldsets, or stale entries. */
+    orphan: string[];
+    /** Schema fields absent from the doctype. Usually deliberate curation, occasionally an oversight. */
+    omitted: string[];
+    /** `fieldname: authored=… schema=…` where the chosen component differs from the scalar mapping. */
+    componentDrift: string[];
+    /** `fieldname: authored=… schema=…` where nullability disagrees. */
+    requiredDrift: string[];
+    /** Identity properties that differ. These are the ones a human must adjudicate. */
+    identityDrift: string[];
+}
+/** Outcome of a merge: the doctype to write, plus what generation disagreed with. @public */
+export interface MergeResult {
+    /** The authored doctype with `source` markers added and nothing else changed. */
+    doctype: AuthoredDoctype;
+    /** Advisory report. Never applied. */
+    drift: DoctypeDrift;
+}
+/**
+ * Verify an authored doctype against freshly generated output and stamp provenance.
+ *
+ * @param authored - the doctype as it exists on disk; every key not named below is preserved verbatim
+ * @param generated - `convertGraphQLSchema` output for the corresponding GraphQL type
+ * @returns the doctype to write, plus a drift report
+ *
+ * @example
+ * ```ts
+ * const [generated] = convertGraphQLSchema(introspection, { include: ['Uom'] })
+ * const { doctype, drift } = mergeIntrospectedDoctype(JSON.parse(onDisk), generated)
+ * if (drift.identityDrift.length) console.warn(drift.identityDrift.join('\n'))
+ * ```
+ *
+ * @public
+ */
+export declare function mergeIntrospectedDoctype(authored: AuthoredDoctype, generated: ConvertedGraphQLDoctype): MergeResult;
+/**
+ * Render a drift report as human-readable lines. Empty when generation agrees with the doctype.
+ *
+ * @param drift - a report from {@link mergeIntrospectedDoctype}
+ * @returns one line per finding, ready to print
+ *
+ * @public
+ */
+export declare function formatDoctypeDrift(drift: DoctypeDrift): string[];
+//# sourceMappingURL=merge.d.ts.map

package/dist/src/converter/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/converter/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAErD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;IACzB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,mGAAmG;IACnG,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,qGAAqG;IACrG,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mGAAmG;IACnG,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,oEAAoE;IACpE,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,mFAAmF;IACnF,aAAa,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC3B,iFAAiF;IACjF,OAAO,EAAE,eAAe,CAAA;IACxB,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAA;CACnB;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,uBAAuB,GAAG,WAAW,CA4EnH;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAYhE"}