@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/systems-of-record/system-of-record-facet.shared.schemas.js

@@ -0,0 +1,619 @@
+/**
+ * `SystemOfRecordVendorFacet` — what a VENDOR is, as a system of record.
+ *
+ * Four concepts carry one job each in this lane (#1049 §4.1, #1055): the **external-data lane** (the
+ * engine runtime), a **dialect adapter** (how to speak — `HttpApiTransportDialect`), a **vendor
+ * facet** (this module: what the vendor needs to be addressed and believed), and a **system of
+ * record** — a named, declared INSTANCE that resources bind by name.
+ *
+ * ## What a facet is NOT
+ *
+ * It is not a provider. A provider is selected through a capability plane, may carry a person's
+ * lent credential, and has an operation catalogue; a system of record is a named deployment the
+ * application reads its own business rows out of, spending its own service identity (D10, D12).
+ * Nothing in this module may reach the provider registry, and the reverse import is what
+ * `pnpm check:systems-of-record-separation` refuses.
+ *
+ * It is also not an INSTANCE. The facet says "an Odoo needs a base URL, a database and a login, and
+ * offers the in-args API-key credential"; it never says WHICH Odoo. Two instances of one vendor
+ * (`odoo-fr`, `odoo-de`) share this facet and differ only in their addresses and secrets — which is
+ * the whole reason the instance is a separate concept from the vendor.
+ *
+ * ## Why this lives in `@wildo-ai/saas-models/external-data` (#1055 R2)
+ *
+ * The obvious home looks like `external-connectors-models`, beside the provider contracts. It
+ * cannot be: that package depends only on `zod-decorators` and its own header forbids reaching
+ * saas-models, while a facet is typed against `HttpApiTransportDialect`, which lives here. It is
+ * also not `ProviderMetadata`-shaped, which is bundle-fenced. So the facet sits beside the binding
+ * schema it serves, on the subpath whose two audiences — the app author and the backend — are
+ * exactly the audiences a facet has.
+ *
+ * Note the split with the two VOCABULARIES it names: `HttpApiTransportDialect` and
+ * `SystemOfRecordCredentialKind` are root-exported boundary modules, because the root-exported
+ * `systemsOfRecord` declaration names them. The SHAPES here are subpath-only, because nothing
+ * root-exported names a slot.
+ *
+ * ## Slots, and why their slugs are lowerCamelCase with nothing else in them
+ *
+ * A slot's slug becomes half of a derived environment-variable name, `WILDO_SOR_<NAME>__<SLOT>`
+ * (#1055 R4). The instance name admits `-` and the slug admits neither `-` nor `_`, so the DOUBLE
+ * underscore between them is a delimiter neither half can produce: the pair is recoverable from
+ * the variable name, and `odoo-api` + `key` can never collide with `odoo` + `apiKey`. That property
+ * is the reason for the regex, so widening it would silently reintroduce the collision.
+ *
+ * ## Partitioning LANDED in #1058, and was held back until it had a reader
+ *
+ * The facet is the single partition authority — which remote field carries the tenant, how it is
+ * encoded — and that vocabulary arrived with the slice that first READS it. It is `partition`
+ * below, and the INSTANCE-side opt-in is now honoured rather than refused at declaration.
+ *
+ * It was withheld until then on purpose, and the reasoning is kept because it is the general rule:
+ * shipping a four-member vocabulary with no reader is the "declared surface with nothing behind
+ * it" shape this repository keeps paying for. It landed additively, as an OPTIONAL field, so every
+ * facet written against the earlier shape still parses.
+ */
+// Side-effect import: this module calls `.systemEnum()` at load, so the decorators must be installed first —
+// never by the importer's luck (#966). A named import used only as a type would be elided and install nothing.
+import '@wildo-ai/zod-decorators';
+import { z } from 'zod';
+import { HttpApiTransportDialect } from '../http-api-binding/http-api-transport-dialect.shared.js';
+import { HttpApiKeyComponentCodec } from '../http-api-binding/http-api-binding.shared.schemas.js';
+import { SystemOfRecordCredentialKind } from './system-of-record-credential-kind.shared.js';
+import { SYSTEM_OF_RECORD_ENABLED_SLOT, SYSTEM_OF_RECORD_SLOT_SLUG_PATTERN, deriveSystemOfRecordEnabledEnvVarName } from './system-of-record-env.shared.js';
+/** @wildo_source:part:start saas.models.systems-of-record facet:layer:shared facet:audience:app-developer */
+/**
+ * One input an instance must supply — an address slot (non-secret, authored in the infra env
+ * config) or a secret slot (authored in `secrets.json`). Both halves share this shape because both
+ * derive an environment-variable name the same way; what differs is WHERE the value is authored and
+ * whether it is ever printed.
+ */
+export const SystemOfRecordSlotSchema = z.strictObject({
+    /**
+     * lowerCamelCase, and nothing else — see the module header. Becomes the `<SLOT>` half of
+     * `WILDO_SOR_<NAME>__<SLOT>` by upper-snake-casing.
+     */
+    slug: z
+        .string()
+        .regex(SYSTEM_OF_RECORD_SLOT_SLUG_PATTERN, 'A slot slug is lowerCamelCase with no separators.')
+        .max(40)
+        .refine((slug) => slug !== SYSTEM_OF_RECORD_ENABLED_SLOT, {
+        error: `"${SYSTEM_OF_RECORD_ENABLED_SLOT}" is reserved: the environment builder emits `
+            + `${deriveSystemOfRecordEnabledEnvVarName('example')} itself to say an environment has no access to an instance. `
+            + 'A slot of that name would make "declared absent" indistinguishable from an address whose value happens to be false.',
+    }),
+    /**
+     * Whether an instance MUST supply it. A missing required slot refuses at `wildo config sync` and
+     * again at boot (#1055 E4) — the remedy is authoring a value, which needs no running companion,
+     * so refusing is legitimate there.
+     */
+    required: z.boolean(),
+    /** What an operator must put in it. Printed by sync and by the secrets report. */
+    description: z.string().min(1),
+});
+/**
+ * A slot list that cannot be order-dependent or ambiguous: sorted by slug, slugs unique.
+ *
+ * Mirrors `ProviderSecretContractShapeSchema`, and for the same reason — these lists are compared,
+ * reported and (once #1057 lands) contributed by independently-versioned packages, so two facets
+ * declaring the same slots in different orders must not be two different things.
+ */
+const systemOfRecordSlotListSchema = (label) => z.array(SystemOfRecordSlotSchema).superRefine((slots, context) => {
+    const seen = new Set();
+    for (const [index, slot] of slots.entries()) {
+        if (seen.has(slot.slug)) {
+            context.addIssue({ code: 'custom', path: [index, 'slug'], message: `Duplicate ${label} slot "${slot.slug}".` });
+        }
+        seen.add(slot.slug);
+        if (index > 0 && slots[index - 1].slug.localeCompare(slot.slug) >= 0) {
+            context.addIssue({ code: 'custom', path: [index, 'slug'], message: `${label} slots must be sorted by slug.` });
+        }
+    }
+});
+/**
+ * What ONE credential kind needs, independent of vendor (#1055 R15).
+ *
+ * The kind owns its secrets and any address slot that exists only because the kind was chosen — a
+ * future `OAUTH2_CLIENT_CREDENTIALS` owns `tokenUrl`, which no vendor would declare if it were
+ * reached with a static key. `ODOO_API_KEY_IN_ARGS` needs no address slot of its own, and that is
+ * the seam rather than an omission: its `database` and `login` inputs identify WHICH Odoo and WHICH
+ * user, so they belong to the vendor and would survive a second Odoo credential kind.
+ */
+export const SystemOfRecordCredentialKindContractSchema = z.strictObject({
+    addressSlots: systemOfRecordSlotListSchema('credential address'),
+    secretSlots: systemOfRecordSlotListSchema('credential secret'),
+});
+/**
+ * Every credential kind's inputs. Engine-owned and CLOSED, keyed by the enum so a member added
+ * without a contract is a compile error rather than a boot surprise.
+ *
+ * ## Which half a slot lands in, since the answer is not "is it secret"
+ *
+ * The split follows the precedent #1055 set with Odoo's `login`: **an identity slot is an ADDRESS
+ * slot and a proof slot is a SECRET slot.** A `clientId` and a BASIC `username` are not
+ * confidential — they name WHICH client and WHICH user — and putting them in `secrets.json` would
+ * hide, from every diff and every environment review, the one thing an operator most often needs to
+ * check. What must never be printed is the half that PROVES the identity.
+ *
+ * The consequence is that a credential's two halves are authored in two files. That is deliberate
+ * and it is the same shape Odoo already has (`login` in the infra config, `apiKey` in the secrets),
+ * so an operator meets one convention rather than two.
+ *
+ * ## Required-ness that a static list cannot express
+ *
+ * Three slots are declared `required: false` here and are made required by the FACET's offer, which
+ * is the only place that knows: `certificateKeyId` when the vendor's assertion header policy is
+ * {@link SystemOfRecordAssertionHeaderPolicy.KEY_ID_SUPPLIED}, `certificatePem` when it is
+ * `X509_THUMBPRINT_DERIVED`, and `subject` for the JWT-bearer grant's `sub`. The join is performed
+ * ONCE, in {@link resolveSystemOfRecordInstanceSlots}, rather than by each of the five readers of
+ * "what does this instance need" — which is the enumeration failure
+ * `invariant-call-site-enumeration.md` exists to stop.
+ */
+export const SYSTEM_OF_RECORD_CREDENTIAL_KIND_CONTRACTS = {
+    [SystemOfRecordCredentialKind.ODOO_API_KEY_IN_ARGS]: {
+        addressSlots: [],
+        secretSlots: [
+            {
+                slug: 'apiKey',
+                required: true,
+                description: 'Odoo external-API key (Settings → Users → API Keys). It replaces the password in '
+                    + '`common.authenticate` and rides as a positional argument of every `execute_kw` call.',
+            },
+        ],
+    },
+    [SystemOfRecordCredentialKind.API_KEY_HEADER]: {
+        addressSlots: [],
+        secretSlots: [
+            {
+                slug: 'apiKey',
+                required: true,
+                description: 'The static key this deployment presents. It travels in the header the vendor facet names — '
+                    + 'the operator never chooses the header, only supplies the key.',
+            },
+        ],
+    },
+    [SystemOfRecordCredentialKind.API_KEY_QUERY]: {
+        addressSlots: [],
+        secretSlots: [
+            {
+                slug: 'apiKey',
+                required: true,
+                description: 'The static key this deployment presents, appended as the query parameter the vendor facet '
+                    + 'names. Weaker than a header — a URL reaches access logs and proxy logs — so prefer a '
+                    + 'header kind when the vendor offers one.',
+            },
+        ],
+    },
+    [SystemOfRecordCredentialKind.BASIC]: {
+        addressSlots: [
+            {
+                slug: 'username',
+                required: true,
+                description: 'The user this deployment authenticates as (SAP calls it a communication user). It names an '
+                    + 'identity rather than proving one, so it is authored in the environment config beside the '
+                    + 'base URL. It may not contain ":" — RFC 7617 makes the colon the delimiter.',
+            },
+        ],
+        secretSlots: [
+            { slug: 'password', required: true, description: "That user's password. Half of one credential; rotate it with the username only if the vendor requires." },
+        ],
+    },
+    [SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_SECRET]: {
+        addressSlots: [
+            { slug: 'audience', required: false, description: 'The `audience` / `resource` parameter, when the vendor requires one to scope the token (Entra names the resource; Salesforce does not).' },
+            { slug: 'clientId', required: true, description: 'The registered application (client) id. Names WHICH client, so it is addressing rather than proof.' },
+            { slug: 'scope', required: false, description: 'Space-delimited scopes to request. Omitted when the vendor derives them from the client registration.' },
+            { slug: 'tokenUrl', required: true, description: "The token endpoint's absolute URL. Kind-owned: no vendor would declare it if the instance were reached with a static key." },
+        ],
+        secretSlots: [
+            { slug: 'clientSecret', required: true, description: 'The client secret issued with the client id. This is the half that proves the identity, and the only half that is never printed.' },
+        ],
+    },
+    [SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_CERTIFICATE]: {
+        addressSlots: [
+            { slug: 'audience', required: false, description: 'The `audience` / `resource` parameter when the vendor requires one.' },
+            {
+                slug: 'certificateKeyId',
+                required: false,
+                description: 'The key id the vendor assigned to this certificate, placed in the assertion\'s protected '
+                    + 'header as `kid` (NetSuite issues one at upload). REQUIRED when the vendor facet declares '
+                    + 'the key-id header policy; unused otherwise.',
+            },
+            {
+                slug: 'certificatePem',
+                required: false,
+                description: 'The PUBLIC certificate in PEM, used to derive the `x5t` thumbprint the assertion header '
+                    + 'carries. REQUIRED when the vendor facet declares the thumbprint header policy; unused '
+                    + 'otherwise. Public material, so it is an address slot rather than a secret.',
+            },
+            { slug: 'clientId', required: true, description: 'The registered application (client) id — the assertion\'s `iss` and `sub`.' },
+            { slug: 'scope', required: false, description: 'Space-delimited scopes to request.' },
+            { slug: 'tokenUrl', required: true, description: "The token endpoint's absolute URL, and the assertion's `aud`." },
+        ],
+        secretSlots: [
+            {
+                slug: 'privateKeyPem',
+                required: true,
+                description: 'The UNENCRYPTED PKCS#8 private key, in PEM, that signs the client assertion. An '
+                    + 'encrypted key is refused by name: the secret channel is the protection, and a passphrase '
+                    + 'stored beside the key it protects protects nothing.',
+            },
+        ],
+    },
+    [SystemOfRecordCredentialKind.OAUTH2_JWT_BEARER]: {
+        addressSlots: [
+            { slug: 'audience', required: false, description: 'The assertion\'s `aud`, when it differs from the token endpoint (Salesforce wants the login host).' },
+            { slug: 'clientId', required: true, description: 'The connected app\'s consumer key — the assertion\'s `iss`.' },
+            { slug: 'scope', required: false, description: 'Space-delimited scopes to request.' },
+            {
+                slug: 'subject',
+                required: false,
+                description: 'The user the assertion is made FOR — its `sub`. REQUIRED for this grant and declared '
+                    + 'optional here only because the facet\'s offer is what asserts it; a service account\'s '
+                    + 'username on the vendor side.',
+            },
+            { slug: 'tokenUrl', required: true, description: "The token endpoint's absolute URL." },
+        ],
+        secretSlots: [
+            { slug: 'privateKeyPem', required: true, description: 'The UNENCRYPTED PKCS#8 private key, in PEM, that signs the assertion. An encrypted key is refused by name.' },
+        ],
+    },
+};
+/**
+ * How a vendor wants a client assertion's PROTECTED HEADER built (#1056 R2).
+ *
+ * A generic "sign it with the private key" is rejected by both vendors that want an assertion, and
+ * they want DIFFERENT things — which is why this is a facet policy rather than an engine constant.
+ */
+export var SystemOfRecordAssertionHeaderPolicy;
+(function (SystemOfRecordAssertionHeaderPolicy) {
+    /** `kid` carries a key id the VENDOR assigned when the certificate was uploaded (NetSuite). */
+    SystemOfRecordAssertionHeaderPolicy["KEY_ID_SUPPLIED"] = "key-id-supplied";
+    /**
+     * `x5t` carries the base64url SHA-1 thumbprint of the certificate, DERIVED by the engine from the
+     * supplied `certificatePem` (Microsoft Entra's certificate credential).
+     *
+     * SHA-1 is not a security choice here: `x5t` is defined as a SHA-1 thumbprint (RFC 7515 §4.1.7)
+     * and is an identifier for locating a key, never an integrity proof.
+     * spec-cite: RFC 7515 §4.1.7 ("x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter).
+     */
+    SystemOfRecordAssertionHeaderPolicy["X509_THUMBPRINT_DERIVED"] = "x509-thumbprint-derived";
+})(SystemOfRecordAssertionHeaderPolicy || (SystemOfRecordAssertionHeaderPolicy = {}));
+/**
+ * Where a client's id and secret travel on a client-credentials token request.
+ *
+ * RFC 6749 §2.3.1 permits BOTH and says a server MUST support the Basic header while it MAY support
+ * the body form — and real vendors differ, so the choice cannot be an engine default.
+ * spec-cite: RFC 6749 §2.3.1 (Client Password).
+ */
+export var SystemOfRecordClientAuthenticationPlacement;
+(function (SystemOfRecordClientAuthenticationPlacement) {
+    /** `client_id` and `client_secret` as form fields in the request body. */
+    SystemOfRecordClientAuthenticationPlacement["REQUEST_BODY"] = "request-body";
+    /** `Authorization: Basic base64(client_id ":" client_secret)`. */
+    SystemOfRecordClientAuthenticationPlacement["BASIC_HEADER"] = "basic-header";
+})(SystemOfRecordClientAuthenticationPlacement || (SystemOfRecordClientAuthenticationPlacement = {}));
+/**
+ * The algorithms an assertion may be signed with. Asymmetric ONLY, and that is the point: a
+ * symmetric `HS*` assertion is signed with a shared secret, which makes the assertion no stronger
+ * than the secret it was supposed to replace, and `none` is not an algorithm.
+ */
+export var SystemOfRecordAssertionSigningAlgorithm;
+(function (SystemOfRecordAssertionSigningAlgorithm) {
+    SystemOfRecordAssertionSigningAlgorithm["RS256"] = "RS256";
+    SystemOfRecordAssertionSigningAlgorithm["RS384"] = "RS384";
+    SystemOfRecordAssertionSigningAlgorithm["RS512"] = "RS512";
+    SystemOfRecordAssertionSigningAlgorithm["PS256"] = "PS256";
+    SystemOfRecordAssertionSigningAlgorithm["ES256"] = "ES256";
+    SystemOfRecordAssertionSigningAlgorithm["ES384"] = "ES384";
+    SystemOfRecordAssertionSigningAlgorithm["ES512"] = "ES512";
+})(SystemOfRecordAssertionSigningAlgorithm || (SystemOfRecordAssertionSigningAlgorithm = {}));
+/**
+ * How long to treat a token as valid when the answer carries no `expires_in` (#1056 R3).
+ *
+ * A FACET property rather than a per-kind engine constant, because two vendors of the SAME kind
+ * disagree: NetSuite's answer states `expires_in` is always 3600, while Salesforce's
+ * client-credentials answer is reported to omit it. A per-kind constant would have to be wrong for
+ * one of them.
+ */
+const tokenLifetimeFallbackSecondsSchema = z.number().int().min(30).max(86_400);
+/**
+ * ONE credential kind as ONE vendor offers it — the kind, plus everything about it that varies by
+ * VENDOR and not by deployment.
+ *
+ * A discriminated union rather than a kind list beside a policy map, so a policy cannot exist
+ * without its kind and a kind cannot be offered without the policy it needs. `API_KEY_HEADER` with
+ * no header name is unrepresentable here; under a parallel map it would parse and fail at the first
+ * read.
+ */
+export const SystemOfRecordCredentialOfferSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal(SystemOfRecordCredentialKind.ODOO_API_KEY_IN_ARGS).systemEnum('SystemOfRecordCredentialKind') }),
+    z.strictObject({
+        kind: z.literal(SystemOfRecordCredentialKind.API_KEY_HEADER).systemEnum('SystemOfRecordCredentialKind'),
+        /** The header the key travels in — `Authorization`, `X-API-Key`, `apikey`, whatever the vendor reads. */
+        headerName: z.string().regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/, 'A header name is an RFC 9110 token.').max(64),
+        /** What precedes the key in the header value, INCLUDING its trailing space (`"Bearer "`). Omitted when the key stands alone. */
+        valuePrefix: z.string().max(32).optional(),
+    }),
+    z.strictObject({
+        kind: z.literal(SystemOfRecordCredentialKind.API_KEY_QUERY).systemEnum('SystemOfRecordCredentialKind'),
+        /** The query parameter the key is appended as. */
+        parameterName: z.string().regex(/^[A-Za-z0-9_.-]+$/, 'A query parameter name is alphanumeric with -._').max(64),
+    }),
+    z.strictObject({ kind: z.literal(SystemOfRecordCredentialKind.BASIC).systemEnum('SystemOfRecordCredentialKind') }),
+    z.strictObject({
+        kind: z.literal(SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_SECRET).systemEnum('SystemOfRecordCredentialKind'),
+        clientAuthentication: z.enum(SystemOfRecordClientAuthenticationPlacement),
+        tokenLifetimeFallbackSeconds: tokenLifetimeFallbackSecondsSchema,
+    }),
+    z.strictObject({
+        kind: z.literal(SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_CERTIFICATE).systemEnum('SystemOfRecordCredentialKind'),
+        assertionHeaderPolicy: z.enum(SystemOfRecordAssertionHeaderPolicy),
+        assertionSigningAlgorithm: z.enum(SystemOfRecordAssertionSigningAlgorithm),
+        /** How long the ASSERTION is valid — minutes, not hours; it is consumed once at the token endpoint. */
+        assertionLifetimeSeconds: z.number().int().min(30).max(600),
+        tokenLifetimeFallbackSeconds: tokenLifetimeFallbackSecondsSchema,
+    }),
+    z.strictObject({
+        kind: z.literal(SystemOfRecordCredentialKind.OAUTH2_JWT_BEARER).systemEnum('SystemOfRecordCredentialKind'),
+        assertionSigningAlgorithm: z.enum(SystemOfRecordAssertionSigningAlgorithm),
+        assertionLifetimeSeconds: z.number().int().min(30).max(600),
+        tokenLifetimeFallbackSeconds: tokenLifetimeFallbackSecondsSchema,
+    }),
+]);
+/**
+ * How a vendor's OData service pages a COLLECTION READ (#1292).
+ *
+ * A vendor property rather than a dialect constant, and the reason is one large implementation: the
+ * Microsoft Dataverse Web API refuses `$skip` outright, while OData v4 defines it and a conformant
+ * service serves it. A per-dialect default would have to be wrong for one of them — the same
+ * argument #1056 R3 settled for the token-lifetime fallback.
+ *
+ * spec-cite: OData Version 4.01 Part 1: Protocol §11.2.6 ("$top and $skip") for the default; Microsoft
+ * Learn, "Query data using the Web API"
+ * (https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/query-data-web-api) for
+ * the refusal — that page enumerates the query options the Web API does not support.
+ */
+export var SystemOfRecordODataListPaging;
+(function (SystemOfRecordODataListPaging) {
+    /**
+     * `$top` + `$skip` — one request for any page, which is what a page-numbered contract wants.
+     *
+     * The default, because it is what OData v4 defines and what an uncatalogued service serves.
+     */
+    SystemOfRecordODataListPaging["SKIP"] = "skip";
+    /**
+     * `@odata.nextLink` only: the service hands back a continuation URL and refuses to be addressed by
+     * offset.
+     *
+     * The consequence is structural rather than a detail — a cursor has no page NUMBER, so page N costs
+     * N requests. The engine walks forward and refuses past a bound rather than pretending otherwise.
+     */
+    SystemOfRecordODataListPaging["NEXT_LINK_ONLY"] = "next-link-only";
+})(SystemOfRecordODataListPaging || (SystemOfRecordODataListPaging = {}));
+/**
+ * HOW a vendor partitions the data one deployment holds (#1058).
+ *
+ * Inside ONE corporate, a system of record usually holds several partitions — Odoo companies, SAP
+ * company codes, Dynamics business units, NetSuite subsidiaries. They are not tenants: they all
+ * belong to the operator, which is why they map onto ORGANIZATION UNITS of the owner organization
+ * rather than onto organizations (#1049 Q3).
+ */
+export var SystemOfRecordPartitionKind;
+(function (SystemOfRecordPartitionKind) {
+    /**
+     * A FIELD on every row carries the partition (Odoo `company_id`, NetSuite `subsidiary`). The only
+     * kind supported today: it is filterable, so the confinement can be PUSHED DOWN and a caller never
+     * receives rows of a partition they may not see.
+     */
+    SystemOfRecordPartitionKind["FIELD"] = "field";
+    /**
+     * The partition is a PATH SEGMENT of the request (Business Central's `/companies({id})/customers`).
+     *
+     * Declared so a facet can be HONEST about a vendor this engine cannot confine yet, and refused by
+     * name where a partition is opted into. A path segment is chosen before the request is built, so it
+     * cannot express "these three companies" in one read — the confinement would have to fan out into
+     * one request per unit, which is a different mechanism rather than a different predicate.
+     */
+    SystemOfRecordPartitionKind["PATH_SEGMENT"] = "path-segment";
+})(SystemOfRecordPartitionKind || (SystemOfRecordPartitionKind = {}));
+/**
+ * The SHAPE a partition value arrives in — the difference between a number and a pair.
+ *
+ * Odoo answers a many2one as `[id, display_name]`: `company_id: [10, "Acme"]` on a read, and `false`
+ * when unset. A reader that took the whole array as the key would match nothing, and one that took
+ * `row.company_id` as a scalar would stamp `"10,Acme"`. The shape is declared because the engine
+ * cannot tell a pair from a two-element list by looking.
+ *
+ * spec-cite: Odoo 18.0 developer documentation, "External API" — a many2one is returned as an
+ * `[id, display_name]` pair under both *Read records* and *Search and read*.
+ */
+export var SystemOfRecordPartitionValueShape;
+(function (SystemOfRecordPartitionValueShape) {
+    /** The field holds the key directly (an integer, a GUID, a string). */
+    SystemOfRecordPartitionValueShape["SCALAR"] = "scalar";
+    /** Odoo's many2one: `[id, label]`, and `false` when unset. The id is the key. */
+    SystemOfRecordPartitionValueShape["MANY2ONE_PAIR"] = "many2one-pair";
+})(SystemOfRecordPartitionValueShape || (SystemOfRecordPartitionValueShape = {}));
+/**
+ * What a vendor's partitioning IS — declared by the FACET, opted into by the INSTANCE.
+ *
+ * The split is the same one every other vendor fact takes: how a vendor partitions is a property of
+ * the vendor, and WHETHER this deployment's data is partitioned is a property of the deployment. A
+ * single-company Odoo has a `company_id` on every row and nothing to confine.
+ */
+export const SystemOfRecordPartitionSupportSchema = z.strictObject({
+    kind: z.enum(SystemOfRecordPartitionKind),
+    /** The remote field carrying the partition key (`company_id`, `subsidiary`, `CompanyCode`). */
+    remoteField: z.string().min(1).max(120),
+    /**
+     * How a key is spelled on the wire. Reused from the KEY component vocabulary rather than given its
+     * own: a partition key is addressed exactly as a key component is — decoded from an operator's
+     * authored string, compiled into a remote predicate — and two vocabularies for one job would drift.
+     */
+    codec: z.enum(HttpApiKeyComponentCodec),
+    valueShape: z.enum(SystemOfRecordPartitionValueShape),
+});
+/**
+ * What a vendor is, as a system of record. Parsed rather than trusted because #1057 lets a PACKAGE
+ * ship one — a record produced by one package version and read by another.
+ */
+export const SystemOfRecordVendorFacetSchema = z.strictObject({
+    /** The vendor's stable identifier, named by an instance's `vendor`. Same charset law as an instance name. */
+    vendor: z.string().regex(/^[a-z][a-z0-9-]*$/, 'A vendor id is lower-kebab-case.').max(40),
+    /**
+     * The dialects this vendor can be READ through. An instance's `dialect` must be one of them, and
+     * a binding's `dialect` must equal its instance's — both refused at boot registration, where the
+     * declaration and the facet are finally in the same scope.
+     */
+    dialects: z.array(z.enum(HttpApiTransportDialect)).min(1),
+    /**
+     * The vendor's own address slots — non-secret, authored per instance in the infra env config. The
+     * base URL is registration-scoped and is never credential material.
+     */
+    addressSlots: systemOfRecordSlotListSchema('vendor address'),
+    /**
+     * The credential kinds this vendor offers, each carrying THIS vendor's policy for it. The instance
+     * chooses one kind; a kind no offer names is refused.
+     *
+     * Reshaped from a bare `credentialKinds: Kind[]` in #1056. A list of kinds could say that a vendor
+     * accepts a header-borne API key and could not say WHICH header — so either the operator was asked
+     * (a question the vendor already answers, `derive-before-you-ask.md`) or the engine guessed. An
+     * offer is the kind and its vendor policy as one indivisible thing.
+     */
+    credentialOffers: z.array(SystemOfRecordCredentialOfferSchema).min(1),
+    /**
+     * How a COLLECTION READ pages against this vendor (#1292). Meaningful only for the OData dialects.
+     *
+     * OPTIONAL rather than defaulted, and the difference is not cosmetic: `.default()` would make the
+     * field REQUIRED on the parsed type, so every facet — Odoo's JSON-RPC included — would have to
+     * state an answer to a question about a dialect it does not speak. Absent means "not an OData
+     * concern, or the conformant default", and {@link resolveSystemOfRecordODataListPaging} is the one
+     * place that turns absence into `SKIP`.
+     */
+    odataListPaging: z.enum(SystemOfRecordODataListPaging).optional(),
+    /**
+     * How this vendor partitions one deployment's data (#1058), when it does.
+     *
+     * ABSENT means the vendor has no partition concept the engine can confine on — which is a real
+     * answer rather than an unfinished one, and the reason an instance opting into `partition` against
+     * such a facet is refused by name rather than silently doing nothing.
+     */
+    partition: SystemOfRecordPartitionSupportSchema.optional(),
+}).superRefine((facet, context) => {
+    const seenDialects = new Set();
+    for (const [index, dialect] of facet.dialects.entries()) {
+        if (seenDialects.has(dialect)) {
+            context.addIssue({ code: 'custom', path: ['dialects', index], message: `Duplicate dialects member "${dialect}".` });
+        }
+        seenDialects.add(dialect);
+    }
+    // One vendor may not offer the same kind twice: the instance names a KIND, so two offers of one
+    // kind would make the policy the engine reads depend on array order.
+    const seenKinds = new Set();
+    for (const [index, offer] of facet.credentialOffers.entries()) {
+        if (seenKinds.has(offer.kind)) {
+            context.addIssue({ code: 'custom', path: ['credentialOffers', index], message: `Duplicate credentialOffers member "${offer.kind}".` });
+        }
+        seenKinds.add(offer.kind);
+    }
+    // A vendor address slug that a kind also declares would make the derived environment variable
+    // ambiguous about who owns the value, so the two namespaces are checked against each other here
+    // rather than at the instance, where the failure would read as an authoring mistake.
+    const vendorSlugs = new Set(facet.addressSlots.map((slot) => slot.slug));
+    for (const offer of facet.credentialOffers) {
+        for (const slot of SYSTEM_OF_RECORD_CREDENTIAL_KIND_CONTRACTS[offer.kind].addressSlots) {
+            if (vendorSlugs.has(slot.slug)) {
+                context.addIssue({
+                    code: 'custom',
+                    path: ['addressSlots'],
+                    message: `Address slot "${slot.slug}" is declared by this vendor AND by credential kind "${offer.kind}" — one slot has one owner.`,
+                });
+            }
+        }
+    }
+});
+/** @wildo_source:part:end saas.models.systems-of-record */
+/**
+ * How this vendor pages an OData collection read — the ONE place an absent declaration becomes an
+ * answer (#1292).
+ *
+ * `$skip` is what OData v4 defines and what a conformant service serves, so silence means the
+ * conformant behaviour rather than an unknown. A second `?? SKIP` written at a consumer is how two
+ * readers come to disagree about what silence meant.
+ */
+export function resolveSystemOfRecordODataListPaging(facet) {
+    return facet.odataListPaging ?? SystemOfRecordODataListPaging.SKIP;
+}
+/**
+ * Find the offer a vendor makes for one kind, or `undefined`.
+ *
+ * Separate from {@link resolveSystemOfRecordInstanceSlots} because the two answer different
+ * questions: this one is "what is this vendor's POLICY for the kind I chose", which the minter needs
+ * at every call, while the slot union is a boot-time question asked once.
+ */
+export function findSystemOfRecordCredentialOffer(facet, credentialKind) {
+    return facet.credentialOffers.find((offer) => offer.kind === credentialKind);
+}
+/**
+ * The ONE place the vendor's slots and the credential kind's slots are joined.
+ *
+ * Every reader of "what does this instance need" goes through here — the environment-variable
+ * derivation, `wildo config sync`'s coherence check, the k8s secrets generator, the CI collector
+ * and the backend registry. Four of those five live in different packages, which is precisely why
+ * re-deriving the union at each of them would drift (`invariant-call-site-enumeration.md`).
+ *
+ * ## It also applies the offer's REQUIRED-NESS, which is why it takes a facet and not a contract
+ *
+ * Three slots are declared optional in the contract map and become required here, because only the
+ * vendor's offer knows: `certificateKeyId` under the key-id assertion header policy, `certificatePem`
+ * under the thumbprint policy, and `subject` for the JWT-bearer grant. Declaring them required in the
+ * contract would make every certificate vendor supply both halves of a choice only one of them makes;
+ * leaving them optional everywhere would let an instance boot with an assertion it cannot build, and
+ * fail at the first read instead of at configuration.
+ *
+ * Throws when the kind is not one the facet offers: that pairing is chosen by an instance and
+ * refused where the instance is validated, so reaching here with it means a caller skipped the
+ * check rather than an operator wrote something wrong.
+ */
+export function resolveSystemOfRecordInstanceSlots(facet, credentialKind) {
+    const offer = findSystemOfRecordCredentialOffer(facet, credentialKind);
+    if (offer === undefined) {
+        throw new Error(`Vendor "${facet.vendor}" does not offer credential kind "${credentialKind}" `
+            + `(offers: ${facet.credentialOffers.map((candidate) => candidate.kind).join(', ')}).`);
+    }
+    const contract = SYSTEM_OF_RECORD_CREDENTIAL_KIND_CONTRACTS[credentialKind];
+    const requiredByOffer = slotSlugsTheOfferMakesRequired(offer);
+    const applyOffer = (slot) => (slot.required || !requiredByOffer.has(slot.slug) ? slot : { ...slot, required: true });
+    const bySlug = (left, right) => left.slug.localeCompare(right.slug);
+    return {
+        addressSlots: [...facet.addressSlots, ...contract.addressSlots.map(applyOffer)].sort(bySlug),
+        secretSlots: [...contract.secretSlots.map(applyOffer)].sort(bySlug),
+    };
+}
+/**
+ * Which otherwise-optional slugs THIS offer turns into obligations.
+ *
+ * A `switch` over the discriminated union rather than a lookup, so a member added to the union
+ * without a decision here is a compile error rather than a slot that silently stays optional.
+ */
+function slotSlugsTheOfferMakesRequired(offer) {
+    switch (offer.kind) {
+        case SystemOfRecordCredentialKind.ODOO_API_KEY_IN_ARGS:
+        case SystemOfRecordCredentialKind.API_KEY_HEADER:
+        case SystemOfRecordCredentialKind.API_KEY_QUERY:
+        case SystemOfRecordCredentialKind.BASIC:
+        case SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_SECRET:
+            return new Set();
+        case SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_CERTIFICATE:
+            return new Set([
+                offer.assertionHeaderPolicy === SystemOfRecordAssertionHeaderPolicy.KEY_ID_SUPPLIED
+                    ? 'certificateKeyId'
+                    : 'certificatePem',
+            ]);
+        case SystemOfRecordCredentialKind.OAUTH2_JWT_BEARER:
+            // The `sub` of an RFC 7523 §2.1 assertion. Optional in the contract only because the GRANT is
+            // what asserts it — no other kind has a subject at all.
+            return new Set(['subject']);
+    }
+}
+//# sourceMappingURL=system-of-record-facet.shared.schemas.js.map