@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/errors/thrown-value-description.shared.utils.js

@@ -0,0 +1,66 @@
+/**
+ * A caught value as ONE readable line — the part of `describeCaughtError` that knows nothing about the
+ * engine's own error type, and therefore needs no import at all.
+ *
+ * Split out (2026-09-24) so a BROWSER-bound package can describe a caught value without importing the
+ * root of `@wildo-ai/saas-models`: a bundle-isolated package (`saas-website`) may reach this package only
+ * through `@wildo-ai/saas-models/public-runtime`. It is re-exported there, and `describeCaughtError`
+ * (in the import-free `caught-error-description.shared.utils`, #1591 — also on that seam) delegates to
+ * it for every value that is not a `WildoError_Backend`, so there is one implementation of the rendering.
+ *
+ * Prefer `describeCaughtError`, which is equally light: a value that IS a `WildoError_Backend` reads here
+ * as its identifying fields rather than its human message.
+ */
+export function describeThrownValue(error) {
+    return error instanceof Error ? error.message : describeNonErrorValue(error);
+}
+/**
+ * The fields of a thrown plain object that IDENTIFY the fault, rendered with their values — in this
+ * order. Everything else on the object is named by KEY only.
+ *
+ * The split is the logging rule, stated once: a diagnostic carries what failed, never the data it
+ * failed on. A provider's structured-generation error is a plain object whose other fields are the
+ * model's generated `text`, the provider `response` body and the rejected `cause.value`; rendering the
+ * whole object put all three into error logs and into trace telemetry every sink emits (measured
+ * 2026-09-24 on `agents.backend.service.structured-output-limit`, five pins red). An engine or
+ * application fault object names itself through these keys — `{ kind, reason }`, `{ code, message }` —
+ * so its diagnostic survives intact.
+ */
+const IDENTIFYING_FIELDS = ['name', 'code', 'kind', 'type', 'status', 'statusCode', 'reason', 'message'];
+/** The longest diagnostic this renders; a longer one is cut and says so. */
+const NON_ERROR_DESCRIPTION_LIMIT = 400;
+/**
+ * Render a thrown value that is neither an `Error` nor a {@link WildoError_Backend}.
+ *
+ * `String(value)` renders EVERY plain object as `'[object Object]'`, so distinct faults become one
+ * string. Measured 2026-09-23 (#1273): a playbook failed inside the journey's choreography and the run
+ * record persisted `'[object Object]'` as its only diagnostic. So an object is rendered by its
+ * {@link IDENTIFYING_FIELDS} with their scalar values, and by the NAMES of its other fields — never
+ * their values, which is where the data a fault carries lives (see that constant). A cyclic object
+ * needs no serialization this way, and the result is bounded.
+ */
+export function describeNonErrorValue(value) {
+    if (typeof value !== 'object' || value === null)
+        return String(value);
+    let keys;
+    try {
+        keys = Object.keys(value);
+    }
+    catch {
+        return String(value);
+    }
+    const record = value;
+    const identifying = IDENTIFYING_FIELDS.filter((key) => {
+        const field = record[key];
+        return (typeof field === 'string' && field.length > 0) || typeof field === 'number' || typeof field === 'boolean';
+    });
+    const parts = identifying.map((key) => `${key}: ${String(record[key])}`);
+    const otherKeys = keys.filter((key) => !identifying.includes(key));
+    if (otherKeys.length > 0)
+        parts.push(`fields: ${otherKeys.join(', ')}`);
+    const description = `{${parts.join('; ')}}`;
+    return description.length > NON_ERROR_DESCRIPTION_LIMIT
+        ? `${description.slice(0, NON_ERROR_DESCRIPTION_LIMIT)}… (truncated)`
+        : description;
+}
+//# sourceMappingURL=thrown-value-description.shared.utils.js.map

package/dist/esm/errors/thrown-value-description.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thrown-value-description.shared.utils.js","sourceRoot":"","sources":["../../../../src/errors/thrown-value-description.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AAElH,4EAA4E;AAC5E,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAExC;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACtE,IAAI,IAAc,CAAC;IACnB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,WAAW,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;QACpD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,CAAC;IACpH,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAE,WAAiC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1F,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACxE,MAAM,WAAW,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAC5C,OAAO,WAAW,CAAC,MAAM,GAAG,2BAA2B;QACrD,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,2BAA2B,CAAC,eAAe;QACrE,CAAC,CAAC,WAAW,CAAC;AAClB,CAAC","sourcesContent":["/**\n * A caught value as ONE readable line — the part of `describeCaughtError` that knows nothing about the\n * engine's own error type, and therefore needs no import at all.\n *\n * Split out (2026-09-24) so a BROWSER-bound package can describe a caught value without importing the\n * root of `@wildo-ai/saas-models`: a bundle-isolated package (`saas-website`) may reach this package only\n * through `@wildo-ai/saas-models/public-runtime`. It is re-exported there, and `describeCaughtError`\n * (in the import-free `caught-error-description.shared.utils`, #1591 — also on that seam) delegates to\n * it for every value that is not a `WildoError_Backend`, so there is one implementation of the rendering.\n *\n * Prefer `describeCaughtError`, which is equally light: a value that IS a `WildoError_Backend` reads here\n * as its identifying fields rather than its human message.\n */\nexport function describeThrownValue(error: unknown): string {\n  return error instanceof Error ? error.message : describeNonErrorValue(error);\n}\n\n/**\n * The fields of a thrown plain object that IDENTIFY the fault, rendered with their values — in this\n * order. Everything else on the object is named by KEY only.\n *\n * The split is the logging rule, stated once: a diagnostic carries what failed, never the data it\n * failed on. A provider's structured-generation error is a plain object whose other fields are the\n * model's generated `text`, the provider `response` body and the rejected `cause.value`; rendering the\n * whole object put all three into error logs and into trace telemetry every sink emits (measured\n * 2026-09-24 on `agents.backend.service.structured-output-limit`, five pins red). An engine or\n * application fault object names itself through these keys — `{ kind, reason }`, `{ code, message }` —\n * so its diagnostic survives intact.\n */\nconst IDENTIFYING_FIELDS = ['name', 'code', 'kind', 'type', 'status', 'statusCode', 'reason', 'message'] as const;\n\n/** The longest diagnostic this renders; a longer one is cut and says so. */\nconst NON_ERROR_DESCRIPTION_LIMIT = 400;\n\n/**\n * Render a thrown value that is neither an `Error` nor a {@link WildoError_Backend}.\n *\n * `String(value)` renders EVERY plain object as `'[object Object]'`, so distinct faults become one\n * string. Measured 2026-09-23 (#1273): a playbook failed inside the journey's choreography and the run\n * record persisted `'[object Object]'` as its only diagnostic. So an object is rendered by its\n * {@link IDENTIFYING_FIELDS} with their scalar values, and by the NAMES of its other fields — never\n * their values, which is where the data a fault carries lives (see that constant). A cyclic object\n * needs no serialization this way, and the result is bounded.\n */\nexport function describeNonErrorValue(value: unknown): string {\n  if (typeof value !== 'object' || value === null) return String(value);\n  let keys: string[];\n  try {\n    keys = Object.keys(value);\n  } catch {\n    return String(value);\n  }\n  const record = value as Record<string, unknown>;\n  const identifying = IDENTIFYING_FIELDS.filter((key) => {\n    const field = record[key];\n    return (typeof field === 'string' && field.length > 0) || typeof field === 'number' || typeof field === 'boolean';\n  });\n  const parts = identifying.map((key) => `${key}: ${String(record[key])}`);\n  const otherKeys = keys.filter((key) => !(identifying as readonly string[]).includes(key));\n  if (otherKeys.length > 0) parts.push(`fields: ${otherKeys.join(', ')}`);\n  const description = `{${parts.join('; ')}}`;\n  return description.length > NON_ERROR_DESCRIPTION_LIMIT\n    ? `${description.slice(0, NON_ERROR_DESCRIPTION_LIMIT)}… (truncated)`\n    : description;\n}\n"]}

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

@@ -0,0 +1,70 @@
+/**
+ * A pipeline declaration, described for a READER (#1685) — the structured `externalDataPipeline` slice a resource
+ * specification carries.
+ *
+ * ## Why it is derived, never authored
+ *
+ * Before this, a resource's specification described its pipeline in prose (Wonder Todos' `externalCustomers` did, in
+ * `notes` and `businessConstraints`), and prose restating a declaration is a second copy that starts drifting the day
+ * the declaration changes. So the slice is a FUNCTION of the declaration: `resourceSpecification()` attaches it when
+ * it can materialize the resource configuration, and the companion's specification projection derives it from the
+ * configuration it already holds. Nothing here is typed by an author, so nothing here can disagree with what runs.
+ *
+ * ## What it answers
+ *
+ * Where the rows come from (system, entity, dialect), which rows (the source filter, archived rows), how they are
+ * keyed, when a pass runs, what happens to a row that leaves the source — and, per local field, WHAT writes it: the
+ * remote fields it reads and the declared operation, including the four expressions (enum mapping, concatenation,
+ * arithmetic, conditional). `expression` is a one-line rendering of that operation for a person reviewing the
+ * specification; `entry` is the declared data itself, for a reader that needs the exact values.
+ */
+import { ExternalDataMappingEntryKind, ExternalDataPipelineDirection, type ExternalDataFieldMappingEntry, type ExternalDataPipelineDeclaration } from './external-data-pipeline.shared.schemas';
+/** One local field the pipeline writes, and how. */
+export interface ExternalDataPipelineMappingDescription {
+    readonly localField: string;
+    readonly kind: ExternalDataMappingEntryKind;
+    /** Every remote field this entry reads — what the extraction requests for it. Empty for a CONSTANT. */
+    readonly readsRemoteFields: readonly string[];
+    /** The declared operation in one line, for a reviewer. */
+    readonly expression: string;
+    /** The declared entry, exactly as the pipeline runs it. */
+    readonly entry: ExternalDataFieldMappingEntry;
+}
+/** The structured pipeline slice of a resource specification. */
+export interface ExternalDataPipelineDescription {
+    /**
+     * Which way rows travel (#1690). For an OUTBOUND pipeline `source` names where rows are SENT, each mapping entry names
+     * the local field sent and the remote field it lands on, and the inbound-only facts (`population`, `orphanPolicy`,
+     * `sourceFilter`, `archivedRecords`, `incremental`) describe nothing and are null.
+     */
+    readonly direction: ExternalDataPipelineDirection;
+    readonly source: {
+        readonly system: string;
+        readonly entityRef: string;
+        readonly dialect: string;
+    };
+    /** For an OUTBOUND or BIDIRECTIONAL pipeline, the write verbs it sends (`create`, `update`); empty for an inbound one. */
+    readonly sends: readonly string[];
+    /** A BIDIRECTIONAL pipeline's conflict policy (#1723), resolved; null for any other direction. */
+    readonly conflictPolicy: string | null;
+    /** The local field holding each row's remote identity, the key the load merges on. */
+    readonly remoteKeyLocalField: string;
+    readonly sourceFilter: Readonly<Record<string, unknown>> | null;
+    readonly population: string | null;
+    readonly orphanPolicy: string | null;
+    readonly archivedRecords: string | null;
+    readonly scheduleCron: string | null;
+    readonly incremental: {
+        readonly mode: string;
+        readonly fullPassCron: string;
+    } | null;
+    /** The partition stamps; an OUTBOUND pipeline has only the unit a created row is placed by (`key` null). */
+    readonly partitionFields: {
+        readonly unit: string;
+        readonly key: string | null;
+    } | null;
+    readonly mapping: readonly ExternalDataPipelineMappingDescription[];
+}
+/** Describe a PARSED pipeline declaration for a resource specification (#1685). */
+export declare function describeExternalDataPipeline(declaration: ExternalDataPipelineDeclaration): ExternalDataPipelineDescription;
+//# sourceMappingURL=external-data-pipeline-description.shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-pipeline-description.shared.d.ts","sourceRoot":"","sources":["../../../../src/external-data/external-data-pipeline-description.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAIL,4BAA4B,EAC5B,6BAA6B,EAM7B,KAAK,6BAA6B,EAClC,KAAK,+BAA+B,EACrC,MAAM,yCAAyC,CAAC;AAEjD,oDAAoD;AACpD,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,uGAAuG;IACvG,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,6BAA6B,CAAC;CAC/C;AAED,iEAAiE;AACjE,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,6BAA6B,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnG,0HAA0H;IAC1H,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kGAAkG;IAClG,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,sFAAsF;IACtF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtF,4GAA4G;IAC5G,QAAQ,CAAC,eAAe,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACxF,QAAQ,CAAC,OAAO,EAAE,SAAS,sCAAsC,EAAE,CAAC;CACrE;AA6CD,mFAAmF;AACnF,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,+BAA+B,GAAG,+BAA+B,CA4B1H"}

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

@@ -0,0 +1,92 @@
+/**
+ * A pipeline declaration, described for a READER (#1685) — the structured `externalDataPipeline` slice a resource
+ * specification carries.
+ *
+ * ## Why it is derived, never authored
+ *
+ * Before this, a resource's specification described its pipeline in prose (Wonder Todos' `externalCustomers` did, in
+ * `notes` and `businessConstraints`), and prose restating a declaration is a second copy that starts drifting the day
+ * the declaration changes. So the slice is a FUNCTION of the declaration: `resourceSpecification()` attaches it when
+ * it can materialize the resource configuration, and the companion's specification projection derives it from the
+ * configuration it already holds. Nothing here is typed by an author, so nothing here can disagree with what runs.
+ *
+ * ## What it answers
+ *
+ * Where the rows come from (system, entity, dialect), which rows (the source filter, archived rows), how they are
+ * keyed, when a pass runs, what happens to a row that leaves the source — and, per local field, WHAT writes it: the
+ * remote fields it reads and the declared operation, including the four expressions (enum mapping, concatenation,
+ * arithmetic, conditional). `expression` is a one-line rendering of that operation for a person reviewing the
+ * specification; `entry` is the declared data itself, for a reader that needs the exact values.
+ */
+import { ExternalDataConcatenationPartKind, ExternalDataConditionalOutcomeKind, ExternalDataFieldCoercion, ExternalDataMappingEntryKind, ExternalDataPipelineDirection, ExternalDataUnmappedValuePolicy, listExternalDataMappingEntryRemoteFields, resolveExternalDataConflictPolicy, resolveExternalDataFieldOwner, } from './external-data-pipeline.shared.schemas.js';
+const quoted = (value) => JSON.stringify(value);
+function describeOutcome(outcome) {
+    return outcome.kind === ExternalDataConditionalOutcomeKind.CONSTANT ? quoted(outcome.constant) : `\`${outcome.remoteField}\``;
+}
+/** The one-line rendering of one entry's operation. Total over the entry kinds. */
+function describeMappingExpression(entry) {
+    switch (entry.kind) {
+        case ExternalDataMappingEntryKind.REMOTE_FIELD:
+            return `\`${entry.remoteField}\``
+                + (entry.coercion === ExternalDataFieldCoercion.NONE ? '' : ` (${entry.coercion})`)
+                + (entry.required ? ', required' : '');
+        case ExternalDataMappingEntryKind.CONSTANT:
+            return `constant ${quoted(entry.constant)}`;
+        case ExternalDataMappingEntryKind.REMOTE_REFERENCE:
+            return `foreign key to ${entry.targetResourceType} from \`${entry.remoteField}\``
+                + (entry.valueShape === undefined ? '' : ` (${entry.valueShape})`) + `, unresolved: ${entry.unresolved}`;
+        case ExternalDataMappingEntryKind.ENUM_MAP:
+            return `\`${entry.remoteField}\` mapped: `
+                + entry.values.map(({ remoteValue, localValue }) => `${quoted(remoteValue)} → ${quoted(localValue)}`).join(', ')
+                + `; unmapped: ${entry.unmapped.policy === ExternalDataUnmappedValuePolicy.USE_DEFAULT ? quoted(entry.unmapped.localValue) : 'reject the row'}`
+                + (entry.required ? ', required' : '');
+        case ExternalDataMappingEntryKind.CONCATENATION:
+            return 'concatenation of '
+                + entry.parts.map((part) => (part.kind === ExternalDataConcatenationPartKind.REMOTE_FIELD ? `\`${part.remoteField}\`` : quoted(part.literal))).join(', ')
+                + (entry.separator === '' ? '' : ` joined by ${quoted(entry.separator)}`)
+                + (entry.required ? ', required' : '');
+        case ExternalDataMappingEntryKind.ARITHMETIC:
+            return `\`${entry.remoteField}\` × ${entry.factor}${entry.offset === 0 ? '' : ` + ${entry.offset}`}`
+                + (entry.decimalPlaces === undefined ? '' : `, rounded to ${entry.decimalPlaces} decimal places`)
+                + (entry.required ? ', required' : '');
+        case ExternalDataMappingEntryKind.CONDITIONAL:
+            return `by \`${entry.remoteField}\`: `
+                + entry.cases.map((entryCase) => `${quoted(entryCase.equals)} → ${describeOutcome(entryCase.then)}`).join('; ')
+                + `; otherwise ${describeOutcome(entry.otherwise)}`;
+        default: {
+            const unhandled = entry;
+            throw new Error(`describeExternalDataPipeline: unhandled mapping entry ${quoted(unhandled)}`);
+        }
+    }
+}
+/** Describe a PARSED pipeline declaration for a resource specification (#1685). */
+export function describeExternalDataPipeline(declaration) {
+    const outbound = declaration.direction === ExternalDataPipelineDirection.OUTBOUND;
+    const bidirectional = declaration.direction === ExternalDataPipelineDirection.BIDIRECTIONAL;
+    return {
+        direction: declaration.direction,
+        source: { system: declaration.binding.system, entityRef: declaration.binding.entityRef, dialect: declaration.binding.dialect },
+        sends: outbound || bidirectional ? [...declaration.binding.writableVerbs].sort() : [],
+        conflictPolicy: bidirectional ? resolveExternalDataConflictPolicy(declaration) : null,
+        remoteKeyLocalField: declaration.remoteKeyLocalField,
+        sourceFilter: declaration.sourceFilter ?? null,
+        // Parsed defaults on an OUTBOUND declaration, which refuses them when authored: describing them would state a load
+        // policy for a pipeline that loads nothing.
+        population: outbound ? null : declaration.population,
+        orphanPolicy: outbound ? null : declaration.orphanPolicy,
+        archivedRecords: declaration.archivedRecords?.treatment ?? null,
+        scheduleCron: declaration.scheduleCron ?? null,
+        incremental: declaration.incremental === undefined ? null : { mode: declaration.incremental.mode, fullPassCron: declaration.incremental.fullPassCron },
+        partitionFields: declaration.partitionUnitLocalField === undefined
+            ? null
+            : { unit: declaration.partitionUnitLocalField, key: declaration.partitionKeyLocalField ?? null },
+        mapping: declaration.mapping.map((entry) => ({
+            localField: entry.localField,
+            kind: entry.kind,
+            readsRemoteFields: listExternalDataMappingEntryRemoteFields(entry),
+            expression: describeMappingExpression(entry) + (bidirectional ? ` — owner ${resolveExternalDataFieldOwner(entry)}` : ''),
+            entry,
+        })),
+    };
+}
+//# sourceMappingURL=external-data-pipeline-description.shared.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-pipeline-description.shared.js","sourceRoot":"","sources":["../../../../src/external-data/external-data-pipeline-description.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A pipeline declaration, described for a READER (#1685) — the structured `externalDataPipeline` slice a resource\n * specification carries.\n *\n * ## Why it is derived, never authored\n *\n * Before this, a resource's specification described its pipeline in prose (Wonder Todos' `externalCustomers` did, in\n * `notes` and `businessConstraints`), and prose restating a declaration is a second copy that starts drifting the day\n * the declaration changes. So the slice is a FUNCTION of the declaration: `resourceSpecification()` attaches it when\n * it can materialize the resource configuration, and the companion's specification projection derives it from the\n * configuration it already holds. Nothing here is typed by an author, so nothing here can disagree with what runs.\n *\n * ## What it answers\n *\n * Where the rows come from (system, entity, dialect), which rows (the source filter, archived rows), how they are\n * keyed, when a pass runs, what happens to a row that leaves the source — and, per local field, WHAT writes it: the\n * remote fields it reads and the declared operation, including the four expressions (enum mapping, concatenation,\n * arithmetic, conditional). `expression` is a one-line rendering of that operation for a person reviewing the\n * specification; `entry` is the declared data itself, for a reader that needs the exact values.\n */\nimport {\n  ExternalDataConcatenationPartKind,\n  ExternalDataConditionalOutcomeKind,\n  ExternalDataFieldCoercion,\n  ExternalDataMappingEntryKind,\n  ExternalDataPipelineDirection,\n  ExternalDataUnmappedValuePolicy,\n  listExternalDataMappingEntryRemoteFields,\n  resolveExternalDataConflictPolicy,\n  resolveExternalDataFieldOwner,\n  type ExternalDataConditionalOutcome,\n  type ExternalDataFieldMappingEntry,\n  type ExternalDataPipelineDeclaration,\n} from './external-data-pipeline.shared.schemas';\n\n/** One local field the pipeline writes, and how. */\nexport interface ExternalDataPipelineMappingDescription {\n  readonly localField: string;\n  readonly kind: ExternalDataMappingEntryKind;\n  /** Every remote field this entry reads — what the extraction requests for it. Empty for a CONSTANT. */\n  readonly readsRemoteFields: readonly string[];\n  /** The declared operation in one line, for a reviewer. */\n  readonly expression: string;\n  /** The declared entry, exactly as the pipeline runs it. */\n  readonly entry: ExternalDataFieldMappingEntry;\n}\n\n/** The structured pipeline slice of a resource specification. */\nexport interface ExternalDataPipelineDescription {\n  /**\n   * Which way rows travel (#1690). For an OUTBOUND pipeline `source` names where rows are SENT, each mapping entry names\n   * the local field sent and the remote field it lands on, and the inbound-only facts (`population`, `orphanPolicy`,\n   * `sourceFilter`, `archivedRecords`, `incremental`) describe nothing and are null.\n   */\n  readonly direction: ExternalDataPipelineDirection;\n  readonly source: { readonly system: string; readonly entityRef: string; readonly dialect: string };\n  /** For an OUTBOUND or BIDIRECTIONAL pipeline, the write verbs it sends (`create`, `update`); empty for an inbound one. */\n  readonly sends: readonly string[];\n  /** A BIDIRECTIONAL pipeline's conflict policy (#1723), resolved; null for any other direction. */\n  readonly conflictPolicy: string | null;\n  /** The local field holding each row's remote identity, the key the load merges on. */\n  readonly remoteKeyLocalField: string;\n  readonly sourceFilter: Readonly<Record<string, unknown>> | null;\n  readonly population: string | null;\n  readonly orphanPolicy: string | null;\n  readonly archivedRecords: string | null;\n  readonly scheduleCron: string | null;\n  readonly incremental: { readonly mode: string; readonly fullPassCron: string } | null;\n  /** The partition stamps; an OUTBOUND pipeline has only the unit a created row is placed by (`key` null). */\n  readonly partitionFields: { readonly unit: string; readonly key: string | null } | null;\n  readonly mapping: readonly ExternalDataPipelineMappingDescription[];\n}\n\nconst quoted = (value: unknown): string => JSON.stringify(value);\n\nfunction describeOutcome(outcome: ExternalDataConditionalOutcome): string {\n  return outcome.kind === ExternalDataConditionalOutcomeKind.CONSTANT ? quoted(outcome.constant) : `\\`${outcome.remoteField}\\``;\n}\n\n/** The one-line rendering of one entry's operation. Total over the entry kinds. */\nfunction describeMappingExpression(entry: ExternalDataFieldMappingEntry): string {\n  switch (entry.kind) {\n    case ExternalDataMappingEntryKind.REMOTE_FIELD:\n      return `\\`${entry.remoteField}\\``\n        + (entry.coercion === ExternalDataFieldCoercion.NONE ? '' : ` (${entry.coercion})`)\n        + (entry.required ? ', required' : '');\n    case ExternalDataMappingEntryKind.CONSTANT:\n      return `constant ${quoted(entry.constant)}`;\n    case ExternalDataMappingEntryKind.REMOTE_REFERENCE:\n      return `foreign key to ${entry.targetResourceType} from \\`${entry.remoteField}\\``\n        + (entry.valueShape === undefined ? '' : ` (${entry.valueShape})`) + `, unresolved: ${entry.unresolved}`;\n    case ExternalDataMappingEntryKind.ENUM_MAP:\n      return `\\`${entry.remoteField}\\` mapped: `\n        + entry.values.map(({ remoteValue, localValue }) => `${quoted(remoteValue)} → ${quoted(localValue)}`).join(', ')\n        + `; unmapped: ${entry.unmapped.policy === ExternalDataUnmappedValuePolicy.USE_DEFAULT ? quoted(entry.unmapped.localValue) : 'reject the row'}`\n        + (entry.required ? ', required' : '');\n    case ExternalDataMappingEntryKind.CONCATENATION:\n      return 'concatenation of '\n        + entry.parts.map((part) => (part.kind === ExternalDataConcatenationPartKind.REMOTE_FIELD ? `\\`${part.remoteField}\\`` : quoted(part.literal))).join(', ')\n        + (entry.separator === '' ? '' : ` joined by ${quoted(entry.separator)}`)\n        + (entry.required ? ', required' : '');\n    case ExternalDataMappingEntryKind.ARITHMETIC:\n      return `\\`${entry.remoteField}\\` × ${entry.factor}${entry.offset === 0 ? '' : ` + ${entry.offset}`}`\n        + (entry.decimalPlaces === undefined ? '' : `, rounded to ${entry.decimalPlaces} decimal places`)\n        + (entry.required ? ', required' : '');\n    case ExternalDataMappingEntryKind.CONDITIONAL:\n      return `by \\`${entry.remoteField}\\`: `\n        + entry.cases.map((entryCase) => `${quoted(entryCase.equals)} → ${describeOutcome(entryCase.then)}`).join('; ')\n        + `; otherwise ${describeOutcome(entry.otherwise)}`;\n    default: {\n      const unhandled: never = entry;\n      throw new Error(`describeExternalDataPipeline: unhandled mapping entry ${quoted(unhandled)}`);\n    }\n  }\n}\n\n/** Describe a PARSED pipeline declaration for a resource specification (#1685). */\nexport function describeExternalDataPipeline(declaration: ExternalDataPipelineDeclaration): ExternalDataPipelineDescription {\n  const outbound = declaration.direction === ExternalDataPipelineDirection.OUTBOUND;\n  const bidirectional = declaration.direction === ExternalDataPipelineDirection.BIDIRECTIONAL;\n  return {\n    direction: declaration.direction,\n    source: { system: declaration.binding.system, entityRef: declaration.binding.entityRef, dialect: declaration.binding.dialect },\n    sends: outbound || bidirectional ? [...declaration.binding.writableVerbs].sort() : [],\n    conflictPolicy: bidirectional ? resolveExternalDataConflictPolicy(declaration) : null,\n    remoteKeyLocalField: declaration.remoteKeyLocalField,\n    sourceFilter: declaration.sourceFilter ?? null,\n    // Parsed defaults on an OUTBOUND declaration, which refuses them when authored: describing them would state a load\n    // policy for a pipeline that loads nothing.\n    population: outbound ? null : declaration.population,\n    orphanPolicy: outbound ? null : declaration.orphanPolicy,\n    archivedRecords: declaration.archivedRecords?.treatment ?? null,\n    scheduleCron: declaration.scheduleCron ?? null,\n    incremental: declaration.incremental === undefined ? null : { mode: declaration.incremental.mode, fullPassCron: declaration.incremental.fullPassCron },\n    partitionFields: declaration.partitionUnitLocalField === undefined\n      ? null\n      : { unit: declaration.partitionUnitLocalField, key: declaration.partitionKeyLocalField ?? null },\n    mapping: declaration.mapping.map((entry) => ({\n      localField: entry.localField,\n      kind: entry.kind,\n      readsRemoteFields: listExternalDataMappingEntryRemoteFields(entry),\n      expression: describeMappingExpression(entry) + (bidirectional ? ` — owner ${resolveExternalDataFieldOwner(entry)}` : ''),\n      entry,\n    })),\n  };\n}\n"]}

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

@@ -0,0 +1,154 @@
+/**
+ * The pipeline PASS-MODE vocabulary (#1682), in its own ROOT-exported module.
+ *
+ * Not beside the pipeline declaration on the `@wildo-ai/saas-models/external-data` subpath, because two
+ * ROOT-exported contracts carry it: the read-through audit event (`pipelinePassMode` on
+ * `AuditableEvent_HttpApiReadThroughAccess_EventDataSchema`) and, through saas-backend-lib's root, the
+ * pipeline run report. A nominal enum reached from a root contract must be nameable from the root
+ * (`package-public-entrypoints.md`), so the boundary moved here rather than the audit field weakening to
+ * a string.
+ */
+/**
+ * The two kinds of pass a pipeline runs (#1682) — and they answer different questions, which is why
+ * they are two tracks on the state row rather than one cursor.
+ *
+ * A FULL pass reads the whole remote population (in key order, possibly across many runs) and is the
+ * ONLY pass that may conclude a remote row was deleted: "absent from a complete read" is evidence of
+ * deletion, "absent from a read of what changed" is not. An INCREMENTAL pass reads only what changed
+ * since the pipeline's watermark, loads it, and never runs the orphan walk.
+ *
+ * A pipeline that declares no `incremental` runs full passes only, exactly as before.
+ */
+export declare enum ExternalDataPipelinePassMode {
+    FULL = "full",
+    INCREMENTAL = "incremental",
+    /**
+     * An OUTBOUND pipeline's pass (#1690): it reads no source and loads nothing — it SENDS the destination's owed local
+     * changes to the system of record. The only mode such a pipeline runs, and one an inbound pipeline never runs; asking
+     * for either of the other two on an outbound pipeline, or for this one on an inbound pipeline, is refused.
+     */
+    SEND = "send"
+}
+/**
+ * The `operationIdentifier` a pipeline RUN writes on its read-through audit row — the one value that tells a run's row
+ * apart from an ordinary read-through `read` / `list` / `count` / `search` of the same event type.
+ *
+ * Named because two parties must agree on it and neither owns the other: the run service writes it, and the erasure
+ * evidence requirement (`erasure-propagation-record` C5, #1746) selects the rows it sums `suppressedRows` over by it.
+ * A literal on each side would drift the day either was edited, and the collector would then sum nothing while
+ * reporting a clean window. Root-exported for the same reason the pass mode is.
+ */
+export declare const EXTERNAL_DATA_PIPELINE_RUN_OPERATION_IDENTIFIER = "externalDataPipelineRun";
+/**
+ * An operator's answer to an OUTBOUND write of unknown outcome (#2039), given through the admin door
+ * (`POST /internal/admin/external-data/outbound-changes/resolve`) by someone who LOOKED in the system of record. Root-exported
+ * for the pass mode's reason: the answer's audit event carries it.
+ *
+ * The pass never answers this itself. A write whose outcome is unknown may have landed, and for a CREATE, sending it
+ * again could make the record twice, so the change waits for someone who can see the system of record.
+ */
+export declare enum ExternalDataOutboundUnknownAnswer {
+    /**
+     * The write landed. For a CREATE the answer carries the remote key of the record found, and the engine writes it to
+     * the local row, so later edits reach that record as updates. The change is then settled as if it had been
+     * acknowledged, and a change made since is sent next.
+     */
+    APPLIED = "applied",
+    /** The write did not land: the change is sent again by the next pass, under a new Idempotency-Key. */
+    NOT_APPLIED = "not-applied"
+}
+/**
+ * Why the outbound resolution door refused an answer (#2039). Root-exported because it reaches a CLIENT: it is the
+ * stable `code` on the refusal, which a console or a script branches on — so it is named here, in the models every
+ * consumer can import, not inside the backend module that decides it. Each names what the operator must look at before
+ * answering again.
+ */
+export declare enum ExternalDataOutboundResolutionRefusal {
+    /** The row has no change of unknown outcome — answered already, settled by a pass, or never unknown. */
+    NO_UNKNOWN_CHANGE = "no-unknown-change",
+    /** An APPLIED answer to a CREATE must carry the remote key of the record found. */
+    REMOTE_KEY_REQUIRED = "remote-key-required",
+    /** A remote key only answers an applied CREATE; an update or a not-applied answer has no record to link. */
+    REMOTE_KEY_NOT_ACCEPTED = "remote-key-not-accepted",
+    /** The key is not one the binding's key fields can hold (its codec refused it, or it is a non-canonical alias). */
+    REMOTE_KEY_MALFORMED = "remote-key-malformed",
+    /**
+     * ANOTHER local row already holds that remote key. Linking a second row to the record would make each row's edits
+     * overwrite the other's — the one duplicate this door could create that the pass never can. Look again.
+     */
+    REMOTE_KEY_HELD_BY_ANOTHER_ROW = "remote-key-held-by-another-row",
+    /** The local row is gone: there is nothing to link the record to. */
+    ROW_GONE = "row-gone",
+    /** The local row is not the owner organization's — a pipeline never sends it, so no answer applies to it. */
+    ROW_NOT_OWNER_ORGANIZATION = "row-not-owner-organization",
+    /** The local row already holds a DIFFERENT remote key — the answer would re-point it. Look again. */
+    ROW_HOLDS_ANOTHER_KEY = "row-holds-another-key",
+    /**
+     * The create was answered NOT applied, but the row already holds a remote key — it is linked, so the create DID land
+     * (a pass or an earlier answer recorded it). Sending it again would contradict the row. Look again.
+     */
+    ROW_ALREADY_LINKED = "row-already-linked",
+    /** The change moved while it was being answered (a pass, another answer). Nothing was changed; list again. */
+    CHANGED_MEANWHILE = "changed-meanwhile"
+}
+/**
+ * What a BIDIRECTIONAL pipeline does with a row changed on BOTH sides since they last agreed (#1723) — declared per
+ * pipeline (`conflictPolicy`), and chosen per row by an operator for a conflict the pipeline refused. Root-exported for the
+ * pass mode's reason: the conflict's audit event carries it.
+ *
+ * Only fields BOTH sides own (`owner: BOTH`) can conflict: a field only the system of record owns is loaded, a field
+ * only the application owns is sent, and neither ever overwrites the other side's version of the same field.
+ */
+export declare enum ExternalDataConflictPolicy {
+    /** The system of record's values are loaded over the local ones; the local change to those fields is discarded. */
+    REMOTE_WINS = "remote-wins",
+    /** The local values are kept and sent over the system of record's; its change to those fields is discarded. */
+    LOCAL_WINS = "local-wins",
+    /**
+     * Neither side's BOTH-owned fields are touched: the row is reported as a conflict, and waits for an operator to choose
+     * REMOTE_WINS or LOCAL_WINS for it (`POST /internal/admin/external-data/outbound-changes/resolve`). The default —
+     * nothing is overwritten that nobody decided to overwrite. The row's REMOTE-owned fields still load: they cannot
+     * conflict, because nothing local writes them.
+     */
+    REFUSE_AND_REPORT = "refuse-and-report"
+}
+/**
+ * Which side's values a RESOLVED conflict kept (#1723) — the outcome, where {@link ExternalDataConflictPolicy} is the
+ * rule that chose it. What the conflict's audit row names. Root-exported for the same reason as the policy: the audit
+ * event carrying it is a root-exported contract.
+ */
+export declare enum ExternalDataConflictWinner {
+    /** The system of record's values were loaded over the local ones. */
+    REMOTE = "remote",
+    /** The local values were kept, and the next outbound pass sends them over the system of record's. */
+    LOCAL = "local"
+}
+/** Who chose a resolved conflict's winner (#1723). */
+export declare enum ExternalDataConflictDecisionSource {
+    /** The pipeline's declared `conflictPolicy`. */
+    DECLARED_POLICY = "declared-policy",
+    /** An operator's answer for this row, through the admin door, after the declared policy refused it. */
+    OPERATOR = "operator"
+}
+/**
+ * What the operator reset door (`POST /internal/admin/external-data/reset`, #1734) discards. Here, root-exported, for the
+ * pass mode's reason: the reset's audit event (`AuditableEvent_ExternalDataPipelineReset_EventDataSchema`) is a
+ * root-exported contract that carries it.
+ *
+ * The door exists because the run REFUSES, deliberately, on state it cannot trust — a state row with no checkpoint
+ * version, a malformed checkpoint, a membership journal that is cyclic or does not match its pass — and each refusal
+ * would otherwise repeat on every scheduled tick until someone edited rows by hand. A reset is the audited way past it.
+ */
+export declare enum ExternalDataPipelineResetMode {
+    /**
+     * Drop the FULL pass in flight — its cursor, its checkpoint and its membership journal. The next full run starts a new
+     * pass from the beginning. The incremental track (#1682), if any, is kept: its watermark is still a true position.
+     */
+    RESTART_PASS = "restart-pass",
+    /**
+     * Everything RESTART_PASS drops, and the incremental track too, so the next incremental pass re-reads the whole
+     * source. For a watermark that is no longer trusted — a restored source, a source whose change timestamps moved.
+     */
+    FULL_RESYNC = "full-resync"
+}
+//# sourceMappingURL=external-data-pipeline-pass-mode.shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-pipeline-pass-mode.shared.d.ts","sourceRoot":"","sources":["../../../../src/external-data/external-data-pipeline-pass-mode.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,oBAAY,4BAA4B;IACtC,IAAI,SAAS;IACb,WAAW,gBAAgB;IAC3B;;;;OAIG;IACH,IAAI,SAAS;CACd;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+CAA+C,4BAA4B,CAAC;AAEzF;;;;;;;GAOG;AACH,oBAAY,iCAAiC;IAC3C;;;;OAIG;IACH,OAAO,YAAY;IACnB,sGAAsG;IACtG,WAAW,gBAAgB;CAC5B;AAED;;;;;GAKG;AACH,oBAAY,qCAAqC;IAC/C,wGAAwG;IACxG,iBAAiB,sBAAsB;IACvC,mFAAmF;IACnF,mBAAmB,wBAAwB;IAC3C,4GAA4G;IAC5G,uBAAuB,4BAA4B;IACnD,mHAAmH;IACnH,oBAAoB,yBAAyB;IAC7C;;;OAGG;IACH,8BAA8B,mCAAmC;IACjE,qEAAqE;IACrE,QAAQ,aAAa;IACrB,6GAA6G;IAC7G,0BAA0B,+BAA+B;IACzD,qGAAqG;IACrG,qBAAqB,0BAA0B;IAC/C;;;OAGG;IACH,kBAAkB,uBAAuB;IACzC,8GAA8G;IAC9G,iBAAiB,sBAAsB;CACxC;AAED;;;;;;;GAOG;AACH,oBAAY,0BAA0B;IACpC,mHAAmH;IACnH,WAAW,gBAAgB;IAC3B,+GAA+G;IAC/G,UAAU,eAAe;IACzB;;;;;OAKG;IACH,iBAAiB,sBAAsB;CACxC;AAED;;;;GAIG;AACH,oBAAY,0BAA0B;IACpC,qEAAqE;IACrE,MAAM,WAAW;IACjB,qGAAqG;IACrG,KAAK,UAAU;CAChB;AAED,sDAAsD;AACtD,oBAAY,kCAAkC;IAC5C,gDAAgD;IAChD,eAAe,oBAAoB;IACnC,uGAAuG;IACvG,QAAQ,aAAa;CACtB;AAED;;;;;;;;GAQG;AACH,oBAAY,6BAA6B;IACvC;;;OAGG;IACH,YAAY,iBAAiB;IAC7B;;;OAGG;IACH,WAAW,gBAAgB;CAC5B"}

package/dist/esm/external-data/external-data-pipeline-pass-mode.shared.js

@@ -0,0 +1,161 @@
+/**
+ * The pipeline PASS-MODE vocabulary (#1682), in its own ROOT-exported module.
+ *
+ * Not beside the pipeline declaration on the `@wildo-ai/saas-models/external-data` subpath, because two
+ * ROOT-exported contracts carry it: the read-through audit event (`pipelinePassMode` on
+ * `AuditableEvent_HttpApiReadThroughAccess_EventDataSchema`) and, through saas-backend-lib's root, the
+ * pipeline run report. A nominal enum reached from a root contract must be nameable from the root
+ * (`package-public-entrypoints.md`), so the boundary moved here rather than the audit field weakening to
+ * a string.
+ */
+/**
+ * The two kinds of pass a pipeline runs (#1682) — and they answer different questions, which is why
+ * they are two tracks on the state row rather than one cursor.
+ *
+ * A FULL pass reads the whole remote population (in key order, possibly across many runs) and is the
+ * ONLY pass that may conclude a remote row was deleted: "absent from a complete read" is evidence of
+ * deletion, "absent from a read of what changed" is not. An INCREMENTAL pass reads only what changed
+ * since the pipeline's watermark, loads it, and never runs the orphan walk.
+ *
+ * A pipeline that declares no `incremental` runs full passes only, exactly as before.
+ */
+export var ExternalDataPipelinePassMode;
+(function (ExternalDataPipelinePassMode) {
+    ExternalDataPipelinePassMode["FULL"] = "full";
+    ExternalDataPipelinePassMode["INCREMENTAL"] = "incremental";
+    /**
+     * An OUTBOUND pipeline's pass (#1690): it reads no source and loads nothing — it SENDS the destination's owed local
+     * changes to the system of record. The only mode such a pipeline runs, and one an inbound pipeline never runs; asking
+     * for either of the other two on an outbound pipeline, or for this one on an inbound pipeline, is refused.
+     */
+    ExternalDataPipelinePassMode["SEND"] = "send";
+})(ExternalDataPipelinePassMode || (ExternalDataPipelinePassMode = {}));
+/**
+ * The `operationIdentifier` a pipeline RUN writes on its read-through audit row — the one value that tells a run's row
+ * apart from an ordinary read-through `read` / `list` / `count` / `search` of the same event type.
+ *
+ * Named because two parties must agree on it and neither owns the other: the run service writes it, and the erasure
+ * evidence requirement (`erasure-propagation-record` C5, #1746) selects the rows it sums `suppressedRows` over by it.
+ * A literal on each side would drift the day either was edited, and the collector would then sum nothing while
+ * reporting a clean window. Root-exported for the same reason the pass mode is.
+ */
+export const EXTERNAL_DATA_PIPELINE_RUN_OPERATION_IDENTIFIER = 'externalDataPipelineRun';
+/**
+ * An operator's answer to an OUTBOUND write of unknown outcome (#2039), given through the admin door
+ * (`POST /internal/admin/external-data/outbound-changes/resolve`) by someone who LOOKED in the system of record. Root-exported
+ * for the pass mode's reason: the answer's audit event carries it.
+ *
+ * The pass never answers this itself. A write whose outcome is unknown may have landed, and for a CREATE, sending it
+ * again could make the record twice, so the change waits for someone who can see the system of record.
+ */
+export var ExternalDataOutboundUnknownAnswer;
+(function (ExternalDataOutboundUnknownAnswer) {
+    /**
+     * The write landed. For a CREATE the answer carries the remote key of the record found, and the engine writes it to
+     * the local row, so later edits reach that record as updates. The change is then settled as if it had been
+     * acknowledged, and a change made since is sent next.
+     */
+    ExternalDataOutboundUnknownAnswer["APPLIED"] = "applied";
+    /** The write did not land: the change is sent again by the next pass, under a new Idempotency-Key. */
+    ExternalDataOutboundUnknownAnswer["NOT_APPLIED"] = "not-applied";
+})(ExternalDataOutboundUnknownAnswer || (ExternalDataOutboundUnknownAnswer = {}));
+/**
+ * Why the outbound resolution door refused an answer (#2039). Root-exported because it reaches a CLIENT: it is the
+ * stable `code` on the refusal, which a console or a script branches on — so it is named here, in the models every
+ * consumer can import, not inside the backend module that decides it. Each names what the operator must look at before
+ * answering again.
+ */
+export var ExternalDataOutboundResolutionRefusal;
+(function (ExternalDataOutboundResolutionRefusal) {
+    /** The row has no change of unknown outcome — answered already, settled by a pass, or never unknown. */
+    ExternalDataOutboundResolutionRefusal["NO_UNKNOWN_CHANGE"] = "no-unknown-change";
+    /** An APPLIED answer to a CREATE must carry the remote key of the record found. */
+    ExternalDataOutboundResolutionRefusal["REMOTE_KEY_REQUIRED"] = "remote-key-required";
+    /** A remote key only answers an applied CREATE; an update or a not-applied answer has no record to link. */
+    ExternalDataOutboundResolutionRefusal["REMOTE_KEY_NOT_ACCEPTED"] = "remote-key-not-accepted";
+    /** The key is not one the binding's key fields can hold (its codec refused it, or it is a non-canonical alias). */
+    ExternalDataOutboundResolutionRefusal["REMOTE_KEY_MALFORMED"] = "remote-key-malformed";
+    /**
+     * ANOTHER local row already holds that remote key. Linking a second row to the record would make each row's edits
+     * overwrite the other's — the one duplicate this door could create that the pass never can. Look again.
+     */
+    ExternalDataOutboundResolutionRefusal["REMOTE_KEY_HELD_BY_ANOTHER_ROW"] = "remote-key-held-by-another-row";
+    /** The local row is gone: there is nothing to link the record to. */
+    ExternalDataOutboundResolutionRefusal["ROW_GONE"] = "row-gone";
+    /** The local row is not the owner organization's — a pipeline never sends it, so no answer applies to it. */
+    ExternalDataOutboundResolutionRefusal["ROW_NOT_OWNER_ORGANIZATION"] = "row-not-owner-organization";
+    /** The local row already holds a DIFFERENT remote key — the answer would re-point it. Look again. */
+    ExternalDataOutboundResolutionRefusal["ROW_HOLDS_ANOTHER_KEY"] = "row-holds-another-key";
+    /**
+     * The create was answered NOT applied, but the row already holds a remote key — it is linked, so the create DID land
+     * (a pass or an earlier answer recorded it). Sending it again would contradict the row. Look again.
+     */
+    ExternalDataOutboundResolutionRefusal["ROW_ALREADY_LINKED"] = "row-already-linked";
+    /** The change moved while it was being answered (a pass, another answer). Nothing was changed; list again. */
+    ExternalDataOutboundResolutionRefusal["CHANGED_MEANWHILE"] = "changed-meanwhile";
+})(ExternalDataOutboundResolutionRefusal || (ExternalDataOutboundResolutionRefusal = {}));
+/**
+ * What a BIDIRECTIONAL pipeline does with a row changed on BOTH sides since they last agreed (#1723) — declared per
+ * pipeline (`conflictPolicy`), and chosen per row by an operator for a conflict the pipeline refused. Root-exported for the
+ * pass mode's reason: the conflict's audit event carries it.
+ *
+ * Only fields BOTH sides own (`owner: BOTH`) can conflict: a field only the system of record owns is loaded, a field
+ * only the application owns is sent, and neither ever overwrites the other side's version of the same field.
+ */
+export var ExternalDataConflictPolicy;
+(function (ExternalDataConflictPolicy) {
+    /** The system of record's values are loaded over the local ones; the local change to those fields is discarded. */
+    ExternalDataConflictPolicy["REMOTE_WINS"] = "remote-wins";
+    /** The local values are kept and sent over the system of record's; its change to those fields is discarded. */
+    ExternalDataConflictPolicy["LOCAL_WINS"] = "local-wins";
+    /**
+     * Neither side's BOTH-owned fields are touched: the row is reported as a conflict, and waits for an operator to choose
+     * REMOTE_WINS or LOCAL_WINS for it (`POST /internal/admin/external-data/outbound-changes/resolve`). The default —
+     * nothing is overwritten that nobody decided to overwrite. The row's REMOTE-owned fields still load: they cannot
+     * conflict, because nothing local writes them.
+     */
+    ExternalDataConflictPolicy["REFUSE_AND_REPORT"] = "refuse-and-report";
+})(ExternalDataConflictPolicy || (ExternalDataConflictPolicy = {}));
+/**
+ * Which side's values a RESOLVED conflict kept (#1723) — the outcome, where {@link ExternalDataConflictPolicy} is the
+ * rule that chose it. What the conflict's audit row names. Root-exported for the same reason as the policy: the audit
+ * event carrying it is a root-exported contract.
+ */
+export var ExternalDataConflictWinner;
+(function (ExternalDataConflictWinner) {
+    /** The system of record's values were loaded over the local ones. */
+    ExternalDataConflictWinner["REMOTE"] = "remote";
+    /** The local values were kept, and the next outbound pass sends them over the system of record's. */
+    ExternalDataConflictWinner["LOCAL"] = "local";
+})(ExternalDataConflictWinner || (ExternalDataConflictWinner = {}));
+/** Who chose a resolved conflict's winner (#1723). */
+export var ExternalDataConflictDecisionSource;
+(function (ExternalDataConflictDecisionSource) {
+    /** The pipeline's declared `conflictPolicy`. */
+    ExternalDataConflictDecisionSource["DECLARED_POLICY"] = "declared-policy";
+    /** An operator's answer for this row, through the admin door, after the declared policy refused it. */
+    ExternalDataConflictDecisionSource["OPERATOR"] = "operator";
+})(ExternalDataConflictDecisionSource || (ExternalDataConflictDecisionSource = {}));
+/**
+ * What the operator reset door (`POST /internal/admin/external-data/reset`, #1734) discards. Here, root-exported, for the
+ * pass mode's reason: the reset's audit event (`AuditableEvent_ExternalDataPipelineReset_EventDataSchema`) is a
+ * root-exported contract that carries it.
+ *
+ * The door exists because the run REFUSES, deliberately, on state it cannot trust — a state row with no checkpoint
+ * version, a malformed checkpoint, a membership journal that is cyclic or does not match its pass — and each refusal
+ * would otherwise repeat on every scheduled tick until someone edited rows by hand. A reset is the audited way past it.
+ */
+export var ExternalDataPipelineResetMode;
+(function (ExternalDataPipelineResetMode) {
+    /**
+     * Drop the FULL pass in flight — its cursor, its checkpoint and its membership journal. The next full run starts a new
+     * pass from the beginning. The incremental track (#1682), if any, is kept: its watermark is still a true position.
+     */
+    ExternalDataPipelineResetMode["RESTART_PASS"] = "restart-pass";
+    /**
+     * Everything RESTART_PASS drops, and the incremental track too, so the next incremental pass re-reads the whole
+     * source. For a watermark that is no longer trusted — a restored source, a source whose change timestamps moved.
+     */
+    ExternalDataPipelineResetMode["FULL_RESYNC"] = "full-resync";
+})(ExternalDataPipelineResetMode || (ExternalDataPipelineResetMode = {}));
+//# sourceMappingURL=external-data-pipeline-pass-mode.shared.js.map