docs(spec): IEmailService Errors lists name TEMPLATE_INVALID

.changeset/26803-email-service-template-invalid.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): `IEmailService.sendTemplate` and `renderTemplate` list `TEMPLATE_INVALID` in their Errors
+
+Clause-②: no
+Metadata-protocol: none
+
+`@objectstack/plugin-email` already refuses a stored template whose hole the authoring rules refuse (rule `email-template-hole-grammar`), throwing `TEMPLATE_INVALID: email template NAME (locale=LOCALE): HOLE_AND_RULE` from both methods. The contract's Errors lists now name that code beside `TEMPLATE_NOT_FOUND`, `TEMPLATE_INACTIVE` and `MISSING_VARIABLES`, so a channel or app author reading `IEmailService` knows the failure is permanent until the template is re-published. Documentation only: no type or schema changes.

content/docs/kernel/runtime-services/email-service.mdx

@@ -31,3 +31,4 @@ services.email.sendTemplate(input: SendTemplateInput): Promise<SendEmailResult>
 - `TEMPLATE_NOT_FOUND`
 - `TEMPLATE_INACTIVE`
 - `MISSING_VARIABLES`
+- `TEMPLATE_INVALID`: the stored template has a hole the authoring rules refuse (a second formatter, or a `currency` argument that is not a literal ISO 4217 code). It is permanent: retrying fails until the template is re-published without that hole. `renderTemplate` raises it too.

packages/spec/src/contracts/email-service.ts

@@ -318,6 +318,12 @@ export interface IEmailService {
    *   (for a call that named no locale) the name carries no members at all.
    * - `TEMPLATE_INACTIVE`  — the template exists but `active=false`.
    * - `MISSING_VARIABLES`  — declared `required` variables absent from `data`.
+   * - `TEMPLATE_INVALID`   — the stored template has a hole the authoring rules
+   *   refuse (rule `email-template-hole-grammar`: a second formatter, or a
+   *   `currency` argument that is not a literal ISO 4217 code). It is refused
+   *   at render, as `TEMPLATE_INVALID: email template <name> (locale=<l>):
+   *   <hole and rule>`, so nothing is delivered. Permanent: retrying cannot
+   *   succeed until the template is re-published without that hole.
    */
   sendTemplate(input: SendTemplateInput): Promise<SendEmailResult>;
 
@@ -337,6 +343,12 @@ export interface IEmailService {
    *   (for a call that named no locale) the name carries no members at all.
    * - `TEMPLATE_INACTIVE`  — the template exists but `active=false`.
    * - `MISSING_VARIABLES`  — declared `required` variables absent from `data`.
+   * - `TEMPLATE_INVALID`   — the stored template has a hole the authoring rules
+   *   refuse (rule `email-template-hole-grammar`: a second formatter, or a
+   *   `currency` argument that is not a literal ISO 4217 code). It is refused
+   *   at render, as `TEMPLATE_INVALID: email template <name> (locale=<l>):
+   *   <hole and rule>`, so nothing is rendered. Permanent: retrying cannot
+   *   succeed until the template is re-published without that hole.
    */
   renderTemplate(input: RenderTemplateInput): Promise<RenderTemplateResult>;