@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/http-api-binding/http-api-rest-write-operations.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-rest-write-operations.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-rest-write-operations.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,kIAAkI;AAClI;;;;GAIG;AACH,oBAAY,sBAAsB;IAChC,IAAI,SAAS;IACb,KAAK,UAAU;IACf,MAAM,WAAW;CAClB;AAED,qEAAqE;AACrE,oBAAY,2BAA2B;IACrC;;;OAGG;IACH,aAAa,kBAAkB;IAC/B;;;;OAIG;IACH,eAAe,oBAAoB;CACpC;AAED,mHAAmH;AACnH,eAAO,MAAM,2BAA2B;;;;;6BAStC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mCAAmC;;;;;;;;;;iBAe9C,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAChG,gFAAgF;AAEhF,oFAAoF;AACpF,MAAM,WAAW,2BAA2B;IAC1C,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACpD,+GAA+G;IAC/G,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAOD;;;GAGG;AACH,wBAAgB,oCAAoC,CAAC,IAAI,EAAE,6BAA6B,EAAE,KAAK,EAAE,2BAA2B,GAAG,IAAI,CAgFlI"}

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

@@ -0,0 +1,191 @@
+/**
+ * How a REST_JSON binding SENDS a row write (#1728): one declared request per opened verb.
+ *
+ * ODATA and ODOO_JSONRPC each have a protocol, so their write dialects know the wire and a binding only opens verbs
+ * (`writableVerbs`). REST_JSON has no protocol — the thing it names is "a vendor's own JSON API" — so, exactly as for its
+ * reads, the binding DECLARES what a create, an update and a delete look like: a method and a path template, and for a
+ * create, where the vendor answers the new record's key. Nothing is emulated and nothing is guessed.
+ *
+ * ## The two vendors this was measured against
+ *
+ * | | create | update | delete | the new key |
+ * |---|---|---|---|---|
+ * | Salesforce sObject rows | `POST …/sobjects/<Object>` → `201` | `PATCH …/sobjects/<Object>/<id>` → `204` | `DELETE …/sobjects/<Object>/<id>` → `204` | the body's `id` |
+ * | NetSuite record service | `POST …/record/v1/<type>` → `204`, no body | `PATCH …/record/v1/<type>/<id>` → `204` | `DELETE …/record/v1/<type>/<id>` → `204` | the `Location` header |
+ *
+ * spec-cite: Oracle NetSuite, "Creating a Record Instance"
+ * (https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1545141395.html) — the create answers
+ * `HTTP Code 204` and "The URL of the newly created record is given in the Location header of the response."
+ * spec-cite: Oracle NetSuite, "Updating a Record Instance" (section_1545142173.html) and "Deleting a Record Instance"
+ * (section_1545142287.html) — `PATCH` and `DELETE` on `/record/v1/<type>/<id>`, each answering 204 with no body.
+ * spec-cite: N/A for Salesforce's own pages, which refuse an unauthenticated fetch (403) — the shapes above are read from
+ * jsforce's `Connection` (`_createSingle` POSTs to `sobjects/<type>` and reads the answer; `_updateSingle` PATCHes and
+ * `_destroySingle` DELETEs `sobjects/<type>/<id>`, both answered with no content), the most used client of that API.
+ *
+ * ## Why a declared METHOD, and why never `PUT`
+ *
+ * An update carries only the fields the caller changed. A `PUT` REPLACES the resource on every API that follows HTTP's own
+ * definition, so a partial `PUT` resets whatever it omitted — the reason the OData dialect never sends one. So `PUT` is not
+ * in {@link HttpApiRestWriteMethod} at all: a vendor whose only update is a full replacement cannot be written through a
+ * field-level change, and the honest answer is to leave the binding read-only. `POST` is admitted for an update and a
+ * delete because RPC-shaped APIs spell every change that way (the same reason the declared erasure call admits it).
+ *
+ * ## Why no idempotency and no retry
+ *
+ * Neither vendor deduplicates a synchronous write by a request id: NetSuite's `X-NetSuite-Idempotency-Key` is documented
+ * for ASYNCHRONOUS requests (`Prefer: respond-async`), and Salesforce's sObject rows take none. So every write is sent
+ * ONCE, and an interrupted one is an unknown outcome — as for Odoo and OData, and for the same reason: a `POST` re-sent
+ * after a lost answer creates a second record.
+ * spec-cite: Oracle NetSuite, "Sending an Asynchronous Request Using an Idempotency Key"
+ * (https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/subsect_164494900632.html) — the only request shape the
+ * header is documented on carries `Prefer: respond-async`.
+ *
+ * ## No conditional write
+ *
+ * Neither vendor's record API is written here with a precondition, so a `VERSION_CHECKED` stance on a REST_JSON binding is
+ * best-effort exactly as it is on Odoo: the engine compares before sending, and a change landing between that read and
+ * the write is not seen. It also needs a vendor facet that declares the row version field, which neither facet does today.
+ *
+ * Deliberately a module of its own rather than a block of `http-api-binding.shared.schemas.ts`: it names no binding type,
+ * so the binding module can import it without the two importing each other. The per-VERB rules — which member each
+ * opened verb needs, which methods each may use — live beside `HttpApiWriteVerb` in that module
+ * (`assertHttpApiBindingDialectCoherence`), and call {@link assertHttpApiRestWriteOperationShape} for each member.
+ */
+import { z } from 'zod';
+/** @wildo_source:part:start saas.models.http-api-binding.rest-write-operations facet:layer:shared facet:audience:app-developer */
+/**
+ * The methods a declared REST_JSON row write may use. Never `PUT` (it replaces the resource, so a partial update would
+ * reset every field it omits) and never `GET` (a read is not a write). Which of these each verb admits is decided per verb:
+ * a create is a `POST`; an update a `PATCH` or an RPC-style `POST`; a delete a `DELETE` or an RPC-style `POST`.
+ */
+export var HttpApiRestWriteMethod;
+(function (HttpApiRestWriteMethod) {
+    HttpApiRestWriteMethod["POST"] = "POST";
+    HttpApiRestWriteMethod["PATCH"] = "PATCH";
+    HttpApiRestWriteMethod["DELETE"] = "DELETE";
+})(HttpApiRestWriteMethod || (HttpApiRestWriteMethod = {}));
+/** Where a vendor answers the KEY of a record a create just made. */
+export var HttpApiRestCreatedKeySource;
+(function (HttpApiRestCreatedKeySource) {
+    /**
+     * A value in the JSON answer, at a declared dot-path — Salesforce's `{ "id": "001…", "success": true, "errors": [] }`
+     * answers `path: 'id'`. The answer need not be the record: only its key is read, and the row is then read back by it.
+     */
+    HttpApiRestCreatedKeySource["RESPONSE_BODY"] = "response-body";
+    /**
+     * The LAST path segment of the answer's `Location` header — NetSuite answers `204` with no body and
+     * `Location: https://<account>.suitetalk.api.netsuite.com/services/rest/record/v1/customer/647`. The header must name a
+     * record of the path the create was sent to (`<create path>/<key>`), or the answer is not read as a key.
+     */
+    HttpApiRestCreatedKeySource["LOCATION_HEADER"] = "location-header";
+})(HttpApiRestCreatedKeySource || (HttpApiRestCreatedKeySource = {}));
+/** Where a create's answer carries the new record's key. A single-key binding only: one answer names one value. */
+export const HttpApiRestCreatedKeySchema = z.discriminatedUnion('source', [
+    z.object({
+        source: z.literal(HttpApiRestCreatedKeySource.RESPONSE_BODY),
+        /** Dot-path to the key inside the JSON answer (`id`, `data.id`). */
+        path: z.string().min(1),
+    }),
+    z.object({
+        source: z.literal(HttpApiRestCreatedKeySource.LOCATION_HEADER),
+    }),
+]);
+/**
+ * One declared REST_JSON row write: `operations.create`, `operations.update` or `operations.delete` — each present exactly
+ * when the binding opens that verb in `writableVerbs`.
+ *
+ * @example
+ * ```ts
+ * // Salesforce: a create answers the id in its body; an update and a delete answer 204.
+ * create: { method: HttpApiRestWriteMethod.POST, pathTemplate: '/services/data/v62.0/sobjects/Account',
+ *           createdKey: { source: HttpApiRestCreatedKeySource.RESPONSE_BODY, path: 'id' } },
+ * update: { method: HttpApiRestWriteMethod.PATCH, pathTemplate: '/services/data/v62.0/sobjects/Account/{key}' },
+ * delete: { method: HttpApiRestWriteMethod.DELETE, pathTemplate: '/services/data/v62.0/sobjects/Account/{key}' },
+ * ```
+ */
+export const HttpApiRestWriteOperationSpecSchema = z.object({
+    method: z.enum(HttpApiRestWriteMethod),
+    /**
+     * Path relative to the instance's base URL. An update or a delete addresses ONE record by `{key}` (a single-key binding)
+     * or `{key.<RemoteField>}` tokens, exactly as a `read` member does; a create names the collection and carries no key
+     * token — the vendor chooses the key.
+     */
+    pathTemplate: z.string().min(1),
+    /** Where the vendor answers the created record's key. Required on `create`, refused on `update` and `delete`. */
+    createdKey: HttpApiRestCreatedKeySchema.optional(),
+    /**
+     * Headers this vendor requires on the write. VENDOR headers only: a credential comes from the instance's access, never
+     * from a binding, and an `Authorization` key is refused by name.
+     */
+    staticHeaders: z.record(z.string().min(1), z.string().min(1)).optional(),
+});
+/** A key-addressing token in a path template: `{key}` or `{key.<RemoteField>}`. */
+const KEY_TOKEN = /\{key(?:\.[^}]+)?\}/;
+/** Any `{…}` token. A write has no declared parameters, so every token must be a key token. */
+const ANY_TOKEN = /\{[^}]*\}/g;
+/**
+ * Throws, naming the member, when one declared REST_JSON write cannot be sent as declared. Called by
+ * `assertHttpApiBindingDialectCoherence` for each opened verb's member.
+ */
+export function assertHttpApiRestWriteOperationShape(spec, rules) {
+    const { member } = rules;
+    if (!rules.methods.includes(spec.method)) {
+        throw new Error(`operations.${member}.method: '${spec.method}' is not a ${member} — declare one of ${rules.methods.join(' / ')}. `
+            + '(`PUT` is never admitted: it replaces the record, so a partial write would reset every field it omits.)');
+    }
+    /*
+     * The path is appended to the instance's base URL as it is, so it starts at `/`. That is also what makes a create's
+     * `Location` comparable on a segment boundary: a collection `/sobjects/Account` can only match `…/sobjects/Account/<id>`,
+     * never `…/xsobjects/Account/<id>`.
+     */
+    if (!spec.pathTemplate.startsWith('/')) {
+        throw new Error(`operations.${member}.pathTemplate: '${spec.pathTemplate}' must start with '/' — it is appended to the instance's base URL.`);
+    }
+    for (const token of spec.pathTemplate.match(ANY_TOKEN) ?? []) {
+        if (!KEY_TOKEN.test(token)) {
+            throw new Error(`operations.${member}.pathTemplate: '${token}' names no key component — a row write has no declared parameters, `
+                + 'so only `{key}` or `{key.<RemoteField>}` may appear.');
+        }
+        // Checked here rather than at the first write: a token that names nothing would refuse every request it compiles.
+        if (token === '{key}' && rules.keyRemoteFields.length !== 1) {
+            throw new Error(`operations.${member}.pathTemplate: '{key}' addresses a single-key binding, and this one declares ${rules.keyRemoteFields.length} `
+                + 'key components — use one `{key.<RemoteField>}` token per component.');
+        }
+        const remoteField = token.startsWith('{key.') ? token.slice('{key.'.length, -1) : undefined;
+        if (remoteField !== undefined && !rules.keyRemoteFields.includes(remoteField)) {
+            throw new Error(`operations.${member}.pathTemplate: '${token}' names no key field — declared: ${rules.keyRemoteFields.map((field) => `'${field}'`).join(', ')}.`);
+        }
+    }
+    const addressesRecord = KEY_TOKEN.test(spec.pathTemplate);
+    if (rules.addressesOneRecord && !addressesRecord) {
+        throw new Error(`operations.${member}.pathTemplate: '${spec.pathTemplate}' addresses no record — a ${member} changes ONE record, so its `
+            + 'path carries `{key}` (or `{key.<RemoteField>}` tokens).');
+    }
+    if (!rules.addressesOneRecord && addressesRecord) {
+        throw new Error(`operations.${member}.pathTemplate: '${spec.pathTemplate}' addresses a record by key — a create names the collection, `
+            + 'and the vendor chooses the key.');
+    }
+    if (!rules.addressesOneRecord && spec.pathTemplate.split('?')[0].replace(/\/+$/, '').length === 0) {
+        throw new Error(`operations.${member}.pathTemplate: a create must name its collection — '/' names none, and a Location could not be `
+            + 'checked against it.');
+    }
+    if (!rules.addressesOneRecord && spec.createdKey === undefined) {
+        throw new Error(`operations.${member}.createdKey: a create must say where the vendor answers the new record's key — `
+            + `{ source: '${HttpApiRestCreatedKeySource.RESPONSE_BODY}', path: '<dot.path>' } or `
+            + `{ source: '${HttpApiRestCreatedKeySource.LOCATION_HEADER}' }. Without it the row the create made could not be named.`);
+    }
+    if (rules.addressesOneRecord && spec.createdKey !== undefined) {
+        throw new Error(`operations.${member}.createdKey: only a create answers a new key — remove it from the ${member}.`);
+    }
+    if (spec.createdKey !== undefined && rules.keyRemoteFields.length !== 1) {
+        throw new Error(`operations.${member}.createdKey: this binding declares ${rules.keyRemoteFields.length} key components, and a create's answer names ONE `
+            + 'value. A REST_JSON binding opening CREATE must have a single key field.');
+    }
+    for (const header of Object.keys(spec.staticHeaders ?? {})) {
+        if (header.toLowerCase() === 'authorization') {
+            throw new Error(`operations.${member}.staticHeaders: '${header}' is a credential. Credentials come from the system of record's `
+                + 'access and are never declared in a binding, which is committed.');
+        }
+    }
+}
+//# sourceMappingURL=http-api-rest-write-operations.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-rest-write-operations.shared.schemas.js","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-rest-write-operations.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How a REST_JSON binding SENDS a row write (#1728): one declared request per opened verb.\n *\n * ODATA and ODOO_JSONRPC each have a protocol, so their write dialects know the wire and a binding only opens verbs\n * (`writableVerbs`). REST_JSON has no protocol — the thing it names is \"a vendor's own JSON API\" — so, exactly as for its\n * reads, the binding DECLARES what a create, an update and a delete look like: a method and a path template, and for a\n * create, where the vendor answers the new record's key. Nothing is emulated and nothing is guessed.\n *\n * ## The two vendors this was measured against\n *\n * | | create | update | delete | the new key |\n * |---|---|---|---|---|\n * | Salesforce sObject rows | `POST …/sobjects/<Object>` → `201` | `PATCH …/sobjects/<Object>/<id>` → `204` | `DELETE …/sobjects/<Object>/<id>` → `204` | the body's `id` |\n * | NetSuite record service | `POST …/record/v1/<type>` → `204`, no body | `PATCH …/record/v1/<type>/<id>` → `204` | `DELETE …/record/v1/<type>/<id>` → `204` | the `Location` header |\n *\n * spec-cite: Oracle NetSuite, \"Creating a Record Instance\"\n * (https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1545141395.html) — the create answers\n * `HTTP Code 204` and \"The URL of the newly created record is given in the Location header of the response.\"\n * spec-cite: Oracle NetSuite, \"Updating a Record Instance\" (section_1545142173.html) and \"Deleting a Record Instance\"\n * (section_1545142287.html) — `PATCH` and `DELETE` on `/record/v1/<type>/<id>`, each answering 204 with no body.\n * spec-cite: N/A for Salesforce's own pages, which refuse an unauthenticated fetch (403) — the shapes above are read from\n * jsforce's `Connection` (`_createSingle` POSTs to `sobjects/<type>` and reads the answer; `_updateSingle` PATCHes and\n * `_destroySingle` DELETEs `sobjects/<type>/<id>`, both answered with no content), the most used client of that API.\n *\n * ## Why a declared METHOD, and why never `PUT`\n *\n * An update carries only the fields the caller changed. A `PUT` REPLACES the resource on every API that follows HTTP's own\n * definition, so a partial `PUT` resets whatever it omitted — the reason the OData dialect never sends one. So `PUT` is not\n * in {@link HttpApiRestWriteMethod} at all: a vendor whose only update is a full replacement cannot be written through a\n * field-level change, and the honest answer is to leave the binding read-only. `POST` is admitted for an update and a\n * delete because RPC-shaped APIs spell every change that way (the same reason the declared erasure call admits it).\n *\n * ## Why no idempotency and no retry\n *\n * Neither vendor deduplicates a synchronous write by a request id: NetSuite's `X-NetSuite-Idempotency-Key` is documented\n * for ASYNCHRONOUS requests (`Prefer: respond-async`), and Salesforce's sObject rows take none. So every write is sent\n * ONCE, and an interrupted one is an unknown outcome — as for Odoo and OData, and for the same reason: a `POST` re-sent\n * after a lost answer creates a second record.\n * spec-cite: Oracle NetSuite, \"Sending an Asynchronous Request Using an Idempotency Key\"\n * (https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/subsect_164494900632.html) — the only request shape the\n * header is documented on carries `Prefer: respond-async`.\n *\n * ## No conditional write\n *\n * Neither vendor's record API is written here with a precondition, so a `VERSION_CHECKED` stance on a REST_JSON binding is\n * best-effort exactly as it is on Odoo: the engine compares before sending, and a change landing between that read and\n * the write is not seen. It also needs a vendor facet that declares the row version field, which neither facet does today.\n *\n * Deliberately a module of its own rather than a block of `http-api-binding.shared.schemas.ts`: it names no binding type,\n * so the binding module can import it without the two importing each other. The per-VERB rules — which member each\n * opened verb needs, which methods each may use — live beside `HttpApiWriteVerb` in that module\n * (`assertHttpApiBindingDialectCoherence`), and call {@link assertHttpApiRestWriteOperationShape} for each member.\n */\nimport { z } from 'zod';\n\n/** @wildo_source:part:start saas.models.http-api-binding.rest-write-operations facet:layer:shared facet:audience:app-developer */\n/**\n * The methods a declared REST_JSON row write may use. Never `PUT` (it replaces the resource, so a partial update would\n * reset every field it omits) and never `GET` (a read is not a write). Which of these each verb admits is decided per verb:\n * a create is a `POST`; an update a `PATCH` or an RPC-style `POST`; a delete a `DELETE` or an RPC-style `POST`.\n */\nexport enum HttpApiRestWriteMethod {\n  POST = 'POST',\n  PATCH = 'PATCH',\n  DELETE = 'DELETE',\n}\n\n/** Where a vendor answers the KEY of a record a create just made. */\nexport enum HttpApiRestCreatedKeySource {\n  /**\n   * A value in the JSON answer, at a declared dot-path — Salesforce's `{ \"id\": \"001…\", \"success\": true, \"errors\": [] }`\n   * answers `path: 'id'`. The answer need not be the record: only its key is read, and the row is then read back by it.\n   */\n  RESPONSE_BODY = 'response-body',\n  /**\n   * The LAST path segment of the answer's `Location` header — NetSuite answers `204` with no body and\n   * `Location: https://<account>.suitetalk.api.netsuite.com/services/rest/record/v1/customer/647`. The header must name a\n   * record of the path the create was sent to (`<create path>/<key>`), or the answer is not read as a key.\n   */\n  LOCATION_HEADER = 'location-header',\n}\n\n/** Where a create's answer carries the new record's key. A single-key binding only: one answer names one value. */\nexport const HttpApiRestCreatedKeySchema = z.discriminatedUnion('source', [\n  z.object({\n    source: z.literal(HttpApiRestCreatedKeySource.RESPONSE_BODY),\n    /** Dot-path to the key inside the JSON answer (`id`, `data.id`). */\n    path: z.string().min(1),\n  }),\n  z.object({\n    source: z.literal(HttpApiRestCreatedKeySource.LOCATION_HEADER),\n  }),\n]);\nexport type HttpApiRestCreatedKey = z.infer<typeof HttpApiRestCreatedKeySchema>;\n\n/**\n * One declared REST_JSON row write: `operations.create`, `operations.update` or `operations.delete` — each present exactly\n * when the binding opens that verb in `writableVerbs`.\n *\n * @example\n * ```ts\n * // Salesforce: a create answers the id in its body; an update and a delete answer 204.\n * create: { method: HttpApiRestWriteMethod.POST, pathTemplate: '/services/data/v62.0/sobjects/Account',\n *           createdKey: { source: HttpApiRestCreatedKeySource.RESPONSE_BODY, path: 'id' } },\n * update: { method: HttpApiRestWriteMethod.PATCH, pathTemplate: '/services/data/v62.0/sobjects/Account/{key}' },\n * delete: { method: HttpApiRestWriteMethod.DELETE, pathTemplate: '/services/data/v62.0/sobjects/Account/{key}' },\n * ```\n */\nexport const HttpApiRestWriteOperationSpecSchema = z.object({\n  method: z.enum(HttpApiRestWriteMethod),\n  /**\n   * Path relative to the instance's base URL. An update or a delete addresses ONE record by `{key}` (a single-key binding)\n   * or `{key.<RemoteField>}` tokens, exactly as a `read` member does; a create names the collection and carries no key\n   * token — the vendor chooses the key.\n   */\n  pathTemplate: z.string().min(1),\n  /** Where the vendor answers the created record's key. Required on `create`, refused on `update` and `delete`. */\n  createdKey: HttpApiRestCreatedKeySchema.optional(),\n  /**\n   * Headers this vendor requires on the write. VENDOR headers only: a credential comes from the instance's access, never\n   * from a binding, and an `Authorization` key is refused by name.\n   */\n  staticHeaders: z.record(z.string().min(1), z.string().min(1)).optional(),\n});\nexport type HttpApiRestWriteOperationSpec = z.infer<typeof HttpApiRestWriteOperationSpecSchema>;\n/** @wildo_source:part:end saas.models.http-api-binding.rest-write-operations */\n\n/** What one member's shape must satisfy, decided per verb by the binding module. */\nexport interface HttpApiRestWriteMemberRules {\n  /** `operations.<member>`, for the message. */\n  readonly member: string;\n  /** The methods this verb admits. */\n  readonly methods: readonly HttpApiRestWriteMethod[];\n  /** `true` for an update or a delete (the path must address one record), `false` for a create (it must not). */\n  readonly addressesOneRecord: boolean;\n  /**\n   * The binding's key fields' REMOTE names, in order. `{key}` needs exactly one; `{key.<RemoteField>}` must name one of\n   * them; a created key is readable for a single-key binding only.\n   */\n  readonly keyRemoteFields: readonly string[];\n}\n\n/** A key-addressing token in a path template: `{key}` or `{key.<RemoteField>}`. */\nconst KEY_TOKEN = /\\{key(?:\\.[^}]+)?\\}/;\n/** Any `{…}` token. A write has no declared parameters, so every token must be a key token. */\nconst ANY_TOKEN = /\\{[^}]*\\}/g;\n\n/**\n * Throws, naming the member, when one declared REST_JSON write cannot be sent as declared. Called by\n * `assertHttpApiBindingDialectCoherence` for each opened verb's member.\n */\nexport function assertHttpApiRestWriteOperationShape(spec: HttpApiRestWriteOperationSpec, rules: HttpApiRestWriteMemberRules): void {\n  const { member } = rules;\n  if (!rules.methods.includes(spec.method)) {\n    throw new Error(\n      `operations.${member}.method: '${spec.method}' is not a ${member} — declare one of ${rules.methods.join(' / ')}. `\n      + '(`PUT` is never admitted: it replaces the record, so a partial write would reset every field it omits.)',\n    );\n  }\n  /*\n   * The path is appended to the instance's base URL as it is, so it starts at `/`. That is also what makes a create's\n   * `Location` comparable on a segment boundary: a collection `/sobjects/Account` can only match `…/sobjects/Account/<id>`,\n   * never `…/xsobjects/Account/<id>`.\n   */\n  if (!spec.pathTemplate.startsWith('/')) {\n    throw new Error(`operations.${member}.pathTemplate: '${spec.pathTemplate}' must start with '/' — it is appended to the instance's base URL.`);\n  }\n  for (const token of spec.pathTemplate.match(ANY_TOKEN) ?? []) {\n    if (!KEY_TOKEN.test(token)) {\n      throw new Error(\n        `operations.${member}.pathTemplate: '${token}' names no key component — a row write has no declared parameters, `\n        + 'so only `{key}` or `{key.<RemoteField>}` may appear.',\n      );\n    }\n    // Checked here rather than at the first write: a token that names nothing would refuse every request it compiles.\n    if (token === '{key}' && rules.keyRemoteFields.length !== 1) {\n      throw new Error(\n        `operations.${member}.pathTemplate: '{key}' addresses a single-key binding, and this one declares ${rules.keyRemoteFields.length} `\n        + 'key components — use one `{key.<RemoteField>}` token per component.',\n      );\n    }\n    const remoteField = token.startsWith('{key.') ? token.slice('{key.'.length, -1) : undefined;\n    if (remoteField !== undefined && !rules.keyRemoteFields.includes(remoteField)) {\n      throw new Error(\n        `operations.${member}.pathTemplate: '${token}' names no key field — declared: ${rules.keyRemoteFields.map((field) => `'${field}'`).join(', ')}.`,\n      );\n    }\n  }\n  const addressesRecord = KEY_TOKEN.test(spec.pathTemplate);\n  if (rules.addressesOneRecord && !addressesRecord) {\n    throw new Error(\n      `operations.${member}.pathTemplate: '${spec.pathTemplate}' addresses no record — a ${member} changes ONE record, so its `\n      + 'path carries `{key}` (or `{key.<RemoteField>}` tokens).',\n    );\n  }\n  if (!rules.addressesOneRecord && addressesRecord) {\n    throw new Error(\n      `operations.${member}.pathTemplate: '${spec.pathTemplate}' addresses a record by key — a create names the collection, `\n      + 'and the vendor chooses the key.',\n    );\n  }\n  if (!rules.addressesOneRecord && spec.pathTemplate.split('?')[0]!.replace(/\\/+$/, '').length === 0) {\n    throw new Error(\n      `operations.${member}.pathTemplate: a create must name its collection — '/' names none, and a Location could not be `\n      + 'checked against it.',\n    );\n  }\n  if (!rules.addressesOneRecord && spec.createdKey === undefined) {\n    throw new Error(\n      `operations.${member}.createdKey: a create must say where the vendor answers the new record's key — `\n      + `{ source: '${HttpApiRestCreatedKeySource.RESPONSE_BODY}', path: '<dot.path>' } or `\n      + `{ source: '${HttpApiRestCreatedKeySource.LOCATION_HEADER}' }. Without it the row the create made could not be named.`,\n    );\n  }\n  if (rules.addressesOneRecord && spec.createdKey !== undefined) {\n    throw new Error(`operations.${member}.createdKey: only a create answers a new key — remove it from the ${member}.`);\n  }\n  if (spec.createdKey !== undefined && rules.keyRemoteFields.length !== 1) {\n    throw new Error(\n      `operations.${member}.createdKey: this binding declares ${rules.keyRemoteFields.length} key components, and a create's answer names ONE `\n      + 'value. A REST_JSON binding opening CREATE must have a single key field.',\n    );\n  }\n  for (const header of Object.keys(spec.staticHeaders ?? {})) {\n    if (header.toLowerCase() === 'authorization') {\n      throw new Error(\n        `operations.${member}.staticHeaders: '${header}' is a credential. Credentials come from the system of record's `\n        + 'access and are never declared in a binding, which is committed.',\n      );\n    }\n  }\n}\n"]}

package/dist/esm/http-api-binding/http-api-transport-dialect.shared.d.ts

@@ -55,7 +55,7 @@ export declare enum HttpApiTransportDialect {
      * `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata` boot-time
      * verification probe of the committed declaration.
      *
-     * ⚠ **This member is v4 ONLY, and that excludes SAP's most-used API.** An earlier revision of
+     * ⚠ **This member is v4 ONLY; SAP's most-used API is v2 and is read through `ODATA_V2`.** An earlier revision of
      * this comment named "SAP S/4HANA, Microsoft Dataverse/Dynamics 365" here, which is half right
      * and was load-bearing — it is why nobody looked:
      *
@@ -63,7 +63,7 @@ export declare enum HttpApiTransportDialect {
      * |---|---|---|
      * | Microsoft Dataverse / Dynamics 365 Web API (`/api/data/v9.2/`) | v4 | ✅ |
      * | SAP S/4HANA OData **v4** services (`/sap/opu/odata4/…`) | v4 | ✅ |
-     * | SAP `API_BUSINESS_PARTNER` (`/sap/opu/odata/sap/API_BUSINESS_PARTNER`) | **v2** | ❌ |
+     * | SAP `API_BUSINESS_PARTNER` (`/sap/opu/odata/sap/API_BUSINESS_PARTNER`) | **v2** | through `ODATA_V2` |
      *
      * v2 is not a v4 variant with a different header. Its collection envelope is
      * `{ "d": { "results": [...], "__next": …, "__count": … } }` rather than
@@ -71,17 +71,48 @@ export declare enum HttpApiTransportDialect {
      * rather than ISO 8601; `Edm.Decimal` and `Edm.Int64` serialize as JSON STRINGS rather than
      * numbers; and JSON must be requested (`$format=json`) because v2 defaults to Atom/XML. So it
      * changes the envelope, the paging property, the count property AND the value encoding — a
-     * reader written for one cannot read the other, and the mapping layer needs coercions the way
-     * Odoo needs `ODOO_FALSE_AS_NULL`.
+     * reader written for one cannot read the other. (`ODATA_V2` decodes values at the wire from the
+     * service's `$metadata`, so no mapping-layer coercion is needed for it.)
      * spec-cite: OData Version 2.0 JSON Format
      * (https://www.odata.org/documentation/odata-version-2-0/json-format/) — the `d`/`results`/
      * `__next`/`__count` envelope, the `/Date(<ticks>)/` DateTime literal, and Edm.Decimal /
      * Edm.Int64 "formatted as a JSON string".
      *
-     * Supporting v2 is an OPEN decision, not an oversight. Until it lands, point an ODATA binding at
-     * a v4 service: for SAP that means the OData v4 edition of the API where one is published.
+     * v2 is its own member, {@link HttpApiTransportDialect.ODATA_V2} (#1687) — not a flag on this one. A v2 body read
+     * through an ODATA binding is still refused BY NAME at the first read, so pointing a v4 binding at a v2 root is a
+     * clear error rather than an empty page.
      */
     ODATA = "odata",
+    /**
+     * OData **v2** (#1687) — SAP's classic Gateway services (`/sap/opu/odata/sap/<SERVICE>`), `API_BUSINESS_PARTNER`
+     * first among them. A distinct dialect because every layer differs from v4:
+     *
+     * | | v4 (`ODATA`) | v2 (`ODATA_V2`) |
+     * |---|---|---|
+     * | JSON | the default | asked for on every request (`$format=json`); the default is Atom/XML |
+     * | collection | `{ value: [...], @odata.nextLink }` | `{ d: { results: [...], __next, __count } }` |
+     * | single entity | the object | `{ d: { ... } }` |
+     * | row annotations | `@odata.*` | a `__metadata` object per row |
+     * | total | `$count=true` → `@odata.count` | `$inlinecount=allpages` → `__count` (a STRING) |
+     * | Edm.DateTime | ISO 8601 | `"/Date(<ms>[±<minutes>])/"` |
+     * | Edm.Int64 / Decimal / Double | JSON numbers | JSON STRINGS |
+     * | filter literals | `2026-01-05T00:00:00Z`, `5` | `datetime'2026-01-05T00:00:00'`, `5L`, `1.5M`, `guid'…'` |
+     *
+     * The engine reads the service's `$metadata` (once per client, lazily — never at boot) for each property's Edm type,
+     * because both the value decoding and the filter literal depend on it and nothing in a local field says which: a
+     * decimal and an Int32 are both `number` locally and are spelled differently on the wire.
+     * spec-cite: OData Version 2.0 JSON Format (https://www.odata.org/documentation/odata-version-2-0/json-format/) —
+     * Edm.DateTime `"/Date(<ticks>["+" | "-" <offset>)/"`; Edm.Decimal "Literal form of Edm.Decimal as used in URIs
+     * formatted as a JSON string"; Edm.Int64 "A 64-bit integer formatted as a JSON string"; the `d`/`results`/`__count`/
+     * `__next` envelope; the `__metadata` object ("uri", "type", "etag").
+     * spec-cite: OData Version 2.0 Overview (https://www.odata.org/documentation/odata-version-2-0/overview/) — the
+     * primitive literal forms: `datetime'yyyy-mm-ddThh:mm[:ss[.fffffff]]'`, `2.345M`, `2.0d`, `64L`, `guid'…'`,
+     * `datetimeoffset'…'`.
+     *
+     * Reads only: a binding opening writes on v2 is refused at startup (SAP's CSRF-token handshake and v2's own write
+     * shapes are the write path's, #1679), and so is an explicit-erasure stance, which is a remote DELETE.
+     */
+    ODATA_V2 = "odata-v2",
     /**
      * 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

package/dist/esm/http-api-binding/http-api-transport-dialect.shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-api-transport-dialect.shared.d.ts","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-transport-dialect.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;GAIG;AACH,oBAAY,uBAAuB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,KAAK,UAAU;IAEf;;;;OAIG;IACH,SAAS,cAAc;IAEvB;;;;;;;;;;;;;OAaG;IACH,YAAY,iBAAiB;CAC9B"}
+{"version":3,"file":"http-api-transport-dialect.shared.d.ts","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-transport-dialect.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;GAIG;AACH,oBAAY,uBAAuB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,KAAK,UAAU;IAEf;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,QAAQ,aAAa;IAErB;;;;OAIG;IACH,SAAS,cAAc;IAEvB;;;;;;;;;;;;;OAaG;IACH,YAAY,iBAAiB;CAC9B"}

package/dist/esm/http-api-binding/http-api-transport-dialect.shared.js

@@ -56,7 +56,7 @@ export var HttpApiTransportDialect;
      * `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata` boot-time
      * verification probe of the committed declaration.
      *
-     * ⚠ **This member is v4 ONLY, and that excludes SAP's most-used API.** An earlier revision of
+     * ⚠ **This member is v4 ONLY; SAP's most-used API is v2 and is read through `ODATA_V2`.** An earlier revision of
      * this comment named "SAP S/4HANA, Microsoft Dataverse/Dynamics 365" here, which is half right
      * and was load-bearing — it is why nobody looked:
      *
@@ -64,7 +64,7 @@ export var HttpApiTransportDialect;
      * |---|---|---|
      * | Microsoft Dataverse / Dynamics 365 Web API (`/api/data/v9.2/`) | v4 | ✅ |
      * | SAP S/4HANA OData **v4** services (`/sap/opu/odata4/…`) | v4 | ✅ |
-     * | SAP `API_BUSINESS_PARTNER` (`/sap/opu/odata/sap/API_BUSINESS_PARTNER`) | **v2** | ❌ |
+     * | SAP `API_BUSINESS_PARTNER` (`/sap/opu/odata/sap/API_BUSINESS_PARTNER`) | **v2** | through `ODATA_V2` |
      *
      * v2 is not a v4 variant with a different header. Its collection envelope is
      * `{ "d": { "results": [...], "__next": …, "__count": … } }` rather than
@@ -72,17 +72,48 @@ export var HttpApiTransportDialect;
      * rather than ISO 8601; `Edm.Decimal` and `Edm.Int64` serialize as JSON STRINGS rather than
      * numbers; and JSON must be requested (`$format=json`) because v2 defaults to Atom/XML. So it
      * changes the envelope, the paging property, the count property AND the value encoding — a
-     * reader written for one cannot read the other, and the mapping layer needs coercions the way
-     * Odoo needs `ODOO_FALSE_AS_NULL`.
+     * reader written for one cannot read the other. (`ODATA_V2` decodes values at the wire from the
+     * service's `$metadata`, so no mapping-layer coercion is needed for it.)
      * spec-cite: OData Version 2.0 JSON Format
      * (https://www.odata.org/documentation/odata-version-2-0/json-format/) — the `d`/`results`/
      * `__next`/`__count` envelope, the `/Date(<ticks>)/` DateTime literal, and Edm.Decimal /
      * Edm.Int64 "formatted as a JSON string".
      *
-     * Supporting v2 is an OPEN decision, not an oversight. Until it lands, point an ODATA binding at
-     * a v4 service: for SAP that means the OData v4 edition of the API where one is published.
+     * v2 is its own member, {@link HttpApiTransportDialect.ODATA_V2} (#1687) — not a flag on this one. A v2 body read
+     * through an ODATA binding is still refused BY NAME at the first read, so pointing a v4 binding at a v2 root is a
+     * clear error rather than an empty page.
      */
     HttpApiTransportDialect["ODATA"] = "odata";
+    /**
+     * OData **v2** (#1687) — SAP's classic Gateway services (`/sap/opu/odata/sap/<SERVICE>`), `API_BUSINESS_PARTNER`
+     * first among them. A distinct dialect because every layer differs from v4:
+     *
+     * | | v4 (`ODATA`) | v2 (`ODATA_V2`) |
+     * |---|---|---|
+     * | JSON | the default | asked for on every request (`$format=json`); the default is Atom/XML |
+     * | collection | `{ value: [...], @odata.nextLink }` | `{ d: { results: [...], __next, __count } }` |
+     * | single entity | the object | `{ d: { ... } }` |
+     * | row annotations | `@odata.*` | a `__metadata` object per row |
+     * | total | `$count=true` → `@odata.count` | `$inlinecount=allpages` → `__count` (a STRING) |
+     * | Edm.DateTime | ISO 8601 | `"/Date(<ms>[±<minutes>])/"` |
+     * | Edm.Int64 / Decimal / Double | JSON numbers | JSON STRINGS |
+     * | filter literals | `2026-01-05T00:00:00Z`, `5` | `datetime'2026-01-05T00:00:00'`, `5L`, `1.5M`, `guid'…'` |
+     *
+     * The engine reads the service's `$metadata` (once per client, lazily — never at boot) for each property's Edm type,
+     * because both the value decoding and the filter literal depend on it and nothing in a local field says which: a
+     * decimal and an Int32 are both `number` locally and are spelled differently on the wire.
+     * spec-cite: OData Version 2.0 JSON Format (https://www.odata.org/documentation/odata-version-2-0/json-format/) —
+     * Edm.DateTime `"/Date(<ticks>["+" | "-" <offset>)/"`; Edm.Decimal "Literal form of Edm.Decimal as used in URIs
+     * formatted as a JSON string"; Edm.Int64 "A 64-bit integer formatted as a JSON string"; the `d`/`results`/`__count`/
+     * `__next` envelope; the `__metadata` object ("uri", "type", "etag").
+     * spec-cite: OData Version 2.0 Overview (https://www.odata.org/documentation/odata-version-2-0/overview/) — the
+     * primitive literal forms: `datetime'yyyy-mm-ddThh:mm[:ss[.fffffff]]'`, `2.345M`, `2.0d`, `64L`, `guid'…'`,
+     * `datetimeoffset'…'`.
+     *
+     * Reads only: a binding opening writes on v2 is refused at startup (SAP's CSRF-token handshake and v2's own write
+     * shapes are the write path's, #1679), and so is an explicit-erasure stance, which is a remote DELETE.
+     */
+    HttpApiTransportDialect["ODATA_V2"] = "odata-v2";
     /**
      * 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

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

@@ -1 +1 @@
-{"version":3,"file":"http-api-transport-dialect.shared.js","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-transport-dialect.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;GAIG;AACH,MAAM,CAAN,IAAY,uBAwDX;AAxDD,WAAY,uBAAuB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,0CAAe,CAAA;IAEf;;;;OAIG;IACH,kDAAuB,CAAA;IAEvB;;;;;;;;;;;;;OAaG;IACH,wDAA6B,CAAA;AAC/B,CAAC,EAxDW,uBAAuB,KAAvB,uBAAuB,QAwDlC","sourcesContent":["/**\n * `HttpApiTransportDialect` — how the engine SPEAKS to a system of record.\n *\n * A boundary module, and the reason it is one is a package-contract rule rather than taste.\n *\n * ## Why this is not in `http-api-binding.shared.schemas.ts` any more (#1055, R3)\n *\n * That module is published ONLY through the `@wildo-ai/saas-models/external-data` subpath. The enum\n * is about to be named by the ROOT-exported application-configuration contract (`systemsOfRecord`\n * declares a dialect per instance), and a TypeScript `enum` is NOMINAL: a root-only consumer that\n * cannot name it through a public specifier gets `TS2742`/`TS2883` — \"the inferred type cannot be\n * named without a reference to …/node_modules/…\" — which is\n * `.claude/rules/package-public-entrypoints.md`'s \"root barrel must not DEPEND on a subpath-only\n * surface\", exactly.\n *\n * The rule's prescribed fix is to MOVE THE BOUNDARY, never to re-export across it: adding this module\n * to the subpath barrel as well would be `root-barrel-overlap` (a second door onto one room), which\n * `pnpm check:package-entrypoints` rule 1 refuses. So the enum lives here, the root exports it, the\n * binding schema imports it, and the subpath does NOT re-export it.\n *\n * Three root-reachable modules already cross into that subpath under `entrypoint-closure-waiver`.\n * This is the fourth crossing avoided rather than waived — and it is the one that would have put a\n * nominal enum into the most re-derived contract in the repository.\n *\n * ## What belongs here, and what does not\n *\n * ONLY the closed vocabulary. The per-dialect binding arms, the compilers and the key codecs stay\n * with the binding schema: they are the SHAPE of a declaration, not its name, and nothing\n * root-exported needs to name them.\n *\n * ## The root-only probe, measured 2026-09-15\n *\n * `package-public-entrypoints.md` asks for a measurement rather than a category judgement, so here is\n * the result. A consumer importing ONLY the package root, deriving values from this enum and emitting\n * with `declaration: true`:\n *\n * ```\n * export declare const declaredDialect = HttpApiTransportDialect.ODOO_JSONRPC;\n * export declare function pickDialect(): { dialect: HttpApiTransportDialect };\n * ```\n *\n * Zero errors, and the emitted declaration NAMES the enum through the root specifier rather than\n * reaching into a `node_modules/.../dist/esm/...` path. The same probe run before this module reached\n * the root barrel emitted `dialect: any` and `TS2305` — so the measurement has both halves, and the\n * enum is safe in a root-exported contract.\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 */\nexport enum HttpApiTransportDialect {\n  /**\n   * OData **v4** — one generic client: mechanical pushdown of\n   * `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata` boot-time\n   * verification probe of the committed declaration.\n   *\n   * ⚠ **This member is v4 ONLY, and that excludes SAP's most-used API.** An earlier revision of\n   * this comment named \"SAP S/4HANA, Microsoft Dataverse/Dynamics 365\" here, which is half right\n   * and was load-bearing — it is why nobody looked:\n   *\n   * | Target | Version | Consumable today |\n   * |---|---|---|\n   * | Microsoft Dataverse / Dynamics 365 Web API (`/api/data/v9.2/`) | v4 | ✅ |\n   * | SAP S/4HANA OData **v4** services (`/sap/opu/odata4/…`) | v4 | ✅ |\n   * | SAP `API_BUSINESS_PARTNER` (`/sap/opu/odata/sap/API_BUSINESS_PARTNER`) | **v2** | ❌ |\n   *\n   * v2 is not a v4 variant with a different header. Its collection envelope is\n   * `{ \"d\": { \"results\": [...], \"__next\": …, \"__count\": … } }` rather than\n   * `{ \"value\": [...], \"@odata.nextLink\": … }`; `Edm.DateTime` serializes as `\"/Date(<ticks>)/\"`\n   * rather than ISO 8601; `Edm.Decimal` and `Edm.Int64` serialize as JSON STRINGS rather than\n   * numbers; and JSON must be requested (`$format=json`) because v2 defaults to Atom/XML. So it\n   * changes the envelope, the paging property, the count property AND the value encoding — a\n   * reader written for one cannot read the other, and the mapping layer needs coercions the way\n   * Odoo needs `ODOO_FALSE_AS_NULL`.\n   * spec-cite: OData Version 2.0 JSON Format\n   * (https://www.odata.org/documentation/odata-version-2-0/json-format/) — the `d`/`results`/\n   * `__next`/`__count` envelope, the `/Date(<ticks>)/` DateTime literal, and Edm.Decimal /\n   * Edm.Int64 \"formatted as a JSON string\".\n   *\n   * Supporting v2 is an OPEN decision, not an oversight. Until it lands, point an ODATA binding at\n   * a v4 service: for SAP that means the OData v4 edition of the API where one is published.\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"]}
+{"version":3,"file":"http-api-transport-dialect.shared.js","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-transport-dialect.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;GAIG;AACH,MAAM,CAAN,IAAY,uBAwFX;AAxFD,WAAY,uBAAuB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0CAAe,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,gDAAqB,CAAA;IAErB;;;;OAIG;IACH,kDAAuB,CAAA;IAEvB;;;;;;;;;;;;;OAaG;IACH,wDAA6B,CAAA;AAC/B,CAAC,EAxFW,uBAAuB,KAAvB,uBAAuB,QAwFlC","sourcesContent":["/**\n * `HttpApiTransportDialect` — how the engine SPEAKS to a system of record.\n *\n * A boundary module, and the reason it is one is a package-contract rule rather than taste.\n *\n * ## Why this is not in `http-api-binding.shared.schemas.ts` any more (#1055, R3)\n *\n * That module is published ONLY through the `@wildo-ai/saas-models/external-data` subpath. The enum\n * is about to be named by the ROOT-exported application-configuration contract (`systemsOfRecord`\n * declares a dialect per instance), and a TypeScript `enum` is NOMINAL: a root-only consumer that\n * cannot name it through a public specifier gets `TS2742`/`TS2883` — \"the inferred type cannot be\n * named without a reference to …/node_modules/…\" — which is\n * `.claude/rules/package-public-entrypoints.md`'s \"root barrel must not DEPEND on a subpath-only\n * surface\", exactly.\n *\n * The rule's prescribed fix is to MOVE THE BOUNDARY, never to re-export across it: adding this module\n * to the subpath barrel as well would be `root-barrel-overlap` (a second door onto one room), which\n * `pnpm check:package-entrypoints` rule 1 refuses. So the enum lives here, the root exports it, the\n * binding schema imports it, and the subpath does NOT re-export it.\n *\n * Three root-reachable modules already cross into that subpath under `entrypoint-closure-waiver`.\n * This is the fourth crossing avoided rather than waived — and it is the one that would have put a\n * nominal enum into the most re-derived contract in the repository.\n *\n * ## What belongs here, and what does not\n *\n * ONLY the closed vocabulary. The per-dialect binding arms, the compilers and the key codecs stay\n * with the binding schema: they are the SHAPE of a declaration, not its name, and nothing\n * root-exported needs to name them.\n *\n * ## The root-only probe, measured 2026-09-15\n *\n * `package-public-entrypoints.md` asks for a measurement rather than a category judgement, so here is\n * the result. A consumer importing ONLY the package root, deriving values from this enum and emitting\n * with `declaration: true`:\n *\n * ```\n * export declare const declaredDialect = HttpApiTransportDialect.ODOO_JSONRPC;\n * export declare function pickDialect(): { dialect: HttpApiTransportDialect };\n * ```\n *\n * Zero errors, and the emitted declaration NAMES the enum through the root specifier rather than\n * reaching into a `node_modules/.../dist/esm/...` path. The same probe run before this module reached\n * the root barrel emitted `dialect: any` and `TS2305` — so the measurement has both halves, and the\n * enum is safe in a root-exported contract.\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 */\nexport enum HttpApiTransportDialect {\n  /**\n   * OData **v4** — one generic client: mechanical pushdown of\n   * `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata` boot-time\n   * verification probe of the committed declaration.\n   *\n   * ⚠ **This member is v4 ONLY; SAP's most-used API is v2 and is read through `ODATA_V2`.** An earlier revision of\n   * this comment named \"SAP S/4HANA, Microsoft Dataverse/Dynamics 365\" here, which is half right\n   * and was load-bearing — it is why nobody looked:\n   *\n   * | Target | Version | Consumable today |\n   * |---|---|---|\n   * | Microsoft Dataverse / Dynamics 365 Web API (`/api/data/v9.2/`) | v4 | ✅ |\n   * | SAP S/4HANA OData **v4** services (`/sap/opu/odata4/…`) | v4 | ✅ |\n   * | SAP `API_BUSINESS_PARTNER` (`/sap/opu/odata/sap/API_BUSINESS_PARTNER`) | **v2** | through `ODATA_V2` |\n   *\n   * v2 is not a v4 variant with a different header. Its collection envelope is\n   * `{ \"d\": { \"results\": [...], \"__next\": …, \"__count\": … } }` rather than\n   * `{ \"value\": [...], \"@odata.nextLink\": … }`; `Edm.DateTime` serializes as `\"/Date(<ticks>)/\"`\n   * rather than ISO 8601; `Edm.Decimal` and `Edm.Int64` serialize as JSON STRINGS rather than\n   * numbers; and JSON must be requested (`$format=json`) because v2 defaults to Atom/XML. So it\n   * changes the envelope, the paging property, the count property AND the value encoding — a\n   * reader written for one cannot read the other. (`ODATA_V2` decodes values at the wire from the\n   * service's `$metadata`, so no mapping-layer coercion is needed for it.)\n   * spec-cite: OData Version 2.0 JSON Format\n   * (https://www.odata.org/documentation/odata-version-2-0/json-format/) — the `d`/`results`/\n   * `__next`/`__count` envelope, the `/Date(<ticks>)/` DateTime literal, and Edm.Decimal /\n   * Edm.Int64 \"formatted as a JSON string\".\n   *\n   * v2 is its own member, {@link HttpApiTransportDialect.ODATA_V2} (#1687) — not a flag on this one. A v2 body read\n   * through an ODATA binding is still refused BY NAME at the first read, so pointing a v4 binding at a v2 root is a\n   * clear error rather than an empty page.\n   */\n  ODATA = 'odata',\n\n  /**\n   * OData **v2** (#1687) — SAP's classic Gateway services (`/sap/opu/odata/sap/<SERVICE>`), `API_BUSINESS_PARTNER`\n   * first among them. A distinct dialect because every layer differs from v4:\n   *\n   * | | v4 (`ODATA`) | v2 (`ODATA_V2`) |\n   * |---|---|---|\n   * | JSON | the default | asked for on every request (`$format=json`); the default is Atom/XML |\n   * | collection | `{ value: [...], @odata.nextLink }` | `{ d: { results: [...], __next, __count } }` |\n   * | single entity | the object | `{ d: { ... } }` |\n   * | row annotations | `@odata.*` | a `__metadata` object per row |\n   * | total | `$count=true` → `@odata.count` | `$inlinecount=allpages` → `__count` (a STRING) |\n   * | Edm.DateTime | ISO 8601 | `\"/Date(<ms>[±<minutes>])/\"` |\n   * | Edm.Int64 / Decimal / Double | JSON numbers | JSON STRINGS |\n   * | filter literals | `2026-01-05T00:00:00Z`, `5` | `datetime'2026-01-05T00:00:00'`, `5L`, `1.5M`, `guid'…'` |\n   *\n   * The engine reads the service's `$metadata` (once per client, lazily — never at boot) for each property's Edm type,\n   * because both the value decoding and the filter literal depend on it and nothing in a local field says which: a\n   * decimal and an Int32 are both `number` locally and are spelled differently on the wire.\n   * spec-cite: OData Version 2.0 JSON Format (https://www.odata.org/documentation/odata-version-2-0/json-format/) —\n   * Edm.DateTime `\"/Date(<ticks>[\"+\" | \"-\" <offset>)/\"`; Edm.Decimal \"Literal form of Edm.Decimal as used in URIs\n   * formatted as a JSON string\"; Edm.Int64 \"A 64-bit integer formatted as a JSON string\"; the `d`/`results`/`__count`/\n   * `__next` envelope; the `__metadata` object (\"uri\", \"type\", \"etag\").\n   * spec-cite: OData Version 2.0 Overview (https://www.odata.org/documentation/odata-version-2-0/overview/) — the\n   * primitive literal forms: `datetime'yyyy-mm-ddThh:mm[:ss[.fffffff]]'`, `2.345M`, `2.0d`, `64L`, `guid'…'`,\n   * `datetimeoffset'…'`.\n   *\n   * Reads only: a binding opening writes on v2 is refused at startup (SAP's CSRF-token handshake and v2's own write\n   * shapes are the write path's, #1679), and so is an explicit-erasure stance, which is a remote DELETE.\n   */\n  ODATA_V2 = 'odata-v2',\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"]}

package/dist/esm/i18n/application-config-vocabulary.shared.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The vocabularies whose NAME the framework owns and whose VALUES an application declares. "Config" is meant broadly:
+ * an application's declarations, in its configuration (`agentWorkReview.reasonCodes`, `organizationTypes`) or in what
+ * its backend modules register (a gate's `pauseStates`, #1864).
+ *
+ * The labelling planner reads each one's values where the application declares them — the configuration, or the
+ * backend introspection for a gate's pause states — and words them under `system_enums.<name>.<value>`, and a surface
+ * that shows one of the values reads the same key. So a value the application declares is worded the moment it is
+ * declared, and one it removes stops being planned, with no list of the application's values kept anywhere.
+ *
+ * The engine's own open vocabularies, whose values the ENGINE declares, are `EngineOpenVocabulary`.
+ *
+ * Kept in its own file with no imports, so a schema can name its vocabulary without importing anything else.
+ */
+export declare enum ApplicationConfigVocabulary {
+    /** The reasons an expert may give for correcting an agent's work (`agentWorkReview.reasonCodes`, #1921). */
+    AGENT_WORK_REASON_CODE = "AgentWorkReasonCode",
+    /** The organization types an application declares (`organizationTypes`, keyed by type): an organization's `type` (#1851). */
+    ORGANIZATION_TYPE = "OrganizationType",
+    /**
+     * Why a reviewer may stop a decision's clocks: the pause states every approval gate declares
+     * (`humanApproval.deadlines.pauseStates` on a function tool, #1864). The approval inbox's Pause choice and its
+     * "clocks paused" line read each state's word.
+     */
+    HUMAN_DECISION_PAUSE_STATE = "HumanDecisionPauseState"
+}
+/**
+ * What a value of a declared vocabulary may contain: it is also the LAST SEGMENT of its label key
+ * (`system_enums.<name>.<value>`), and the label tree is addressed by dotted path. A dotted value would name a label
+ * nobody could resolve, so it would render raw forever with nothing reporting why; every declaration of an
+ * `ApplicationConfigVocabulary` value refuses one that fails this test. One source, so the declarations cannot drift.
+ */
+export declare const LABEL_KEY_SEGMENT_PATTERN: RegExp;
+/** Whether `value` can be the last segment of a label key — see `LABEL_KEY_SEGMENT_PATTERN`. */
+export declare function isLabelKeySegment(value: string): boolean;
+//# sourceMappingURL=application-config-vocabulary.shared.d.ts.map

package/dist/esm/i18n/application-config-vocabulary.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-config-vocabulary.shared.d.ts","sourceRoot":"","sources":["../../../../src/i18n/application-config-vocabulary.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,oBAAY,2BAA2B;IACrC,4GAA4G;IAC5G,sBAAsB,wBAAwB;IAC9C,6HAA6H;IAC7H,iBAAiB,qBAAqB;IACtC;;;;OAIG;IACH,0BAA0B,4BAA4B;CACvD;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAA2B,CAAC;AAEpE,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/dist/esm/i18n/application-config-vocabulary.shared.js

@@ -0,0 +1,39 @@
+/**
+ * The vocabularies whose NAME the framework owns and whose VALUES an application declares. "Config" is meant broadly:
+ * an application's declarations, in its configuration (`agentWorkReview.reasonCodes`, `organizationTypes`) or in what
+ * its backend modules register (a gate's `pauseStates`, #1864).
+ *
+ * The labelling planner reads each one's values where the application declares them — the configuration, or the
+ * backend introspection for a gate's pause states — and words them under `system_enums.<name>.<value>`, and a surface
+ * that shows one of the values reads the same key. So a value the application declares is worded the moment it is
+ * declared, and one it removes stops being planned, with no list of the application's values kept anywhere.
+ *
+ * The engine's own open vocabularies, whose values the ENGINE declares, are `EngineOpenVocabulary`.
+ *
+ * Kept in its own file with no imports, so a schema can name its vocabulary without importing anything else.
+ */
+export var ApplicationConfigVocabulary;
+(function (ApplicationConfigVocabulary) {
+    /** The reasons an expert may give for correcting an agent's work (`agentWorkReview.reasonCodes`, #1921). */
+    ApplicationConfigVocabulary["AGENT_WORK_REASON_CODE"] = "AgentWorkReasonCode";
+    /** The organization types an application declares (`organizationTypes`, keyed by type): an organization's `type` (#1851). */
+    ApplicationConfigVocabulary["ORGANIZATION_TYPE"] = "OrganizationType";
+    /**
+     * Why a reviewer may stop a decision's clocks: the pause states every approval gate declares
+     * (`humanApproval.deadlines.pauseStates` on a function tool, #1864). The approval inbox's Pause choice and its
+     * "clocks paused" line read each state's word.
+     */
+    ApplicationConfigVocabulary["HUMAN_DECISION_PAUSE_STATE"] = "HumanDecisionPauseState";
+})(ApplicationConfigVocabulary || (ApplicationConfigVocabulary = {}));
+/**
+ * What a value of a declared vocabulary may contain: it is also the LAST SEGMENT of its label key
+ * (`system_enums.<name>.<value>`), and the label tree is addressed by dotted path. A dotted value would name a label
+ * nobody could resolve, so it would render raw forever with nothing reporting why; every declaration of an
+ * `ApplicationConfigVocabulary` value refuses one that fails this test. One source, so the declarations cannot drift.
+ */
+export const LABEL_KEY_SEGMENT_PATTERN = /^[A-Za-z0-9_-]+$/;
+/** Whether `value` can be the last segment of a label key — see `LABEL_KEY_SEGMENT_PATTERN`. */
+export function isLabelKeySegment(value) {
+    return LABEL_KEY_SEGMENT_PATTERN.test(value);
+}
+//# sourceMappingURL=application-config-vocabulary.shared.js.map

package/dist/esm/i18n/application-config-vocabulary.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-config-vocabulary.shared.js","sourceRoot":"","sources":["../../../../src/i18n/application-config-vocabulary.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAN,IAAY,2BAWX;AAXD,WAAY,2BAA2B;IACrC,4GAA4G;IAC5G,6EAA8C,CAAA;IAC9C,6HAA6H;IAC7H,qEAAsC,CAAA;IACtC;;;;OAIG;IACH,qFAAsD,CAAA;AACxD,CAAC,EAXW,2BAA2B,KAA3B,2BAA2B,QAWtC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAW,kBAAkB,CAAC;AAEpE,gGAAgG;AAChG,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC","sourcesContent":["/**\n * The vocabularies whose NAME the framework owns and whose VALUES an application declares. \"Config\" is meant broadly:\n * an application's declarations, in its configuration (`agentWorkReview.reasonCodes`, `organizationTypes`) or in what\n * its backend modules register (a gate's `pauseStates`, #1864).\n *\n * The labelling planner reads each one's values where the application declares them — the configuration, or the\n * backend introspection for a gate's pause states — and words them under `system_enums.<name>.<value>`, and a surface\n * that shows one of the values reads the same key. So a value the application declares is worded the moment it is\n * declared, and one it removes stops being planned, with no list of the application's values kept anywhere.\n *\n * The engine's own open vocabularies, whose values the ENGINE declares, are `EngineOpenVocabulary`.\n *\n * Kept in its own file with no imports, so a schema can name its vocabulary without importing anything else.\n */\nexport enum ApplicationConfigVocabulary {\n  /** The reasons an expert may give for correcting an agent's work (`agentWorkReview.reasonCodes`, #1921). */\n  AGENT_WORK_REASON_CODE = 'AgentWorkReasonCode',\n  /** The organization types an application declares (`organizationTypes`, keyed by type): an organization's `type` (#1851). */\n  ORGANIZATION_TYPE = 'OrganizationType',\n  /**\n   * Why a reviewer may stop a decision's clocks: the pause states every approval gate declares\n   * (`humanApproval.deadlines.pauseStates` on a function tool, #1864). The approval inbox's Pause choice and its\n   * \"clocks paused\" line read each state's word.\n   */\n  HUMAN_DECISION_PAUSE_STATE = 'HumanDecisionPauseState',\n}\n\n/**\n * What a value of a declared vocabulary may contain: it is also the LAST SEGMENT of its label key\n * (`system_enums.<name>.<value>`), and the label tree is addressed by dotted path. A dotted value would name a label\n * nobody could resolve, so it would render raw forever with nothing reporting why; every declaration of an\n * `ApplicationConfigVocabulary` value refuses one that fails this test. One source, so the declarations cannot drift.\n */\nexport const LABEL_KEY_SEGMENT_PATTERN: RegExp = /^[A-Za-z0-9_-]+$/;\n\n/** Whether `value` can be the last segment of a label key — see `LABEL_KEY_SEGMENT_PATTERN`. */\nexport function isLabelKeySegment(value: string): boolean {\n  return LABEL_KEY_SEGMENT_PATTERN.test(value);\n}\n"]}

package/dist/esm/i18n/engine-open-vocabulary-values.shared.d.ts

@@ -0,0 +1,11 @@
+import { EngineOpenVocabulary } from './engine-open-vocabulary.shared';
+/**
+ * The values of each {@link EngineOpenVocabulary}, which the labelling planner words under
+ * `system_enums.<name>.<value>` for every application (#1791).
+ *
+ * A `Record` keyed on the enum, so a vocabulary added there without its values is a compile error here rather
+ * than a vocabulary that renders its identifiers for ever. Derived from the engine's own enums, so a member added
+ * to one of them is planned on the next labelling run with no edit here.
+ */
+export declare const ENGINE_OPEN_VOCABULARY_VALUES: Readonly<Record<EngineOpenVocabulary, readonly string[]>>;
+//# sourceMappingURL=engine-open-vocabulary-values.shared.d.ts.map

package/dist/esm/i18n/engine-open-vocabulary-values.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-open-vocabulary-values.shared.d.ts","sourceRoot":"","sources":["../../../../src/i18n/engine-open-vocabulary-values.shared.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC,CAEnG,CAAC"}

package/dist/esm/i18n/engine-open-vocabulary-values.shared.js

@@ -0,0 +1,14 @@
+import { CoreAuditableEventType } from '../compliance/audit-trails/auditable-events.shared.schema.js';
+import { EngineOpenVocabulary } from './engine-open-vocabulary.shared.js';
+/**
+ * The values of each {@link EngineOpenVocabulary}, which the labelling planner words under
+ * `system_enums.<name>.<value>` for every application (#1791).
+ *
+ * A `Record` keyed on the enum, so a vocabulary added there without its values is a compile error here rather
+ * than a vocabulary that renders its identifiers for ever. Derived from the engine's own enums, so a member added
+ * to one of them is planned on the next labelling run with no edit here.
+ */
+export const ENGINE_OPEN_VOCABULARY_VALUES = {
+    [EngineOpenVocabulary.CORE_AUDITABLE_EVENT_TYPE]: Object.values(CoreAuditableEventType),
+};
+//# sourceMappingURL=engine-open-vocabulary-values.shared.js.map

package/dist/esm/i18n/engine-open-vocabulary-values.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-open-vocabulary-values.shared.js","sourceRoot":"","sources":["../../../../src/i18n/engine-open-vocabulary-values.shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,2DAA2D,CAAC;AACnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAA8D;IACtG,CAAC,oBAAoB,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC;CACxF,CAAC","sourcesContent":["import { CoreAuditableEventType } from '../compliance/audit-trails/auditable-events.shared.schema';\nimport { EngineOpenVocabulary } from './engine-open-vocabulary.shared';\n\n/**\n * The values of each {@link EngineOpenVocabulary}, which the labelling planner words under\n * `system_enums.<name>.<value>` for every application (#1791).\n *\n * A `Record` keyed on the enum, so a vocabulary added there without its values is a compile error here rather\n * than a vocabulary that renders its identifiers for ever. Derived from the engine's own enums, so a member added\n * to one of them is planned on the next labelling run with no edit here.\n */\nexport const ENGINE_OPEN_VOCABULARY_VALUES: Readonly<Record<EngineOpenVocabulary, readonly string[]>> = {\n  [EngineOpenVocabulary.CORE_AUDITABLE_EVENT_TYPE]: Object.values(CoreAuditableEventType),\n};\n"]}

package/dist/esm/i18n/engine-open-vocabulary.shared.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The engine's OPEN vocabularies (#1791): named sets of values that a STRING field carries and the engine declares
+ * outside any schema.
+ *
+ * `z.enum` is how a field normally names its vocabulary, and it lets the labeller read the values off the field.
+ * Some fields cannot be an enum because the schema does not own their values. An audit event's `eventType` is a
+ * string, because an event type is written by whoever emits it. Such a field declares its vocabulary with
+ * `.systemEnum(EngineOpenVocabulary.X)`: the display reads `system_enums.<name>.<value>`, and the labeller plans
+ * those keys from {@link ENGINE_OPEN_VOCABULARY_VALUES}, the one place the values are listed.
+ *
+ * A vocabulary whose values an APPLICATION declares is not here: those are `ApplicationConfigVocabulary`, and the
+ * labeller reads their values from the application's configuration.
+ *
+ * Kept in its own file with no imports, so a schema can name its vocabulary without importing the values.
+ */
+export declare enum EngineOpenVocabulary {
+    /** Every `CoreAuditableEventType` the engine emits: the words an audit trail shows for an event. */
+    CORE_AUDITABLE_EVENT_TYPE = "CoreAuditableEventType"
+}
+//# sourceMappingURL=engine-open-vocabulary.shared.d.ts.map

package/dist/esm/i18n/engine-open-vocabulary.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-open-vocabulary.shared.d.ts","sourceRoot":"","sources":["../../../../src/i18n/engine-open-vocabulary.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,oBAAY,oBAAoB;IAC9B,oGAAoG;IACpG,yBAAyB,2BAA2B;CACrD"}