@wildo-ai/saas-models 1.1.5 → 1.1.7

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-pipeline-pass-mode.shared.js","sourceRoot":"","sources":["../../../src/external-data/external-data-pipeline-pass-mode.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAN,IAAY,4BASX;AATD,WAAY,4BAA4B;IACtC,6CAAa,CAAA;IACb,2DAA2B,CAAA;IAC3B;;;;OAIG;IACH,6CAAa,CAAA;AACf,CAAC,EATW,4BAA4B,KAA5B,4BAA4B,QASvC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,+CAA+C,GAAG,yBAAyB,CAAC;AAEzF;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,iCASX;AATD,WAAY,iCAAiC;IAC3C;;;;OAIG;IACH,wDAAmB,CAAA;IACnB,sGAAsG;IACtG,gEAA2B,CAAA;AAC7B,CAAC,EATW,iCAAiC,KAAjC,iCAAiC,QAS5C;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,qCA2BX;AA3BD,WAAY,qCAAqC;IAC/C,wGAAwG;IACxG,gFAAuC,CAAA;IACvC,mFAAmF;IACnF,oFAA2C,CAAA;IAC3C,4GAA4G;IAC5G,4FAAmD,CAAA;IACnD,mHAAmH;IACnH,sFAA6C,CAAA;IAC7C;;;OAGG;IACH,0GAAiE,CAAA;IACjE,qEAAqE;IACrE,8DAAqB,CAAA;IACrB,6GAA6G;IAC7G,kGAAyD,CAAA;IACzD,qGAAqG;IACrG,wFAA+C,CAAA;IAC/C;;;OAGG;IACH,kFAAyC,CAAA;IACzC,8GAA8G;IAC9G,gFAAuC,CAAA;AACzC,CAAC,EA3BW,qCAAqC,KAArC,qCAAqC,QA2BhD;AAED;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,0BAYX;AAZD,WAAY,0BAA0B;IACpC,mHAAmH;IACnH,yDAA2B,CAAA;IAC3B,+GAA+G;IAC/G,uDAAyB,CAAA;IACzB;;;;;OAKG;IACH,qEAAuC,CAAA;AACzC,CAAC,EAZW,0BAA0B,KAA1B,0BAA0B,QAYrC;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,0BAKX;AALD,WAAY,0BAA0B;IACpC,qEAAqE;IACrE,+CAAiB,CAAA;IACjB,qGAAqG;IACrG,6CAAe,CAAA;AACjB,CAAC,EALW,0BAA0B,KAA1B,0BAA0B,QAKrC;AAED,sDAAsD;AACtD,MAAM,CAAN,IAAY,kCAKX;AALD,WAAY,kCAAkC;IAC5C,gDAAgD;IAChD,yEAAmC,CAAA;IACnC,uGAAuG;IACvG,2DAAqB,CAAA;AACvB,CAAC,EALW,kCAAkC,KAAlC,kCAAkC,QAK7C;AAED;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,6BAWX;AAXD,WAAY,6BAA6B;IACvC;;;OAGG;IACH,8DAA6B,CAAA;IAC7B;;;OAGG;IACH,4DAA2B,CAAA;AAC7B,CAAC,EAXW,6BAA6B,KAA7B,6BAA6B,QAWxC","sourcesContent":["/**\n * The pipeline PASS-MODE vocabulary (#1682), in its own ROOT-exported module.\n *\n * Not beside the pipeline declaration on the `@wildo-ai/saas-models/external-data` subpath, because two\n * ROOT-exported contracts carry it: the read-through audit event (`pipelinePassMode` on\n * `AuditableEvent_HttpApiReadThroughAccess_EventDataSchema`) and, through saas-backend-lib's root, the\n * pipeline run report. A nominal enum reached from a root contract must be nameable from the root\n * (`package-public-entrypoints.md`), so the boundary moved here rather than the audit field weakening to\n * a string.\n */\n\n/**\n * The two kinds of pass a pipeline runs (#1682) — and they answer different questions, which is why\n * they are two tracks on the state row rather than one cursor.\n *\n * A FULL pass reads the whole remote population (in key order, possibly across many runs) and is the\n * ONLY pass that may conclude a remote row was deleted: \"absent from a complete read\" is evidence of\n * deletion, \"absent from a read of what changed\" is not. An INCREMENTAL pass reads only what changed\n * since the pipeline's watermark, loads it, and never runs the orphan walk.\n *\n * A pipeline that declares no `incremental` runs full passes only, exactly as before.\n */\nexport enum ExternalDataPipelinePassMode {\n  FULL = 'full',\n  INCREMENTAL = 'incremental',\n  /**\n   * An OUTBOUND pipeline's pass (#1690): it reads no source and loads nothing — it SENDS the destination's owed local\n   * changes to the system of record. The only mode such a pipeline runs, and one an inbound pipeline never runs; asking\n   * for either of the other two on an outbound pipeline, or for this one on an inbound pipeline, is refused.\n   */\n  SEND = 'send',\n}\n\n/**\n * The `operationIdentifier` a pipeline RUN writes on its read-through audit row — the one value that tells a run's row\n * apart from an ordinary read-through `read` / `list` / `count` / `search` of the same event type.\n *\n * Named because two parties must agree on it and neither owns the other: the run service writes it, and the erasure\n * evidence requirement (`erasure-propagation-record` C5, #1746) selects the rows it sums `suppressedRows` over by it.\n * A literal on each side would drift the day either was edited, and the collector would then sum nothing while\n * reporting a clean window. Root-exported for the same reason the pass mode is.\n */\nexport const EXTERNAL_DATA_PIPELINE_RUN_OPERATION_IDENTIFIER = 'externalDataPipelineRun';\n\n/**\n * An operator's answer to an OUTBOUND write of unknown outcome (#2039), given through the admin door\n * (`POST /internal/admin/external-data/outbound-changes/resolve`) by someone who LOOKED in the system of record. Root-exported\n * for the pass mode's reason: the answer's audit event carries it.\n *\n * The pass never answers this itself. A write whose outcome is unknown may have landed, and for a CREATE, sending it\n * again could make the record twice, so the change waits for someone who can see the system of record.\n */\nexport enum ExternalDataOutboundUnknownAnswer {\n  /**\n   * The write landed. For a CREATE the answer carries the remote key of the record found, and the engine writes it to\n   * the local row, so later edits reach that record as updates. The change is then settled as if it had been\n   * acknowledged, and a change made since is sent next.\n   */\n  APPLIED = 'applied',\n  /** The write did not land: the change is sent again by the next pass, under a new Idempotency-Key. */\n  NOT_APPLIED = 'not-applied',\n}\n\n/**\n * Why the outbound resolution door refused an answer (#2039). Root-exported because it reaches a CLIENT: it is the\n * stable `code` on the refusal, which a console or a script branches on — so it is named here, in the models every\n * consumer can import, not inside the backend module that decides it. Each names what the operator must look at before\n * answering again.\n */\nexport enum ExternalDataOutboundResolutionRefusal {\n  /** The row has no change of unknown outcome — answered already, settled by a pass, or never unknown. */\n  NO_UNKNOWN_CHANGE = 'no-unknown-change',\n  /** An APPLIED answer to a CREATE must carry the remote key of the record found. */\n  REMOTE_KEY_REQUIRED = 'remote-key-required',\n  /** A remote key only answers an applied CREATE; an update or a not-applied answer has no record to link. */\n  REMOTE_KEY_NOT_ACCEPTED = 'remote-key-not-accepted',\n  /** The key is not one the binding's key fields can hold (its codec refused it, or it is a non-canonical alias). */\n  REMOTE_KEY_MALFORMED = 'remote-key-malformed',\n  /**\n   * ANOTHER local row already holds that remote key. Linking a second row to the record would make each row's edits\n   * overwrite the other's — the one duplicate this door could create that the pass never can. Look again.\n   */\n  REMOTE_KEY_HELD_BY_ANOTHER_ROW = 'remote-key-held-by-another-row',\n  /** The local row is gone: there is nothing to link the record to. */\n  ROW_GONE = 'row-gone',\n  /** The local row is not the owner organization's — a pipeline never sends it, so no answer applies to it. */\n  ROW_NOT_OWNER_ORGANIZATION = 'row-not-owner-organization',\n  /** The local row already holds a DIFFERENT remote key — the answer would re-point it. Look again. */\n  ROW_HOLDS_ANOTHER_KEY = 'row-holds-another-key',\n  /**\n   * The create was answered NOT applied, but the row already holds a remote key — it is linked, so the create DID land\n   * (a pass or an earlier answer recorded it). Sending it again would contradict the row. Look again.\n   */\n  ROW_ALREADY_LINKED = 'row-already-linked',\n  /** The change moved while it was being answered (a pass, another answer). Nothing was changed; list again. */\n  CHANGED_MEANWHILE = 'changed-meanwhile',\n}\n\n/**\n * What a BIDIRECTIONAL pipeline does with a row changed on BOTH sides since they last agreed (#1723) — declared per\n * pipeline (`conflictPolicy`), and chosen per row by an operator for a conflict the pipeline refused. Root-exported for the\n * pass mode's reason: the conflict's audit event carries it.\n *\n * Only fields BOTH sides own (`owner: BOTH`) can conflict: a field only the system of record owns is loaded, a field\n * only the application owns is sent, and neither ever overwrites the other side's version of the same field.\n */\nexport enum ExternalDataConflictPolicy {\n  /** The system of record's values are loaded over the local ones; the local change to those fields is discarded. */\n  REMOTE_WINS = 'remote-wins',\n  /** The local values are kept and sent over the system of record's; its change to those fields is discarded. */\n  LOCAL_WINS = 'local-wins',\n  /**\n   * Neither side's BOTH-owned fields are touched: the row is reported as a conflict, and waits for an operator to choose\n   * REMOTE_WINS or LOCAL_WINS for it (`POST /internal/admin/external-data/outbound-changes/resolve`). The default —\n   * nothing is overwritten that nobody decided to overwrite. The row's REMOTE-owned fields still load: they cannot\n   * conflict, because nothing local writes them.\n   */\n  REFUSE_AND_REPORT = 'refuse-and-report',\n}\n\n/**\n * Which side's values a RESOLVED conflict kept (#1723) — the outcome, where {@link ExternalDataConflictPolicy} is the\n * rule that chose it. What the conflict's audit row names. Root-exported for the same reason as the policy: the audit\n * event carrying it is a root-exported contract.\n */\nexport enum ExternalDataConflictWinner {\n  /** The system of record's values were loaded over the local ones. */\n  REMOTE = 'remote',\n  /** The local values were kept, and the next outbound pass sends them over the system of record's. */\n  LOCAL = 'local',\n}\n\n/** Who chose a resolved conflict's winner (#1723). */\nexport enum ExternalDataConflictDecisionSource {\n  /** The pipeline's declared `conflictPolicy`. */\n  DECLARED_POLICY = 'declared-policy',\n  /** An operator's answer for this row, through the admin door, after the declared policy refused it. */\n  OPERATOR = 'operator',\n}\n\n/**\n * What the operator reset door (`POST /internal/admin/external-data/reset`, #1734) discards. Here, root-exported, for the\n * pass mode's reason: the reset's audit event (`AuditableEvent_ExternalDataPipelineReset_EventDataSchema`) is a\n * root-exported contract that carries it.\n *\n * The door exists because the run REFUSES, deliberately, on state it cannot trust — a state row with no checkpoint\n * version, a malformed checkpoint, a membership journal that is cyclic or does not match its pass — and each refusal\n * would otherwise repeat on every scheduled tick until someone edited rows by hand. A reset is the audited way past it.\n */\nexport enum ExternalDataPipelineResetMode {\n  /**\n   * Drop the FULL pass in flight — its cursor, its checkpoint and its membership journal. The next full run starts a new\n   * pass from the beginning. The incremental track (#1682), if any, is kept: its watermark is still a true position.\n   */\n  RESTART_PASS = 'restart-pass',\n  /**\n   * Everything RESTART_PASS drops, and the incremental track too, so the next incremental pass re-reads the whole\n   * source. For a watermark that is no longer trusted — a restored source, a source whose change timestamps moved.\n   */\n  FULL_RESYNC = 'full-resync',\n}\n"]}