@wildo-ai/saas-models 1.1.4 → 1.1.6

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

@@ -10,84 +10,36 @@
  *
  * The binding is a REQUIRED companion declaration on any resource configuration that selects
  * `PersistenceAdapter.HTTP_API`. It answers, statically and per resource:
- * - WHERE the rows live (provider + entity), and in which transport dialect they are queried;
+ * - WHICH declared system of record the rows live in (`system`), and WHICH remote entity inside it;
  * - HOW a row is identified (ordered key components → the synthesized engine-facing `_id`);
- * - WHOSE identity reaches the target system (service principal vs per-user delegation);
- * - HOW tenancy confinement is expressed remotely — or the explicit single-tenant stance;
  * - WHAT the erasure story is (all three stances are first-class; none is silently defaulted);
  * - WHICH remote-call semantics apply (timeout, retry, rate budget, id-set bound).
  *
- * Credentials are NEVER declared here. They resolve at runtime through
- * `ExternalProvidersRegistryBackendService` against the `providerRef`, exactly as email, SMS and
- * billing providers do — the binding carries only the reference (plan decision D7).
+ * ## Three questions this used to answer and no longer does (#1055)
+ *
+ * WHOSE ACCOUNT (`connection`), WHERE the deployment is (`providerRef`) and HOW TENANCY is expressed
+ * remotely (`tenancy`) all left in the same change, and none of them was replaced by a smaller field:
+ *
+ * - WHOSE ACCOUNT has one legal answer for a system of record — the application's own service
+ *   identity (D12). The customer-connection case is case 2 of #1049 and keeps the connector lane.
+ * - WHERE is a property of the declared INSTANCE (`systemsOfRecord.<name>`) and of the ENVIRONMENT,
+ *   not of each resource. That is what lets two instances of one vendor exist at all.
+ * - TENANCY became a STAMP rather than a declaration: the row projector writes the owner
+ *   organization's id onto every remote row, so the per-row gate passes with no exemption.
+ *
+ * Credentials are NEVER declared here. They resolve at runtime through the systems-of-record
+ * registry, from environment variables DERIVED from the instance name — the binding carries only the
+ * name.
  */
 import { z } from 'zod';
-import { ExternalProvider_Connection_DelegationMode, ExternalProvider_Connection_OwnerScope, ExternalProvider_ConnectionShapeSchema, } from '@wildo-ai/external-connectors-models';
+import { HttpApiTransportDialect } from './http-api-transport-dialect.shared.js';
+import { HttpApiErasureStance } from './http-api-erasure-stance.shared.js';
+import { HttpApiRestWriteMethod, HttpApiRestWriteOperationSpecSchema, assertHttpApiRestWriteOperationShape, } from './http-api-rest-write-operations.shared.schemas.js';
+import { SystemOfRecordActionDeclarationsSchema, assertSystemOfRecordActionDeclarationsCoherence, } from '../systems-of-record/system-of-record-actions.shared.schemas.js';
 // --------------------------------
 // Transport dialect
 // --------------------------------
-/**
- * The query dialect the adapter speaks toward the target system. Closed vocabulary (slice 1);
- * SOAP is a possible later member over the same HTTP transport, and a direct-database kind would
- * be a NEW `PersistenceAdapter` member, never a dialect here.
- */
 /** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */
-export var HttpApiTransportDialect;
-(function (HttpApiTransportDialect) {
-    /**
-     * OData **v4** — one generic client: mechanical pushdown of
-     * `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata` boot-time
-     * verification probe of the committed declaration.
-     *
-     * ⚠ **This member is v4 ONLY, and that excludes SAP's most-used API.** An earlier revision of
-     * this comment named "SAP S/4HANA, Microsoft Dataverse/Dynamics 365" here, which is half right
-     * and was load-bearing — it is why nobody looked:
-     *
-     * | Target | Version | Consumable today |
-     * |---|---|---|
-     * | Microsoft Dataverse / Dynamics 365 Web API (`/api/data/v9.2/`) | v4 | ✅ |
-     * | SAP S/4HANA OData **v4** services (`/sap/opu/odata4/…`) | v4 | ✅ |
-     * | SAP `API_BUSINESS_PARTNER` (`/sap/opu/odata/sap/API_BUSINESS_PARTNER`) | **v2** | ❌ |
-     *
-     * v2 is not a v4 variant with a different header. Its collection envelope is
-     * `{ "d": { "results": [...], "__next": …, "__count": … } }` rather than
-     * `{ "value": [...], "@odata.nextLink": … }`; `Edm.DateTime` serializes as `"/Date(<ticks>)/"`
-     * rather than ISO 8601; `Edm.Decimal` and `Edm.Int64` serialize as JSON STRINGS rather than
-     * numbers; and JSON must be requested (`$format=json`) because v2 defaults to Atom/XML. So it
-     * changes the envelope, the paging property, the count property AND the value encoding — a
-     * reader written for one cannot read the other, and the mapping layer needs coercions the way
-     * Odoo needs `ODOO_FALSE_AS_NULL`.
-     * spec-cite: OData Version 2.0 JSON Format
-     * (https://www.odata.org/documentation/odata-version-2-0/json-format/) — the `d`/`results`/
-     * `__next`/`__count` envelope, the `/Date(<ticks>)/` DateTime literal, and Edm.Decimal /
-     * Edm.Int64 "formatted as a JSON string".
-     *
-     * Supporting v2 is an OPEN decision, not an oversight. Until it lands, point an ODATA binding at
-     * a v4 service: for SAP that means the OData v4 edition of the API where one is published.
-     */
-    HttpApiTransportDialect["ODATA"] = "odata";
-    /**
-     * Declared per-binding REST/JSON operation mapping (bespoke enterprise APIs). Unlike ODATA
-     * there is no generic client: each binding declares how read/list/count/search map onto
-     * concrete HTTP operations.
-     */
-    HttpApiTransportDialect["REST_JSON"] = "rest-json";
-    /**
-     * Odoo's external API (`/jsonrpc` + `execute_kw`). Promoted to its OWN dialect 2026-08-27 —
-     * D0's original "JSON-RPC is a thin envelope variant of REST_JSON" was corrected by measuring
-     * the protocol: it is generic like ODATA (no per-binding operation declarations — the model
-     * name IS `entityRef`, and read/list/count map onto `read`/`search_read`/`search_count`
-     * mechanically), but it speaks POSITIONAL arguments, its own domain filter language
-     * (`[['field','=',value], …]` with polish-notation `'|'` disjunction), and authenticates
-     * INSIDE the RPC args (`execute_kw(db, uid, api_key, …)`) rather than via HTTP headers.
-     * Forcing that through REST_JSON's declared-parameter model would have been the
-     * merge-distinct-concepts failure `design-philosophy.md` forbids.
-     *
-     * Structural constraint (schema-enforced): exactly ONE key field with the `INTEGER` codec —
-     * Odoo row ids are integers, always.
-     */
-    HttpApiTransportDialect["ODOO_JSONRPC"] = "odoo-jsonrpc";
-})(HttpApiTransportDialect || (HttpApiTransportDialect = {}));
 // --------------------------------
 // Whose identity reaches the target
 // --------------------------------
@@ -100,7 +52,9 @@ export var HttpApiTransportDialect;
  * two independent questions with five real answers (`ExternalProvider_ConnectionShape`):
  *
  *   - a user's own personal grant is `USER × SERVICE`;
- *   - a tenant's registration acting for one of its members is `ORGANIZATION × USER`.
+ *   - one member's own account, linked for the whole organization, is `ORGANIZATION × USER`
+ *     (decided on wildo-ai/wildo-ai#18: every member spends it, and the linking member is named in
+ *     the audit trail).
  *
  * Both are "per-user OAuth against the target", they resolve DIFFERENT credentials, and the single
  * field cannot distinguish them. So mapping it onto a target would have silently picked a lane —
@@ -114,55 +68,33 @@ export var HttpApiTransportDialect;
 // --------------------------------
 // Erasure stance (GDPR Art. 17 on rows we do not own)
 // --------------------------------
-/**
- * The declared erasure stance of an HTTP_API-backed resource. All three stances are first-class
- * from slice 1 (decision D6, 2026-08-26); a binding MUST declare one — an undeclared stance is a
- * registration refusal, because `exportSubject` is a fail-closed obligation on every resource and
- * "we cannot delete rows we do not own" is not an answer the framework may imply silently.
+/*
+ * `HttpApiErasureStance` lives in `./http-api-erasure-stance.shared` and is published from the package ROOT
+ * (#1710): three root-exported contracts name it, and a nominal enum reachable only through this subpath
+ * made their inferred types unnameable for a root-only consumer (TS2742). The binding arms below still
+ * discriminate on it.
  */
-export var HttpApiErasureStance;
-(function (HttpApiErasureStance) {
-    /**
-     * (6a) The resource declares it holds NO personal/subject data. Registration verifies the
-     * declaration is coherent (e.g. `exportSubject` posture) and erasure is structurally N/A for
-     * the remote rows.
-     */
-    HttpApiErasureStance["NO_SUBJECT_DATA"] = "no-subject-data";
-    /**
-     * (6b) The binding declares HOW erasure reaches the foreign system: one named API operation the
-     * engine invokes on a subject-erasure request. This is a single declared write and does NOT
-     * require general write support (slice 1 stays read-only otherwise).
-     */
-    HttpApiErasureStance["EXTERNAL_ERASURE_OPERATION"] = "external-erasure-operation";
-    /**
-     * (6c) Erasure REFUSES by default; an explicit, per-request, audited controller acknowledgement
-     * lets it proceed and records the un-erased remote rows at high severity. Mirrors the existing
-     * administrative-floor acknowledgement shape (`administrative-continuity-floors.md`): the record
-     * is the control. NEVER a standing default — the acknowledgement is per erasure request.
-     */
-    HttpApiErasureStance["CONTROLLER_ACKNOWLEDGED_NON_ERASURE"] = "controller-acknowledged-non-erasure";
-})(HttpApiErasureStance || (HttpApiErasureStance = {}));
-// --------------------------------
-// Tenancy stance
-// --------------------------------
-/**
- * How tenant confinement is enforced against the remote system (requirements R4/R16).
+/*
+ * ─── `HttpApiTenancyStance` was REMOVED here (#1055), and NOT replaced by a narrower vocabulary ──
+ *
+ * It had two members and both were wrong for a system of record.
+ *
+ * `SCOPE_FILTER_PUSHDOWN` pushed the engine's contextual scope predicate into the remote query —
+ * which means sending WILDO's own organization id to a system that has never heard of it, as a
+ * filter value. Nothing on the far side could match it, so the stance could only ever have worked
+ * against a remote that happened to store Wildo ids.
+ *
+ * `SINGLE_TENANT_BINDING` then became the only truth, and a declaration with one legal value is a
+ * question nobody should be asked — plus it carried a `justification` string, which made every
+ * binding restate the same sentence.
+ *
+ * What replaced it is a different MECHANISM rather than a smaller field: the row projector stamps
+ * the owner organization's id onto each remote row, so the per-row tenant gate passes with no
+ * exemption and a request under another organization's URL is refused by the branch that already
+ * existed. Narrowing a system of record BY organization unit is #1058, and it belongs to the
+ * INSTANCE and its vendor facet — one declaration for every resource that reads that system,
+ * rather than one per binding.
  */
-export var HttpApiTenancyStance;
-(function (HttpApiTenancyStance) {
-    /**
-     * The engine's contextual scope predicate is pushed down into every remote query against a
-     * declared remote field. Registration REFUSES a binding whose declared surface cannot express
-     * the scope predicate — a query-time refusal would be a data leak one missed branch away.
-     */
-    HttpApiTenancyStance["SCOPE_FILTER_PUSHDOWN"] = "scope-filter-pushdown";
-    /**
-     * The binding declares the target system serves exactly ONE tenant (the normal case for an
-     * internal tool on one enterprise's IS). Scope pushdown is then N/A by declaration — an
-     * explicit, audited stance, never an inferred one (R16).
-     */
-    HttpApiTenancyStance["SINGLE_TENANT_BINDING"] = "single-tenant-binding";
-})(HttpApiTenancyStance || (HttpApiTenancyStance = {}));
 // --------------------------------
 // Key declaration + component codecs (paper A)
 // --------------------------------
@@ -190,6 +122,82 @@ export var HttpApiKeyComponentCodec;
      */
     HttpApiKeyComponentCodec["DATETIME_ISO"] = "datetime-iso";
 })(HttpApiKeyComponentCodec || (HttpApiKeyComponentCodec = {}));
+// --------------------------------
+// Write verbs a binding OPENS (#1679)
+// --------------------------------
+/**
+ * A row-level write a read-through resource may send to its system of record.
+ *
+ * Three members and no bulk ones, deliberately. A bulk write against a system the platform does not
+ * own has no atomicity to offer — ten rows are ten remote calls, any of which can fail after the ones
+ * before it landed — so the engine opens single-row create, update and delete by key, and nothing
+ * else. `createMany`, `updateMany`, `deleteMany`, the guarded atomic primitives and the raw-filter
+ * doors stay refused by name on the repository.
+ *
+ * ## Why the binding declares them at all, when the resource already lists its operations
+ *
+ * Because opening a write door into somebody else's ERP is a decision of its own, taken where the
+ * remote contract is written. The resource's operation list says which HTTP routes exist; this says
+ * the binding may WRITE through them. The resource factory refuses the two disagreeing in EITHER
+ * direction — a write operation whose verb the binding does not open, and an opened verb no operation
+ * uses — so the second declaration can never drift from the first into an inert door or an open one.
+ *
+ * Absent is empty: every binding written before #1679 stays read-only without a change.
+ */
+export var HttpApiWriteVerb;
+(function (HttpApiWriteVerb) {
+    /** A new remote row. The engine derives its partition from the caller's organization unit. */
+    HttpApiWriteVerb["CREATE"] = "create";
+    /** A change to one remote row, addressed by its synthesized id. Read first, then written. */
+    HttpApiWriteVerb["UPDATE"] = "update";
+    /** The removal of one remote row, addressed by its synthesized id. Read first, then deleted. */
+    HttpApiWriteVerb["DELETE"] = "delete";
+})(HttpApiWriteVerb || (HttpApiWriteVerb = {}));
+/**
+ * What protects an UPDATE against overwriting a change made since its author read the row (#1724, #1726, #1728) —
+ * declared by every binding that opens UPDATE, whatever its dialect (ODOO_JSONRPC, ODATA, REST_JSON).
+ *
+ * ## Why a binding must say this at all
+ *
+ * An update that carries no version is last-writer-wins, whatever the vendor could have offered: Odoo's external API
+ * applies `write(ids, vals)` unconditionally, a REST_JSON write is sent with no precondition, and an OData service
+ * applies a `PATCH` whose `If-Match` matches — which a caller who never read the row cannot make match anything but
+ * `*`. A default nobody chose is a lost update nobody expects, so a binding that opens UPDATE states which of the two it
+ * accepts, and the factory refuses the omission.
+ *
+ * ## What VERSION_CHECKED is, honestly — it depends on the dialect
+ *
+ * The caller sends the row version it read (the local field named by `versionField`, mapped onto the vendor's
+ * `rowVersionField` — Odoo `write_date`, an OData service's `@odata.etag`). The engine reads the row just before
+ * writing it — the read it already makes to check the partition — and refuses the update when the versions differ,
+ * before anything is sent. Then:
+ *
+ * - **Odoo: best-effort.** Odoo takes no precondition, so the comparison and the write are two calls. That NARROWS the
+ *   race to the gap between them; it does NOT close it. A change landing inside that gap is overwritten, and a vendor
+ *   that serves its version coarsely (Odoo: to the second) cannot tell two changes in the same second apart.
+ * - **REST_JSON: best-effort, as on Odoo** — the write is sent as declared, with no precondition. It is available only
+ *   where the vendor facet declares a `rowVersionField`; neither the Salesforce nor the NetSuite facet does, so a
+ *   binding against them states LAST_WRITER_WINS (startup refuses VERSION_CHECKED there).
+ * - **OData: atomic.** The version is also sent as `If-Match`, so the SERVICE compares it with the row it is about to
+ *   change and answers `412 Precondition Failed` without applying anything when it moved — the gap is closed by the
+ *   vendor, not narrowed by the engine.
+ *   spec-cite: OData Version 4.01 Part 1: Protocol §8.2.4 (Header If-Match).
+ */
+export var HttpApiWriteConcurrencyMode;
+(function (HttpApiWriteConcurrencyMode) {
+    /**
+     * Every UPDATE carries the version its author read, and a stale one is refused before sending. Best-effort on Odoo
+     * and REST_JSON; atomic on OData, where the version also travels as `If-Match`.
+     */
+    HttpApiWriteConcurrencyMode["VERSION_CHECKED"] = "version-checked";
+    /**
+     * No check against the version the CALLER read: the last update sent wins. Stated, so it is a decision rather than an
+     * accident. On OData the engine still sends the entity tag of the row it read first (or `*` when the row carries
+     * none), so a row that moved between that read and the write is refused, and a row deleted in between is never
+     * re-created by an upsert.
+     */
+    HttpApiWriteConcurrencyMode["LAST_WRITER_WINS"] = "last-writer-wins";
+})(HttpApiWriteConcurrencyMode || (HttpApiWriteConcurrencyMode = {}));
 /** @wildo_source:part:end saas.models.http-api-binding */
 /**
  * One ordered component of the remote entity's key. `keyFields` order is the ENCODING order —
@@ -208,13 +216,52 @@ export const HttpApiKeyFieldSchema = z.object({
 // --------------------------------
 // Field mapping
 // --------------------------------
+/** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */
+/**
+ * What kind of TEMPORAL value a remote field holds, when a query statement compares it (#1972).
+ *
+ * A statement language spells a date and a date-time differently, and neither accepts a quoted string:
+ *
+ * | language | `DATE` | `DATE_TIME` |
+ * |---|---|---|
+ * | SOQL | `2026-01-05` (unquoted) | `2026-01-05T10:00:00Z` (unquoted, whole seconds) |
+ * | SuiteQL | `TO_DATE('2026-01-05', 'YYYY-MM-DD')` ¹ | `TO_DATE('2026-01-05 10:00:00', 'YYYY-MM-DD HH24:MI:SS')` |
+ *
+ * ¹ spec-cite: N/A — the date-only mask is Oracle SQL's `TO_DATE` convention (SuiteQL is SQL-92 / Oracle SQL);
+ * NetSuite's page shows only the date-time mask cited below.
+ *
+ * Which one a field needs is a fact about the REMOTE column that nothing in a local `Date` carries, so a
+ * statement read that filters a date field DECLARES it; a date compared with an undeclared field is refused
+ * rather than guessed, because the wrong form is refused by the vendor or silently compares as text.
+ * spec-cite: Salesforce, "SOQL and SOSL Reference" v68.0, WHERE › "Date Formats and Date Literals in WHERE" —
+ * `WHERE CreatedDate > 2005-10-08T01:02:03Z`; `date YYYY-MM-DD`; `dateTime YYYY-MM-DDThh:mm:ss+hh:mm,
+ * YYYY-MM-DDThh:mm:ss-hh:mm, or YYYY-MM-DDThh:mm:ssZ`.
+ * spec-cite: Oracle NetSuite, "SuiteQL Performance and Best Practices" (article_0824094533) — "You can't use date
+ * literals. You must encapsulate dates using the `to_date()` function."; "Do not use plain string values for date
+ * comparisons."; `where lastmodifieddate >= TO_DATE('2024-01-01 00:00:00', 'yyyy-mm-dd hh24:mi:ss')`.
+ *
+ * Read by the REST_JSON STATEMENT compilers only; declared on another dialect, or on a REST_JSON binding none of
+ * whose read members is a statement, it would change nothing, so the binding coherence refuses it there.
+ */
+export var HttpApiRemoteTemporalKind;
+(function (HttpApiRemoteTemporalKind) {
+    /** A calendar date with no time — SOQL `date`, a NetSuite date column. */
+    HttpApiRemoteTemporalKind["DATE"] = "date";
+    /** An instant — SOQL `dateTime`, a NetSuite datetime column. */
+    HttpApiRemoteTemporalKind["DATE_TIME"] = "date-time";
+})(HttpApiRemoteTemporalKind || (HttpApiRemoteTemporalKind = {}));
 /**
  * Local-to-remote field name mapping for fields whose names differ. Fields not listed map by
  * identity (same name both sides). Key components are declared in `keyFields`, not here.
+ *
+ * A REST_JSON statement read that FILTERS a temporal field lists it here — with the same name on both sides
+ * when they agree — to declare its `temporalKind`.
  */
 export const HttpApiFieldMappingSchema = z.object({
     localField: z.string().min(1),
     remoteField: z.string().min(1),
+    /** The remote column's temporal kind, when a statement compares it with a date — see {@link HttpApiRemoteTemporalKind}. */
+    temporalKind: z.enum(HttpApiRemoteTemporalKind).optional(),
 });
 // --------------------------------
 // Remote-call semantics (decision D10 / requirement R15)
@@ -228,8 +275,9 @@ export const HttpApiRemoteCallSemanticsSchema = z.object({
     /** Per-call timeout. */
     timeoutMs: z.number().int().positive().max(120_000).default(10_000),
     /**
-     * Retry policy for idempotent READ-family calls only. Writes (when D4 lands) never retry
-     * implicitly.
+     * Retry policy for idempotent READ-family calls. A WRITE (#1679) is retried only when its dialect
+     * declares a remote idempotency mechanism; otherwise it is sent exactly once, and a timeout on it
+     * is reported as an UNKNOWN outcome rather than retried into a duplicate.
      */
     retry: z
         .object({
@@ -248,6 +296,25 @@ export const HttpApiRemoteCallSemanticsSchema = z.object({
      * (scope-down paper, shape T2).
      */
     maxIdSetSize: z.number().int().positive().max(500).default(50),
+    /**
+     * Upper bound for the translated PARTITION confinement (#1058 E7) — `key ∈ {every partition this
+     * caller may touch}`, compiled per dialect.
+     *
+     * Its own knob rather than a reuse of `maxIdSetSize`, because the two bound different things and
+     * would be tuned against different facts. An id set is a CALLER's request and its size is a
+     * property of what they asked for; a partition set is a property of the DEPLOYMENT — how many
+     * legal entities live inside one system of record — and of the caller's grant. An operator raising
+     * one for a bulk read has no reason to raise the other, and lowering `maxIdSetSize` to tame a URL
+     * would silently cut the confinement off at the knees: above the bound the adapter REFUSES, so a
+     * confinement that cannot compile is a read that cannot happen.
+     *
+     * The default is deliberately far above `maxIdSetSize`'s. A corporate with more than two hundred
+     * legal entities inside ONE system of record exists, and when it does the honest answer is a
+     * refusal that NAMES the bound rather than a request the target truncates or rejects with a 414.
+     * Refused rather than paged: splitting one read into N requests is a different mechanism, and one
+     * that would make a single `total` impossible to compute.
+     */
+    maxPartitionSetSize: z.number().int().positive().max(1_000).default(200),
 });
 // --------------------------------
 // Dialect-specific declarations
@@ -255,15 +322,29 @@ export const HttpApiRemoteCallSemanticsSchema = z.object({
 /**
  * HTTP methods a declared read-family operation may use. Deliberately NOT the full HTTP verb set
  * (`API_HttpMethod` in `@wildo-ai/external-connectors-models` describes provider-protocol
- * operations): slice 1 is read-only, so the closed vocabulary is the read-safe verb plus POST —
+ * operations): these are READ members, so the closed vocabulary is the read-safe verb plus POST —
  * because JSON-RPC (Odoo) and many enterprise search endpoints are POST-shaped even for reads.
- * Write verbs (PUT/PATCH/DELETE) enter only with the D4 write story, as their own decision.
+ * Row writes are opened by `writableVerbs` (#1679) and framed by each dialect's write compiler; a
+ * REST_JSON write surface is its own declaration (#1728), never a widening of this enum.
  */
 export var HttpApiRestOperationMethod;
 (function (HttpApiRestOperationMethod) {
     HttpApiRestOperationMethod["GET"] = "GET";
     HttpApiRestOperationMethod["POST"] = "POST";
 })(HttpApiRestOperationMethod || (HttpApiRestOperationMethod = {}));
+/** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */
+/**
+ * Where a declared REST parameter is placed on the request, when the method's own answer is wrong for it (#1686).
+ */
+export var HttpApiRestParameterPlacement;
+(function (HttpApiRestParameterPlacement) {
+    /**
+     * The URL query string, whatever the method — NetSuite's SuiteQL `limit` and `offset` on a POST.
+     * spec-cite: Oracle NetSuite, "Executing SuiteQL Queries Through REST Web Services" (section_157909186990) — the
+     * statement is POSTed as `{"q": …}` and paged by `?limit=10&offset=10` on the request URL.
+     */
+    HttpApiRestParameterPlacement["QUERY_STRING"] = "query-string";
+})(HttpApiRestParameterPlacement || (HttpApiRestParameterPlacement = {}));
 /**
  * REST_JSON per-operation declaration: how one read-family member maps onto a concrete HTTP
  * operation. Deliberately minimal in slice 1 — pagination/filter parameter NAMES are declared,
@@ -279,14 +360,182 @@ export var HttpApiRestOperationMethod;
  * — ten exported symbols with zero code readers — was deleted in #331 rather than wired up, so
  * "what a provider can do" has one description instead of two.)
  *
- * The convergence this JSDoc asked to be RECORDED rather than performed implicitly happened in
- * S3a (#331), and it is not the merge that sentence was written to prevent. A member of
- * {@link HttpApiRestOperationsSchema} may now be a {@link HttpApiRestOperationReferenceSchema}
- * naming an operation in the PROVIDER's own `rest.operations` catalogue — the vendor half stated
- * once per provider, the resource half (local-field filter mapping, search parameter, which path
- * token takes the key) still stated here, because a provider has never heard of a local field
- * name. Both forms stay: an inline spec is still the right answer for a target no provider wraps.
+ * The convergence performed in S3a (#331) — a member naming an operation in a PROVIDER's own
+ * catalogue — was UNDONE in #1055. A system of record is not a connector (D10), and a read that
+ * depends on a provider catalogue being loadable is the crossing that decision forbids. An inline
+ * spec is now the only form, which is what every authored binding used anyway.
+ */
+/**
+ * A query LANGUAGE a REST system of record reads through, rather than a set of filter parameters
+ * (#1293).
+ *
+ * Two vendors read this way and neither can be expressed as parameters: Salesforce takes SOQL and
+ * NetSuite takes SuiteQL, each as ONE statement naming the fields, the entity, the predicates and
+ * the order. A `filterParams` map cannot say "SELECT these columns FROM that object", so without this
+ * neither vendor can be declared at all.
+ *
+ * ## Why this is a closed vocabulary and not a template string
+ *
+ * A statement is BUILT, and building means escaping. Each language has its own literal rules and its
+ * own paging spelling, and a template with `{filter}` holes would put the escaping in the author's
+ * hands — an injection surface in a file nobody reviews as one. The engine builds the statement and
+ * the vocabulary names which grammar to build.
+ *
+ * This is the same trade the OData compiler already makes for `$filter`: expressions are composed
+ * here, literals are escaped by one function, and no authored string reaches the wire uninspected.
+ */
+export var HttpApiQueryStatementLanguage;
+(function (HttpApiQueryStatementLanguage) {
+    /**
+     * Salesforce Object Query Language.
+     *
+     * spec-cite: Salesforce Developers, "SOQL and SOSL Reference" —
+     * https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/
+     *
+     * `SELECT *` does not exist: every field is named, which the binding's `fieldMappings` and key
+     * fields already supply. Paging is by the response's own continuation rather than by `OFFSET`,
+     * which SOQL bounds at 2000 rows.
+     */
+    HttpApiQueryStatementLanguage["SOQL"] = "soql";
+    /**
+     * NetSuite SuiteQL — an SQL-92 dialect over its analytics schema.
+     *
+     * spec-cite: Oracle NetSuite, "SuiteQL" —
+     * https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156257770590.html
+     *
+     * Paged by `limit` / `offset` QUERY parameters rather than inside the statement, which is why the
+     * statement declaration and `pagingParams` are independent.
+     */
+    HttpApiQueryStatementLanguage["SUITEQL"] = "suiteql";
+})(HttpApiQueryStatementLanguage || (HttpApiQueryStatementLanguage = {}));
+/**
+ * Where a KEYSET page's size bound goes, per statement language (#1686).
+ *
+ * A keyset page is "the next N rows after the last key", so the statement's predicate and order are
+ * the same in every language — `<key> > <last key> … ORDER BY <key> ASC` — and only the size bound
+ * differs. Decided by the LANGUAGE, never declared by an author: it is a fact about the grammar.
+ */
+export var HttpApiKeysetPageBound;
+(function (HttpApiKeysetPageBound) {
+    /**
+     * The statement carries `LIMIT <n>` itself — SOQL, which has no size parameter on `/query`.
+     *
+     * The vendor may still split the limited result into several BATCHES and answer the first one with
+     * a continuation (`nextRecordsUrl`), so a keyset page on this bound follows the operation's declared
+     * `cursorPath` inside the page until the result is exhausted — which is why the bound requires one.
+     * Without it, a batch shorter than the limit would read as the end of the pass and every row after
+     * it would go unread, and a DELETE orphan policy would then delete them.
+     * spec-cite: Salesforce REST API Developer Guide v68.0, "Query" — "up to 2,000 records can be returned
+     * at a time … the returned batch can include fewer records than the limit or what's set in the
+     * request … If the total number of results exceeds the limit or the requested number of results, the
+     * response contains the first batch of records, a false value for done, and a query locator."
+     */
+    HttpApiKeysetPageBound["STATEMENT_LIMIT_CLAUSE"] = "statement-limit-clause";
+    /**
+     * The operation's declared `pagingParams.limitParam` carries the size, and its `offsetParam` is sent
+     * as 0 on every page — SuiteQL, which pages by `limit`/`offset` query parameters.
+     *
+     * Offset 0 always: each page is a NEW query that starts after the last key, so no offset is ever
+     * needed, and none of the offset rules (an offset divisible by the limit, the result ceiling) is
+     * ever reached.
+     * spec-cite: Oracle NetSuite, "Collection Paging" (section_156414087576) — "You can only set offset
+     * and limit values in a way that the offset is divisible by the limit"; "Executing SuiteQL Queries
+     * Through REST Web Services" (section_157909186990) — "Using SuiteQL queries, you can return a
+     * maximum of 100,000 results."
+     */
+    HttpApiKeysetPageBound["LIMIT_PARAMETER"] = "limit-parameter";
+})(HttpApiKeysetPageBound || (HttpApiKeysetPageBound = {}));
+/** The page bound of each statement language. A `Record` over the enum, so a new language is a compile error until it has one. */
+export const HTTP_API_KEYSET_PAGE_BOUND = {
+    [HttpApiQueryStatementLanguage.SOQL]: HttpApiKeysetPageBound.STATEMENT_LIMIT_CLAUSE,
+    [HttpApiQueryStatementLanguage.SUITEQL]: HttpApiKeysetPageBound.LIMIT_PARAMETER,
+};
+/**
+ * The key codecs a keyset may walk (#1686): an INTEGER compares as a number and a STRING by code
+ * unit, and the engine CHECKS every served page against that order before trusting its last key.
+ *
+ * GUID and DATETIME_ISO are refused. A GUID has no order the vendors agree on — SQL Server sorts a
+ * `uniqueidentifier` by its last bytes first — so a page could never be checked; a datetime is not
+ * unique, and a keyset on a non-unique column skips the rows that share the boundary value.
+ */
+export const HTTP_API_KEYSET_ELIGIBLE_CODECS = [
+    HttpApiKeyComponentCodec.INTEGER,
+    HttpApiKeyComponentCodec.STRING,
+];
+/**
+ * A declared KEYSET on a statement read (#1686) — what lets a REST system of record feed a pipeline.
+ *
+ * ## What it makes the engine build
+ *
+ * For the pipeline's extraction, the `list` member's statement becomes
+ *
+ * ```
+ * SELECT <mapped fields> FROM <entity> WHERE <sourceFilter> AND <key> > <last key> ORDER BY <key> ASC
+ * ```
+ *
+ * with the page size bounded per {@link HttpApiKeysetPageBound} (SOQL `LIMIT <n>`; SuiteQL
+ * `limit=<n>&offset=0`). The last key of each page is the pipeline's persisted cursor, and a page
+ * shorter than asked ends the pass — the Odoo id-keyset discipline, drift-safe for the same reason: a
+ * row inserted or deleted mid-pass never shifts the rows after the cursor, so none is skipped or read
+ * twice. Offset paging has neither property, which is why a REST source without a keyset stays
+ * refused.
+ *
+ * ## Why there is no cursor PLACEHOLDER to write
+ *
+ * The statement is BUILT by the engine (#1293), never templated by an author, so there is nowhere for a
+ * `:cursor` placeholder to go and no ORDER BY an author could forget: declaring the keyset is what puts
+ * both into the statement, and the engine writes them itself. What an author declares is only which
+ * column the walk runs on.
+ *
+ * ## Which column
+ *
+ * The binding's ONE key field — unique and immutable, which is what a keyset needs. Named by its
+ * remote field; its codec is the key field's own, so the two cannot disagree. A composite key is
+ * refused: one component of it is not unique.
+ *
+ * ## A vendor continuation is followed INSIDE a page, never persisted
+ *
+ * Salesforce's `nextRecordsUrl` names a server-side query locator. How long a locator lives is not
+ * stated in the REST API guide (UNVERIFIED), so it is never the cross-run cursor: the key is.
+ */
+export const HttpApiQueryStatementKeysetSchema = z.strictObject({
+    /** The remote field of the binding's single key field — Salesforce `Id`, NetSuite `id`. */
+    keyRemoteField: z.string().min(1),
+});
+/**
+ * How a read member builds and sends a query STATEMENT (#1293).
+ *
+ * Declared per operation rather than per binding, because a vendor's `read` and `list` genuinely
+ * differ: Salesforce addresses one record at `/sobjects/Account/{key}` and queries collections
+ * through `/query`, and only the second is a statement at all.
  */
+export const HttpApiQueryStatementSpecSchema = z.object({
+    language: z.enum(HttpApiQueryStatementLanguage),
+    /**
+     * The parameter or body member the statement is placed in (`q` for both vendors surveyed).
+     *
+     * WHERE it lands is not declared, because the operation's own `method` already decides: a GET puts
+     * parameters in the query string and a POST puts them in the JSON body, which is what the request
+     * builder has always done. A `placement` field was drafted here and removed before it shipped — it
+     * would have been a second declaration of something the method already says, free to disagree with
+     * it. Salesforce is a GET with `?q=`, NetSuite a POST with `{"q": …}`, and neither needs to be told
+     * twice. PAGING is the one parameter the method places wrongly for a vendor — NetSuite reads its
+     * `limit`/`offset` from the URL of that POST — which is why `pagingParams` carries its own
+     * `placement` (#1686) while the statement does not.
+     */
+    parameterName: z.string().min(1),
+    /**
+     * The object the statement selects FROM. Absent = the binding's `entityRef`, which is the ordinary
+     * case; present when the vendor's query schema names an object differently from its REST resource.
+     */
+    fromEntity: z.string().min(1).optional(),
+    /**
+     * The KEYSET a pipeline extraction walks (#1686) — see {@link HttpApiQueryStatementKeysetSchema}.
+     * Declared on the `list` member only. Absent = the binding can be read through, and cannot feed a
+     * pipeline.
+     */
+    keyset: HttpApiQueryStatementKeysetSchema.optional(),
+});
 export const HttpApiRestOperationSpecSchema = z.object({
     /** HTTP method for this read-family operation. */
     method: z.enum(HttpApiRestOperationMethod),
@@ -300,6 +549,15 @@ export const HttpApiRestOperationSpecSchema = z.object({
         .object({
         limitParam: z.string().min(1),
         offsetParam: z.string().min(1),
+        /**
+         * Where the two paging parameters go (#1686). Absent = where the operation's method puts every
+         * parameter: the query string of a GET, the JSON body of a POST.
+         *
+         * NetSuite is why this exists: its SuiteQL read is a POST whose BODY is the statement and whose
+         * paging is in the URL, so a method-placed `limit` lands in the body, where the vendor does not
+         * read it, and the page is not bounded at all.
+         */
+        placement: z.enum(HttpApiRestParameterPlacement).optional(),
     })
         .optional(),
     /**
@@ -326,73 +584,63 @@ export const HttpApiRestOperationSpecSchema = z.object({
         rpcMethod: z.string().min(1),
     })
         .optional(),
-});
-/**
- * A REFERENCE into the PROVIDER's own operation catalogue, instead of restating the operation here
- * (S3a, #331 — the convergence {@link HttpApiRestOperationSpecSchema}'s JSDoc asked to be recorded
- * as a decision rather than performed implicitly).
- *
- * ## The split, and why it is not a merge
- *
- * The two schemas describe different things and both survive. A provider operation is VENDOR-
- * shaped: method, path, result path, how the vendor pages. An ETL read surface is RESOURCE-shaped:
- * which LOCAL field is translatable to which remote filter parameter, which parameter carries the
- * search text, which path token receives this resource's synthesized key. The vendor half is the
- * same for every resource that reads that vendor, and restating it per binding is how ten bindings
- * come to disagree about one API. The resource half cannot live on the provider, because a provider
- * has never heard of a local field name.
- *
- * So a reference carries the resource half and NAMES the vendor half. What it does not do is merge
- * the two concepts: an inline spec is still the right answer for a target no provider wraps.
- *
- * ## What a reference refuses
- *
- * The referenced operation must be a READ (`classification`) and must speak GET or POST. A read
- * surface that could reference a WRITE would let a LIST call delete rows, and the resource
- * repository's whole read-only stance (D3) would rest on nobody having authored it that way.
- */
-export const HttpApiRestOperationReferenceSchema = z.strictObject({
-    /** The `operationId` in the provider's own `rest.operations` catalogue. */
-    providerOperationId: z.string().min(1),
     /**
-     * The catalogue DOMAIN, so the provider's loader can answer one domain instead of every one.
-     * Absent, the whole catalogue is loaded — correct, and wasteful for a vendor with hundreds.
+     * Read through a query STATEMENT rather than through filter parameters (#1293).
+     *
+     * Mutually exclusive with `filterParams` and `searchParam` in practice rather than by schema: a
+     * statement expresses its own predicates, so a declaration carrying both has said the same thing
+     * twice in two grammars. The compiler refuses that pairing, where it can name which one it was
+     * about to ignore.
      */
-    domain: z.string().min(1).optional(),
+    statement: HttpApiQueryStatementSpecSchema.optional(),
     /**
-     * The referenced operation's PATH parameter that receives this resource's synthesized key.
-     * Required on `read` (a key-addressed read has a hole only the key fills) and meaningless on a
-     * collection member, where it is refused rather than ignored.
+     * Dot-path to a CONTINUATION URL in the response — Salesforce's `nextRecordsUrl` (#1293).
+     *
+     * Declared rather than sniffed, for the same reason `resultPath` is: response shapes vary per
+     * target and a wrong guess reads zero rows silently. Absent means the operation pages by
+     * `pagingParams` or not at all.
+     *
+     * A continuation is followed only on the target's OWN origin, exactly as the OData one is — the
+     * link comes from a remote response body and carries this deployment's credentials wherever it
+     * points.
      */
-    keyParameter: z.string().min(1).optional(),
+    cursorPath: z.string().min(1).optional(),
     /**
-     * Declared filter parameter name per LOCAL field — resource-shaped, exactly as on an inline
-     * spec, because the provider cannot know a local field name. Only fields listed here are
-     * translatable for this operation; everything else is refused at the adapter boundary.
+     * Headers this vendor requires on the request — NetSuite's `Prefer: transient` (#1293).
+     *
+     * VENDOR headers only. A credential never goes here: credentials come from the instance's access,
+     * and a header authored in a binding would be a second credential channel in a file that is
+     * committed. The compiler refuses an `authorization` key by name rather than trusting the author.
      */
-    filterParams: z.record(z.string().min(1), z.string().min(1)).optional(),
-    /** The parameter that receives the SEARCH text. Absent = search is refused for this binding. */
-    searchParam: z.string().min(1).optional(),
+    staticHeaders: z.record(z.string().min(1), z.string().min(1)).optional(),
 });
+/** @wildo_source:part:end saas.models.http-api-binding */
+/*
+ * ─── The catalogue REFERENCE form was REMOVED here (#1055 D10) ──────────────────────────────────
+ *
+ * A REST_JSON member could name an `operationId` in a PROVIDER's own `rest.operations` catalogue,
+ * so a resource's read surface reached into the connector lane for its shape. That is precisely the
+ * crossing D10 forbids: no runtime object, stored row, route, secret name, audit subject or
+ * specification serves both a system of record and a connector — and this one made a read depend on
+ * a provider's catalogue being loadable at request time.
+ *
+ * Nothing loses a capability. A REST_JSON binding declares its read members INLINE, typed against its
+ * vendor facet, which is what every authored binding does today: no REST_JSON system of record was
+ * ever declared against a catalogue, and the generic-REST simulator proof moves to a facet fixture.
+ *
+ * The convergence recorded above (#331) is what is being undone, and deliberately rather than by
+ * accident: stating the vendor half once per provider is a real saving for a CONNECTOR, and a
+ * category error for a system the application reads its OWN rows out of.
+ */
 /**
- * One read-surface member: the operation stated INLINE, or a REFERENCE into the provider's
- * catalogue.
- *
- * A plain union rather than a `kind`-discriminated one, deliberately: the two shapes are already
- * unambiguous (an inline spec has a required `method` and `pathTemplate`, a reference a required
- * `providerOperationId`, and neither satisfies the other), and adding a discriminator would have
- * meant editing every binding that exists today to say `kind: 'inline'` — churn on working
- * declarations to buy a slightly better parse error.
+ * One read-surface member. An INLINE spec, and now only that.
+ *
+ * Kept as a named alias rather than collapsed into {@link HttpApiRestOperationSpecSchema} at every
+ * use site: the members of a read surface are a concept in their own right, and a later form — a
+ * facet-declared operation shape — would arrive HERE rather than at each of its consumers.
  */
-export const HttpApiRestOperationDeclarationSchema = z.union([
-    HttpApiRestOperationSpecSchema,
-    HttpApiRestOperationReferenceSchema,
-]);
-/** Narrow a declared member to a catalogue reference. */
-export function isHttpApiRestOperationReference(declaration) {
-    return typeof declaration.providerOperationId === 'string';
-}
-/** The REST_JSON read-surface mapping: which lifecycle members exist remotely, and how. */
+export const HttpApiRestOperationDeclarationSchema = HttpApiRestOperationSpecSchema;
+/** The REST_JSON operation mapping: which read members and opened row writes exist remotely, and how each is sent. */
 export const HttpApiRestOperationsSchema = z.object({
     read: HttpApiRestOperationDeclarationSchema,
     list: HttpApiRestOperationDeclarationSchema,
@@ -400,23 +648,26 @@ export const HttpApiRestOperationsSchema = z.object({
     count: HttpApiRestOperationDeclarationSchema.optional(),
     /** Absent = SEARCH is refused for this binding. */
     search: HttpApiRestOperationDeclarationSchema.optional(),
+    /**
+     * The declared row WRITES (#1728) — see `http-api-rest-write-operations.shared.schemas.ts`. Each is present exactly
+     * when `writableVerbs` opens its verb; `assertHttpApiBindingDialectCoherence` refuses either without the other.
+     */
+    create: HttpApiRestWriteOperationSpecSchema.optional(),
+    update: HttpApiRestWriteOperationSpecSchema.optional(),
+    delete: HttpApiRestWriteOperationSpecSchema.optional(),
 });
+/**
+ * What each opened verb's REST_JSON write member must be (#1728). Total over {@link HttpApiWriteVerb}, so a verb added to
+ * the vocabulary is a compile error here until somebody decides how REST_JSON declares it. The member name IS the verb.
+ */
+const HTTP_API_REST_WRITE_MEMBER_RULES = {
+    [HttpApiWriteVerb.CREATE]: { methods: [HttpApiRestWriteMethod.POST], addressesOneRecord: false },
+    [HttpApiWriteVerb.UPDATE]: { methods: [HttpApiRestWriteMethod.PATCH, HttpApiRestWriteMethod.POST], addressesOneRecord: true },
+    [HttpApiWriteVerb.DELETE]: { methods: [HttpApiRestWriteMethod.DELETE, HttpApiRestWriteMethod.POST], addressesOneRecord: true },
+};
 // --------------------------------
 // Stance sub-declarations
 // --------------------------------
-/** Tenancy declaration — discriminated so each stance carries exactly its own obligations. */
-export const HttpApiTenancyDeclarationSchema = z.discriminatedUnion('stance', [
-    z.object({
-        stance: z.literal(HttpApiTenancyStance.SCOPE_FILTER_PUSHDOWN),
-        /** The remote field the engine's tenant-scope predicate is pushed down against. */
-        remoteScopeField: z.string().min(1),
-    }),
-    z.object({
-        stance: z.literal(HttpApiTenancyStance.SINGLE_TENANT_BINDING),
-        /** Why this binding is single-tenant — recorded, audited justification (R16). */
-        justification: z.string().min(1),
-    }),
-]);
 /**
  * HTTP methods a declared EXPLICIT erasure operation (stance 6b, REST_JSON) may use.
  *
@@ -493,70 +744,172 @@ export const HttpApiErasureDeclarationSchema = z.discriminatedUnion('stance', [
 // --------------------------------
 // The binding declaration
 // --------------------------------
+/** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */
+/**
+ * The fields EVERY binding carries, whatever its dialect — spread into each arm of the union below.
+ */
 const httpApiResourceBindingBaseShape = {
     /**
-     * The external provider whose declared protocol configuration carries the base URL and whose
-     * credentials resolve through `ExternalProvidersRegistryBackendService` (decision D7 — no new
-     * secret store, no connection string on the resource config).
+     * The SYSTEM OF RECORD this resource lives in, by the NAME the application declared it under in
+     * `wildo.saas.config.ts` (`systemsOfRecord.<name>`, #1055).
+     *
+     * ## Why a name, and not a provider ref
+     *
+     * `providerRef` named a PROVIDER, and a provider's env-var names live in its module — so one ref
+     * was one deployment, and a second Odoo was unrepresentable. A name here is an INSTANCE: two
+     * (`odoo-fr`, `odoo-de`) share one vendor facet and differ only in the environment variables their
+     * names derive. It is also not a provider in any other sense (D10): nothing here is selected
+     * through the capability plane, carries a person's lent credential, or has an operation catalogue.
+     *
+     * ## What validates it, and where
+     *
+     * Not here, and not in the resource factory — the factory runs in the application's `shared-lib`,
+     * where the saas configuration is not in scope. The factory checks SHAPE; the boot registry checks
+     * that this name is DECLARED and that `dialect` below equals the instance's, at the first moment
+     * both are visible. That split is the honest one rather than a compromise.
      */
-    providerRef: z.string().min(1),
+    system: z.string().min(1),
     /**
      * The remote entity addressed by this binding — an OData entity-set name, or a logical name for
      * a REST_JSON surface. One binding, one remote entity set.
      */
     entityRef: z.string().min(1),
-    /**
-     * WHOSE ACCOUNT this binding spends, and ON WHOSE BEHALF — the two axes a provider also declares
-     * as `admissibleConnections`, so a binding and the provider it targets are compared in one
-     * vocabulary instead of through an adapter.
+    /*
+     * `connection` was here, and it is GONE (#1055 D12).
      *
-     * A SHAPE, not a target: the binding says `ORGANIZATION × USER`, and WHICH organization and
-     * WHICH member are supplied per call from the execution that triggered the read. A binding that
-     * named an instance would be a binding per tenant.
+     * It declared WHOSE ACCOUNT a binding spends — `ORGANIZATION × USER` and its siblings — which is a
+     * real question for a CONNECTOR, where a customer connects their own account. A system of record is
+     * not that: it is a deployment the application reads its own business rows out of, with its own
+     * service identity, and the only honest answer was always `APPLICATION × SERVICE`. A field with one
+     * legal value is a question nobody should be asked.
      *
-     * Defaults to the application acting as itself, which is what every binding authored before this
-     * field existed meant.
+     * The customer-connection case is case 2 of #1049 and keeps the connector resolver, untouched.
      */
-    connection: ExternalProvider_ConnectionShapeSchema.default({
-        ownerScope: ExternalProvider_Connection_OwnerScope.APPLICATION,
-        delegation: ExternalProvider_Connection_DelegationMode.SERVICE,
-    }),
     /** Ordered key declaration — the source of the synthesized engine-facing `_id` (paper A). */
     keyFields: z.array(HttpApiKeyFieldSchema).min(1),
     /** Non-key field name mappings; unlisted fields map by identity. */
     fieldMappings: z.array(HttpApiFieldMappingSchema).default([]),
-    /** Tenancy stance (R4/R16). */
-    tenancy: HttpApiTenancyDeclarationSchema,
+    /*
+     * `tenancy` was here, and it is GONE (#1055 §5).
+     *
+     * Both of its stances were wrong for a system of record. `SCOPE_FILTER_PUSHDOWN` sent WILDO's own
+     * organization id to the remote as a filter value — an id the remote has never heard of — and
+     * `SINGLE_TENANT_BINDING` became the only truth, which makes it a declaration with one legal answer.
+     *
+     * What replaced it is not a smaller field but a different mechanism: the row projector STAMPS the
+     * owner organization's id onto every remote row, so the per-row tenant gate passes with no exemption
+     * and a read under another organization's URL is refused by the gate that already existed.
+     * Partitioning a system of record BY organization unit returns in #1058, as a property of the
+     * INSTANCE and its vendor facet rather than of each binding.
+     */
     /** Erasure stance (D6) — required; no silent default. */
     erasure: HttpApiErasureDeclarationSchema,
+    /**
+     * The processing PURPOSES this data flow serves (#1745) — each a `purposeRef` of
+     * `operatorComplianceIdentity.lawfulBases` in `wildo.saas.config.ts`. Absent = none linked.
+     *
+     * A system of record is where an application OBTAINS personal data it did not collect from the person, and a
+     * privacy notice then owes the purpose and the legal basis for it (GDPR Art. 14(1)(c)) beside the source (Art.
+     * 14(2)(f)). The source and the categories are derived from this binding; the purpose is the one thing the
+     * framework cannot infer from what the data is, so it is LINKED here, per binding, rather than typed into a
+     * notice. The same link a provider's compliance choice carries (#1709), for the same reason.
+     *
+     * Checked where both halves are visible — the document facts and the evidence collector — and a ref naming no
+     * declared purpose is REPORTED there as a broken link, never refused: the factory runs in `shared-lib`, where the
+     * lawful bases are not in scope, and a compliance link must never stop the application from starting.
+     */
+    purposeRefs: z.array(z.string().trim().min(1)).optional(),
+    /**
+     * The row-level writes this binding OPENS toward its system of record (#1679). Absent = none: the
+     * binding is read-only, which is what every binding authored before #1679 declared implicitly.
+     *
+     * Opening a verb is not enough to write. The resource must also declare the matching operation
+     * (the factory refuses either without the other), the dialect must implement writes (the boot
+     * registration refuses a verb its dialect cannot send, naming the dialect), and every write
+     * variant carries a REQUIRED `Idempotency-Key`, because a remote write cannot be rolled back and
+     * a retried request must replay its first outcome rather than write twice.
+     */
+    writableVerbs: z.array(z.enum(HttpApiWriteVerb)).default([]),
+    /**
+     * How an opened UPDATE is protected against overwriting a change made since its author read the row (#1724). See
+     * {@link HttpApiWriteConcurrencyMode} for the two answers and the limit of the first.
+     *
+     * REQUIRED when the binding opens UPDATE — on ODOO_JSONRPC (#1724), ODATA (#1726) and REST_JSON (#1728) alike — and
+     * refused when the binding opens no UPDATE — a concurrency stance on a door that is shut decides nothing. `versionField` names the LOCAL field that
+     * carries the version: it must map onto the vendor facet's `rowVersionField` (checked at boot, where the facet is
+     * visible) — Odoo `write_date`, an OData service's `@odata.etag` — and the resource's schema must let an UPDATE carry
+     * it and keep a CREATE from sending it (checked by the resource factory).
+     */
+    writeConcurrency: z.discriminatedUnion('mode', [
+        z.strictObject({
+            mode: z.literal(HttpApiWriteConcurrencyMode.VERSION_CHECKED),
+            /** The LOCAL field carrying the row version the caller read — never written to the remote. */
+            versionField: z.string().min(1),
+        }),
+        z.strictObject({ mode: z.literal(HttpApiWriteConcurrencyMode.LAST_WRITER_WINS) }),
+    ]).optional(),
+    /**
+     * The vendor ACTIONS this binding declares toward its system of record (#1678) — named operations that are not row
+     * writes: posting an invoice, confirming an order, an OData bound or unbound action. Absent = none.
+     *
+     * Declared here rather than on the instance for the reasons `system-of-record-actions.shared.schemas.ts` records: an
+     * action carries a Zod input schema and the roles admitted to it, both of which live in `shared-lib` beside this
+     * binding. An action runs only through the system-of-record action executor, under the instance's service identity,
+     * confined to the owner organization and to the caller's partition, and audited on every outcome. It is reached over
+     * HTTP only through a custom operation of this resource whose implementation calls the executor.
+     */
+    actions: SystemOfRecordActionDeclarationsSchema.optional(),
     /** Remote-call semantics (D10/R15). */
     remoteCallSemantics: HttpApiRemoteCallSemanticsSchema.default({
         timeoutMs: 10_000,
         retry: { maxAttempts: 2, backoffMs: 500 },
         maxIdSetSize: 50,
+        maxPartitionSetSize: 200,
     }),
 };
+/** @wildo_source:part:end saas.models.http-api-binding */
 /**
  * The HTTP_API resource binding — discriminated on the transport dialect so each dialect carries
- * exactly its own obligations: ODATA is generic (plus an optional `$metadata` probe opt-out for
- * targets that do not serve one); REST_JSON must declare its whole read surface.
+ * exactly its own obligations: ODATA and ODOO_JSONRPC are generic (the model name IS `entityRef`, and
+ * read/list/count map mechanically); REST_JSON must declare its whole read surface INLINE.
+ *
+ * Every arm carries `system` — the declared instance this resource lives in — and none carries a
+ * provider, a connection shape or a tenancy stance. See the base shape above for what each of those
+ * was and why none was replaced by a smaller field (#1055).
  */
 /** @wildo_source:part:start saas.models.http-api-binding facet:layer:shared facet:audience:app-developer */
 export const HttpApiResourceBindingSchema = z.discriminatedUnion('dialect', [
     z.object({
         dialect: z.literal(HttpApiTransportDialect.ODATA),
         ...httpApiResourceBindingBaseShape,
-        /**
-         * Verify the committed declaration against the live `$metadata` at boot (decision D5 —
-         * drift is detected at boot and the fix is re-authoring, never silent adaptation). Opt out
-         * only for targets that genuinely do not serve `$metadata`.
+        /*
+         * `verifyMetadataAtBoot` was here, and it is GONE (#1055 §5).
+         *
+         * It had ZERO non-test readers — measured, not assumed — so nothing ever probed `$metadata` at
+         * boot whatever it was set to. It also asked for exactly what the registry above it must never
+         * do: dial the remote during startup, where an ERP outage would stop an application booting
+         * (`continuity-drift-and-cas-basis.md` Rule 3).
+         *
+         * The drift probe it promised EXISTS, on the extraction source, reached through the operator door
+         * (`external-data-extraction-source.backend.ts`) — where a human is present and a refusal is
+         * something somebody can act on.
          */
-        verifyMetadataAtBoot: z.boolean().default(true),
+    }),
+    z.object({
+        /*
+         * OData v2 (#1687) — generic like ODATA: the entity set IS `entityRef`, and read/list/count map mechanically. Its
+         * own arm rather than a flag on ODATA because the compiler, the envelope and the value encoding all differ.
+         */
+        dialect: z.literal(HttpApiTransportDialect.ODATA_V2),
+        ...httpApiResourceBindingBaseShape,
     }),
     z.object({
         dialect: z.literal(HttpApiTransportDialect.REST_JSON),
         ...httpApiResourceBindingBaseShape,
-        /** The declared read surface — absent members are refused, never emulated. */
+        /**
+         * The declared read surface, and the declared request of each row write the binding opens (#1728) — absent members
+         * are refused, never emulated.
+         */
         operations: HttpApiRestOperationsSchema,
     }),
     z.object({
@@ -569,6 +922,76 @@ export const HttpApiResourceBindingSchema = z.discriminatedUnion('dialect', [
         // in effects, which discriminated unions do not admit.
     }),
 ]);
+/**
+ * A declared statement keyset must be one the engine can walk (#1686). Every refusal names the fix.
+ *
+ * Checked on the BINDING rather than only on a pipeline, so a keyset declared on a read-through
+ * resource is refused the same way: a declaration that says something false is refused wherever it
+ * is written, not only where it is used.
+ */
+function assertRestJsonKeysetCoherence(keyFields, operations) {
+    for (const [member, declaration] of Object.entries(operations)) {
+        /*
+         * A statement on `read` is never sent (#1972 review): a key-addressed read is a path with `{key}` — Salesforce's
+         * `/sobjects/Account/{key}` — and `compileRestJsonKeyAddressedRead` reads no statement. Declared there it would
+         * look like it shapes the read and shape nothing, and it would admit a `temporalKind` that nothing reads.
+         */
+        if (member === 'read' && declaration?.statement !== undefined) {
+            throw new Error('operations.read.statement: a key-addressed read is its `pathTemplate` with `{key}`, and sends no statement — declare the '
+                + 'statement on `list` (or `search` / `count`), where collection reads are built.');
+        }
+        /*
+         * SuiteQL is NetSuite's, and NetSuite reads a SuiteQL POST's paging from the URL (#1686). Placed by method, the
+         * `limit` lands in the body, the vendor applies its own default, and the page is not bounded — a read-through LIST
+         * then serves whole results, and a keyset page is refused at every run. Refused here, where the declaration is.
+         * spec-cite: Oracle NetSuite, "Executing SuiteQL Queries Through REST Web Services" (section_157909186990) — the
+         * statement is POSTed as `{"q": …}` and paged by `?limit=10&offset=10` on the request URL.
+         */
+        if (declaration?.statement?.language === HttpApiQueryStatementLanguage.SUITEQL
+            && declaration.method === HttpApiRestOperationMethod.POST
+            && declaration.pagingParams !== undefined
+            && declaration.pagingParams.placement !== HttpApiRestParameterPlacement.QUERY_STRING) {
+            throw new Error(`operations.${member}.pagingParams: a SuiteQL read POSTs its statement in the body and is paged in the URL — declare `
+                + `\`placement: '${HttpApiRestParameterPlacement.QUERY_STRING}'\`, or the limit lands in the body and bounds nothing.`);
+        }
+        const keyset = declaration?.statement?.keyset;
+        if (declaration === undefined || keyset === undefined)
+            continue;
+        if (member !== 'list') {
+            throw new Error(`operations.${member}.statement.keyset: a keyset is what a pipeline walks a COLLECTION by, so it is declared on the 'list' member only.`);
+        }
+        if (keyFields.length !== 1) {
+            throw new Error(`operations.list.statement.keyset: this binding declares ${keyFields.length} key components, and a keyset needs ONE unique column — `
+                + 'one component of a composite key is not unique, and a walk on it skips the rows that share its boundary value.');
+        }
+        const keyField = keyFields[0];
+        if (keyset.keyRemoteField !== keyField.remoteField) {
+            throw new Error(`operations.list.statement.keyset.keyRemoteField: '${keyset.keyRemoteField}' is not this binding's key field ('${keyField.remoteField}'). `
+                + 'A keyset walks the row identity, which is the key field: unique and immutable, so no row can move behind the cursor.');
+        }
+        if (!HTTP_API_KEYSET_ELIGIBLE_CODECS.includes(keyField.codec)) {
+            throw new Error(`operations.list.statement.keyset: the key field '${keyField.remoteField}' has the ${keyField.codec} codec, and a keyset walks `
+                + `${HTTP_API_KEYSET_ELIGIBLE_CODECS.join(' or ')} keys only — the engine checks each page against the key's order, and that `
+                + 'order must be one it can state.');
+        }
+        const bound = HTTP_API_KEYSET_PAGE_BOUND[declaration.statement.language];
+        switch (bound) {
+            case HttpApiKeysetPageBound.STATEMENT_LIMIT_CLAUSE:
+                if (declaration.cursorPath === undefined) {
+                    throw new Error(`operations.list: a ${declaration.statement.language.toUpperCase()} keyset bounds its page with LIMIT, and the vendor may still `
+                        + 'answer the limited result in several batches. Declare the continuation (`cursorPath`, e.g. \'nextRecordsUrl\') so a page is '
+                        + 'read to its end — a batch shorter than the limit would otherwise end the pass with rows unread.');
+                }
+                break;
+            case HttpApiKeysetPageBound.LIMIT_PARAMETER:
+                if (declaration.pagingParams === undefined) {
+                    throw new Error(`operations.list: a ${declaration.statement.language.toUpperCase()} keyset bounds its page with the operation's limit parameter — `
+                        + 'declare `pagingParams` (limitParam / offsetParam; the offset is always sent as 0).');
+                }
+                break;
+        }
+    }
+}
 /**
  * Dialect-specific structural constraints that a discriminated union cannot express member-side.
  * Called by the resource-configuration factory AFTER the schema parse; throws with the offending
@@ -583,21 +1006,103 @@ export function assertHttpApiBindingDialectCoherence(binding) {
             throw new Error("keyFields: an ODOO_JSONRPC binding must declare exactly one key field with the INTEGER codec — Odoo row ids are integers ('id').");
         }
     }
-    // A read member must be ONE form or the other. The union parses an object carrying both as an
-    // INLINE spec (the first branch that matches wins) and drops the reference without a word — an
-    // author who wrote `providerOperationId` beside a `method` believes it does something, so the
-    // ambiguity is refused at authoring rather than resolved by branch order at parse time.
+    /*
+     * A member naming a PROVIDER's catalogue operation is refused, and refused EXPLICITLY (#1055 D10).
+     *
+     * The schema alone would refuse it as an unknown key, with a message about `providerOperationId`
+     * not being expected — true, and useless to an author who reasonably believes the form still
+     * exists, because it did until this slice. So the refusal names what happened and where the shape
+     * went instead of letting the parse error carry it.
+     *
+     * This replaces an ambiguity check that existed for the opposite reason: while BOTH forms were
+     * legal, a member carrying both parsed as the inline one and dropped the reference silently.
+     */
     if (binding.dialect === HttpApiTransportDialect.REST_JSON) {
         for (const [member, declaration] of Object.entries(binding.operations)) {
             if (declaration === undefined)
                 continue;
-            const asAny = declaration;
-            if (asAny.providerOperationId !== undefined && asAny.method !== undefined) {
-                throw new Error(`operations.${member}: a read member is either stated INLINE (method + pathTemplate) or a REFERENCE `
-                    + '(providerOperationId) into the provider\'s operation catalogue — never both.');
+            if (declaration.providerOperationId !== undefined) {
+                throw new Error(`operations.${member}: a read member can no longer REFERENCE a provider's operation catalogue `
+                    + '(`providerOperationId`). A system of record is not a connector, so its read surface is declared '
+                    + 'INLINE here (method + pathTemplate) against the vendor facet.');
             }
         }
+        assertRestJsonKeysetCoherence(binding.keyFields, binding.operations);
+    }
+    // #1972 — a temporal kind is read by the REST_JSON statement compilers only; anywhere no statement is built it would
+    // decide nothing — a setting that looks like it controls date spelling and controls nothing.
+    const declaredTemporal = binding.fieldMappings.find((mapping) => mapping.temporalKind !== undefined);
+    if (declaredTemporal !== undefined) {
+        const readsThroughStatement = binding.dialect === HttpApiTransportDialect.REST_JSON
+            && Object.values(binding.operations).some((member) => member?.statement !== undefined);
+        if (!readsThroughStatement) {
+            throw new Error(`fieldMappings('${declaredTemporal.localField}').temporalKind: declared on a ${binding.dialect} binding that reads through no query `
+                + 'statement — it tells a SOQL or SuiteQL statement how to spell a date, and nothing here builds one, so it would change nothing. Remove it.');
+        }
+    }
+    // #1679 — each opened verb once. A duplicate is not harmful by itself, but it is a declaration that
+    // says the same thing twice, which is the shape that drifts when one copy is edited.
+    if (new Set(binding.writableVerbs).size !== binding.writableVerbs.length) {
+        throw new Error(`writableVerbs: each verb may be opened once — got [${binding.writableVerbs.join(', ')}].`);
     }
+    // #1724 — the concurrency stance of an opened UPDATE. A stance with no UPDATE decides nothing; an Odoo UPDATE with no
+    // stance would be last-writer-wins by an omission nobody reviewed, because Odoo's `write` takes no precondition.
+    const opensUpdate = binding.writableVerbs.includes(HttpApiWriteVerb.UPDATE);
+    if (binding.writeConcurrency !== undefined && !opensUpdate) {
+        throw new Error('writeConcurrency: declared on a binding that opens no UPDATE — it governs updates only. Remove it, or open the update.');
+    }
+    if (opensUpdate && binding.writeConcurrency === undefined && binding.dialect === HttpApiTransportDialect.ODOO_JSONRPC) {
+        throw new Error(`writeConcurrency: this binding opens UPDATE toward '${binding.system}', and Odoo's external API has no conditional write — `
+            + '`write(ids, vals)` applies the values whatever changed since they were read. State the stance: '
+            + `{ mode: '${HttpApiWriteConcurrencyMode.VERSION_CHECKED}', versionField: '<local field mapped to write_date>' } to refuse `
+            + `a stale version before sending (best-effort: it narrows the race, it does not close it), or { mode: '${HttpApiWriteConcurrencyMode.LAST_WRITER_WINS}' }.`);
+    }
+    // #1728 — a REST_JSON write is sent exactly as the binding declares it, so each opened verb needs its member and a
+    // member of a verb that is not opened is a declaration nothing sends. Both are refused, naming the member.
+    if (binding.dialect === HttpApiTransportDialect.REST_JSON) {
+        for (const verb of Object.values(HttpApiWriteVerb)) {
+            const member = binding.operations[verb];
+            const opened = binding.writableVerbs.includes(verb);
+            if (opened && member === undefined) {
+                throw new Error(`operations.${verb}: this binding opens ${verb.toUpperCase()} toward '${binding.system}', and a REST_JSON write is sent `
+                    + `exactly as declared — declare operations.${verb} (method + pathTemplate${verb === HttpApiWriteVerb.CREATE ? ' + createdKey' : ''}).`);
+            }
+            if (!opened && member !== undefined) {
+                throw new Error(`operations.${verb}: declared on a binding that does not open ${verb.toUpperCase()} — nothing would ever send it. `
+                    + `Open it in writableVerbs, or remove the member.`);
+            }
+            if (member !== undefined) {
+                assertHttpApiRestWriteOperationShape(member, {
+                    member: verb,
+                    ...HTTP_API_REST_WRITE_MEMBER_RULES[verb],
+                    keyRemoteFields: binding.keyFields.map((keyField) => keyField.remoteField),
+                });
+            }
+        }
+        // Neither REST_JSON vendor's record API is written with a precondition, so an update's stance must be stated, as on Odoo.
+        if (opensUpdate && binding.writeConcurrency === undefined) {
+            throw new Error(`writeConcurrency: this binding opens UPDATE toward '${binding.system}' over REST_JSON, which the engine writes with no `
+                + `precondition. State the stance: { mode: '${HttpApiWriteConcurrencyMode.LAST_WRITER_WINS}' }, or `
+                + `{ mode: '${HttpApiWriteConcurrencyMode.VERSION_CHECKED}', versionField: '<local field mapped to the row version>' } — `
+                + 'best-effort, and available only when the vendor facet declares its row version field.');
+        }
+    }
+    // #1726 — an OData UPDATE is conditional only on a version the caller supplies; without a stance it would be
+    // last-writer-wins by an omission nobody reviewed, exactly as for Odoo.
+    if (opensUpdate && binding.writeConcurrency === undefined && binding.dialect === HttpApiTransportDialect.ODATA) {
+        throw new Error(`writeConcurrency: this binding opens UPDATE toward '${binding.system}' over OData. State the stance: `
+            + `{ mode: '${HttpApiWriteConcurrencyMode.VERSION_CHECKED}', versionField: '<local field mapped to @odata.etag>' } to send the `
+            + 'entity tag the caller read as If-Match, so the service itself refuses a stale update (412) — available only when the '
+            + `vendor facet declares its entity tag as rowVersionField — or { mode: '${HttpApiWriteConcurrencyMode.LAST_WRITER_WINS}' }.`);
+    }
+    if (binding.writeConcurrency?.mode === HttpApiWriteConcurrencyMode.VERSION_CHECKED) {
+        const versionField = binding.writeConcurrency.versionField;
+        if (binding.keyFields.some((keyField) => keyField.localField === versionField)) {
+            throw new Error(`writeConcurrency.versionField: '${versionField}' is a key field — a row's version is not its address.`);
+        }
+    }
+    // #1678 — every declared action must be one this binding's dialect can call, on the target it names.
+    assertSystemOfRecordActionDeclarationsCoherence({ dialect: binding.dialect, actions: binding.actions });
     // D6 stance 6b — the declared erasure operation's FORM is dialect-specific. The union schema
     // admits both forms; only the pairing below is executable, so an incoherent pairing must refuse
     // at authoring rather than on the first subject-erasure request:
@@ -607,6 +1112,15 @@ export function assertHttpApiBindingDialectCoherence(binding) {
     //   - REST_JSON    → an explicit operation spec only (there IS no canonical delete to rely on —
     //                    the binding declares the exact call, like every other REST_JSON operation).
     if (binding.erasure.stance === HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION) {
+        /*
+         * #1687 — an OData v2 binding reads only. The explicit-erasure stance is a remote DELETE, which on SAP Gateway needs
+         * the CSRF-token handshake the engine does not perform, and v2's write shapes are the write path's (#1679). Refused
+         * here rather than at the first erasure request, where a subject's Art. 17 answer would be the one to fail.
+         */
+        if (binding.dialect === HttpApiTransportDialect.ODATA_V2) {
+            throw new Error('erasure: an ODATA_V2 binding reads only, and the explicit-erasure stance is a remote DELETE the engine does not send on v2 '
+                + '(SAP Gateway requires a CSRF-token handshake). Declare NO_SUBJECT_DATA or CONTROLLER_ACKNOWLEDGED_NON_ERASURE, or bind a v4 service.');
+        }
         const usesCanonicalDelete = 'useCanonicalDelete' in binding.erasure.operation;
         if (binding.dialect === HttpApiTransportDialect.REST_JSON && usesCanonicalDelete) {
             throw new Error('erasure.operation: a REST_JSON binding has no canonical delete — declare the explicit erasure operation spec (method/path), like its other declared operations.');