@fougere/schema 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,46 @@
+// ─── The primitive — a Field on four orthogonal axes + meta ──
+export { isField, cloneField, nullableShape, anatomy, 
+// The constraint a `role.unique` member list denotes — `[]` means the field carrying it.
+uniqueMembers, isNullable, registerGenerator, resolveCustomGenerator, resolveBoundary, declaredBoundary, boundaryOf, registerDecoder, registerEncoder, registerBoundaryAlias, } from './field/index.js';
+// ─── The carrier and its derivation algebra ──────────────────
+export { entity, compose, createSchemaConstructor, ANONYMOUS_SCHEMA_NAME, } from './entity.js';
+// ─── The vocabulary — field constructors and transforms ──────
+export { primary } from './vocabulary/primary.js';
+export { text } from './vocabulary/text.js';
+export { email } from './vocabulary/email.js';
+export { url } from './vocabulary/url.js';
+export { list } from './vocabulary/list.js';
+export { number } from './vocabulary/number.js';
+export { bool } from './vocabulary/bool.js';
+export { date } from './vocabulary/date.js';
+export { auto } from './vocabulary/auto.js';
+export { updated } from './vocabulary/updated.js';
+export { oneOf } from './vocabulary/oneOf.js';
+export { ref } from './vocabulary/ref.js';
+export { many } from './vocabulary/many.js';
+export { optional } from './vocabulary/optional.js';
+export { nullable } from './vocabulary/nullable.js';
+export { immutable } from './vocabulary/immutable.js';
+export { unique } from './vocabulary/unique.js';
+export { indexed } from './vocabulary/indexed.js';
+export { readOnly } from './vocabulary/readOnly.js';
+export { writeOnly } from './vocabulary/writeOnly.js';
+export { json } from './vocabulary/json.js';
+// ─── Projections — consumers of the axes ─────────────────────
+// lifecycle: the axis → the values the system writes. The dual of validation — the
+// judge never fills a hole, this is what fills it, and a storage adapter calls it
+// instead of re-deriving the rule.
+export { applyCreate, applyUpdate } from './projections/lifecycle.js';
+// validation: shape → ingress predicate (+ boundary decode)
+export { validateFields, checkValue } from './projections/validation.js';
+// encode: boundary → egress wire form (the dual of validation)
+export { encodeFields } from './projections/encode.js';
+// io: the dual client-surface projections — ingress (may supply) / egress (may read)
+export { inputFields, outputFields } from './projections/io.js';
+// descriptor (the card): the portable, serialisable identity of a schema
+export { describe, describeSet, sourceNameOf } from './projections/describe.js';
+export { reconstruct, reconstructSet } from './projections/reconstruct.js';
+export { shapeTypeOf, entitySourceOf, facadeTypeSourceOf } from './projections/typescript.js';
+// source: the one reader that takes a live class OR a card — what an adapter stands on
+export { schemaOf, fieldsOf, uniqueOf } from './projections/source.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,OAAO,EAmBL,OAAO,EACP,UAAU,EACV,aAAa,EACb,OAAO;AACP,yFAAyF;AACzF,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,eAAe,EACf,qBAAqB,GAMtB,MAAM,kBAAkB,CAAC;AAE1B,gEAAgE;AAChE,OAAO,EACL,MAAM,EACN,OAAO,EACP,uBAAuB,EACvB,qBAAqB,GAItB,MAAM,aAAa,CAAC;AAIrB,gEAAgE;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAoB,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAoB,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAE5C,gEAAgE;AAChE,mFAAmF;AACnF,kFAAkF;AAClF,mCAAmC;AACnC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACtE,4DAA4D;AAC5D,OAAO,EAA6D,cAAc,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACpI,+DAA+D;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,qFAAqF;AACrF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChE,yEAAyE;AACzE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAA6C,MAAM,6BAA6B,CAAC;AAUzI,uFAAuF;AACvF,OAAO,EAAqB,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/projections/card.d.ts

@@ -0,0 +1,117 @@
+import type { BoundaryRef, Lifecycle } from '../field/index.js';
+/**
+ * The portable schema descriptor — Fougère's "carte d'identité" of an entity.
+ *
+ * It is a JSON Schema document (the `shape` axis, a near-identity projection now
+ * that {@link FieldDescriptor} already speaks JSON Schema) carrying the three axes JSON
+ * Schema cannot express under a single `x-fougere` extension key per field: `role`
+ * (identity/relations), `lifecycle` (write rules), `boundary` (wire↔domain).
+ * The normal forms (named tokens, pure JSON) ARE the wire form — lifecycle and
+ * boundary travel verbatim, no descriptor twin to maintain.
+ *
+ * It is the structural counterpart of Standard Schema (`~standard`): where
+ * `~standard` is the live, opaque "I can validate" interface, the descriptor is the
+ * transparent, serialisable description that crosses the wire. `describe()` produces
+ * it; a single `reconstruct()` reads it back into a working schema (validate + from).
+ *
+ * Honest losses vs the live field map — a reference becomes a name, a live function
+ * does not travel:
+ * - `role.relation.to` (a `() => Entity` thunk) → {@link RelationDescriptor.to}, a name.
+ * - a custom generator or boundary decoder/encoder travels by NAME, re-resolved
+ *   against the consumer's registry ("unknown generator/alias" is loud and local).
+ */
+/** JSON Schema's `type` values, plus `null` for the nullable union form. */
+export type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+/**
+ * One field as a JSON Schema property. The shape keywords sit at the top level
+ * (so an external JSON Schema tool reads them directly); the Fougère-only axes
+ * live under `x-fougere`. A nullable field folds into the union `type: ['T','null']`.
+ */
+export interface FieldDescriptor {
+    type?: JsonSchemaType | JsonSchemaType[];
+    /** JSON Schema format predicate (`date-time` for a date value, email, uuid, uri…). */
+    format?: 'date-time' | 'date' | 'time' | 'email' | 'uuid' | 'uri';
+    enum?: readonly (string | null)[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    /** A value list's element shape (`list(text())`). A bare `many` relation has none. */
+    items?: FieldDescriptor;
+    minItems?: number;
+    maxItems?: number;
+    /** An embedded value object (`json(Entity)`): the nested shape-only properties. */
+    properties?: Record<string, FieldDescriptor>;
+    /** The embedded object's required keys (JSON Schema nesting, travels verbatim). */
+    required?: readonly string[];
+    /** JSON Schema standard keyword — mirrors the field's `description`. */
+    description?: string;
+    'x-fougere'?: FieldExtension;
+}
+/** The three axes JSON Schema can't express, namespaced under a field's `x-fougere`. */
+export interface FieldExtension {
+    role?: RoleDescriptor;
+    /** The normal form travels verbatim — named tokens, pure JSON. */
+    lifecycle?: Lifecycle;
+    boundary?: BoundaryRef;
+}
+export interface RoleDescriptor {
+    primary?: boolean;
+    /**
+     * The unique constraints this field is a member of — one member list each, member
+     * names spelled out. `[["slug"]]` is unique on its own; `[["listId","docId"]]` on both
+     * members says the pair is unique together, which is the fact a foreign consumer could
+     * not read before: the card carried one boolean per field and the pair vanished.
+     *
+     * Self-reference is resolved on the way out (a lone `unique()` holds `[]` in memory,
+     * because a field does not know its own key) — a card always names its members, so a
+     * reader never has to know which field a group hangs on.
+     */
+    unique?: string[][];
+    index?: boolean;
+    relation?: RelationDescriptor;
+}
+/** A relation as portable data: the target is a NAME, not a live entity thunk. */
+export interface RelationDescriptor {
+    to: string;
+    kind: 'one' | 'many';
+    onDelete?: 'cascade' | 'restrict' | 'set null';
+}
+/**
+ * A whole entity as a JSON Schema object document. `version`/`vendor` mirror Standard
+ * Schema's own (versioned + vendored), under `x-` extension keywords so the document
+ * stays a valid JSON Schema for external tooling.
+ */
+export interface SchemaDescriptor {
+    /** The entity name. */
+    title?: string;
+    type: 'object';
+    properties: Record<string, FieldDescriptor>;
+    /**
+     * Create-time semantics: the names a caller MUST supply — no `lifecycle.create`
+     * rule answers absence (nor a `many` relation, absent → `[]`). Presence only:
+     * a nullable-but-required field IS listed (supply `null`, don't omit the key).
+     * Narrower than JSON Schema's context-free `required`: it answers "what must a
+     * creation payload carry?", not "what is always present when read?".
+     */
+    required?: string[];
+    'x-fougere-version': 1;
+    'x-fougere-vendor': 'fougere';
+}
+/**
+ * A self-contained set of entity cards — a JSON Schema bundle. Every entity lives
+ * under `$defs`, keyed by name; a relation's `to` is that name — the `$ref` into
+ * `$defs`. The document is portable AND circular-safe: a relation is a pointer, never
+ * an inlined sub-schema, so `Post → Author → Post` is two references, not infinite
+ * nesting. `reconstructSet` resolves those `$ref`s so a synced relation hands back the
+ * real reconstructed target (it feeds adapters), not just a name.
+ */
+export interface SchemaBundle {
+    $defs: Record<string, SchemaDescriptor>;
+    'x-fougere-version': 1;
+    'x-fougere-vendor': 'fougere';
+}
+/** Drop keys whose value is `undefined`, so the descriptor stays clean JSON. */
+export declare function clean<T extends Record<string, unknown>>(obj: T): T;
+//# sourceMappingURL=card.d.ts.map

package/dist/projections/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../src/projections/card.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,SAAS,GACT,QAAQ,GACR,OAAO,GACP,MAAM,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC;IACzC,sFAAsF;IACtF,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IAClE,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC7C,mFAAmF;IACnF,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,kEAAkE;IAClE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,EAAE,CAAC,CAAC;IACvB,kBAAkB,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACxC,mBAAmB,EAAE,CAAC,CAAC;IACvB,kBAAkB,EAAE,SAAS,CAAC;CAC/B;AAED,gFAAgF;AAChF,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAGlE"}

package/dist/projections/card.js

@@ -0,0 +1,8 @@
+/** Drop keys whose value is `undefined`, so the descriptor stays clean JSON. */
+export function clean(obj) {
+    for (const key of Object.keys(obj))
+        if (obj[key] === undefined)
+            delete obj[key];
+    return obj;
+}
+//# sourceMappingURL=card.js.map

package/dist/projections/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../../src/projections/card.ts"],"names":[],"mappings":"AAkIA,gFAAgF;AAChF,MAAM,UAAU,KAAK,CAAoC,GAAM;IAC7D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;IAChF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/projections/describe.d.ts

@@ -0,0 +1,25 @@
+import type { SchemaLike } from '../field/index.js';
+import { type SchemaBundle, type SchemaDescriptor } from './card.js';
+/**
+ * Produce the portable card for a schema — THE single canonical serialiser
+ * (the hand-rolled copies in adapters call this). `name` titles the entity; it
+ * falls back to the schema's source/class name when omitted.
+ */
+export declare function describe(schema: SchemaLike, name?: string): SchemaDescriptor;
+/**
+ * The name of the schema a view came from — `Post` for `Post`, and `Post` for
+ * `Post.pick('title')` too, since a derivation carries its `source`.
+ *
+ * Exported because two projections need the SAME answer: the card titles an entity with it,
+ * and GraphQL names a field's enum type with it — an enum named after the view would give
+ * `Post.status` and `CreatePostInput.status` two incompatible types for one set of values.
+ */
+export declare function sourceNameOf(schema: SchemaLike): string | undefined;
+/**
+ * Describe a whole set of entities as one self-contained bundle (the `$defs`
+ * document). Accepts a name→schema record or an array (names taken from the
+ * schemas). Keys are lowercased to match the relation `to` names `describe` emits,
+ * so `$ref`-by-name resolves cleanly in {@link reconstructSet}.
+ */
+export declare function describeSet(schemas: Record<string, SchemaLike> | SchemaLike[]): SchemaBundle;
+//# sourceMappingURL=describe.d.ts.map

package/dist/projections/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/projections/describe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpE,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,WAAW,CAAC;AAkEnB;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAiB5E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,UAAU,EAAE,GAAG,YAAY,CAU5F"}

package/dist/projections/describe.js

@@ -0,0 +1,129 @@
+import { uniqueMembers } from '../field/index.js';
+import { clean, } from './card.js';
+// ─── describe — schema → card (the single canonical serialiser) ────
+/**
+ * A caller must supply this field: no create rule answers absence, and it is not
+ * a `many` relation (absent → `[]`). Presence only — nullability is the OTHER
+ * axis: a `nullable()` field stays required (the caller may supply `null`, not
+ * omit the key), exactly what `validateFields` enforces.
+ */
+function isRequired(field) {
+    if (field.lifecycle?.create !== undefined)
+        return false;
+    if (field.role?.relation?.kind === 'many')
+        return false;
+    return true;
+}
+function describeRole(role, key) {
+    const out = {};
+    if (role.primary)
+        out.primary = true;
+    // Members are spelled out on the wire: in memory a lone `unique()` holds the empty
+    // self-reference (a field cannot name its own key), and a consumer has no way to know
+    // which field a group hangs on. `key` is that missing half, so it is resolved here.
+    if (role.unique?.length)
+        out.unique = role.unique.map((group) => uniqueMembers(group, key));
+    if (role.index)
+        out.index = true;
+    if (role.relation) {
+        out.relation = clean({
+            to: role.relation.to().name?.toLowerCase() ?? '', // thunk → name
+            kind: role.relation.kind,
+            onDelete: role.relation.onDelete,
+        });
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+function describeExtension(field, key) {
+    const ext = {};
+    if (field.role)
+        ext.role = describeRole(field.role, key);
+    // The normal forms are named tokens, pure JSON — they travel verbatim
+    // (a custom generator travels by NAME, re-resolved against the consumer's registry).
+    if (field.lifecycle)
+        ext.lifecycle = field.lifecycle;
+    // Carry only an explicit override; the derived default (date → isoDate) is
+    // re-derived from `shape.format` on reconstruction (convention over config).
+    if (field.boundary !== undefined)
+        ext.boundary = field.boundary;
+    clean(ext);
+    return Object.keys(ext).length ? ext : undefined;
+}
+function describeField(field, key) {
+    const out = {};
+    // Shape is already JSON Schema's vocabulary — nullability included, as the
+    // `[T,'null']` type union — so its keywords copy verbatim (an embedded object's
+    // `properties`/`required` too, themselves shape-only).
+    if (field.shape) {
+        for (const [key, value] of Object.entries(field.shape)) {
+            if (value === undefined)
+                continue;
+            out[key] = value;
+        }
+    }
+    else if (field.role?.relation?.kind === 'many') {
+        out.type = 'array';
+    }
+    if (field.meta?.description)
+        out.description = field.meta.description;
+    const ext = describeExtension(field, key);
+    if (ext)
+        out['x-fougere'] = ext;
+    return out;
+}
+/**
+ * Produce the portable card for a schema — THE single canonical serialiser
+ * (the hand-rolled copies in adapters call this). `name` titles the entity; it
+ * falls back to the schema's source/class name when omitted.
+ */
+export function describe(schema, name) {
+    const properties = {};
+    const required = [];
+    for (const [key, field] of Object.entries(schema.getFields())) {
+        properties[key] = describeField(field, key);
+        if (isRequired(field))
+            required.push(key);
+    }
+    const descriptor = {
+        type: 'object',
+        properties,
+        'x-fougere-version': 1,
+        'x-fougere-vendor': 'fougere',
+    };
+    const title = name ?? sourceNameOf(schema);
+    if (title)
+        descriptor.title = title;
+    if (required.length)
+        descriptor.required = required;
+    return descriptor;
+}
+/**
+ * The name of the schema a view came from — `Post` for `Post`, and `Post` for
+ * `Post.pick('title')` too, since a derivation carries its `source`.
+ *
+ * Exported because two projections need the SAME answer: the card titles an entity with it,
+ * and GraphQL names a field's enum type with it — an enum named after the view would give
+ * `Post.status` and `CreatePostInput.status` two incompatible types for one set of values.
+ */
+export function sourceNameOf(schema) {
+    const s = schema;
+    return s.source?.name ?? s.name;
+}
+/**
+ * Describe a whole set of entities as one self-contained bundle (the `$defs`
+ * document). Accepts a name→schema record or an array (names taken from the
+ * schemas). Keys are lowercased to match the relation `to` names `describe` emits,
+ * so `$ref`-by-name resolves cleanly in {@link reconstructSet}.
+ */
+export function describeSet(schemas) {
+    const entries = Array.isArray(schemas)
+        ? schemas.map((s) => [sourceNameOf(s) ?? '', s])
+        : Object.entries(schemas);
+    const $defs = {};
+    for (const [name, schema] of entries) {
+        const key = name.toLowerCase();
+        $defs[key] = describe(schema, key);
+    }
+    return { $defs, 'x-fougere-version': 1, 'x-fougere-vendor': 'fougere' };
+}
+//# sourceMappingURL=describe.js.map

package/dist/projections/describe.js.map

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

package/dist/projections/encode.d.ts

@@ -0,0 +1,11 @@
+import type { Fields } from '../field/index.js';
+/**
+ * Egress: encode a domain record into its wire form, field by field — the dual of
+ * `validateFields` (which decodes on ingress). A write-only field (boundary
+ * `out: 'closed'`, e.g. a password) is OMITTED — it never crosses outbound.
+ * Keys absent from `fields` (e.g. presenter computed fields) pass through
+ * untouched; null/undefined are left as-is.
+ * Shallow by design: a relation's nested rows are not deep-encoded here.
+ */
+export declare function encodeFields(fields: Fields, record: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=encode.d.ts.map

package/dist/projections/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/projections/encode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUrG"}

package/dist/projections/encode.js

@@ -0,0 +1,26 @@
+import { boundaryOf, resolveBoundary } from '../field/index.js';
+/**
+ * Egress: encode a domain record into its wire form, field by field — the dual of
+ * `validateFields` (which decodes on ingress). A write-only field (boundary
+ * `out: 'closed'`, e.g. a password) is OMITTED — it never crosses outbound.
+ * Keys absent from `fields` (e.g. presenter computed fields) pass through
+ * untouched; null/undefined are left as-is.
+ * Shallow by design: a relation's nested rows are not deep-encoded here.
+ */
+export function encodeFields(fields, record) {
+    const out = { ...record };
+    for (const [key, field] of Object.entries(fields)) {
+        if (!(key in record))
+            continue;
+        if (boundaryOf(field).out === 'closed') {
+            delete out[key];
+            continue;
+        }
+        const value = record[key];
+        if (value === null || value === undefined)
+            continue;
+        out[key] = resolveBoundary(field).encode(value);
+    }
+    return out;
+}
+//# sourceMappingURL=encode.js.map

package/dist/projections/encode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.js","sourceRoot":"","sources":["../../src/projections/encode.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,MAA+B;IAC1E,MAAM,GAAG,GAA4B,EAAE,GAAG,MAAM,EAAE,CAAC;IACnD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC;YAAE,SAAS;QAC/B,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YAAC,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QACtE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QACpD,GAAG,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/projections/io.d.ts

@@ -0,0 +1,30 @@
+import type { Fields } from '../field/index.js';
+/**
+ * The two dual projections of a field set onto a client surface — membership
+ * only, derived from the axes.
+ *
+ * The create/patch MODE never changes membership, it only changes omissibility, which
+ * the view (`partial()`) carries.
+ *
+ * ⚠️ The audience lives in this comment, not in the data — no axis says "client", so
+ * these two functions are the only place the word exists. Surfaces are SUPPOSED to read
+ * them instead of restating the rules, and several don't: the GraphQL public
+ * `registerInput`, the runtime judge and the CLI each answer "what may a client supply"
+ * with a different set. The judge is the most permissive — a client-forged primary key
+ * reaches the ORM. Reconciling them needs the audience to become data.
+ */
+/**
+ * Ingress: what a CLIENT may supply. Excluded —
+ * - `role.primary`               → identity is system-owned
+ * - `lifecycle.create === 'now'` → managed timestamps are stamped, not supplied
+ * - `role.relation.kind 'many'`  → the collection lives on the other side
+ * - `boundary.in === 'closed'`   → read-only, never accepted from a client
+ */
+export declare function inputFields(fields: Fields): Fields;
+/**
+ * Egress: what a CLIENT may read. Excluded —
+ * - `boundary.out === 'closed'` → write-only (password), never emitted
+ * (`encodeFields` also omits them at runtime; types and payloads agree.)
+ */
+export declare function outputFields(fields: Fields): Fields;
+//# sourceMappingURL=io.d.ts.map

package/dist/projections/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/projections/io.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAUlD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOnD"}

package/dist/projections/io.js

@@ -0,0 +1,52 @@
+import { boundaryOf } from '../field/index.js';
+/**
+ * The two dual projections of a field set onto a client surface — membership
+ * only, derived from the axes.
+ *
+ * The create/patch MODE never changes membership, it only changes omissibility, which
+ * the view (`partial()`) carries.
+ *
+ * ⚠️ The audience lives in this comment, not in the data — no axis says "client", so
+ * these two functions are the only place the word exists. Surfaces are SUPPOSED to read
+ * them instead of restating the rules, and several don't: the GraphQL public
+ * `registerInput`, the runtime judge and the CLI each answer "what may a client supply"
+ * with a different set. The judge is the most permissive — a client-forged primary key
+ * reaches the ORM. Reconciling them needs the audience to become data.
+ */
+/**
+ * Ingress: what a CLIENT may supply. Excluded —
+ * - `role.primary`               → identity is system-owned
+ * - `lifecycle.create === 'now'` → managed timestamps are stamped, not supplied
+ * - `role.relation.kind 'many'`  → the collection lives on the other side
+ * - `boundary.in === 'closed'`   → read-only, never accepted from a client
+ */
+export function inputFields(fields) {
+    const result = {};
+    for (const [name, field] of Object.entries(fields)) {
+        if (field.role?.primary)
+            continue;
+        if (field.lifecycle?.create === 'now')
+            continue;
+        if (field.role?.relation?.kind === 'many')
+            continue;
+        if (boundaryOf(field).in === 'closed')
+            continue;
+        result[name] = field;
+    }
+    return result;
+}
+/**
+ * Egress: what a CLIENT may read. Excluded —
+ * - `boundary.out === 'closed'` → write-only (password), never emitted
+ * (`encodeFields` also omits them at runtime; types and payloads agree.)
+ */
+export function outputFields(fields) {
+    const result = {};
+    for (const [name, field] of Object.entries(fields)) {
+        if (boundaryOf(field).out === 'closed')
+            continue;
+        result[name] = field;
+    }
+    return result;
+}
+//# sourceMappingURL=io.js.map

package/dist/projections/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/projections/io.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,MAAM,MAAM,GAAW,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,KAAK,CAAC,IAAI,EAAE,OAAO;YAAE,SAAS;QAClC,IAAI,KAAK,CAAC,SAAS,EAAE,MAAM,KAAK,KAAK;YAAE,SAAS;QAChD,IAAI,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,KAAK,MAAM;YAAE,SAAS;QACpD,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,QAAQ;YAAE,SAAS;QAChD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,MAAM,GAAW,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,QAAQ;YAAE,SAAS;QACjD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/projections/lifecycle.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The lifecycle axis, realized — once, for every storage.
+ *
+ * `validation.ts` states the split: the judge answers "is this value legal?" and never
+ * fills a hole; filling it — stamp `'now'`, apply `{ value }`, call `{ generate }` — is
+ * the storage's role at the point of persistence. The split is right. What was missing
+ * is that the framework shipped the RULE and never its realization, so each storage
+ * rewrote it and they drifted:
+ *
+ * - `schema-sql` realized `{ generate }` and `'now'` in its ORM, and `{ value }` in its
+ *   DDL — as a column `DEFAULT` the database fills. A mechanism only SQL has.
+ * - The Nuxt module's fallback ORM realized none of the three: its signature is
+ *   `(_entity, _name)`, both ignored, so it forces the name `id` and a random uuid.
+ * - A third-party adapter (MongoDB, written outside the repo on 2026-08-08) found the
+ *   gap the only way available: a test that expected `'draft'` and got `undefined`.
+ *
+ * Measured, one entity, `oneOf('draft','published',{ default:'draft' })`: SQLite answered
+ * `'draft'`, MongoDB answered `undefined`. Same declaration, same port, two answers.
+ *
+ * So the rule and its realization live together now, and a storage adapter calls this
+ * instead of re-deriving it. `update: 'forbidden'` is NOT here: refusing a value is a
+ * judgment, and the façade already does it (`validation.ts`, patch mode).
+ */
+import { type Fields } from '../field/index.js';
+type Row = Record<string, unknown>;
+/**
+ * Fill what the entity says the system writes at creation.
+ *
+ * A value the caller supplied is never touched, including `null` — presence is the
+ * test, not truthiness, so `archivedAt: null` stays null rather than being re-filled.
+ *
+ * `'now'` produces a `Date`, the value the field declares. The storage converts it if
+ * its driver needs something else (`schema-sql/src/values.ts` does exactly that) —
+ * which is the same direction every other value travels.
+ */
+export declare function applyCreate(fields: Fields, input: Row): Row;
+/**
+ * Fill what the entity says the system writes at every update — `updated()`, and
+ * nothing else. A supplied value wins, same rule as create.
+ */
+export declare function applyUpdate(fields: Fields, patch: Row): Row;
+export {};
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/projections/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/projections/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAyC,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGvF,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA8BnC;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,GAAG,CAqB3D;AAgBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,GAAG,CAS3D"}