@stonecrop/schema 0.24.0 → 0.26.0

package/dist/src/doctype.d.ts

@@ -249,6 +249,7 @@ export declare const DoctypeMeta: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     displayField: z.ZodOptional<z.ZodString>;
+    route: z.ZodOptional<z.ZodString>;
     fields: z.ZodArray<z.ZodType<import("./field").DoctypeField, unknown, z.core.$ZodTypeInternals<import("./field").DoctypeField, unknown>>>;
     links: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         target: z.ZodString;
@@ -314,6 +315,43 @@ export declare const DoctypeMeta: z.ZodObject<{
  * @public
  */
 export type DoctypeMeta = z.infer<typeof DoctypeMeta>;
+/**
+ * The one string a doctype is addressed by.
+ *
+ * A doctype carries two names — `name` (`OrderItem`) and `slug` (`order-item`) — and every registry
+ * must agree on which one keys it. Three implementations had drifted apart: the adapter's registry is
+ * keyed by `name` and its `getMeta` also scans for a matching `slug`, so it accepts **either**; the
+ * client's registry is keyed by a slug it derives itself and accepts **only** that; and
+ * `Doctype.fromObject` dropped an authored `slug` on the floor and re-derived one regardless. The
+ * adapter's accepted set was therefore a strict superset of the client's, and a link target written
+ * as the Name booted the server, passed its reference check, served rows over GraphQL, and was
+ * silently dropped by the client — an expanding child table rendering as one empty text input, with
+ * nothing logged.
+ *
+ * Resolving through this in both runtimes is what makes the two answers the same answer. It is the
+ * derivation only; a *lookup* still belongs to whichever registry owns the corpus, because the two
+ * corpora legitimately differ (a client registers lazily, and a client-only host has no adapter at
+ * all).
+ *
+ * An authored `slug` wins over the derived one because the authored doctype is the source of truth:
+ * generation verifies a file and never overwrites it, so a doctype that states its own slug means it.
+ * Deriving unconditionally is what `fromObject` did, and it made an authored `slug` a silent no-op on
+ * one side of the wire while the other honoured it.
+ *
+ * @param doctype - anything carrying a doctype's `name` and optional authored `slug`
+ * @returns the canonical slug
+ * @public
+ *
+ * @example
+ * ```typescript
+ * getDoctypeSlug({ name: 'OrderItem' })                      // 'order-item'
+ * getDoctypeSlug({ name: 'Planner', slug: 'planner-board' }) // 'planner-board'
+ * ```
+ */
+export declare function getDoctypeSlug(doctype: {
+    name: string;
+    slug?: string;
+}): string;
 /**
  * Suffix appended to a link fieldname for its pre-resolved display text in record payloads.
  *

package/dist/src/doctype.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctype.d.ts","sourceRoot":"","sources":["../../src/doctype.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doctype.d.ts","sourceRoot":"","sources":["../../src/doctype.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;EAGtB,CAAA;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAErD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAEvC;;;GAGG;AACH,eAAO,MAAM,SAAS;;;iBAUnB,CAAA;AAEH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAEjD;;;GAGG;AACH,eAAO,MAAM,SAAS;;iBAQnB,CAAA;AAEH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAEjD;;;GAGG;AACH,eAAO,MAAM,WAAW;;;iBAUrB,CAAA;AAEH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;;;6BAGxB,CAAA;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEzD;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;iBA0BzB,CAAA;AAEH;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;iBAgC1B,CAAA;AAEH;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;;;;iBAc3B,CAAA;AAEH;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAIjH;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;kBAO1B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqBtB,CAAA;AAEH;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEvD;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwFrB,CAAA;AAEH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAK/E;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,cAAc,CAAA;AAE9C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oCAAoC;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAAA;IAElC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAChC,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;IAC/B,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EAAE,CAAC,GAAG,WAAW;IAC7E;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAEnD;;;;;;;;;;OAUG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAE7F;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAE9E;;;;;;;;OAQG;IACH,SAAS,CACR,OAAO,EAAE,CAAC,EACV,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EAAE,GACd,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;CACrE"}

package/dist/src/doctype.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { DoctypeFieldSchema, flattenFields, getDisplayField } from './field';
+import { toSlug } from './naming';
 /**
  * Cardinality for relationship links.
  * @public
@@ -214,6 +215,16 @@ export const DoctypeMeta = z
      * returns that field as `{ id, displayText }`, reading `displayText` from this field.
      */
     displayField: z.string().min(1).optional(),
+    /**
+     * URL path this doctype registers at, written literally — `/order` for a collection,
+     * `/order/:id` for a record. Absent means the doctype has no page of its own, which is the
+     * common case: a child table is reached inside its parent, never at a URL.
+     *
+     * A path rather than a segment because the record parameter has to be somewhere, and a host
+     * that reads a bare segment has to know which kind of doctype it is holding to decide where
+     * to put it. Writing it out means nothing downstream re-derives it.
+     */
+    route: z.string().startsWith('/').optional(),
     /** Field definitions (a link field is one carrying `doctype`) */
     fields: z.array(DoctypeFieldSchema),
     /** Relationship links to other doctypes */
@@ -239,9 +250,13 @@ export const DoctypeMeta = z
     // need not be unique — `stonecropRecord`'s row map then keeps whichever row comes last.
     // Refusing at the gate is what makes it say so.
     //
+    // Counts the flattened set, because that is the set `getPrimaryKeyField` resolves over. The
+    // two asked different questions while this scanned top level only: a doctype with one key
+    // declared at each level passed the gate and then had one of them silently dropped.
+    //
     // Zero keys stays legal and is not an omission: a surrogate-key doctype declares none and
     // resolves through `getRecordIdField`'s documented `id` fallback.
-    const declared = doctype.fields.filter(f => f.kind === 'field' && f.primaryKey);
+    const declared = flattenFields(doctype.fields).filter(f => f.kind === 'field' && f.primaryKey);
     if (declared.length > 1) {
         ctx.addIssue({
             code: 'custom',
@@ -267,6 +282,45 @@ export const DoctypeMeta = z
         });
     }
 });
+/**
+ * The one string a doctype is addressed by.
+ *
+ * A doctype carries two names — `name` (`OrderItem`) and `slug` (`order-item`) — and every registry
+ * must agree on which one keys it. Three implementations had drifted apart: the adapter's registry is
+ * keyed by `name` and its `getMeta` also scans for a matching `slug`, so it accepts **either**; the
+ * client's registry is keyed by a slug it derives itself and accepts **only** that; and
+ * `Doctype.fromObject` dropped an authored `slug` on the floor and re-derived one regardless. The
+ * adapter's accepted set was therefore a strict superset of the client's, and a link target written
+ * as the Name booted the server, passed its reference check, served rows over GraphQL, and was
+ * silently dropped by the client — an expanding child table rendering as one empty text input, with
+ * nothing logged.
+ *
+ * Resolving through this in both runtimes is what makes the two answers the same answer. It is the
+ * derivation only; a *lookup* still belongs to whichever registry owns the corpus, because the two
+ * corpora legitimately differ (a client registers lazily, and a client-only host has no adapter at
+ * all).
+ *
+ * An authored `slug` wins over the derived one because the authored doctype is the source of truth:
+ * generation verifies a file and never overwrites it, so a doctype that states its own slug means it.
+ * Deriving unconditionally is what `fromObject` did, and it made an authored `slug` a silent no-op on
+ * one side of the wire while the other honoured it.
+ *
+ * @param doctype - anything carrying a doctype's `name` and optional authored `slug`
+ * @returns the canonical slug
+ * @public
+ *
+ * @example
+ * ```typescript
+ * getDoctypeSlug({ name: 'OrderItem' })                      // 'order-item'
+ * getDoctypeSlug({ name: 'Planner', slug: 'planner-board' }) // 'planner-board'
+ * ```
+ */
+export function getDoctypeSlug(doctype) {
+    // `||` rather than `??`: an empty authored slug is not a usable registry key, and this is
+    // reachable — `Doctype.fromObject` builds a doctype without going through the Zod gate, which is
+    // where `slug: z.string().min(1)` would have refused it.
+    return doctype.slug || toSlug(doctype.name);
+}
 /**
  * Suffix appended to a link fieldname for its pre-resolved display text in record payloads.
  *

package/dist/src/field.d.ts

@@ -157,6 +157,29 @@ export interface TableField {
  * @public
  */
 export type DoctypeField = ValueField | FieldsetField | TableField;
+/**
+ * Which of the three field shapes an entry has, read from the entry's own structure.
+ *
+ * The single definition of that question. It had three copies before this — the parser's
+ * `injectKind`, {@link stripFieldKind}'s agreement check, and the docbuilder's own
+ * `isValueField` in another package — each free to drift, and drift here re-types a field rather
+ * than throwing: a value field read as a fieldset loses its column, a fieldset read as a value
+ * field loses every child.
+ *
+ * Deliberately **shape-only**: a declared `kind` is ignored. Two callers depend on that. The
+ * stripper compares this against the declaration to decide whether removing it is lossless, which
+ * it cannot do if this honours it. The docbuilder reads raw JSON off disk and classifies entries to
+ * decide which to render as editable rows — and `kind` is Stonecrop's own discriminant, not
+ * something a doctype author writes, so a tool reading a file has no business consulting it.
+ *
+ * `injectKind` is the one place a declaration still wins, and only to leave an already-parsed
+ * object untouched on its way back through.
+ *
+ * @param field - a field entry, authored or parsed
+ * @returns the kind its shape implies
+ * @public
+ */
+export declare function inferFieldKind(field: unknown): DoctypeField['kind'];
 /**
  * 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`
@@ -173,6 +196,27 @@ export type DoctypeField = ValueField | FieldsetField | TableField;
  * @public
  */
 export declare function normalizeFieldKind(field: unknown): unknown;
+/**
+ * Remove the `kind` discriminant from a field, recursing into a fieldset's children.
+ *
+ * The outbound half of the boundary {@link normalizeFieldKind} owns inbound. `kind` is a
+ * discriminated-union tag the parser synthesizes, not something an author writes, so nothing that
+ * *writes* a doctype should put it on disk — the generator and the docbuilder's save both call
+ * this. Without it the two round-trip asymmetrically: every save adds a key the file never had.
+ *
+ * Strips only when `injectKind` would restore exactly what was removed. A fieldset carrying no
+ * `schema` re-infers as a plain field, so its `kind` is kept rather than silently re-typing the
+ * document; `DoctypeMeta` requires `schema` on a fieldset, so that shape is already invalid and
+ * belongs to the load gate, not here.
+ *
+ * Table `columns` are {@link ColumnSchema} entries rather than `DoctypeField`s and never carry an
+ * injected `kind`, so they are passed through untouched — the same asymmetry `injectKind` has.
+ *
+ * @param field - a field object, as held in memory after parsing
+ * @returns the field without `kind`, safe to serialize
+ * @public
+ */
+export declare function stripFieldKind(field: unknown): unknown;
 /**
  * The field properties a `source: 'introspected'` marker freezes — the ones the database owns.
  *
@@ -194,15 +238,19 @@ export declare const INTROSPECTED_IDENTITY_PROPS: readonly ["fieldname", "primar
  * 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. Identity is single-valued by design — a doctype describes the API
- *   surface, and mapping a composite database key onto one identity there is the adapter's job —
- *   so a doctype declaring several is malformed rather than composite. `DoctypeMeta` rejects that
- *   at the load gate; this stays total for callers holding fields that never went through it.
+ * Two deliberate rules, both matching the shape `primaryKey` actually has:
+ * - Fieldset children are **included**, via {@link flattenFields}. A fieldset is layout, not
+ *   scope: its children are fields of the doctype with columns of their own, which is why the
+ *   adapter's SELECT already descends and why `getDisplayField` does too. Scanning top level only
+ *   did not *refuse* a nested declaration — it ignored one, so an author marked identity and
+ *   nothing honoured it and nothing said so.
+ * - The **first** match in document order wins. Identity is single-valued by design — a doctype
+ *   describes the API surface, and mapping a composite database key onto one identity there is the
+ *   adapter's job — so a doctype declaring several is malformed rather than composite.
+ *   `DoctypeMeta` rejects that at the load gate; this stays total for callers holding fields that
+ *   never went through it.
  *
- * @param fields - the doctype's top-level fields
+ * @param fields - the doctype's fields; fieldset children are descended into
  * @returns the primary-key field, or `undefined` for a PK-less doctype
  * @public
  */

package/dist/src/field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/field.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/field.ts"],"names":[],"mappings":"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"}

package/dist/src/field.js

@@ -40,6 +40,37 @@ export const FieldValidation = z
 // ---------------------------------------------------------------------------
 // Zod runtime validation schemas
 // ---------------------------------------------------------------------------
+/**
+ * Which of the three field shapes an entry has, read from the entry's own structure.
+ *
+ * The single definition of that question. It had three copies before this — the parser's
+ * `injectKind`, {@link stripFieldKind}'s agreement check, and the docbuilder's own
+ * `isValueField` in another package — each free to drift, and drift here re-types a field rather
+ * than throwing: a value field read as a fieldset loses its column, a fieldset read as a value
+ * field loses every child.
+ *
+ * Deliberately **shape-only**: a declared `kind` is ignored. Two callers depend on that. The
+ * stripper compares this against the declaration to decide whether removing it is lossless, which
+ * it cannot do if this honours it. The docbuilder reads raw JSON off disk and classifies entries to
+ * decide which to render as editable rows — and `kind` is Stonecrop's own discriminant, not
+ * something a doctype author writes, so a tool reading a file has no business consulting it.
+ *
+ * `injectKind` is the one place a declaration still wins, and only to leave an already-parsed
+ * object untouched on its way back through.
+ *
+ * @param field - a field entry, authored or parsed
+ * @returns the kind its shape implies
+ * @public
+ */
+export function inferFieldKind(field) {
+    if (typeof field !== 'object' || field === null || Array.isArray(field))
+        return 'field';
+    if ('schema' in field)
+        return 'fieldset';
+    if ('columns' in field)
+        return 'table';
+    return 'field';
+}
 /**
  * Infers the `kind` discriminant from the structural properties of a raw field
  * object, then injects it if absent. This allows authored JSON to omit `kind`
@@ -63,13 +94,14 @@ function injectKind(data) {
         return data;
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- safe: non-null, non-array object verified by guards above
     const obj = data;
+    // An explicit `kind` is left exactly as it was found: this is the one place a declaration still
+    // beats the shape, and only so an already-parsed object survives a second pass unchanged.
+    // Returning `data` itself rather than rebuilding it also preserves identity and key order.
+    // Nothing outside this function shares that precedence — a reader classifying a file on disk
+    // wants `inferFieldKind`, because `kind` is ours and no author writes it.
     if ('kind' in obj)
         return data;
-    if ('schema' in obj)
-        return { kind: 'fieldset', ...obj };
-    if ('columns' in obj)
-        return { kind: 'table', ...obj };
-    return { kind: 'field', ...obj };
+    return { kind: inferFieldKind(obj), ...obj };
 }
 /**
  * Recursively injects the `kind` discriminant into a raw field object and, for fieldsets,
@@ -97,6 +129,39 @@ export function normalizeFieldKind(field) {
     }
     return injected;
 }
+/**
+ * Remove the `kind` discriminant from a field, recursing into a fieldset's children.
+ *
+ * The outbound half of the boundary {@link normalizeFieldKind} owns inbound. `kind` is a
+ * discriminated-union tag the parser synthesizes, not something an author writes, so nothing that
+ * *writes* a doctype should put it on disk — the generator and the docbuilder's save both call
+ * this. Without it the two round-trip asymmetrically: every save adds a key the file never had.
+ *
+ * Strips only when `injectKind` would restore exactly what was removed. A fieldset carrying no
+ * `schema` re-infers as a plain field, so its `kind` is kept rather than silently re-typing the
+ * document; `DoctypeMeta` requires `schema` on a fieldset, so that shape is already invalid and
+ * belongs to the load gate, not here.
+ *
+ * Table `columns` are {@link ColumnSchema} entries rather than `DoctypeField`s and never carry an
+ * injected `kind`, so they are passed through untouched — the same asymmetry `injectKind` has.
+ *
+ * @param field - a field object, as held in memory after parsing
+ * @returns the field without `kind`, safe to serialize
+ * @public
+ */
+export function stripFieldKind(field) {
+    if (typeof field !== 'object' || field === null || Array.isArray(field))
+        return field;
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- safe: non-null, non-array object verified by the guard above
+    const obj = field;
+    if (obj.kind !== undefined && obj.kind !== inferFieldKind(obj))
+        return field;
+    const { kind: _kind, ...rest } = obj;
+    if (Array.isArray(rest.schema)) {
+        return { ...rest, schema: rest.schema.map(stripFieldKind) };
+    }
+    return rest;
+}
 /**
  * The field properties a `source: 'introspected'` marker freezes — the ones the database owns.
  *
@@ -125,20 +190,24 @@ export const INTROSPECTED_IDENTITY_PROPS = [
  * 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. Identity is single-valued by design — a doctype describes the API
- *   surface, and mapping a composite database key onto one identity there is the adapter's job —
- *   so a doctype declaring several is malformed rather than composite. `DoctypeMeta` rejects that
- *   at the load gate; this stays total for callers holding fields that never went through it.
+ * Two deliberate rules, both matching the shape `primaryKey` actually has:
+ * - Fieldset children are **included**, via {@link flattenFields}. A fieldset is layout, not
+ *   scope: its children are fields of the doctype with columns of their own, which is why the
+ *   adapter's SELECT already descends and why `getDisplayField` does too. Scanning top level only
+ *   did not *refuse* a nested declaration — it ignored one, so an author marked identity and
+ *   nothing honoured it and nothing said so.
+ * - The **first** match in document order wins. Identity is single-valued by design — a doctype
+ *   describes the API surface, and mapping a composite database key onto one identity there is the
+ *   adapter's job — so a doctype declaring several is malformed rather than composite.
+ *   `DoctypeMeta` rejects that at the load gate; this stays total for callers holding fields that
+ *   never went through it.
  *
- * @param fields - the doctype's top-level fields
+ * @param fields - the doctype's fields; fieldset children are descended into
  * @returns the primary-key field, or `undefined` for a PK-less doctype
  * @public
  */
 export function getPrimaryKeyField(fields) {
-    return fields.find((f) => f.kind === 'field' && Boolean(f.primaryKey));
+    return flattenFields(fields).find((f) => f.kind === 'field' && Boolean(f.primaryKey));
 }
 /**
  * Recursively flatten Fieldset containers into a flat array of non-container fields.

package/dist/src/index.d.ts

@@ -2,11 +2,11 @@ export type { InteractionMode } from './mode';
 export { TableViewConfig } from './table';
 export { CANONICAL_COMPONENTS, COMPONENT_CATEGORY, COMPONENT_LINK_EXPANSION, componentCategory, componentLinkExpansion, resolveLinkRenderMode, type ComponentCategory, type LinkExpansion, type LinkRenderMode, } from './component-meta';
 export type { DoctypeField, FieldOptions, FieldValidation, FieldsetField, TableField, ValueField } from './field';
-export { DoctypeFieldSchema, FieldsetFieldSchema, flattenFields, getDisplayField, getPrimaryKeyField, getRecordIdentity, getRecordIdField, INTROSPECTED_IDENTITY_PROPS, normalizeFieldKind, TableFieldSchema, ValueFieldSchema, } from './field';
-export { ActionDefinition, TriggerDefinition, WorkflowLayout, WorkflowMeta, isActionAllowedInState, LINK_DISPLAY_SUFFIX, linkDisplayFieldname, } from './doctype';
+export { DoctypeFieldSchema, FieldsetFieldSchema, flattenFields, getDisplayField, getPrimaryKeyField, getRecordIdentity, getRecordIdField, INTROSPECTED_IDENTITY_PROPS, normalizeFieldKind, inferFieldKind, stripFieldKind, TableFieldSchema, ValueFieldSchema, } from './field';
+export { ActionDefinition, TriggerDefinition, WorkflowLayout, WorkflowMeta, getDoctypeSlug, isActionAllowedInState, LINK_DISPLAY_SUFFIX, linkDisplayFieldname, } from './doctype';
 export type { Cardinality, CustomFetch, DataClient, DoctypeContext, DoctypeMeta, DoctypeRef, FetchStrategy, GetRecordOptions, GetRecordResult, GetRecordsOptions, GetRecordsResult, LazyFetch, LinkDeclaration, SerializedFunction, SyncFetch, } from './doctype';
 export { parseDoctype, parseField, validateDoctype, validateField, type ValidationError, type ValidationResult, } from './validation';
-export { buildScalarMap, classifyFieldType, convertGraphQLSchema, defaultIsEntityField, defaultIsEntityType, formatDoctypeDrift, GQL_SCALAR_MAP, INTERNAL_SCALARS, mergeIntrospectedDoctype, WELL_KNOWN_SCALARS, type AuthoredDoctype, type ConvertedGraphQLDoctype, type DoctypeDrift, type GraphQLConversionFieldMeta, type GraphQLConversionOptions, type IntrospectionSource, type MergeResult, } from './converter';
+export { aggregateDoctypeName, buildAggregateDoctype, buildScalarMap, classifyFieldType, convertGraphQLSchema, defaultIsEntityField, defaultIsEntityType, formatDoctypeDrift, GQL_SCALAR_MAP, INTERNAL_SCALARS, mergeIntrospectedDoctype, planGeneration, WELL_KNOWN_SCALARS, type AuthoredDoctype, type ConvertedGraphQLDoctype, type DoctypeDrift, type GraphQLConversionFieldMeta, type GenerationPlanEntry, type GenerationPlanOptions, type GraphQLConversionOptions, type IntrospectionSource, type MergeOptions, type MergeResult, } from './converter';
 export { toSlug, toPascalCase, pascalToSnake, snakeToCamel, camelToSnake, snakeToLabel, camelToLabel } from './naming';
 export type { ColumnSchema } from './column-schema';
 export type { BadgeDescriptor, BadgePresentation, BadgeSpec, BadgeSpecObject, BadgeVariant, SelectOptions, } from './badge';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AAG7C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAGzC,OAAO,EACN,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,GACnB,MAAM,kBAAkB,CAAA;AAGzB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACjH,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,2BAA2B,EAC3B,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GAChB,MAAM,SAAS,CAAA;AAKhB,OAAO,EACN,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,GACpB,MAAM,WAAW,CAAA;AAClB,YAAY,EACX,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,SAAS,GACT,MAAM,WAAW,CAAA;AAGlB,OAAO,EACN,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACrB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACN,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,EACxB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,WAAW,GAChB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGtH,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD,YAAY,EACX,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,YAAY,EACZ,aAAa,GACb,MAAM,SAAS,CAAA;AAChB,OAAO,EACN,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,aAAa,GACb,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AAG7C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAGzC,OAAO,EACN,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,GACnB,MAAM,kBAAkB,CAAA;AAGzB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACjH,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,2BAA2B,EAC3B,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GAChB,MAAM,SAAS,CAAA;AAKhB,OAAO,EACN,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,GACpB,MAAM,WAAW,CAAA;AAClB,YAAY,EACX,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,SAAS,GACT,MAAM,WAAW,CAAA;AAGlB,OAAO,EACN,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACrB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACN,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,WAAW,GAChB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGtH,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD,YAAY,EACX,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,YAAY,EACZ,aAAa,GACb,MAAM,SAAS,CAAA;AAChB,OAAO,EACN,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,aAAa,GACb,MAAM,SAAS,CAAA"}

package/dist/src/index.js

@@ -2,15 +2,15 @@
 export { TableViewConfig } from './table';
 // Component → semantic category — the single source of "what kind of value does this component render"
 export { CANONICAL_COMPONENTS, COMPONENT_CATEGORY, COMPONENT_LINK_EXPANSION, componentCategory, componentLinkExpansion, resolveLinkRenderMode, } from './component-meta';
-export { DoctypeFieldSchema, FieldsetFieldSchema, flattenFields, getDisplayField, getPrimaryKeyField, getRecordIdentity, getRecordIdField, INTROSPECTED_IDENTITY_PROPS, normalizeFieldKind, TableFieldSchema, ValueFieldSchema, } from './field';
+export { DoctypeFieldSchema, FieldsetFieldSchema, flattenFields, getDisplayField, getPrimaryKeyField, getRecordIdentity, getRecordIdField, INTROSPECTED_IDENTITY_PROPS, normalizeFieldKind, inferFieldKind, stripFieldKind, TableFieldSchema, ValueFieldSchema, } from './field';
 // Doctype schema
 // ActionDefinition and WorkflowMeta are exported as values (Zod schemas) so consumers can use
 // .safeParse(), .shape, etc. at runtime. TypeScript types are inferred from the same exports.
-export { ActionDefinition, TriggerDefinition, WorkflowLayout, WorkflowMeta, isActionAllowedInState, LINK_DISPLAY_SUFFIX, linkDisplayFieldname, } from './doctype';
+export { ActionDefinition, TriggerDefinition, WorkflowLayout, WorkflowMeta, getDoctypeSlug, isActionAllowedInState, LINK_DISPLAY_SUFFIX, linkDisplayFieldname, } from './doctype';
 // Validation helpers
 export { parseDoctype, parseField, validateDoctype, validateField, } from './validation';
 // GraphQL to Doctype conversion
-export { buildScalarMap, classifyFieldType, convertGraphQLSchema, defaultIsEntityField, defaultIsEntityType, formatDoctypeDrift, GQL_SCALAR_MAP, INTERNAL_SCALARS, mergeIntrospectedDoctype, WELL_KNOWN_SCALARS, } from './converter';
+export { aggregateDoctypeName, buildAggregateDoctype, buildScalarMap, classifyFieldType, convertGraphQLSchema, defaultIsEntityField, defaultIsEntityType, formatDoctypeDrift, GQL_SCALAR_MAP, INTERNAL_SCALARS, mergeIntrospectedDoctype, planGeneration, WELL_KNOWN_SCALARS, } from './converter';
 // Naming utilities
 export { toSlug, toPascalCase, pascalToSnake, snakeToCamel, camelToSnake, snakeToLabel, camelToLabel } from './naming';
 export { hasBadgeOptions, isBadgeDescriptor, isSelectChoiceMap, isSelectOptions, lookupBadge, selectChoices, } from './badge';