@hyperscale0/udl 1.0.0-beta.1 → 1.0.0

package/dist/schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { udlCheckEvidenceProfiles } from "./check-profiles.js";
 export const UDL_FORMAT_VERSION = 1;
 const snakeCasePattern = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
 const camelCasePattern = /^[a-z][A-Za-z0-9]*$/;
@@ -8,18 +9,26 @@ const eventNamePattern = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/;
 const udlSnakeCaseSchema = z
     .string()
     .regex(snakeCasePattern, "must be a snake_case identifier");
-const udlVerbNameSchema = z
+const udlActionNameSchema = z
     .string()
-    .regex(snakeCasePattern, "must be a snake_case verb identifier");
+    .regex(snakeCasePattern, "must be a snake_case action identifier");
 const udlFieldNameSchema = z
     .string()
     .regex(camelCasePattern, "must be a camelCase field name");
-export const udlPublicIntentSchema = z
+export const udlPublicActionSchema = z
     .string()
-    .regex(camelCasePattern, "must be a camelCase public intent name");
+    .regex(camelCasePattern, "must be a camelCase public action name");
+export const udlInstrumentActionIdSchema = z
+    .string()
+    .max(160)
+    .regex(/^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/, "must name an instrument action as instrument_id.action_key");
 const nonEmptyTextSchema = z
     .string()
     .refine((value) => value.trim().length > 0, "must not be blank");
+// Agent-facing presentation prose. Every MCP tool description an agent reads is
+// this string, so it is capped: a 400-character ceiling keeps a 60-tool surface
+// under the token budget a client spends before it can pick a tool.
+const udlAgentDescriptionSchema = nonEmptyTextSchema.max(400);
 const fieldPathSchema = z
     .string()
     .regex(fieldPathPattern, "must be a dot-separated camelCase field path");
@@ -28,6 +37,25 @@ const instanceValuePathSchema = z
     .regex(/^(?:fields|refs)\.[a-z][A-Za-z0-9]*$/, "must name one declared fields.* or refs.* value");
 const jsonObjectSchema = z.record(z.string(), z.json());
 const stringMapSchema = z.record(nonEmptyTextSchema, nonEmptyTextSchema);
+const providerFamilyIds = [
+    "accounts_ledger_first_party",
+    "identity_verification",
+    "national_identity",
+    "credit_bureau",
+    "sanctions_screening",
+    "enforcement_instrument",
+    "credit_servicing",
+    "collections_agency",
+    "settlement_ingestion",
+    "payouts",
+    "banking_or_card_issuing",
+    "insurance_carrier",
+    "insurance_claims_adjuster",
+    "air_carrier",
+    "lodging_supplier",
+    "email_or_notification",
+];
+export const udlProviderFamilyIdSchema = z.enum(providerFamilyIds);
 const udlDeclaredValuePolicySchema = z.enum(["required", "optional", "none"]);
 const udlSubjectSchema = z.strictObject({
     declaredValue: udlDeclaredValuePolicySchema,
@@ -36,9 +64,15 @@ const udlSubjectSchema = z.strictObject({
     title: nonEmptyTextSchema,
     version: z.number().int().positive(),
 });
-const udlNounSubjectSchema = z.strictObject({
+const udlInstrumentSubjectSchema = z.strictObject({
+    extensible: z.boolean().optional(),
     kinds: z.array(udlSnakeCaseSchema).min(1),
 });
+const udlExampleSchema = z.strictObject({
+    input: jsonObjectSchema,
+    name: nonEmptyTextSchema,
+    output: z.json().optional(),
+});
 const udlLifecycleTransitionSchema = z.strictObject({
     from: z.array(udlSnakeCaseSchema).min(1),
     to: udlSnakeCaseSchema,
@@ -46,14 +80,15 @@ const udlLifecycleTransitionSchema = z.strictObject({
 const udlLifecycleSchema = z.strictObject({
     initial: udlSnakeCaseSchema,
     states: z.array(udlSnakeCaseSchema).min(1),
-    transitions: z.record(udlVerbNameSchema, udlLifecycleTransitionSchema),
+    transitions: z.record(udlActionNameSchema, udlLifecycleTransitionSchema),
 });
 const udlUpdatePolicySchema = z.strictObject({
+    examples: z.array(udlExampleSchema).optional(),
     fields: z.array(udlFieldNameSchema).min(1),
     states: z.array(udlSnakeCaseSchema).min(1),
 });
 const udlGateSchema = z.strictObject({
-    /** Local field key <- referenced instance path; create verbs only. */
+    /** Local field key <- referenced instance path; create actions only. */
     bind: z.record(udlFieldNameSchema, fieldPathSchema).optional(),
     field: udlFieldNameSchema,
     /** Local instance path === referenced instance path at admission. */
@@ -61,7 +96,7 @@ const udlGateSchema = z.strictObject({
     /** Opt-in over an optional reference field: absent passes, set is held to the clause. */
     optional: z.literal(true).optional(),
     statuses: z.array(udlSnakeCaseSchema).min(1),
-    /** One dependent ever per referenced instance; create verbs only. */
+    /** One dependent ever per referenced instance; create actions only. */
     unique: z.literal(true).optional(),
 });
 const udlBindingSchema = z.discriminatedUnion("from", [
@@ -97,17 +132,22 @@ const udlMoveSchema = z.strictObject({
 });
 const udlDueRecurrenceSchema = z.strictObject({
     countField: udlFieldNameSchema.optional(),
+    delinquency: z.literal("parent_policy").optional(),
+    drainAction: udlActionNameSchema.optional(),
     period: z.union([
         nonEmptyTextSchema,
         z.strictObject({
             calendar: z.enum(["gregorian", "hijri"]),
+            monthEnd: z.literal("clamp_to_last_day"),
             months: z.number().int().positive(),
         }),
     ]),
+    liability: z.literal("one_open").optional(),
+    untilAction: udlActionNameSchema.optional(),
     untilField: udlFieldNameSchema.optional(),
 });
 const udlDueParentStatusSchema = z.strictObject({
-    nounId: udlSnakeCaseSchema,
+    instrumentId: udlSnakeCaseSchema,
     refField: udlFieldNameSchema,
     statuses: z.array(udlSnakeCaseSchema).min(1),
 });
@@ -126,21 +166,62 @@ const udlSetsAtSchema = z.strictObject({
     marker: z.literal(true).optional(),
     offset: nonEmptyTextSchema,
 });
-const udlUnwindPenaltySchema = z.strictObject({
+const udlQuoteChargeSchema = z.strictObject({
     bps: z.number().int().min(0).max(9_999),
     withinOffset: nonEmptyTextSchema.optional(),
 });
-const udlUnwindSchema = z.strictObject({
-    beforeField: udlFieldNameSchema.optional(),
-    confirm: udlVerbNameSchema,
-    penalty: z.array(udlUnwindPenaltySchema).min(1),
-    quote: udlVerbNameSchema,
-    refundableField: udlFieldNameSchema,
-    refundDestinationField: udlFieldNameSchema,
-});
+// A priced, expiring offer. The quoting action splits `baseField` into a charge
+// and a net at its own clock, freezes the fields the price was read from, and
+// stamps an expiry. Only the paired `commit` action may spend the offer, and
+// only while it is unexpired and its frozen fields still hold.
+const udlQuoteShape = {
+    /** Date-time whose remaining time picks the charge tier; omit for elapsed age. */
+    anchorField: udlFieldNameSchema.optional(),
+    baseField: udlFieldNameSchema,
+    chargeRef: udlFieldNameSchema,
+    charges: z.array(udlQuoteChargeSchema).min(1),
+    /** Fixed ISO-8601 duration from the quoting action, or a stored deadline. */
+    expires: z.union([
+        z.strictObject({ field: udlFieldNameSchema }),
+        z.strictObject({ offset: nonEmptyTextSchema }),
+    ]),
+    fixes: z.array(udlFieldNameSchema).min(1),
+    netDestinationField: udlFieldNameSchema,
+    netRef: udlFieldNameSchema,
+};
+const udlQuoteSchema = z.strictObject(udlQuoteShape);
+/**
+ * Where a quoting action stamps the instant its offer stops being committable.
+ * Derived from the author's net ref rather than a fixed name, so two offers on
+ * one instrument never share the slot.
+ */
+export function quoteExpiresAtRefKey(quote) {
+    return `${quote.netRef}ExpiresAt`;
+}
+/**
+ * Where a quoting action stamps the fingerprint of the field values it froze.
+ * The committing action recomputes it against the live fields, which is how an
+ * offer priced on one set of terms refuses to pay out against another.
+ */
+export function quoteFrozenRefKey(quote) {
+    return `${quote.netRef}Frozen`;
+}
+/**
+ * Every ref key one quote seeds: the charge and the net the author named, plus
+ * the two the machinery derives to hold the offer itself. One derivation, read
+ * by the validator, the compiler, and the runtime alike.
+ */
+export function quoteSeededRefKeys(quote) {
+    return [
+        quote.chargeRef,
+        quote.netRef,
+        quoteExpiresAtRefKey(quote),
+        quoteFrozenRefKey(quote),
+    ];
+}
 const udlDecisionSchema = z.strictObject({
-    capability: udlSnakeCaseSchema,
-    deadlineMs: z.number().int().positive(),
+    capability: udlProviderFamilyIdSchema,
+    deadlineMs: z.number().int().positive().max(15_000),
     // A decision that never came back is not an approval. `approve` would let a
     // document release money because a counterparty went quiet, so the grammar
     // admits only the fail-closed answer. Every published document already
@@ -148,11 +229,6 @@ const udlDecisionSchema = z.strictObject({
     // be.
     onTimeout: z.literal("decline"),
 });
-const udlExampleSchema = z.strictObject({
-    input: jsonObjectSchema,
-    name: nonEmptyTextSchema,
-    output: z.json().optional(),
-});
 const udlAggregateCheckSchema = z.discriminatedUnion("kind", [
     z.strictObject({
         amountField: udlFieldNameSchema,
@@ -188,7 +264,7 @@ const udlAggregateCheckSchema = z.discriminatedUnion("kind", [
 ]);
 const udlAggregateConditionSchema = z.strictObject({
     check: udlAggregateCheckSchema,
-    nounId: udlSnakeCaseSchema.optional(),
+    instrumentId: udlSnakeCaseSchema.optional(),
     over: z.enum(["children", "siblings"]),
     refField: udlFieldNameSchema,
     statuses: z.array(udlSnakeCaseSchema).min(1),
@@ -198,11 +274,11 @@ const udlExposureRequirementSchema = z.strictObject({
     anchorField: udlFieldNameSchema,
     capField: udlFieldNameSchema,
     capOnAnchor: z.literal(true).optional(),
-    childNounId: udlSnakeCaseSchema,
+    childInstrumentId: udlSnakeCaseSchema,
     statuses: z.array(udlSnakeCaseSchema).min(1),
 });
-// The tenant-backend decision port: the verb's caller asserts the acting
-// party, checked at admission against the noun's party bindings for the
+// The tenant-backend decision port: the action's caller asserts the acting
+// party, checked at admission against the instrument's party bindings for the
 // allowed roles.
 const udlPortSchema = z.strictObject({
     allowedParties: z
@@ -218,13 +294,60 @@ const udlPayoutSchema = z.strictObject({
     sourceAccountField: udlFieldNameSchema,
     speed: z.literal("standard"),
 });
-const udlRequiresSettlementSchema = z.strictObject({
+/**
+ * One expectation an action asserts about money it cannot see yet: how much,
+ * in which currency, which way, and against whose provider-side row. Evidence
+ * that lands later either matches under the declared law or the expectation
+ * breaks: past the window the kernel raises the declared exception child, binds
+ * the unmatched amount and the break reason onto it, and spends the due
+ * occurrence. There is no third outcome and no silent wait.
+ */
+const udlReconcileSchema = z.strictObject({
+    /** `fields.<name>` or `refs.<name>`: the money this action says will land. */
+    amount: instanceValuePathSchema,
+    /** Where the matched evidence id lands in refs. */
     capture: udlFieldNameSchema,
-    payoutRef: udlFieldNameSchema,
+    /** The ref naming the provider-side row the evidence must cite. */
+    counterpartyRef: udlFieldNameSchema,
+    currencyField: udlFieldNameSchema,
+    direction: z.enum(["credit", "debit"]),
+    /** Exactly one source. A reconcile never reads two ledgers at once. */
+    evidence: z.enum(["movement", "provider_confirmation", "statement_line"]),
+    /**
+     * Where an expectation that never matched lands. The named child instrument
+     * carries the break, and `maxOpen` caps how many of them one instance may
+     * hold open at once, the same count measure the aggregate invariants use.
+     */
+    exception: z.strictObject({
+        amountField: udlFieldNameSchema,
+        childInstrumentId: udlSnakeCaseSchema,
+        maxOpen: z.number().int().min(1).max(1_000),
+        reasonField: udlFieldNameSchema,
+        refField: udlFieldNameSchema,
+    }),
+    /**
+     * How a candidate becomes the match. `exact` demands equal minor units,
+     * `tolerance` allows a bounded difference, `window` drops the amount test
+     * for a source that nets several items into one line.
+     */
+    match: z.discriminatedUnion("law", [
+        z.strictObject({ law: z.literal("exact") }),
+        z.strictObject({
+            dial: udlSnakeCaseSchema,
+            law: z.literal("tolerance"),
+            minorUnits: z.number().int().positive(),
+        }),
+        z.strictObject({ law: z.literal("window") }),
+    ]),
+    /** Fixed ISO-8601 duration from the expecting action, or a stored deadline. */
+    within: z.union([
+        z.strictObject({ field: udlFieldNameSchema }),
+        z.strictObject({ offset: nonEmptyTextSchema }),
+    ]),
 });
 const udlSignedSumSourceSchema = z.strictObject({
     amountField: udlFieldNameSchema,
-    nounId: udlSnakeCaseSchema,
+    instrumentId: udlSnakeCaseSchema,
     refField: udlFieldNameSchema,
     sign: z.enum(["add", "subtract"]),
     statuses: z.array(udlSnakeCaseSchema).min(1),
@@ -247,9 +370,78 @@ const udlDistributeSchema = z.strictObject({
     statuses: z.array(udlSnakeCaseSchema).min(1),
     weightField: udlFieldNameSchema,
 });
+const udlRemainderCollectedSchema = z.strictObject({
+    amountField: udlFieldNameSchema,
+    instrumentId: udlSnakeCaseSchema,
+    path: z.literal("refs").optional(),
+    refField: udlFieldNameSchema,
+    statuses: z.array(udlSnakeCaseSchema).min(1),
+});
+const udlRemainderSchema = z.strictObject({
+    accumulateRef: udlFieldNameSchema.optional(),
+    amountRef: udlFieldNameSchema,
+    collected: z.array(udlRemainderCollectedSchema).optional(),
+    inputKey: udlFieldNameSchema.optional(),
+    onZero: z.enum(["refuse", "skip_steps"]),
+    totalPath: instanceValuePathSchema,
+});
+const udlCheckRequirementVariants = udlCheckEvidenceProfiles.map((profile) => z.strictObject({
+    checkKind: z.literal(profile.checkKind),
+    family: z.literal(profile.family),
+    maxAge: nonEmptyTextSchema.optional(),
+    statuses: z.array(z.enum(profile.statuses)).min(1),
+    subjectField: udlFieldNameSchema,
+}));
+const udlCheckRequirementSchema = z.union(udlCheckRequirementVariants);
+const udlDialSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        field: udlFieldNameSchema,
+        key: udlSnakeCaseSchema,
+        kind: z.literal("window"),
+        maxOffset: nonEmptyTextSchema.optional(),
+        minOffset: nonEmptyTextSchema.optional(),
+        summary: nonEmptyTextSchema,
+        title: nonEmptyTextSchema,
+    }),
+    z.strictObject({
+        action: udlActionNameSchema,
+        key: udlSnakeCaseSchema,
+        kind: z.literal("decision_deadline_ms"),
+        maxMs: z.number().int().positive().max(15_000).optional(),
+        minMs: z.number().int().positive().max(15_000).optional(),
+        summary: nonEmptyTextSchema,
+        title: nonEmptyTextSchema,
+    }),
+    z.strictObject({
+        key: udlSnakeCaseSchema,
+        kind: z.literal("reconcile_tolerance"),
+        /** Ceiling on the minor units any reconcile may forgive under this dial. */
+        maxMinorUnits: z.number().int().positive().max(1_000_000),
+        summary: nonEmptyTextSchema,
+        title: nonEmptyTextSchema,
+    }),
+    z.strictObject({
+        key: udlSnakeCaseSchema,
+        kind: z.literal("unwind_penalty"),
+        summary: nonEmptyTextSchema,
+        title: nonEmptyTextSchema,
+    }),
+]);
 // A same-instance conservation law: the piece fields (money, minor units)
 // must sum exactly to the total field; admission refuses a create whose
 // pieces diverge.
+// A composition-level dial. Instrument dials tune one instrument's frozen slots;
+// this one is a property of the whole product, so it hangs off the document.
+// `confirmation_threshold` carries minor units of the kernel currency: a
+// money-moving tool call whose declared money inputs sum below the configured
+// value skips the explicit confirmation argument.
+const udlCompositionDialSchema = z.strictObject({
+    key: udlSnakeCaseSchema,
+    kind: z.literal("confirmation_threshold"),
+    maxMinor: z.number().int().positive().max(1_000_000_000_000).optional(),
+    summary: nonEmptyTextSchema,
+    title: nonEmptyTextSchema,
+});
 const udlPartitionSchema = z.strictObject({
     pieceFields: z.array(udlFieldNameSchema).min(2),
     totalField: udlFieldNameSchema,
@@ -263,35 +455,105 @@ const udlDerivedAmountSchema = z.strictObject({
     }),
     sourceField: udlFieldNameSchema,
 });
-const udlVerbSchema = z.strictObject({
+const udlFeeLeafRuleSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        bps: z.number().int().min(1).max(9_999),
+        kind: z.literal("bps"),
+    }),
+    z.strictObject({
+        currencyField: udlFieldNameSchema,
+        field: udlFieldNameSchema,
+        kind: z.literal("exact"),
+    }),
+]);
+const nonNegativeDecimalIntegerSchema = z
+    .string()
+    .regex(/^(0|[1-9][0-9]*)$/, "must be a nonnegative decimal integer");
+const udlFeeRuleSchema = z.strictObject({
+    amountField: udlFieldNameSchema,
+    baseField: udlFieldNameSchema,
+    bearerField: udlFieldNameSchema,
+    position: z.enum(["carved", "on_top"]),
+    rule: z.discriminatedUnion("kind", [
+        ...udlFeeLeafRuleSchema.options,
+        z.strictObject({
+            kind: z.literal("tiered"),
+            tiers: z
+                .array(z.strictObject({
+                fromInclusive: nonNegativeDecimalIntegerSchema,
+                rule: udlFeeLeafRuleSchema,
+                toExclusive: nonNegativeDecimalIntegerSchema.optional(),
+            }))
+                .min(1)
+                .max(16),
+        }),
+    ]),
+});
+const udlDecidedAmountSchema = z.strictObject({
+    boundField: udlFieldNameSchema,
+    field: udlFieldNameSchema,
+    remainderAction: udlActionNameSchema,
+});
+const udlEffectRowSchema = z.strictObject({
+    signature: nonEmptyTextSchema,
+    source: nonEmptyTextSchema,
+});
+const udlNotifyEffectSchema = z.strictObject({
+    channel: udlSnakeCaseSchema,
+    role: udlSnakeCaseSchema,
+    signature: nonEmptyTextSchema,
+    source: nonEmptyTextSchema,
+});
+const udlEffectsShape = {
+    decides: z.array(udlEffectRowSchema).min(1).optional(),
+    holds: z.array(udlEffectRowSchema).min(1).optional(),
+    moves: z.array(udlEffectRowSchema).min(1).optional(),
+    notifies: z.array(udlNotifyEffectSchema).min(1).optional(),
+    reads: z.array(udlEffectRowSchema).min(1).optional(),
+    schedules: z.array(udlEffectRowSchema).min(1).optional(),
+};
+const udlEffectsSchema = z.strictObject(udlEffectsShape);
+const udlActionShape = {
+    agentDescription: udlAgentDescriptionSchema.optional(),
     captureInput: z.record(udlFieldNameSchema, udlFieldNameSchema).optional(),
+    /** Names the quoting action whose offer this action spends. */
+    commit: udlActionNameSchema.optional(),
+    decidedAmount: udlDecidedAmountSchema.optional(),
     deadline: udlDeadlineSchema.optional(),
     decision: udlDecisionSchema.optional(),
     distribute: udlDistributeSchema.optional(),
     description: nonEmptyTextSchema.optional(),
     due: udlDueSchema.optional(),
     earnable: z.boolean().optional(),
+    effects: udlEffectsSchema.optional(),
     eventName: z.string().regex(eventNamePattern).optional(),
     examples: z.array(udlExampleSchema).min(1).optional(),
     input: jsonObjectSchema.optional(),
     moves: z.array(udlMoveSchema).default([]),
     payout: udlPayoutSchema.optional(),
     port: udlPortSchema.optional(),
-    publicIntent: udlPublicIntentSchema
+    quote: udlQuoteSchema.optional(),
+    publicAction: udlPublicActionSchema
         .optional()
-        .describe("Author-approved public intent name; the containing verb key remains the lifecycle and execution identity"),
+        .describe("Author-approved public action name; the containing action key remains the lifecycle and execution identity"),
+    principal: z.literal("user_session").optional(),
+    reconcile: z.array(udlReconcileSchema).min(1).optional(),
+    remainder: udlRemainderSchema.optional(),
     requiresAggregate: z.array(udlAggregateConditionSchema).min(1).optional(),
+    requiresChecks: z.array(udlCheckRequirementSchema).optional(),
     requiresDrainedAccount: z.strictObject({ path: fieldPathSchema }).optional(),
     requiresExposure: z.array(udlExposureRequirementSchema).min(1).optional(),
     requiresRefs: z.array(udlGateSchema).min(1).optional(),
-    requiresSettlement: udlRequiresSettlementSchema.optional(),
+    sandboxFailurePoint: z.enum(["funding", "release"]).optional(),
     setsAt: udlSetsAtSchema.optional(),
     signedSum: udlSignedSumSchema.optional(),
     steps: z.array(udlStepSchema),
     summary: nonEmptyTextSchema,
-});
+    updates: z.array(udlFieldNameSchema).min(1).optional(),
+};
+const udlActionSchema = z.strictObject(udlActionShape);
 const udlAggregateBaseShape = {
-    childNounId: udlSnakeCaseSchema,
+    childInstrumentId: udlSnakeCaseSchema,
     childRefField: udlFieldNameSchema,
     childStatuses: z.array(udlSnakeCaseSchema).min(1),
     parentField: udlFieldNameSchema,
@@ -315,18 +577,25 @@ const udlAggregateSchema = z.union([
             .optional(),
     }),
 ]);
-const udlNounSchema = z.strictObject({
+const udlInstrumentShape = {
+    actionOrder: z.array(udlActionNameSchema).min(1),
+    agentDescription: udlAgentDescriptionSchema.optional(),
     aggregateInvariants: z.array(udlAggregateSchema).min(1).optional(),
-    computedMoneyRefs: z.array(udlFieldNameSchema).min(1).optional(),
+    callerParkedStates: z
+        .record(udlSnakeCaseSchema, nonEmptyTextSchema)
+        .optional(),
     description: nonEmptyTextSchema.optional(),
+    dials: z.array(udlDialSchema).optional(),
     distinctParties: z.literal(true).optional(),
     derivedAmounts: z.array(udlDerivedAmountSchema).min(1).max(4).optional(),
+    feeRules: z.array(udlFeeRuleSchema).min(1).max(4).optional(),
     fields: z.record(udlFieldNameSchema, jsonObjectSchema),
     id: udlSnakeCaseSchema,
     idPrefix: z
         .string()
         .regex(idPrefixPattern, "must contain 2 to 8 lowercase letters"),
     lifecycle: udlLifecycleSchema,
+    nav: z.array(nonEmptyTextSchema).min(1).optional(),
     parties: z
         .strictObject({
         beneficiary: udlFieldNameSchema.optional(),
@@ -336,15 +605,425 @@ const udlNounSchema = z.strictObject({
         .optional(),
     partitions: z.array(udlPartitionSchema).min(1).optional(),
     required: z.array(udlFieldNameSchema),
-    subject: udlNounSubjectSchema.optional(),
+    subject: udlInstrumentSubjectSchema.optional(),
     summary: nonEmptyTextSchema,
+    surfaceVisibility: z.enum(["internal", "public", "system"]).optional(),
+    templateId: udlSnakeCaseSchema.optional(),
     title: nonEmptyTextSchema,
-    unwind: udlUnwindSchema.optional(),
     update: udlUpdatePolicySchema.optional(),
-    verbs: z.record(udlVerbNameSchema, udlVerbSchema),
-});
+    actions: z.record(udlActionNameSchema, udlActionSchema),
+};
+const udlInstrumentSchema = z.strictObject(udlInstrumentShape);
+export const udlClauseVocabulary = [
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "agent description",
+        target: "agentDescription",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "capture input",
+        target: "captureInput",
+    },
+    {
+        cardinality: "one",
+        // The committing action consumes the quote through its priced moves.
+        // An extra row here would bill the same movement twice.
+        effects: [],
+        scope: "action",
+        spelling: "commit",
+        target: "commit",
+    },
+    {
+        cardinality: "one",
+        effects: [
+            {
+                kind: "holds",
+                per: "clause",
+                signature: { fixed: "quote" },
+            },
+            {
+                kind: "schedules",
+                per: "clause",
+                signature: { fixed: "expiry" },
+            },
+        ],
+        linearOutputs: ["netRef"],
+        scope: "action",
+        spelling: "quote",
+        target: "quote",
+    },
+    {
+        cardinality: "one",
+        linearOutputs: ["field"],
+        scope: "action",
+        spelling: "decided amount",
+        target: "decidedAmount",
+    },
+    {
+        cardinality: "one",
+        effects: [
+            {
+                kind: "schedules",
+                per: "clause",
+                signature: { fixed: "deadline" },
+            },
+        ],
+        scope: "action",
+        spelling: "deadline",
+        target: "deadline",
+    },
+    {
+        cardinality: "one",
+        effects: [
+            {
+                kind: "decides",
+                per: "clause",
+                signature: { fromField: "capability" },
+            },
+        ],
+        scope: "action",
+        spelling: "decision",
+        target: "decision",
+    },
+    {
+        cardinality: "one",
+        linearOutputs: ["amountRef"],
+        scope: "action",
+        spelling: "computes distribute",
+        target: "distribute",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "description",
+        target: "description",
+    },
+    {
+        cardinality: "one",
+        effects: [
+            {
+                kind: "schedules",
+                per: "clause",
+                signature: { fixed: "due" },
+            },
+        ],
+        scope: "action",
+        spelling: "due",
+        target: "due",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "earnable",
+        target: "earnable",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "event name",
+        target: "eventName",
+    },
+    {
+        cardinality: "many",
+        scope: "action",
+        spelling: "examples",
+        target: "examples",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "input",
+        target: "input",
+    },
+    {
+        cardinality: "many",
+        effects: [
+            {
+                kind: "moves",
+                per: "element",
+                signature: { movementClass: true },
+            },
+            {
+                kind: "holds",
+                per: "element",
+                signature: { fixed: "reserve" },
+            },
+        ],
+        linearSink: true,
+        scope: "action",
+        spelling: "moves",
+        target: "moves",
+    },
+    {
+        cardinality: "one",
+        effects: [
+            {
+                kind: "moves",
+                per: "clause",
+                signature: { fixed: "payout.external" },
+            },
+        ],
+        linearSink: true,
+        scope: "action",
+        spelling: "payout",
+        target: "payout",
+    },
+    {
+        cardinality: "one",
+        effects: [
+            {
+                kind: "decides",
+                per: "clause",
+                signature: { fixed: "tenant_port" },
+            },
+        ],
+        scope: "action",
+        spelling: "port",
+        target: "port",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "principal",
+        target: "principal",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "public action",
+        target: "publicAction",
+    },
+    {
+        cardinality: "many",
+        effects: [
+            {
+                kind: "reads",
+                per: "element",
+                signature: { fixed: "reconcile" },
+            },
+        ],
+        scope: "action",
+        spelling: "reconcile",
+        target: "reconcile",
+    },
+    {
+        cardinality: "one",
+        linearOutputs: ["amountRef"],
+        scope: "action",
+        spelling: "computes remainder",
+        target: "remainder",
+    },
+    {
+        cardinality: "many",
+        effects: [
+            {
+                kind: "reads",
+                per: "clause",
+                signature: { fixed: "requires_aggregate" },
+            },
+        ],
+        scope: "action",
+        spelling: "requires aggregate",
+        target: "requiresAggregate",
+    },
+    {
+        cardinality: "many",
+        effects: [
+            {
+                kind: "reads",
+                per: "clause",
+                signature: { fixed: "requires_checks" },
+            },
+        ],
+        scope: "action",
+        spelling: "requires checks",
+        target: "requiresChecks",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "requires drained",
+        target: "requiresDrainedAccount",
+    },
+    {
+        cardinality: "many",
+        scope: "action",
+        spelling: "requires exposure",
+        target: "requiresExposure",
+    },
+    {
+        cardinality: "many",
+        effects: [
+            {
+                kind: "reads",
+                per: "clause",
+                signature: { fixed: "requires_refs" },
+            },
+        ],
+        scope: "action",
+        spelling: "requires refs",
+        target: "requiresRefs",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "sandbox failure point",
+        target: "sandboxFailurePoint",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "sets at",
+        target: "setsAt",
+    },
+    {
+        cardinality: "one",
+        linearOutputs: ["amountRef"],
+        scope: "action",
+        spelling: "computes signed_sum",
+        target: "signedSum",
+    },
+    {
+        cardinality: "many",
+        linearSink: true,
+        scope: "action",
+        spelling: "steps",
+        target: "steps",
+    },
+    {
+        cardinality: "one",
+        scope: "action",
+        spelling: "summary",
+        target: "summary",
+    },
+    {
+        cardinality: "many",
+        scope: "action",
+        spelling: "updates",
+        target: "updates",
+    },
+    {
+        cardinality: "many",
+        effects: [
+            {
+                kind: "notifies",
+                per: "element",
+                signature: { fromField: "channel" },
+            },
+        ],
+        scope: "action",
+        spelling: "notify",
+        target: "effects.notifies",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "agent description",
+        target: "agentDescription",
+    },
+    {
+        cardinality: "many",
+        scope: "instrument",
+        spelling: "aggregate invariants",
+        target: "aggregateInvariants",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "caller parked states",
+        target: "callerParkedStates",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "description",
+        target: "description",
+    },
+    {
+        cardinality: "many",
+        scope: "instrument",
+        spelling: "dials",
+        target: "dials",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "distinct parties",
+        target: "distinctParties",
+    },
+    {
+        cardinality: "many",
+        scope: "instrument",
+        spelling: "computes derived",
+        target: "derivedAmounts",
+    },
+    {
+        cardinality: "many",
+        scope: "instrument",
+        spelling: "computes fees",
+        target: "feeRules",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "id prefix",
+        target: "idPrefix",
+    },
+    {
+        cardinality: "many",
+        scope: "instrument",
+        spelling: "nav",
+        target: "nav",
+    },
+    {
+        cardinality: "many",
+        scope: "instrument",
+        spelling: "partitions",
+        target: "partitions",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "subject",
+        target: "subject",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "summary",
+        target: "summary",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "surface visibility",
+        target: "surfaceVisibility",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "template id",
+        target: "templateId",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "title",
+        target: "title",
+    },
+    {
+        cardinality: "one",
+        scope: "instrument",
+        spelling: "update",
+        target: "update",
+    },
+];
 const udlDocumentShapeSchema = z.strictObject({
-    nouns: z.array(udlNounSchema).min(1),
+    dials: z.array(udlCompositionDialSchema).min(1).optional(),
+    instruments: z.array(udlInstrumentSchema).min(1),
     product: udlSnakeCaseSchema,
     subjects: z.array(udlSubjectSchema),
     title: nonEmptyTextSchema,
@@ -355,7 +1034,7 @@ const moneyPatterns = new Set(["^[1-9][0-9]{0,17}$", "^(0|[1-9][0-9]{0,17})$"]);
 function isMoneyField(schema) {
     return (typeof schema?.pattern === "string" && moneyPatterns.has(schema.pattern));
 }
-function referenceTargets(schema, nouns) {
+function referenceTargets(schema, instruments) {
     if (schema.type !== "string" || typeof schema.pattern !== "string")
         return [];
     // Parse the scoped-ID pattern. Executing an author regex here would bypass
@@ -375,40 +1054,47 @@ function referenceTargets(schema, nouns) {
     if (typeof schema.maxLength === "number" && probe.length > schema.maxLength) {
         return [];
     }
-    return nouns.filter((noun) => noun.idPrefix === prefix);
+    return instruments.filter((instrument) => instrument.idPrefix === prefix);
 }
-function declaredMoneyRefKeys(noun) {
+function declaredMoneyRefKeys(instrument) {
     return new Set([
-        ...(noun.computedMoneyRefs ?? []),
-        ...Object.values(noun.verbs).flatMap((verb) => [
-            ...(verb.signedSum
+        ...Object.values(instrument.actions).flatMap((action) => [
+            ...(action.remainder
+                ? [
+                    action.remainder.amountRef,
+                    ...(action.remainder.accumulateRef
+                        ? [action.remainder.accumulateRef]
+                        : []),
+                ]
+                : []),
+            ...(action.signedSum
                 ? [
-                    verb.signedSum.amountRef,
-                    ...verb.signedSum.sources.map((source) => source.subtotalRef),
+                    action.signedSum.amountRef,
+                    ...action.signedSum.sources.map((source) => source.subtotalRef),
                 ]
                 : []),
-            ...(verb.distribute ? [verb.distribute.amountRef] : []),
+            ...(action.distribute ? [action.distribute.amountRef] : []),
+            ...(action.quote ? [action.quote.chargeRef, action.quote.netRef] : []),
         ]),
-        ...(noun.unwind ? ["unwindRefund", "unwindPenalty"] : []),
     ]);
 }
 export const udlDocumentSchema = udlDocumentShapeSchema.superRefine((document, context) => {
-    document.nouns.forEach((noun, nounIndex) => {
-        noun.derivedAmounts?.forEach((amount, amountIndex) => {
+    document.instruments.forEach((instrument, instrumentIndex) => {
+        instrument.derivedAmounts?.forEach((amount, amountIndex) => {
             const base = [
-                "nouns",
-                nounIndex,
+                "instruments",
+                instrumentIndex,
                 "derivedAmounts",
                 amountIndex,
             ];
-            if (!isMoneyField(noun.fields[amount.field])) {
+            if (!isMoneyField(instrument.fields[amount.field])) {
                 context.addIssue({
                     code: "custom",
                     message: `derived amount target ${amount.field} must be a declared money field`,
                     path: [...base, "field"],
                 });
             }
-            if (!isMoneyField(noun.fields[amount.sourceField])) {
+            if (!isMoneyField(instrument.fields[amount.sourceField])) {
                 context.addIssue({
                     code: "custom",
                     message: `derived amount source ${amount.sourceField} must be a declared money field`,
@@ -423,29 +1109,29 @@ export const udlDocumentSchema = udlDocumentShapeSchema.superRefine((document, c
                 });
             }
         });
-        Object.entries(noun.verbs).forEach(([verbName, verb]) => {
-            const distribute = verb.distribute;
+        Object.entries(instrument.actions).forEach(([actionName, action]) => {
+            const distribute = action.distribute;
             if (!distribute)
                 return;
             const base = [
-                "nouns",
-                nounIndex,
-                "verbs",
-                verbName,
+                "instruments",
+                instrumentIndex,
+                "actions",
+                actionName,
                 "distribute",
             ];
-            const refSchema = noun.fields[distribute.refField];
+            const refSchema = instrument.fields[distribute.refField];
             const parents = refSchema
-                ? referenceTargets(refSchema, document.nouns)
+                ? referenceTargets(refSchema, document.instruments)
                 : [];
             if (parents.length !== 1) {
                 context.addIssue({
                     code: "custom",
-                    message: `distribute refField ${distribute.refField} must identify exactly one parent noun`,
+                    message: `distribute refField ${distribute.refField} must identify exactly one parent instrument`,
                     path: [...base, "refField"],
                 });
             }
-            if (!isMoneyField(noun.fields[distribute.weightField])) {
+            if (!isMoneyField(instrument.fields[distribute.weightField])) {
                 context.addIssue({
                     code: "custom",
                     message: `distribute weightField ${distribute.weightField} must be a declared money field`,
@@ -453,11 +1139,11 @@ export const udlDocumentSchema = udlDocumentShapeSchema.superRefine((document, c
                 });
             }
             distribute.statuses.forEach((status, statusIndex) => {
-                if (noun.lifecycle.states.includes(status))
+                if (instrument.lifecycle.states.includes(status))
                     return;
                 context.addIssue({
                     code: "custom",
-                    message: `distribute status ${status} is not declared by ${noun.id}`,
+                    message: `distribute status ${status} is not declared by ${instrument.id}`,
                     path: [...base, "statuses", statusIndex],
                 });
             });