@wildo-ai/saas-models 1.1.5 → 1.1.7

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

@@ -33,6 +33,9 @@
  */
 import { z } from 'zod';
 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
 // --------------------------------
@@ -65,34 +68,12 @@ import { HttpApiTransportDialect } from './http-api-transport-dialect.shared.js'
 // --------------------------------
 // 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 = {}));
 /*
  * ─── `HttpApiTenancyStance` was REMOVED here (#1055), and NOT replaced by a narrower vocabulary ──
  *
@@ -141,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 —
@@ -159,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)
@@ -179,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({
@@ -225,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,
@@ -297,6 +408,100 @@ export var HttpApiQueryStatementLanguage;
      */
     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).
  *
@@ -314,7 +519,9 @@ export const HttpApiQueryStatementSpecSchema = z.object({
      * 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.
+     * 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),
     /**
@@ -322,6 +529,12 @@ export const HttpApiQueryStatementSpecSchema = z.object({
      * 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. */
@@ -336,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(),
     /**
@@ -392,6 +614,7 @@ export const HttpApiRestOperationSpecSchema = z.object({
      */
     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) ──────────────────────────────────
  *
@@ -417,7 +640,7 @@ export const HttpApiRestOperationSpecSchema = z.object({
  * facet-declared operation shape — would arrive HERE rather than at each of its consumers.
  */
 export const HttpApiRestOperationDeclarationSchema = HttpApiRestOperationSpecSchema;
-/** The REST_JSON read-surface mapping: which lifecycle members exist remotely, and how. */
+/** 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,
@@ -425,7 +648,23 @@ 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
 // --------------------------------
@@ -505,6 +744,10 @@ 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 SYSTEM OF RECORD this resource lives in, by the NAME the application declared it under in
@@ -561,6 +804,61 @@ const httpApiResourceBindingBaseShape = {
      */
     /** 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,
@@ -569,6 +867,7 @@ const httpApiResourceBindingBaseShape = {
         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 and ODOO_JSONRPC are generic (the model name IS `entityRef`, and
@@ -596,10 +895,21 @@ export const HttpApiResourceBindingSchema = z.discriminatedUnion('dialect', [
          * something somebody can act on.
          */
     }),
+    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({
@@ -612,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
@@ -647,7 +1027,82 @@ export function assertHttpApiBindingDialectCoherence(binding) {
                     + '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:
@@ -657,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.');