@wildo-ai/saas-models 1.1.4 → 1.1.6

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

@@ -0,0 +1,327 @@
+/**
+ * Declared ACTIONS of a system of record (#1678) — the named vendor operations an application may run against the
+ * ERP it reads, beside the row reads and row writes its read-through bindings already open.
+ *
+ * Posting an invoice (Odoo `account.move` `action_post`), confirming a sales order, an OData bound or unbound action:
+ * none of them is a row write, and before this nothing declared one and nothing executed one. The only thing that
+ * could run one was the systems-of-record registry's raw access hand-out, which returns an instance's credentials and
+ * records nothing (#1738 withdrew it from every application-facing door).
+ *
+ * ## The decision these declarations implement (Paul, 2026-09-25, on #1677/#1678)
+ *
+ * One vendor may serve two roles through two SEPARATE lanes. The system-of-record lane declares named actions and runs
+ * them under the INSTANCE's service identity, confined to the owner organization and to the member's partition, with
+ * its own audit event. The same vendor may also be a classical provider with its own user or organization connections.
+ * The two share a vendor identity for display and compliance, and never a credential or a runtime object (#1049 D10).
+ * There is no Odoo provider package, and a provider operation can never name a system-of-record instance.
+ *
+ * ## WHERE an action is declared, and the placement that was rejected
+ *
+ * On a read-through BINDING (`httpApiBinding.actions`), both kinds:
+ *
+ * - a RECORD-targeted action on the binding of the entity it acts on, which supplies the key codec that decodes the
+ *   target id and the resource whose read gates decide whether the caller may reach that record;
+ * - a RECORD-FREE action on the binding of the entity whose model (Odoo) or service (OData) the call is made against.
+ *
+ * Rejected: record-free actions on the INSTANCE (`systemsOfRecord.<name>.actions` in `wildo.saas.config.ts`). Three
+ * reasons, any one sufficient. An action declares a Zod INPUT schema, and the saas configuration is parsed by the CLI
+ * and the companion as data, where a schema object is not representable. An action declares the ROLES admitted to it,
+ * which are the same role keys the resource's operations declare in `shared-lib`, and a second home for them would
+ * drift. And the HTTP exposure of an action is a custom operation on a read-through resource, which lives in the
+ * resource configuration anyway; the instance declaration is not in scope there (it lives in the application root, not
+ * in `shared-lib`). What the instance keeps is what only the instance knows: whether its data is partitioned, which is
+ * why a record-free action's partition stance is checked at boot, where both are visible.
+ *
+ * ## What is checked where
+ *
+ * - HERE, at authoring (the resource factory, through `assertHttpApiBindingDialectCoherence`): the call shape against
+ *   the binding's dialect, the target against the call shape, the refused vendor methods, the stance's placement.
+ * - At BOOT (the resources registry, where the instance and the vendor facet are visible): the facet declares the call
+ *   shape, a record-free action on a PARTITIONED instance states its partition stance, and action names are unique per
+ *   instance.
+ * - Per REQUEST (the system-of-record action executor): who may run it, on which record, and what it sends.
+ */
+import { z } from 'zod';
+import { isZodObject } from '@wildo-ai/zod-decorators';
+import { HttpApiTransportDialect } from '../http-api-binding/http-api-transport-dialect.shared.js';
+/** @wildo_source:part:start saas.models.system-of-record-actions facet:layer:shared facet:audience:app-developer */
+/**
+ * The wire SHAPE of a vendor action — how the engine calls it. Declared by the VENDOR FACET (which shapes its product
+ * supports, `actionCallShapes`) and chosen per action by its declaration.
+ *
+ * REST_JSON has no member: an arbitrary REST surface has no action convention to compile against, and a declared method
+ * plus path template is a design of its own. A REST_JSON binding declaring an action is refused by name. (REST_JSON
+ * ROW writes are declared per verb since #1728 — `operations.create` / `update` / `delete` — because a row write has a
+ * fixed meaning a method and a path can carry; an action's meaning is the vendor's, and has no such shape.)
+ */
+export var SystemOfRecordActionCallShape;
+(function (SystemOfRecordActionCallShape) {
+    /**
+     * Odoo's `object.execute_kw(db, uid, key, model, method, positional, keyword)` — any public model method, the
+     * credential inside the RPC arguments. A record-targeted call passes the record ids as its first positional
+     * argument, which is how Odoo addresses a recordset method such as `action_post`.
+     *
+     * spec-cite: Odoo 18.0 developer documentation, External API — "Calling methods" (the execute_kw argument layout).
+     */
+    SystemOfRecordActionCallShape["ODOO_EXECUTE_KW"] = "odoo-execute-kw";
+    /**
+     * An OData v4 BOUND action: `POST <EntitySet>(<key>)/<Namespace>.<Action>`, parameters in the JSON body.
+     *
+     * spec-cite: OData Version 4.01 Part 1: Protocol §11.5.5 (Actions) and §11.5.5.1 (Invoking an Action).
+     */
+    SystemOfRecordActionCallShape["ODATA_BOUND_ACTION"] = "odata-bound-action";
+    /**
+     * An OData v4 UNBOUND action reached through its action import: `POST /<ActionImport>`, parameters in the JSON body.
+     *
+     * spec-cite: OData Version 4.01 Part 1: Protocol §11.5.5.1 (Invoking an Action).
+     */
+    SystemOfRecordActionCallShape["ODATA_UNBOUND_ACTION"] = "odata-unbound-action";
+})(SystemOfRecordActionCallShape || (SystemOfRecordActionCallShape = {}));
+/**
+ * The dialect each call shape is spoken over. Total over {@link SystemOfRecordActionCallShape}, so a new shape is a
+ * compile error here until somebody says which dialect it belongs to.
+ */
+export const SYSTEM_OF_RECORD_ACTION_CALL_SHAPE_DIALECT = Object.freeze({
+    [SystemOfRecordActionCallShape.ODOO_EXECUTE_KW]: HttpApiTransportDialect.ODOO_JSONRPC,
+    [SystemOfRecordActionCallShape.ODATA_BOUND_ACTION]: HttpApiTransportDialect.ODATA,
+    [SystemOfRecordActionCallShape.ODATA_UNBOUND_ACTION]: HttpApiTransportDialect.ODATA,
+});
+/** What an action acts ON. */
+export var SystemOfRecordActionTarget;
+(function (SystemOfRecordActionTarget) {
+    /**
+     * ONE record of the binding's entity, addressed by its synthesized id. The record is READ FIRST through the binding's
+     * read gates (owner organization, partition), so a caller can act only on a record it could see — and a record
+     * outside its partition answers as absent, exactly as a read answers.
+     */
+    SystemOfRecordActionTarget["RECORD"] = "record";
+    /** No record: a model-level Odoo method (`create`) or an OData unbound action. */
+    SystemOfRecordActionTarget["NONE"] = "none";
+})(SystemOfRecordActionTarget || (SystemOfRecordActionTarget = {}));
+/** Where an Odoo action's validated input goes in the `execute_kw` call. */
+export var SystemOfRecordOdooActionInputPlacement;
+(function (SystemOfRecordOdooActionInputPlacement) {
+    /** The input object is the keyword-argument dict. The default: most recordset methods take options by keyword. */
+    SystemOfRecordOdooActionInputPlacement["KEYWORD_ARGUMENTS"] = "keyword-arguments";
+    /**
+     * The input object is the (next) POSITIONAL argument — after the id list on a record-targeted action, first on a
+     * record-free one. `create(vals)` is the canonical case.
+     */
+    SystemOfRecordOdooActionInputPlacement["POSITIONAL"] = "positional";
+    /** The method takes nothing beyond its records (`action_post`). The declared input must then be empty. */
+    SystemOfRecordOdooActionInputPlacement["NONE"] = "none";
+})(SystemOfRecordOdooActionInputPlacement || (SystemOfRecordOdooActionInputPlacement = {}));
+/**
+ * How a RECORD-FREE action relates to the instance's partitions (#1058), required at boot when the instance is
+ * partitioned. A record-targeted action needs none: the record it reads first carries its partition.
+ */
+export var SystemOfRecordActionPartitionStanceKind;
+(function (SystemOfRecordActionPartitionStanceKind) {
+    /**
+     * The action touches no partitioned data — a lookup of a vendor setting, an action whose effect no partition owns.
+     * The declaration must say WHY in `reason`, because a claim nothing checks has to be one a reviewer can read.
+     */
+    SystemOfRecordActionPartitionStanceKind["PARTITION_NEUTRAL"] = "partition-neutral";
+    /**
+     * The action CARRIES the partition as one of its inputs, and the engine derives it from the caller's organization
+     * unit exactly as a read-through create is placed (#1679): a member of one unit lands in its partition, a member of
+     * several names the unit, and a caller may never supply the partition value itself.
+     */
+    SystemOfRecordActionPartitionStanceKind["MEMBER_UNIT_PARTITION"] = "member-unit-partition";
+})(SystemOfRecordActionPartitionStanceKind || (SystemOfRecordActionPartitionStanceKind = {}));
+export const SystemOfRecordActionPartitionStanceSchema = z.discriminatedUnion('kind', [
+    z.strictObject({
+        kind: z.literal(SystemOfRecordActionPartitionStanceKind.PARTITION_NEUTRAL),
+        /** Why no partition is reached. Read by a reviewer; nothing can verify it, which is why it is required. */
+        reason: z.string().trim().min(20, 'Say why this action reaches no partitioned data — a reviewer reads this.'),
+    }),
+    z.strictObject({
+        kind: z.literal(SystemOfRecordActionPartitionStanceKind.MEMBER_UNIT_PARTITION),
+        /**
+         * The REMOTE parameter the placed partition value is written into (`company_id`): a key of the Odoo keyword
+         * arguments or of the positional input object, or a member of the OData body. The caller's input may not carry it.
+         */
+        parameter: z.string().min(1).max(120),
+    }),
+]);
+export const SystemOfRecordActionCallSchema = z.discriminatedUnion('shape', [
+    z.strictObject({
+        shape: z.literal(SystemOfRecordActionCallShape.ODOO_EXECUTE_KW),
+        /** The model method, in Odoo's own spelling (`action_post`, `create`). */
+        method: z.string().regex(/^[a-z_][a-z0-9_]*$/, 'An Odoo method name is snake_case.').max(120),
+        /**
+         * The model the call is made on, for a RECORD-FREE action only. A record-targeted action acts on the binding's own
+         * model — the one its key codec and read gates describe — so naming another would decode the id against the wrong
+         * entity. Absent means the binding's `entityRef`.
+         */
+        model: z.string().regex(/^[a-z_][a-z0-9_.]*$/, 'An Odoo model name is dotted snake_case.').max(120).optional(),
+        inputPlacement: z.enum(SystemOfRecordOdooActionInputPlacement).default(SystemOfRecordOdooActionInputPlacement.KEYWORD_ARGUMENTS),
+    }),
+    z.strictObject({
+        shape: z.literal(SystemOfRecordActionCallShape.ODATA_BOUND_ACTION),
+        /** The namespace-qualified action name (`Microsoft.Dynamics.CRM.WinOpportunity`). */
+        qualifiedName: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)+$/, 'A bound action is named Namespace.Action.').max(200),
+    }),
+    z.strictObject({
+        shape: z.literal(SystemOfRecordActionCallShape.ODATA_UNBOUND_ACTION),
+        /** The action import's name, as the service root exposes it. */
+        actionImport: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'An action import is a simple identifier.').max(200),
+    }),
+]);
+/**
+ * The application's NAME for an action — lowerCamelCase, and distinct from the vendor's method name on purpose: the
+ * name is what code, roles and audit rows speak (`postInvoice`), the call is what the vendor understands
+ * (`account.move` `action_post`). Unique per INSTANCE across every binding, checked at boot, because callers address an
+ * action by `(system, action)`.
+ */
+export const SYSTEM_OF_RECORD_ACTION_NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+export const SystemOfRecordActionNameSchema = z.string().regex(SYSTEM_OF_RECORD_ACTION_NAME_PATTERN, 'An action name is lowerCamelCase.').max(64);
+/** A Zod OBJECT schema carried as a value — an action's input contract. */
+const zodObjectSchemaValue = z.custom((value) => value !== null && typeof value === 'object' && isZodObject(value), { message: 'An action input is a Zod object schema (z.object({...})).' });
+/** Any Zod schema carried as a value — an action's output contract. */
+const zodSchemaValue = z.custom((value) => value !== null && typeof value === 'object' && typeof value.safeParse === 'function', { message: 'An action output is a Zod schema.' });
+/** ONE declared action. */
+export const SystemOfRecordActionDeclarationSchema = z.strictObject({
+    target: z.enum(SystemOfRecordActionTarget),
+    call: SystemOfRecordActionCallSchema,
+    /**
+     * The input contract, validated BEFORE anything is sent. Strict parsing is the caller's contract: a key the schema
+     * does not declare is refused rather than forwarded, so nothing reaches the vendor that the author did not name.
+     */
+    input: zodObjectSchemaValue,
+    /**
+     * The result contract. When declared, the vendor's answer is parsed through it and only the parsed value is returned;
+     * an answer it rejects after the vendor APPLIED the action is reported as an unknown outcome, never as "not done".
+     * Absent means the result is returned as the vendor sent it.
+     */
+    output: zodSchemaValue.optional(),
+    /**
+     * Whether the action CHANGES remote state. A writing action must carry an Idempotency-Key from EVERY caller, because a
+     * remote change cannot be rolled back, and its interrupted attempts are reported as an unknown outcome rather than as
+     * a failure. A non-writing action (a vendor computation that changes nothing) needs neither.
+     */
+    writes: z.boolean(),
+    /**
+     * Whether the VENDOR makes a repeated call harmless, so the transport may re-send it after a timeout or a 5xx. False
+     * unless the vendor offers an idempotency mechanism for this call; Odoo offers none, so no Odoo action is retry-safe.
+     * A writing action is never re-sent without an Idempotency-Key, whatever this says.
+     */
+    retrySafe: z.boolean().default(false),
+    /**
+     * The role keys admitted to run it, held in the OWNER organization (an organization role) or at application scope. A
+     * role held only inside an organization UNIT admits the action on that unit's partition alone.
+     */
+    roles: z.array(z.string().min(1)).min(1),
+    /**
+     * Whether a context with NO user and no machine principal — the engine's own batch, cron and queue work, a webhook, an
+     * autonomous agent with nobody behind it — may run it. Such a context then acts ORGANIZATION-WIDE on the owner
+     * organization's behalf, which is exactly why it is off unless declared.
+     */
+    admitsSystemInitiation: z.boolean().default(false),
+    /** A record-free action's relation to the instance's partitions; see {@link SystemOfRecordActionPartitionStanceKind}. */
+    partitionStance: SystemOfRecordActionPartitionStanceSchema.optional(),
+    /**
+     * The resource operation that is this action's HTTP door, when it has one: a custom operation of the SAME resource
+     * whose implementation hands the request to the system-of-record action executor. Absent means the action is reached
+     * from code only.
+     *
+     * Naming the door HERE is what lets the resource factory tell an action from a row write. Without it, the only thing the
+     * factory can see is the verb the operation borrows, and both available borrows were wrong (#1678 review, F1):
+     *
+     * - borrowing READ made a state-changing route a GET, and its required Idempotency-Key was refused at boot, because a
+     *   read-shaped operation claims its repeat changes nothing — Wonder Todos' backend could not start;
+     * - borrowing UPDATE read as a ROW write, so the factory demanded `writableVerbs: [update]` — a door onto the bound
+     *   entity's rows that nobody asked for.
+     *
+     * A named door is exempt from the row-write rules and held to the action's own instead: a WRITING action's door borrows
+     * a single-row mutation verb (so its route is not a GET and a retry is keyed), requires the key on every variant, and
+     * runs INLINE. See `assertHttpApiWriteDeclarationCoherence`.
+     */
+    operation: z.string().min(1).optional(),
+});
+/** Every action a binding declares, keyed by the application's action name. */
+export const SystemOfRecordActionDeclarationsSchema = z.record(SystemOfRecordActionNameSchema, SystemOfRecordActionDeclarationSchema);
+/** @wildo_source:part:end saas.models.system-of-record-actions */
+/**
+ * Odoo methods that READ, refused as actions.
+ *
+ * An action's answer is returned to its caller, and it is not confined the way the read lane confines rows: a
+ * `search_read` declared as an action would hand a unit-confined member every company's rows. Reads go through the
+ * read-through resource, whose pushdown and key-addressed admission are the confinement. A deny-list cannot be
+ * complete — Odoo lets any public method be called — so an author reviews what a declared method returns; these are the
+ * methods whose whole purpose is to return rows.
+ */
+export const ODOO_READ_METHODS_REFUSED_AS_ACTIONS = new Set([
+    'read', 'search', 'search_read', 'search_count', 'read_group', 'name_search', 'name_get', 'fields_get',
+    'web_read', 'web_search_read', 'web_read_group', 'export_data', 'get_views', 'load_views', 'default_get',
+]);
+/**
+ * Odoo methods that are ROW WRITES of the binding's own entity, refused as record-targeted actions: `write` and
+ * `unlink` on the bound model are exactly what `writableVerbs` opens (#1679), with its payload rules and its field-level
+ * trail. Declaring them as actions would open a second door onto the same change, one that skips both.
+ */
+export const ODOO_ROW_WRITE_METHODS_REFUSED_AS_RECORD_ACTIONS = new Set(['write', 'unlink']);
+/**
+ * Refuse every action declaration the engine could not honour, at AUTHORING (#1678). Throws a plain `Error` naming the
+ * action and the fix; the resource factory wraps it with the resource identifier.
+ *
+ * What is NOT decidable here, and why: whether the vendor's facet supports the call shape and whether the instance is
+ * partitioned both need the saas configuration and the facet map, which `shared-lib` does not see. Those are the boot
+ * checks (`collectSystemOfRecordActionDeclarationViolations` in the backend).
+ */
+export function assertSystemOfRecordActionDeclarationsCoherence(params) {
+    const { dialect, actions } = params;
+    for (const [actionName, action] of Object.entries(actions ?? {})) {
+        const refuse = (why) => {
+            throw new Error(`actions.${actionName}: ${why}`);
+        };
+        if (dialect === HttpApiTransportDialect.REST_JSON) {
+            refuse('a REST_JSON binding cannot declare actions: an arbitrary REST surface has no action convention for the engine to '
+                + 'compile (its row writes are declared per verb in `operations`; an action has no such fixed shape). Declare the '
+                + 'action on an Odoo or OData binding, or remove it.');
+        }
+        const shapeDialect = SYSTEM_OF_RECORD_ACTION_CALL_SHAPE_DIALECT[action.call.shape];
+        if (shapeDialect !== dialect) {
+            refuse(`the call shape '${action.call.shape}' is spoken over ${shapeDialect}, and this binding speaks ${dialect}.`);
+        }
+        if (action.target === SystemOfRecordActionTarget.RECORD && action.call.shape === SystemOfRecordActionCallShape.ODATA_UNBOUND_ACTION) {
+            refuse('an UNBOUND OData action acts on no record; declare target: none, or use a bound action.');
+        }
+        if (action.target === SystemOfRecordActionTarget.NONE && action.call.shape === SystemOfRecordActionCallShape.ODATA_BOUND_ACTION) {
+            refuse('a BOUND OData action is invoked on a record; declare target: record, or use the unbound action import.');
+        }
+        if (action.target === SystemOfRecordActionTarget.RECORD && action.partitionStance !== undefined) {
+            refuse('a record-targeted action takes its partition from the record it reads first, so a partition stance would be a second, '
+                + 'unchecked answer to the same question. Remove partitionStance.');
+        }
+        if (action.call.shape === SystemOfRecordActionCallShape.ODOO_EXECUTE_KW) {
+            if (ODOO_READ_METHODS_REFUSED_AS_ACTIONS.has(action.call.method)) {
+                refuse(`'${action.call.method}' reads rows, and an action's answer is not confined the way the read lane confines rows. `
+                    + 'Read through the read-through resource instead.');
+            }
+            if (action.target === SystemOfRecordActionTarget.RECORD && action.call.model !== undefined) {
+                refuse('a record-targeted action acts on the binding\'s own model, whose key codec and read gates address the record; '
+                    + 'declare the action on the binding of the model it acts on, or make it record-free.');
+            }
+            if (action.target === SystemOfRecordActionTarget.RECORD && ODOO_ROW_WRITE_METHODS_REFUSED_AS_RECORD_ACTIONS.has(action.call.method)) {
+                refuse(`'${action.call.method}' is a row write of this binding's entity; open it through writableVerbs instead (#1679).`);
+            }
+            if (action.call.inputPlacement === SystemOfRecordOdooActionInputPlacement.NONE
+                && Object.keys(action.input.shape).length > 0) {
+                refuse('inputPlacement \'none\' sends no input, so the declared input must be an empty object (z.object({})).');
+            }
+        }
+        if (action.partitionStance?.kind === SystemOfRecordActionPartitionStanceKind.MEMBER_UNIT_PARTITION) {
+            const parameter = action.partitionStance.parameter;
+            if (Object.prototype.hasOwnProperty.call(action.input.shape, parameter)) {
+                refuse(`the partition parameter '${parameter}' is placed by the engine from the caller's organization unit, so the input `
+                    + 'may not declare it — a caller who could send it would choose which company the action lands in.');
+            }
+            if (action.call.shape === SystemOfRecordActionCallShape.ODOO_EXECUTE_KW
+                && action.call.inputPlacement === SystemOfRecordOdooActionInputPlacement.NONE) {
+                refuse('a member-unit partition is written into the input, and inputPlacement \'none\' sends no input.');
+            }
+        }
+    }
+}
+//# sourceMappingURL=system-of-record-actions.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system-of-record-actions.shared.schemas.js","sourceRoot":"","sources":["../../../../src/systems-of-record/system-of-record-actions.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Declared ACTIONS of a system of record (#1678) — the named vendor operations an application may run against the\n * ERP it reads, beside the row reads and row writes its read-through bindings already open.\n *\n * Posting an invoice (Odoo `account.move` `action_post`), confirming a sales order, an OData bound or unbound action:\n * none of them is a row write, and before this nothing declared one and nothing executed one. The only thing that\n * could run one was the systems-of-record registry's raw access hand-out, which returns an instance's credentials and\n * records nothing (#1738 withdrew it from every application-facing door).\n *\n * ## The decision these declarations implement (Paul, 2026-09-25, on #1677/#1678)\n *\n * One vendor may serve two roles through two SEPARATE lanes. The system-of-record lane declares named actions and runs\n * them under the INSTANCE's service identity, confined to the owner organization and to the member's partition, with\n * its own audit event. The same vendor may also be a classical provider with its own user or organization connections.\n * The two share a vendor identity for display and compliance, and never a credential or a runtime object (#1049 D10).\n * There is no Odoo provider package, and a provider operation can never name a system-of-record instance.\n *\n * ## WHERE an action is declared, and the placement that was rejected\n *\n * On a read-through BINDING (`httpApiBinding.actions`), both kinds:\n *\n * - a RECORD-targeted action on the binding of the entity it acts on, which supplies the key codec that decodes the\n *   target id and the resource whose read gates decide whether the caller may reach that record;\n * - a RECORD-FREE action on the binding of the entity whose model (Odoo) or service (OData) the call is made against.\n *\n * Rejected: record-free actions on the INSTANCE (`systemsOfRecord.<name>.actions` in `wildo.saas.config.ts`). Three\n * reasons, any one sufficient. An action declares a Zod INPUT schema, and the saas configuration is parsed by the CLI\n * and the companion as data, where a schema object is not representable. An action declares the ROLES admitted to it,\n * which are the same role keys the resource's operations declare in `shared-lib`, and a second home for them would\n * drift. And the HTTP exposure of an action is a custom operation on a read-through resource, which lives in the\n * resource configuration anyway; the instance declaration is not in scope there (it lives in the application root, not\n * in `shared-lib`). What the instance keeps is what only the instance knows: whether its data is partitioned, which is\n * why a record-free action's partition stance is checked at boot, where both are visible.\n *\n * ## What is checked where\n *\n * - HERE, at authoring (the resource factory, through `assertHttpApiBindingDialectCoherence`): the call shape against\n *   the binding's dialect, the target against the call shape, the refused vendor methods, the stance's placement.\n * - At BOOT (the resources registry, where the instance and the vendor facet are visible): the facet declares the call\n *   shape, a record-free action on a PARTITIONED instance states its partition stance, and action names are unique per\n *   instance.\n * - Per REQUEST (the system-of-record action executor): who may run it, on which record, and what it sends.\n */\nimport { z } from 'zod';\nimport { isZodObject } from '@wildo-ai/zod-decorators';\n\nimport { HttpApiTransportDialect } from '../http-api-binding/http-api-transport-dialect.shared';\n\n/** @wildo_source:part:start saas.models.system-of-record-actions facet:layer:shared facet:audience:app-developer */\n\n/**\n * The wire SHAPE of a vendor action — how the engine calls it. Declared by the VENDOR FACET (which shapes its product\n * supports, `actionCallShapes`) and chosen per action by its declaration.\n *\n * REST_JSON has no member: an arbitrary REST surface has no action convention to compile against, and a declared method\n * plus path template is a design of its own. A REST_JSON binding declaring an action is refused by name. (REST_JSON\n * ROW writes are declared per verb since #1728 — `operations.create` / `update` / `delete` — because a row write has a\n * fixed meaning a method and a path can carry; an action's meaning is the vendor's, and has no such shape.)\n */\nexport enum SystemOfRecordActionCallShape {\n  /**\n   * Odoo's `object.execute_kw(db, uid, key, model, method, positional, keyword)` — any public model method, the\n   * credential inside the RPC arguments. A record-targeted call passes the record ids as its first positional\n   * argument, which is how Odoo addresses a recordset method such as `action_post`.\n   *\n   * spec-cite: Odoo 18.0 developer documentation, External API — \"Calling methods\" (the execute_kw argument layout).\n   */\n  ODOO_EXECUTE_KW = 'odoo-execute-kw',\n  /**\n   * An OData v4 BOUND action: `POST <EntitySet>(<key>)/<Namespace>.<Action>`, parameters in the JSON body.\n   *\n   * spec-cite: OData Version 4.01 Part 1: Protocol §11.5.5 (Actions) and §11.5.5.1 (Invoking an Action).\n   */\n  ODATA_BOUND_ACTION = 'odata-bound-action',\n  /**\n   * An OData v4 UNBOUND action reached through its action import: `POST /<ActionImport>`, parameters in the JSON body.\n   *\n   * spec-cite: OData Version 4.01 Part 1: Protocol §11.5.5.1 (Invoking an Action).\n   */\n  ODATA_UNBOUND_ACTION = 'odata-unbound-action',\n}\n\n/**\n * The dialect each call shape is spoken over. Total over {@link SystemOfRecordActionCallShape}, so a new shape is a\n * compile error here until somebody says which dialect it belongs to.\n */\nexport const SYSTEM_OF_RECORD_ACTION_CALL_SHAPE_DIALECT: Readonly<Record<SystemOfRecordActionCallShape, HttpApiTransportDialect>> = Object.freeze({\n  [SystemOfRecordActionCallShape.ODOO_EXECUTE_KW]: HttpApiTransportDialect.ODOO_JSONRPC,\n  [SystemOfRecordActionCallShape.ODATA_BOUND_ACTION]: HttpApiTransportDialect.ODATA,\n  [SystemOfRecordActionCallShape.ODATA_UNBOUND_ACTION]: HttpApiTransportDialect.ODATA,\n});\n\n/** What an action acts ON. */\nexport enum SystemOfRecordActionTarget {\n  /**\n   * ONE record of the binding's entity, addressed by its synthesized id. The record is READ FIRST through the binding's\n   * read gates (owner organization, partition), so a caller can act only on a record it could see — and a record\n   * outside its partition answers as absent, exactly as a read answers.\n   */\n  RECORD = 'record',\n  /** No record: a model-level Odoo method (`create`) or an OData unbound action. */\n  NONE = 'none',\n}\n\n/** Where an Odoo action's validated input goes in the `execute_kw` call. */\nexport enum SystemOfRecordOdooActionInputPlacement {\n  /** The input object is the keyword-argument dict. The default: most recordset methods take options by keyword. */\n  KEYWORD_ARGUMENTS = 'keyword-arguments',\n  /**\n   * The input object is the (next) POSITIONAL argument — after the id list on a record-targeted action, first on a\n   * record-free one. `create(vals)` is the canonical case.\n   */\n  POSITIONAL = 'positional',\n  /** The method takes nothing beyond its records (`action_post`). The declared input must then be empty. */\n  NONE = 'none',\n}\n\n/**\n * How a RECORD-FREE action relates to the instance's partitions (#1058), required at boot when the instance is\n * partitioned. A record-targeted action needs none: the record it reads first carries its partition.\n */\nexport enum SystemOfRecordActionPartitionStanceKind {\n  /**\n   * The action touches no partitioned data — a lookup of a vendor setting, an action whose effect no partition owns.\n   * The declaration must say WHY in `reason`, because a claim nothing checks has to be one a reviewer can read.\n   */\n  PARTITION_NEUTRAL = 'partition-neutral',\n  /**\n   * The action CARRIES the partition as one of its inputs, and the engine derives it from the caller's organization\n   * unit exactly as a read-through create is placed (#1679): a member of one unit lands in its partition, a member of\n   * several names the unit, and a caller may never supply the partition value itself.\n   */\n  MEMBER_UNIT_PARTITION = 'member-unit-partition',\n}\n\nexport const SystemOfRecordActionPartitionStanceSchema = z.discriminatedUnion('kind', [\n  z.strictObject({\n    kind: z.literal(SystemOfRecordActionPartitionStanceKind.PARTITION_NEUTRAL),\n    /** Why no partition is reached. Read by a reviewer; nothing can verify it, which is why it is required. */\n    reason: z.string().trim().min(20, 'Say why this action reaches no partitioned data — a reviewer reads this.'),\n  }),\n  z.strictObject({\n    kind: z.literal(SystemOfRecordActionPartitionStanceKind.MEMBER_UNIT_PARTITION),\n    /**\n     * The REMOTE parameter the placed partition value is written into (`company_id`): a key of the Odoo keyword\n     * arguments or of the positional input object, or a member of the OData body. The caller's input may not carry it.\n     */\n    parameter: z.string().min(1).max(120),\n  }),\n]);\nexport type SystemOfRecordActionPartitionStance = z.infer<typeof SystemOfRecordActionPartitionStanceSchema>;\n\nexport const SystemOfRecordActionCallSchema = z.discriminatedUnion('shape', [\n  z.strictObject({\n    shape: z.literal(SystemOfRecordActionCallShape.ODOO_EXECUTE_KW),\n    /** The model method, in Odoo's own spelling (`action_post`, `create`). */\n    method: z.string().regex(/^[a-z_][a-z0-9_]*$/, 'An Odoo method name is snake_case.').max(120),\n    /**\n     * The model the call is made on, for a RECORD-FREE action only. A record-targeted action acts on the binding's own\n     * model — the one its key codec and read gates describe — so naming another would decode the id against the wrong\n     * entity. Absent means the binding's `entityRef`.\n     */\n    model: z.string().regex(/^[a-z_][a-z0-9_.]*$/, 'An Odoo model name is dotted snake_case.').max(120).optional(),\n    inputPlacement: z.enum(SystemOfRecordOdooActionInputPlacement).default(SystemOfRecordOdooActionInputPlacement.KEYWORD_ARGUMENTS),\n  }),\n  z.strictObject({\n    shape: z.literal(SystemOfRecordActionCallShape.ODATA_BOUND_ACTION),\n    /** The namespace-qualified action name (`Microsoft.Dynamics.CRM.WinOpportunity`). */\n    qualifiedName: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$/, 'A bound action is named Namespace.Action.').max(200),\n  }),\n  z.strictObject({\n    shape: z.literal(SystemOfRecordActionCallShape.ODATA_UNBOUND_ACTION),\n    /** The action import's name, as the service root exposes it. */\n    actionImport: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'An action import is a simple identifier.').max(200),\n  }),\n]);\nexport type SystemOfRecordActionCall = z.infer<typeof SystemOfRecordActionCallSchema>;\n\n/**\n * The application's NAME for an action — lowerCamelCase, and distinct from the vendor's method name on purpose: the\n * name is what code, roles and audit rows speak (`postInvoice`), the call is what the vendor understands\n * (`account.move` `action_post`). Unique per INSTANCE across every binding, checked at boot, because callers address an\n * action by `(system, action)`.\n */\nexport const SYSTEM_OF_RECORD_ACTION_NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;\nexport const SystemOfRecordActionNameSchema = z.string().regex(SYSTEM_OF_RECORD_ACTION_NAME_PATTERN, 'An action name is lowerCamelCase.').max(64);\n\n/** A Zod OBJECT schema carried as a value — an action's input contract. */\nconst zodObjectSchemaValue = z.custom<z.ZodObject<z.ZodRawShape>>(\n  (value) => value !== null && typeof value === 'object' && isZodObject(value as z.ZodTypeAny),\n  { message: 'An action input is a Zod object schema (z.object({...})).' },\n);\n/** Any Zod schema carried as a value — an action's output contract. */\nconst zodSchemaValue = z.custom<z.ZodTypeAny>(\n  (value) => value !== null && typeof value === 'object' && typeof (value as { safeParse?: unknown }).safeParse === 'function',\n  { message: 'An action output is a Zod schema.' },\n);\n\n/** ONE declared action. */\nexport const SystemOfRecordActionDeclarationSchema = z.strictObject({\n  target: z.enum(SystemOfRecordActionTarget),\n  call: SystemOfRecordActionCallSchema,\n  /**\n   * The input contract, validated BEFORE anything is sent. Strict parsing is the caller's contract: a key the schema\n   * does not declare is refused rather than forwarded, so nothing reaches the vendor that the author did not name.\n   */\n  input: zodObjectSchemaValue,\n  /**\n   * The result contract. When declared, the vendor's answer is parsed through it and only the parsed value is returned;\n   * an answer it rejects after the vendor APPLIED the action is reported as an unknown outcome, never as \"not done\".\n   * Absent means the result is returned as the vendor sent it.\n   */\n  output: zodSchemaValue.optional(),\n  /**\n   * Whether the action CHANGES remote state. A writing action must carry an Idempotency-Key from EVERY caller, because a\n   * remote change cannot be rolled back, and its interrupted attempts are reported as an unknown outcome rather than as\n   * a failure. A non-writing action (a vendor computation that changes nothing) needs neither.\n   */\n  writes: z.boolean(),\n  /**\n   * Whether the VENDOR makes a repeated call harmless, so the transport may re-send it after a timeout or a 5xx. False\n   * unless the vendor offers an idempotency mechanism for this call; Odoo offers none, so no Odoo action is retry-safe.\n   * A writing action is never re-sent without an Idempotency-Key, whatever this says.\n   */\n  retrySafe: z.boolean().default(false),\n  /**\n   * The role keys admitted to run it, held in the OWNER organization (an organization role) or at application scope. A\n   * role held only inside an organization UNIT admits the action on that unit's partition alone.\n   */\n  roles: z.array(z.string().min(1)).min(1),\n  /**\n   * Whether a context with NO user and no machine principal — the engine's own batch, cron and queue work, a webhook, an\n   * autonomous agent with nobody behind it — may run it. Such a context then acts ORGANIZATION-WIDE on the owner\n   * organization's behalf, which is exactly why it is off unless declared.\n   */\n  admitsSystemInitiation: z.boolean().default(false),\n  /** A record-free action's relation to the instance's partitions; see {@link SystemOfRecordActionPartitionStanceKind}. */\n  partitionStance: SystemOfRecordActionPartitionStanceSchema.optional(),\n  /**\n   * The resource operation that is this action's HTTP door, when it has one: a custom operation of the SAME resource\n   * whose implementation hands the request to the system-of-record action executor. Absent means the action is reached\n   * from code only.\n   *\n   * Naming the door HERE is what lets the resource factory tell an action from a row write. Without it, the only thing the\n   * factory can see is the verb the operation borrows, and both available borrows were wrong (#1678 review, F1):\n   *\n   * - borrowing READ made a state-changing route a GET, and its required Idempotency-Key was refused at boot, because a\n   *   read-shaped operation claims its repeat changes nothing — Wonder Todos' backend could not start;\n   * - borrowing UPDATE read as a ROW write, so the factory demanded `writableVerbs: [update]` — a door onto the bound\n   *   entity's rows that nobody asked for.\n   *\n   * A named door is exempt from the row-write rules and held to the action's own instead: a WRITING action's door borrows\n   * a single-row mutation verb (so its route is not a GET and a retry is keyed), requires the key on every variant, and\n   * runs INLINE. See `assertHttpApiWriteDeclarationCoherence`.\n   */\n  operation: z.string().min(1).optional(),\n});\nexport type SystemOfRecordActionDeclaration = z.infer<typeof SystemOfRecordActionDeclarationSchema>;\n/** What an author writes — defaulted fields optional. */\nexport type SystemOfRecordActionDeclarationAuthored = z.input<typeof SystemOfRecordActionDeclarationSchema>;\n\n/** Every action a binding declares, keyed by the application's action name. */\nexport const SystemOfRecordActionDeclarationsSchema = z.record(SystemOfRecordActionNameSchema, SystemOfRecordActionDeclarationSchema);\nexport type SystemOfRecordActionDeclarations = z.infer<typeof SystemOfRecordActionDeclarationsSchema>;\n\n/** @wildo_source:part:end saas.models.system-of-record-actions */\n\n/**\n * Odoo methods that READ, refused as actions.\n *\n * An action's answer is returned to its caller, and it is not confined the way the read lane confines rows: a\n * `search_read` declared as an action would hand a unit-confined member every company's rows. Reads go through the\n * read-through resource, whose pushdown and key-addressed admission are the confinement. A deny-list cannot be\n * complete — Odoo lets any public method be called — so an author reviews what a declared method returns; these are the\n * methods whose whole purpose is to return rows.\n */\nexport const ODOO_READ_METHODS_REFUSED_AS_ACTIONS: ReadonlySet<string> = new Set([\n  'read', 'search', 'search_read', 'search_count', 'read_group', 'name_search', 'name_get', 'fields_get',\n  'web_read', 'web_search_read', 'web_read_group', 'export_data', 'get_views', 'load_views', 'default_get',\n]);\n\n/**\n * Odoo methods that are ROW WRITES of the binding's own entity, refused as record-targeted actions: `write` and\n * `unlink` on the bound model are exactly what `writableVerbs` opens (#1679), with its payload rules and its field-level\n * trail. Declaring them as actions would open a second door onto the same change, one that skips both.\n */\nexport const ODOO_ROW_WRITE_METHODS_REFUSED_AS_RECORD_ACTIONS: ReadonlySet<string> = new Set(['write', 'unlink']);\n\n/**\n * Refuse every action declaration the engine could not honour, at AUTHORING (#1678). Throws a plain `Error` naming the\n * action and the fix; the resource factory wraps it with the resource identifier.\n *\n * What is NOT decidable here, and why: whether the vendor's facet supports the call shape and whether the instance is\n * partitioned both need the saas configuration and the facet map, which `shared-lib` does not see. Those are the boot\n * checks (`collectSystemOfRecordActionDeclarationViolations` in the backend).\n */\nexport function assertSystemOfRecordActionDeclarationsCoherence(params: {\n  readonly dialect: HttpApiTransportDialect;\n  readonly actions: SystemOfRecordActionDeclarations | undefined;\n}): void {\n  const { dialect, actions } = params;\n  for (const [actionName, action] of Object.entries(actions ?? {})) {\n    const refuse = (why: string): never => {\n      throw new Error(`actions.${actionName}: ${why}`);\n    };\n    if (dialect === HttpApiTransportDialect.REST_JSON) {\n      refuse(\n        'a REST_JSON binding cannot declare actions: an arbitrary REST surface has no action convention for the engine to '\n        + 'compile (its row writes are declared per verb in `operations`; an action has no such fixed shape). Declare the '\n        + 'action on an Odoo or OData binding, or remove it.',\n      );\n    }\n    const shapeDialect = SYSTEM_OF_RECORD_ACTION_CALL_SHAPE_DIALECT[action.call.shape];\n    if (shapeDialect !== dialect) {\n      refuse(`the call shape '${action.call.shape}' is spoken over ${shapeDialect}, and this binding speaks ${dialect}.`);\n    }\n    if (action.target === SystemOfRecordActionTarget.RECORD && action.call.shape === SystemOfRecordActionCallShape.ODATA_UNBOUND_ACTION) {\n      refuse('an UNBOUND OData action acts on no record; declare target: none, or use a bound action.');\n    }\n    if (action.target === SystemOfRecordActionTarget.NONE && action.call.shape === SystemOfRecordActionCallShape.ODATA_BOUND_ACTION) {\n      refuse('a BOUND OData action is invoked on a record; declare target: record, or use the unbound action import.');\n    }\n    if (action.target === SystemOfRecordActionTarget.RECORD && action.partitionStance !== undefined) {\n      refuse(\n        'a record-targeted action takes its partition from the record it reads first, so a partition stance would be a second, '\n        + 'unchecked answer to the same question. Remove partitionStance.',\n      );\n    }\n    if (action.call.shape === SystemOfRecordActionCallShape.ODOO_EXECUTE_KW) {\n      if (ODOO_READ_METHODS_REFUSED_AS_ACTIONS.has(action.call.method)) {\n        refuse(\n          `'${action.call.method}' reads rows, and an action's answer is not confined the way the read lane confines rows. `\n          + 'Read through the read-through resource instead.',\n        );\n      }\n      if (action.target === SystemOfRecordActionTarget.RECORD && action.call.model !== undefined) {\n        refuse(\n          'a record-targeted action acts on the binding\\'s own model, whose key codec and read gates address the record; '\n          + 'declare the action on the binding of the model it acts on, or make it record-free.',\n        );\n      }\n      if (action.target === SystemOfRecordActionTarget.RECORD && ODOO_ROW_WRITE_METHODS_REFUSED_AS_RECORD_ACTIONS.has(action.call.method)) {\n        refuse(`'${action.call.method}' is a row write of this binding's entity; open it through writableVerbs instead (#1679).`);\n      }\n      if (\n        action.call.inputPlacement === SystemOfRecordOdooActionInputPlacement.NONE\n        && Object.keys(action.input.shape).length > 0\n      ) {\n        refuse('inputPlacement \\'none\\' sends no input, so the declared input must be an empty object (z.object({})).');\n      }\n    }\n    if (action.partitionStance?.kind === SystemOfRecordActionPartitionStanceKind.MEMBER_UNIT_PARTITION) {\n      const parameter = action.partitionStance.parameter;\n      if (Object.prototype.hasOwnProperty.call(action.input.shape, parameter)) {\n        refuse(\n          `the partition parameter '${parameter}' is placed by the engine from the caller's organization unit, so the input `\n          + 'may not declare it — a caller who could send it would choose which company the action lands in.',\n        );\n      }\n      if (action.call.shape === SystemOfRecordActionCallShape.ODOO_EXECUTE_KW\n        && action.call.inputPlacement === SystemOfRecordOdooActionInputPlacement.NONE) {\n        refuse('a member-unit partition is written into the input, and inputPlacement \\'none\\' sends no input.');\n      }\n    }\n  }\n}\n"]}

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

@@ -0,0 +1,159 @@
+/**
+ * `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 declare enum 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).
+     */
+    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`).
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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).
+     */
+    OAUTH2_JWT_BEARER = "oauth2-jwt-bearer"
+}
+/** Whether a kind obtains a token from a token endpoint — the three that need a minter and a cache. */
+export declare function systemOfRecordCredentialKindMintsToken(kind: SystemOfRecordCredentialKind): boolean;
+//# sourceMappingURL=system-of-record-credential-kind.shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system-of-record-credential-kind.shared.d.ts","sourceRoot":"","sources":["../../../../src/systems-of-record/system-of-record-credential-kind.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH;;;;;GAKG;AACH,oBAAY,4BAA4B;IACtC;;;;;;;;OAQG;IACH,oBAAoB,yBAAyB;IAE7C;;;;;;;;OAQG;IACH,cAAc,mBAAmB;IAEjC;;;;;;;;;OASG;IACH,aAAa,kBAAkB;IAE/B;;;;;;;;;;;OAWG;IACH,KAAK,UAAU;IAEf;;;;;;;;OAQG;IACH,gCAAgC,qCAAqC;IAErE;;;;;;;;;;;;;;;;OAgBG;IACH,qCAAqC,0CAA0C;IAE/E;;;;;;;;;OASG;IACH,iBAAiB,sBAAsB;CACxC;AAED,uGAAuG;AACvG,wBAAgB,sCAAsC,CAAC,IAAI,EAAE,4BAA4B,GAAG,OAAO,CAIlG"}