open-agreements 0.7.4 → 0.7.6

package/dist/core/metadata.d.ts

@@ -1,27 +1,82 @@
 import { z } from 'zod';
+/**
+ * License values accepted by template metadata.
+ *
+ * CC-BY-4.0 and CC0-1.0 templates may be redistributed as OpenAgreements
+ * content. CC-BY-ND-4.0 templates are vendored only when unmodified and must
+ * declare `allow_derivatives: false`.
+ */
 export declare const LicenseEnum: z.ZodEnum<{
     "CC-BY-4.0": "CC-BY-4.0";
     "CC0-1.0": "CC0-1.0";
     "CC-BY-ND-4.0": "CC-BY-ND-4.0";
 }>;
 export type License = z.infer<typeof LicenseEnum>;
-export declare const FieldDefinitionSchema: z.ZodObject<{
-    name: z.ZodString;
-    type: z.ZodEnum<{
-        string: "string";
-        number: "number";
-        boolean: "boolean";
-        date: "date";
-        enum: "enum";
-        array: "array";
-    }>;
-    description: z.ZodString;
-    default: z.ZodOptional<z.ZodString>;
-    default_value_rationale: z.ZodOptional<z.ZodString>;
-    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    section: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type FieldDefinition = z.infer<typeof FieldDefinitionSchema>;
+/** Field kinds supported by template, external-template, and recipe metadata. */
+declare const FieldTypeEnum: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    date: "date";
+    enum: "enum";
+    array: "array";
+    multiselect: "multiselect";
+}>;
+export type FieldType = z.infer<typeof FieldTypeEnum>;
+/**
+ * Metadata definition for a fillable field.
+ *
+ * `name`, `type`, and `description` are required. `enum` and `multiselect`
+ * fields must declare non-empty `options`; `array` fields may declare nested
+ * `items`; `display_label` is a presentation hint and never replaces `name`.
+ */
+export interface FieldDefinition {
+    name: string;
+    type: FieldType;
+    description: string;
+    display_label?: string;
+    default?: string;
+    default_value_rationale?: string;
+    options?: string[];
+    derive_booleans?: boolean;
+    section?: string;
+    items?: FieldDefinition[];
+    /**
+     * Marks this boolean field as a *statutory compliance representation*: its
+     * `true` value asserts a past real-world fact that is a statutory precondition
+     * to the agreement's enforceability/validity (e.g. a required advance notice
+     * or written advisal that must actually have been given before signing).
+     *
+     * Deliberately NARROW — opt-in per field and reserved for the few reps that
+     * gate enforceability, NOT general representations (a purchase agreement may
+     * carry dozens of ordinary reps that should not all demand per-rep
+     * confirmation). When set, the field MUST be boolean with `default: 'false'`
+     * and MUST declare `authority_url`. A template clause references it via the
+     * renderer's `confirm=` directive, which renders the recital clean when the
+     * field is true and as a highlighted `[CONFIRM …]` bracket when it is false
+     * (never silently dropped). The broad confirmation warning rides in
+     * `description`; the short reason shown inside the rendered bracket rides in
+     * `confirm_note`.
+     */
+    statutory_compliance_representation?: boolean;
+    /**
+     * Statute / practice-note link used as the learn-more reference for a
+     * `statutory_compliance_representation` field (surfaced in the field
+     * description and the rendered `[CONFIRM …; see <authority_url>]` bracket).
+     * Only valid on a `statutory_compliance_representation` field.
+     */
+    authority_url?: string;
+    /**
+     * Short, human-readable reason rendered inside the
+     * `[CONFIRM before signing: <confirm_note>; see <authority_url>]` bracket of a
+     * `statutory_compliance_representation` field. This is the single source of
+     * truth for the bracket note — a `confirm=<field>` clause directive resolves
+     * it from here rather than restating it. Only valid on (and required for) a
+     * `statutory_compliance_representation` field.
+     */
+    confirm_note?: string;
+}
+export declare const FieldDefinitionSchema: z.ZodType<FieldDefinition>;
 export declare const TemplateMetadataSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -35,25 +90,28 @@ export declare const TemplateMetadataSchema: z.ZodObject<{
     }>;
     allow_derivatives: z.ZodBoolean;
     attribution_text: z.ZodString;
-    fields: z.ZodArray<z.ZodObject<{
+    fields: z.ZodArray<z.ZodType<FieldDefinition, unknown, z.core.$ZodTypeInternals<FieldDefinition, unknown>>>;
+    priority_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    credits: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            date: "date";
-            enum: "enum";
-            array: "array";
+        role: z.ZodEnum<{
+            drafter: "drafter";
+            drafting_editor: "drafting_editor";
+            reviewer: "reviewer";
+            maintainer: "maintainer";
         }>;
-        description: z.ZodString;
-        default: z.ZodOptional<z.ZodString>;
-        default_value_rationale: z.ZodOptional<z.ZodString>;
-        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        section: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    priority_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        profile_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    derived_from: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type TemplateMetadata = z.infer<typeof TemplateMetadataSchema>;
+/**
+ * Metadata for vendored external templates.
+ *
+ * `source_sha256` records the checksum of the unmodified upstream document so
+ * validation can verify provenance for no-derivatives templates before local
+ * transient fills or CI license checks rely on that source.
+ */
 export declare const ExternalMetadataSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -67,26 +125,23 @@ export declare const ExternalMetadataSchema: z.ZodObject<{
     }>;
     allow_derivatives: z.ZodBoolean;
     attribution_text: z.ZodString;
-    fields: z.ZodArray<z.ZodObject<{
+    fields: z.ZodArray<z.ZodType<FieldDefinition, unknown, z.core.$ZodTypeInternals<FieldDefinition, unknown>>>;
+    priority_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    credits: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            date: "date";
-            enum: "enum";
-            array: "array";
+        role: z.ZodEnum<{
+            drafter: "drafter";
+            drafting_editor: "drafting_editor";
+            reviewer: "reviewer";
+            maintainer: "maintainer";
         }>;
-        description: z.ZodString;
-        default: z.ZodOptional<z.ZodString>;
-        default_value_rationale: z.ZodOptional<z.ZodString>;
-        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        section: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    priority_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        profile_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    derived_from: z.ZodOptional<z.ZodString>;
     source_sha256: z.ZodString;
 }, z.core.$strip>;
 export type ExternalMetadata = z.infer<typeof ExternalMetadataSchema>;
+/** Declarative cleaner configuration for recipe DOCX preprocessing. */
 export declare const CleanConfigSchema: z.ZodObject<{
     removeFootnotes: z.ZodDefault<z.ZodBoolean>;
     removeBeforePattern: z.ZodOptional<z.ZodString>;
@@ -126,8 +181,8 @@ export declare const NormalizeConfigSchema: z.ZodObject<{
 export type NormalizeConfig = z.infer<typeof NormalizeConfigSchema>;
 export declare const GuidanceEntrySchema: z.ZodObject<{
     source: z.ZodEnum<{
-        footnote: "footnote";
         pattern: "pattern";
+        footnote: "footnote";
         range: "range";
     }>;
     part: z.ZodString;
@@ -136,6 +191,7 @@ export declare const GuidanceEntrySchema: z.ZodObject<{
     groupId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type GuidanceEntry = z.infer<typeof GuidanceEntrySchema>;
+/** Machine-readable guidance artifact produced from recipe cleaning inputs. */
 export declare const GuidanceOutputSchema: z.ZodObject<{
     extractedFrom: z.ZodObject<{
         sourceHash: z.ZodString;
@@ -143,8 +199,8 @@ export declare const GuidanceOutputSchema: z.ZodObject<{
     }, z.core.$strip>;
     entries: z.ZodArray<z.ZodObject<{
         source: z.ZodEnum<{
-            footnote: "footnote";
             pattern: "pattern";
+            footnote: "footnote";
             range: "range";
         }>;
         part: z.ZodString;
@@ -154,30 +210,27 @@ export declare const GuidanceOutputSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GuidanceOutput = z.infer<typeof GuidanceOutputSchema>;
+/**
+ * Metadata required for recipe-based templates.
+ *
+ * Recipes point at non-redistributable upstream source DOCX files and ship only
+ * transformation instructions. Required fields are `name`, `source_url`,
+ * `source_version`, and `license_note`; `fields` and `priority_fields` reuse
+ * the same field-definition semantics as template metadata and default to
+ * empty arrays. `optional` defaults to `false`. `source_sha256` verifies
+ * provenance for upstream sources when present. `market_data_citations`
+ * records optional external citation metadata used by recipe guidance.
+ */
 export declare const RecipeMetadataSchema: z.ZodObject<{
     name: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     source_url: z.ZodString;
     source_version: z.ZodString;
     license_note: z.ZodString;
     optional: z.ZodDefault<z.ZodBoolean>;
     source_sha256: z.ZodOptional<z.ZodString>;
-    fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            date: "date";
-            enum: "enum";
-            array: "array";
-        }>;
-        description: z.ZodString;
-        default: z.ZodOptional<z.ZodString>;
-        default_value_rationale: z.ZodOptional<z.ZodString>;
-        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        section: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodType<FieldDefinition, unknown, z.core.$ZodTypeInternals<FieldDefinition, unknown>>>>;
     priority_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
     market_data_citations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -203,4 +256,5 @@ export declare function validateRecipeMetadata(recipeDir: string): {
     valid: boolean;
     errors: string[];
 };
+export {};
 //# sourceMappingURL=metadata.d.ts.map

package/dist/core/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,WAAW;;;;EAAmD,CAAC;AAC5E,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAElD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;iBAmBjC,CAAC;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AA2CpE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAIjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,eAAO,MAAM,iBAAiB;;;;;;;;;iBAS5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,uCAAuC;;;;;;;;;;iBAUlD,CAAC;AACH,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC;AAExG,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAEhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAM9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;iBAM/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAQlE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAa/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAKlE;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAe1F;AAID,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAK1E;AAED,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAelG;AAID,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAKpE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAO9D;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CAOtE;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAe9F"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;EAAmD,CAAC;AAC5E,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAElD,iFAAiF;AACjF,QAAA,MAAM,aAAa;;;;;;;;EAAkF,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAGtD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,eAAe,EAAE,CAAC;IAC1B;;;;;;;;;;;;;;;;OAgBG;IACH,mCAAmC,CAAC,EAAE,OAAO,CAAC;IAC9C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAoM5D,CAAC;AAyGF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,uEAAuE;AACvE,eAAO,MAAM,iBAAiB;;;;;;;;;iBAS5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,uCAAuC;;;;;;;;;;iBAUlD,CAAC;AACH,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC;AAExG,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAEhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAM9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;iBAM/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAQlE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;iBAe/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAKlE;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAe1F;AAID,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAK1E;AAED,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAelG;AAID,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAKpE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAO9D;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CAOtE;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAe9F"}

package/dist/core/metadata.js

@@ -2,24 +2,215 @@ import { z } from 'zod';
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import yaml from 'js-yaml';
+/**
+ * License values accepted by template metadata.
+ *
+ * CC-BY-4.0 and CC0-1.0 templates may be redistributed as OpenAgreements
+ * content. CC-BY-ND-4.0 templates are vendored only when unmodified and must
+ * declare `allow_derivatives: false`.
+ */
 export const LicenseEnum = z.enum(['CC-BY-4.0', 'CC0-1.0', 'CC-BY-ND-4.0']);
-export const FieldDefinitionSchema = z.object({
+/** Field kinds supported by template, external-template, and recipe metadata. */
+const FieldTypeEnum = z.enum(['string', 'date', 'number', 'boolean', 'enum', 'array', 'multiselect']);
+const MULTISELECT_OPTION_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const FieldDefinitionSchema = z.lazy(() => z.object({
     name: z.string(),
-    type: z.enum(['string', 'date', 'number', 'boolean', 'enum', 'array']),
+    type: FieldTypeEnum,
     description: z.string(),
+    display_label: z.string().optional(),
     default: z.string().optional(),
     default_value_rationale: z.string().optional(),
     options: z.array(z.string()).optional(),
+    derive_booleans: z.boolean().optional(),
     section: z.string().optional(),
-}).refine((f) => f.type !== 'enum' || (f.options !== undefined && f.options.length > 0), { message: 'Fields with type "enum" must have a non-empty options array' }).refine((f) => {
-    if (f.default === undefined)
-        return true;
-    if (f.type === 'number')
-        return !isNaN(Number(f.default));
-    if (f.type === 'boolean')
-        return f.default === 'true' || f.default === 'false';
-    return true;
-}, { message: 'Default value must be valid for the declared field type' });
+    items: z.array(FieldDefinitionSchema).nonempty().optional(),
+    statutory_compliance_representation: z.boolean().optional(),
+    authority_url: z.string().optional(),
+    confirm_note: z.string().optional(),
+}).superRefine((field, ctx) => {
+    if ((field.type === 'enum' || field.type === 'multiselect') &&
+        (field.options === undefined || field.options.length === 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['options'],
+            message: `Fields with type "${field.type}" must have a non-empty options array`,
+        });
+    }
+    if (field.type === 'multiselect' && field.options) {
+        const seenOptions = new Set();
+        field.options.forEach((option, index) => {
+            if (!MULTISELECT_OPTION_RE.test(option)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['options', index],
+                    message: 'Multiselect options must be valid identifiers matching /^[A-Za-z_][A-Za-z0-9_]*$/',
+                });
+            }
+            if (seenOptions.has(option)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['options', index],
+                    message: `Duplicate multiselect option "${option}"`,
+                });
+                return;
+            }
+            seenOptions.add(option);
+        });
+    }
+    if (field.derive_booleans !== undefined && field.type !== 'multiselect') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['derive_booleans'],
+            message: 'derive_booleans is only valid for fields with type "multiselect"',
+        });
+    }
+    if (field.items !== undefined && field.type !== 'array') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['items'],
+            message: 'Only fields with type "array" may define nested items',
+        });
+    }
+    // `statutory_compliance_representation` is a NARROW opt-in category for the
+    // few boolean reps whose truth is a statutory precondition to
+    // enforceability. Enforce its shape so the renderer's `confirm=` mechanism
+    // and the get_template confirmation surface stay sound.
+    if (field.statutory_compliance_representation === true) {
+        if (field.type !== 'boolean') {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['statutory_compliance_representation'],
+                message: 'statutory_compliance_representation is only valid on a boolean field',
+            });
+        }
+        if (field.default !== 'false') {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['default'],
+                message: "statutory_compliance_representation fields must declare default: 'false' (a compliance fact is unconfirmed until a human confirms it)",
+            });
+        }
+        if (field.authority_url === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authority_url'],
+                message: 'statutory_compliance_representation fields must declare an authority_url (statute / practice-note link)',
+            });
+        }
+        else if (!/^https?:\/\/\S+$/.test(field.authority_url)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authority_url'],
+                message: 'authority_url must be an http(s) URL',
+            });
+        }
+        // confirm_note is the SSOT for the rendered `[CONFIRM …]` bracket note, so
+        // it must be present and non-empty (after trimming) on these fields.
+        if (field.confirm_note === undefined || field.confirm_note.trim().length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['confirm_note'],
+                message: 'statutory_compliance_representation fields must declare a non-empty confirm_note (the short reason shown in the rendered [CONFIRM …] bracket)',
+            });
+        }
+    }
+    else {
+        // Keep these properties scoped: they have no meaning outside the
+        // statutory_compliance_representation category.
+        if (field.authority_url !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authority_url'],
+                message: 'authority_url is only valid on a statutory_compliance_representation field',
+            });
+        }
+        if (field.confirm_note !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['confirm_note'],
+                message: 'confirm_note is only valid on a statutory_compliance_representation field',
+            });
+        }
+    }
+    if (field.default !== undefined) {
+        if (field.type === 'number' && isNaN(Number(field.default))) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['default'],
+                message: 'Default value must be valid for the declared field type',
+            });
+        }
+        if (field.type === 'boolean' && field.default !== 'true' && field.default !== 'false') {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['default'],
+                message: 'Default value must be valid for the declared field type',
+            });
+        }
+        if (field.type === 'multiselect') {
+            let parsedDefault;
+            try {
+                parsedDefault = JSON.parse(field.default);
+            }
+            catch {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['default'],
+                    message: 'Default value must be a JSON-encoded array of strings for multiselect fields',
+                });
+                return;
+            }
+            if (!Array.isArray(parsedDefault)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['default'],
+                    message: 'Default value must be a JSON-encoded array of strings for multiselect fields',
+                });
+                return;
+            }
+            const seenDefaults = new Set();
+            parsedDefault.forEach((entry) => {
+                if (typeof entry !== 'string') {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['default'],
+                        message: 'Default value must be a JSON-encoded array of strings for multiselect fields',
+                    });
+                    return;
+                }
+                if (seenDefaults.has(entry)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['default'],
+                        message: `Default value contains duplicate multiselect option "${entry}"`,
+                    });
+                    return;
+                }
+                seenDefaults.add(entry);
+                if (field.options && !field.options.includes(entry)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['default'],
+                        message: `Default value references option "${entry}" which is not declared in options`,
+                    });
+                }
+            });
+        }
+    }
+}));
+/** Closed set of provenance roles accepted in template `credits` entries. */
+const TemplateCreditRoleEnum = z.enum([
+    'drafter',
+    'drafting_editor',
+    'reviewer',
+    'maintainer',
+]);
+/** Optional template provenance entry surfaced by CLI discovery output. */
+const TemplateCreditSchema = z.object({
+    name: z.string(),
+    role: TemplateCreditRoleEnum,
+    profile_url: z.string().url().optional(),
+});
 function validatePriorityFields(fields, priorityFields, ctx) {
     const fieldNames = new Set(fields.map((field) => field.name));
     const seen = new Set();
@@ -42,8 +233,47 @@ function validatePriorityFields(fields, priorityFields, ctx) {
         }
     });
 }
+function validateDerivedBooleanCollisions(fields, ctx) {
+    const topLevelFieldNames = new Set(fields.map((field) => field.name));
+    const derivedKeyOwners = new Map();
+    fields.forEach((field, fieldIndex) => {
+        if (field.type !== 'multiselect' || field.derive_booleans !== true || !field.options) {
+            return;
+        }
+        field.options.forEach((option, optionIndex) => {
+            const derivedKey = `${option}_enabled`;
+            if (topLevelFieldNames.has(derivedKey)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['fields', fieldIndex, 'options', optionIndex],
+                    message: `Derived boolean key "${derivedKey}" from multiselect "${field.name}" collides with another top-level field name`,
+                });
+            }
+            const existingOwner = derivedKeyOwners.get(derivedKey);
+            if (existingOwner) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['fields', fieldIndex, 'options', optionIndex],
+                    message: `Derived boolean key "${derivedKey}" from multiselect "${field.name}" collides with derived key from multiselect "${existingOwner}"`,
+                });
+                return;
+            }
+            derivedKeyOwners.set(derivedKey, field.name);
+        });
+    });
+}
+/**
+ * Base metadata required for first-party and external templates.
+ *
+ * Template directories must provide `metadata.yaml` with a non-empty display
+ * name, source URL, version, license, derivative flag, attribution text, and
+ * field definitions. `category` is optional discovery grouping metadata.
+ * `priority_fields` reference required fill fields. `credits` records
+ * contributor provenance and defaults to an empty array; `derived_from` is
+ * expository provenance text and does not affect licensing.
+ */
 const TemplateMetadataBaseSchema = z.object({
-    name: z.string(),
+    name: z.string().trim().min(1, 'name must be a non-empty string (used as display_name on list_templates)'),
     description: z.string().optional(),
     category: z.string().optional(),
     source_url: z.string().url(),
@@ -53,17 +283,29 @@ const TemplateMetadataBaseSchema = z.object({
     attribution_text: z.string(),
     fields: z.array(FieldDefinitionSchema),
     priority_fields: z.array(z.string()).default([]),
+    credits: z.array(TemplateCreditSchema).default([]),
+    derived_from: z.string().optional(),
 });
 export const TemplateMetadataSchema = TemplateMetadataBaseSchema.superRefine((meta, ctx) => {
     validatePriorityFields(meta.fields, meta.priority_fields, ctx);
+    validateDerivedBooleanCollisions(meta.fields, ctx);
 });
 // --- External template schemas ---
+/**
+ * Metadata for vendored external templates.
+ *
+ * `source_sha256` records the checksum of the unmodified upstream document so
+ * validation can verify provenance for no-derivatives templates before local
+ * transient fills or CI license checks rely on that source.
+ */
 export const ExternalMetadataSchema = TemplateMetadataBaseSchema.extend({
     source_sha256: z.string(),
 }).superRefine((meta, ctx) => {
     validatePriorityFields(meta.fields, meta.priority_fields, ctx);
+    validateDerivedBooleanCollisions(meta.fields, ctx);
 });
 // --- Recipe schemas ---
+/** Declarative cleaner configuration for recipe DOCX preprocessing. */
 export const CleanConfigSchema = z.object({
     removeFootnotes: z.boolean().default(false),
     removeBeforePattern: z.string().optional(),
@@ -95,6 +337,7 @@ export const GuidanceEntrySchema = z.object({
     text: z.string(),
     groupId: z.string().optional(),
 });
+/** Machine-readable guidance artifact produced from recipe cleaning inputs. */
 export const GuidanceOutputSchema = z.object({
     extractedFrom: z.object({
         sourceHash: z.string(),
@@ -107,8 +350,20 @@ const MarketDataCitationSchema = z.object({
     label: z.string(),
     url: z.string().optional(),
 });
+/**
+ * Metadata required for recipe-based templates.
+ *
+ * Recipes point at non-redistributable upstream source DOCX files and ship only
+ * transformation instructions. Required fields are `name`, `source_url`,
+ * `source_version`, and `license_note`; `fields` and `priority_fields` reuse
+ * the same field-definition semantics as template metadata and default to
+ * empty arrays. `optional` defaults to `false`. `source_sha256` verifies
+ * provenance for upstream sources when present. `market_data_citations`
+ * records optional external citation metadata used by recipe guidance.
+ */
 export const RecipeMetadataSchema = z.object({
-    name: z.string(),
+    name: z.string().trim().min(1, 'name must be a non-empty string (used as display_name on list_templates)'),
+    category: z.string().optional(),
     description: z.string().optional(),
     source_url: z.string().url(),
     source_version: z.string(),
@@ -120,6 +375,7 @@ export const RecipeMetadataSchema = z.object({
     market_data_citations: z.array(MarketDataCitationSchema).optional(),
 }).superRefine((meta, ctx) => {
     validatePriorityFields(meta.fields, meta.priority_fields, ctx);
+    validateDerivedBooleanCollisions(meta.fields, ctx);
 });
 // --- Template loaders ---
 export function loadMetadata(templateDir) {