@orkestrel/template 0.0.5 → 0.0.7

package/dist/src/core/index.d.cts

@@ -1,665 +1,841 @@
-import { ContractShape } from '@orkestrel/contract';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { FieldPath } from '@orkestrel/contract';
+import type { ContractShape } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { FieldPath } from '@orkestrel/contract';
 
 /**
- * Create a template.
+ * Creates a working {@link TemplateInterface} from a {@link TemplateOptions}
+ * bag, backed by the `Template` class.
  *
  * @param options - The template's `name` / `content`, an optional `id`
  *   (defaults to a generated UUID), `placeholders`, catalog metadata, and
  *   `missing` / `locale` fill defaults
  * @returns A working {@link TemplateInterface}
- *
- * @example
- * ```ts
- * import { createTemplate } from '@src/core'
- *
- * const greeting = createTemplate({ name: 'greeting', content: 'Hi {{name}}' })
- * greeting.fill({ name: 'Ada' }) // 'Hi Ada'
- * ```
- */
-export declare function createTemplate(options: TemplateOptions): TemplateInterface;
-
-/**
- * Create a template registry.
- *
- * @param options - Optional initial `templates` seed collection and
- *   manager-wide `missing` / `locale` fill defaults, emitter `on` hooks, and
- *   an `error` handler
- * @returns A working {@link TemplateManagerInterface}
- *
- * @example
- * ```ts
- * import { createTemplateManager } from '@src/core'
- *
- * const templates = createTemplateManager({
- * 	templates: [{ id: 'greeting', name: 'greeting', content: 'Hi {{name}}' }],
- * })
- * templates.fill('greeting', { name: 'Ada' }) // 'Hi Ada'
- * ```
- */
-export declare function createTemplateManager(options?: TemplateManagerOptions): TemplateManagerInterface;
-
-/** Default `locale` for `Template#fill` / `TemplateManager#fill` when unspecified. */
-export declare const DEFAULT_LOCALE = "en-US";
-
-/** Default `missing` policy for `Template#fill` / `TemplateManager#fill` when unspecified. */
-export declare const DEFAULT_MISSING_POLICY: MissingPolicy;
-
-/**
- * The single-pass `{{name}}` substitution pattern shared by `Template#fill`
- * and `Template#validate`.
- *
- * @remarks
- * Global-flagged, two-alternative pattern: a match of the FIRST alternative
- * (`\{{` — a literal backslash followed by `{{`) means "emit a literal
- * `{{`" — the escape hatch for content that must show `{{` without
- * triggering substitution. A match that instead populates capture group 1
- * (`\{{([^{}]+?)\}\}`) means "substitute the named token" — group 1 is the
- * RAW (untrimmed) token text between the braces; every call site trims it
- * (`token.trim()`) before using it as a lookup name, so `'{{ name }}'` still
- * resolves `'name'`. The pattern intentionally does NOT wrap the token in
- * `\s*` — an unclosed `'{{' + ' '.repeat(n)` with no closing `}}` would
- * otherwise force the regex engine into catastrophic backtracking over the
- * whitespace run (O(n^2)); trimming after the match keeps the same
- * whitespace tolerance without the backtracking hazard. Every call site
- * builds a fresh `RegExp` from `.source` / `.flags` rather than sharing this
- * instance's mutable `lastIndex` across scans.
- */
-export declare const FILL_PATTERN: RegExp;
-
-/**
- * Substitute every `{{name}}` token in `content` in a single pass.
- *
- * @remarks
- * Uses a fresh `RegExp` clone of `FILL_PATTERN` per call (never sharing its
- * `lastIndex`) and a single `String#replace` scan — substituted output is
- * never re-scanned. For each token: the matching declared
- * {@link TemplatePlaceholder} (exact `name`) supplies its `path` (falling
- * back to the token split on `.`); ANY path segment in `UNSAFE_FIELD_SEGMENTS`
- * makes the token unresolved without ever calling `resolveField` (a
- * prototype-pollution guard). A resolved value formats via `formatValue`; an
- * unresolved value falls back to the placeholder's `fallback` when declared;
- * otherwise `options.missing` governs — `'literal'` re-emits the original
- * `{{name}}` text, `'empty'` emits `''`, and `'error'` emits `''` for every
- * token but collects EVERY unresolved required token (an undeclared token, or
- * a declared token with `required !== false`) and throws one
- * {@link TemplateError} coded `MISSING` listing them all, in first-appearance
- * order, once the scan completes. An escaped `\{{` emits a literal `{{`.
- *
- * PARITY: called with no declared `placeholders` and `{ missing: 'empty' }`,
- * this reproduces `interpolateMessage` (`@src/core` sibling
- * `interpret`) vector-for-vector. KNOWN DIVERGENCE: `FILL_PATTERN`'s token
- * class (`[^{}]`) excludes `{`, where `interpolateMessage`'s (`[^}]`) allows
- * it — a token containing `{` therefore behaves differently here.
- *
- * @param content - The template content carrying `{{name}}` tokens
- * @param values - The values tokens resolve against
- * @param options - `missing` (default `'error'`), `locale` (default `'en-US'`), and the declared `placeholders` (default none) tokens resolve against
- * @returns The substituted content
- *
- * @example
- * ```ts
- * import { fillTemplate } from '@src/core'
- *
- * fillTemplate('Hi {{name}}', { name: 'Ada' }) // 'Hi Ada'
- * fillTemplate('Limit {{limit}}', { limit: 5010 }, { missing: 'empty' }) // 'Limit 5,010'
- * ```
- */
-export declare function fillTemplate(content: string, values?: TemplateFillValues, options?: TemplateFillOptions & {
-    readonly placeholders?: readonly TemplatePlaceholder[];
-}): string;
-
-/**
- * Format a resolved fill value for substitution into a template's `content`.
- *
- * @remarks
- * A finite number renders with the given locale's thousand grouping (via
- * `toLocaleString`); every other value — including `null` — String-coerces.
- * `null` therefore renders as the literal string `'null'`, intentionally
- * mirroring `interpolateMessage`'s coercion parity (see `fillTemplate`). An
- * invalid BCP-47 `locale` tag throws a `RangeError` from the underlying
- * `toLocaleString` call when `value` is a finite number — this is a caller
- * error (an invalid locale argument), by design, and is not caught here.
- *
- * @param value - The resolved value to format
- * @param locale - The locale used for finite-number formatting
- * @returns The formatted string
- *
- * @example
- * ```ts
- * import { formatValue } from '@src/core'
- *
- * formatValue(5010, 'en-US') // '5,010'
- * formatValue(null, 'en-US') // 'null'
- * ```
- */
-export declare function formatValue(value: unknown, locale: string): string;
-
-/**
- * Narrow an unknown caught value to a {@link TemplateError}.
- *
- * @param value - The value to test (typically a `catch` binding)
- * @returns `true` when `value` is a {@link TemplateError}
- *
- * @example
- * ```ts
- * import { isTemplateError } from '@src/core'
- *
- * try {
- * 	manager.template('missing')
- * } catch (error) {
- * 	if (isTemplateError(error) && error.code === 'NOTFOUND') return
- * }
- * ```
- */
-export declare function isTemplateError(value: unknown): value is TemplateError;
-
-/**
- * How {@link TemplateInterface#fill} handles an unresolved required
- * placeholder.
- *
- * @remarks
- * `error` — throws a {@link TemplateError} coded `MISSING`. `empty` —
- * substitutes an empty string. `literal` — substitutes the placeholder's own
- * `{{name}}` token back into the output, unchanged.
- */
-export declare type MissingPolicy = 'error' | 'empty' | 'literal';
-
-/**
- * Build the `@orkestrel/contract` object shape describing a template's
- * declared placeholders.
- *
- * @remarks
- * Each placeholder becomes a `stringShape` carrying its `description`;
- * `required === false` wraps it in `optionalShape`. Used by `Template` to
- * compile its `parameters()` contract once per instance.
- *
- * @param placeholders - The declared placeholders to shape
- * @returns The contract shape for `createContract`
- *
- * @example
- * ```ts
- * import { placeholderShape } from '@src/core'
- * import { createContract } from '@orkestrel/contract'
- *
- * const contract = createContract(placeholderShape([{ name: 'city' }]))
- * ```
- */
-export declare function placeholderShape(placeholders: readonly TemplatePlaceholder[]): ContractShape;
-
-/**
- * Resolve a field path against a fill-values record, refusing any path that
- * touches a prototype-pollution-unsafe segment.
- *
- * @remarks
- * A prototype-pollution guard shared by `fillTemplate` and `Template#validate`
- * so the two stay in lockstep: `path` normalizes to a segment array (a bare
- * string `path` becomes a single-segment array); if ANY segment appears in
- * `UNSAFE_FIELD_SEGMENTS` (`'__proto__'`, `'constructor'`, `'prototype'`), the
- * lookup is refused and `undefined` is returned WITHOUT ever calling
- * `resolveField` — a path like `['__proto__', 'polluted']` can never reach
- * the record's actual prototype chain through this function. Every other
- * path resolves through `@orkestrel/contract`'s `resolveField`.
- *
- * @param record - The fill-values record to resolve against
- * @param path - The field path — a single segment or a segment array
- * @returns The resolved value, or `undefined` when unresolved or the path is unsafe
- *
- * @example
- * ```ts
- * import { resolveSafeField } from '@src/core'
- *
- * resolveSafeField({ a: { b: 1 } }, ['a', 'b']) // 1
- * resolveSafeField({}, ['__proto__', 'polluted']) // undefined
- * ```
- */
-export declare function resolveSafeField(record: TemplateFillValues, path: FieldPath): unknown;
-
-/**
- * A named, versionable template — `{{name}}` tokens in `content`, filled
- * against a values record.
- *
- * @remarks
- * `missing` / `locale` seed this instance's default {@link TemplateFillOptions},
- * overridable per `fill` call. Its `parameters()` contract (built from
- * `placeholders` via `placeholderShape`) compiles once, in the constructor.
- *
- * @example
- * ```ts
- * const greeting = new Template({ name: 'greeting', content: 'Hi {{name}}' })
- * greeting.fill({ name: 'Ada' }) // 'Hi Ada'
- * ```
- */
-export declare class Template implements TemplateInterface {
-    #private;
-    readonly id: string;
-    readonly name: string;
-    readonly content: string;
-    readonly placeholders: readonly TemplatePlaceholder[];
-    readonly summary?: string;
-    readonly description?: string;
-    readonly category?: string;
-    readonly tags?: readonly string[];
-    constructor(options: TemplateOptions);
-    /**
-     * The plain, JSON-serializable data this template carries.
-     *
-     * @returns The {@link TemplateDefinition} record
-     *
-     * @example
-     * ```ts
-     * const instance = new Template({ name: 'greeting', content: 'Hi {{name}}' })
-     * instance.definition().name // 'greeting'
-     * ```
-     */
-    definition(): TemplateDefinition;
-    /**
-     * Substitute every `{{name}}` token in `content` against `values`.
-     *
-     * @param values - The values tokens resolve against
-     * @param options - Per-call overrides for this instance's `missing` / `locale` defaults
-     * @returns The substituted content
-     *
-     * @example
-     * ```ts
-     * const instance = new Template({ name: 'greeting', content: 'Hi {{name}}' })
-     * instance.fill({ name: 'Ada' }) // 'Hi Ada'
-     * ```
-     */
-    fill(values?: TemplateFillValues, options?: TemplateFillOptions): string;
-    /**
-     * Report which required placeholders would stay unresolved, and which
-     * `values` keys go unused, without producing output.
-     *
-     * @remarks
-     * Content-token driven: scans `this.content` for every `{{name}}` token
-     * (skipping escaped `\{{` matches) the same way `fill` does, so `validate`
-     * predicts `fill`'s `'error'`-{@link MissingPolicy} outcome exactly — a
-     * token reported here as missing is precisely a token that would throw
-     * under `fill(values, { missing: 'error' })`. For each distinct token
-     * (first-appearance order, trimmed): a declared {@link TemplatePlaceholder}
-     * sharing its `name` supplies `path` (falling back to the token split on
-     * `.`); the value resolves via `resolveSafeField`. The token is `missing`
-     * only when the value is unresolved AND no `fallback` is declared AND the
-     * placeholder is required (`required !== false`, including undeclared
-     * tokens). `extra` lists every `values` key with no declared placeholder.
+ * @throws {@link TemplateError} Thrown when `options.placeholders` declares a duplicate `name` or an empty `path` (coded `INVALID`)
      *
-     * @param values - The values to check
-     * @returns The {@link TemplateValidationResult}
-     *
-     * @example
+     * @example Create a template and a registry
      * ```ts
-     * const instance = new Template({
-     * 	name: 'greeting',
-     * 	content: 'Hi {{name}}',
-     * 	placeholders: [{ name: 'name' }],
-     * })
-     * instance.validate({}).missing // ['name']
-     * ```
-     */
-    validate(values?: TemplateFillValues): TemplateValidationResult;
-    /**
-     * Project this template's placeholders to the open tool-parameters record
-     * shape.
+     * import { createTemplate, createTemplateManager } from '@orkestrel/template'
      *
-     * @returns The compiled parameters record, or `undefined` when `schemaToParameters` yields none
+     * const greeting = createTemplate({ name: 'greeting', content: 'Hi {{name}}' })
+     * greeting.fill({ name: 'Ada' }) // 'Hi Ada'
      *
-     * @example
-     * ```ts
-     * const instance = new Template({
-     * 	name: 'greeting',
-     * 	content: 'Hi {{name}}',
-     * 	placeholders: [{ name: 'name' }],
+     * const templates = createTemplateManager({
+     * 	templates: [
+     * 		{ id: 'greeting', name: 'greeting', content: 'Hi {{name}}', category: 'mail' },
+     * 		{ id: 'farewell', name: 'farewell', content: 'Bye {{name}}', category: 'mail' },
+     * 		{ id: 'alert', name: 'alert', content: 'Alert: {{reason}}', category: 'ops' },
+     * 	],
      * })
-     * instance.parameters()
+     * templates.fill('greeting', { name: 'Ada' }) // 'Hi Ada'
+     * templates.find({ category: 'mail' }).map((one) => one.id) // ['greeting', 'farewell']
+     * templates.has('alert') // true
+     * templates.has('missing') // false
      * ```
      */
-    parameters(): Readonly<Record<string, unknown>> | undefined;
-}
+ export declare function createTemplate(options: TemplateOptions): TemplateInterface;
 
-/**
- * A named, versionable template record — pure data, no behavior.
- *
- * @remarks
- * `content` is the raw string carrying `{{name}}` tokens (see
- * `FILL_PATTERN` in `constants.ts`); `placeholders` declares every token's
- * lookup rule. `summary` / `description` / `category` / `tags` are optional
- * catalog metadata for `TemplateManagerInterface#find`.
- */
-export declare interface TemplateDefinition {
-    readonly id: string;
-    readonly name: string;
-    readonly content: string;
-    readonly placeholders: readonly TemplatePlaceholder[];
-    readonly summary?: string;
-    readonly description?: string;
-    readonly category?: string;
-    readonly tags?: readonly string[];
-}
+ /**
+  * Creates a working {@link TemplateManagerInterface}, optionally seeded with
+  * the templates the options carry, backed by the `TemplateManager` class.
+  *
+  * @param options - Optional initial `templates` seed collection and
+  *   manager-wide `missing` / `locale` fill defaults, emitter `on` hooks, and
+  *   an `error` handler
+  * @returns A working {@link TemplateManagerInterface}
+  * @throws {@link TemplateError} Thrown when a seeded `options.templates` bag declares a duplicate placeholder `name` or an empty `path` (coded `INVALID`)
+      *
+      * @example
+      * ```ts
+      * import { createTemplateManager } from '@src/core'
+      *
+      * const templates = createTemplateManager({
+      * 	templates: [{ id: 'greeting', name: 'greeting', content: 'Hi {{name}}' }],
+      * })
+      * templates.fill('greeting', { name: 'Ada' }) // 'Hi Ada'
+      * ```
+      */
+  export declare function createTemplateManager(options?: TemplateManagerOptions): TemplateManagerInterface;
 
-/**
- * An error thrown by the template layer.
- *
- * @remarks
- * Thrown for: a required placeholder staying unresolved under the `error`
- * {@link MissingPolicy} (`MISSING`), an unknown template id
- * (`NOTFOUND`), `createTemplate` handed invalid data (`INVALID`), and
- * `TemplateManagerInterface#register` handed an id already present without
- * `options.replace` (`CONFLICT`). `context`, when present, carries the
- * offending id / name.
- */
-export declare class TemplateError extends Error {
-    readonly code: TemplateErrorCode;
-    readonly context?: Readonly<Record<string, unknown>>;
-    constructor(code: TemplateErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
-}
+  /**
+   * Holds `'en-US'`, the default `locale` for `Template#fill` /
+   * `TemplateManager#fill` when unspecified.
+   */
+  export declare const DEFAULT_LOCALE = "en-US";
 
-/**
- * Coded misuse / failure conditions thrown as a {@link TemplateError}.
- *
- * @remarks
- * `MISSING` — a required placeholder stayed unresolved under the `error`
- * {@link MissingPolicy}. `NOTFOUND` — `TemplateManagerInterface#template`
- * (or `fill` / `validate` / `parameters` by id) was handed an unknown id.
- * `INVALID` — `createTemplate` was handed data that fails validation.
- * `CONFLICT` — `register` was handed an id already present without
- * `options.replace`.
- */
-export declare type TemplateErrorCode = 'MISSING' | 'NOTFOUND' | 'INVALID' | 'CONFLICT';
-
-/** Per-call options for `TemplateInterface#fill` / `TemplateManagerInterface#fill`. */
-export declare interface TemplateFillOptions {
-    readonly missing?: MissingPolicy;
-    readonly locale?: string;
-}
-
-/** The values a {@link TemplateInterface#fill} / `#validate` call resolves placeholders against. */
-export declare type TemplateFillValues = Readonly<Record<string, unknown>>;
+  /**
+   * Holds `'error'`, the default `missing` policy for `Template#fill` /
+   * `TemplateManager#fill` when unspecified.
+   */
+  export declare const DEFAULT_MISSING_POLICY: MissingPolicy;
 
-/**
- * The template contract (AGENTS §22 — exact bijection with `Template`).
- *
- * @remarks
- * `definition` returns the plain {@link TemplateDefinition} data. `fill`
- * substitutes every `{{name}}` token in `content` against `values`,
- * honoring `options.missing` for unresolved required placeholders. `validate`
- * reports which required placeholders are unresolved (`missing`) and which
- * supplied `values` keys are unused (`extra`) without producing output.
- * `parameters` projects this template's placeholders to the open
- * tool-parameters record shape (`schemaToParameters`'s return type from
- * `@orkestrel/contract`).
- */
-export declare interface TemplateInterface {
-    readonly id: string;
-    readonly name: string;
-    readonly content: string;
-    readonly placeholders: readonly TemplatePlaceholder[];
-    readonly summary?: string;
-    readonly description?: string;
-    readonly category?: string;
-    readonly tags?: readonly string[];
-    definition(): TemplateDefinition;
-    fill(values?: TemplateFillValues, options?: TemplateFillOptions): string;
-    validate(values?: TemplateFillValues): TemplateValidationResult;
-    parameters(): Readonly<Record<string, unknown>> | undefined;
-}
+  /**
+   * Holds the single-pass `{{name}}` substitution pattern shared by
+   * `Template#fill` and `Template#validate`.
+   *
+   * @remarks
+   * Global-flagged, two-alternative pattern: a match of the first alternative
+   * (`\{{` — a literal backslash followed by `{{`) means "emit a literal
+   * `{{`" — the escape hatch for content that must show `{{` without
+   * triggering substitution. A match that instead populates capture group 1
+   * (`\{{([^{}]+?)\}\}`) means "substitute the named token" — group 1 is the
+   * untrimmed token text between the braces; every call site trims it
+   * (`token.trim()`) before using it as a lookup name, so `'{{ name }}'` still
+   * resolves `'name'`. The pattern deliberately does not wrap the token in
+   * `\s*` — an unclosed `'{{' + ' '.repeat(n)` with no closing `}}` would
+   * otherwise force the regex engine into catastrophic backtracking over the
+   * whitespace run (O(n^2)); trimming after the match keeps the same
+   * whitespace tolerance without the backtracking hazard. Every call site
+   * builds a fresh `RegExp` from `.source` / `.flags` rather than sharing this
+   * instance's mutable `lastIndex` across scans.
+   */
+  export declare const FILL_PATTERN: RegExp;
 
-/**
- * The template registry — a self-owning, id-keyed record-holder for the
- * {@link TemplateInterface} instances a consumer registers, looks up, fills,
- * and validates by id (AGENTS §9.1 singular/plural accessors, §9.2 batch
- * `remove` overloads, §13 emitter ownership).
- *
- * @remarks
- * `register` accepts either a constructed {@link TemplateInterface} (kept
- * as-is, including its own `missing` / `locale` defaults) or a plain
- * {@link TemplateOptions} bag — constructed into a `Template` with this
- * manager's `missing` / `locale` defaults applied wherever the bag omits
- * them. A duplicate `id` throws a {@link TemplateError} coded `CONFLICT`
- * unless `options.replace` is `true`, in which case the existing entry is
- * overwritten. `options.templates` SEEDS the registry at construction
- * WITHOUT emitting `register` — only calls to `register` after construction
- * emit. The batch `remove(ids)` form is ALL-OR-NOTHING: any id absent from
- * the registry leaves the collection untouched and returns `false`.
- *
- * @example
- * ```ts
- * import { TemplateManager } from '@src/core'
- *
- * const manager = new TemplateManager()
- * const instance = manager.register({ name: 'greeting', content: 'Hi {{name}}' })
- * manager.fill(instance.id, { name: 'Ada' }) // 'Hi Ada'
- * ```
- */
-export declare class TemplateManager implements TemplateManagerInterface {
-    #private;
-    constructor(options?: TemplateManagerOptions);
-    get emitter(): EmitterInterface<TemplateManagerEventMap>;
-    get size(): number;
-    /**
-     * Register a template — a constructed {@link TemplateInterface} (kept
-     * as-is) or a plain {@link TemplateOptions} bag (constructed into a
-     * `Template` with this manager's `missing` / `locale` defaults applied
-     * wherever the bag omits them).
-     *
-     * @param template - The template instance or options to register
-     * @param options - `replace` — overwrite an existing entry sharing the same id instead of throwing
-     * @returns The registered {@link TemplateInterface}
-     *
-     * @example
-     * ```ts
-     * const instance = manager.register({ id: 'greeting', name: 'greeting', content: 'Hi {{name}}' })
-     * ```
-     */
-    register(template: TemplateInterface | TemplateOptions, options?: {
-        readonly replace?: boolean;
-    }): TemplateInterface;
-    /**
-     * Look up a registered template by id.
-     *
-     * @param id - The template id
-     * @returns The registered {@link TemplateInterface}
-     * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
-         */
-     template(id: string): TemplateInterface;
-     /**
-      * List every registered template.
-      *
-      * @returns A snapshot array of every registered {@link TemplateInterface}
-      */
-     templates(): readonly TemplateInterface[];
-     /**
-      * Filter registered templates by name / category / tag — every supplied
-      * field must match (logical AND).
-      *
-      * @param query - The {@link TemplateQuery} to filter by; omit for every registered template
-      * @returns The matching templates
-      */
-     find(query?: TemplateQuery): readonly TemplateInterface[];
-     /**
-      * Test whether a template id is registered.
-      *
-      * @param id - The template id
-      * @returns `true` when `id` is registered
-      */
-     has(id: string): boolean;
-     /**
-      * Remove one, several, or every registered template (AGENTS §9.2 batch
-      * overloads) — array overload declared first so a list resolves to the
-      * batch form.
-      *
-      * @remarks
-      * `remove()` removes every registered template, emitting `remove` once per
-      * instance. `remove(id)` removes one template by id, emitting `remove` and
-      * returning `true` when it existed, `false` otherwise. `remove(ids)` is
-      * ALL-OR-NOTHING: if any id in the list is unregistered, the collection is
-      * left untouched and `false` is returned; otherwise every listed template
-      * is removed (each emitting `remove`) and `true` is returned.
-      *
-      * @param target - Omit to remove all, a single id, or a list of ids
-      * @returns `boolean` for the single-id / list-of-ids forms; `void` for the remove-all form
-      */
-     remove(ids: readonly string[]): boolean;
-     remove(id: string): boolean;
-     remove(): void;
-     /** Remove every registered template, emitting `clear`. */
-     clear(): void;
-     /**
-      * Fill a registered template by id.
-      *
-      * @param id - The template id
-      * @param values - The values tokens resolve against
-      * @param options - Per-call overrides for the template's `missing` / `locale` defaults
-      * @returns The substituted content
-      * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
-          */
-      fill(id: string, values?: TemplateFillValues, options?: TemplateFillOptions): string;
-      /**
-       * Validate values against a registered template by id.
+  /**
+   * Substitutes every `{{name}}` token in `content` in a single pass.
+   *
+   * @remarks
+   * Uses a fresh `RegExp` clone of `FILL_PATTERN` per call (never sharing its
+   * `lastIndex`) and a single `String#replace` scan — substituted output is
+   * never re-scanned. Each token resolves through `resolveToken`, the one rule
+   * `Template#validate` also applies: the matching declared
+   * {@link TemplatePlaceholder} (exact `name`) supplies its `path` (falling
+   * back to the token split on `.`); any path segment in `UNSAFE_FIELD_SEGMENTS`
+   * makes the token unresolved without ever calling `resolveField` (a
+   * prototype-pollution guard). A resolved value formats through `formatValue`; an
+   * unresolved value falls back to the placeholder's `fallback` when declared;
+   * otherwise `options.missing` governs — `'literal'` re-emits the original
+   * `{{name}}` text, `'empty'` emits `''`, and `'error'` emits `''` for every
+   * token but collects every unresolved required token (an undeclared token, or
+   * a declared token with `required !== false`) and throws one
+   * {@link TemplateError} coded `MISSING` listing them all, in first-appearance
+   * order, once the scan completes. An escaped `\{{` emits a literal `{{`.
+   *
+   * Called with no declared `placeholders` and `{ missing: 'empty' }`, this is a
+   * bare interpolation over `content` — every token resolves by dotted path
+   * against the values record and every unresolved token emits `''`.
+   * `FILL_PATTERN`'s token class (`[^{}]`) excludes `{`, so a token containing
+   * `{` never matches and the surrounding `{{` stays literal.
+   *
+   * @param content - The template content carrying `{{name}}` tokens
+   * @param values - The values tokens resolve against
+   * @param options - `missing` (default `'error'`), `locale` (default `'en-US'`), and the declared `placeholders` (default none) tokens resolve against
+   * @returns The substituted content
+   *
+   * @example
+   * ```ts
+   * import { fillTemplate } from '@src/core'
+   *
+   * fillTemplate('Hi {{name}}', { name: 'Ada' }) // 'Hi Ada'
+   * fillTemplate('Limit {{limit}}', { limit: 5010 }, { missing: 'empty' }) // 'Limit 5,010'
+   * ```
+   */
+  export declare function fillTemplate(content: string, values?: TemplateFillValues, options?: TemplateFillContext): string;
+
+  /**
+   * Formats a resolved fill value for substitution into a template's `content`.
+   *
+   * @remarks
+   * A finite number renders with the given locale's thousand grouping (through
+   * `toLocaleString`); every other value — including `null` — String-coerces.
+   * `null` therefore renders as the literal string `'null'`, matching
+   * `String(value)` exactly, so a resolved `null` is visible in the output
+   * rather than silently empty. An
+   * invalid BCP-47 `locale` tag throws a `RangeError` from the underlying
+   * `toLocaleString` call when `value` is a finite number — this is a caller
+   * error (an invalid locale argument), by design, and is not caught here.
+   *
+   * @param value - The resolved value to format
+   * @param locale - The locale used for finite-number formatting
+   * @returns The formatted string
+   *
+   * @example
+   * ```ts
+   * import { formatValue } from '@src/core'
+   *
+   * formatValue(5010, 'en-US') // '5,010'
+   * formatValue(null, 'en-US') // 'null'
+   * ```
+   */
+  export declare function formatValue(value: unknown, locale: string): string;
+
+  /**
+   * Narrows an unknown caught value to a {@link TemplateError}.
+   *
+   * @param value - The value to test (typically a `catch` binding)
+   * @returns True if `value` is a {@link TemplateError}; false otherwise
+   *
+   * @example
+   * ```ts
+   * import { isTemplateError } from '@src/core'
+   *
+   * try {
+   * 	manager.fill('missing')
+   * } catch (error) {
+   * 	if (isTemplateError(error) && error.code === 'NOTFOUND') return
+   * }
+   * ```
+   */
+  export declare function isTemplateError(value: unknown): value is TemplateError;
+
+  /**
+   * Names how {@link TemplateInterface#fill} handles an unresolved required
+   * placeholder.
+   *
+   * @remarks
+   * `error` — throws a {@link TemplateError} coded `MISSING`. `empty` —
+   * substitutes an empty string. `literal` — substitutes the placeholder's own
+   * `{{name}}` token back into the output, unchanged.
+   */
+  export declare type MissingPolicy = 'error' | 'empty' | 'literal';
+
+  /**
+   * Builds the `@orkestrel/contract` object shape describing a template's
+   * declared placeholders.
+   *
+   * @remarks
+   * Each placeholder becomes a `stringShape` carrying its `description`;
+   * `required === false` wraps it in `optionalShape`. Used by `Template` to
+   * compile its `parameters()` contract once per instance.
+   *
+   * @param placeholders - The declared placeholders to shape
+   * @returns The contract shape for `createContract`
+   *
+   * @example
+   * ```ts
+   * import { placeholderShape } from '@src/core'
+   * import { createContract } from '@orkestrel/contract'
+   *
+   * const contract = createContract(placeholderShape([{ name: 'city' }]))
+   * ```
+   */
+  export declare function placeholderShape(placeholders: readonly TemplatePlaceholder[]): ContractShape;
+
+  /**
+   * Resolves a field path against a fill-values record, refusing any path that
+   * touches a prototype-pollution-unsafe segment.
+   *
+   * @remarks
+   * A prototype-pollution guard shared by `fillTemplate` and `Template#validate`
+   * so the two stay in lockstep: `path` normalizes to a segment array (a bare
+   * string `path` becomes a single-segment array); if any segment appears in
+   * `UNSAFE_FIELD_SEGMENTS` (`'__proto__'`, `'constructor'`, `'prototype'`), the
+   * lookup is refused and `undefined` is returned without ever calling
+   * `resolveField` — a path like `['__proto__', 'polluted']` can never reach
+   * the record's actual prototype chain through this function. Every other
+   * path resolves through `@orkestrel/contract`'s `resolveField`.
+   *
+   * @param record - The fill-values record to resolve against
+   * @param path - The field path — a single segment or a segment array
+   * @returns The resolved value, or `undefined` when unresolved or the path is unsafe
+   *
+   * @example
+   * ```ts
+   * import { resolveSafeField } from '@src/core'
+   *
+   * resolveSafeField({ a: { b: 1 } }, ['a', 'b']) // 1
+   * resolveSafeField({}, ['__proto__', 'polluted']) // undefined
+   * ```
+   */
+  export declare function resolveSafeField(record: TemplateFillValues, path: FieldPath): unknown;
+
+  /**
+   * Resolves one `{{name}}` token against the declared placeholders and the
+   * fill-values record.
+   *
+   * @remarks
+   * The single implementation of the token rule `fillTemplate` and
+   * `Template#validate` both apply, so the two can never drift: the declared
+   * {@link TemplatePlaceholder} sharing the token's `name` (exact match)
+   * supplies its `path`, falling back to the token split on `.`; the value
+   * resolves through `resolveSafeField`, so any segment in
+   * `UNSAFE_FIELD_SEGMENTS` yields `undefined` without ever calling
+   * `resolveField`; `required` is `true` for an undeclared token and for a
+   * declared placeholder whose `required` is not `false`. The token is passed
+   * already trimmed. `fallback` is not applied here — it is read from
+   * `declared` by each caller, because `fill` substitutes it and `validate`
+   * only counts it.
+   *
+   * @param record - The fill-values record the token resolves against
+   * @param placeholders - The declared placeholders the token matches by name
+   * @param token - The trimmed token text, without its `{{` / `}}` delimiters
+   * @returns The {@link TemplateTokenResolution} for the token
+   *
+   * @example
+   * ```ts
+   * import { resolveToken } from '@src/core'
+   *
+   * resolveToken({ name: 'Ada' }, [], 'name').value // 'Ada'
+   * resolveToken({}, [{ name: 'nickname', required: false }], 'nickname').required // false
+   * ```
+   */
+  export declare function resolveToken(record: TemplateFillValues, placeholders: readonly TemplatePlaceholder[], token: string): TemplateTokenResolution;
+
+  /**
+   * Represents a named, versionable template — `{{name}}` tokens in `content`,
+   * filled against a values record — implementing `TemplateInterface` exactly.
+   *
+   * @remarks
+   * `missing` / `locale` seed this instance's default {@link TemplateFillOptions},
+   * overridable per `fill` call. Its `parameters()` contract (built from
+   * `placeholders` through `placeholderShape`) compiles once, in the constructor.
+   *
+   * @throws {@link TemplateError} Thrown when `options.placeholders` declares a duplicate `name` or an empty `path` (coded `INVALID`)
        *
-       * @param id - The template id
-       * @param values - The values to check
-       * @returns The {@link TemplateValidationResult}
-       * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
-           */
-       validate(id: string, values?: TemplateFillValues): TemplateValidationResult;
+       * @example
+       * ```ts
+       * const greeting = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+       * greeting.fill({ name: 'Ada' }) // 'Hi Ada'
+       * ```
+       */
+   export declare class Template implements TemplateInterface {
+       #private;
+       readonly id: string;
+       readonly name: string;
+       readonly content: string;
+       readonly placeholders: readonly TemplatePlaceholder[];
+       readonly summary?: string;
+       readonly description?: string;
+       readonly category?: string;
+       readonly tags?: readonly string[];
+       constructor(options: TemplateOptions);
        /**
-        * Project a registered template's parameters by id.
+        * Returns the plain, JSON-serializable data this template carries.
+        *
+        * @returns The {@link TemplateDefinition} record
         *
-        * @param id - The template id
-        * @returns The compiled parameters record, or `undefined` when the template has none
-        * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+        * @example
+        * ```ts
+        * const instance = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+        * instance.definition().name // 'greeting'
+        * ```
+        */
+       definition(): TemplateDefinition;
+       /**
+        * Substitutes every `{{name}}` token in `content` against `values`.
+        *
+        * @param values - The values tokens resolve against
+        * @param options - Per-call overrides for this instance's `missing` / `locale` defaults
+        * @returns The substituted content
+        * @throws {@link TemplateError} Thrown when a required placeholder stays unresolved under the `'error'` policy (coded `MISSING`)
+            *
+            * @example
+            * ```ts
+            * const instance = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+            * instance.fill({ name: 'Ada' }) // 'Hi Ada'
+            * ```
             */
-        parameters(id: string): Readonly<Record<string, unknown>> | undefined;
+        fill(values?: TemplateFillValues, options?: TemplateFillOptions): string;
+        /**
+         * Reports which required placeholders would stay unresolved, and which
+         * `values` keys go unused, without producing output.
+         *
+         * @remarks
+         * Content-token driven: scans `this.content` for every `{{name}}` token
+         * (skipping escaped `\{{` matches) the same way `fill` does, so `validate`
+         * predicts `fill`'s `'error'`-{@link MissingPolicy} outcome exactly — a
+         * token reported here as missing is precisely a token that would throw
+         * under `fill(values, { missing: 'error' })`. For each distinct token
+         * (first-appearance order, trimmed): `resolveToken` applies the one shared
+         * token rule `fill` also applies — a declared {@link TemplatePlaceholder}
+         * sharing its `name` supplies `path` (falling back to the token split on
+         * `.`), and the value resolves through `resolveSafeField`. The token is `missing`
+         * only when the value is unresolved, no `fallback` is declared, and the
+         * placeholder is required (`required !== false`, including undeclared
+         * tokens). `extra` lists every `values` key with no declared placeholder.
+         *
+         * @param values - The values to check
+         * @returns The {@link TemplateValidationResult}
+         *
+         * @example
+         * ```ts
+         * const instance = new Template({
+         * 	name: 'greeting',
+         * 	content: 'Hi {{name}}',
+         * 	placeholders: [{ name: 'name' }],
+         * })
+         * instance.validate({}).missing // ['name']
+         * ```
+         */
+        validate(values?: TemplateFillValues): TemplateValidationResult;
+        /**
+         * Projects this template's placeholders to the open tool-parameters record
+         * shape.
+         *
+         * @returns The compiled parameters record, or `undefined` when `schemaToParameters` yields none
+         *
+         * @example
+         * ```ts
+         * const instance = new Template({
+         * 	name: 'greeting',
+         * 	content: 'Hi {{name}}',
+         * 	placeholders: [{ name: 'name' }],
+         * })
+         * instance.parameters()
+         * ```
+         */
+        parameters(): Readonly<Record<string, unknown>> | undefined;
        }
 
        /**
-        * The push observation surface of a {@link TemplateManagerInterface} (AGENTS
-        * §13) — an id-keyed registry, so `register` / `remove` are the events
-        * (never ordered-list `append`/`prepend`).
+        * Represents a named, versionable template record — pure data, no behavior.
+        *
+        * @remarks
+        * `content` is the raw string carrying `{{name}}` tokens (see
+        * `FILL_PATTERN` in `constants.ts`); `placeholders` declares every token's
+        * lookup rule. `category` and `tags` are the fields
+        * `TemplateManagerInterface#find` filters on, alongside `name`. `summary` and
+        * `description` are catalog metadata that `definition()` carries and no query
+        * reads.
         */
-       export declare type TemplateManagerEventMap = {
-           /** A template was registered — carries the registered template. */
-           readonly register: readonly [template: TemplateInterface];
-           /** A template was removed — carries the removed template. */
-           readonly remove: readonly [template: TemplateInterface];
-           /** The registry was cleared. */
-           readonly clear: readonly [];
-       };
+       export declare interface TemplateDefinition {
+           readonly id: string;
+           readonly name: string;
+           readonly content: string;
+           readonly placeholders: readonly TemplatePlaceholder[];
+           readonly summary?: string;
+           readonly description?: string;
+           readonly category?: string;
+           readonly tags?: readonly string[];
+       }
 
        /**
-        * The template registry — a self-owning, id-keyed record-holder (AGENTS §9.1
-        * singular/plural accessors, §9.2 batch overloads).
+        * Represents an error thrown by the template layer — a machine-readable
+        * {@link TemplateErrorCode} and an optional `context` record naming the
+        * offending id or placeholder name.
         *
         * @remarks
-        * `register` accepts either a constructed {@link TemplateInterface} or a
-        * plain {@link TemplateOptions} bag (constructed internally), and throws a
-        * {@link TemplateError} coded `CONFLICT` when the id already exists unless
-        * `options.replace` is `true`. `template` throws `NOTFOUND` for an unknown
-        * id. `remove`'s batch form is all-or-nothing: any missing id in the list
-        * leaves the collection untouched and returns `false`.
+        * Thrown for: a required placeholder staying unresolved under the `error`
+        * {@link MissingPolicy} (`MISSING`), an unknown template id
+        * (`NOTFOUND`), `createTemplate` handed invalid data (`INVALID`), and
+        * `TemplateManagerInterface#register` handed an id already present without
+        * `options.replace` (`CONFLICT`).
         */
-       export declare interface TemplateManagerInterface {
-           readonly emitter: EmitterInterface<TemplateManagerEventMap>;
-           readonly size: number;
-           register(template: TemplateInterface | TemplateOptions, options?: {
-               readonly replace?: boolean;
-           }): TemplateInterface;
-           template(id: string): TemplateInterface;
-           templates(): readonly TemplateInterface[];
-           find(query?: TemplateQuery): readonly TemplateInterface[];
-           has(id: string): boolean;
-           remove(ids: readonly string[]): boolean;
-           remove(id: string): boolean;
-           remove(): void;
-           clear(): void;
-           fill(id: string, values?: TemplateFillValues, options?: TemplateFillOptions): string;
-           validate(id: string, values?: TemplateFillValues): TemplateValidationResult;
-           parameters(id: string): Readonly<Record<string, unknown>> | undefined;
+       export declare class TemplateError extends Error {
+           readonly code: TemplateErrorCode;
+           readonly context?: Readonly<Record<string, unknown>>;
+           constructor(code: TemplateErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
        }
 
        /**
-        * Options for `createTemplateManager` / the `TemplateManager` constructor.
+        * Names the coded misuse / failure conditions thrown as a {@link TemplateError}.
+        *
+        * @remarks
+        * `MISSING` — a required placeholder stayed unresolved under the `error`
+        * {@link MissingPolicy}. `NOTFOUND` — `TemplateManagerInterface#fill`,
+        * `#validate`, or `#parameters` was handed an unknown id.
+        * `INVALID` — `createTemplate` was handed data that fails validation.
+        * `CONFLICT` — `register` was handed an id already present without
+        * `options.replace`.
+        */
+       export declare type TemplateErrorCode = 'MISSING' | 'NOTFOUND' | 'INVALID' | 'CONFLICT';
+
+       /**
+        * Carries the full option bag `fillTemplate` takes — the per-call
+        * {@link TemplateFillOptions} plus the declared placeholders tokens resolve
+        * against.
         *
         * @remarks
-        * `templates` seeds the registry — either constructed {@link TemplateInterface}
-        * instances or plain {@link TemplateOptions} bags. `missing` / `locale` are
-        * the manager-wide default {@link TemplateFillOptions}, overridable per-call.
-        * `on` — initial event listeners (AGENTS §8/§13). `error` — the emitter's
-        * listener-error handler.
+        * `Template#fill` supplies `placeholders` from its own declaration; a direct
+        * `fillTemplate` caller supplies them per call, and omitting them fills
+        * against undeclared tokens alone.
         */
-       export declare interface TemplateManagerOptions {
-           readonly templates?: ReadonlyArray<TemplateInterface | TemplateOptions>;
+       export declare interface TemplateFillContext extends TemplateFillOptions {
+           readonly placeholders?: readonly TemplatePlaceholder[];
+       }
+
+       /** Carries the per-call options for `TemplateInterface#fill` / `TemplateManagerInterface#fill`. */
+       export declare interface TemplateFillOptions {
            readonly missing?: MissingPolicy;
            readonly locale?: string;
-           readonly on?: EmitterHooks<TemplateManagerEventMap>;
-           readonly error?: EmitterErrorHandler;
        }
 
+       /** Represents the values a {@link TemplateInterface#fill} / `#validate` call resolves placeholders against. */
+       export declare type TemplateFillValues = Readonly<Record<string, unknown>>;
+
        /**
-        * Options for `createTemplate` / the `Template` constructor.
+        * Declares the template contract a consumer holds — the readonly template
+        * record and the `definition`, `fill`, `validate`, and `parameters` calls
+        * over it.
         *
         * @remarks
-        * `id` defaults to a generated id when omitted. `placeholders` defaults to
-        * an empty list. `missing` / `locale` seed the instance's default
-        * {@link TemplateFillOptions}, overridable per-call.
+        * `Template` implements this contract exactly, so the class exposes these
+        * members and no other public behavior.
         */
-       export declare interface TemplateOptions {
-           readonly id?: string;
+       export declare interface TemplateInterface {
+           readonly id: string;
            readonly name: string;
            readonly content: string;
-           readonly placeholders?: readonly TemplatePlaceholder[];
+           readonly placeholders: readonly TemplatePlaceholder[];
            readonly summary?: string;
            readonly description?: string;
            readonly category?: string;
            readonly tags?: readonly string[];
-           readonly missing?: MissingPolicy;
-           readonly locale?: string;
+           /** Returns the plain, JSON-serializable template data. */
+           definition(): TemplateDefinition;
+           /**
+            * Substitutes every `{{name}}` token in `content` against `values`.
+            *
+            * @remarks
+            * `options.missing` governs an unresolved required placeholder, defaulting
+            * to the instance's own {@link MissingPolicy}.
+            */
+           fill(values?: TemplateFillValues, options?: TemplateFillOptions): string;
+           /**
+            * Reports which required placeholders would stay unresolved, and which
+            * `values` keys go unused.
+            *
+            * @remarks
+            * The unresolved names arrive as `missing` and the unused keys as `extra`,
+            * and neither reading produces output.
+            */
+           validate(values?: TemplateFillValues): TemplateValidationResult;
+           /**
+            * Projects the declared placeholders to the open tool-parameters record
+            * shape.
+            *
+            * @remarks
+            * The shape is `schemaToParameters`'s return type from
+            * `@orkestrel/contract`.
+            */
+           parameters(): Readonly<Record<string, unknown>> | undefined;
        }
 
        /**
-        * One placeholder a {@link TemplateDefinition}'s `content` declares — its
-        * lookup name, an optional field path into the values record, whether it is
-        * required, and a literal fallback.
+        * Represents the template registry — a self-owning, id-keyed record-holder for
+        * the {@link TemplateInterface} instances a consumer registers, looks up,
+        * fills, and validates by id — implementing `TemplateManagerInterface`
+        * exactly.
         *
         * @remarks
-        * `name` is the `{{name}}` token as written in `content`. `path`, when
-        * present, resolves the fill value through a (possibly nested)
-        * {@link FieldPath} rather than a flat `name` lookup on the values record.
-        * `required` defaults to `true` when omitted — an unresolved required
-        * placeholder is governed by the active {@link MissingPolicy}. `fallback` is
-        * a literal substituted when the value is unresolved, regardless of
-        * `required`.
+        * Singular and plural accessors, the batch `remove` overloads, and ownership
+        * of the emitter all sit here. `register` accepts either a constructed {@link TemplateInterface} (kept
+        * as-is, including its own `missing` / `locale` defaults) or a plain
+        * {@link TemplateOptions} bag — constructed into a `Template` with this
+        * manager's `missing` / `locale` defaults applied wherever the bag omits
+        * them. A duplicate `id` throws a {@link TemplateError} coded `CONFLICT`
+        * unless `options.replace` is `true`, in which case the existing entry is
+        * overwritten. `options.templates` seeds the registry at construction without
+        * emitting `register` — only calls to `register` after construction emit.
+        * The batch `remove(ids)` form removes every present id and returns
+        * `true` only when every listed id was present.
+        *
+        * @example
+        * ```ts
+        * import { TemplateManager } from '@src/core'
+        *
+        * const manager = new TemplateManager()
+        * const instance = manager.register({ name: 'greeting', content: 'Hi {{name}}' })
+        * manager.fill(instance.id, { name: 'Ada' }) // 'Hi Ada'
+        * ```
         */
-       export declare interface TemplatePlaceholder {
-           readonly name: string;
-           readonly path?: FieldPath;
-           readonly required?: boolean;
-           readonly fallback?: unknown;
-           readonly description?: string;
-       }
+       export declare class TemplateManager implements TemplateManagerInterface {
+           #private;
+           constructor(options?: TemplateManagerOptions);
+           get emitter(): EmitterInterface<TemplateManagerEventMap>;
+           get count(): number;
+           /**
+            * Registers a template — a constructed {@link TemplateInterface} (kept
+            * as-is) or a plain {@link TemplateOptions} bag (constructed into a
+            * `Template` with this manager's `missing` / `locale` defaults applied
+            * wherever the bag omits them).
+            *
+            * @param template - The template instance or options to register
+            * @param options - `replace` — overwrite an existing entry sharing the same id instead of throwing
+            * @returns The registered {@link TemplateInterface}
+            * @throws {@link TemplateError} Thrown when the id is already registered and `options.replace` is not `true` (coded `CONFLICT`), or when an options bag declares a duplicate placeholder `name` or an empty `path` (coded `INVALID`)
+                *
+                * @example
+                * ```ts
+                * const instance = manager.register({ id: 'greeting', name: 'greeting', content: 'Hi {{name}}' })
+                * ```
+                */
+            register(template: TemplateInterface | TemplateOptions, options?: TemplateRegisterOptions): TemplateInterface;
+            /**
+             * Returns one registered {@link TemplateInterface} by id.
+             *
+             * @param id - The template id
+             * @returns The registered {@link TemplateInterface}, or `undefined` when `id` is unregistered
+             */
+            template(id: string): TemplateInterface | undefined;
+            /**
+             * Lists every registered template.
+             *
+             * @returns A snapshot array of every registered {@link TemplateInterface}
+             */
+            templates(): readonly TemplateInterface[];
+            /**
+             * Filters registered templates by `name`, `category`, and `tag` — every
+             * supplied field must match.
+             *
+             * @param query - The {@link TemplateQuery} to filter by; omit for every registered template
+             * @returns The matching templates
+             */
+            find(query?: TemplateQuery): readonly TemplateInterface[];
+            /**
+             * Tests whether a template id is registered.
+             *
+             * @param id - The template id
+             * @returns True if `id` is registered; false otherwise
+             */
+            has(id: string): boolean;
+            /**
+             * Removes one, several, or every registered template.
+             *
+             * @remarks
+             * `remove()` removes every registered template, emitting `remove` once per
+             * instance. `remove(id)` removes one template by id, emitting `remove` and
+             * returning `true` when it existed, `false` otherwise. `remove(ids)`
+             * removes every listed id that is present, emitting `remove` once per
+             * removed instance, and returns `true` only when every listed id was
+             * present.
+             *
+             * @param target - Omit to remove all, a single id, or a list of ids
+             * @returns `boolean` for the single-id / list-of-ids forms; `void` for the remove-all form
+             */
+            remove(ids: readonly string[]): boolean;
+            remove(id: string): boolean;
+            remove(): void;
+            /** Removes every registered template, emitting `clear`. */
+            clear(): void;
+            /**
+             * Tears down the registry: drops every registered template and destroys the
+             * owned emitter. Idempotent.
+             *
+             * @remarks
+             * Teardown is not an observable registry operation and the emitter is being
+             * released, so this emits neither `clear` nor `remove`. The emitter is torn
+             * down last, after the registry is dropped.
+             *
+             * @example
+             * ```ts
+             * const manager = new TemplateManager()
+             * manager.destroy()
+             * manager.emitter.destroyed // true
+             * ```
+             */
+            destroy(): void;
+            /**
+             * Fills a registered template by id.
+             *
+             * @param id - The template id
+             * @param values - The values tokens resolve against
+             * @param options - Per-call overrides for the template's `missing` / `locale` defaults
+             * @returns The substituted content
+             * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+                 * @throws {@link TemplateError} Thrown when a required placeholder stays unresolved under the `'error'` policy (coded `MISSING`)
+                     */
+                 fill(id: string, values?: TemplateFillValues, options?: TemplateFillOptions): string;
+                 /**
+                  * Validates values against a registered template by id.
+                  *
+                  * @param id - The template id
+                  * @param values - The values to check
+                  * @returns The {@link TemplateValidationResult}
+                  * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+                      */
+                  validate(id: string, values?: TemplateFillValues): TemplateValidationResult;
+                  /**
+                   * Projects a registered template's parameters by id.
+                   *
+                   * @param id - The template id
+                   * @returns The compiled parameters record, or `undefined` when the template has none
+                   * @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+                       */
+                   parameters(id: string): Readonly<Record<string, unknown>> | undefined;
+                  }
 
-       /** A query for `TemplateManagerInterface#find` — every supplied field must match. */
-       export declare interface TemplateQuery {
-           readonly name?: string;
-           readonly category?: string;
-           readonly tag?: string;
-       }
+                  /**
+                   * Declares the push observation surface of a {@link TemplateManagerInterface}
+                   * — an id-keyed registry, so `register` / `remove` are the events (never
+                   * ordered-list `append`/`prepend`).
+                   */
+                  export declare type TemplateManagerEventMap = {
+                      /** Fires when a template is registered — carries the registered template. */
+                      readonly register: readonly [template: TemplateInterface];
+                      /** Fires when a template is removed — carries the removed template. */
+                      readonly remove: readonly [template: TemplateInterface];
+                      /** Fires when the registry is cleared. */
+                      readonly clear: readonly [];
+                  };
 
-       /** The outcome of `TemplateInterface#validate` — which required placeholders are unresolved, and which supplied values are unused. */
-       export declare interface TemplateValidationResult {
-           readonly valid: boolean;
-           readonly missing: readonly string[];
-           readonly extra: readonly string[];
-       }
+                  /**
+                   * Declares the registry contract a consumer holds — a self-owning, id-keyed
+                   * record-holder with singular and plural accessors over the templates it
+                   * registers.
+                   *
+                   * @remarks
+                   * `TemplateManager` implements this contract exactly, so the class exposes
+                   * these members and no other public behavior. The by-id calls split on what
+                   * an unknown id means to each: `template` reports its absence as `undefined`,
+                   * while `fill`, `validate`, and `parameters` throw a {@link TemplateError}
+                   * coded `NOTFOUND`, because each needs a template to proceed.
+                   */
+                  export declare interface TemplateManagerInterface {
+                      readonly emitter: EmitterInterface<TemplateManagerEventMap>;
+                      readonly count: number;
+                      /**
+                       * Registers one template, or overwrites the entry sharing its id when
+                       * `options.replace` is `true`, and emits `register`.
+                       *
+                       * @remarks
+                       * The template arrives as a constructed {@link TemplateInterface} or as a
+                       * plain {@link TemplateOptions} bag, which is constructed internally. A
+                       * duplicate id without `options.replace` throws a {@link TemplateError}
+                       * coded `CONFLICT`.
+                       */
+                      register(template: TemplateInterface | TemplateOptions, options?: TemplateRegisterOptions): TemplateInterface;
+                      /** Returns one registered template by id, or `undefined` when the id is unregistered. */
+                      template(id: string): TemplateInterface | undefined;
+                      /** Lists every registered template. */
+                      templates(): readonly TemplateInterface[];
+                      /** Filters registered templates by `name`, `category`, and `tag` — every supplied field must match. */
+                      find(query?: TemplateQuery): readonly TemplateInterface[];
+                      /** Reports whether a template with the given id is registered. */
+                      has(id: string): boolean;
+                      /**
+                       * Removes the listed templates by id, one template by id, or every
+                       * registered template, emitting `remove` once per removed template.
+                       *
+                       * @remarks
+                       * The batch form removes every present id and reports `true` only when
+                       * every listed id was present, so one absent id turns the answer `false`
+                       * while the present ids still remove. The no-argument form removes every
+                       * registered template and reports nothing.
+                       */
+                      remove(ids: readonly string[]): boolean;
+                      remove(id: string): boolean;
+                      remove(): void;
+                      /** Removes every registered template, emitting `clear`. */
+                      clear(): void;
+                      /**
+                       * Tears the registry down: drops every registered template and destroys the
+                       * owned emitter. Idempotent.
+                       *
+                       * @remarks
+                       * Teardown emits nothing, because the emitter is being released.
+                       */
+                      destroy(): void;
+                      /** Fills a registered template by id. */
+                      fill(id: string, values?: TemplateFillValues, options?: TemplateFillOptions): string;
+                      /** Validates values against a registered template by id. */
+                      validate(id: string, values?: TemplateFillValues): TemplateValidationResult;
+                      /** Projects a registered template's parameters by id. */
+                      parameters(id: string): Readonly<Record<string, unknown>> | undefined;
+                  }
 
-       /**
-        * Prototype-pollution-unsafe field-path segments — a fill lookup refuses to
-        * resolve ANY path containing one, treating the placeholder as unresolved.
-        */
-       export declare const UNSAFE_FIELD_SEGMENTS: readonly string[];
+                  /**
+                   * Carries the options for `createTemplateManager` / the `TemplateManager`
+                   * constructor.
+                   *
+                   * @remarks
+                   * `templates` seeds the registry — either constructed {@link TemplateInterface}
+                   * instances or plain {@link TemplateOptions} bags. `missing` / `locale` are
+                   * the manager-wide default {@link TemplateFillOptions}, overridable per-call.
+                   * `on` — initial event listeners. `error` — the emitter's
+                   * listener-error handler.
+                   */
+                  export declare interface TemplateManagerOptions {
+                      readonly templates?: ReadonlyArray<TemplateInterface | TemplateOptions>;
+                      readonly missing?: MissingPolicy;
+                      readonly locale?: string;
+                      readonly on?: EmitterHooks<TemplateManagerEventMap>;
+                      readonly error?: EmitterErrorHandler;
+                  }
+
+                  /**
+                   * Carries the options for `createTemplate` / the `Template` constructor.
+                   *
+                   * @remarks
+                   * `id` defaults to a generated id when omitted. `placeholders` defaults to
+                   * an empty list. `missing` / `locale` seed the instance's default
+                   * {@link TemplateFillOptions}, overridable per-call.
+                   */
+                  export declare interface TemplateOptions {
+                      readonly id?: string;
+                      readonly name: string;
+                      readonly content: string;
+                      readonly placeholders?: readonly TemplatePlaceholder[];
+                      readonly summary?: string;
+                      readonly description?: string;
+                      readonly category?: string;
+                      readonly tags?: readonly string[];
+                      readonly missing?: MissingPolicy;
+                      readonly locale?: string;
+                  }
+
+                  /**
+                   * Represents one placeholder a {@link TemplateDefinition}'s `content`
+                   * declares — its lookup name, an optional field path into the values record,
+                   * whether it is required, and a literal fallback.
+                   *
+                   * @remarks
+                   * `name` is the `{{name}}` token as written in `content`. `path`, when
+                   * present, resolves the fill value through a (possibly nested)
+                   * {@link FieldPath} rather than a flat `name` lookup on the values record.
+                   * `required` defaults to `true` when omitted — an unresolved required
+                   * placeholder is governed by the active {@link MissingPolicy}. `fallback` is
+                   * a literal substituted when the value is unresolved, regardless of
+                   * `required`.
+                   */
+                  export declare interface TemplatePlaceholder {
+                      readonly name: string;
+                      readonly path?: FieldPath;
+                      readonly required?: boolean;
+                      readonly fallback?: unknown;
+                      readonly description?: string;
+                  }
+
+                  /** Represents a query for `TemplateManagerInterface#find` — every supplied field must match. */
+                  export declare interface TemplateQuery {
+                      readonly name?: string;
+                      readonly category?: string;
+                      readonly tag?: string;
+                  }
+
+                  /**
+                   * Carries the options for `TemplateManagerInterface#register`.
+                   *
+                   * @remarks
+                   * `replace` overwrites an existing entry sharing the registered id instead of
+                   * throwing a {@link TemplateError} coded `CONFLICT`.
+                   */
+                  export declare interface TemplateRegisterOptions {
+                      readonly replace?: boolean;
+                  }
+
+                  /**
+                   * Represents one `{{name}}` token's resolution — the single token rule
+                   * `fillTemplate` and `TemplateInterface#validate` share.
+                   *
+                   * @remarks
+                   * `value` is the resolved fill value, `undefined` when the path is
+                   * unresolved or refused by the prototype-pollution guard. `declared` is the
+                   * matching {@link TemplatePlaceholder}, `undefined` for an undeclared token.
+                   * `required` is `true` for an undeclared token and for a declared
+                   * placeholder whose `required` is not `false`. A declared `fallback` is left
+                   * on `declared` rather than applied here, because `fill` substitutes it and
+                   * `validate` only counts it.
+                   */
+                  export declare interface TemplateTokenResolution {
+                      readonly value: unknown;
+                      readonly declared: TemplatePlaceholder | undefined;
+                      readonly required: boolean;
+                  }
+
+                  /** Reports the outcome of `TemplateInterface#validate` — which required placeholders are unresolved, and which supplied values are unused. */
+                  export declare interface TemplateValidationResult {
+                      readonly valid: boolean;
+                      readonly missing: readonly string[];
+                      readonly extra: readonly string[];
+                  }
+
+                  /**
+                   * Lists the prototype-pollution-unsafe field-path segments `'__proto__'`,
+                   * `'constructor'`, and `'prototype'` — a fill lookup refuses to resolve a path
+                   * containing one of them, treating the placeholder as unresolved.
+                   */
+                  export declare const UNSAFE_FIELD_SEGMENTS: readonly string[];
 
-       export { }
+                  export { }