@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/http-api-binding/http-api-binding.shared.schemas.js

@@ -0,0 +1,513 @@
+/**
+ * HTTP-API persistence binding — the declaration model for resources whose rows live in a system
+ * reached over an authenticated HTTP API (`PersistenceAdapter.HTTP_API`) rather than in a
+ * platform-provisioned database.
+ *
+ * Design source of truth: `.claude/plans/etl-post-repository.md` (decisions D0/D1/D6/D9/D10,
+ * requirements R7/R12/R15/R16) plus the two companion papers
+ * `.claude/plans/etl-composite-key-synthesis.md` (key declaration + id codec) and
+ * `.claude/plans/etl-filter-dialect-scope-down.md` (declared filter/sort/search surface).
+ *
+ * The binding is a REQUIRED companion declaration on any resource configuration that selects
+ * `PersistenceAdapter.HTTP_API`. It answers, statically and per resource:
+ * - WHERE the rows live (provider + entity), and in which transport dialect they are queried;
+ * - HOW a row is identified (ordered key components → the synthesized engine-facing `_id`);
+ * - WHOSE identity reaches the target system (service principal vs per-user delegation);
+ * - HOW tenancy confinement is expressed remotely — or the explicit single-tenant stance;
+ * - WHAT the erasure story is (all three stances are first-class; none is silently defaulted);
+ * - WHICH remote-call semantics apply (timeout, retry, rate budget, id-set bound).
+ *
+ * Credentials are NEVER declared here. They resolve at runtime through
+ * `ExternalProvidersRegistryBackendService` against the `providerRef`, exactly as email, SMS and
+ * billing providers do — the binding carries only the reference (plan decision D7).
+ */
+import { z } from 'zod';
+// --------------------------------
+// Transport dialect
+// --------------------------------
+/**
+ * The query dialect the adapter speaks toward the target system. Closed vocabulary (slice 1);
+ * SOAP is a possible later member over the same HTTP transport, and a direct-database kind would
+ * be a NEW `PersistenceAdapter` member, never a dialect here.
+ */
+/** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */
+export var HttpApiTransportDialect;
+(function (HttpApiTransportDialect) {
+    /**
+     * OData v4 (SAP S/4HANA, Microsoft Dataverse/Dynamics 365): one generic client — mechanical
+     * pushdown of `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata`
+     * boot-time verification probe of the committed declaration.
+     */
+    HttpApiTransportDialect["ODATA"] = "odata";
+    /**
+     * Declared per-binding REST/JSON operation mapping (bespoke enterprise APIs). Unlike ODATA
+     * there is no generic client: each binding declares how read/list/count/search map onto
+     * concrete HTTP operations.
+     */
+    HttpApiTransportDialect["REST_JSON"] = "rest-json";
+    /**
+     * Odoo's external API (`/jsonrpc` + `execute_kw`). Promoted to its OWN dialect 2026-08-27 —
+     * D0's original "JSON-RPC is a thin envelope variant of REST_JSON" was corrected by measuring
+     * the protocol: it is generic like ODATA (no per-binding operation declarations — the model
+     * name IS `entityRef`, and read/list/count map onto `read`/`search_read`/`search_count`
+     * mechanically), but it speaks POSITIONAL arguments, its own domain filter language
+     * (`[['field','=',value], …]` with polish-notation `'|'` disjunction), and authenticates
+     * INSIDE the RPC args (`execute_kw(db, uid, api_key, …)`) rather than via HTTP headers.
+     * Forcing that through REST_JSON's declared-parameter model would have been the
+     * merge-distinct-concepts failure `design-philosophy.md` forbids.
+     *
+     * Structural constraint (schema-enforced): exactly ONE key field with the `INTEGER` codec —
+     * Odoo row ids are integers, always.
+     */
+    HttpApiTransportDialect["ODOO_JSONRPC"] = "odoo-jsonrpc";
+})(HttpApiTransportDialect || (HttpApiTransportDialect = {}));
+// --------------------------------
+// Identity mode (whose identity reaches the target)
+// --------------------------------
+/**
+ * Whose identity the adapter presents to the target system. In BOTH modes audit rows carry the
+ * REAL initiating user — the shared-principal attribution failure documented for Power Platform
+ * ("credential-sharing as a service") must not be reproduced (requirement R12).
+ *
+ * D9 ruling (Paul, 2026-08-27 — re-scoping the original "both executable in slice 1"):
+ * **SERVICE_PRINCIPAL-first.** `USER_DELEGATED` stays DECLARED and representable so bindings
+ * need no reshape when it arrives, but resolving it REFUSES naming the missing substrate: the
+ * engine has no outbound per-user token store (measured — `OAuth2_CredentialSchema` is a model
+ * with no resource, persistence or service behind it). Building that store is its own workstream.
+ */
+export var HttpApiIdentityMode;
+(function (HttpApiIdentityMode) {
+    /**
+     * One service account per binding (never shared across applications — blast-radius doctrine).
+     * Wildo's own roles/operations gate who may trigger calls. The default, and the only option
+     * when the target has no per-user OAuth surface.
+     */
+    HttpApiIdentityMode["SERVICE_PRINCIPAL"] = "service-principal";
+    /**
+     * Per-user OAuth 2.0 tokens against the target — encrypted, session-bound (the Retool model;
+     * on-behalf-of where the IdP is shared, e.g. Entra ID for Dynamics). Use when the TARGET's own
+     * authorization must decide per user: the tool can then never show a user more than the target
+     * would.
+     */
+    HttpApiIdentityMode["USER_DELEGATED"] = "user-delegated";
+})(HttpApiIdentityMode || (HttpApiIdentityMode = {}));
+// --------------------------------
+// Erasure stance (GDPR Art. 17 on rows we do not own)
+// --------------------------------
+/**
+ * The declared erasure stance of an HTTP_API-backed resource. All three stances are first-class
+ * from slice 1 (decision D6, 2026-08-26); a binding MUST declare one — an undeclared stance is a
+ * registration refusal, because `exportSubject` is a fail-closed obligation on every resource and
+ * "we cannot delete rows we do not own" is not an answer the framework may imply silently.
+ */
+export var HttpApiErasureStance;
+(function (HttpApiErasureStance) {
+    /**
+     * (6a) The resource declares it holds NO personal/subject data. Registration verifies the
+     * declaration is coherent (e.g. `exportSubject` posture) and erasure is structurally N/A for
+     * the remote rows.
+     */
+    HttpApiErasureStance["NO_SUBJECT_DATA"] = "no-subject-data";
+    /**
+     * (6b) The binding declares HOW erasure reaches the foreign system: one named API operation the
+     * engine invokes on a subject-erasure request. This is a single declared write and does NOT
+     * require general write support (slice 1 stays read-only otherwise).
+     */
+    HttpApiErasureStance["EXTERNAL_ERASURE_OPERATION"] = "external-erasure-operation";
+    /**
+     * (6c) Erasure REFUSES by default; an explicit, per-request, audited controller acknowledgement
+     * lets it proceed and records the un-erased remote rows at high severity. Mirrors the existing
+     * administrative-floor acknowledgement shape (`administrative-continuity-floors.md`): the record
+     * is the control. NEVER a standing default — the acknowledgement is per erasure request.
+     */
+    HttpApiErasureStance["CONTROLLER_ACKNOWLEDGED_NON_ERASURE"] = "controller-acknowledged-non-erasure";
+})(HttpApiErasureStance || (HttpApiErasureStance = {}));
+// --------------------------------
+// Tenancy stance
+// --------------------------------
+/**
+ * How tenant confinement is enforced against the remote system (requirements R4/R16).
+ */
+export var HttpApiTenancyStance;
+(function (HttpApiTenancyStance) {
+    /**
+     * The engine's contextual scope predicate is pushed down into every remote query against a
+     * declared remote field. Registration REFUSES a binding whose declared surface cannot express
+     * the scope predicate — a query-time refusal would be a data leak one missed branch away.
+     */
+    HttpApiTenancyStance["SCOPE_FILTER_PUSHDOWN"] = "scope-filter-pushdown";
+    /**
+     * The binding declares the target system serves exactly ONE tenant (the normal case for an
+     * internal tool on one enterprise's IS). Scope pushdown is then N/A by declaration — an
+     * explicit, audited stance, never an inferred one (R16).
+     */
+    HttpApiTenancyStance["SINGLE_TENANT_BINDING"] = "single-tenant-binding";
+})(HttpApiTenancyStance || (HttpApiTenancyStance = {}));
+// --------------------------------
+// Key declaration + component codecs (paper A)
+// --------------------------------
+/**
+ * Per-component value normalization for key synthesis. The codec is what makes the synthesized
+ * `_id` STABLE: every component must round-trip byte-identically between the remote
+ * representation and the encoded id, or the same remote row would answer to different ids.
+ *
+ * `INTEGER` and `GUID` are the two codecs whose entire value space is URL-unreserved-safe, which
+ * is what qualifies a single-key binding for the VERBATIM id form (see
+ * `httpApiBindingUsesVerbatimKey`).
+ */
+export var HttpApiKeyComponentCodec;
+(function (HttpApiKeyComponentCodec) {
+    /** Arbitrary remote string. NOT charset-safe → always participates via the encoded id form. */
+    HttpApiKeyComponentCodec["STRING"] = "string";
+    /** Integer key (Odoo `id`, SAP numeric keys). Digits only → verbatim-eligible. */
+    HttpApiKeyComponentCodec["INTEGER"] = "integer";
+    /** GUID/UUID key (Dataverse row ids). Hex + dashes → verbatim-eligible. */
+    HttpApiKeyComponentCodec["GUID"] = "guid";
+    /**
+     * Date/time key component, normalized to the RFC 3339 / ISO 8601 UTC string form before
+     * encoding. NOT verbatim-eligible (`:` is forbidden in ids — websocket room names are
+     * colon-parsed).
+     */
+    HttpApiKeyComponentCodec["DATETIME_ISO"] = "datetime-iso";
+})(HttpApiKeyComponentCodec || (HttpApiKeyComponentCodec = {}));
+/** @wildo_source:part:end saas.models.http-api-binding */
+/**
+ * One ordered component of the remote entity's key. `keyFields` order is the ENCODING order —
+ * declared, committed, and boot-verified against `$metadata` where the dialect provides one;
+ * never inferred at runtime (a silently adopted key change would orphan every stored FK value
+ * and bookmark).
+ */
+export const HttpApiKeyFieldSchema = z.object({
+    /** The field name on the Wildo resource schema that carries this component. */
+    localField: z.string().min(1),
+    /** The remote entity's property name for this component. */
+    remoteField: z.string().min(1),
+    /** Value normalization for stable synthesis. */
+    codec: z.enum(HttpApiKeyComponentCodec),
+});
+// --------------------------------
+// Field mapping
+// --------------------------------
+/**
+ * Local-to-remote field name mapping for fields whose names differ. Fields not listed map by
+ * identity (same name both sides). Key components are declared in `keyFields`, not here.
+ */
+export const HttpApiFieldMappingSchema = z.object({
+    localField: z.string().min(1),
+    remoteField: z.string().min(1),
+});
+// --------------------------------
+// Remote-call semantics (decision D10 / requirement R15)
+// --------------------------------
+/**
+ * Declared remote-call semantics. An enterprise API is 100ms–2s, rate-limited, and sometimes
+ * down; these are DECISIONS, not inherited pipeline defaults. Defaults are conservative on
+ * purpose — a binding that needs more declares more.
+ */
+export const HttpApiRemoteCallSemanticsSchema = z.object({
+    /** Per-call timeout. */
+    timeoutMs: z.number().int().positive().max(120_000).default(10_000),
+    /**
+     * Retry policy for idempotent READ-family calls only. Writes (when D4 lands) never retry
+     * implicitly.
+     */
+    retry: z
+        .object({
+        maxAttempts: z.number().int().min(1).max(5).default(2),
+        backoffMs: z.number().int().positive().max(30_000).default(500),
+    })
+        .default({ maxAttempts: 2, backoffMs: 500 }),
+    /**
+     * Rate budget toward the target, per process. `undefined` = no local throttle (the target's own
+     * limits still apply and surface as refusals).
+     */
+    maxRequestsPerMinute: z.number().int().positive().optional(),
+    /**
+     * Upper bound for translated id-set predicates (`_id ∈ {…}` → key-predicate disjunction /
+     * `in`). Above the bound the adapter REFUSES rather than emitting an unbounded URL
+     * (scope-down paper, shape T2).
+     */
+    maxIdSetSize: z.number().int().positive().max(500).default(50),
+});
+// --------------------------------
+// Dialect-specific declarations
+// --------------------------------
+/**
+ * HTTP methods a declared read-family operation may use. Deliberately NOT the full HTTP verb set
+ * (`API_HttpMethod` in `@wildo-ai/external-connectors-models` describes provider-protocol
+ * operations): slice 1 is read-only, so the closed vocabulary is the read-safe verb plus POST —
+ * because JSON-RPC (Odoo) and many enterprise search endpoints are POST-shaped even for reads.
+ * Write verbs (PUT/PATCH/DELETE) enter only with the D4 write story, as their own decision.
+ */
+export var HttpApiRestOperationMethod;
+(function (HttpApiRestOperationMethod) {
+    HttpApiRestOperationMethod["GET"] = "GET";
+    HttpApiRestOperationMethod["POST"] = "POST";
+})(HttpApiRestOperationMethod || (HttpApiRestOperationMethod = {}));
+/**
+ * REST_JSON per-operation declaration: how one read-family member maps onto a concrete HTTP
+ * operation. Deliberately minimal in slice 1 — pagination/filter parameter NAMES are declared,
+ * their VALUES are supplied by the adapter from the translated query.
+ *
+ * Related but distinct: `REST_API_OperationSpecSchema` in `@wildo-ai/external-connectors-models`
+ * describes provider-protocol operations for capability transformers. This schema describes a
+ * RESOURCE read surface; if the two converge later that is a recorded decision, not an implicit
+ * merge of distinct concepts.
+ */
+export const HttpApiRestOperationSpecSchema = z.object({
+    /** HTTP method for this read-family operation. */
+    method: z.enum(HttpApiRestOperationMethod),
+    /**
+     * Path template relative to the provider's base URL. `{key}` interpolates the synthesized
+     * key's remote addressing form; other `{param}` tokens must be declared parameter names.
+     */
+    pathTemplate: z.string().min(1),
+    /** Query/body parameter names for pagination, when the operation supports it. */
+    pagingParams: z
+        .object({
+        limitParam: z.string().min(1),
+        offsetParam: z.string().min(1),
+    })
+        .optional(),
+    /**
+     * Declared filter parameter name per LOCAL field. Only fields listed here are translatable for
+     * this operation (scope-down paper, shape T3); everything else is refused at the adapter
+     * boundary.
+     */
+    filterParams: z.record(z.string().min(1), z.string().min(1)).optional(),
+    /**
+     * The parameter that receives the SEARCH text (T4), for a `search` operation. Absent =
+     * search is refused for this binding even when the operation exists.
+     */
+    searchParam: z.string().min(1).optional(),
+    /**
+     * Dot-path to the payload inside the response body — the rows array (list/search), the entity
+     * object (read), or the number (count). Absent = the body IS the payload. Declared, never
+     * sniffed: response shapes vary per target (`items`, `result`, `value`, raw array) and a wrong
+     * guess would silently read zero rows.
+     */
+    resultPath: z.string().min(1).optional(),
+    /** Wrap request/response in a JSON-RPC 2.0 envelope (the Odoo variant). */
+    jsonRpcEnvelope: z
+        .object({
+        rpcMethod: z.string().min(1),
+    })
+        .optional(),
+});
+/** The REST_JSON read-surface mapping: which lifecycle members exist remotely, and how. */
+export const HttpApiRestOperationsSchema = z.object({
+    read: HttpApiRestOperationSpecSchema,
+    list: HttpApiRestOperationSpecSchema,
+    /** Absent = COUNT is refused for this binding (honest refusal, never an emulated scan). */
+    count: HttpApiRestOperationSpecSchema.optional(),
+    /** Absent = SEARCH is refused for this binding. */
+    search: HttpApiRestOperationSpecSchema.optional(),
+});
+// --------------------------------
+// Stance sub-declarations
+// --------------------------------
+/** Tenancy declaration — discriminated so each stance carries exactly its own obligations. */
+export const HttpApiTenancyDeclarationSchema = z.discriminatedUnion('stance', [
+    z.object({
+        stance: z.literal(HttpApiTenancyStance.SCOPE_FILTER_PUSHDOWN),
+        /** The remote field the engine's tenant-scope predicate is pushed down against. */
+        remoteScopeField: z.string().min(1),
+    }),
+    z.object({
+        stance: z.literal(HttpApiTenancyStance.SINGLE_TENANT_BINDING),
+        /** Why this binding is single-tenant — recorded, audited justification (R16). */
+        justification: z.string().min(1),
+    }),
+]);
+/**
+ * HTTP methods a declared EXPLICIT erasure operation (stance 6b, REST_JSON) may use.
+ *
+ * A separate vocabulary from {@link HttpApiRestOperationMethod} on purpose: that enum describes
+ * READ-family operations (GET/POST), and reusing it here would let an erasure declare `GET` — a
+ * read spelled as a deletion. Deletion is expressed as the resource-oriented `DELETE` or an
+ * RPC-style `POST`; nothing else is a deletion on the wire.
+ */
+export var HttpApiErasureOperationMethod;
+(function (HttpApiErasureOperationMethod) {
+    HttpApiErasureOperationMethod["POST"] = "POST";
+    HttpApiErasureOperationMethod["DELETE"] = "DELETE";
+})(HttpApiErasureOperationMethod || (HttpApiErasureOperationMethod = {}));
+/**
+ * The EXPLICIT erasure call a REST_JSON binding declares for stance 6b. Deliberately narrower
+ * than {@link HttpApiRestOperationSpecSchema}: an erasure addresses ONE row by key — it has no
+ * pagination, no filter params, no search, no result path to project.
+ */
+export const HttpApiErasureOperationSpecSchema = z.object({
+    method: z.enum(HttpApiErasureOperationMethod),
+    /**
+     * Path template relative to the provider base URL. `{key}` interpolates the row's remote key
+     * addressing form, exactly as in the read-family `pathTemplate`.
+     */
+    pathTemplate: z.string().min(1),
+    /**
+     * JSON-RPC envelope for RPC-style targets (pairs with `method: POST`), mirroring the
+     * read-family declaration.
+     */
+    jsonRpcEnvelope: z.object({ rpcMethod: z.string().min(1) }).optional(),
+});
+/** Erasure declaration — discriminated; stance 6b names the operation it invokes. */
+export const HttpApiErasureDeclarationSchema = z.discriminatedUnion('stance', [
+    z.object({
+        stance: z.literal(HttpApiErasureStance.NO_SUBJECT_DATA),
+    }),
+    z.object({
+        stance: z.literal(HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION),
+        /**
+         * The declared erasure call. ODATA and ODOO_JSONRPC bindings rely on their CANONICAL delete
+         * (`DELETE /EntitySet(key)` / `execute_kw('unlink', [[ids]])`) by declaring
+         * `useCanonicalDelete`; REST_JSON bindings declare the operation explicitly. The pairing is
+         * enforced by {@link assertHttpApiBindingDialectCoherence}.
+         */
+        operation: z.union([
+            z.object({ useCanonicalDelete: z.literal(true) }),
+            HttpApiErasureOperationSpecSchema,
+        ]),
+        /**
+         * The LOCAL field naming the DATA SUBJECT whose erasure deletes a remote row — the rows the
+         * declared operation applies to are exactly `{ [subjectLinkLocalField]: <erased subject id> }`.
+         *
+         * DECLARED, never inferred, for the same reason `dataSubjectPolicy` exists on retention: a
+         * foreign key usually names an OWNER or an ACTOR, not the subject — inferring from "any FK to
+         * the erased user" would delete a purchase-order row because the erased user merely CREATED
+         * it, destroying a business record no erasure asked for. One field, mirroring
+         * `sessionPrincipalField`'s "one field names the person". Registration verifies a declared
+         * relationship carries this field as its FK (so the subject type it links is known).
+         */
+        subjectLinkLocalField: z.string().trim().min(1),
+    }),
+    z.object({
+        stance: z.literal(HttpApiErasureStance.CONTROLLER_ACKNOWLEDGED_NON_ERASURE),
+        /**
+         * Optional evidence link: the LOCAL field naming the data subject, used ONLY to COUNT the
+         * remaining remote rows for the acknowledgement's CRITICAL audit record (`remainingRowCount`).
+         * Optional because 6c legitimately covers linkage no FK expresses (an email inside remote
+         * rows) — absent, the record carries no count rather than a fabricated zero. Never used to
+         * delete anything.
+         */
+        subjectLinkLocalField: z.string().trim().min(1).optional(),
+    }),
+]);
+// --------------------------------
+// The binding declaration
+// --------------------------------
+const httpApiResourceBindingBaseShape = {
+    /**
+     * The external provider whose declared protocol configuration carries the base URL and whose
+     * credentials resolve through `ExternalProvidersRegistryBackendService` (decision D7 — no new
+     * secret store, no connection string on the resource config).
+     */
+    providerRef: z.string().min(1),
+    /**
+     * The remote entity addressed by this binding — an OData entity-set name, or a logical name for
+     * a REST_JSON surface. One binding, one remote entity set.
+     */
+    entityRef: z.string().min(1),
+    /** Whose identity reaches the target (D9). */
+    identityMode: z.enum(HttpApiIdentityMode).default(HttpApiIdentityMode.SERVICE_PRINCIPAL),
+    /** Ordered key declaration — the source of the synthesized engine-facing `_id` (paper A). */
+    keyFields: z.array(HttpApiKeyFieldSchema).min(1),
+    /** Non-key field name mappings; unlisted fields map by identity. */
+    fieldMappings: z.array(HttpApiFieldMappingSchema).default([]),
+    /** Tenancy stance (R4/R16). */
+    tenancy: HttpApiTenancyDeclarationSchema,
+    /** Erasure stance (D6) — required; no silent default. */
+    erasure: HttpApiErasureDeclarationSchema,
+    /** Remote-call semantics (D10/R15). */
+    remoteCallSemantics: HttpApiRemoteCallSemanticsSchema.default({
+        timeoutMs: 10_000,
+        retry: { maxAttempts: 2, backoffMs: 500 },
+        maxIdSetSize: 50,
+    }),
+};
+/**
+ * The HTTP_API resource binding — discriminated on the transport dialect so each dialect carries
+ * exactly its own obligations: ODATA is generic (plus an optional `$metadata` probe opt-out for
+ * targets that do not serve one); REST_JSON must declare its whole read surface.
+ */
+/** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */
+export const HttpApiResourceBindingSchema = z.discriminatedUnion('dialect', [
+    z.object({
+        dialect: z.literal(HttpApiTransportDialect.ODATA),
+        ...httpApiResourceBindingBaseShape,
+        /**
+         * Verify the committed declaration against the live `$metadata` at boot (decision D5 —
+         * drift is detected at boot and the fix is re-authoring, never silent adaptation). Opt out
+         * only for targets that genuinely do not serve `$metadata`.
+         */
+        verifyMetadataAtBoot: z.boolean().default(true),
+    }),
+    z.object({
+        dialect: z.literal(HttpApiTransportDialect.REST_JSON),
+        ...httpApiResourceBindingBaseShape,
+        /** The declared read surface — absent members are refused, never emulated. */
+        operations: HttpApiRestOperationsSchema,
+    }),
+    z.object({
+        dialect: z.literal(HttpApiTransportDialect.ODOO_JSONRPC),
+        ...httpApiResourceBindingBaseShape,
+        // Generic like ODATA — no per-binding operation declarations: `entityRef` is the Odoo model
+        // (e.g. 'res.partner'); read/list/count map onto read/search_read/search_count mechanically.
+        // The single-INTEGER-key constraint is enforced by `assertHttpApiBindingDialectCoherence`
+        // (called by the resource-configuration factory) — a refine here would wrap the union member
+        // in effects, which discriminated unions do not admit.
+    }),
+]);
+/**
+ * Dialect-specific structural constraints that a discriminated union cannot express member-side.
+ * Called by the resource-configuration factory AFTER the schema parse; throws with the offending
+ * path named.
+ */
+export function assertHttpApiBindingDialectCoherence(binding) {
+    if (binding.dialect === HttpApiTransportDialect.ODOO_JSONRPC) {
+        // Odoo row ids are INTEGERS, always — one key field, INTEGER codec, or the synthesized id
+        // could never address a row.
+        if (binding.keyFields.length !== 1
+            || binding.keyFields[0].codec !== HttpApiKeyComponentCodec.INTEGER) {
+            throw new Error("keyFields: an ODOO_JSONRPC binding must declare exactly one key field with the INTEGER codec — Odoo row ids are integers ('id').");
+        }
+    }
+    // D6 stance 6b — the declared erasure operation's FORM is dialect-specific. The union schema
+    // admits both forms; only the pairing below is executable, so an incoherent pairing must refuse
+    // at authoring rather than on the first subject-erasure request:
+    //   - ODATA        → `useCanonicalDelete` only (the canonical `DELETE /EntitySet(key)`);
+    //   - ODOO_JSONRPC → `useCanonicalDelete` only (compiles to `execute_kw('unlink', [[ids]])`,
+    //                    Odoo's own canonical delete);
+    //   - REST_JSON    → an explicit operation spec only (there IS no canonical delete to rely on —
+    //                    the binding declares the exact call, like every other REST_JSON operation).
+    if (binding.erasure.stance === HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION) {
+        const usesCanonicalDelete = 'useCanonicalDelete' in binding.erasure.operation;
+        if (binding.dialect === HttpApiTransportDialect.REST_JSON && usesCanonicalDelete) {
+            throw new Error('erasure.operation: a REST_JSON binding has no canonical delete — declare the explicit erasure operation spec (method/path), like its other declared operations.');
+        }
+        if (binding.dialect !== HttpApiTransportDialect.REST_JSON && !usesCanonicalDelete) {
+            throw new Error(`erasure.operation: a ${binding.dialect} binding executes erasure through its CANONICAL delete (declare { useCanonicalDelete: true }) — an explicit REST operation spec has no translation on this dialect.`);
+        }
+    }
+}
+// --------------------------------
+// Static binding properties
+// --------------------------------
+/**
+ * Codecs whose ENTIRE value space stays within the synthesized-id charset law
+ * (`^[A-Za-z0-9._~-]+$`, see `http-api-binding-id.shared.utils.ts`). Membership here is what
+ * qualifies a single-key binding for the verbatim id form.
+ */
+const VERBATIM_ELIGIBLE_CODECS = [
+    HttpApiKeyComponentCodec.INTEGER,
+    HttpApiKeyComponentCodec.GUID,
+];
+/**
+ * Whether this binding's synthesized `_id` is the single key value VERBATIM (legible ids for
+ * Dataverse GUIDs / Odoo integers) versus the encoded composite form. A STATIC property of the
+ * declaration — never sniffed per row — which is what keeps decode unambiguous (paper A).
+ */
+export function httpApiBindingUsesVerbatimKey(binding) {
+    return (binding.keyFields.length === 1
+        && VERBATIM_ELIGIBLE_CODECS.includes(binding.keyFields[0].codec));
+}
+//# sourceMappingURL=http-api-binding.shared.schemas.js.map

package/dist/esm/http-api-binding/http-api-binding.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-binding.shared.schemas.js","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-binding.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,mCAAmC;AACnC,oBAAoB;AACpB,mCAAmC;AAEnC;;;;GAIG;AACH,4GAA4G;AAC5G,MAAM,CAAN,IAAY,uBA8BX;AA9BD,WAAY,uBAAuB;IACjC;;;;OAIG;IACH,0CAAe,CAAA;IAEf;;;;OAIG;IACH,kDAAuB,CAAA;IAEvB;;;;;;;;;;;;;OAaG;IACH,wDAA6B,CAAA;AAC/B,CAAC,EA9BW,uBAAuB,KAAvB,uBAAuB,QA8BlC;AAED,mCAAmC;AACnC,oDAAoD;AACpD,mCAAmC;AAEnC;;;;;;;;;;GAUG;AACH,MAAM,CAAN,IAAY,mBAeX;AAfD,WAAY,mBAAmB;IAC7B;;;;OAIG;IACH,8DAAuC,CAAA;IAEvC;;;;;OAKG;IACH,wDAAiC,CAAA;AACnC,CAAC,EAfW,mBAAmB,KAAnB,mBAAmB,QAe9B;AAED,mCAAmC;AACnC,sDAAsD;AACtD,mCAAmC;AAEnC;;;;;GAKG;AACH,MAAM,CAAN,IAAY,oBAsBX;AAtBD,WAAY,oBAAoB;IAC9B;;;;OAIG;IACH,2DAAmC,CAAA;IAEnC;;;;OAIG;IACH,iFAAyD,CAAA;IAEzD;;;;;OAKG;IACH,mGAA2E,CAAA;AAC7E,CAAC,EAtBW,oBAAoB,KAApB,oBAAoB,QAsB/B;AAED,mCAAmC;AACnC,iBAAiB;AACjB,mCAAmC;AAEnC;;GAEG;AACH,MAAM,CAAN,IAAY,oBAcX;AAdD,WAAY,oBAAoB;IAC9B;;;;OAIG;IACH,uEAA+C,CAAA;IAE/C;;;;OAIG;IACH,uEAA+C,CAAA;AACjD,CAAC,EAdW,oBAAoB,KAApB,oBAAoB,QAc/B;AAED,mCAAmC;AACnC,+CAA+C;AAC/C,mCAAmC;AAEnC;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,wBAgBX;AAhBD,WAAY,wBAAwB;IAClC,+FAA+F;IAC/F,6CAAiB,CAAA;IAEjB,kFAAkF;IAClF,+CAAmB,CAAA;IAEnB,2EAA2E;IAC3E,yCAAa,CAAA;IAEb;;;;OAIG;IACH,yDAA6B,CAAA;AAC/B,CAAC,EAhBW,wBAAwB,KAAxB,wBAAwB,QAgBnC;AACD,0DAA0D;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,+EAA+E;IAC/E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE7B,4DAA4D;IAC5D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE9B,gDAAgD;IAChD,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC;CACxC,CAAC,CAAC;AAIH,mCAAmC;AACnC,gBAAgB;AAChB,mCAAmC;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC/B,CAAC,CAAC;AAIH,mCAAmC;AACnC,yDAAyD;AACzD,mCAAmC;AAEnC;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC;IACvD,wBAAwB;IACxB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IAEnE;;;OAGG;IACH,KAAK,EAAE,CAAC;SACL,MAAM,CAAC;QACN,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QACtD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;KAChE,CAAC;SACD,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IAE9C;;;OAGG;IACH,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAE5D;;;;OAIG;IACH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC/D,CAAC,CAAC;AAIH,mCAAmC;AACnC,gCAAgC;AAChC,mCAAmC;AAEnC;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,0BAGX;AAHD,WAAY,0BAA0B;IACpC,yCAAW,CAAA;IACX,2CAAa,CAAA;AACf,CAAC,EAHW,0BAA0B,KAA1B,0BAA0B,QAGrC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IACrD,kDAAkD;IAClD,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC;IAE1C;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE/B,iFAAiF;IACjF,YAAY,EAAE,CAAC;SACZ,MAAM,CAAC;QACN,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KAC/B,CAAC;SACD,QAAQ,EAAE;IAEb;;;;OAIG;IACH,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEvE;;;OAGG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEzC;;;;;OAKG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAExC,2EAA2E;IAC3E,eAAe,EAAE,CAAC;SACf,MAAM,CAAC;QACN,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KAC7B,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAIH,2FAA2F;AAC3F,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,8BAA8B;IACpC,IAAI,EAAE,8BAA8B;IACpC,2FAA2F;IAC3F,KAAK,EAAE,8BAA8B,CAAC,QAAQ,EAAE;IAChD,mDAAmD;IACnD,MAAM,EAAE,8BAA8B,CAAC,QAAQ,EAAE;CAClD,CAAC,CAAC;AAIH,mCAAmC;AACnC,0BAA0B;AAC1B,mCAAmC;AAEnC,8FAA8F;AAC9F,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE;IAC5E,CAAC,CAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,qBAAqB,CAAC;QAC7D,mFAAmF;QACnF,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KACpC,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,qBAAqB,CAAC;QAC7D,iFAAiF;QACjF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KACjC,CAAC;CACH,CAAC,CAAC;AAIH;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,6BAGX;AAHD,WAAY,6BAA6B;IACvC,8CAAa,CAAA;IACb,kDAAiB,CAAA;AACnB,CAAC,EAHW,6BAA6B,KAA7B,6BAA6B,QAGxC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,6BAA6B,CAAC;IAE7C;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE/B;;;OAGG;IACH,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvE,CAAC,CAAC;AAIH,qFAAqF;AACrF,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE;IAC5E,CAAC,CAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,eAAe,CAAC;KACxD,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,0BAA0B,CAAC;QAClE;;;;;WAKG;QACH,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC;YACjB,CAAC,CAAC,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACjD,iCAAiC;SAClC,CAAC;QACF;;;;;;;;;;WAUG;QACH,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KAChD,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,mCAAmC,CAAC;QAC3E;;;;;;WAMG;QACH,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;KAC3D,CAAC;CACH,CAAC,CAAC;AAIH,mCAAmC;AACnC,0BAA0B;AAC1B,mCAAmC;AAEnC,MAAM,+BAA+B,GAAG;IACtC;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE9B;;;OAGG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE5B,8CAA8C;IAC9C,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,iBAAiB,CAAC;IAExF,6FAA6F;IAC7F,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAEhD,oEAAoE;IACpE,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAE7D,+BAA+B;IAC/B,OAAO,EAAE,+BAA+B;IAExC,yDAAyD;IACzD,OAAO,EAAE,+BAA+B;IAExC,uCAAuC;IACvC,mBAAmB,EAAE,gCAAgC,CAAC,OAAO,CAAC;QAC5D,SAAS,EAAE,MAAM;QACjB,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;QACzC,YAAY,EAAE,EAAE;KACjB,CAAC;CACH,CAAC;AAEF;;;;GAIG;AACH,4GAA4G;AAC5G,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;IAC1E,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,uBAAuB,CAAC,KAAK,CAAC;QACjD,GAAG,+BAA+B;QAClC;;;;WAIG;QACH,oBAAoB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;KAChD,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,uBAAuB,CAAC,SAAS,CAAC;QACrD,GAAG,+BAA+B;QAClC,8EAA8E;QAC9E,UAAU,EAAE,2BAA2B;KACxC,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,uBAAuB,CAAC,YAAY,CAAC;QACxD,GAAG,+BAA+B;QAClC,4FAA4F;QAC5F,6FAA6F;QAC7F,0FAA0F;QAC1F,6FAA6F;QAC7F,uDAAuD;KACxD,CAAC;CACH,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,oCAAoC,CAAC,OAA+B;IAClF,IAAI,OAAO,CAAC,OAAO,KAAK,uBAAuB,CAAC,YAAY,EAAE,CAAC;QAC7D,0FAA0F;QAC1F,6BAA6B;QAC7B,IACE,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;eAC3B,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,wBAAwB,CAAC,OAAO,EAClE,CAAC;YACD,MAAM,IAAI,KAAK,CACb,kIAAkI,CACnI,CAAC;QACJ,CAAC;IACH,CAAC;IAED,6FAA6F;IAC7F,gGAAgG;IAChG,iEAAiE;IACjE,yFAAyF;IACzF,6FAA6F;IAC7F,mDAAmD;IACnD,gGAAgG;IAChG,iGAAiG;IACjG,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,oBAAoB,CAAC,0BAA0B,EAAE,CAAC;QAC/E,MAAM,mBAAmB,GAAG,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;QAC9E,IAAI,OAAO,CAAC,OAAO,KAAK,uBAAuB,CAAC,SAAS,IAAI,mBAAmB,EAAE,CAAC;YACjF,MAAM,IAAI,KAAK,CACb,iKAAiK,CAClK,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,KAAK,uBAAuB,CAAC,SAAS,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAClF,MAAM,IAAI,KAAK,CACb,wBAAwB,OAAO,CAAC,OAAO,qKAAqK,CAC7M,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAKD,mCAAmC;AACnC,4BAA4B;AAC5B,mCAAmC;AAEnC;;;;GAIG;AACH,MAAM,wBAAwB,GAAwC;IACpE,wBAAwB,CAAC,OAAO;IAChC,wBAAwB,CAAC,IAAI;CAC9B,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,OAAkD;IAElD,OAAO,CACL,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;WAC3B,wBAAwB,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CACjE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * HTTP-API persistence binding — the declaration model for resources whose rows live in a system\n * reached over an authenticated HTTP API (`PersistenceAdapter.HTTP_API`) rather than in a\n * platform-provisioned database.\n *\n * Design source of truth: `.claude/plans/etl-post-repository.md` (decisions D0/D1/D6/D9/D10,\n * requirements R7/R12/R15/R16) plus the two companion papers\n * `.claude/plans/etl-composite-key-synthesis.md` (key declaration + id codec) and\n * `.claude/plans/etl-filter-dialect-scope-down.md` (declared filter/sort/search surface).\n *\n * The binding is a REQUIRED companion declaration on any resource configuration that selects\n * `PersistenceAdapter.HTTP_API`. It answers, statically and per resource:\n * - WHERE the rows live (provider + entity), and in which transport dialect they are queried;\n * - HOW a row is identified (ordered key components → the synthesized engine-facing `_id`);\n * - WHOSE identity reaches the target system (service principal vs per-user delegation);\n * - HOW tenancy confinement is expressed remotely — or the explicit single-tenant stance;\n * - WHAT the erasure story is (all three stances are first-class; none is silently defaulted);\n * - WHICH remote-call semantics apply (timeout, retry, rate budget, id-set bound).\n *\n * Credentials are NEVER declared here. They resolve at runtime through\n * `ExternalProvidersRegistryBackendService` against the `providerRef`, exactly as email, SMS and\n * billing providers do — the binding carries only the reference (plan decision D7).\n */\n\nimport { z } from 'zod';\n\n// --------------------------------\n// Transport dialect\n// --------------------------------\n\n/**\n * The query dialect the adapter speaks toward the target system. Closed vocabulary (slice 1);\n * SOAP is a possible later member over the same HTTP transport, and a direct-database kind would\n * be a NEW `PersistenceAdapter` member, never a dialect here.\n */\n/** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */\nexport enum HttpApiTransportDialect {\n  /**\n   * OData v4 (SAP S/4HANA, Microsoft Dataverse/Dynamics 365): one generic client — mechanical\n   * pushdown of `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata`\n   * boot-time verification probe of the committed declaration.\n   */\n  ODATA = 'odata',\n\n  /**\n   * Declared per-binding REST/JSON operation mapping (bespoke enterprise APIs). Unlike ODATA\n   * there is no generic client: each binding declares how read/list/count/search map onto\n   * concrete HTTP operations.\n   */\n  REST_JSON = 'rest-json',\n\n  /**\n   * Odoo's external API (`/jsonrpc` + `execute_kw`). Promoted to its OWN dialect 2026-08-27 —\n   * D0's original \"JSON-RPC is a thin envelope variant of REST_JSON\" was corrected by measuring\n   * the protocol: it is generic like ODATA (no per-binding operation declarations — the model\n   * name IS `entityRef`, and read/list/count map onto `read`/`search_read`/`search_count`\n   * mechanically), but it speaks POSITIONAL arguments, its own domain filter language\n   * (`[['field','=',value], …]` with polish-notation `'|'` disjunction), and authenticates\n   * INSIDE the RPC args (`execute_kw(db, uid, api_key, …)`) rather than via HTTP headers.\n   * Forcing that through REST_JSON's declared-parameter model would have been the\n   * merge-distinct-concepts failure `design-philosophy.md` forbids.\n   *\n   * Structural constraint (schema-enforced): exactly ONE key field with the `INTEGER` codec —\n   * Odoo row ids are integers, always.\n   */\n  ODOO_JSONRPC = 'odoo-jsonrpc',\n}\n\n// --------------------------------\n// Identity mode (whose identity reaches the target)\n// --------------------------------\n\n/**\n * Whose identity the adapter presents to the target system. In BOTH modes audit rows carry the\n * REAL initiating user — the shared-principal attribution failure documented for Power Platform\n * (\"credential-sharing as a service\") must not be reproduced (requirement R12).\n *\n * D9 ruling (Paul, 2026-08-27 — re-scoping the original \"both executable in slice 1\"):\n * **SERVICE_PRINCIPAL-first.** `USER_DELEGATED` stays DECLARED and representable so bindings\n * need no reshape when it arrives, but resolving it REFUSES naming the missing substrate: the\n * engine has no outbound per-user token store (measured — `OAuth2_CredentialSchema` is a model\n * with no resource, persistence or service behind it). Building that store is its own workstream.\n */\nexport enum HttpApiIdentityMode {\n  /**\n   * One service account per binding (never shared across applications — blast-radius doctrine).\n   * Wildo's own roles/operations gate who may trigger calls. The default, and the only option\n   * when the target has no per-user OAuth surface.\n   */\n  SERVICE_PRINCIPAL = 'service-principal',\n\n  /**\n   * Per-user OAuth 2.0 tokens against the target — encrypted, session-bound (the Retool model;\n   * on-behalf-of where the IdP is shared, e.g. Entra ID for Dynamics). Use when the TARGET's own\n   * authorization must decide per user: the tool can then never show a user more than the target\n   * would.\n   */\n  USER_DELEGATED = 'user-delegated',\n}\n\n// --------------------------------\n// Erasure stance (GDPR Art. 17 on rows we do not own)\n// --------------------------------\n\n/**\n * The declared erasure stance of an HTTP_API-backed resource. All three stances are first-class\n * from slice 1 (decision D6, 2026-08-26); a binding MUST declare one — an undeclared stance is a\n * registration refusal, because `exportSubject` is a fail-closed obligation on every resource and\n * \"we cannot delete rows we do not own\" is not an answer the framework may imply silently.\n */\nexport enum HttpApiErasureStance {\n  /**\n   * (6a) The resource declares it holds NO personal/subject data. Registration verifies the\n   * declaration is coherent (e.g. `exportSubject` posture) and erasure is structurally N/A for\n   * the remote rows.\n   */\n  NO_SUBJECT_DATA = 'no-subject-data',\n\n  /**\n   * (6b) The binding declares HOW erasure reaches the foreign system: one named API operation the\n   * engine invokes on a subject-erasure request. This is a single declared write and does NOT\n   * require general write support (slice 1 stays read-only otherwise).\n   */\n  EXTERNAL_ERASURE_OPERATION = 'external-erasure-operation',\n\n  /**\n   * (6c) Erasure REFUSES by default; an explicit, per-request, audited controller acknowledgement\n   * lets it proceed and records the un-erased remote rows at high severity. Mirrors the existing\n   * administrative-floor acknowledgement shape (`administrative-continuity-floors.md`): the record\n   * is the control. NEVER a standing default — the acknowledgement is per erasure request.\n   */\n  CONTROLLER_ACKNOWLEDGED_NON_ERASURE = 'controller-acknowledged-non-erasure',\n}\n\n// --------------------------------\n// Tenancy stance\n// --------------------------------\n\n/**\n * How tenant confinement is enforced against the remote system (requirements R4/R16).\n */\nexport enum HttpApiTenancyStance {\n  /**\n   * The engine's contextual scope predicate is pushed down into every remote query against a\n   * declared remote field. Registration REFUSES a binding whose declared surface cannot express\n   * the scope predicate — a query-time refusal would be a data leak one missed branch away.\n   */\n  SCOPE_FILTER_PUSHDOWN = 'scope-filter-pushdown',\n\n  /**\n   * The binding declares the target system serves exactly ONE tenant (the normal case for an\n   * internal tool on one enterprise's IS). Scope pushdown is then N/A by declaration — an\n   * explicit, audited stance, never an inferred one (R16).\n   */\n  SINGLE_TENANT_BINDING = 'single-tenant-binding',\n}\n\n// --------------------------------\n// Key declaration + component codecs (paper A)\n// --------------------------------\n\n/**\n * Per-component value normalization for key synthesis. The codec is what makes the synthesized\n * `_id` STABLE: every component must round-trip byte-identically between the remote\n * representation and the encoded id, or the same remote row would answer to different ids.\n *\n * `INTEGER` and `GUID` are the two codecs whose entire value space is URL-unreserved-safe, which\n * is what qualifies a single-key binding for the VERBATIM id form (see\n * `httpApiBindingUsesVerbatimKey`).\n */\nexport enum HttpApiKeyComponentCodec {\n  /** Arbitrary remote string. NOT charset-safe → always participates via the encoded id form. */\n  STRING = 'string',\n\n  /** Integer key (Odoo `id`, SAP numeric keys). Digits only → verbatim-eligible. */\n  INTEGER = 'integer',\n\n  /** GUID/UUID key (Dataverse row ids). Hex + dashes → verbatim-eligible. */\n  GUID = 'guid',\n\n  /**\n   * Date/time key component, normalized to the RFC 3339 / ISO 8601 UTC string form before\n   * encoding. NOT verbatim-eligible (`:` is forbidden in ids — websocket room names are\n   * colon-parsed).\n   */\n  DATETIME_ISO = 'datetime-iso',\n}\n/** @wildo_source:part:end saas.models.http-api-binding */\n\n/**\n * One ordered component of the remote entity's key. `keyFields` order is the ENCODING order —\n * declared, committed, and boot-verified against `$metadata` where the dialect provides one;\n * never inferred at runtime (a silently adopted key change would orphan every stored FK value\n * and bookmark).\n */\nexport const HttpApiKeyFieldSchema = z.object({\n  /** The field name on the Wildo resource schema that carries this component. */\n  localField: z.string().min(1),\n\n  /** The remote entity's property name for this component. */\n  remoteField: z.string().min(1),\n\n  /** Value normalization for stable synthesis. */\n  codec: z.enum(HttpApiKeyComponentCodec),\n});\n\nexport type HttpApiKeyField = z.infer<typeof HttpApiKeyFieldSchema>;\n\n// --------------------------------\n// Field mapping\n// --------------------------------\n\n/**\n * Local-to-remote field name mapping for fields whose names differ. Fields not listed map by\n * identity (same name both sides). Key components are declared in `keyFields`, not here.\n */\nexport const HttpApiFieldMappingSchema = z.object({\n  localField: z.string().min(1),\n  remoteField: z.string().min(1),\n});\n\nexport type HttpApiFieldMapping = z.infer<typeof HttpApiFieldMappingSchema>;\n\n// --------------------------------\n// Remote-call semantics (decision D10 / requirement R15)\n// --------------------------------\n\n/**\n * Declared remote-call semantics. An enterprise API is 100ms–2s, rate-limited, and sometimes\n * down; these are DECISIONS, not inherited pipeline defaults. Defaults are conservative on\n * purpose — a binding that needs more declares more.\n */\nexport const HttpApiRemoteCallSemanticsSchema = z.object({\n  /** Per-call timeout. */\n  timeoutMs: z.number().int().positive().max(120_000).default(10_000),\n\n  /**\n   * Retry policy for idempotent READ-family calls only. Writes (when D4 lands) never retry\n   * implicitly.\n   */\n  retry: z\n    .object({\n      maxAttempts: z.number().int().min(1).max(5).default(2),\n      backoffMs: z.number().int().positive().max(30_000).default(500),\n    })\n    .default({ maxAttempts: 2, backoffMs: 500 }),\n\n  /**\n   * Rate budget toward the target, per process. `undefined` = no local throttle (the target's own\n   * limits still apply and surface as refusals).\n   */\n  maxRequestsPerMinute: z.number().int().positive().optional(),\n\n  /**\n   * Upper bound for translated id-set predicates (`_id ∈ {…}` → key-predicate disjunction /\n   * `in`). Above the bound the adapter REFUSES rather than emitting an unbounded URL\n   * (scope-down paper, shape T2).\n   */\n  maxIdSetSize: z.number().int().positive().max(500).default(50),\n});\n\nexport type HttpApiRemoteCallSemantics = z.infer<typeof HttpApiRemoteCallSemanticsSchema>;\n\n// --------------------------------\n// Dialect-specific declarations\n// --------------------------------\n\n/**\n * HTTP methods a declared read-family operation may use. Deliberately NOT the full HTTP verb set\n * (`API_HttpMethod` in `@wildo-ai/external-connectors-models` describes provider-protocol\n * operations): slice 1 is read-only, so the closed vocabulary is the read-safe verb plus POST —\n * because JSON-RPC (Odoo) and many enterprise search endpoints are POST-shaped even for reads.\n * Write verbs (PUT/PATCH/DELETE) enter only with the D4 write story, as their own decision.\n */\nexport enum HttpApiRestOperationMethod {\n  GET = 'GET',\n  POST = 'POST',\n}\n\n/**\n * REST_JSON per-operation declaration: how one read-family member maps onto a concrete HTTP\n * operation. Deliberately minimal in slice 1 — pagination/filter parameter NAMES are declared,\n * their VALUES are supplied by the adapter from the translated query.\n *\n * Related but distinct: `REST_API_OperationSpecSchema` in `@wildo-ai/external-connectors-models`\n * describes provider-protocol operations for capability transformers. This schema describes a\n * RESOURCE read surface; if the two converge later that is a recorded decision, not an implicit\n * merge of distinct concepts.\n */\nexport const HttpApiRestOperationSpecSchema = z.object({\n  /** HTTP method for this read-family operation. */\n  method: z.enum(HttpApiRestOperationMethod),\n\n  /**\n   * Path template relative to the provider's base URL. `{key}` interpolates the synthesized\n   * key's remote addressing form; other `{param}` tokens must be declared parameter names.\n   */\n  pathTemplate: z.string().min(1),\n\n  /** Query/body parameter names for pagination, when the operation supports it. */\n  pagingParams: z\n    .object({\n      limitParam: z.string().min(1),\n      offsetParam: z.string().min(1),\n    })\n    .optional(),\n\n  /**\n   * Declared filter parameter name per LOCAL field. Only fields listed here are translatable for\n   * this operation (scope-down paper, shape T3); everything else is refused at the adapter\n   * boundary.\n   */\n  filterParams: z.record(z.string().min(1), z.string().min(1)).optional(),\n\n  /**\n   * The parameter that receives the SEARCH text (T4), for a `search` operation. Absent =\n   * search is refused for this binding even when the operation exists.\n   */\n  searchParam: z.string().min(1).optional(),\n\n  /**\n   * Dot-path to the payload inside the response body — the rows array (list/search), the entity\n   * object (read), or the number (count). Absent = the body IS the payload. Declared, never\n   * sniffed: response shapes vary per target (`items`, `result`, `value`, raw array) and a wrong\n   * guess would silently read zero rows.\n   */\n  resultPath: z.string().min(1).optional(),\n\n  /** Wrap request/response in a JSON-RPC 2.0 envelope (the Odoo variant). */\n  jsonRpcEnvelope: z\n    .object({\n      rpcMethod: z.string().min(1),\n    })\n    .optional(),\n});\n\nexport type HttpApiRestOperationSpec = z.infer<typeof HttpApiRestOperationSpecSchema>;\n\n/** The REST_JSON read-surface mapping: which lifecycle members exist remotely, and how. */\nexport const HttpApiRestOperationsSchema = z.object({\n  read: HttpApiRestOperationSpecSchema,\n  list: HttpApiRestOperationSpecSchema,\n  /** Absent = COUNT is refused for this binding (honest refusal, never an emulated scan). */\n  count: HttpApiRestOperationSpecSchema.optional(),\n  /** Absent = SEARCH is refused for this binding. */\n  search: HttpApiRestOperationSpecSchema.optional(),\n});\n\nexport type HttpApiRestOperations = z.infer<typeof HttpApiRestOperationsSchema>;\n\n// --------------------------------\n// Stance sub-declarations\n// --------------------------------\n\n/** Tenancy declaration — discriminated so each stance carries exactly its own obligations. */\nexport const HttpApiTenancyDeclarationSchema = z.discriminatedUnion('stance', [\n  z.object({\n    stance: z.literal(HttpApiTenancyStance.SCOPE_FILTER_PUSHDOWN),\n    /** The remote field the engine's tenant-scope predicate is pushed down against. */\n    remoteScopeField: z.string().min(1),\n  }),\n  z.object({\n    stance: z.literal(HttpApiTenancyStance.SINGLE_TENANT_BINDING),\n    /** Why this binding is single-tenant — recorded, audited justification (R16). */\n    justification: z.string().min(1),\n  }),\n]);\n\nexport type HttpApiTenancyDeclaration = z.infer<typeof HttpApiTenancyDeclarationSchema>;\n\n/**\n * HTTP methods a declared EXPLICIT erasure operation (stance 6b, REST_JSON) may use.\n *\n * A separate vocabulary from {@link HttpApiRestOperationMethod} on purpose: that enum describes\n * READ-family operations (GET/POST), and reusing it here would let an erasure declare `GET` — a\n * read spelled as a deletion. Deletion is expressed as the resource-oriented `DELETE` or an\n * RPC-style `POST`; nothing else is a deletion on the wire.\n */\nexport enum HttpApiErasureOperationMethod {\n  POST = 'POST',\n  DELETE = 'DELETE',\n}\n\n/**\n * The EXPLICIT erasure call a REST_JSON binding declares for stance 6b. Deliberately narrower\n * than {@link HttpApiRestOperationSpecSchema}: an erasure addresses ONE row by key — it has no\n * pagination, no filter params, no search, no result path to project.\n */\nexport const HttpApiErasureOperationSpecSchema = z.object({\n  method: z.enum(HttpApiErasureOperationMethod),\n\n  /**\n   * Path template relative to the provider base URL. `{key}` interpolates the row's remote key\n   * addressing form, exactly as in the read-family `pathTemplate`.\n   */\n  pathTemplate: z.string().min(1),\n\n  /**\n   * JSON-RPC envelope for RPC-style targets (pairs with `method: POST`), mirroring the\n   * read-family declaration.\n   */\n  jsonRpcEnvelope: z.object({ rpcMethod: z.string().min(1) }).optional(),\n});\n\nexport type HttpApiErasureOperationSpec = z.infer<typeof HttpApiErasureOperationSpecSchema>;\n\n/** Erasure declaration — discriminated; stance 6b names the operation it invokes. */\nexport const HttpApiErasureDeclarationSchema = z.discriminatedUnion('stance', [\n  z.object({\n    stance: z.literal(HttpApiErasureStance.NO_SUBJECT_DATA),\n  }),\n  z.object({\n    stance: z.literal(HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION),\n    /**\n     * The declared erasure call. ODATA and ODOO_JSONRPC bindings rely on their CANONICAL delete\n     * (`DELETE /EntitySet(key)` / `execute_kw('unlink', [[ids]])`) by declaring\n     * `useCanonicalDelete`; REST_JSON bindings declare the operation explicitly. The pairing is\n     * enforced by {@link assertHttpApiBindingDialectCoherence}.\n     */\n    operation: z.union([\n      z.object({ useCanonicalDelete: z.literal(true) }),\n      HttpApiErasureOperationSpecSchema,\n    ]),\n    /**\n     * The LOCAL field naming the DATA SUBJECT whose erasure deletes a remote row — the rows the\n     * declared operation applies to are exactly `{ [subjectLinkLocalField]: <erased subject id> }`.\n     *\n     * DECLARED, never inferred, for the same reason `dataSubjectPolicy` exists on retention: a\n     * foreign key usually names an OWNER or an ACTOR, not the subject — inferring from \"any FK to\n     * the erased user\" would delete a purchase-order row because the erased user merely CREATED\n     * it, destroying a business record no erasure asked for. One field, mirroring\n     * `sessionPrincipalField`'s \"one field names the person\". Registration verifies a declared\n     * relationship carries this field as its FK (so the subject type it links is known).\n     */\n    subjectLinkLocalField: z.string().trim().min(1),\n  }),\n  z.object({\n    stance: z.literal(HttpApiErasureStance.CONTROLLER_ACKNOWLEDGED_NON_ERASURE),\n    /**\n     * Optional evidence link: the LOCAL field naming the data subject, used ONLY to COUNT the\n     * remaining remote rows for the acknowledgement's CRITICAL audit record (`remainingRowCount`).\n     * Optional because 6c legitimately covers linkage no FK expresses (an email inside remote\n     * rows) — absent, the record carries no count rather than a fabricated zero. Never used to\n     * delete anything.\n     */\n    subjectLinkLocalField: z.string().trim().min(1).optional(),\n  }),\n]);\n\nexport type HttpApiErasureDeclaration = z.infer<typeof HttpApiErasureDeclarationSchema>;\n\n// --------------------------------\n// The binding declaration\n// --------------------------------\n\nconst httpApiResourceBindingBaseShape = {\n  /**\n   * The external provider whose declared protocol configuration carries the base URL and whose\n   * credentials resolve through `ExternalProvidersRegistryBackendService` (decision D7 — no new\n   * secret store, no connection string on the resource config).\n   */\n  providerRef: z.string().min(1),\n\n  /**\n   * The remote entity addressed by this binding — an OData entity-set name, or a logical name for\n   * a REST_JSON surface. One binding, one remote entity set.\n   */\n  entityRef: z.string().min(1),\n\n  /** Whose identity reaches the target (D9). */\n  identityMode: z.enum(HttpApiIdentityMode).default(HttpApiIdentityMode.SERVICE_PRINCIPAL),\n\n  /** Ordered key declaration — the source of the synthesized engine-facing `_id` (paper A). */\n  keyFields: z.array(HttpApiKeyFieldSchema).min(1),\n\n  /** Non-key field name mappings; unlisted fields map by identity. */\n  fieldMappings: z.array(HttpApiFieldMappingSchema).default([]),\n\n  /** Tenancy stance (R4/R16). */\n  tenancy: HttpApiTenancyDeclarationSchema,\n\n  /** Erasure stance (D6) — required; no silent default. */\n  erasure: HttpApiErasureDeclarationSchema,\n\n  /** Remote-call semantics (D10/R15). */\n  remoteCallSemantics: HttpApiRemoteCallSemanticsSchema.default({\n    timeoutMs: 10_000,\n    retry: { maxAttempts: 2, backoffMs: 500 },\n    maxIdSetSize: 50,\n  }),\n};\n\n/**\n * The HTTP_API resource binding — discriminated on the transport dialect so each dialect carries\n * exactly its own obligations: ODATA is generic (plus an optional `$metadata` probe opt-out for\n * targets that do not serve one); REST_JSON must declare its whole read surface.\n */\n/** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */\nexport const HttpApiResourceBindingSchema = z.discriminatedUnion('dialect', [\n  z.object({\n    dialect: z.literal(HttpApiTransportDialect.ODATA),\n    ...httpApiResourceBindingBaseShape,\n    /**\n     * Verify the committed declaration against the live `$metadata` at boot (decision D5 —\n     * drift is detected at boot and the fix is re-authoring, never silent adaptation). Opt out\n     * only for targets that genuinely do not serve `$metadata`.\n     */\n    verifyMetadataAtBoot: z.boolean().default(true),\n  }),\n  z.object({\n    dialect: z.literal(HttpApiTransportDialect.REST_JSON),\n    ...httpApiResourceBindingBaseShape,\n    /** The declared read surface — absent members are refused, never emulated. */\n    operations: HttpApiRestOperationsSchema,\n  }),\n  z.object({\n    dialect: z.literal(HttpApiTransportDialect.ODOO_JSONRPC),\n    ...httpApiResourceBindingBaseShape,\n    // Generic like ODATA — no per-binding operation declarations: `entityRef` is the Odoo model\n    // (e.g. 'res.partner'); read/list/count map onto read/search_read/search_count mechanically.\n    // The single-INTEGER-key constraint is enforced by `assertHttpApiBindingDialectCoherence`\n    // (called by the resource-configuration factory) — a refine here would wrap the union member\n    // in effects, which discriminated unions do not admit.\n  }),\n]);\n\n/**\n * Dialect-specific structural constraints that a discriminated union cannot express member-side.\n * Called by the resource-configuration factory AFTER the schema parse; throws with the offending\n * path named.\n */\nexport function assertHttpApiBindingDialectCoherence(binding: HttpApiResourceBinding): void {\n  if (binding.dialect === HttpApiTransportDialect.ODOO_JSONRPC) {\n    // Odoo row ids are INTEGERS, always — one key field, INTEGER codec, or the synthesized id\n    // could never address a row.\n    if (\n      binding.keyFields.length !== 1\n      || binding.keyFields[0].codec !== HttpApiKeyComponentCodec.INTEGER\n    ) {\n      throw new Error(\n        \"keyFields: an ODOO_JSONRPC binding must declare exactly one key field with the INTEGER codec — Odoo row ids are integers ('id').\",\n      );\n    }\n  }\n\n  // D6 stance 6b — the declared erasure operation's FORM is dialect-specific. The union schema\n  // admits both forms; only the pairing below is executable, so an incoherent pairing must refuse\n  // at authoring rather than on the first subject-erasure request:\n  //   - ODATA        → `useCanonicalDelete` only (the canonical `DELETE /EntitySet(key)`);\n  //   - ODOO_JSONRPC → `useCanonicalDelete` only (compiles to `execute_kw('unlink', [[ids]])`,\n  //                    Odoo's own canonical delete);\n  //   - REST_JSON    → an explicit operation spec only (there IS no canonical delete to rely on —\n  //                    the binding declares the exact call, like every other REST_JSON operation).\n  if (binding.erasure.stance === HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION) {\n    const usesCanonicalDelete = 'useCanonicalDelete' in binding.erasure.operation;\n    if (binding.dialect === HttpApiTransportDialect.REST_JSON && usesCanonicalDelete) {\n      throw new Error(\n        'erasure.operation: a REST_JSON binding has no canonical delete — declare the explicit erasure operation spec (method/path), like its other declared operations.',\n      );\n    }\n    if (binding.dialect !== HttpApiTransportDialect.REST_JSON && !usesCanonicalDelete) {\n      throw new Error(\n        `erasure.operation: a ${binding.dialect} binding executes erasure through its CANONICAL delete (declare { useCanonicalDelete: true }) — an explicit REST operation spec has no translation on this dialect.`,\n      );\n    }\n  }\n}\n\n/** @wildo_source:part:end saas.models.http-api-binding */\nexport type HttpApiResourceBinding = z.infer<typeof HttpApiResourceBindingSchema>;\n\n// --------------------------------\n// Static binding properties\n// --------------------------------\n\n/**\n * Codecs whose ENTIRE value space stays within the synthesized-id charset law\n * (`^[A-Za-z0-9._~-]+$`, see `http-api-binding-id.shared.utils.ts`). Membership here is what\n * qualifies a single-key binding for the verbatim id form.\n */\nconst VERBATIM_ELIGIBLE_CODECS: readonly HttpApiKeyComponentCodec[] = [\n  HttpApiKeyComponentCodec.INTEGER,\n  HttpApiKeyComponentCodec.GUID,\n];\n\n/**\n * Whether this binding's synthesized `_id` is the single key value VERBATIM (legible ids for\n * Dataverse GUIDs / Odoo integers) versus the encoded composite form. A STATIC property of the\n * declaration — never sniffed per row — which is what keeps decode unambiguous (paper A).\n */\nexport function httpApiBindingUsesVerbatimKey(\n  binding: { keyFields: readonly HttpApiKeyField[] },\n): boolean {\n  return (\n    binding.keyFields.length === 1\n    && VERBATIM_ELIGIBLE_CODECS.includes(binding.keyFields[0].codec)\n  );\n}\n"]}

package/dist/esm/i18n/interpolate-label-params.shared.utils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * interpolateLabelParams — the single canonical placeholder substitution for
+ * every translated label in the framework.
+ *
+ * ## Convention (the ONE contract content authors and the generator follow)
+ *
+ * SINGLE braces, and the placeholder name is exactly the declared param name:
+ *
+ * ```
+ * interpolateLabelParams('Enter at least {count} characters', { count: 2 })
+ *   // -> 'Enter at least 2 characters'
+ * interpolateLabelParams('Showing {from}–{to} of {total}', { from: 1, to: 10, total: 42 })
+ *   // -> 'Showing 1–10 of 42'
+ * ```
+ *
+ * This util is the single source of truth shared by:
+ *   - the frontend translation engine (`t()` in `I18nContext`)
+ *   - the backend email/label interpolation (`interpolateEmailLabel`)
+ * and it mirrors the convention the LLM label generator is instructed to emit
+ * (single-brace placeholders whose names match the declared `params` of each
+ * label).
+ *
+ * ## Why these exact semantics
+ *
+ * - **Name-based, not positional** — multi-param labels
+ *   (`Select between {min} and {max}`) and locale reorderings
+ *   (`{total} éléments` vs `{total} items`) stay correct because each
+ *   placeholder binds to its named value, never to an index.
+ * - **Unknown placeholder left verbatim** — a `{token}` with no matching param
+ *   is returned untouched rather than blanked. This means (a) a label that
+ *   legitimately contains brace text is never corrupted, and (b) a
+ *   genuinely-missing param surfaces as a visible `{token}` instead of a silent
+ *   gap, which is the louder, easier-to-catch failure.
+ * - **No params → identity** — passing `undefined`/no params returns the
+ *   template unchanged (the common case for paramless labels).
+ *
+ * ## History (do not regress)
+ *
+ * The frontend `t()` historically matched DOUBLE braces (`{{param}}`) while
+ * 100% of generated content and the backend interpolator used single braces —
+ * so no frontend parameter ever interpolated and users saw literal `{value}` /
+ * `{count}` text. Centralizing the substitution here removes that divergence:
+ * there is now exactly one brace convention, defined in one place.
+ *
+ * @param template the (already locale-resolved) label string
+ * @param params   name → value map; values are coerced with `String(...)`
+ * @returns the template with every `{name}` whose `name` is present in `params`
+ *          replaced by its stringified value; all other text (including
+ *          unmatched `{tokens}`) left exactly as authored.
+ */
+export declare function interpolateLabelParams(template: string, params?: Record<string, string | number | undefined | null>): string;
+//# sourceMappingURL=interpolate-label-params.shared.utils.d.ts.map

package/dist/esm/i18n/interpolate-label-params.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate-label-params.shared.utils.d.ts","sourceRoot":"","sources":["../../../../src/i18n/interpolate-label-params.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,GAC1D,MAAM,CAYR"}