@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/systems-of-record/system-of-record-credential-kind.shared.js

@@ -0,0 +1,164 @@
+/**
+ * `SystemOfRecordCredentialKind` — HOW the engine authenticates to a system of record.
+ *
+ * A root-exported boundary module, for the same package-contract reason as its sibling
+ * `HttpApiTransportDialect` (#1055 R3): the ROOT-exported application-configuration contract
+ * (`systemsOfRecord.<name>.credential.kind`) names this vocabulary, and a TypeScript `enum` is
+ * NOMINAL — a root-only consumer that cannot reach the declaring module through a public specifier
+ * gets `TS2742`/`TS2883`. `.claude/rules/package-public-entrypoints.md` prescribes moving the
+ * boundary rather than re-exporting across it, so the `external-data` subpath does NOT re-export
+ * this module.
+ *
+ * ## Why it is a separate vocabulary from the dialect
+ *
+ * A dialect says how to SPEAK (query protocol, envelope, filter language); a credential kind says
+ * how to PROVE WHO YOU ARE. Odoo happens to pair one with the other today, and that coincidence is
+ * exactly what `CLAUDE.md` forbids merging on: an OData v4 service reached with a bearer token and
+ * the same service reached with client-credentials OAuth2 differ in the second axis and not the
+ * first. Keeping them apart costs one enum and stops the pairing from being baked into the model.
+ *
+ * ## What a kind OWNS (#1055 R15, the slot-ownership decision)
+ *
+ * The kind owns the inputs IT needs — its secret slots, and any address slot that exists only
+ * because of the kind. `OAUTH2_CLIENT_CREDENTIALS_SECRET` owns `tokenUrl`, which no vendor would
+ * declare if it were reached with a static key. The FACET owns the vendor's own address slots and
+ * the OFFERS it makes (a kind plus that vendor's policy for it); the INSTANCE chooses one offer.
+ *
+ * A third owner arrived with #1056 and is worth naming, because two of the three are easy to
+ * confuse: the FACET also owns everything about a kind that varies BY VENDOR but not by deployment —
+ * which header carries a static key, whether a token answer omits `expires_in`, whether an assertion
+ * header needs a supplied `kid` or a derived `x5t`. Those are not slots: nobody types them per
+ * environment, and asking an operator for them would be asking a question the facet already holds
+ * the answer to (`derive-before-you-ask.md`).
+ * The contracts themselves live beside the facet schema, on the `external-data` subpath, because
+ * nothing root-exported needs to name a slot SHAPE — only the kind's NAME.
+ *
+ * ## How the catalogue grew, and what is still missing from it
+ *
+ * #1055 shipped ONE member, the one kind its one facet offered. #1056 added the six a service
+ * identity actually needs across the vendors epic #1049 §4.6 surveyed — two static-key placements,
+ * HTTP Basic, and three OAuth2 shapes. A member here with no entry in
+ * `SYSTEM_OF_RECORD_CREDENTIAL_KIND_CONTRACTS` is a compile error, so the two cannot drift.
+ *
+ * `MTLS_CLIENT_CERTIFICATE` is deliberately ABSENT and is #1263. It is not a seventh variation on
+ * composing a request: every kind here decides what to put IN a request, and mTLS decides how the
+ * CONNECTION is made, which `HttpApiFetchLike` has no channel for (its `init` carries no
+ * dispatcher). Adding it means widening the one outbound seam both this lane and the connector lane
+ * run on — a different blast radius, and the reason SAP is declared unsupported-by-kind in #1057
+ * rather than every other vendor waiting behind it.
+ *
+ * ## The root-only probe, measured 2026-09-15
+ *
+ * `package-public-entrypoints.md` asks for a measurement rather than a category judgement. A
+ * consumer importing ONLY the package root, deriving values from this enum and emitting with
+ * `declaration: true`:
+ *
+ * ```
+ * export declare const declaredKind = SystemOfRecordCredentialKind.ODOO_API_KEY_IN_ARGS;
+ * export declare function pickInstance(): { kind: SystemOfRecordCredentialKind; dialect: HttpApiTransportDialect };
+ * ```
+ *
+ * Zero errors, and the emitted declaration NAMES the enum through the root specifier rather than a
+ * `node_modules/.../dist/esm/...` path. The probe's negative control — importing
+ * `SystemOfRecordVendorFacetSchema`, which is deliberately subpath-only — fails with `TS2305`, so
+ * the probe discriminates rather than passing everything.
+ */
+/**
+ * How the engine proves its identity to a system of record. Closed vocabulary — a system of record
+ * spends the APPLICATION's own service identity (D12), so nothing here is ever a person's lent
+ * credential; those live on the connected-accounts lane and are deliberately not reachable from
+ * this one (`pnpm check:systems-of-record-separation`).
+ */
+export var SystemOfRecordCredentialKind;
+(function (SystemOfRecordCredentialKind) {
+    /**
+     * Odoo's classic external API: the credential travels INSIDE the RPC arguments rather than in an
+     * HTTP header. The adapter performs `common.authenticate(db, login, apiKey, {})` for a uid and
+     * then passes `(db, uid, apiKey, …)` as the leading positional arguments of every `execute_kw`.
+     *
+     * Its inputs are the API key (a secret slot, owned here) plus the database and login (vendor
+     * address slots, owned by the Odoo facet — they identify WHICH Odoo and WHICH user, and would
+     * still be needed by a hypothetical second Odoo credential kind).
+     */
+    SystemOfRecordCredentialKind["ODOO_API_KEY_IN_ARGS"] = "odoo-api-key-in-args";
+    /**
+     * A static key presented in an HTTP request header.
+     *
+     * The SECRET is the key; WHICH header carries it and what prefixes it (`Bearer `, `ApiKey `, or
+     * nothing at all) are the VENDOR's facts, so they are declared on the facet's offer rather than
+     * asked of the operator who authors an instance. An operator who has to be told their vendor's
+     * header name is being asked a question the facet already holds the answer to
+     * (`derive-before-you-ask.md`).
+     */
+    SystemOfRecordCredentialKind["API_KEY_HEADER"] = "api-key-header";
+    /**
+     * A static key presented as a query-string parameter.
+     *
+     * Weaker than a header by construction — a URL reaches access logs, proxy logs and `Referer`
+     * headers — and offered only because some vendors accept nothing else. The parameter NAME is the
+     * vendor's fact, like the header name above.
+     *
+     * The key is appended by the transport at dispatch, never baked into a stored `baseUrl`: a base
+     * URL is printed in diagnostics and a credential must not ride in it.
+     */
+    SystemOfRecordCredentialKind["API_KEY_QUERY"] = "api-key-query";
+    /**
+     * HTTP Basic (RFC 7617): `Authorization: Basic base64(username ":" password)`.
+     *
+     * SAP's communication user is the case this exists for. The username is a SECRET slot rather than
+     * an address slot even though it is not confidential on its own — it is half of one credential,
+     * it is rotated with the other half, and splitting a credential across the address channel and
+     * the secret channel makes rotation two operations that can disagree.
+     *
+     * A username containing `:` is unrepresentable in this scheme (the colon is the delimiter and the
+     * RFC forbids it), so it is refused where it is authored rather than producing a credential that
+     * decodes to a different pair than the one typed.
+     */
+    SystemOfRecordCredentialKind["BASIC"] = "basic";
+    /**
+     * OAuth 2.0 client credentials (RFC 6749 §4.4) with a shared secret: `grant_type=client_credentials`
+     * plus `client_id` and `client_secret`.
+     *
+     * An APP-ONLY identity — no person, no consent screen, no refresh token. That is the whole of D12:
+     * a system of record is the operator's own deployment, reached as the application, so a
+     * user-delegated flow would be authenticating the wrong party. The connector lane owns the
+     * authorization-code exchange and is not reachable from here.
+     */
+    SystemOfRecordCredentialKind["OAUTH2_CLIENT_CREDENTIALS_SECRET"] = "oauth2-client-credentials-secret";
+    /**
+     * OAuth 2.0 client credentials with a CLIENT ASSERTION signed by a private key (RFC 7523 §2.2):
+     * `grant_type=client_credentials` with
+     * `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
+     *
+     * NetSuite and Microsoft Entra's certificate credential are both this, and NetSuite is the reason
+     * it is separate from {@link OAUTH2_JWT_BEARER}: its documentation states the grant type is
+     * *always* `client_credentials`, so it is client AUTHENTICATION by assertion rather than the
+     * assertion GRANT (#1056 R1 corrected an earlier reading that had NetSuite under the grant).
+     *
+     * spec-cite: RFC 7523 §2.2 (Using JWTs for Client Authentication); NetSuite OAuth 2.0
+     * client-credentials help, https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162755359851.html
+     *
+     * The assertion's protected HEADER differs by vendor — NetSuite carries a vendor-assigned `kid`,
+     * Entra wants an `x5t` thumbprint — so the header policy is declared on the facet's offer (R2). A
+     * generic "sign it with the private key" is rejected by both.
+     */
+    SystemOfRecordCredentialKind["OAUTH2_CLIENT_CREDENTIALS_CERTIFICATE"] = "oauth2-client-credentials-certificate";
+    /**
+     * The OAuth 2.0 JWT BEARER GRANT (RFC 7523 §2.1):
+     * `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` with a signed `assertion`.
+     *
+     * Salesforce only, among the vendors surveyed. Distinct from the kind above in the one field that
+     * decides how the token endpoint reads the request — the grant type — which is exactly the kind of
+     * distinction `CLAUDE.md` forbids collapsing because two shapes look similar.
+     *
+     * spec-cite: RFC 7523 §2.1 (Using JWTs as Authorization Grants).
+     */
+    SystemOfRecordCredentialKind["OAUTH2_JWT_BEARER"] = "oauth2-jwt-bearer";
+})(SystemOfRecordCredentialKind || (SystemOfRecordCredentialKind = {}));
+/** Whether a kind obtains a token from a token endpoint — the three that need a minter and a cache. */
+export function systemOfRecordCredentialKindMintsToken(kind) {
+    return kind === SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_SECRET
+        || kind === SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_CERTIFICATE
+        || kind === SystemOfRecordCredentialKind.OAUTH2_JWT_BEARER;
+}
+//# sourceMappingURL=system-of-record-credential-kind.shared.js.map

package/dist/esm/systems-of-record/system-of-record-credential-kind.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-of-record-credential-kind.shared.js","sourceRoot":"","sources":["../../../../src/systems-of-record/system-of-record-credential-kind.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH;;;;;GAKG;AACH,MAAM,CAAN,IAAY,4BA0FX;AA1FD,WAAY,4BAA4B;IACtC;;;;;;;;OAQG;IACH,6EAA6C,CAAA;IAE7C;;;;;;;;OAQG;IACH,iEAAiC,CAAA;IAEjC;;;;;;;;;OASG;IACH,+DAA+B,CAAA;IAE/B;;;;;;;;;;;OAWG;IACH,+CAAe,CAAA;IAEf;;;;;;;;OAQG;IACH,qGAAqE,CAAA;IAErE;;;;;;;;;;;;;;;;OAgBG;IACH,+GAA+E,CAAA;IAE/E;;;;;;;;;OASG;IACH,uEAAuC,CAAA;AACzC,CAAC,EA1FW,4BAA4B,KAA5B,4BAA4B,QA0FvC;AAED,uGAAuG;AACvG,MAAM,UAAU,sCAAsC,CAAC,IAAkC;IACvF,OAAO,IAAI,KAAK,4BAA4B,CAAC,gCAAgC;WACxE,IAAI,KAAK,4BAA4B,CAAC,qCAAqC;WAC3E,IAAI,KAAK,4BAA4B,CAAC,iBAAiB,CAAC;AAC/D,CAAC","sourcesContent":["/**\n * `SystemOfRecordCredentialKind` — HOW the engine authenticates to a system of record.\n *\n * A root-exported boundary module, for the same package-contract reason as its sibling\n * `HttpApiTransportDialect` (#1055 R3): the ROOT-exported application-configuration contract\n * (`systemsOfRecord.<name>.credential.kind`) names this vocabulary, and a TypeScript `enum` is\n * NOMINAL — a root-only consumer that cannot reach the declaring module through a public specifier\n * gets `TS2742`/`TS2883`. `.claude/rules/package-public-entrypoints.md` prescribes moving the\n * boundary rather than re-exporting across it, so the `external-data` subpath does NOT re-export\n * this module.\n *\n * ## Why it is a separate vocabulary from the dialect\n *\n * A dialect says how to SPEAK (query protocol, envelope, filter language); a credential kind says\n * how to PROVE WHO YOU ARE. Odoo happens to pair one with the other today, and that coincidence is\n * exactly what `CLAUDE.md` forbids merging on: an OData v4 service reached with a bearer token and\n * the same service reached with client-credentials OAuth2 differ in the second axis and not the\n * first. Keeping them apart costs one enum and stops the pairing from being baked into the model.\n *\n * ## What a kind OWNS (#1055 R15, the slot-ownership decision)\n *\n * The kind owns the inputs IT needs — its secret slots, and any address slot that exists only\n * because of the kind. `OAUTH2_CLIENT_CREDENTIALS_SECRET` owns `tokenUrl`, which no vendor would\n * declare if it were reached with a static key. The FACET owns the vendor's own address slots and\n * the OFFERS it makes (a kind plus that vendor's policy for it); the INSTANCE chooses one offer.\n *\n * A third owner arrived with #1056 and is worth naming, because two of the three are easy to\n * confuse: the FACET also owns everything about a kind that varies BY VENDOR but not by deployment —\n * which header carries a static key, whether a token answer omits `expires_in`, whether an assertion\n * header needs a supplied `kid` or a derived `x5t`. Those are not slots: nobody types them per\n * environment, and asking an operator for them would be asking a question the facet already holds\n * the answer to (`derive-before-you-ask.md`).\n * The contracts themselves live beside the facet schema, on the `external-data` subpath, because\n * nothing root-exported needs to name a slot SHAPE — only the kind's NAME.\n *\n * ## How the catalogue grew, and what is still missing from it\n *\n * #1055 shipped ONE member, the one kind its one facet offered. #1056 added the six a service\n * identity actually needs across the vendors epic #1049 §4.6 surveyed — two static-key placements,\n * HTTP Basic, and three OAuth2 shapes. A member here with no entry in\n * `SYSTEM_OF_RECORD_CREDENTIAL_KIND_CONTRACTS` is a compile error, so the two cannot drift.\n *\n * `MTLS_CLIENT_CERTIFICATE` is deliberately ABSENT and is #1263. It is not a seventh variation on\n * composing a request: every kind here decides what to put IN a request, and mTLS decides how the\n * CONNECTION is made, which `HttpApiFetchLike` has no channel for (its `init` carries no\n * dispatcher). Adding it means widening the one outbound seam both this lane and the connector lane\n * run on — a different blast radius, and the reason SAP is declared unsupported-by-kind in #1057\n * rather than every other vendor waiting behind it.\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. A\n * consumer importing ONLY the package root, deriving values from this enum and emitting with\n * `declaration: true`:\n *\n * ```\n * export declare const declaredKind = SystemOfRecordCredentialKind.ODOO_API_KEY_IN_ARGS;\n * export declare function pickInstance(): { kind: SystemOfRecordCredentialKind; dialect: HttpApiTransportDialect };\n * ```\n *\n * Zero errors, and the emitted declaration NAMES the enum through the root specifier rather than a\n * `node_modules/.../dist/esm/...` path. The probe's negative control — importing\n * `SystemOfRecordVendorFacetSchema`, which is deliberately subpath-only — fails with `TS2305`, so\n * the probe discriminates rather than passing everything.\n */\n\n/**\n * How the engine proves its identity to a system of record. Closed vocabulary — a system of record\n * spends the APPLICATION's own service identity (D12), so nothing here is ever a person's lent\n * credential; those live on the connected-accounts lane and are deliberately not reachable from\n * this one (`pnpm check:systems-of-record-separation`).\n */\nexport enum SystemOfRecordCredentialKind {\n  /**\n   * Odoo's classic external API: the credential travels INSIDE the RPC arguments rather than in an\n   * HTTP header. The adapter performs `common.authenticate(db, login, apiKey, {})` for a uid and\n   * then passes `(db, uid, apiKey, …)` as the leading positional arguments of every `execute_kw`.\n   *\n   * Its inputs are the API key (a secret slot, owned here) plus the database and login (vendor\n   * address slots, owned by the Odoo facet — they identify WHICH Odoo and WHICH user, and would\n   * still be needed by a hypothetical second Odoo credential kind).\n   */\n  ODOO_API_KEY_IN_ARGS = 'odoo-api-key-in-args',\n\n  /**\n   * A static key presented in an HTTP request header.\n   *\n   * The SECRET is the key; WHICH header carries it and what prefixes it (`Bearer `, `ApiKey `, or\n   * nothing at all) are the VENDOR's facts, so they are declared on the facet's offer rather than\n   * asked of the operator who authors an instance. An operator who has to be told their vendor's\n   * header name is being asked a question the facet already holds the answer to\n   * (`derive-before-you-ask.md`).\n   */\n  API_KEY_HEADER = 'api-key-header',\n\n  /**\n   * A static key presented as a query-string parameter.\n   *\n   * Weaker than a header by construction — a URL reaches access logs, proxy logs and `Referer`\n   * headers — and offered only because some vendors accept nothing else. The parameter NAME is the\n   * vendor's fact, like the header name above.\n   *\n   * The key is appended by the transport at dispatch, never baked into a stored `baseUrl`: a base\n   * URL is printed in diagnostics and a credential must not ride in it.\n   */\n  API_KEY_QUERY = 'api-key-query',\n\n  /**\n   * HTTP Basic (RFC 7617): `Authorization: Basic base64(username \":\" password)`.\n   *\n   * SAP's communication user is the case this exists for. The username is a SECRET slot rather than\n   * an address slot even though it is not confidential on its own — it is half of one credential,\n   * it is rotated with the other half, and splitting a credential across the address channel and\n   * the secret channel makes rotation two operations that can disagree.\n   *\n   * A username containing `:` is unrepresentable in this scheme (the colon is the delimiter and the\n   * RFC forbids it), so it is refused where it is authored rather than producing a credential that\n   * decodes to a different pair than the one typed.\n   */\n  BASIC = 'basic',\n\n  /**\n   * OAuth 2.0 client credentials (RFC 6749 §4.4) with a shared secret: `grant_type=client_credentials`\n   * plus `client_id` and `client_secret`.\n   *\n   * An APP-ONLY identity — no person, no consent screen, no refresh token. That is the whole of D12:\n   * a system of record is the operator's own deployment, reached as the application, so a\n   * user-delegated flow would be authenticating the wrong party. The connector lane owns the\n   * authorization-code exchange and is not reachable from here.\n   */\n  OAUTH2_CLIENT_CREDENTIALS_SECRET = 'oauth2-client-credentials-secret',\n\n  /**\n   * OAuth 2.0 client credentials with a CLIENT ASSERTION signed by a private key (RFC 7523 §2.2):\n   * `grant_type=client_credentials` with\n   * `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.\n   *\n   * NetSuite and Microsoft Entra's certificate credential are both this, and NetSuite is the reason\n   * it is separate from {@link OAUTH2_JWT_BEARER}: its documentation states the grant type is\n   * *always* `client_credentials`, so it is client AUTHENTICATION by assertion rather than the\n   * assertion GRANT (#1056 R1 corrected an earlier reading that had NetSuite under the grant).\n   *\n   * spec-cite: RFC 7523 §2.2 (Using JWTs for Client Authentication); NetSuite OAuth 2.0\n   * client-credentials help, https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162755359851.html\n   *\n   * The assertion's protected HEADER differs by vendor — NetSuite carries a vendor-assigned `kid`,\n   * Entra wants an `x5t` thumbprint — so the header policy is declared on the facet's offer (R2). A\n   * generic \"sign it with the private key\" is rejected by both.\n   */\n  OAUTH2_CLIENT_CREDENTIALS_CERTIFICATE = 'oauth2-client-credentials-certificate',\n\n  /**\n   * The OAuth 2.0 JWT BEARER GRANT (RFC 7523 §2.1):\n   * `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` with a signed `assertion`.\n   *\n   * Salesforce only, among the vendors surveyed. Distinct from the kind above in the one field that\n   * decides how the token endpoint reads the request — the grant type — which is exactly the kind of\n   * distinction `CLAUDE.md` forbids collapsing because two shapes look similar.\n   *\n   * spec-cite: RFC 7523 §2.1 (Using JWTs as Authorization Grants).\n   */\n  OAUTH2_JWT_BEARER = 'oauth2-jwt-bearer',\n}\n\n/** Whether a kind obtains a token from a token endpoint — the three that need a minter and a cache. */\nexport function systemOfRecordCredentialKindMintsToken(kind: SystemOfRecordCredentialKind): boolean {\n  return kind === SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_SECRET\n    || kind === SystemOfRecordCredentialKind.OAUTH2_CLIENT_CREDENTIALS_CERTIFICATE\n    || kind === SystemOfRecordCredentialKind.OAUTH2_JWT_BEARER;\n}\n"]}

package/dist/esm/systems-of-record/system-of-record-declaration.shared.schemas.d.ts

@@ -0,0 +1,322 @@
+/**
+ * `systemsOfRecord` — the application's declared INSTANCES of the systems it reads its own business
+ * rows out of.
+ *
+ * ```ts
+ * systemsOfRecord: {
+ *   odoo: { vendor: 'odoo', dialect: HttpApiTransportDialect.ODOO_JSONRPC },
+ * }
+ * ```
+ *
+ * ## The name is the whole point
+ *
+ * Before this, a resource addressed a remote system by `httpApiBinding.providerRef` — a free string
+ * naming a PROVIDER whose env-var names were literals inside its module, so one ref was one
+ * deployment and a second Odoo could not be expressed at all. A name here is an INSTANCE: two
+ * (`odoo-fr`, `odoo-de`) share one vendor facet and differ only in their addresses and secrets.
+ *
+ * The name is also the stem of every environment variable the instance needs —
+ * `WILDO_SOR_<NAME>__<SLOT>` — which is why it is capped at 32 characters and admits only
+ * lower-kebab-case. Renaming an instance therefore renames its variables, and there is deliberately
+ * no rename door for secrets: `wildo config sync` reports every now-missing slot and an operator
+ * re-authors them (#1055 E6).
+ *
+ * ## What is validated HERE, and what is not
+ *
+ * Here: the SHAPE, and only what a single configuration file can see. That `vendor` names a facet
+ * the deployment actually ships, and that `dialect` is one the facet speaks, are checked at BOOT by
+ * the systems-of-record registry — the earliest place where the declaration and the facet map are in
+ * the same scope. Splitting it that way is the same honest split `httpApiBinding` already makes:
+ * the factory checks shape, the registry checks agreement.
+ *
+ * Also not here: that the environment actually supplies each slot. The saas config and the infra env
+ * config parse independently, so cross-file coherence is checked at the seams where both are in
+ * scope — `wildo config sync` and the backend startup validator.
+ *
+ * ## Why declaring one requires an owner organization (#1054)
+ *
+ * A system of record is read with the APPLICATION's own service identity, and its rows are stamped
+ * with the owning organization's id so the per-row tenant gate passes without an exemption. An
+ * application that declares no organization type carrying `ownsApplication` has no organization to
+ * stamp with, so every read of every bound resource would refuse at request time. That refusal is
+ * a statement about two top-level blocks, so it lives in `WildoSaasConfigSchema`'s own refinement,
+ * where both are visible.
+ */
+import { z } from 'zod';
+import { HttpApiTransportDialect } from '../http-api-binding/http-api-transport-dialect.shared';
+import { SystemOfRecordCredentialKind } from './system-of-record-credential-kind.shared';
+/** @wildo_source:part:start saas.models.systems-of-record facet:layer:shared facet:audience:app-developer */
+/**
+ * The charset law for an instance name, exported because the environment-variable derivation and
+ * every tool that parses a derived name back into a `(name, slot)` pair depend on it: a name may
+ * not contain `_`, so the `__` delimiter is unambiguous (#1055 R4).
+ */
+export declare const SYSTEM_OF_RECORD_NAME_PATTERN: RegExp;
+/** 32 characters, because the name is a stem of an environment-variable name rather than a label. */
+export declare const SYSTEM_OF_RECORD_NAME_MAX_LENGTH = 32;
+/**
+ * Whether the personal data held in a system-of-record INSTANCE can have originated from publicly
+ * accessible sources (#1745) — the half of GDPR Art. 14(2)(f) nothing else in an application can
+ * derive.
+ *
+ * A privacy notice owes, for personal data not collected from the person, "from which source the
+ * personal data originate, and if applicable, whether it came from publicly accessible sources".
+ * spec-cite: GDPR Art. 14(2)(f), https://gdpr-info.eu/art-14-gdpr/.
+ * The binding already makes the first half true: the source is this instance, a deployment the
+ * operator runs. The second half is about how records got INTO that deployment — an ERP contact
+ * may have been typed in from a public register, a website or a bought list — and only the
+ * operator knows. So the operator states it here, once per instance, as a typed value a reviewer
+ * can diff, rather than answering a question or leaving it to a drafter's guess.
+ *
+ * Omitting it is legitimate and is NOT read as "no": the notice's source statement then marks the
+ * public-origin half owed for every resource read from the instance.
+ */
+export declare enum SystemOfRecordPersonalDataOrigin {
+    /** Every person's data in this instance was collected by the operator — from the person, their organisation or the operator's own dealings with them — and none from a publicly accessible source. */
+    NO_PUBLICLY_ACCESSIBLE_SOURCES = "no-publicly-accessible-sources",
+    /** Some of it may come from publicly accessible sources: company registers, websites, social profiles, enrichment services. The notice says so. */
+    INCLUDES_PUBLICLY_ACCESSIBLE_SOURCES = "includes-publicly-accessible-sources"
+}
+export declare const SystemOfRecordNameSchema: z.ZodString;
+/**
+ * The i18n bucket holding every instance's display words — the first segment of
+ * {@link buildSystemOfRecordDisplayNameLabelKey}'s keys.
+ */
+export declare const SYSTEM_OF_RECORD_LABEL_BUCKET = "systems_of_record";
+/**
+ * The label key naming ONE declared instance to a person: `systems_of_record.<name>.displayName` (#1997).
+ *
+ * An instance NAME is an environment-variable stem (`odoo`, `sap-fr`), not words: it cannot be translated, and the
+ * words a reader recognises ("Odoo", "SAP France") are not derivable from it. So a surface that names an instance —
+ * the provenance cue on a field a pipeline wrote, "synced from Odoo" — resolves this key, and the labelling pipeline
+ * plans it for every declared instance, total over `systemsOfRecord`. There is deliberately no `displayName` on the
+ * declaration: display text comes from the i18n tree, never from configuration. A key nobody generated renders the
+ * raw name, which is the missing label looking missing.
+ */
+export declare function buildSystemOfRecordDisplayNameLabelKey(name: string): string;
+/** ONE declared instance. */
+export declare const SystemOfRecordDeclarationSchema: z.ZodObject<{
+    /**
+     * Which vendor this is an instance of — the `vendor` of a facet the deployment ships: the framework's facets
+     * come from the opt-in library `@wildo-ai/systems-of-record`, which `wildo config sync` declares on the backend
+     * as soon as an instance is declared (#2013). Refused at boot when no facet answers to it, rather than here,
+     * because the facet map is not in scope in `wildo.saas.config.ts`.
+     */
+    vendor: z.ZodString;
+    /**
+     * How this instance is READ. Declared per instance rather than taken from the facet because a
+     * vendor may speak several dialects — a service reachable over both OData v4 and a bespoke REST
+     * surface is one vendor and two ways in. The facet's `dialects` is the closed set this must belong
+     * to, checked at boot.
+     *
+     * ## One instance per SERVICE ROOT — so a system serving OData v2 and v4 is two instances (#1687)
+     *
+     * An instance has ONE dialect and ONE base URL, and for OData that URL is a service root: an SAP
+     * system's `/sap/opu/odata/sap/API_BUSINESS_PARTNER` (v2) and `/sap/opu/odata4/sap/<service>/…` (v4)
+     * are different roots, as two v4 services of the same system already are. So a system reached over
+     * both versions is declared as two instances, one per root, each with its own dialect, credential
+     * and `maxRequestsPerMinute`.
+     *
+     * Decided rather than asked, because the model already answered it: an instance naming several roots
+     * would need a root per binding, which is what two instances are, and a budget SHARED across
+     * instances would be a new cross-instance ledger for a ceiling the operator can already honour by
+     * splitting it between the instances' `maxRequestsPerMinute`. Both were rejected on that ground.
+     * The cost, stated: two instances against one vendor account are paced separately, so their sum —
+     * not either one — is what must stay under the vendor's allowance.
+     */
+    dialect: z.ZodEnum<typeof HttpApiTransportDialect>;
+    /**
+     * How the engine proves who it is.
+     *
+     * OPTIONAL, and the absence is DERIVED rather than defaulted: when the instance's facet offers
+     * exactly one credential kind there is nothing for an author to decide, so the registry takes it;
+     * when a facet offers more than one and the instance names none, boot refuses and lists them.
+     * The framework derives before it asks: a declaration with one legal value is a question whose
+     * answer the mechanism already holds.
+     *
+     * This stays additive when #1056 widens the facet set: an instance that omitted the field is
+     * refused on the day its facet gains a second kind, which is exactly the day its author acquires a
+     * real decision.
+     */
+    credential: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<typeof SystemOfRecordCredentialKind>;
+    }, z.core.$strict>>;
+    /**
+     * The pace this deployment may call the instance at, across EVERY resource bound to it (#1056 §3).
+     *
+     * Per INSTANCE because that is the unit the vendor accounts for: two resources bound to one
+     * Dataverse are one application user to Dataverse, so two independent per-binding budgets would
+     * each believe they were within a limit the pair together exceeds.
+     *
+     * A binding's own `remoteCallSemantics.maxRequestsPerMinute` stays, and becomes a CEILING UNDER
+     * this one: it answers a different question — how much of the shared allowance may ONE resource
+     * take — which matters when a pipeline load and an interactive read share an instance. Both are
+     * consumed for every call, and a call proceeds only if both have room.
+     *
+     * Omitted means unlimited HERE, which is the honest default: the framework does not know the
+     * vendor's contract, and inventing a number would either throttle a deployment that paid for more
+     * or fail to protect one that has less.
+     */
+    maxRequestsPerMinute: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Whether THIS deployment's data is partitioned, and its rows therefore confined to organization
+     * units of the owner organization (#1058).
+     *
+     * ## The reservation this replaces
+     *
+     * #1055 declared this field `z.never()` and refused it by name, because accepting a declaration the
+     * mechanism could not honour would let an author believe their rows were narrowed while every
+     * member still saw every row. That refusal did its job and is now lifted.
+     *
+     * ## Why the VENDOR says how and the INSTANCE says whether
+     *
+     * How a vendor partitions — which field, what shape, what codec — is a property of the vendor and
+     * lives on its facet. Whether a given 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, and
+     * asking its operator to restate the field name would be asking a question the facet answers.
+     *
+     * Opting in against a facet that declares no partitioning is refused at boot, naming the vendor —
+     * the alternative is a `true` that does nothing, which is the shape the reservation existed to
+     * prevent in the first place.
+     */
+    partition: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * The PACKAGES whose facet augmentation applies to this instance (#1675) — npm package names, each of which
+     * must ship an augmentation for this instance's vendor from its `./systems-of-record` export.
+     *
+     * An explicit opt-in per INSTANCE, never implied by installation, because what an augmentation adds can be a
+     * partition declaration, and the facet is the single authority on how a tenant's rows are confined. Two
+     * instances of one vendor may therefore differ: one opts a package's partition in, the other does not.
+     * A package named here that ships no augmentation for the vendor refuses at startup, naming it.
+     *
+     * Naming a package here is also what ADMITS its `./systems-of-record` module to discovery (#2013): apart from the
+     * framework library `@wildo-ai/systems-of-record`, a facet module is recorded only from a package some instance
+     * names. The package must still be walked — named `<scope>/provider-*`, or listed in `providers.packages`.
+     */
+    facetAugmentations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /**
+     * Whether the personal data in THIS deployment can have come from publicly accessible sources — see
+     * {@link SystemOfRecordPersonalDataOrigin}. A property of the deployment, not the vendor: two Odoo
+     * instances may be fed differently. Optional; omitted, the privacy notice marks that statement owed
+     * for every resource read from this instance, and never states "not from public sources" by default.
+     */
+    personalDataOrigin: z.ZodOptional<z.ZodEnum<typeof SystemOfRecordPersonalDataOrigin>>;
+}, z.core.$strict>;
+export type SystemOfRecordDeclaration = z.infer<typeof SystemOfRecordDeclarationSchema>;
+/**
+ * Every instance this application declares, keyed by name.
+ *
+ * Optional as a whole: an application that reads nothing out of another system declares nothing, and
+ * declaring this block is what ENABLES the external-data lane (#1055 D3) rather than an engine
+ * capability flag — the lane has no meaning without an instance to point at.
+ */
+export declare const SystemsOfRecordConfigSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    /**
+     * Which vendor this is an instance of — the `vendor` of a facet the deployment ships: the framework's facets
+     * come from the opt-in library `@wildo-ai/systems-of-record`, which `wildo config sync` declares on the backend
+     * as soon as an instance is declared (#2013). Refused at boot when no facet answers to it, rather than here,
+     * because the facet map is not in scope in `wildo.saas.config.ts`.
+     */
+    vendor: z.ZodString;
+    /**
+     * How this instance is READ. Declared per instance rather than taken from the facet because a
+     * vendor may speak several dialects — a service reachable over both OData v4 and a bespoke REST
+     * surface is one vendor and two ways in. The facet's `dialects` is the closed set this must belong
+     * to, checked at boot.
+     *
+     * ## One instance per SERVICE ROOT — so a system serving OData v2 and v4 is two instances (#1687)
+     *
+     * An instance has ONE dialect and ONE base URL, and for OData that URL is a service root: an SAP
+     * system's `/sap/opu/odata/sap/API_BUSINESS_PARTNER` (v2) and `/sap/opu/odata4/sap/<service>/…` (v4)
+     * are different roots, as two v4 services of the same system already are. So a system reached over
+     * both versions is declared as two instances, one per root, each with its own dialect, credential
+     * and `maxRequestsPerMinute`.
+     *
+     * Decided rather than asked, because the model already answered it: an instance naming several roots
+     * would need a root per binding, which is what two instances are, and a budget SHARED across
+     * instances would be a new cross-instance ledger for a ceiling the operator can already honour by
+     * splitting it between the instances' `maxRequestsPerMinute`. Both were rejected on that ground.
+     * The cost, stated: two instances against one vendor account are paced separately, so their sum —
+     * not either one — is what must stay under the vendor's allowance.
+     */
+    dialect: z.ZodEnum<typeof HttpApiTransportDialect>;
+    /**
+     * How the engine proves who it is.
+     *
+     * OPTIONAL, and the absence is DERIVED rather than defaulted: when the instance's facet offers
+     * exactly one credential kind there is nothing for an author to decide, so the registry takes it;
+     * when a facet offers more than one and the instance names none, boot refuses and lists them.
+     * The framework derives before it asks: a declaration with one legal value is a question whose
+     * answer the mechanism already holds.
+     *
+     * This stays additive when #1056 widens the facet set: an instance that omitted the field is
+     * refused on the day its facet gains a second kind, which is exactly the day its author acquires a
+     * real decision.
+     */
+    credential: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<typeof SystemOfRecordCredentialKind>;
+    }, z.core.$strict>>;
+    /**
+     * The pace this deployment may call the instance at, across EVERY resource bound to it (#1056 §3).
+     *
+     * Per INSTANCE because that is the unit the vendor accounts for: two resources bound to one
+     * Dataverse are one application user to Dataverse, so two independent per-binding budgets would
+     * each believe they were within a limit the pair together exceeds.
+     *
+     * A binding's own `remoteCallSemantics.maxRequestsPerMinute` stays, and becomes a CEILING UNDER
+     * this one: it answers a different question — how much of the shared allowance may ONE resource
+     * take — which matters when a pipeline load and an interactive read share an instance. Both are
+     * consumed for every call, and a call proceeds only if both have room.
+     *
+     * Omitted means unlimited HERE, which is the honest default: the framework does not know the
+     * vendor's contract, and inventing a number would either throttle a deployment that paid for more
+     * or fail to protect one that has less.
+     */
+    maxRequestsPerMinute: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Whether THIS deployment's data is partitioned, and its rows therefore confined to organization
+     * units of the owner organization (#1058).
+     *
+     * ## The reservation this replaces
+     *
+     * #1055 declared this field `z.never()` and refused it by name, because accepting a declaration the
+     * mechanism could not honour would let an author believe their rows were narrowed while every
+     * member still saw every row. That refusal did its job and is now lifted.
+     *
+     * ## Why the VENDOR says how and the INSTANCE says whether
+     *
+     * How a vendor partitions — which field, what shape, what codec — is a property of the vendor and
+     * lives on its facet. Whether a given 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, and
+     * asking its operator to restate the field name would be asking a question the facet answers.
+     *
+     * Opting in against a facet that declares no partitioning is refused at boot, naming the vendor —
+     * the alternative is a `true` that does nothing, which is the shape the reservation existed to
+     * prevent in the first place.
+     */
+    partition: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * The PACKAGES whose facet augmentation applies to this instance (#1675) — npm package names, each of which
+     * must ship an augmentation for this instance's vendor from its `./systems-of-record` export.
+     *
+     * An explicit opt-in per INSTANCE, never implied by installation, because what an augmentation adds can be a
+     * partition declaration, and the facet is the single authority on how a tenant's rows are confined. Two
+     * instances of one vendor may therefore differ: one opts a package's partition in, the other does not.
+     * A package named here that ships no augmentation for the vendor refuses at startup, naming it.
+     *
+     * Naming a package here is also what ADMITS its `./systems-of-record` module to discovery (#2013): apart from the
+     * framework library `@wildo-ai/systems-of-record`, a facet module is recorded only from a package some instance
+     * names. The package must still be walked — named `<scope>/provider-*`, or listed in `providers.packages`.
+     */
+    facetAugmentations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /**
+     * Whether the personal data in THIS deployment can have come from publicly accessible sources — see
+     * {@link SystemOfRecordPersonalDataOrigin}. A property of the deployment, not the vendor: two Odoo
+     * instances may be fed differently. Optional; omitted, the privacy notice marks that statement owed
+     * for every resource read from this instance, and never states "not from public sources" by default.
+     */
+    personalDataOrigin: z.ZodOptional<z.ZodEnum<typeof SystemOfRecordPersonalDataOrigin>>;
+}, z.core.$strict>>;
+export type SystemsOfRecordConfig = z.infer<typeof SystemsOfRecordConfigSchema>;
+/** @wildo_source:part:end saas.models.systems-of-record */
+//# sourceMappingURL=system-of-record-declaration.shared.schemas.d.ts.map

package/dist/esm/systems-of-record/system-of-record-declaration.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-of-record-declaration.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/systems-of-record/system-of-record-declaration.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,uDAAuD,CAAC;AAChG,OAAO,EAAE,4BAA4B,EAAE,MAAM,2CAA2C,CAAC;AAEzF,6GAA6G;AAE7G;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,QAAsB,CAAC;AAEjE,qGAAqG;AACrG,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,oBAAY,gCAAgC;IAC1C,sMAAsM;IACtM,8BAA8B,mCAAmC;IACjE,mJAAmJ;IACnJ,oCAAoC,yCAAyC;CAC9E;AAED,eAAO,MAAM,wBAAwB,aAGG,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE;;;;;;;;;GASG;AACH,wBAAgB,sCAAsC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,6BAA6B;AAC7B,eAAO,MAAM,+BAA+B;IAC1C;;;;;OAKG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;OAYG;;;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;OAYG;;IAMH;;;;;OAKG;;kBAEH,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;IA1HtC;;;;;OAKG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;OAYG;;;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;OAYG;;IAMH;;;;;OAKG;;mBAwBD,CAAC;AACL,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,2DAA2D"}