@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/errors/utils/rate-limit-environment-relaxation.backend.utils.d.ts

@@ -80,4 +80,37 @@ export declare function resolveRateLimitEnvironmentMultiplier(applicationEnv: Ru
  * @returns `authoredMax` in `STAGING` / `PRODUCTION`; the relaxed ceiling otherwise.
  */
 export declare function relaxAbuseThrottleMaxForEnvironment(authoredMax: number, applicationEnv: RuntimeEnvironment): number;
+/**
+ * Every abuse throttle this relaxation reaches, named so the boot announcement can list them (#499).
+ *
+ * A line saying "abuse limits relaxed" would be accurate and still misleading: an operator would
+ * reasonably read it as ALL of them, and it is not — a counter whose maximum is a product or tenant
+ * policy is deliberately untouched, as is any counter used as an audit de-duplication window (see the
+ * module header). Naming the reached set is what makes the announcement actionable rather than
+ * atmospheric.
+ *
+ * Maintained by hand against the import sites, which is a list re-stating another file's population —
+ * exactly the shape `invariant-call-site-enumeration.md` warns about. It is tolerable ONLY because it
+ * feeds a log line rather than a decision: a stale entry here misinforms an operator, it does not
+ * change a ceiling. Keep it in step when a site is added, and prefer deleting it over letting it rot.
+ */
+export declare const RELAXED_ABUSE_THROTTLE_SITES: readonly string[];
+/** What a boot announcement should say, or `null` when the environment relaxes nothing. */
+export interface AbuseThrottleRelaxationAnnouncement {
+    readonly applicationEnv: RuntimeEnvironment;
+    readonly multiplier: number;
+    readonly relaxedSites: readonly string[];
+}
+/**
+ * Describe the relaxation in force, for an unmissable line at startup (#499).
+ *
+ * The relaxation is keyed on the resolved environment and nothing else — a deliberate decision, so
+ * there is one source of truth for "what kind of host is this" rather than a second flag that can
+ * disagree with it. The residual risk is that a host which merely REPORTS development (a demonstration
+ * box, a staging-like environment mis-declared) runs with maxima multiplied by a thousand. That risk is
+ * accepted, and this function is the whole of what makes it visible instead of silent.
+ *
+ * Returns `null` in `STAGING` / `PRODUCTION`, so a caller logs nothing where nothing is relaxed.
+ */
+export declare function describeAbuseThrottleRelaxation(applicationEnv: RuntimeEnvironment): AbuseThrottleRelaxationAnnouncement | null;
 //# sourceMappingURL=rate-limit-environment-relaxation.backend.utils.d.ts.map

package/dist/esm/errors/utils/rate-limit-environment-relaxation.backend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit-environment-relaxation.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/errors/utils/rate-limit-environment-relaxation.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC,OAAO,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,cAAc,EAAE,kBAAkB,GAAG,MAAM,CAIhG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mCAAmC,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,kBAAkB,GAAG,MAAM,CAEnH"}
+{"version":3,"file":"rate-limit-environment-relaxation.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/errors/utils/rate-limit-environment-relaxation.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC,OAAO,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,cAAc,EAAE,kBAAkB,GAAG,MAAM,CAIhG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mCAAmC,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,kBAAkB,GAAG,MAAM,CAEnH;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,MAAM,EAQzD,CAAC;AAEF,2FAA2F;AAC3F,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAC7C,cAAc,EAAE,kBAAkB,GACjC,mCAAmC,GAAG,IAAI,CAK5C"}

package/dist/esm/errors/utils/rate-limit-environment-relaxation.backend.utils.js

@@ -86,4 +86,44 @@ export function resolveRateLimitEnvironmentMultiplier(applicationEnv) {
 export function relaxAbuseThrottleMaxForEnvironment(authoredMax, applicationEnv) {
     return authoredMax * resolveRateLimitEnvironmentMultiplier(applicationEnv);
 }
+/**
+ * Every abuse throttle this relaxation reaches, named so the boot announcement can list them (#499).
+ *
+ * A line saying "abuse limits relaxed" would be accurate and still misleading: an operator would
+ * reasonably read it as ALL of them, and it is not — a counter whose maximum is a product or tenant
+ * policy is deliberately untouched, as is any counter used as an audit de-duplication window (see the
+ * module header). Naming the reached set is what makes the announcement actionable rather than
+ * atmospheric.
+ *
+ * Maintained by hand against the import sites, which is a list re-stating another file's population —
+ * exactly the shape `invariant-call-site-enumeration.md` warns about. It is tolerable ONLY because it
+ * feeds a log line rather than a decision: a stale entry here misinforms an operator, it does not
+ * change a ceiling. Keep it in step when a site is added, and prefer deleting it over letting it rot.
+ */
+export const RELAXED_ABUSE_THROTTLE_SITES = [
+    'HTTP perimeter limiter',
+    'WebSocket per-event limiter',
+    'machine-credential failure guard',
+    'external-turn throttle (A2A / MCP)',
+    'authorization-denial audit sampler',
+    'webhook endpoint-test cap',
+    'rate-limit policy service',
+];
+/**
+ * Describe the relaxation in force, for an unmissable line at startup (#499).
+ *
+ * The relaxation is keyed on the resolved environment and nothing else — a deliberate decision, so
+ * there is one source of truth for "what kind of host is this" rather than a second flag that can
+ * disagree with it. The residual risk is that a host which merely REPORTS development (a demonstration
+ * box, a staging-like environment mis-declared) runs with maxima multiplied by a thousand. That risk is
+ * accepted, and this function is the whole of what makes it visible instead of silent.
+ *
+ * Returns `null` in `STAGING` / `PRODUCTION`, so a caller logs nothing where nothing is relaxed.
+ */
+export function describeAbuseThrottleRelaxation(applicationEnv) {
+    const multiplier = resolveRateLimitEnvironmentMultiplier(applicationEnv);
+    return multiplier === 1
+        ? null
+        : { applicationEnv, multiplier, relaxedSites: RELAXED_ABUSE_THROTTLE_SITES };
+}
 //# sourceMappingURL=rate-limit-environment-relaxation.backend.utils.js.map

package/dist/esm/errors/utils/rate-limit-environment-relaxation.backend.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit-environment-relaxation.backend.utils.js","sourceRoot":"","sources":["../../../../../src/errors/utils/rate-limit-environment-relaxation.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,IAAI,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,UAAU,qCAAqC,CAAC,cAAkC;IACtF,OAAO,cAAc,KAAK,kBAAkB,CAAC,WAAW,IAAI,cAAc,KAAK,kBAAkB,CAAC,IAAI;QACpG,CAAC,CAAC,oCAAoC;QACtC,CAAC,CAAC,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mCAAmC,CAAC,WAAmB,EAAE,cAAkC;IACzG,OAAO,WAAW,GAAG,qCAAqC,CAAC,cAAc,CAAC,CAAC;AAC7E,CAAC","sourcesContent":["/**\n * Non-production relaxation of ABUSE-THROTTLE maxima — the single seam.\n *\n * ## Why this module exists\n *\n * Every rate-limit maximum in the engine is authored for a PRODUCTION threat model\n * (credential stuffing, registration spam, enumeration, LLM-spend abuse, unmetered\n * egress). Applied unchanged, those same numbers turn ordinary local development and\n * automated e2e/integration runs — which legitimately fire the same endpoint from the\n * same IP, the same email and the same principal dozens of times in seconds — into a\n * 429 flood.\n *\n * The relaxation used to live as a private constant inside\n * `RateLimitBackendService`, so it reached only that service's three surfaces\n * (`checkRateLimit`, `checkPolicy`, `checkPolicyForVariant`). Five other enforcement\n * sites carry their own hard-coded maxima and never saw it. The one that hurt most in\n * practice was the machine-credential failure guard\n * (`assertMachineAuthAttemptWithinRate`, 50 failures / 600 s / source IP): on a dev\n * machine every process shares `127.0.0.1`, so fifty failed `sk_*` / `oc_*`\n * presentations from ANY source lock out every machine-credential path for ten\n * minutes — including the ones a developer is actively debugging.\n *\n * This module is that single seam. Import it at every abuse-throttle site rather than\n * re-deriving an environment branch locally; a second copy of the branch is how the\n * first one drifted (see `.claude/rules/invariant-call-site-enumeration.md`).\n *\n * ## What it deliberately does NOT do\n *\n * - **It does not bypass enforcement.** The counters still increment through the real\n *   Redis `INCR` + `EXPIRE` path, so a genuine regression (windows not incrementing,\n *   keys colliding, TTL never set) still reproduces locally. Only the ceiling moves.\n * - **It does not touch `STAGING` / `PRODUCTION`.** {@link resolveRateLimitEnvironmentMultiplier}\n *   returns `1` for every environment other than `DEVELOPMENT` and `TEST`, so the\n *   authored number IS the enforced number wherever the threat model is real.\n * - **It must not be applied to business-semantic counters.** A counter whose maximum\n *   is a product or tenant policy — SSO grace logins (`enforcement.graceLoginAttempts`),\n *   trial quotas, plan entitlements — is not an abuse throttle. Multiplying it would\n *   change observable product behavior in dev/test and make local runs disagree with\n *   production semantics, which is the opposite of what this exists for. The same goes\n *   for counters used as audit/log DE-DUPLICATION windows (the authorization-denial\n *   audit sampler, the SAML assertion warning de-dup): relaxing those produces an\n *   audit/log flood, not headroom.\n *\n * @see `.claude/rules/invariant-call-site-enumeration.md` — the per-site enumeration\n *   discipline that produced this module.\n */\n\nimport { RuntimeEnvironment } from '@wildo-ai/saas-models';\n\n/**\n * Factor applied to an abuse-throttle maximum in `DEVELOPMENT` / `TEST`.\n *\n * Large on purpose. The goal is that no honest local or automated run can reach a\n * ceiling, while the counter itself still exercises the real enforcement path. A\n * smaller factor (10×, 100×) merely moves the flood later into a long e2e suite,\n * which is the worst of both worlds: still flaky, still hard to attribute.\n */\nexport const NON_PRODUCTION_RATE_LIMIT_MULTIPLIER = 1000;\n\n/**\n * `NON_PRODUCTION_RATE_LIMIT_MULTIPLIER` in `DEVELOPMENT` / `TEST`, `1` everywhere\n * else. The single branch point for the relaxation.\n *\n * @param applicationEnv - the resolved runtime environment, normally\n *   `AppConfigurationService.applicationEnv`.\n */\nexport function resolveRateLimitEnvironmentMultiplier(applicationEnv: RuntimeEnvironment): number {\n  return applicationEnv === RuntimeEnvironment.DEVELOPMENT || applicationEnv === RuntimeEnvironment.TEST\n    ? NON_PRODUCTION_RATE_LIMIT_MULTIPLIER\n    : 1;\n}\n\n/**\n * Scale one abuse-throttle maximum for the current environment. The canonical call\n * shape at an enforcement site:\n *\n * ```ts\n * const effectiveMax = relaxAbuseThrottleMaxForEnvironment(MACHINE_AUTH_FAILURE_MAX, applicationEnv);\n * if (failureCount >= effectiveMax) { … }\n * ```\n *\n * Compare the LIVE count against the returned value — never scale the count itself,\n * and never scale the window length. Shortening the window in dev would make a local\n * run stop reproducing the production timing behavior; raising the ceiling does not.\n *\n * @param authoredMax - the production-authored maximum for the window.\n * @param applicationEnv - the resolved runtime environment.\n * @returns `authoredMax` in `STAGING` / `PRODUCTION`; the relaxed ceiling otherwise.\n */\nexport function relaxAbuseThrottleMaxForEnvironment(authoredMax: number, applicationEnv: RuntimeEnvironment): number {\n  return authoredMax * resolveRateLimitEnvironmentMultiplier(applicationEnv);\n}\n"]}
+{"version":3,"file":"rate-limit-environment-relaxation.backend.utils.js","sourceRoot":"","sources":["../../../../../src/errors/utils/rate-limit-environment-relaxation.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,IAAI,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,UAAU,qCAAqC,CAAC,cAAkC;IACtF,OAAO,cAAc,KAAK,kBAAkB,CAAC,WAAW,IAAI,cAAc,KAAK,kBAAkB,CAAC,IAAI;QACpG,CAAC,CAAC,oCAAoC;QACtC,CAAC,CAAC,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mCAAmC,CAAC,WAAmB,EAAE,cAAkC;IACzG,OAAO,WAAW,GAAG,qCAAqC,CAAC,cAAc,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAsB;IAC7D,wBAAwB;IACxB,6BAA6B;IAC7B,kCAAkC;IAClC,oCAAoC;IACpC,oCAAoC;IACpC,2BAA2B;IAC3B,2BAA2B;CAC5B,CAAC;AASF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,+BAA+B,CAC7C,cAAkC;IAElC,MAAM,UAAU,GAAG,qCAAqC,CAAC,cAAc,CAAC,CAAC;IACzE,OAAO,UAAU,KAAK,CAAC;QACrB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,4BAA4B,EAAE,CAAC;AACjF,CAAC","sourcesContent":["/**\n * Non-production relaxation of ABUSE-THROTTLE maxima — the single seam.\n *\n * ## Why this module exists\n *\n * Every rate-limit maximum in the engine is authored for a PRODUCTION threat model\n * (credential stuffing, registration spam, enumeration, LLM-spend abuse, unmetered\n * egress). Applied unchanged, those same numbers turn ordinary local development and\n * automated e2e/integration runs — which legitimately fire the same endpoint from the\n * same IP, the same email and the same principal dozens of times in seconds — into a\n * 429 flood.\n *\n * The relaxation used to live as a private constant inside\n * `RateLimitBackendService`, so it reached only that service's three surfaces\n * (`checkRateLimit`, `checkPolicy`, `checkPolicyForVariant`). Five other enforcement\n * sites carry their own hard-coded maxima and never saw it. The one that hurt most in\n * practice was the machine-credential failure guard\n * (`assertMachineAuthAttemptWithinRate`, 50 failures / 600 s / source IP): on a dev\n * machine every process shares `127.0.0.1`, so fifty failed `sk_*` / `oc_*`\n * presentations from ANY source lock out every machine-credential path for ten\n * minutes — including the ones a developer is actively debugging.\n *\n * This module is that single seam. Import it at every abuse-throttle site rather than\n * re-deriving an environment branch locally; a second copy of the branch is how the\n * first one drifted (see `.claude/rules/invariant-call-site-enumeration.md`).\n *\n * ## What it deliberately does NOT do\n *\n * - **It does not bypass enforcement.** The counters still increment through the real\n *   Redis `INCR` + `EXPIRE` path, so a genuine regression (windows not incrementing,\n *   keys colliding, TTL never set) still reproduces locally. Only the ceiling moves.\n * - **It does not touch `STAGING` / `PRODUCTION`.** {@link resolveRateLimitEnvironmentMultiplier}\n *   returns `1` for every environment other than `DEVELOPMENT` and `TEST`, so the\n *   authored number IS the enforced number wherever the threat model is real.\n * - **It must not be applied to business-semantic counters.** A counter whose maximum\n *   is a product or tenant policy — SSO grace logins (`enforcement.graceLoginAttempts`),\n *   trial quotas, plan entitlements — is not an abuse throttle. Multiplying it would\n *   change observable product behavior in dev/test and make local runs disagree with\n *   production semantics, which is the opposite of what this exists for. The same goes\n *   for counters used as audit/log DE-DUPLICATION windows (the authorization-denial\n *   audit sampler, the SAML assertion warning de-dup): relaxing those produces an\n *   audit/log flood, not headroom.\n *\n * @see `.claude/rules/invariant-call-site-enumeration.md` — the per-site enumeration\n *   discipline that produced this module.\n */\n\nimport { RuntimeEnvironment } from '@wildo-ai/saas-models';\n\n/**\n * Factor applied to an abuse-throttle maximum in `DEVELOPMENT` / `TEST`.\n *\n * Large on purpose. The goal is that no honest local or automated run can reach a\n * ceiling, while the counter itself still exercises the real enforcement path. A\n * smaller factor (10×, 100×) merely moves the flood later into a long e2e suite,\n * which is the worst of both worlds: still flaky, still hard to attribute.\n */\nexport const NON_PRODUCTION_RATE_LIMIT_MULTIPLIER = 1000;\n\n/**\n * `NON_PRODUCTION_RATE_LIMIT_MULTIPLIER` in `DEVELOPMENT` / `TEST`, `1` everywhere\n * else. The single branch point for the relaxation.\n *\n * @param applicationEnv - the resolved runtime environment, normally\n *   `AppConfigurationService.applicationEnv`.\n */\nexport function resolveRateLimitEnvironmentMultiplier(applicationEnv: RuntimeEnvironment): number {\n  return applicationEnv === RuntimeEnvironment.DEVELOPMENT || applicationEnv === RuntimeEnvironment.TEST\n    ? NON_PRODUCTION_RATE_LIMIT_MULTIPLIER\n    : 1;\n}\n\n/**\n * Scale one abuse-throttle maximum for the current environment. The canonical call\n * shape at an enforcement site:\n *\n * ```ts\n * const effectiveMax = relaxAbuseThrottleMaxForEnvironment(MACHINE_AUTH_FAILURE_MAX, applicationEnv);\n * if (failureCount >= effectiveMax) { … }\n * ```\n *\n * Compare the LIVE count against the returned value — never scale the count itself,\n * and never scale the window length. Shortening the window in dev would make a local\n * run stop reproducing the production timing behavior; raising the ceiling does not.\n *\n * @param authoredMax - the production-authored maximum for the window.\n * @param applicationEnv - the resolved runtime environment.\n * @returns `authoredMax` in `STAGING` / `PRODUCTION`; the relaxed ceiling otherwise.\n */\nexport function relaxAbuseThrottleMaxForEnvironment(authoredMax: number, applicationEnv: RuntimeEnvironment): number {\n  return authoredMax * resolveRateLimitEnvironmentMultiplier(applicationEnv);\n}\n\n/**\n * Every abuse throttle this relaxation reaches, named so the boot announcement can list them (#499).\n *\n * A line saying \"abuse limits relaxed\" would be accurate and still misleading: an operator would\n * reasonably read it as ALL of them, and it is not — a counter whose maximum is a product or tenant\n * policy is deliberately untouched, as is any counter used as an audit de-duplication window (see the\n * module header). Naming the reached set is what makes the announcement actionable rather than\n * atmospheric.\n *\n * Maintained by hand against the import sites, which is a list re-stating another file's population —\n * exactly the shape `invariant-call-site-enumeration.md` warns about. It is tolerable ONLY because it\n * feeds a log line rather than a decision: a stale entry here misinforms an operator, it does not\n * change a ceiling. Keep it in step when a site is added, and prefer deleting it over letting it rot.\n */\nexport const RELAXED_ABUSE_THROTTLE_SITES: readonly string[] = [\n  'HTTP perimeter limiter',\n  'WebSocket per-event limiter',\n  'machine-credential failure guard',\n  'external-turn throttle (A2A / MCP)',\n  'authorization-denial audit sampler',\n  'webhook endpoint-test cap',\n  'rate-limit policy service',\n];\n\n/** What a boot announcement should say, or `null` when the environment relaxes nothing. */\nexport interface AbuseThrottleRelaxationAnnouncement {\n  readonly applicationEnv: RuntimeEnvironment;\n  readonly multiplier: number;\n  readonly relaxedSites: readonly string[];\n}\n\n/**\n * Describe the relaxation in force, for an unmissable line at startup (#499).\n *\n * The relaxation is keyed on the resolved environment and nothing else — a deliberate decision, so\n * there is one source of truth for \"what kind of host is this\" rather than a second flag that can\n * disagree with it. The residual risk is that a host which merely REPORTS development (a demonstration\n * box, a staging-like environment mis-declared) runs with maxima multiplied by a thousand. That risk is\n * accepted, and this function is the whole of what makes it visible instead of silent.\n *\n * Returns `null` in `STAGING` / `PRODUCTION`, so a caller logs nothing where nothing is relaxed.\n */\nexport function describeAbuseThrottleRelaxation(\n  applicationEnv: RuntimeEnvironment,\n): AbuseThrottleRelaxationAnnouncement | null {\n  const multiplier = resolveRateLimitEnvironmentMultiplier(applicationEnv);\n  return multiplier === 1\n    ? null\n    : { applicationEnv, multiplier, relaxedSites: RELAXED_ABUSE_THROTTLE_SITES };\n}\n"]}

package/dist/esm/external-data/controllers/external-data-admin.backend.contracts.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Public contracts for the {@link ExternalDataAdminBackendController}.
+ *
+ * Co-located away from the controller so tests, operators and ad-hoc scripts can consume the
+ * literal paths without instantiating the DI container — the same split, and the same reasons, as
+ * `data-seeding-admin.backend.contracts`. No runtime logic here, only literals and types.
+ */
+/** @wildo_source:part:start saas.external-data.admin-endpoints facet:kind:framework-api facet:audience:operator */
+/**
+ * Environment variable holding the secret these endpoints require. When unset or empty EVERY
+ * endpoint answers 503 — the safe default, so a fresh deployment never accidentally exposes an
+ * operator surface that can reach a third party's production system.
+ *
+ * Deliberately the SAME key data-seeding uses: an operator administering one app has one admin
+ * secret, and minting a second would mean two rotations to remember and one of them forgotten.
+ */
+export declare const ExternalDataAdminEndpointEnvKey: "APPLICATION_ADMIN_SECRET";
+/** Header carrying the secret. Hash-then-`timingSafeEqual`, per the sibling controller. */
+export declare const ExternalDataAdminEndpointHeaderKey: "X-Admin-Secret";
+/**
+ * Root mount. Under `/internal/...` rather than `/api/v1/...` because this is an operator surface,
+ * not a consumer API — the convention `/health` and the data-seeding admin surface already follow.
+ */
+export declare const ExternalDataAdminEndpointMountBasePath: "/internal/admin/external-data";
+/** Sub-paths, relative to {@link ExternalDataAdminEndpointMountBasePath}. */
+export declare const ExternalDataAdminEndpointPath: {
+    /** GET — every declared pipeline with its persisted cursor and last-run summary. */
+    readonly PIPELINES: "/pipelines";
+    /**
+     * POST — run ONE pipeline now. `{ "resourceType": "externalCustomers" }`.
+     *
+     * This exists because a scheduled-only capability is undevelopable: authoring a mapping against
+     * SAP or Dynamics means change → sync → look, dozens of times, and an hourly cron makes that loop
+     * unusable. Verifying the first dogfood required either waiting an hour or editing committed app
+     * config, which is what proved the door was missing.
+     */
+    readonly RUN: "/run";
+};
+export type ExternalDataAdminEndpointPathValue = (typeof ExternalDataAdminEndpointPath)[keyof typeof ExternalDataAdminEndpointPath];
+/** @wildo_source:part:end saas.external-data.admin-endpoints */
+//# sourceMappingURL=external-data-admin.backend.contracts.d.ts.map

package/dist/esm/external-data/controllers/external-data-admin.backend.contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-admin.backend.contracts.d.ts","sourceRoot":"","sources":["../../../../../src/external-data/controllers/external-data-admin.backend.contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,mHAAmH;AACnH;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAG,0BAAmC,CAAC;AAEnF,2FAA2F;AAC3F,eAAO,MAAM,kCAAkC,EAAG,gBAAyB,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,sCAAsC,EAAG,+BAAwC,CAAC;AAE/F,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B;IACxC,oFAAoF;;IAEpF;;;;;;;OAOG;;CAEK,CAAC;AAEX,MAAM,MAAM,kCAAkC,GAC5C,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,OAAO,6BAA6B,CAAC,CAAC;AACrF,gEAAgE"}

package/dist/esm/external-data/controllers/external-data-admin.backend.contracts.js

@@ -0,0 +1,40 @@
+/**
+ * Public contracts for the {@link ExternalDataAdminBackendController}.
+ *
+ * Co-located away from the controller so tests, operators and ad-hoc scripts can consume the
+ * literal paths without instantiating the DI container — the same split, and the same reasons, as
+ * `data-seeding-admin.backend.contracts`. No runtime logic here, only literals and types.
+ */
+/** @wildo_source:part:start saas.external-data.admin-endpoints facet:kind:framework-api facet:audience:operator */
+/**
+ * Environment variable holding the secret these endpoints require. When unset or empty EVERY
+ * endpoint answers 503 — the safe default, so a fresh deployment never accidentally exposes an
+ * operator surface that can reach a third party's production system.
+ *
+ * Deliberately the SAME key data-seeding uses: an operator administering one app has one admin
+ * secret, and minting a second would mean two rotations to remember and one of them forgotten.
+ */
+export const ExternalDataAdminEndpointEnvKey = 'APPLICATION_ADMIN_SECRET';
+/** Header carrying the secret. Hash-then-`timingSafeEqual`, per the sibling controller. */
+export const ExternalDataAdminEndpointHeaderKey = 'X-Admin-Secret';
+/**
+ * Root mount. Under `/internal/...` rather than `/api/v1/...` because this is an operator surface,
+ * not a consumer API — the convention `/health` and the data-seeding admin surface already follow.
+ */
+export const ExternalDataAdminEndpointMountBasePath = '/internal/admin/external-data';
+/** Sub-paths, relative to {@link ExternalDataAdminEndpointMountBasePath}. */
+export const ExternalDataAdminEndpointPath = {
+    /** GET — every declared pipeline with its persisted cursor and last-run summary. */
+    PIPELINES: '/pipelines',
+    /**
+     * POST — run ONE pipeline now. `{ "resourceType": "externalCustomers" }`.
+     *
+     * This exists because a scheduled-only capability is undevelopable: authoring a mapping against
+     * SAP or Dynamics means change → sync → look, dozens of times, and an hourly cron makes that loop
+     * unusable. Verifying the first dogfood required either waiting an hour or editing committed app
+     * config, which is what proved the door was missing.
+     */
+    RUN: '/run',
+};
+/** @wildo_source:part:end saas.external-data.admin-endpoints */
+//# sourceMappingURL=external-data-admin.backend.contracts.js.map

package/dist/esm/external-data/controllers/external-data-admin.backend.contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-admin.backend.contracts.js","sourceRoot":"","sources":["../../../../../src/external-data/controllers/external-data-admin.backend.contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,mHAAmH;AACnH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,0BAAmC,CAAC;AAEnF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kCAAkC,GAAG,gBAAyB,CAAC;AAE5E;;;GAGG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,+BAAwC,CAAC;AAE/F,6EAA6E;AAC7E,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,oFAAoF;IACpF,SAAS,EAAE,YAAY;IACvB;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM;CACH,CAAC;AAIX,gEAAgE","sourcesContent":["/**\n * Public contracts for the {@link ExternalDataAdminBackendController}.\n *\n * Co-located away from the controller so tests, operators and ad-hoc scripts can consume the\n * literal paths without instantiating the DI container — the same split, and the same reasons, as\n * `data-seeding-admin.backend.contracts`. No runtime logic here, only literals and types.\n */\n\n/** @wildo_source:part:start saas.external-data.admin-endpoints facet:kind:framework-api facet:audience:operator */\n/**\n * Environment variable holding the secret these endpoints require. When unset or empty EVERY\n * endpoint answers 503 — the safe default, so a fresh deployment never accidentally exposes an\n * operator surface that can reach a third party's production system.\n *\n * Deliberately the SAME key data-seeding uses: an operator administering one app has one admin\n * secret, and minting a second would mean two rotations to remember and one of them forgotten.\n */\nexport const ExternalDataAdminEndpointEnvKey = 'APPLICATION_ADMIN_SECRET' as const;\n\n/** Header carrying the secret. Hash-then-`timingSafeEqual`, per the sibling controller. */\nexport const ExternalDataAdminEndpointHeaderKey = 'X-Admin-Secret' as const;\n\n/**\n * Root mount. Under `/internal/...` rather than `/api/v1/...` because this is an operator surface,\n * not a consumer API — the convention `/health` and the data-seeding admin surface already follow.\n */\nexport const ExternalDataAdminEndpointMountBasePath = '/internal/admin/external-data' as const;\n\n/** Sub-paths, relative to {@link ExternalDataAdminEndpointMountBasePath}. */\nexport const ExternalDataAdminEndpointPath = {\n  /** GET — every declared pipeline with its persisted cursor and last-run summary. */\n  PIPELINES: '/pipelines',\n  /**\n   * POST — run ONE pipeline now. `{ \"resourceType\": \"externalCustomers\" }`.\n   *\n   * This exists because a scheduled-only capability is undevelopable: authoring a mapping against\n   * SAP or Dynamics means change → sync → look, dozens of times, and an hourly cron makes that loop\n   * unusable. Verifying the first dogfood required either waiting an hour or editing committed app\n   * config, which is what proved the door was missing.\n   */\n  RUN: '/run',\n} as const;\n\nexport type ExternalDataAdminEndpointPathValue =\n  (typeof ExternalDataAdminEndpointPath)[keyof typeof ExternalDataAdminEndpointPath];\n/** @wildo_source:part:end saas.external-data.admin-endpoints */\n"]}

package/dist/esm/external-data/controllers/external-data-admin.backend.controller.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `ExternalDataAdminBackendController` — the operator door onto external-data pipelines.
+ *
+ * ## Why this exists, and why it is not merely "nice to have"
+ *
+ * A pipeline could only ever be started by its own `scheduleCron`. That makes the capability
+ * UNDEVELOPABLE against a real remote system: authoring a mapping for SAP or Dynamics is a loop of
+ * change → sync → look, run dozens of times, and an hourly cron makes each turn of that loop an
+ * hour long. The gap was not theoretical — verifying Wonder Todos' first pipeline required either
+ * waiting for the hour or editing committed app config, which is what showed the door was missing.
+ *
+ * It is equally the operator surface: "the client list is wrong, sync it now" has no answer when
+ * the only trigger is a clock.
+ *
+ * ## Posture — deliberately identical to the data-seeding admin surface
+ *
+ * Root-mounted under `/internal/...` rather than `/api/v1/...` (operator surface, not consumer
+ * API), gated on `APPLICATION_ADMIN_SECRET` — the SAME key data-seeding uses, because an operator
+ * administering one application should hold one secret, and minting a second means two rotations to
+ * remember and one of them forgotten. Unset ⇒ every endpoint answers 503, so a fresh deployment
+ * never accidentally exposes a door that reaches a third party's production system.
+ *
+ * The secret compare hashes BOTH sides before `timingSafeEqual`, so the buffers are always 32 bytes
+ * and no length-mismatch timing oracle exists (the sibling's audit L-2 lesson, inherited rather
+ * than re-derived).
+ *
+ * There is deliberately NO in-process rate limit: like the sibling, this belongs behind a
+ * network-level limiter, and a run is already single-flighted per pipeline by the run service, so a
+ * caller hammering `/run` gets `already-running` rather than a stampede on the remote system.
+ */
+import 'reflect-metadata';
+import { AbstractControllerBackendService } from '../../base-classes/services/controllers/abstract-controller.backend.service';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service';
+import { ErrorHandlerService } from '../../errors/services/error-handler.backend.service';
+import { LoggerService } from '../../monitoring/logger/services/logger.service';
+import { ExecutionContextCreatorBackendService } from '../../runtime/services/execution-context-creator.backend.service';
+import { RepositoriesRegistryHandlerBackendService } from '../../base-classes/services/repositories/repositories-registry-handler.backend.service';
+import type { ExternalDataPipelineRunBackendService } from '../../external-data/external-data-pipeline-run.backend.service';
+export declare class ExternalDataAdminBackendController extends AbstractControllerBackendService {
+    private readonly pipelineRunService;
+    private readonly repositoriesRegistry;
+    private readonly executionContextCreator;
+    constructor(logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, pipelineRunService: ExternalDataPipelineRunBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService, executionContextCreator: ExecutionContextCreatorBackendService);
+    /** Root-level mount, mirroring `/health` and the data-seeding admin surface. */
+    getCustomMountBasePath(): string;
+    protected setupRoutes(): void;
+    /**
+     * Same guard as the data-seeding admin surface, for the same reasons. Hash BOTH inputs so the
+     * buffers handed to `timingSafeEqual` are a fixed 32 bytes — an early length compare would leak
+     * the secret's length.
+     */
+    private requireAdminSecret;
+    /**
+     * GET /pipelines — every DECLARED pipeline, joined with its persisted state.
+     *
+     * Declaration-first rather than state-first on purpose: a pipeline that has never run has no
+     * state row, and it is exactly the one an operator is looking for when something is wrong.
+     * Listing from state would make it invisible.
+     */
+    private handleListPipelines;
+    /** POST /run — run one pipeline now, and answer with the run report. */
+    private handleRunPipeline;
+}
+//# sourceMappingURL=external-data-admin.backend.controller.d.ts.map

package/dist/esm/external-data/controllers/external-data-admin.backend.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-admin.backend.controller.d.ts","sourceRoot":"","sources":["../../../../../src/external-data/controllers/external-data-admin.backend.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,kBAAkB,CAAC;AAO1B,OAAO,EAAE,gCAAgC,EAAE,MAAM,0FAA0F,CAAC;AAC5I,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAC9G,OAAO,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AACvG,OAAO,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAE7F,OAAO,EAAE,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AACtI,OAAO,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AAKhK,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,6EAA6E,CAAC;AAczI,qBACa,kCAAmC,SAAQ,gCAAgC;IAMpF,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAEnC,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IAErC,OAAO,CAAC,QAAQ,CAAC,uBAAuB;gBARL,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EACxC,YAAY,EAAE,mBAAmB,EAEhE,kBAAkB,EAAE,qCAAqC,EAEzD,oBAAoB,EAAE,yCAAyC,EAE/D,uBAAuB,EAAE,qCAAqC;IAKjF,gFAAgF;IACzE,sBAAsB,IAAI,MAAM;IAIvC,SAAS,CAAC,WAAW,IAAI,IAAI;IAgB7B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAgC1B;;;;;;OAMG;YACW,mBAAmB;IAmCjC,wEAAwE;YAC1D,iBAAiB;CA6BhC"}

package/dist/esm/external-data/controllers/external-data-admin.backend.controller.js

@@ -0,0 +1,193 @@
+/**
+ * `ExternalDataAdminBackendController` — the operator door onto external-data pipelines.
+ *
+ * ## Why this exists, and why it is not merely "nice to have"
+ *
+ * A pipeline could only ever be started by its own `scheduleCron`. That makes the capability
+ * UNDEVELOPABLE against a real remote system: authoring a mapping for SAP or Dynamics is a loop of
+ * change → sync → look, run dozens of times, and an hourly cron makes each turn of that loop an
+ * hour long. The gap was not theoretical — verifying Wonder Todos' first pipeline required either
+ * waiting for the hour or editing committed app config, which is what showed the door was missing.
+ *
+ * It is equally the operator surface: "the client list is wrong, sync it now" has no answer when
+ * the only trigger is a clock.
+ *
+ * ## Posture — deliberately identical to the data-seeding admin surface
+ *
+ * Root-mounted under `/internal/...` rather than `/api/v1/...` (operator surface, not consumer
+ * API), gated on `APPLICATION_ADMIN_SECRET` — the SAME key data-seeding uses, because an operator
+ * administering one application should hold one secret, and minting a second means two rotations to
+ * remember and one of them forgotten. Unset ⇒ every endpoint answers 503, so a fresh deployment
+ * never accidentally exposes a door that reaches a third party's production system.
+ *
+ * The secret compare hashes BOTH sides before `timingSafeEqual`, so the buffers are always 32 bytes
+ * and no length-mismatch timing oracle exists (the sibling's audit L-2 lesson, inherited rather
+ * than re-derived).
+ *
+ * There is deliberately NO in-process rate limit: like the sibling, this belongs behind a
+ * network-level limiter, and a run is already single-flighted per pipeline by the run service, so a
+ * caller hammering `/run` gets `already-running` rather than a stampede on the remote system.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import 'reflect-metadata';
+import { createHash, timingSafeEqual } from 'crypto';
+import { inject, injectable } from 'inversify';
+import { z } from 'zod';
+import { ErrorCustomMessageReference, ErrorType } from '@wildo-ai/saas-models';
+import { AbstractControllerBackendService } from '../../base-classes/services/controllers/abstract-controller.backend.service.js';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
+import { ErrorHandlerService } from '../../errors/services/error-handler.backend.service.js';
+import { LoggerService } from '../../monitoring/logger/services/logger.service.js';
+import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { ExecutionContextCreatorBackendService } from '../../runtime/services/execution-context-creator.backend.service.js';
+import { RepositoriesRegistryHandlerBackendService } from '../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+import { BackendResourceType } from '../../resources/models/resources-types.backend.schemas.js';
+import { CoreResourceOperation } from '@wildo-ai/saas-models';
+import { DataSeedTriggerOrigin } from '../../data-seeding/models/data-seed.shared.schemas.js';
+import { ExternalDataAdminEndpointEnvKey, ExternalDataAdminEndpointHeaderKey, ExternalDataAdminEndpointMountBasePath, ExternalDataAdminEndpointPath, } from './external-data-admin.backend.contracts.js';
+/** `POST /run` body. `resourceType` names the DESTINATION resource declaring the pipeline. */
+const RunPipelineRequestSchema = z.object({
+    resourceType: z.string().min(1),
+}).strict();
+let ExternalDataAdminBackendController = class ExternalDataAdminBackendController extends AbstractControllerBackendService {
+    pipelineRunService;
+    repositoriesRegistry;
+    executionContextCreator;
+    constructor(logger, errorBuilder, errorHandler, pipelineRunService, repositoriesRegistry, executionContextCreator) {
+        super(logger, errorBuilder, errorHandler, 'ExternalDataAdminController');
+        this.pipelineRunService = pipelineRunService;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.executionContextCreator = executionContextCreator;
+    }
+    /** Root-level mount, mirroring `/health` and the data-seeding admin surface. */
+    getCustomMountBasePath() {
+        return ExternalDataAdminEndpointMountBasePath;
+    }
+    setupRoutes() {
+        this.router.use(this.requireAdminSecret.bind(this));
+        this.router.get(ExternalDataAdminEndpointPath.PIPELINES, this.asyncHandler(this.handleListPipelines.bind(this)));
+        this.logRouteRegistration('GET', ExternalDataAdminEndpointPath.PIPELINES, 'List declared external-data pipelines with cursor + last run');
+        this.router.post(ExternalDataAdminEndpointPath.RUN, this.asyncHandler(this.handleRunPipeline.bind(this)));
+        this.logRouteRegistration('POST', ExternalDataAdminEndpointPath.RUN, 'Run one external-data pipeline now');
+    }
+    /**
+     * Same guard as the data-seeding admin surface, for the same reasons. Hash BOTH inputs so the
+     * buffers handed to `timingSafeEqual` are a fixed 32 bytes — an early length compare would leak
+     * the secret's length.
+     */
+    requireAdminSecret(req, _res, next) {
+        const expectedSecret = process.env[ExternalDataAdminEndpointEnvKey];
+        if (!expectedSecret || expectedSecret.length === 0) {
+            throw this.errorBuilder.buildError(ErrorType.INFRASTRUCTURE, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INFRASTRUCTURE,
+                context: {
+                    message: `external-data admin endpoints disabled (${ExternalDataAdminEndpointEnvKey} unset)`,
+                    envKey: ExternalDataAdminEndpointEnvKey,
+                },
+            });
+        }
+        const providedSecret = req.headers[ExternalDataAdminEndpointHeaderKey.toLowerCase()];
+        if (!providedSecret) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.SEED_ADMIN_SECRET_REQUIRED,
+                context: { headerKey: ExternalDataAdminEndpointHeaderKey },
+            });
+        }
+        const providedDigest = createHash('sha256').update(providedSecret).digest();
+        const expectedDigest = createHash('sha256').update(expectedSecret).digest();
+        if (!timingSafeEqual(providedDigest, expectedDigest)) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.SEED_ADMIN_SECRET_INVALID,
+                context: { headerKey: ExternalDataAdminEndpointHeaderKey },
+            });
+        }
+        next();
+    }
+    /**
+     * GET /pipelines — every DECLARED pipeline, joined with its persisted state.
+     *
+     * Declaration-first rather than state-first on purpose: a pipeline that has never run has no
+     * state row, and it is exactly the one an operator is looking for when something is wrong.
+     * Listing from state would make it invisible.
+     */
+    async handleListPipelines(_req, res) {
+        const stateContext = await this.executionContextCreator.createForInternalRepositoryOperation({
+            resourceType: BackendResourceType.EXTERNAL_DATA_PIPELINE_STATE,
+            operationIdentifier: CoreResourceOperation.READ,
+        });
+        const stateRepo = this.repositoriesRegistry.getRepositoryOrThrow(BackendResourceType.EXTERNAL_DATA_PIPELINE_STATE, stateContext);
+        const pipelines = await Promise.all(this.pipelineRunService.listDeclaredPipelines().map(async ({ resourceType, declaration }) => {
+            const state = await stateRepo.read(stateContext, { pipelineResourceType: resourceType });
+            return {
+                resourceType,
+                providerRef: declaration.binding.providerRef,
+                remoteEntityRef: declaration.binding.entityRef,
+                dialect: declaration.binding.dialect,
+                population: declaration.population,
+                orphanPolicy: declaration.orphanPolicy,
+                scheduleCron: declaration.scheduleCron ?? null,
+                maxRowsPerRun: declaration.maxRowsPerRun,
+                // `cursor !== null` means a pass is IN FLIGHT — and therefore that the next run will not
+                // sweep orphans. Surfaced because it is the single most confusing state to debug blind.
+                cursor: state?.cursor ?? null,
+                passStartedAt: state?.passStartedAt ?? null,
+                lastRunAt: state?.lastRunAt ?? null,
+                lastRunSummary: state?.lastRunSummary ?? null,
+            };
+        }));
+        res.json({ pipelines });
+    }
+    /** POST /run — run one pipeline now, and answer with the run report. */
+    async handleRunPipeline(req, res) {
+        const parsed = RunPipelineRequestSchema.safeParse(req.body);
+        if (!parsed.success) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: { issues: parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`) },
+            });
+        }
+        const { resourceType } = parsed.data;
+        const declared = this.pipelineRunService.listDeclaredPipelines().some((entry) => entry.resourceType === resourceType);
+        if (!declared) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    message: `Resource '${resourceType}' declares no externalDataPipeline. GET ${ExternalDataAdminEndpointMountBasePath}${ExternalDataAdminEndpointPath.PIPELINES} lists the ones that do.`,
+                },
+            });
+        }
+        // ADMIN_MANUAL, not SCHEDULED_RERUN: the run ledger should record that a human asked.
+        const report = await this.pipelineRunService.runPipeline({
+            resourceType,
+            triggerOrigin: DataSeedTriggerOrigin.ADMIN_MANUAL,
+            triggeredByUserId: null,
+        });
+        res.json(report);
+    }
+};
+ExternalDataAdminBackendController = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorHandlerService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.ExternalDataPipelineRunService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __metadata("design:paramtypes", [LoggerService,
+        ErrorBuilderBackendService,
+        ErrorHandlerService, Function, RepositoriesRegistryHandlerBackendService,
+        ExecutionContextCreatorBackendService])
+], ExternalDataAdminBackendController);
+export { ExternalDataAdminBackendController };
+//# sourceMappingURL=external-data-admin.backend.controller.js.map

package/dist/esm/external-data/controllers/external-data-admin.backend.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-data-admin.backend.controller.js","sourceRoot":"","sources":["../../../../../src/external-data/controllers/external-data-admin.backend.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;;;;;;;;;;;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,2BAA2B,EAAE,SAAS,EAAqB,MAAM,uBAAuB,CAAC;AAElG,OAAO,EAAE,gCAAgC,EAAE,MAAM,0FAA0F,CAAC;AAC5I,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAC9G,OAAO,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AACvG,OAAO,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AACpF,OAAO,EAAE,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AACtI,OAAO,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AAChK,OAAO,EAAE,mBAAmB,EAAE,MAAM,qEAAqE,CAAC;AAC1G,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,iEAAiE,CAAC;AAIxG,OAAO,EACL,+BAA+B,EAC/B,kCAAkC,EAClC,sCAAsC,EACtC,6BAA6B,GAC9B,MAAM,yCAAyC,CAAC;AAEjD,8FAA8F;AAC9F,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAChC,CAAC,CAAC,MAAM,EAAE,CAAC;AAGL,IAAM,kCAAkC,GAAxC,MAAM,kCAAmC,SAAQ,gCAAgC;IAMnE;IAEA;IAEA;IATnB,YACqC,MAAqB,EACR,YAAwC,EACxC,YAAiC,EAEhE,kBAAyD,EAEzD,oBAA+D,EAE/D,uBAA8D;QAE/E,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,6BAA6B,CAAC,CAAC;QANxD,uBAAkB,GAAlB,kBAAkB,CAAuC;QAEzD,yBAAoB,GAApB,oBAAoB,CAA2C;QAE/D,4BAAuB,GAAvB,uBAAuB,CAAuC;IAGjF,CAAC;IAED,gFAAgF;IACzE,sBAAsB;QAC3B,OAAO,sCAAsC,CAAC;IAChD,CAAC;IAES,WAAW;QACnB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAEpD,IAAI,CAAC,MAAM,CAAC,GAAG,CACb,6BAA6B,CAAC,SAAS,EACvC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CACvD,CAAC;QACF,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,6BAA6B,CAAC,SAAS,EAAE,8DAA8D,CAAC,CAAC;QAE1I,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,6BAA6B,CAAC,GAAG,EACjC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CACrD,CAAC;QACF,IAAI,CAAC,oBAAoB,CAAC,MAAM,EAAE,6BAA6B,CAAC,GAAG,EAAE,oCAAoC,CAAC,CAAC;IAC7G,CAAC;IAED;;;;OAIG;IACK,kBAAkB,CAAC,GAAY,EAAE,IAAc,EAAE,IAAkB;QACzE,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;QACpE,IAAI,CAAC,cAAc,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,cAAc,EAAE,SAAS,EAAE;gBACtE,sBAAsB,EAAE,2BAA2B,CAAC,cAAc;gBAClE,OAAO,EAAE;oBACP,OAAO,EAAE,2CAA2C,+BAA+B,SAAS;oBAC5F,MAAM,EAAE,+BAA+B;iBACxC;aACF,CAAC,CAAC;QACL,CAAC;QAED,MAAM,cAAc,GAAG,GAAG,CAAC,OAAO,CAAC,kCAAkC,CAAC,WAAW,EAAE,CAAuB,CAAC;QAC3G,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,cAAc,EAAE,SAAS,EAAE;gBACtE,sBAAsB,EAAE,2BAA2B,CAAC,0BAA0B;gBAC9E,OAAO,EAAE,EAAE,SAAS,EAAE,kCAAkC,EAAE;aAC3D,CAAC,CAAC;QACL,CAAC;QAED,MAAM,cAAc,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,EAAE,CAAC;QAC5E,MAAM,cAAc,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,EAAE,CAAC;QAC5E,IAAI,CAAC,eAAe,CAAC,cAAc,EAAE,cAAc,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,cAAc,EAAE,SAAS,EAAE;gBACtE,sBAAsB,EAAE,2BAA2B,CAAC,yBAAyB;gBAC7E,OAAO,EAAE,EAAE,SAAS,EAAE,kCAAkC,EAAE;aAC3D,CAAC,CAAC;QACL,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,mBAAmB,CAAC,IAAa,EAAE,GAAa;QAC5D,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,uBAAuB,CAAC,oCAAoC,CAAC;YAC3F,YAAY,EAAE,mBAAmB,CAAC,4BAA4B;YAC9D,mBAAmB,EAAE,qBAAqB,CAAC,IAAI;SACvC,CAAC,CAAC;QACZ,MAAM,SAAS,GAAG,IAAI,CAAC,oBAAoB,CAAC,oBAAoB,CAC9D,mBAAmB,CAAC,4BAAuD,EAC3E,YAAY,CACb,CAAC;QAEF,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,IAAI,CAAC,kBAAkB,CAAC,qBAAqB,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,EAAE;YAC1F,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAA4B,YAAY,EAAE,EAAE,oBAAoB,EAAE,YAAY,EAAE,CAAC,CAAC;YACpH,OAAO;gBACL,YAAY;gBACZ,WAAW,EAAE,WAAW,CAAC,OAAO,CAAC,WAAW;gBAC5C,eAAe,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS;gBAC9C,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO;gBACpC,UAAU,EAAE,WAAW,CAAC,UAAU;gBAClC,YAAY,EAAE,WAAW,CAAC,YAAY;gBACtC,YAAY,EAAE,WAAW,CAAC,YAAY,IAAI,IAAI;gBAC9C,aAAa,EAAE,WAAW,CAAC,aAAa;gBACxC,yFAAyF;gBACzF,wFAAwF;gBACxF,MAAM,EAAE,KAAK,EAAE,MAAM,IAAI,IAAI;gBAC7B,aAAa,EAAE,KAAK,EAAE,aAAa,IAAI,IAAI;gBAC3C,SAAS,EAAE,KAAK,EAAE,SAAS,IAAI,IAAI;gBACnC,cAAc,EAAE,KAAK,EAAE,cAAc,IAAI,IAAI;aAC9C,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;QAEF,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,wEAAwE;IAChE,KAAK,CAAC,iBAAiB,CAAC,GAAY,EAAE,GAAa;QACzD,MAAM,MAAM,GAAG,wBAAwB,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,SAAS,EAAE;gBAClE,sBAAsB,EAAE,2BAA2B,CAAC,UAAU;gBAC9D,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE;aACjH,CAAC,CAAC;QACL,CAAC;QACD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC;QAErC,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC,qBAAqB,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,KAAK,YAAY,CAAC,CAAC;QACtH,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,SAAS,EAAE;gBAClE,sBAAsB,EAAE,2BAA2B,CAAC,UAAU;gBAC9D,OAAO,EAAE;oBACP,OAAO,EAAE,aAAa,YAAY,2CAA2C,sCAAsC,GAAG,6BAA6B,CAAC,SAAS,0BAA0B;iBACxL;aACF,CAAC,CAAC;QACL,CAAC;QAED,sFAAsF;QACtF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC;YACvD,YAAY;YACZ,aAAa,EAAE,qBAAqB,CAAC,YAAY;YACjD,iBAAiB,EAAE,IAAI;SACxB,CAAC,CAAC;QAEH,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnB,CAAC;CACF,CAAA;AAjJY,kCAAkC;IAD9C,UAAU,EAAE;IAGR,WAAA,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;IACjC,WAAA,MAAM,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,CAAA;IAC9C,WAAA,MAAM,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,CAAA;IAC9C,WAAA,MAAM,CAAC,kBAAkB,CAAC,8BAA8B,CAAC,CAAA;IAEzD,WAAA,MAAM,CAAC,kBAAkB,CAAC,kCAAkC,CAAC,CAAA;IAE7D,WAAA,MAAM,CAAC,kBAAkB,CAAC,qCAAqC,CAAC,CAAA;qCAPtB,aAAa;QACM,0BAA0B;QAC1B,mBAAmB,YAI1C,yCAAyC;QAEtC,qCAAqC;GAVtE,kCAAkC,CAiJ9C","sourcesContent":["/**\n * `ExternalDataAdminBackendController` — the operator door onto external-data pipelines.\n *\n * ## Why this exists, and why it is not merely \"nice to have\"\n *\n * A pipeline could only ever be started by its own `scheduleCron`. That makes the capability\n * UNDEVELOPABLE against a real remote system: authoring a mapping for SAP or Dynamics is a loop of\n * change → sync → look, run dozens of times, and an hourly cron makes each turn of that loop an\n * hour long. The gap was not theoretical — verifying Wonder Todos' first pipeline required either\n * waiting for the hour or editing committed app config, which is what showed the door was missing.\n *\n * It is equally the operator surface: \"the client list is wrong, sync it now\" has no answer when\n * the only trigger is a clock.\n *\n * ## Posture — deliberately identical to the data-seeding admin surface\n *\n * Root-mounted under `/internal/...` rather than `/api/v1/...` (operator surface, not consumer\n * API), gated on `APPLICATION_ADMIN_SECRET` — the SAME key data-seeding uses, because an operator\n * administering one application should hold one secret, and minting a second means two rotations to\n * remember and one of them forgotten. Unset ⇒ every endpoint answers 503, so a fresh deployment\n * never accidentally exposes a door that reaches a third party's production system.\n *\n * The secret compare hashes BOTH sides before `timingSafeEqual`, so the buffers are always 32 bytes\n * and no length-mismatch timing oracle exists (the sibling's audit L-2 lesson, inherited rather\n * than re-derived).\n *\n * There is deliberately NO in-process rate limit: like the sibling, this belongs behind a\n * network-level limiter, and a run is already single-flighted per pipeline by the run service, so a\n * caller hammering `/run` gets `already-running` rather than a stampede on the remote system.\n */\n\nimport 'reflect-metadata';\nimport { createHash, timingSafeEqual } from 'crypto';\nimport { inject, injectable } from 'inversify';\nimport type { NextFunction, Request, Response } from 'express';\nimport { z } from 'zod';\nimport { ErrorCustomMessageReference, ErrorType, type ResourceType } from '@wildo-ai/saas-models';\n\nimport { AbstractControllerBackendService } from '~wildo-backend-lib/base-classes/services/controllers/abstract-controller.backend.service';\nimport { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { ErrorHandlerService } from '~wildo-backend-lib/errors/services/error-handler.backend.service';\nimport { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';\nimport { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';\nimport { BackendResourceType } from '~wildo-backend-lib/resources/models/resources-types.backend.schemas';\nimport { CoreResourceOperation } from '@wildo-ai/saas-models';\nimport { DataSeedTriggerOrigin } from '~wildo-backend-lib/data-seeding/models/data-seed.shared.schemas';\nimport type { ExternalDataPipelineState } from '~wildo-backend-lib/external-data/models/external-data-pipeline-state.backend.schemas';\nimport type { ExternalDataPipelineRunBackendService } from '~wildo-backend-lib/external-data/external-data-pipeline-run.backend.service';\n\nimport {\n  ExternalDataAdminEndpointEnvKey,\n  ExternalDataAdminEndpointHeaderKey,\n  ExternalDataAdminEndpointMountBasePath,\n  ExternalDataAdminEndpointPath,\n} from './external-data-admin.backend.contracts';\n\n/** `POST /run` body. `resourceType` names the DESTINATION resource declaring the pipeline. */\nconst RunPipelineRequestSchema = z.object({\n  resourceType: z.string().min(1),\n}).strict();\n\n@injectable()\nexport class ExternalDataAdminBackendController extends AbstractControllerBackendService {\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: ErrorBuilderBackendService,\n    @inject(SAAS_SERVICE_TYPES.ErrorHandlerService) errorHandler: ErrorHandlerService,\n    @inject(SAAS_SERVICE_TYPES.ExternalDataPipelineRunService)\n    private readonly pipelineRunService: ExternalDataPipelineRunBackendService,\n    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)\n    private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,\n    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)\n    private readonly executionContextCreator: ExecutionContextCreatorBackendService,\n  ) {\n    super(logger, errorBuilder, errorHandler, 'ExternalDataAdminController');\n  }\n\n  /** Root-level mount, mirroring `/health` and the data-seeding admin surface. */\n  public getCustomMountBasePath(): string {\n    return ExternalDataAdminEndpointMountBasePath;\n  }\n\n  protected setupRoutes(): void {\n    this.router.use(this.requireAdminSecret.bind(this));\n\n    this.router.get(\n      ExternalDataAdminEndpointPath.PIPELINES,\n      this.asyncHandler(this.handleListPipelines.bind(this)),\n    );\n    this.logRouteRegistration('GET', ExternalDataAdminEndpointPath.PIPELINES, 'List declared external-data pipelines with cursor + last run');\n\n    this.router.post(\n      ExternalDataAdminEndpointPath.RUN,\n      this.asyncHandler(this.handleRunPipeline.bind(this)),\n    );\n    this.logRouteRegistration('POST', ExternalDataAdminEndpointPath.RUN, 'Run one external-data pipeline now');\n  }\n\n  /**\n   * Same guard as the data-seeding admin surface, for the same reasons. Hash BOTH inputs so the\n   * buffers handed to `timingSafeEqual` are a fixed 32 bytes — an early length compare would leak\n   * the secret's length.\n   */\n  private requireAdminSecret(req: Request, _res: Response, next: NextFunction): void {\n    const expectedSecret = process.env[ExternalDataAdminEndpointEnvKey];\n    if (!expectedSecret || expectedSecret.length === 0) {\n      throw this.errorBuilder.buildError(ErrorType.INFRASTRUCTURE, undefined, {\n        customMessageReference: ErrorCustomMessageReference.INFRASTRUCTURE,\n        context: {\n          message: `external-data admin endpoints disabled (${ExternalDataAdminEndpointEnvKey} unset)`,\n          envKey: ExternalDataAdminEndpointEnvKey,\n        },\n      });\n    }\n\n    const providedSecret = req.headers[ExternalDataAdminEndpointHeaderKey.toLowerCase()] as string | undefined;\n    if (!providedSecret) {\n      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.SEED_ADMIN_SECRET_REQUIRED,\n        context: { headerKey: ExternalDataAdminEndpointHeaderKey },\n      });\n    }\n\n    const providedDigest = createHash('sha256').update(providedSecret).digest();\n    const expectedDigest = createHash('sha256').update(expectedSecret).digest();\n    if (!timingSafeEqual(providedDigest, expectedDigest)) {\n      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.SEED_ADMIN_SECRET_INVALID,\n        context: { headerKey: ExternalDataAdminEndpointHeaderKey },\n      });\n    }\n\n    next();\n  }\n\n  /**\n   * GET /pipelines — every DECLARED pipeline, joined with its persisted state.\n   *\n   * Declaration-first rather than state-first on purpose: a pipeline that has never run has no\n   * state row, and it is exactly the one an operator is looking for when something is wrong.\n   * Listing from state would make it invisible.\n   */\n  private async handleListPipelines(_req: Request, res: Response): Promise<void> {\n    const stateContext = await this.executionContextCreator.createForInternalRepositoryOperation({\n      resourceType: BackendResourceType.EXTERNAL_DATA_PIPELINE_STATE,\n      operationIdentifier: CoreResourceOperation.READ,\n    } as never);\n    const stateRepo = this.repositoriesRegistry.getRepositoryOrThrow(\n      BackendResourceType.EXTERNAL_DATA_PIPELINE_STATE as unknown as ResourceType,\n      stateContext,\n    );\n\n    const pipelines = await Promise.all(\n      this.pipelineRunService.listDeclaredPipelines().map(async ({ resourceType, declaration }) => {\n        const state = await stateRepo.read<ExternalDataPipelineState>(stateContext, { pipelineResourceType: resourceType });\n        return {\n          resourceType,\n          providerRef: declaration.binding.providerRef,\n          remoteEntityRef: declaration.binding.entityRef,\n          dialect: declaration.binding.dialect,\n          population: declaration.population,\n          orphanPolicy: declaration.orphanPolicy,\n          scheduleCron: declaration.scheduleCron ?? null,\n          maxRowsPerRun: declaration.maxRowsPerRun,\n          // `cursor !== null` means a pass is IN FLIGHT — and therefore that the next run will not\n          // sweep orphans. Surfaced because it is the single most confusing state to debug blind.\n          cursor: state?.cursor ?? null,\n          passStartedAt: state?.passStartedAt ?? null,\n          lastRunAt: state?.lastRunAt ?? null,\n          lastRunSummary: state?.lastRunSummary ?? null,\n        };\n      }),\n    );\n\n    res.json({ pipelines });\n  }\n\n  /** POST /run — run one pipeline now, and answer with the run report. */\n  private async handleRunPipeline(req: Request, res: Response): Promise<void> {\n    const parsed = RunPipelineRequestSchema.safeParse(req.body);\n    if (!parsed.success) {\n      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.VALIDATION,\n        context: { issues: parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`) },\n      });\n    }\n    const { resourceType } = parsed.data;\n\n    const declared = this.pipelineRunService.listDeclaredPipelines().some((entry) => entry.resourceType === resourceType);\n    if (!declared) {\n      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.VALIDATION,\n        context: {\n          message: `Resource '${resourceType}' declares no externalDataPipeline. GET ${ExternalDataAdminEndpointMountBasePath}${ExternalDataAdminEndpointPath.PIPELINES} lists the ones that do.`,\n        },\n      });\n    }\n\n    // ADMIN_MANUAL, not SCHEDULED_RERUN: the run ledger should record that a human asked.\n    const report = await this.pipelineRunService.runPipeline({\n      resourceType,\n      triggerOrigin: DataSeedTriggerOrigin.ADMIN_MANUAL,\n      triggeredByUserId: null,\n    });\n\n    res.json(report);\n  }\n}\n"]}