@ogygie/generate 0.0.0-stage → 0.19.0

package/dist/screen-block.schema.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @intent Zod schema AND parser of the `# Génération` block of a SCREEN spec
+ * (DECISIONS.md D41): one fenced YAML block, three keys — `consumes` (the API
+ * features and the operations the screen uses), `views` (`list`, `form`,
+ * `custom`, each on ONE operation) and `holes` (the custom views: what they
+ * receive, which writes they may trigger, what their render must show) — plus
+ * an OPTIONAL `route`, the path the screen mounts on. What the shape alone
+ * cannot check — do the operations exist in the consumed blocks, are the
+ * fields of the output or the input — is `screen-checks.ts`, which needs the
+ * consumed features; this module checks the block against itself and refuses
+ * at its path (`OGYGIE_GENERATION_BLOCK_INVALID`, `details.path`), as the
+ * feature block does.
+ */
+import { z } from "zod";
+import type { OgygieError } from "@ogygie/core/errors";
+import { type BlockLocation } from "./generation-block.schema.js";
+export declare const SCREEN_BLOCK_KEYS: readonly ["route", "consumes", "views", "holes"];
+/** A feature id of the map, kebab-case (French ids allowed, as everywhere). */
+export declare const FeatureIdSchema: z.ZodString;
+/** A front path: `/`, `/rates`, `/settings/archetypes` — no parameter in M1. */
+export declare const ScreenRouteSchema: z.ZodString;
+export declare const ConsumedFeatureSchema: z.ZodObject<{
+    feature: z.ZodString;
+    operations: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ConsumedFeature = z.infer<typeof ConsumedFeatureSchema>;
+/** A DataTable over the collection a read serves: its element's fields, in order. */
+export declare const ListViewSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"list">;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sort: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>], null>>;
+    id: z.ZodString;
+    operation: z.ZodString;
+}, z.core.$strict>;
+/** A ContractForm over the input a write expects, calling its mutation. */
+export declare const FormViewSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"form">;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    multiline: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    id: z.ZodString;
+    operation: z.ZodString;
+}, z.core.$strict>;
+/** A view that is thought: a component with a hole, fed by a read's output. */
+export declare const CustomViewSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"custom">;
+    hole: z.ZodString;
+    id: z.ZodString;
+    operation: z.ZodString;
+}, z.core.$strict>;
+export declare const ViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"list">;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sort: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>], null>>;
+    id: z.ZodString;
+    operation: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"form">;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    multiline: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    id: z.ZodString;
+    operation: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"custom">;
+    hole: z.ZodString;
+    id: z.ZodString;
+    operation: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type View = z.infer<typeof ViewSchema>;
+export type ListView = Extract<View, {
+    kind: "list";
+}>;
+export type FormView = Extract<View, {
+    kind: "form";
+}>;
+export type CustomView = Extract<View, {
+    kind: "custom";
+}>;
+export declare const ScreenHoleSchema: z.ZodObject<{
+    id: z.ZodString;
+    receives: z.ZodArray<z.ZodString>;
+    actions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    examples: z.ZodObject<{
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        renders: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ScreenHole = z.infer<typeof ScreenHoleSchema>;
+export declare const ScreenBlockSchema: z.ZodObject<{
+    route: z.ZodOptional<z.ZodString>;
+    consumes: z.ZodArray<z.ZodObject<{
+        feature: z.ZodString;
+        operations: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    views: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"list">;
+        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sort: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>], null>>;
+        id: z.ZodString;
+        operation: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"form">;
+        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        multiline: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        id: z.ZodString;
+        operation: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"custom">;
+        hole: z.ZodString;
+        id: z.ZodString;
+        operation: z.ZodString;
+    }, z.core.$strict>], "kind">>;
+    holes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        receives: z.ZodArray<z.ZodString>;
+        actions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        examples: z.ZodObject<{
+            input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            renders: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ScreenBlock = z.infer<typeof ScreenBlockSchema>;
+export type ScreenBlockParse = {
+    ok: true;
+    block: ScreenBlock;
+} | {
+    ok: false;
+    problems: OgygieError[];
+};
+/** Validates an already-parsed screen block value. */
+export declare function validateScreenBlock(raw: unknown, location: BlockLocation): ScreenBlockParse;
+/** Reads the YAML text of a screen block, then validates it. */
+export declare function parseScreenBlock(yamlText: string, location: BlockLocation): ScreenBlockParse;
+/** The consumed feature an operation belongs to, or null when the block does not consume it. */
+export declare function consumerOf(block: ScreenBlock, operationId: string): ConsumedFeature | null;
+/** The read whose output the screen's ScreenState waits for: the first list or custom view (D40). */
+export declare function primaryViewOf(block: ScreenBlock): ListView | CustomView | null;

package/dist/screen-checks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @intent What a screen block cannot check against itself (D41): that every
+ * consumed feature is on the map — with a `# Génération` block, or, without
+ * one, with GET routes the screen may read (precision of lot 4 M3) — that every
+ * consumed operation is one the feature offers, that a `list` or
+ * `custom` view serves a read whose output carries a collection, that a `form`
+ * serves a write — a create or an import in this lot: a form on a keyed write
+ * needs the row it addresses, which is a custom view — and that every field a
+ * view shows or receives exists in the output's element or the input. Each
+ * refusal names its path, like the block's own checks.
+ */
+import { type OgygieError } from "@ogygie/core/errors";
+import { type ConsumedRoute } from "./consumed-feature.js";
+import { type GenerationBlock } from "./generation-block.schema.js";
+import type { ScreenBlock } from "./screen-block.schema.js";
+import type { FieldModel, SchemaModels } from "./zod-introspection.js";
+export interface ConsumedFeatureCheckInput {
+    featureId: string;
+    /** Null when the feature is on the map but its spec carries no block, or its block does not parse. */
+    block: GenerationBlock | null;
+    /** Null when the feature's schemas module could not be loaded. */
+    schemas: SchemaModels | null;
+    /** The feature's routes as the map declares them: what a feature without a block offers to read (D41 precision). */
+    routes: readonly ConsumedRoute[];
+}
+export interface ScreenCheckInput {
+    block: ScreenBlock;
+    specPath: string;
+    /** The consumed features, as the project resolved them — absent when the map does not know the feature. */
+    consumed: ReadonlyMap<string, ConsumedFeatureCheckInput>;
+}
+/** The element fields of a read output — the one array of objects it carries. */
+export declare function elementFieldsOf(outputModel: FieldModel | undefined): string[] | null;
+export declare function checkScreenBlock(input: ScreenCheckInput): OgygieError[];

package/dist/screen-grammar.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @intent The parser of the closed SCREEN behavior grammar (DECISIONS.md D20,
+ * precision of lot 4 M1):
+ *
+ *   ÉTANT DONNÉ <vue> avec <état>[, [avec|sans] <état>]* ALORS <rendu>[, <rendu>]* [[hole:<id>]]
+ *
+ * Pure text in, structure out — the binder (screen-vocabulary.ts) says
+ * whether the view exists and the words are in its vocabulary. No status: a
+ * screen does not answer, it renders. `<vue>` is a view id of the block or
+ * the word « écran » (the whole screen, its primary read). The keywords are
+ * French (a spec is for the humans of the project); the identifiers a line
+ * cites — view ids, operation ids, field names — are the code's.
+ */
+export declare const SCREEN_SUBJECT = "\u00E9cran";
+export interface ScreenCase {
+    polarity: "with" | "without";
+    phrase: string;
+}
+export interface ParsedScreenBehavior {
+    raw: string;
+    /** A view id, or `écran`. */
+    view: string;
+    cases: ScreenCase[];
+    renders: string[];
+    hole: string | null;
+}
+export type ScreenParseResult = {
+    ok: true;
+    behavior: ParsedScreenBehavior;
+} | {
+    ok: false;
+    raw: string;
+    hole: string | null;
+    reason: string;
+};
+export declare function parseScreenBehavior(input: string): ScreenParseResult;

package/dist/screen-vocabulary.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @intent The vocabulary of ONE view of a screen (DECISIONS.md D20, precision
+ * of lot 4 M1) and the binder of a screen behavior line. A read view (`list`,
+ * `custom`, or the whole screen « écran ») speaks of its states — loading,
+ * error, access denied, rows, no row — and of what it renders — the skeleton,
+ * the error banner, the access explanation, the empty state, the rows, their
+ * order; a `form` view speaks of a valid or invalid form, of a refused write,
+ * and renders the write it triggers, the error sentences, or nothing written.
+ * A line whose every word is in here is derived without a model; a word
+ * outside it needs a hole — a custom view.
+ */
+import { type OgygieError } from "@ogygie/core/errors";
+import { type ScreenParseResult } from "./screen-grammar.js";
+import { type ScreenBlock, type View } from "./screen-block.schema.js";
+export interface ScreenVocabulary {
+    /** Normalized state keys: `with:<phrase>` / `without:<phrase>`. */
+    states: ReadonlySet<string>;
+    renders: ReadonlySet<string>;
+}
+export declare const READ_STATES: readonly ["with:chargement", "with:erreur", "with:accès refusé", "with:lignes", "without:ligne"];
+export declare const READ_RENDERS: readonly ["squelette", "bandeau d'erreur", "explication d'accès", "état vide", "lignes"];
+export declare const FORM_STATES: readonly ["with:formulaire valide", "with:formulaire invalide", "with:écriture refusée"];
+export declare const FORM_RENDERS: readonly ["phrases d'erreur", "rien n'est écrit", "bandeau d'erreur"];
+export declare function screenCaseKey(polarity: "with" | "without", phrase: string): string;
+/** What a line may say of a view — the whole screen speaks like its primary read view. */
+export declare function screenVocabularyOf(view: View | null, block: ScreenBlock, sortableFields?: readonly string[]): ScreenVocabulary;
+export interface ScreenBindingContext {
+    block: ScreenBlock;
+    /** The fields a list view may order by when it declares none: the element fields of its operation's output, when known. */
+    sortableFieldsOf?: (view: View) => readonly string[];
+    specPath: string;
+    line: number;
+}
+export type ScreenBindingOutcome = {
+    ok: true;
+    status: "derivable";
+    view: View | null;
+} | {
+    ok: true;
+    status: "hole";
+    hole: string;
+    view: View | null;
+} | {
+    ok: false;
+    error: OgygieError;
+};
+export declare function bindScreenBehavior(parse: ScreenParseResult, context: ScreenBindingContext): ScreenBindingOutcome;

package/dist/spec-sections.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @intent Reads the two parts of a spec the generator needs, and nothing
+ * else: the single fenced YAML block of the `# Génération` section (D18) and
+ * the behavior paragraphs of `# Comportements` (D20), re-joined when wrapped
+ * over several lines of the file. Top-level sections are split on `# ` lines
+ * OUTSIDE fenced blocks and after the frontmatter — a `#` inside a YAML or
+ * TypeScript fence is not a heading.
+ *
+ * Nothing is dropped in silence: a paragraph opening with the formula
+ * without its accents, or in the three-line QUAND format, is returned as a
+ * paragraph for the grammar to refuse — the gate says why, it never ignores.
+ */
+export interface SectionLine {
+    text: string;
+    /** 1-based line number in the spec file. */
+    line: number;
+}
+export interface SpecSection {
+    title: string;
+    headingLine: number;
+    lines: SectionLine[];
+}
+export declare function splitTopLevelSections(markdown: string): SpecSection[];
+export declare function findSection(markdown: string, title: string): SpecSection | undefined;
+export declare const GENERATION_SECTION_TITLE = "G\u00E9n\u00E9ration";
+export declare const BEHAVIORS_SECTION_TITLE = "Comportements";
+export type GenerationSectionLookup = {
+    kind: "absent";
+} | {
+    kind: "block";
+    yaml: string;
+    line: number;
+} | {
+    kind: "invalid";
+    cause: string;
+    details: Record<string, unknown>;
+};
+/** The ONE yaml block of `# Génération`, or why there is none to read. */
+export declare function extractGenerationSection(markdown: string): GenerationSectionLookup;
+export interface BehaviorParagraph {
+    /** The whole behavior, wrapped lines re-joined with single spaces. */
+    raw: string;
+    /** 1-based line where it starts in the spec file. */
+    line: number;
+}
+/**
+ * Every paragraph of `# Comportements` that opens with (something like) the
+ * formula. A paragraph starts at a line opening with it — bulleted or not —
+ * and runs until a blank line, a heading, a fence or the next opening.
+ */
+export declare function extractBehaviorParagraphs(markdown: string): BehaviorParagraph[];

package/dist/verify-generation.d.ts

@@ -0,0 +1,93 @@
+import { type OgygieError } from "@ogygie/core/errors";
+import type { RepoAdapter } from "@ogygie/core/repo-adapter";
+import { type ParsedBehavior } from "./behavior-grammar.js";
+import { checkSpec, type CheckTally } from "./check-spec.js";
+import type { HoleLibraryEntry } from "./hole-shape.js";
+import { type ManifestGeneration } from "./manifest-generation.schema.js";
+import { type DeclaredManifestEntry } from "./emit/manifest-entry.js";
+import type { SchemaModels } from "./zod-introspection.js";
+import type { ScreenBlock } from "./screen-block.schema.js";
+import type { ConsumedFeatureCheckInput } from "./screen-checks.js";
+import { type ParsedScreenBehavior } from "./screen-grammar.js";
+export declare const GENERATED_DRIFT = "OGYGIE_GENERATED_DRIFT";
+/** The version every emitted header carries — the package's own, so a bump of the lockstep is a drift every product regenerates (D27). */
+export declare const GENERATOR_VERSION: string;
+/**
+ * The repo has no formatter; this is the whole of « after the formatter »
+ * (D21, D27): line endings and trailing whitespace are not a drift, every
+ * other byte is.
+ */
+export declare function normalizeForComparison(text: string): string;
+/** The header every generated file carries on its LINE 1 (D21), with the generator version. */
+export declare const GENERATED_HEADER: RegExp;
+/** A feature of the map that owns a spec: where its code lives. */
+export interface SpecOwnerFolder {
+    specPath: string;
+    /** Folder of the feature, relative to the repo root. */
+    folder: string;
+    /** The map's entry for the feature — its two generated fields, as declared (B3); absent, they are not compared. */
+    declared?: DeclaredManifestEntry;
+    /** The app carrying the feature (D40): a screen lives under a front app and regenerates through the screen pipeline. */
+    appPath?: string;
+    appType?: "api" | "front" | "gateway";
+}
+/** A consumed feature as `verify` needs it to regenerate a screen: what `check` reads of it, its routes on the map included. */
+export type LoadedConsumedForVerify = ConsumedFeatureCheckInput;
+export interface VerifyGenerationInput {
+    repo: RepoAdapter;
+    /** SQL tenant column of the product (`tenancy.column`); required to regenerate a feature. */
+    tenantColumn?: string;
+    /** The holes library, for the neighbours section of every holes/<id>.gen.md. */
+    library?: readonly HoleLibraryEntry[];
+    /** Folder of the specs, as the manifest declares it (`conventions.specsFolder`). */
+    specsFolder: string;
+    /** Folders walked for generated files — the apps and packages the manifest declares. */
+    scanDirs: readonly string[];
+    /** The manifest's `generation` block, null when the product declares none. */
+    generation: ManifestGeneration | null;
+    /** Spec → feature folder, from the manifest; a generated spec without one cannot be checked against its module. */
+    features?: readonly SpecOwnerFolder[];
+    /** Loads and introspects a schemas module (path relative to the repo root); null when the file is absent. */
+    loadSchemaModels?: (modulePath: string) => Promise<SchemaModels | null>;
+    /** Path of the API app, relative to the repo root — where guard modules live. */
+    apiAppPath?: string;
+    /** D41: resolves the features a screen block consumes (their block, schemas and routes); absent, no screen is regenerated. */
+    loadConsumed?: (block: ScreenBlock) => Promise<ReadonlyMap<string, LoadedConsumedForVerify>>;
+}
+export interface VerifiedSpec {
+    specPath: string;
+    generated: boolean;
+    tally: CheckTally;
+}
+export interface GeneratedFileClaim {
+    path: string;
+    /** Version read on line 1, null for a `*.gen.*` file without the header there. */
+    generatorVersion: string | null;
+}
+export interface VerifyGenerationReport {
+    ok: boolean;
+    specs: VerifiedSpec[];
+    generatedFiles: GeneratedFileClaim[];
+    problems: OgygieError[];
+    /** What was examined, and what this version cannot see (D12). */
+    perimeter: {
+        specsFolder: string;
+        scanDirs: readonly string[];
+        outOfScope: readonly string[];
+    };
+}
+/** The folder of the generator's own golden files: regenerated and compared by the package's tests, never by verify (D33, M2). */
+export declare const GOLDEN_DIRECTORY = "__golden__";
+/** The behaviors `check` bound, in the shape the plan takes — unbound ones never reach here (check refused). */
+export declare function boundBehaviorsOf(behaviors: ReturnType<typeof checkSpec>["behaviors"]): Array<{
+    behavior: ParsedBehavior;
+    status: "derivable" | "hole";
+}>;
+/** The screen behaviors `check` bound, in the shape the screen plan takes (D20 for screens). */
+export declare function boundScreenBehaviorsOf(behaviors: ReturnType<typeof checkSpec>["behaviors"]): Array<{
+    behavior: ParsedScreenBehavior;
+    status: "derivable" | "hole";
+}>;
+/** `export function name` or `export const name` — what a declared export must look like in its module. */
+export declare function exportsName(source: string, name: string): boolean;
+export declare function verifyGeneration(input: VerifyGenerationInput): Promise<VerifyGenerationReport>;

package/dist/vocabulary.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @intent The vocabulary of ONE operation (DECISIONS.md D20, D28 to D31,
+ * D34): every case a behavior line may open with, every named value and
+ * phrase an expectation may use, and every error code the operation can
+ * answer with its status — assembled from the generic words of this package,
+ * the guard of the operation (manifest `generation.guards`: its valid case,
+ * its variants, one case per declared refusal with its status and code — the
+ * `perFeature` one at the operation's `guardDeniedCode`), the operation itself
+ * (its kind: a plain read's rows, a keyed write's unknown key, a slot's
+ * words, `respondsWith`, `range`, `orderBy`, `limit`), the motif it uses, the
+ * implicit `signedWrite`, and the holes it carries (a derive's « <field>
+ * dérivé », every refusal code). A line whose every word is in here is derived
+ * without a model; a word outside it needs a hole.
+ */
+import { type GuardRegistry } from "./manifest-generation.schema.js";
+import { type GenerationBlock, type HttpOperation } from "./generation-block.schema.js";
+/** The code the API answers when a request violates its input contract. */
+export declare const CONTRACT_VALIDATION_FAILED = "CONTRACT_VALIDATION_FAILED";
+export interface OperationVocabulary {
+    /** Normalized case keys: `with:<phrase>` / `without:<phrase>`. */
+    cases: ReadonlySet<string>;
+    namedValues: ReadonlySet<string>;
+    phrases: ReadonlySet<string>;
+    /** Error code → the status it comes back with. */
+    codes: ReadonlyMap<string, number>;
+    successStatus: number;
+}
+/** `entrée invalide` is a STRUCTURAL violation — a required field missing — never a near-miss. */
+export declare const GENERIC_CASES: readonly ["with:entrée valide", "with:entrée invalide"];
+export declare const GENERIC_PHRASES: readonly ["rien n'est écrit"];
+export declare function caseKey(polarity: "with" | "without", phrase: string): string;
+/** The code a guard refusal answers for this operation: the operation's `guardDeniedCode` on a `perFeature` refusal, the guard's otherwise (D34). */
+export declare function deniedCodeOf(operation: {
+    guardDeniedCode?: string | null | undefined;
+}, denial: {
+    code: string;
+    perFeature?: boolean | undefined;
+}): string;
+export declare function vocabularyOf(operation: HttpOperation, block: GenerationBlock, guards?: GuardRegistry, contractViolationCode?: string): OperationVocabulary;

package/dist/zod-introspection.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @intent Zod v4 introspection (DECISIONS.md D19): the generator derives
+ * columns, factories and output mappings from the schemas MODULE itself —
+ * never from a copy. It walks the public core definition of each schema
+ * (`schema._zod.def`, the `zod/v4/core` contract library authors build on)
+ * into a small, serializable FieldModel: what the STRUCTURE says (kind, format,
+ * enum values, optional/nullable, bounds) and whether the structure alone can
+ * populate a sample (`derivable`). A regex, a `refine`, a `transform` are not
+ * derivable: such a field carries its example in the schema
+ * (`.meta({ examples })`, D23), read here through the global registry and
+ * checked against the schema (`rejectedExamples`).
+ *
+ * Samples are deterministic by construction: first enum value, the declared
+ * example, dates and uuids of fixed shape — the same module always yields the
+ * same factories, which is what byte-identical regeneration rests on (D21).
+ */
+import * as core from "zod/v4/core";
+interface ModelBase {
+    optional: boolean;
+    nullable: boolean;
+    /** Declared through `.meta({ examples })`, first wins as THE sample. */
+    examples: unknown[];
+    /** Declared examples the schema itself rejects — a refusal of `check`. */
+    rejectedExamples: unknown[];
+    /** Can the structure alone yield a valid sample? */
+    derivable: boolean;
+}
+export type FieldModel = ModelBase & ({
+    kind: "string";
+    format: string | null;
+    pattern: string | null;
+    minLength: number | null;
+    maxLength: number | null;
+    /** `.refine()` and friends: constraints no structure describes. */
+    customChecks: number;
+} | {
+    kind: "number";
+    integer: boolean;
+    minimum: number | null;
+    maximum: number | null;
+    customChecks: number;
+} | {
+    kind: "boolean";
+} | {
+    kind: "enum";
+    values: Array<string | number>;
+} | {
+    kind: "literal";
+    value: unknown;
+} | {
+    kind: "array";
+    element: FieldModel;
+} | {
+    kind: "object";
+    fields: Record<string, FieldModel>;
+}
+/** `z.record(key, value)`: keys the key model admits, every value of one shape — a map, not a row (lot 4 M3). */
+ | {
+    kind: "record";
+    key: FieldModel;
+    value: FieldModel;
+}
+/** `z.union([...])` of anything but literals alone: the first option is the shape a sample takes (lot 4 M3). A union of literals is an enum. */
+ | {
+    kind: "union";
+    options: FieldModel[];
+}
+/** `z.tuple([...])`: a fixed list of positioned shapes (lot 4 M3). */
+ | {
+    kind: "tuple";
+    items: FieldModel[];
+} | {
+    kind: "unknown";
+    typeName: string;
+});
+export interface SchemaModel {
+    /** Export name in the module, e.g. `CreateRateInputSchema`. */
+    name: string;
+    model: FieldModel;
+}
+/** Every `*Schema` export of a module, by export name. */
+export type SchemaModels = Record<string, SchemaModel>;
+export declare function modelOf(schema: core.$ZodType): FieldModel;
+/** The `*Schema` exports of an imported module, modelled. Non-schema exports are ignored. */
+export declare function modelsOfModule(moduleExports: Record<string, unknown>): SchemaModels;
+export type SampleResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+    path: string[];
+};
+/**
+ * A VALID sample of the model, deterministic: the declared example wins,
+ * then the structure. Fails — never guesses — when neither can answer.
+ * `variant` picks another declared example or enum value when there is one
+ * (« d'une autre <k> »), falling back to the first.
+ */
+export declare function sampleOf(model: FieldModel, path?: string[], variant?: number): SampleResult;
+export type InvalidSampleResult = {
+    ok: true;
+    value: Record<string, unknown>;
+    removedField: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * A STRUCTURALLY invalid sample: the valid one without its first required
+ * field — never a near-miss (D23 amendment). Impossible for a schema with no
+ * required field, and said so.
+ */
+export declare function invalidSampleOf(model: FieldModel): InvalidSampleResult;
+/** Field names of an object model, in declaration order; empty for anything else. */
+export declare function fieldNamesOf(model: FieldModel): string[];
+/** Does `model` describe the same object shape as `resource` (same field names)? */
+export declare function hasSameFieldsAs(model: FieldModel, resource: FieldModel): boolean;
+export {};

package/holes-library/27560e1760bb184c.json

@@ -0,0 +1,28 @@
+{
+  "hole": "assertPublicationAfterEffective",
+  "signature": "export function assertPublicationAfterEffective(\n  input: Pick<CreateRateInput, \"effectiveDate\" | \"publicationDate\">,\n): HoleResult<void, \"RATE_PUBLICATION_DATE_BEFORE_EFFECTIVE\"> {",
+  "signatureHash": "27560e1760bb184c",
+  "shape": {
+    "kind": "validate",
+    "reads": [
+      "string:date",
+      "string:date"
+    ],
+    "columns": [],
+    "codeRole": "operation-refusal",
+    "returns": "void"
+  },
+  "shapeHash": "05fa33d36c5f6172",
+  "errorCode": "RATE_PUBLICATION_DATE_BEFORE_EFFECTIVE",
+  "bodyTemplate": "  // ISO dates compare lexicographically; publishing on the effective date itself is allowed.\n  if (input.{{read:1}} >= input.{{read:0}}) return accept(undefined);\n  return refuse(\n    \"{{code}}\",\n    `{{read:1}}=${input.{{read:1}}} is before {{read:0}}=${input.{{read:0}}}`,\n    \"Publish on or after the effective date.\",\n  );",
+  "provenance": [
+    {
+      "hole": "assertPublicationAfterEffective",
+      "repo": "julienTeam/Ogygie",
+      "feature": "publication-de-taux",
+      "path": "human",
+      "model": null,
+      "date": "2026-10-17"
+    }
+  ]
+}

package/holes-library/2c26136fc6bff99a.json

@@ -0,0 +1,30 @@
+{
+  "hole": "projectForCaller",
+  "signature": "export function projectForCaller(context: Pick<ProjectionContext, \"role\">, output: ListGradesOutput): ListGradesOutput {",
+  "signatureHash": "2c26136fc6bff99a",
+  "shape": {
+    "kind": "project",
+    "reads": [
+      "context"
+    ],
+    "columns": [
+      "grades[].holderCount",
+      "canManage"
+    ],
+    "codeRole": "none",
+    "returns": "output"
+  },
+  "shapeHash": "1a61c3f4a779177f",
+  "errorCode": "",
+  "bodyTemplate": "  const manages = context.role === \"owner\";\n  return {\n    ...output,\n    canManage: manages,\n    grades: output.grades.map((grade) => ({ ...grade, holderCount: manages ? grade.holderCount : null })),\n  };",
+  "provenance": [
+    {
+      "hole": "projectForCaller",
+      "repo": "julienTeam/Ogygie",
+      "feature": "referentiel-de-paliers",
+      "path": "human",
+      "model": null,
+      "date": "2026-10-17"
+    }
+  ]
+}

package/holes-library/43a27770407bb38a.json

@@ -0,0 +1,27 @@
+{
+  "hole": "deriveGradeCode",
+  "signature": "export function deriveGradeCode(\n  input: Pick<CreateGradeInput, \"label\">,\n): HoleResult<string, \"GRADE_LABEL_INVALID\"> {",
+  "signatureHash": "43a27770407bb38a",
+  "shape": {
+    "kind": "derive",
+    "reads": [
+      "string"
+    ],
+    "columns": [],
+    "codeRole": "operation-refusal",
+    "returns": "string:regex"
+  },
+  "shapeHash": "5a010bdc51bf4608",
+  "errorCode": "GRADE_LABEL_INVALID",
+  "bodyTemplate": "  const slug = input.{{read:0}}\n    .normalize(\"NFD\")\n    .replace(/[\\u0300-\\u036f]/gu, \"\")\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/gu, \"-\")\n    .replace(/^-+|-+$/gu, \"\")\n    .slice(0, 32)\n    .replace(/-+$/u, \"\");\n  if (slug === \"\") {\n    return refuse(\n      \"{{code}}\",\n      `{{read:0}} ${JSON.stringify(input.{{read:0}})} has no letter nor digit to derive a code from`,\n      \"Give the grade a {{read:0}} with at least one letter or digit.\",\n    );\n  }\n  return accept(slug);",
+  "provenance": [
+    {
+      "hole": "deriveGradeCode",
+      "repo": "julienTeam/Ogygie",
+      "feature": "referentiel-de-paliers",
+      "path": "human",
+      "model": null,
+      "date": "2026-10-17"
+    }
+  ]
+}