@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/external-data/external-data-pipeline.shared.schemas.d.ts

@@ -0,0 +1,347 @@
+/**
+ * The ETL PIPELINE declaration (`externalDataPipeline`) — partial-resource coverage, model v3
+ * (`.claude/plans/etl-partial-resource-coverage.md`, PR-3/PR-19; decisions D-P1…D-P10).
+ *
+ * "Some resources local, some remote, ETL between them": an ordinary LOCAL resource may declare
+ * ONE inbound pipeline from a remote HTTP-API entity. The declaration reuses the whole
+ * {@link HttpApiResourceBindingSchema} as its source half (provider, entity, dialect, key
+ * fields, remote-call semantics — the E is the same adapter plumbing the VIRTUAL mode runs on),
+ * adds the T (a declared field mapping) and the L/refresh contract (population posture, orphan
+ * policy, schedule, run bounds). The destination stays a FULL local resource — files, RAG,
+ * retention/erasure, charts and the read-only UI chain are all inherited, never re-built.
+ *
+ * Everything here is a CLOSED vocabulary with one named source; the runtime seams (P-2) consume
+ * these members, and the paper's ledger rows (PR-…) are cited per surface.
+ */
+import { z } from 'zod';
+import { HttpApiTenancyStance, HttpApiTransportDialect } from '../http-api-binding/http-api-binding.shared.schemas';
+/**
+ * Pipeline direction (PR-19). A SINGLE-member enum on purpose: reverse ETL (local→remote) and
+ * bidirectional sync belong to the outbound-writes gate (ETL plan Step 5, concurrency contract),
+ * but the DECLARATION is direction-extensible NOW so those arrive as new members instead of a
+ * schema reshape — the immutability-needs-a-paired-path lesson applied to a vocabulary.
+ */
+/** @wildo_source:part:start saas.models.external-data-pipeline facet:layer:shared facet:audience:app-developer */
+export declare enum ExternalDataPipelineDirection {
+    INBOUND = "inbound"
+}
+/**
+ * Who owns the destination's row population (D-P8, v3.1 §1).
+ *
+ * The declared answer to the question the orphan sweep MUST have: "is a row the pipeline did not
+ * create a USER row, or a VANISHED remote row?" — undeclared mixed populations are how an orphan
+ * pass deletes user data.
+ */
+export declare enum ExternalDataDestinationPopulation {
+    /**
+     * Every row comes from the pipeline. Caller CREATE is refused at declaration time, and orphan
+     * detection may consider the whole population. The default: safest, and the honest description
+     * of a synced master-data table.
+     */
+    CLOSED = "closed",
+    /**
+     * Mixed rows: users may create rows the pipeline does not own. Pipeline rows are identified by
+     * the remote-key field being present, and orphan detection is CONFINED to that population. A
+     * user row that later matches an incoming remote key is ADOPTED by the upsert (documented
+     * collision semantics, not an accident).
+     */
+    OPEN = "open"
+}
+/**
+ * What happens to a destination row whose remote counterpart disappeared (D-P9).
+ *
+ * MIRRORS `DataSeedSyncOrphanPolicy` (saas-backend-lib, data-seeding) member-for-member, and the
+ * P-2 pipeline→SYNC seam maps the two 1:1. A separate enum EXISTS ONLY because of dependency
+ * direction: this declaration lives in saas-models, the data-seeding models live in
+ * saas-backend-lib, and models cannot import backend. If the data-seeding vocabulary ever moves
+ * down to saas-models, collapse this enum into it — do not let the two drift meanwhile (the
+ * seam's mapping is exhaustive and compile-forced, so a new member on either side reddens P-2).
+ */
+export declare enum ExternalDataOrphanPolicy {
+    /** Hard-delete the orphan row — flows through ordinary lifecycle (cascades, file teardown). Opt-in. */
+    DELETE = "delete",
+    /** Mark the row deprecated and keep it; a re-appearing remote key REVIVES it (v3.1 §4). Opt-in. */
+    DEPRECATE = "deprecate",
+    /** Touch nothing; surface the diff in the run ledger. The DEFAULT — least surprise. */
+    REPORT = "report"
+}
+/** The two shapes a mapping entry can take — a closed discriminator, never inferred from keys. */
+export declare enum ExternalDataMappingEntryKind {
+    /** Copy (and coerce) one remote field into one local field. */
+    REMOTE_FIELD = "remote-field",
+    /** Fill one local field with a declared constant (destination-required fields with no remote source). */
+    CONSTANT = "constant"
+}
+/**
+ * Built-in, closed coercion vocabulary for REMOTE_FIELD entries (v3.1 §3 / PR-8). Slice 1 ships
+ * exactly the coercions the two generic dialects force; arbitrary transforms are the recorded
+ * widenings (W-FK resolution, W-AGENT authored transforms) — never an open function slot here.
+ */
+export declare enum ExternalDataFieldCoercion {
+    /** Value lands as extracted (after the destination schema's own Zod parse). */
+    NONE = "none",
+    /**
+     * Odoo spells an ABSENT value as boolean `false` — a mapped string field would otherwise store
+     * literal `false`. Applied by DEFAULT for ODOO_JSONRPC sources; declaring it on another dialect
+     * is refused (the name is Odoo's semantics, not a generic null-coalesce).
+     */
+    ODOO_FALSE_AS_NULL = "odoo-false-as-null",
+    /** Parse a strict-ISO datetime string into a Date for a date-typed local field. */
+    ISO_STRING_TO_DATE = "iso-string-to-date"
+}
+/** One declared T-step: remote field → local field with a built-in coercion, or a constant. */
+export declare const ExternalDataFieldMappingEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<ExternalDataMappingEntryKind.REMOTE_FIELD>;
+    remoteField: z.ZodString;
+    localField: z.ZodString;
+    coercion: z.ZodDefault<z.ZodEnum<typeof ExternalDataFieldCoercion>>;
+    required: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ExternalDataMappingEntryKind.CONSTANT>;
+    localField: z.ZodString;
+    constant: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strip>], "kind">;
+/** @wildo_source:part:end saas.models.external-data-pipeline */
+export type ExternalDataFieldMappingEntry = z.infer<typeof ExternalDataFieldMappingEntrySchema>;
+/**
+ * The inbound pipeline declaration an ordinary LOCAL resource carries as `externalDataPipeline`.
+ *
+ * NOT legal on an HTTP_API-adapter resource (a virtual resource IS the remote side); the
+ * resource-configuration factory enforces that plus every mainSchema-dependent coherence rule —
+ * see `validateExternalDataPipelineDeclarationAgainstSchema` there. This module owns only the
+ * schema-independent shape and coherence.
+ */
+/** @wildo_source:part:start saas.models.external-data-pipeline facet:layer:shared facet:audience:app-developer */
+export declare const ExternalDataPipelineDeclarationSchema: z.ZodObject<{
+    direction: z.ZodDefault<z.ZodEnum<typeof ExternalDataPipelineDirection>>;
+    binding: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        verifyMetadataAtBoot: z.ZodDefault<z.ZodBoolean>;
+        providerRef: z.ZodString;
+        entityRef: z.ZodString;
+        identityMode: z.ZodDefault<z.ZodEnum<typeof import("../external-data.exports").HttpApiIdentityMode>>;
+        keyFields: z.ZodArray<z.ZodObject<{
+            localField: z.ZodString;
+            remoteField: z.ZodString;
+            codec: z.ZodEnum<typeof import("../external-data.exports").HttpApiKeyComponentCodec>;
+        }, z.core.$strip>>;
+        fieldMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            localField: z.ZodString;
+            remoteField: z.ZodString;
+        }, z.core.$strip>>>;
+        tenancy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            stance: z.ZodLiteral<HttpApiTenancyStance.SCOPE_FILTER_PUSHDOWN>;
+            remoteScopeField: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<HttpApiTenancyStance.SINGLE_TENANT_BINDING>;
+            justification: z.ZodString;
+        }, z.core.$strip>], "stance">;
+        erasure: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.NO_SUBJECT_DATA>;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION>;
+            operation: z.ZodUnion<readonly [z.ZodObject<{
+                useCanonicalDelete: z.ZodLiteral<true>;
+            }, z.core.$strip>, z.ZodObject<{
+                method: z.ZodEnum<typeof import("../external-data.exports").HttpApiErasureOperationMethod>;
+                pathTemplate: z.ZodString;
+                jsonRpcEnvelope: z.ZodOptional<z.ZodObject<{
+                    rpcMethod: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>;
+            subjectLinkLocalField: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.CONTROLLER_ACKNOWLEDGED_NON_ERASURE>;
+            subjectLinkLocalField: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "stance">;
+        remoteCallSemantics: z.ZodDefault<z.ZodObject<{
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+            retry: z.ZodDefault<z.ZodObject<{
+                maxAttempts: z.ZodDefault<z.ZodNumber>;
+                backoffMs: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+            maxRequestsPerMinute: z.ZodOptional<z.ZodNumber>;
+            maxIdSetSize: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        dialect: z.ZodLiteral<HttpApiTransportDialect.ODATA>;
+    }, z.core.$strip>, z.ZodObject<{
+        operations: z.ZodObject<{
+            read: z.ZodObject<{
+                method: z.ZodEnum<typeof import("../external-data.exports").HttpApiRestOperationMethod>;
+                pathTemplate: z.ZodString;
+                pagingParams: z.ZodOptional<z.ZodObject<{
+                    limitParam: z.ZodString;
+                    offsetParam: z.ZodString;
+                }, z.core.$strip>>;
+                filterParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                searchParam: z.ZodOptional<z.ZodString>;
+                resultPath: z.ZodOptional<z.ZodString>;
+                jsonRpcEnvelope: z.ZodOptional<z.ZodObject<{
+                    rpcMethod: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            list: z.ZodObject<{
+                method: z.ZodEnum<typeof import("../external-data.exports").HttpApiRestOperationMethod>;
+                pathTemplate: z.ZodString;
+                pagingParams: z.ZodOptional<z.ZodObject<{
+                    limitParam: z.ZodString;
+                    offsetParam: z.ZodString;
+                }, z.core.$strip>>;
+                filterParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                searchParam: z.ZodOptional<z.ZodString>;
+                resultPath: z.ZodOptional<z.ZodString>;
+                jsonRpcEnvelope: z.ZodOptional<z.ZodObject<{
+                    rpcMethod: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            count: z.ZodOptional<z.ZodObject<{
+                method: z.ZodEnum<typeof import("../external-data.exports").HttpApiRestOperationMethod>;
+                pathTemplate: z.ZodString;
+                pagingParams: z.ZodOptional<z.ZodObject<{
+                    limitParam: z.ZodString;
+                    offsetParam: z.ZodString;
+                }, z.core.$strip>>;
+                filterParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                searchParam: z.ZodOptional<z.ZodString>;
+                resultPath: z.ZodOptional<z.ZodString>;
+                jsonRpcEnvelope: z.ZodOptional<z.ZodObject<{
+                    rpcMethod: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            search: z.ZodOptional<z.ZodObject<{
+                method: z.ZodEnum<typeof import("../external-data.exports").HttpApiRestOperationMethod>;
+                pathTemplate: z.ZodString;
+                pagingParams: z.ZodOptional<z.ZodObject<{
+                    limitParam: z.ZodString;
+                    offsetParam: z.ZodString;
+                }, z.core.$strip>>;
+                filterParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                searchParam: z.ZodOptional<z.ZodString>;
+                resultPath: z.ZodOptional<z.ZodString>;
+                jsonRpcEnvelope: z.ZodOptional<z.ZodObject<{
+                    rpcMethod: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        providerRef: z.ZodString;
+        entityRef: z.ZodString;
+        identityMode: z.ZodDefault<z.ZodEnum<typeof import("../external-data.exports").HttpApiIdentityMode>>;
+        keyFields: z.ZodArray<z.ZodObject<{
+            localField: z.ZodString;
+            remoteField: z.ZodString;
+            codec: z.ZodEnum<typeof import("../external-data.exports").HttpApiKeyComponentCodec>;
+        }, z.core.$strip>>;
+        fieldMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            localField: z.ZodString;
+            remoteField: z.ZodString;
+        }, z.core.$strip>>>;
+        tenancy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            stance: z.ZodLiteral<HttpApiTenancyStance.SCOPE_FILTER_PUSHDOWN>;
+            remoteScopeField: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<HttpApiTenancyStance.SINGLE_TENANT_BINDING>;
+            justification: z.ZodString;
+        }, z.core.$strip>], "stance">;
+        erasure: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.NO_SUBJECT_DATA>;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION>;
+            operation: z.ZodUnion<readonly [z.ZodObject<{
+                useCanonicalDelete: z.ZodLiteral<true>;
+            }, z.core.$strip>, z.ZodObject<{
+                method: z.ZodEnum<typeof import("../external-data.exports").HttpApiErasureOperationMethod>;
+                pathTemplate: z.ZodString;
+                jsonRpcEnvelope: z.ZodOptional<z.ZodObject<{
+                    rpcMethod: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>;
+            subjectLinkLocalField: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.CONTROLLER_ACKNOWLEDGED_NON_ERASURE>;
+            subjectLinkLocalField: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "stance">;
+        remoteCallSemantics: z.ZodDefault<z.ZodObject<{
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+            retry: z.ZodDefault<z.ZodObject<{
+                maxAttempts: z.ZodDefault<z.ZodNumber>;
+                backoffMs: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+            maxRequestsPerMinute: z.ZodOptional<z.ZodNumber>;
+            maxIdSetSize: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        dialect: z.ZodLiteral<HttpApiTransportDialect.REST_JSON>;
+    }, z.core.$strip>, z.ZodObject<{
+        providerRef: z.ZodString;
+        entityRef: z.ZodString;
+        identityMode: z.ZodDefault<z.ZodEnum<typeof import("../external-data.exports").HttpApiIdentityMode>>;
+        keyFields: z.ZodArray<z.ZodObject<{
+            localField: z.ZodString;
+            remoteField: z.ZodString;
+            codec: z.ZodEnum<typeof import("../external-data.exports").HttpApiKeyComponentCodec>;
+        }, z.core.$strip>>;
+        fieldMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            localField: z.ZodString;
+            remoteField: z.ZodString;
+        }, z.core.$strip>>>;
+        tenancy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            stance: z.ZodLiteral<HttpApiTenancyStance.SCOPE_FILTER_PUSHDOWN>;
+            remoteScopeField: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<HttpApiTenancyStance.SINGLE_TENANT_BINDING>;
+            justification: z.ZodString;
+        }, z.core.$strip>], "stance">;
+        erasure: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.NO_SUBJECT_DATA>;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION>;
+            operation: z.ZodUnion<readonly [z.ZodObject<{
+                useCanonicalDelete: z.ZodLiteral<true>;
+            }, z.core.$strip>, z.ZodObject<{
+                method: z.ZodEnum<typeof import("../external-data.exports").HttpApiErasureOperationMethod>;
+                pathTemplate: z.ZodString;
+                jsonRpcEnvelope: z.ZodOptional<z.ZodObject<{
+                    rpcMethod: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>;
+            subjectLinkLocalField: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            stance: z.ZodLiteral<import("../external-data.exports").HttpApiErasureStance.CONTROLLER_ACKNOWLEDGED_NON_ERASURE>;
+            subjectLinkLocalField: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "stance">;
+        remoteCallSemantics: z.ZodDefault<z.ZodObject<{
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+            retry: z.ZodDefault<z.ZodObject<{
+                maxAttempts: z.ZodDefault<z.ZodNumber>;
+                backoffMs: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+            maxRequestsPerMinute: z.ZodOptional<z.ZodNumber>;
+            maxIdSetSize: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        dialect: z.ZodLiteral<HttpApiTransportDialect.ODOO_JSONRPC>;
+    }, z.core.$strip>], "dialect">;
+    remoteKeyLocalField: z.ZodString;
+    mapping: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<ExternalDataMappingEntryKind.REMOTE_FIELD>;
+        remoteField: z.ZodString;
+        localField: z.ZodString;
+        coercion: z.ZodDefault<z.ZodEnum<typeof ExternalDataFieldCoercion>>;
+        required: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ExternalDataMappingEntryKind.CONSTANT>;
+        localField: z.ZodString;
+        constant: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>], "kind">>;
+    sourceFilter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    population: z.ZodDefault<z.ZodEnum<typeof ExternalDataDestinationPopulation>>;
+    orphanPolicy: z.ZodDefault<z.ZodEnum<typeof ExternalDataOrphanPolicy>>;
+    scheduleCron: z.ZodOptional<z.ZodString>;
+    maxRowsPerRun: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** @wildo_source:part:end saas.models.external-data-pipeline */
+export type ExternalDataPipelineDeclaration = z.infer<typeof ExternalDataPipelineDeclarationSchema>;
+/**
+ * Schema-INDEPENDENT coherence of a parsed declaration — the mainSchema-dependent half lives in
+ * the resource-configuration factory (it needs the shape). Throws with the offending path named,
+ * mirroring `assertHttpApiBindingDialectCoherence`'s contract.
+ */
+export declare function assertExternalDataPipelineDeclarationCoherence(declaration: ExternalDataPipelineDeclaration): void;
+//# sourceMappingURL=external-data-pipeline.shared.schemas.d.ts.map

package/dist/esm/external-data/external-data-pipeline.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-pipeline.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-data/external-data-pipeline.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,oBAAoB,EACpB,uBAAuB,EACxB,MAAM,qDAAqD,CAAC;AAE7D;;;;;GAKG;AACH,kHAAkH;AAClH,oBAAY,6BAA6B;IACvC,OAAO,YAAY;CACpB;AAED;;;;;;GAMG;AACH,oBAAY,iCAAiC;IAC3C;;;;OAIG;IACH,MAAM,WAAW;IACjB;;;;;OAKG;IACH,IAAI,SAAS;CACd;AAED;;;;;;;;;GASG;AACH,oBAAY,wBAAwB;IAClC,uGAAuG;IACvG,MAAM,WAAW;IACjB,mGAAmG;IACnG,SAAS,cAAc;IACvB,uFAAuF;IACvF,MAAM,WAAW;CAClB;AAED,kGAAkG;AAClG,oBAAY,4BAA4B;IACtC,+DAA+D;IAC/D,YAAY,iBAAiB;IAC7B,yGAAyG;IACzG,QAAQ,aAAa;CACtB;AAED;;;;GAIG;AACH,oBAAY,yBAAyB;IACnC,+EAA+E;IAC/E,IAAI,SAAS;IACb;;;;OAIG;IACH,kBAAkB,uBAAuB;IACzC,mFAAmF;IACnF,kBAAkB,uBAAuB;CAC1C;AAED,+FAA+F;AAC/F,eAAO,MAAM,mCAAmC;;;;;;;;;;2BAkB9C,CAAC;AAEH,gEAAgE;AAChE,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAKhG;;;;;;;GAOG;AACH,kHAAkH;AAClH,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoDhD,CAAC;AAEH,gEAAgE;AAChE,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAEpG;;;;GAIG;AACH,wBAAgB,8CAA8C,CAAC,WAAW,EAAE,+BAA+B,GAAG,IAAI,CAyCjH"}

package/dist/esm/external-data/external-data-pipeline.shared.schemas.js

@@ -0,0 +1,206 @@
+/**
+ * The ETL PIPELINE declaration (`externalDataPipeline`) — partial-resource coverage, model v3
+ * (`.claude/plans/etl-partial-resource-coverage.md`, PR-3/PR-19; decisions D-P1…D-P10).
+ *
+ * "Some resources local, some remote, ETL between them": an ordinary LOCAL resource may declare
+ * ONE inbound pipeline from a remote HTTP-API entity. The declaration reuses the whole
+ * {@link HttpApiResourceBindingSchema} as its source half (provider, entity, dialect, key
+ * fields, remote-call semantics — the E is the same adapter plumbing the VIRTUAL mode runs on),
+ * adds the T (a declared field mapping) and the L/refresh contract (population posture, orphan
+ * policy, schedule, run bounds). The destination stays a FULL local resource — files, RAG,
+ * retention/erasure, charts and the read-only UI chain are all inherited, never re-built.
+ *
+ * Everything here is a CLOSED vocabulary with one named source; the runtime seams (P-2) consume
+ * these members, and the paper's ledger rows (PR-…) are cited per surface.
+ */
+import { z } from 'zod';
+import { HttpApiResourceBindingSchema, HttpApiTenancyStance, HttpApiTransportDialect, } from '../http-api-binding/http-api-binding.shared.schemas.js';
+/**
+ * Pipeline direction (PR-19). A SINGLE-member enum on purpose: reverse ETL (local→remote) and
+ * bidirectional sync belong to the outbound-writes gate (ETL plan Step 5, concurrency contract),
+ * but the DECLARATION is direction-extensible NOW so those arrive as new members instead of a
+ * schema reshape — the immutability-needs-a-paired-path lesson applied to a vocabulary.
+ */
+/** @wildo_source:part:start saas.models.external-data-pipeline facet:layer:shared facet:audience:app-developer */
+export var ExternalDataPipelineDirection;
+(function (ExternalDataPipelineDirection) {
+    ExternalDataPipelineDirection["INBOUND"] = "inbound";
+})(ExternalDataPipelineDirection || (ExternalDataPipelineDirection = {}));
+/**
+ * Who owns the destination's row population (D-P8, v3.1 §1).
+ *
+ * The declared answer to the question the orphan sweep MUST have: "is a row the pipeline did not
+ * create a USER row, or a VANISHED remote row?" — undeclared mixed populations are how an orphan
+ * pass deletes user data.
+ */
+export var ExternalDataDestinationPopulation;
+(function (ExternalDataDestinationPopulation) {
+    /**
+     * Every row comes from the pipeline. Caller CREATE is refused at declaration time, and orphan
+     * detection may consider the whole population. The default: safest, and the honest description
+     * of a synced master-data table.
+     */
+    ExternalDataDestinationPopulation["CLOSED"] = "closed";
+    /**
+     * Mixed rows: users may create rows the pipeline does not own. Pipeline rows are identified by
+     * the remote-key field being present, and orphan detection is CONFINED to that population. A
+     * user row that later matches an incoming remote key is ADOPTED by the upsert (documented
+     * collision semantics, not an accident).
+     */
+    ExternalDataDestinationPopulation["OPEN"] = "open";
+})(ExternalDataDestinationPopulation || (ExternalDataDestinationPopulation = {}));
+/**
+ * What happens to a destination row whose remote counterpart disappeared (D-P9).
+ *
+ * MIRRORS `DataSeedSyncOrphanPolicy` (saas-backend-lib, data-seeding) member-for-member, and the
+ * P-2 pipeline→SYNC seam maps the two 1:1. A separate enum EXISTS ONLY because of dependency
+ * direction: this declaration lives in saas-models, the data-seeding models live in
+ * saas-backend-lib, and models cannot import backend. If the data-seeding vocabulary ever moves
+ * down to saas-models, collapse this enum into it — do not let the two drift meanwhile (the
+ * seam's mapping is exhaustive and compile-forced, so a new member on either side reddens P-2).
+ */
+export var ExternalDataOrphanPolicy;
+(function (ExternalDataOrphanPolicy) {
+    /** Hard-delete the orphan row — flows through ordinary lifecycle (cascades, file teardown). Opt-in. */
+    ExternalDataOrphanPolicy["DELETE"] = "delete";
+    /** Mark the row deprecated and keep it; a re-appearing remote key REVIVES it (v3.1 §4). Opt-in. */
+    ExternalDataOrphanPolicy["DEPRECATE"] = "deprecate";
+    /** Touch nothing; surface the diff in the run ledger. The DEFAULT — least surprise. */
+    ExternalDataOrphanPolicy["REPORT"] = "report";
+})(ExternalDataOrphanPolicy || (ExternalDataOrphanPolicy = {}));
+/** The two shapes a mapping entry can take — a closed discriminator, never inferred from keys. */
+export var ExternalDataMappingEntryKind;
+(function (ExternalDataMappingEntryKind) {
+    /** Copy (and coerce) one remote field into one local field. */
+    ExternalDataMappingEntryKind["REMOTE_FIELD"] = "remote-field";
+    /** Fill one local field with a declared constant (destination-required fields with no remote source). */
+    ExternalDataMappingEntryKind["CONSTANT"] = "constant";
+})(ExternalDataMappingEntryKind || (ExternalDataMappingEntryKind = {}));
+/**
+ * Built-in, closed coercion vocabulary for REMOTE_FIELD entries (v3.1 §3 / PR-8). Slice 1 ships
+ * exactly the coercions the two generic dialects force; arbitrary transforms are the recorded
+ * widenings (W-FK resolution, W-AGENT authored transforms) — never an open function slot here.
+ */
+export var ExternalDataFieldCoercion;
+(function (ExternalDataFieldCoercion) {
+    /** Value lands as extracted (after the destination schema's own Zod parse). */
+    ExternalDataFieldCoercion["NONE"] = "none";
+    /**
+     * Odoo spells an ABSENT value as boolean `false` — a mapped string field would otherwise store
+     * literal `false`. Applied by DEFAULT for ODOO_JSONRPC sources; declaring it on another dialect
+     * is refused (the name is Odoo's semantics, not a generic null-coalesce).
+     */
+    ExternalDataFieldCoercion["ODOO_FALSE_AS_NULL"] = "odoo-false-as-null";
+    /** Parse a strict-ISO datetime string into a Date for a date-typed local field. */
+    ExternalDataFieldCoercion["ISO_STRING_TO_DATE"] = "iso-string-to-date";
+})(ExternalDataFieldCoercion || (ExternalDataFieldCoercion = {}));
+/** One declared T-step: remote field → local field with a built-in coercion, or a constant. */
+export const ExternalDataFieldMappingEntrySchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal(ExternalDataMappingEntryKind.REMOTE_FIELD),
+        remoteField: z.string().trim().min(1),
+        localField: z.string().trim().min(1),
+        coercion: z.enum(ExternalDataFieldCoercion).default(ExternalDataFieldCoercion.NONE),
+        /**
+         * `true`: a row whose extracted value is ABSENT is REJECTED (reported per row in the run
+         * ledger; its previous local version survives). `false` (default): absent lands as null,
+         * which the declaration coherence requires the local field to accept.
+         */
+        required: z.boolean().default(false),
+    }),
+    z.object({
+        kind: z.literal(ExternalDataMappingEntryKind.CONSTANT),
+        localField: z.string().trim().min(1),
+        constant: z.union([z.string(), z.number(), z.boolean()]),
+    }),
+]);
+/** Scalar values admissible in the declared source filter (T-set equality conjunctions only). */
+const externalDataPipelineFilterScalarSchema = z.union([z.string(), z.number(), z.boolean()]);
+/**
+ * The inbound pipeline declaration an ordinary LOCAL resource carries as `externalDataPipeline`.
+ *
+ * NOT legal on an HTTP_API-adapter resource (a virtual resource IS the remote side); the
+ * resource-configuration factory enforces that plus every mainSchema-dependent coherence rule —
+ * see `validateExternalDataPipelineDeclarationAgainstSchema` there. This module owns only the
+ * schema-independent shape and coherence.
+ */
+/** @wildo_source:part:start saas.models.external-data-pipeline facet:layer:shared facet:audience:app-developer */
+export const ExternalDataPipelineDeclarationSchema = z.object({
+    direction: z.enum(ExternalDataPipelineDirection).default(ExternalDataPipelineDirection.INBOUND),
+    /**
+     * The source half — the SAME binding declaration the VIRTUAL mode uses (provider, entity,
+     * dialect, key fields + codecs, remote-call semantics, erasure stance, tenancy). Slice 1
+     * confines pipelines to SINGLE_TENANT_BINDING sources (W-TENANCY records the widening — a
+     * wrong remote-scope→org mapping is a cross-tenant leak, so it is designed, not improvised).
+     *
+     * ⚠ OPERATIONAL HAZARD (PR-16): changing `keyFields` or a component CODEC after rows exist
+     * re-keys EVERY business key — the whole destination population orphans and re-creates on the
+     * next full pass, detaching local annotations (extension fields, files, chunks) from the rows
+     * that replace them. Treat a key/codec change as a MIGRATION EVENT, never a config tweak. Not
+     * mechanically detectable at authoring (no row access here). Relatedly: a remote system that
+     * RECYCLES ids hands the recycled row the OLD row's local annotations — the upsert cannot tell
+     * a revived entity from a new one wearing its key.
+     */
+    binding: HttpApiResourceBindingSchema,
+    /**
+     * The LOCAL field holding the row's remote identity — the synthesized id (paper A codec) as a
+     * plain STRING business key. The factory requires it declared `.isBusinessKey()` +
+     * `excludeFromCreate/Update`: SYNC's idempotent upsert keys on it, and no caller may mint or
+     * move it.
+     */
+    remoteKeyLocalField: z.string().trim().min(1),
+    /** The declared T — at least one entry; targets validated against `mainSchema` by the factory. */
+    mapping: z.array(ExternalDataFieldMappingEntrySchema).min(1),
+    /**
+     * Optional remote-side subset (v3.1 §2): equality conjunctions over REMOTE fields, exactly the
+     * T-set's T3 shape — anything richer is a widening, not an improvisation.
+     */
+    sourceFilter: z.record(z.string().trim().min(1), externalDataPipelineFilterScalarSchema).optional(),
+    population: z.enum(ExternalDataDestinationPopulation).default(ExternalDataDestinationPopulation.CLOSED),
+    orphanPolicy: z.enum(ExternalDataOrphanPolicy).default(ExternalDataOrphanPolicy.REPORT),
+    /**
+     * Cron expression for the scheduled refresh (crontabs machinery). Absent = on-demand only —
+     * legal, and honest for a manually-driven backfill.
+     */
+    scheduleCron: z.string().trim().min(1).optional(),
+    /**
+     * Extraction bound per run (v3.1 §2): a big backfill progresses across runs via the ledger's
+     * resumable cursor instead of owning one unbounded run. The default matches the rate-budget
+     * era's "bounded by construction" posture.
+     */
+    maxRowsPerRun: z.number().int().positive().default(10_000),
+});
+/**
+ * Schema-INDEPENDENT coherence of a parsed declaration — the mainSchema-dependent half lives in
+ * the resource-configuration factory (it needs the shape). Throws with the offending path named,
+ * mirroring `assertHttpApiBindingDialectCoherence`'s contract.
+ */
+export function assertExternalDataPipelineDeclarationCoherence(declaration) {
+    // S1 tenancy confinement (v3.1 §2 / W-TENANCY).
+    if (declaration.binding.tenancy.stance !== HttpApiTenancyStance.SINGLE_TENANT_BINDING) {
+        throw new Error("binding.tenancy: slice 1 confines pipelines to SINGLE_TENANT_BINDING sources — a pushdown-tenancy source needs the declared remote-scope→organization mapping (widening W-TENANCY), because a wrong org assignment is a cross-tenant leak.");
+    }
+    // D-P10: extraction uses drift-safe paging ONLY (`@odata.nextLink` / the Odoo id-keyset
+    // cursor). REST_JSON declares offset paging, which skips or doubles rows whenever the remote
+    // set shifts mid-run — so a REST_JSON pipeline SOURCE is refused until a declared cursor
+    // contract exists for the dialect (a recorded widening beside W-DELTA, not an improvisation).
+    if (declaration.binding.dialect === HttpApiTransportDialect.REST_JSON) {
+        throw new Error('binding.dialect: REST_JSON pipeline sources are refused in slice 1 — the dialect declares offset paging, which drifts under concurrent remote change (rows skipped or doubled). ODATA (@odata.nextLink) and ODOO_JSONRPC (id cursor) sources are drift-safe; a declared REST cursor contract is the recorded widening.');
+    }
+    const localTargets = new Set();
+    for (const entry of declaration.mapping) {
+        if (localTargets.has(entry.localField)) {
+            throw new Error(`mapping: local field '${entry.localField}' is targeted by more than one entry — one writer per field.`);
+        }
+        localTargets.add(entry.localField);
+        if (entry.localField === declaration.remoteKeyLocalField) {
+            throw new Error(`mapping: local field '${entry.localField}' is the remoteKeyLocalField — the remote identity is written by the pipeline's L from the synthesized id, never by a mapping entry.`);
+        }
+        if (entry.kind === ExternalDataMappingEntryKind.REMOTE_FIELD
+            && entry.coercion === ExternalDataFieldCoercion.ODOO_FALSE_AS_NULL
+            && declaration.binding.dialect !== HttpApiTransportDialect.ODOO_JSONRPC) {
+            throw new Error(`mapping('${entry.localField}').coercion: '${ExternalDataFieldCoercion.ODOO_FALSE_AS_NULL}' names Odoo's absent-as-false semantics and is refused on a ${declaration.binding.dialect} source.`);
+        }
+    }
+}
+//# sourceMappingURL=external-data-pipeline.shared.schemas.js.map

package/dist/esm/external-data/external-data-pipeline.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-pipeline.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-data/external-data-pipeline.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The ETL PIPELINE declaration (`externalDataPipeline`) — partial-resource coverage, model v3\n * (`.claude/plans/etl-partial-resource-coverage.md`, PR-3/PR-19; decisions D-P1…D-P10).\n *\n * \"Some resources local, some remote, ETL between them\": an ordinary LOCAL resource may declare\n * ONE inbound pipeline from a remote HTTP-API entity. The declaration reuses the whole\n * {@link HttpApiResourceBindingSchema} as its source half (provider, entity, dialect, key\n * fields, remote-call semantics — the E is the same adapter plumbing the VIRTUAL mode runs on),\n * adds the T (a declared field mapping) and the L/refresh contract (population posture, orphan\n * policy, schedule, run bounds). The destination stays a FULL local resource — files, RAG,\n * retention/erasure, charts and the read-only UI chain are all inherited, never re-built.\n *\n * Everything here is a CLOSED vocabulary with one named source; the runtime seams (P-2) consume\n * these members, and the paper's ledger rows (PR-…) are cited per surface.\n */\n\nimport { z } from 'zod';\n\nimport {\n  HttpApiResourceBindingSchema,\n  HttpApiTenancyStance,\n  HttpApiTransportDialect,\n} from '../http-api-binding/http-api-binding.shared.schemas';\n\n/**\n * Pipeline direction (PR-19). A SINGLE-member enum on purpose: reverse ETL (local→remote) and\n * bidirectional sync belong to the outbound-writes gate (ETL plan Step 5, concurrency contract),\n * but the DECLARATION is direction-extensible NOW so those arrive as new members instead of a\n * schema reshape — the immutability-needs-a-paired-path lesson applied to a vocabulary.\n */\n/** @wildo_source:part:start saas.models.external-data-pipeline facet:layer:shared facet:audience:app-developer */\nexport enum ExternalDataPipelineDirection {\n  INBOUND = 'inbound',\n}\n\n/**\n * Who owns the destination's row population (D-P8, v3.1 §1).\n *\n * The declared answer to the question the orphan sweep MUST have: \"is a row the pipeline did not\n * create a USER row, or a VANISHED remote row?\" — undeclared mixed populations are how an orphan\n * pass deletes user data.\n */\nexport enum ExternalDataDestinationPopulation {\n  /**\n   * Every row comes from the pipeline. Caller CREATE is refused at declaration time, and orphan\n   * detection may consider the whole population. The default: safest, and the honest description\n   * of a synced master-data table.\n   */\n  CLOSED = 'closed',\n  /**\n   * Mixed rows: users may create rows the pipeline does not own. Pipeline rows are identified by\n   * the remote-key field being present, and orphan detection is CONFINED to that population. A\n   * user row that later matches an incoming remote key is ADOPTED by the upsert (documented\n   * collision semantics, not an accident).\n   */\n  OPEN = 'open',\n}\n\n/**\n * What happens to a destination row whose remote counterpart disappeared (D-P9).\n *\n * MIRRORS `DataSeedSyncOrphanPolicy` (saas-backend-lib, data-seeding) member-for-member, and the\n * P-2 pipeline→SYNC seam maps the two 1:1. A separate enum EXISTS ONLY because of dependency\n * direction: this declaration lives in saas-models, the data-seeding models live in\n * saas-backend-lib, and models cannot import backend. If the data-seeding vocabulary ever moves\n * down to saas-models, collapse this enum into it — do not let the two drift meanwhile (the\n * seam's mapping is exhaustive and compile-forced, so a new member on either side reddens P-2).\n */\nexport enum ExternalDataOrphanPolicy {\n  /** Hard-delete the orphan row — flows through ordinary lifecycle (cascades, file teardown). Opt-in. */\n  DELETE = 'delete',\n  /** Mark the row deprecated and keep it; a re-appearing remote key REVIVES it (v3.1 §4). Opt-in. */\n  DEPRECATE = 'deprecate',\n  /** Touch nothing; surface the diff in the run ledger. The DEFAULT — least surprise. */\n  REPORT = 'report',\n}\n\n/** The two shapes a mapping entry can take — a closed discriminator, never inferred from keys. */\nexport enum ExternalDataMappingEntryKind {\n  /** Copy (and coerce) one remote field into one local field. */\n  REMOTE_FIELD = 'remote-field',\n  /** Fill one local field with a declared constant (destination-required fields with no remote source). */\n  CONSTANT = 'constant',\n}\n\n/**\n * Built-in, closed coercion vocabulary for REMOTE_FIELD entries (v3.1 §3 / PR-8). Slice 1 ships\n * exactly the coercions the two generic dialects force; arbitrary transforms are the recorded\n * widenings (W-FK resolution, W-AGENT authored transforms) — never an open function slot here.\n */\nexport enum ExternalDataFieldCoercion {\n  /** Value lands as extracted (after the destination schema's own Zod parse). */\n  NONE = 'none',\n  /**\n   * Odoo spells an ABSENT value as boolean `false` — a mapped string field would otherwise store\n   * literal `false`. Applied by DEFAULT for ODOO_JSONRPC sources; declaring it on another dialect\n   * is refused (the name is Odoo's semantics, not a generic null-coalesce).\n   */\n  ODOO_FALSE_AS_NULL = 'odoo-false-as-null',\n  /** Parse a strict-ISO datetime string into a Date for a date-typed local field. */\n  ISO_STRING_TO_DATE = 'iso-string-to-date',\n}\n\n/** One declared T-step: remote field → local field with a built-in coercion, or a constant. */\nexport const ExternalDataFieldMappingEntrySchema = z.discriminatedUnion('kind', [\n  z.object({\n    kind: z.literal(ExternalDataMappingEntryKind.REMOTE_FIELD),\n    remoteField: z.string().trim().min(1),\n    localField: z.string().trim().min(1),\n    coercion: z.enum(ExternalDataFieldCoercion).default(ExternalDataFieldCoercion.NONE),\n    /**\n     * `true`: a row whose extracted value is ABSENT is REJECTED (reported per row in the run\n     * ledger; its previous local version survives). `false` (default): absent lands as null,\n     * which the declaration coherence requires the local field to accept.\n     */\n    required: z.boolean().default(false),\n  }),\n  z.object({\n    kind: z.literal(ExternalDataMappingEntryKind.CONSTANT),\n    localField: z.string().trim().min(1),\n    constant: z.union([z.string(), z.number(), z.boolean()]),\n  }),\n]);\n\n/** @wildo_source:part:end saas.models.external-data-pipeline */\nexport type ExternalDataFieldMappingEntry = z.infer<typeof ExternalDataFieldMappingEntrySchema>;\n\n/** Scalar values admissible in the declared source filter (T-set equality conjunctions only). */\nconst externalDataPipelineFilterScalarSchema = z.union([z.string(), z.number(), z.boolean()]);\n\n/**\n * The inbound pipeline declaration an ordinary LOCAL resource carries as `externalDataPipeline`.\n *\n * NOT legal on an HTTP_API-adapter resource (a virtual resource IS the remote side); the\n * resource-configuration factory enforces that plus every mainSchema-dependent coherence rule —\n * see `validateExternalDataPipelineDeclarationAgainstSchema` there. This module owns only the\n * schema-independent shape and coherence.\n */\n/** @wildo_source:part:start saas.models.external-data-pipeline facet:layer:shared facet:audience:app-developer */\nexport const ExternalDataPipelineDeclarationSchema = z.object({\n  direction: z.enum(ExternalDataPipelineDirection).default(ExternalDataPipelineDirection.INBOUND),\n\n  /**\n   * The source half — the SAME binding declaration the VIRTUAL mode uses (provider, entity,\n   * dialect, key fields + codecs, remote-call semantics, erasure stance, tenancy). Slice 1\n   * confines pipelines to SINGLE_TENANT_BINDING sources (W-TENANCY records the widening — a\n   * wrong remote-scope→org mapping is a cross-tenant leak, so it is designed, not improvised).\n   *\n   * ⚠ OPERATIONAL HAZARD (PR-16): changing `keyFields` or a component CODEC after rows exist\n   * re-keys EVERY business key — the whole destination population orphans and re-creates on the\n   * next full pass, detaching local annotations (extension fields, files, chunks) from the rows\n   * that replace them. Treat a key/codec change as a MIGRATION EVENT, never a config tweak. Not\n   * mechanically detectable at authoring (no row access here). Relatedly: a remote system that\n   * RECYCLES ids hands the recycled row the OLD row's local annotations — the upsert cannot tell\n   * a revived entity from a new one wearing its key.\n   */\n  binding: HttpApiResourceBindingSchema,\n\n  /**\n   * The LOCAL field holding the row's remote identity — the synthesized id (paper A codec) as a\n   * plain STRING business key. The factory requires it declared `.isBusinessKey()` +\n   * `excludeFromCreate/Update`: SYNC's idempotent upsert keys on it, and no caller may mint or\n   * move it.\n   */\n  remoteKeyLocalField: z.string().trim().min(1),\n\n  /** The declared T — at least one entry; targets validated against `mainSchema` by the factory. */\n  mapping: z.array(ExternalDataFieldMappingEntrySchema).min(1),\n\n  /**\n   * Optional remote-side subset (v3.1 §2): equality conjunctions over REMOTE fields, exactly the\n   * T-set's T3 shape — anything richer is a widening, not an improvisation.\n   */\n  sourceFilter: z.record(z.string().trim().min(1), externalDataPipelineFilterScalarSchema).optional(),\n\n  population: z.enum(ExternalDataDestinationPopulation).default(ExternalDataDestinationPopulation.CLOSED),\n\n  orphanPolicy: z.enum(ExternalDataOrphanPolicy).default(ExternalDataOrphanPolicy.REPORT),\n\n  /**\n   * Cron expression for the scheduled refresh (crontabs machinery). Absent = on-demand only —\n   * legal, and honest for a manually-driven backfill.\n   */\n  scheduleCron: z.string().trim().min(1).optional(),\n\n  /**\n   * Extraction bound per run (v3.1 §2): a big backfill progresses across runs via the ledger's\n   * resumable cursor instead of owning one unbounded run. The default matches the rate-budget\n   * era's \"bounded by construction\" posture.\n   */\n  maxRowsPerRun: z.number().int().positive().default(10_000),\n});\n\n/** @wildo_source:part:end saas.models.external-data-pipeline */\nexport type ExternalDataPipelineDeclaration = z.infer<typeof ExternalDataPipelineDeclarationSchema>;\n\n/**\n * Schema-INDEPENDENT coherence of a parsed declaration — the mainSchema-dependent half lives in\n * the resource-configuration factory (it needs the shape). Throws with the offending path named,\n * mirroring `assertHttpApiBindingDialectCoherence`'s contract.\n */\nexport function assertExternalDataPipelineDeclarationCoherence(declaration: ExternalDataPipelineDeclaration): void {\n  // S1 tenancy confinement (v3.1 §2 / W-TENANCY).\n  if (declaration.binding.tenancy.stance !== HttpApiTenancyStance.SINGLE_TENANT_BINDING) {\n    throw new Error(\n      \"binding.tenancy: slice 1 confines pipelines to SINGLE_TENANT_BINDING sources — a pushdown-tenancy source needs the declared remote-scope→organization mapping (widening W-TENANCY), because a wrong org assignment is a cross-tenant leak.\",\n    );\n  }\n\n  // D-P10: extraction uses drift-safe paging ONLY (`@odata.nextLink` / the Odoo id-keyset\n  // cursor). REST_JSON declares offset paging, which skips or doubles rows whenever the remote\n  // set shifts mid-run — so a REST_JSON pipeline SOURCE is refused until a declared cursor\n  // contract exists for the dialect (a recorded widening beside W-DELTA, not an improvisation).\n  if (declaration.binding.dialect === HttpApiTransportDialect.REST_JSON) {\n    throw new Error(\n      'binding.dialect: REST_JSON pipeline sources are refused in slice 1 — the dialect declares offset paging, which drifts under concurrent remote change (rows skipped or doubled). ODATA (@odata.nextLink) and ODOO_JSONRPC (id cursor) sources are drift-safe; a declared REST cursor contract is the recorded widening.',\n    );\n  }\n\n  const localTargets = new Set<string>();\n  for (const entry of declaration.mapping) {\n    if (localTargets.has(entry.localField)) {\n      throw new Error(`mapping: local field '${entry.localField}' is targeted by more than one entry — one writer per field.`);\n    }\n    localTargets.add(entry.localField);\n\n    if (entry.localField === declaration.remoteKeyLocalField) {\n      throw new Error(\n        `mapping: local field '${entry.localField}' is the remoteKeyLocalField — the remote identity is written by the pipeline's L from the synthesized id, never by a mapping entry.`,\n      );\n    }\n\n    if (\n      entry.kind === ExternalDataMappingEntryKind.REMOTE_FIELD\n      && entry.coercion === ExternalDataFieldCoercion.ODOO_FALSE_AS_NULL\n      && declaration.binding.dialect !== HttpApiTransportDialect.ODOO_JSONRPC\n    ) {\n      throw new Error(\n        `mapping('${entry.localField}').coercion: '${ExternalDataFieldCoercion.ODOO_FALSE_AS_NULL}' names Odoo's absent-as-false semantics and is refused on a ${declaration.binding.dialect} source.`,\n      );\n    }\n  }\n}\n"]}

package/dist/esm/external-data.exports.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@wildo-ai/saas-models/external-data` — the AUTHORING contract for data that lives in another
+ * system: the read-through VIRTUAL binding (`httpApiBinding`) and the copy-in PIPELINE
+ * (`externalDataPipeline`).
+ *
+ * ## Why this is a subpath rather than root, and why it is not in `saas-backend-lib`
+ *
+ * Both questions were measured on 2026-08-29 rather than argued.
+ *
+ * It is NOT backend-lib, even though only the backend has a runtime for it, because an application
+ * author writes these declarations in `*.resources-config.ts` — which lives in the app's
+ * `shared-lib`, a package that depends on `@wildo-ai/saas-models` and deliberately NOT on
+ * `@wildo-ai/saas-backend-lib` (the frontend imports `shared-lib`, so a backend dependency there
+ * would drag the backend graph browser-ward). Nothing in these modules is runtime: every symbol —
+ * dialects, tenancy, erasure, key fields, population, orphan policy, coercions — is typed by a
+ * human in a schema file. The runtime that consumes them (read client, extraction source,
+ * transform, run service, batch) is already backend-only.
+ *
+ * It IS a subpath rather than the root barrel because only two audiences need it — the app author
+ * declaring a resource, and the backend executing it — while the root is imported by every
+ * consumer of the resource model, including packages that will never speak to a remote system.
+ * Keeping it out of the root shrinks what they see without moving where it lives.
+ *
+ * ROW IDENTITY deliberately stays in the ROOT (`http-api-binding-id.shared.utils`): a synthesized
+ * id appears in URLs and frontend routing, and `ResourcesConfigUtils.isHttpApiSynthesizedId` reads
+ * it from shared code. Identity is not an integration concern.
+ */
+export * from './http-api-binding/http-api-binding.shared.schemas';
+export * from './external-data/external-data-pipeline.shared.schemas';
+//# sourceMappingURL=external-data.exports.d.ts.map

package/dist/esm/external-data.exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-data.exports.d.ts","sourceRoot":"","sources":["../../../src/external-data.exports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,cAAc,oDAAoD,CAAC;AACnE,cAAc,uDAAuD,CAAC"}