@stll/agent-input 0.0.1-placeholder.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1 +1,77 @@
1
- Placeholder for @stll/agent-input; real releases are published from https://github.com/stella/stella.
1
+ # @stll/agent-input
2
+
3
+ Lenient readers for values agents write: dates, date-format specs, numbers, booleans, locales, countries, enum values.
4
+
5
+ ## What lives here
6
+
7
+ One reader per value kind that reaches a tool input, a template marker, or a
8
+ fill value. Each reads the spellings that carry a single meaning (`4 000`,
9
+ `1. 10. 2026`, `ano`, `cs_CZ`, `Česko`) and returns the one ask-for-a-fix shape
10
+ when a spelling carries two (`01/02/2026`, a bare `1,234`, a bare `cs`), so no
11
+ call site grows its own parser or its own wording.
12
+
13
+ `normalizeCountry` reads ISO 3166-1 alpha-3 and alpha-2 codes and the country's
14
+ name in each language the corpus serves, and returns both canonical spellings so
15
+ a caller keeps the one its column holds. The names come from CLDR through
16
+ `Intl.DisplayNames` rather than from a table maintained here; only the official
17
+ long forms CLDR omits (`Česká republika` against its `Česko`) are declared.
18
+ Recognising a country is not admitting it: whether a corpus holds that
19
+ jurisdiction stays the caller's `not_found`.
20
+
21
+ A third outcome exists only on optional inputs: `ok: "absent"`, the input read
22
+ as no value (`readAsAbsent`, `NormalizedOptional<T>`). A model fills every slot
23
+ it is shown, so a filter it is not setting still arrives as `"any"`, `"-"`, the
24
+ nil uuid, or `9999-12-31`. `isAbsentPlaceholder` holds the closed set of
25
+ placeholder words; it is never applied to free text, and the caller decides
26
+ which inputs it covers.
27
+
28
+ `normalizeUuid` reads an id in any spelling that names the same 128 bits
29
+ (uppercase, `{...}`, `urn:uuid:`, no dashes) as the lowercase dashed form, and
30
+ reads the ids a model invents when it has none (nil, max, one repeated digit,
31
+ the RFC and tutorial examples) as no value.
32
+
33
+ `normalizeVocabularyValue` reads a filter value whose allowed set comes from
34
+ data rather than the schema: court names, decision types. It widens step by
35
+ step, from the exact value through folded spellings and aliases to word
36
+ containment, and stops at the first step that finds exactly one entry, so
37
+ `Ústavní soud České republiky` reads as `Ústavní soud` while `Krajský soud`
38
+ asks which regional court. Closed schema enums stay with `normalizeEnumValue`.
39
+
40
+ `normalizeStringList` reads an array sent as its JSON string, and a bare string
41
+ as a list. Whether a bare string is split on commas is the caller's `split`:
42
+ ids can be, free-text phrases cannot.
43
+
44
+ `normalizeDateBound` reads one end of a date range: a bare year or month is that
45
+ end's first or last day, an open-ended sentinel year (`0001`, `9999`) is no
46
+ bound, and a whole range written into one field asks for its two halves.
47
+ `normalizeDateValue` takes the same `bound` without the absent outcome.
48
+
49
+ `normalizeNumberInRange` clamps a bounded count (a page size) into range with a
50
+ note instead of asking, and asks about a fraction where the count is whole.
51
+ Which fields clamp is the caller's choice.
52
+
53
+ `normalizeEli` reads a European Legislation Identifier with or without its
54
+ origin, in any case, with a trailing slash, or with year and number swapped, as
55
+ the canonical work identifier under the publisher origin the caller maps each
56
+ jurisdiction to. A path past the work (a version date, a provision) asks for
57
+ the work; an input that is not an ELI goes through the caller's citation reader
58
+ before it asks.
59
+
60
+ `normalizeAgentInput` derives a recursive normalization plan from the canonical
61
+ JSON Schema. Standard number, boolean, string-enum, and `format: date` keywords
62
+ are the annotations for those kinds; `x-stella-agent-input` names locale and
63
+ date-format fields that JSON Schema cannot distinguish from ordinary strings or
64
+ objects. `agentInputNormalizationMetadata` emits that annotation and its MCP/CLI
65
+ guidance together. `invalidValueDisposition: "handler-owned"` is reserved for
66
+ handlers that deliberately repair invalid properties while applying valid
67
+ siblings; valid spellings still normalize through the shared reader.
68
+
69
+ ## What does not
70
+
71
+ Transport, strict schema validation, and persistence. First-party agent
72
+ transports call the shared API dispatch boundary; upstream MCP servers keep
73
+ their own contracts. Ordinary strings are never normalized heuristically.
74
+
75
+ ## License
76
+
77
+ Apache-2.0
@@ -0,0 +1,420 @@
1
+ import { CountryAlpha3Code, CountryCode } from "@stll/country-codes";
2
+ import { DateFormatStyle } from "@stll/template-conditions";
3
+ //#region src/absent.d.ts
4
+ /**
5
+ * Placeholders on optional filters.
6
+ *
7
+ * A model fills every slot a schema shows it, so a filter it means to leave
8
+ * unset still arrives as `"any"`, `"-"` or `"none"`. Those words name no
9
+ * court, no type, no record: read as a value they match nothing and the call
10
+ * returns an empty page the model then explains away. The set is closed and
11
+ * short on purpose; a word outside it is a value and goes to the kind's own
12
+ * reader.
13
+ *
14
+ * This is not for free text. `"none"` is a fine answer to a question and `"-"`
15
+ * a fine clause body, so the caller decides which inputs a placeholder can
16
+ * stand in for.
17
+ */
18
+ /** The words, already in the folded lowercase form they are compared in. */
19
+ export declare const ABSENT_PLACEHOLDERS: readonly ["-", "--", "–", "—", "*", "all", "any", "none", "null", "nil", "undefined", "n/a", "(none)", "<none>", "(any)", "(all)"];
20
+ /** Whether a string stands for "no value" on an optional filter: blank, or one
21
+ * of the placeholder words in any case and spacing. */
22
+ export declare const isAbsentPlaceholder: (input: unknown) => boolean;
23
+ //#endregion
24
+ //#region src/normalized.d.ts
25
+ /**
26
+ * One shape for every value an agent spells its own way.
27
+ *
28
+ * Models copy examples, translate, and reach for the notation their training
29
+ * data used most: a date arrives as `1. 10. 2026`, a number as `4 000`, a
30
+ * boolean as `ano`, a locale as `cs_CZ`. Each kind in this directory reads the
31
+ * spellings that carry one meaning and asks for a fix when a spelling carries
32
+ * two, so no call site grows its own parser or its own wording.
33
+ *
34
+ * `ok: true` is the canonical value, with `note` set when the input had to be
35
+ * read rather than taken verbatim (surface it as a warning, never as an
36
+ * error). `ok: false` is the single ask-for-a-fix shape: `expected` names the
37
+ * canonical form and `hint` names the one call to make. Callers render those
38
+ * two rather than composing wording of their own, which is what keeps one kind
39
+ * answering the same way on every surface.
40
+ */
41
+ /** The one ask-for-a-fix shape. */
42
+ type NormalizedAsk = {
43
+ ok: false;
44
+ /** The input as the agent sent it, quoted and bounded. */
45
+ received: string;
46
+ /** The canonical form as a noun phrase: "a calendar date". */
47
+ expected: string;
48
+ /** The corrective call, spelled out. */
49
+ hint: string;
50
+ };
51
+ type Normalized<TValue> = {
52
+ ok: true;
53
+ value: TValue;
54
+ note?: string;
55
+ } | NormalizedAsk;
56
+ export declare const askForFix: ({ input, expected, hint }: {
57
+ input: unknown;
58
+ expected: string;
59
+ hint: string;
60
+ }) => NormalizedAsk;
61
+ /** The ask as one sentence, for a caller whose issue shape carries a message
62
+ * beside the hint. */
63
+ export declare const askSentence: (ask: NormalizedAsk) => string;
64
+ /**
65
+ * The input read as no value at all.
66
+ *
67
+ * An optional filter the agent is not setting still arrives filled in: `"any"`,
68
+ * `"-"`, the nil uuid, `9999-12-31` as an open bound. Each of those means "not
69
+ * filtering", and asking about it would send the model back to delete a value
70
+ * it only wrote because the schema had a slot. Only a reader that can see a
71
+ * placeholder returns this, and only on inputs the caller marked optional; the
72
+ * caller drops the property and surfaces `note` as a warning.
73
+ */
74
+ type NormalizedAbsent = {
75
+ ok: "absent";
76
+ /** The input as the agent sent it, quoted and bounded. */
77
+ received: string;
78
+ note: string;
79
+ };
80
+ /** A reader's outcome on an optional input, where a placeholder is no value. */
81
+ type NormalizedOptional<TValue> = Normalized<TValue> | NormalizedAbsent;
82
+ /** The absent outcome, with the one "read X as no value" sentence every kind
83
+ * reports it with. `reason` says why, when the spelling alone does not. */
84
+ export declare const readAsAbsent: (input: unknown, reason?: string) => NormalizedAbsent;
85
+ //#endregion
86
+ //#region src/boolean.d.ts
87
+ /** Read a yes/no answer an agent spelled its own way. */
88
+ export declare const normalizeBoolean: (input: unknown) => Normalized<boolean>;
89
+ //#endregion
90
+ //#region src/country.d.ts
91
+ /**
92
+ * Jurisdictions that publish law without being ISO 3166-1 countries.
93
+ *
94
+ * The EU is the one this corpus holds: the Court of Justice and the Official
95
+ * Journal are supranational, and legal corpora and ELI identifiers spell that
96
+ * jurisdiction `EU`. CLDR carries `EU` as a region, so its names arrive from
97
+ * the same place as a country's, and ISO assigns it neither alpha-2 nor
98
+ * alpha-3, so `EU` is both.
99
+ */
100
+ declare const SUPRANATIONAL_CODES: readonly ["EU"];
101
+ type SupranationalCode = (typeof SUPRANATIONAL_CODES)[number];
102
+ /** A canonical alpha-3 code, or the supranational code ISO leaves unassigned. */
103
+ type CountryAlpha3 = CountryAlpha3Code | SupranationalCode;
104
+ /** A canonical alpha-2 (CLDR region) code, or the supranational code. */
105
+ type CountryAlpha2 = CountryCode | SupranationalCode;
106
+ /**
107
+ * One country, in both spellings a consumer might store.
108
+ *
109
+ * Both are returned because both are canonical somewhere: the corpus keys on
110
+ * alpha-3, and a practice-jurisdiction row and every CLDR lookup key on
111
+ * alpha-2. A caller picks the one its column holds instead of converting.
112
+ */
113
+ type CountryValue = {
114
+ readonly alpha3: CountryAlpha3;
115
+ readonly alpha2: CountryAlpha2;
116
+ };
117
+ /**
118
+ * The longest country spelling a wire schema accepts.
119
+ *
120
+ * A country's own name is a spelling this reader reads, so the bound is a
121
+ * name's length rather than a code's: `Federal Republic of Germany` is a
122
+ * country input, and a schema capped at three characters was what turned it
123
+ * into a rejection before the reader ever saw it. It lives with the reader so
124
+ * the declared bound and what can be read cannot drift apart.
125
+ */
126
+ export declare const COUNTRY_INPUT_MAX_CHARS = 64;
127
+ /** Which ISO spelling the calling surface stores. */
128
+ type CountrySpelling = "alpha-3" | "alpha-2";
129
+ type CountryOptions = {
130
+ /** The spelling the caller keeps, which decides how a coercion is reported:
131
+ * a surface storing alpha-2 must not be told its `CZ` was read as `CZE`. */
132
+ spelling?: CountrySpelling | undefined;
133
+ /** The canonical codes the calling surface holds law for, named in the ask so
134
+ * a model that guessed wrong can see what there is to ask for. */
135
+ admitted?: readonly string[] | undefined;
136
+ /** The tool whose input this is, so the ask names the call to change. */
137
+ tool?: string | undefined;
138
+ /** The property name, which differs between surfaces (`country`,
139
+ * `country_code`). */
140
+ parameter?: string | undefined;
141
+ };
142
+ /** The code a caller keeping `spelling` stores. */
143
+ export declare const countryCodeIn: (value: CountryValue, spelling?: CountrySpelling) => string;
144
+ /**
145
+ * Read a country an agent spelled its own way.
146
+ *
147
+ * An absent value asks rather than defaulting: a corpus country decides which
148
+ * body of law is searched, and picking one on the model's behalf answers a
149
+ * question about Czech law with Slovak decisions.
150
+ */
151
+ export declare const normalizeCountry: (input: unknown, options?: CountryOptions) => Normalized<CountryValue>;
152
+ //#endregion
153
+ //#region src/date-format-spec.d.ts
154
+ type DateFormatSpec = {
155
+ locale: string;
156
+ style: DateFormatStyle;
157
+ };
158
+ export declare const DATE_FORMAT_SPEC_HINT: string;
159
+ /** Read a date-format spec an agent spelled its own way, as one string or as
160
+ * the wire object. */
161
+ export declare const normalizeDateFormatSpec: (input: unknown) => Normalized<DateFormatSpec>;
162
+ //#endregion
163
+ //#region src/date-value.d.ts
164
+ export declare const DATE_VALUE_HINT: string;
165
+ type DateValueOptions = {
166
+ /** Locales to read besides English: the field's own `dateFormat` locale, so
167
+ * a document rendered in Czech accepts a Czech month name back, and one
168
+ * rendered in Portuguese accepts `1 de outubro de 2026` — the structure
169
+ * that locale renders, not only its month names. */
170
+ locales?: readonly string[] | undefined;
171
+ /** Which end of a range the date is. A bound reads a bare year or month as
172
+ * that end's first or last day, and asks when both ends arrive in one
173
+ * field. */
174
+ bound?: DateBound | undefined;
175
+ };
176
+ type DateBound = "start" | "end";
177
+ /** Read a calendar date an agent spelled its own way, as ISO YYYY-MM-DD. With
178
+ * a `bound`, a bare year or month reads as that end's day, and a whole range
179
+ * in the one field asks for its two halves. */
180
+ export declare const normalizeDateValue: (input: unknown, options?: DateValueOptions) => Normalized<string>;
181
+ type DateBoundOptions = {
182
+ bound: DateBound;
183
+ locales?: readonly string[] | undefined;
184
+ };
185
+ /**
186
+ * Read one end of a date range. A placeholder or an open-ended sentinel date
187
+ * is no bound at all, so the caller drops the property rather than filtering
188
+ * to the year 1 or 9999.
189
+ */
190
+ export declare const normalizeDateBound: (input: unknown, options: DateBoundOptions) => NormalizedOptional<string>;
191
+ //#endregion
192
+ //#region src/eli.d.ts
193
+ type EliOptions = {
194
+ /** ELI jurisdiction segment (lowercase, `"cz"`) to the publisher origin
195
+ * (`"https://www.e-sbirka.cz"`) that canonical identifiers carry. */
196
+ hosts: Readonly<Record<string, string>>;
197
+ /** The caller's gazette-citation reader, for an input that is not an ELI at
198
+ * all (`89/2012 Sb.`): the ELI that citation names, or undefined. */
199
+ readCitation?: ((text: string) => string | undefined) | undefined;
200
+ /** The corrective call when the input is not an ELI. */
201
+ hint?: string | undefined;
202
+ };
203
+ /**
204
+ * Read an ELI an agent spelled its own way, as the canonical work identifier
205
+ * under its publisher's origin. An input that is not an ELI goes through the
206
+ * caller's citation reader before it asks.
207
+ */
208
+ export declare const normalizeEli: (input: unknown, options: EliOptions) => Normalized<string>;
209
+ //#endregion
210
+ //#region src/enum-value.d.ts
211
+ type EnumValueOptions = {
212
+ /** What the set is called in the ask: "The styles", "The registries". */
213
+ label?: string;
214
+ /** What the set is, as a noun phrase for `expected`: "a date style". */
215
+ expected?: string;
216
+ };
217
+ /**
218
+ * Read one value of a closed set. An exact hit is taken verbatim; a hit that
219
+ * differs only in case, spacing, or diacritics is read with a note; a value one
220
+ * edit from an allowed one asks and names it; anything else asks with the whole
221
+ * set, which is short enough to copy from.
222
+ */
223
+ export declare const normalizeEnumValue: <TValue extends string>(input: unknown, allowed: readonly TValue[], options?: EnumValueOptions) => Normalized<TValue>;
224
+ //#endregion
225
+ //#region src/locale.d.ts
226
+ /**
227
+ * Whether a tag is already the spelling `Intl` accepts. This is the check a
228
+ * stored or advertised locale passes: a value that reaches
229
+ * `Intl.DateTimeFormat` at fill time must not be able to make it throw, so the
230
+ * leniency below stops at the boundary and never reaches persistence.
231
+ */
232
+ export declare const isPlausibleLocale: (value: string) => boolean;
233
+ /** Read a locale an agent spelled its own way, canonically. */
234
+ export declare const normalizeLocale: (input: unknown) => Normalized<string>;
235
+ //#endregion
236
+ //#region src/number.d.ts
237
+ type NumberOptions = {
238
+ /** The field's locale, when one is configured. It decides `1,234`. */
239
+ locale?: string | undefined;
240
+ };
241
+ /** Read a number an agent spelled its own way. */
242
+ export declare const normalizeNumber: (input: unknown, options?: NumberOptions) => Normalized<number>;
243
+ type NumberInRangeOptions = NumberOptions & {
244
+ minimum?: number | undefined;
245
+ maximum?: number | undefined;
246
+ /** A count: a fraction asks, since 12.5 results is no page size and
247
+ * rounding either way would be a guess. */
248
+ integer?: boolean | undefined;
249
+ };
250
+ /**
251
+ * Read a bounded count (a page size, a result limit) and clamp it into range.
252
+ *
253
+ * `limit: 500` against a cap of 100 has one sensible reading, the most the
254
+ * tool returns, and asking would cost a round trip to learn a number the note
255
+ * can state. The caller decides which fields clamp: a monetary amount out of
256
+ * range is a mistake to ask about, not a value to move.
257
+ */
258
+ export declare const normalizeNumberInRange: (input: unknown, options: NumberInRangeOptions) => Normalized<number>;
259
+ //#endregion
260
+ //#region src/string-list.d.ts
261
+ type StringListOptions = {
262
+ /** `"delimiters"` splits a scalar on commas, semicolons and newlines, for
263
+ * items that cannot contain them (ids, codes). `"never"` wraps a scalar as
264
+ * one item, for free text that may. */
265
+ split: "never" | "delimiters";
266
+ };
267
+ /** Read a list of strings an agent spelled its own way. Only the list's own
268
+ * shape is read here: an array is taken as it is, and one holding anything
269
+ * but strings asks, since what an item should have been is the item's
270
+ * question, not the list's. */
271
+ export declare const normalizeStringList: (input: unknown, options: StringListOptions) => Normalized<string[]>;
272
+ //#endregion
273
+ //#region src/uuid.d.ts
274
+ /** Documentation uuids a model reproduces when it has no real id: RFC 4122
275
+ * and RFC 9562 examples, and the ones tutorials and SDK docs print. */
276
+ export declare const SENTINEL_UUIDS: readonly ["123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426655440000", "01234567-89ab-cdef-0123-456789abcdef", "12345678-1234-1234-1234-123456789012", "12345678-1234-5678-1234-567812345678", "12345678-90ab-cdef-1234-567890abcdef", "00000000-0000-0000-0000-000000000001"];
277
+ /** Whether a canonical uuid is one a model writes for "some id" rather than a
278
+ * record's: nil, max, one repeated digit, or a documentation example. */
279
+ export declare const isSentinelUuid: (canonical: string) => boolean;
280
+ type UuidOptions = {
281
+ /** What the id names, for `expected`: "a matter id". */
282
+ expected?: string | undefined;
283
+ /** The corrective call, when the caller has a better one than the default. */
284
+ hint?: string | undefined;
285
+ };
286
+ /** Read an id an agent spelled its own way, as a lowercase dashed uuid. A
287
+ * placeholder or an invented id is no value. */
288
+ export declare const normalizeUuid: (input: unknown, options?: UuidOptions) => NormalizedOptional<string>;
289
+ //#endregion
290
+ //#region src/vocabulary.d.ts
291
+ /** One allowed value, plus the other names it goes by in the data. */
292
+ type VocabularyEntry = {
293
+ value: string;
294
+ aliases?: readonly string[];
295
+ };
296
+ type VocabularyOptions = {
297
+ /** What the set is called in the ask: "The courts". */
298
+ label?: string;
299
+ /** What the set is, as a noun phrase for `expected`: "a court name". */
300
+ expected?: string;
301
+ /** How many values an ask names before "and N more". */
302
+ maxListed?: number;
303
+ };
304
+ /**
305
+ * Read one value of a vocabulary drawn from data. A placeholder is no value; a
306
+ * spelling that narrows to one entry reads as it with a note; a spelling that
307
+ * matches several, or none, asks and names what there is.
308
+ */
309
+ export declare const normalizeVocabularyValue: (input: unknown, entries: readonly VocabularyEntry[], options?: VocabularyOptions) => NormalizedOptional<string>;
310
+ //#endregion
311
+ //#region src/schema.d.ts
312
+ export declare const AGENT_INPUT_NORMALIZATION_KEY = "x-stella-agent-input";
313
+ export declare const AGENT_INPUT_NORMALIZATION_KIND: {
314
+ readonly boolean: "boolean";
315
+ readonly country: "country";
316
+ readonly date: "date";
317
+ readonly dateFormat: "date-format";
318
+ readonly eli: "eli";
319
+ readonly enum: "enum";
320
+ readonly filter: "filter";
321
+ readonly locale: "locale";
322
+ readonly number: "number";
323
+ readonly stringList: "string-list";
324
+ readonly uuid: "uuid";
325
+ };
326
+ type AgentInputNormalizationKind = (typeof AGENT_INPUT_NORMALIZATION_KIND)[keyof typeof AGENT_INPUT_NORMALIZATION_KIND];
327
+ /**
328
+ * What a country field needs beyond its kind: which ISO spelling the surface
329
+ * stores, and the codes it holds law for, so the ask names the tool to call and
330
+ * the values there are to ask for.
331
+ */
332
+ type AgentInputCountryAnnotation = {
333
+ spelling: CountrySpelling;
334
+ admitted?: readonly string[];
335
+ tool?: string;
336
+ };
337
+ type AgentInputAnnotationCommon = {
338
+ /** Preserve invalid input only when the owning handler deliberately repairs it. */
339
+ invalidValueDisposition?: "handler-owned";
340
+ /** Locale context disambiguates numeric grouping and adds named date months. */
341
+ locale?: string;
342
+ /**
343
+ * A `date` field that is one end of a range: a bare year or month then names
344
+ * its first or last day, and an open-ended sentinel (`0001-01-01`,
345
+ * `9999-12-31`) reads as no bound.
346
+ */
347
+ bound?: "start" | "end";
348
+ /**
349
+ * A `number` field whose range is a server limit rather than a meaning, such
350
+ * as a page size: a value outside it is clamped with a note instead of
351
+ * refused.
352
+ */
353
+ range?: "clamp";
354
+ };
355
+ /**
356
+ * A kind, plus whatever that kind cannot be read without.
357
+ *
358
+ * `country` is a union branch rather than an optional property because it has
359
+ * two canonical spellings and no default between them: a field declared
360
+ * `{ kind: "country" }` alone would type-check and then have nothing to say
361
+ * about which code to store.
362
+ */
363
+ type AgentInputNormalizationAnnotation = (AgentInputAnnotationCommon & {
364
+ kind: Exclude<AgentInputNormalizationKind, typeof AGENT_INPUT_NORMALIZATION_KIND.country>;
365
+ country?: never;
366
+ }) | (AgentInputAnnotationCommon & {
367
+ kind: typeof AGENT_INPUT_NORMALIZATION_KIND.country;
368
+ country: AgentInputCountryAnnotation;
369
+ });
370
+ /** Attach an explicit normalization kind to a canonical JSON Schema field. */
371
+ export declare const agentInputNormalization: (annotation: AgentInputNormalizationAnnotation) => Record<typeof AGENT_INPUT_NORMALIZATION_KEY, AgentInputNormalizationAnnotation>;
372
+ /** Concise model guidance derived from the same kind dispatch executes. */
373
+ export declare const agentInputNormalizationGuidance: (annotation: AgentInputNormalizationAnnotation) => string;
374
+ /** Schema metadata shared by MCP descriptions and generated CLI help. */
375
+ export declare const agentInputNormalizationMetadata: (annotation: AgentInputNormalizationAnnotation, description?: string) => ReturnType<typeof agentInputNormalization> & {
376
+ description: string;
377
+ };
378
+ type AgentInputNormalizationIssue = {
379
+ path: string;
380
+ received: string;
381
+ expected: string;
382
+ hint: string;
383
+ };
384
+ type AgentInputNormalizationResult = {
385
+ ok: true;
386
+ value: unknown;
387
+ notes: readonly string[];
388
+ } | {
389
+ ok: false;
390
+ issues: readonly AgentInputNormalizationIssue[];
391
+ };
392
+ /** Readers a kind cannot run without, supplied by the surface that owns the
393
+ * data: which publisher serves each ELI jurisdiction is the corpus's, not
394
+ * this package's. A kind whose reader is missing is left as sent. */
395
+ type AgentInputReaders = {
396
+ eli?: EliOptions;
397
+ };
398
+ /**
399
+ * What a placeholder in an optional property means. On a read it is "not
400
+ * filtering", so the property is dropped with a note. On a write an optional
401
+ * id can switch what the call does (update this record, or create one), and a
402
+ * placeholder there is an intent nobody stated, so it is asked about.
403
+ */
404
+ type AgentInputPlaceholderPolicy = "absent" | "ask";
405
+ /**
406
+ * Normalize one agent-written value from its canonical JSON Schema. Standard
407
+ * `type`, `format: date`, and string `enum` keywords are the annotations for
408
+ * numbers, booleans, dates, and closed vocabularies. The extension key handles
409
+ * kinds JSON Schema cannot name, such as locales and date-format specs.
410
+ */
411
+ export declare const normalizeAgentInput: ({ path, placeholders, readers, schema, value }: {
412
+ path?: string;
413
+ /** What a placeholder in an optional property means; see the type. */
414
+ placeholders?: AgentInputPlaceholderPolicy;
415
+ readers?: AgentInputReaders;
416
+ schema: unknown;
417
+ value: unknown;
418
+ }) => AgentInputNormalizationResult;
419
+ //#endregion
420
+ export type { AgentInputCountryAnnotation, AgentInputNormalizationAnnotation, AgentInputNormalizationIssue, AgentInputNormalizationKind, AgentInputNormalizationResult, AgentInputPlaceholderPolicy, AgentInputReaders, CountryAlpha2, CountryAlpha3, CountryOptions, CountrySpelling, CountryValue, DateBound, DateBoundOptions, DateValueOptions, EliOptions, Normalized, NormalizedAbsent, NormalizedAsk, NormalizedOptional, NumberInRangeOptions, NumberOptions, StringListOptions, UuidOptions, VocabularyEntry, VocabularyOptions };