@fjall/schema-gate 20.0.0 → 21.1.0

package/dist/.build-source-hash

@@ -9,16 +9,22 @@
     "package.json",
     "tsconfig.json"
   ],
-  "hash": "c9486b00a2df3c22134ea678a22dc1c7724c567938464633624ceb0713f33f29",
+  "hash": "a8bfe6deb4a7b2982b70aaae34fb5669ffdb83ba87f98bd55abe0b6da0f1a188",
   "files": {
-    "src/bin.ts": "3acde81b3b914cc4",
-    "src/index.ts": "ab1151c1b7f1bc38",
-    "src/runSchemaGate.ts": "f0a4b0fec6a095de",
-    "src/types.ts": "67a71f4a53cc1e83",
+    "src/bin.ts": "220357c51746d4bc",
+    "src/classifyPgError.ts": "d89aa698e2c2d524",
+    "src/constants.ts": "7f79df8a6c9f56e6",
+    "src/errorMessage.ts": "b1a2b894374a5401",
+    "src/index.ts": "ccef506f884cbdb1",
+    "src/outcomes.ts": "3f5b42d3e1376dc1",
+    "src/reduceOutcomes.ts": "9f55c509577e0dc9",
+    "src/runSchemaGate.ts": "2efd6d45e4224d38",
+    "src/types.ts": "917f272ff8fc052f",
+    "src/withRetry.ts": "855bb351c8dab0fd",
     "../scripts/minify-dist.mjs": "6b2e4b0df8aec601",
-    "package.json": "76d147d6257c2efa",
+    "package.json": "a8c1f80c1eaf67fd",
     "tsconfig.json": "8a11f0e3fce6a36a"
   },
-  "outputHash": "7d6a19dccfe4e0492be3059a42b7d1a6f92f5d13a09b9678b3f3d27d59addca0",
-  "outputFileCount": 9
+  "outputHash": "12d3f76751e40922d0608a51baddb56e78f6ca0033360d1aa2d73dc76925e8ef",
+  "outputFileCount": 21
 }

package/dist/.minified

@@ -1 +1 @@
-4 files minified at 2026-08-24T18:04:58.941Z
+10 files minified at 2026-08-28T12:40:18.192Z

package/dist/bin.d.ts

@@ -5,5 +5,13 @@
  * code — the dependent app containers' `dependsOn: SUCCESS` turns any
  * non-zero exit into a pre-RUNNING task stop the deployment circuit breaker
  * can count.
+ *
+ * The ClickHouse half authenticates as `fjall_schema_gate` — a dedicated
+ * read-only identity (`readonly=2`, `SELECT` on the audit table only, no
+ * per-user concurrency cap) — never as the schema admin the migration task
+ * and maintenance sidecars use. The retry budget is derived from the
+ * construct's ECS `startTimeout` (`SCHEMA_GATE_START_TIMEOUT_SECONDS`): the
+ * run must end with a verdict inside that window, so the budget cannot be a
+ * number chosen here independently of it.
  */
 export {};

package/dist/bin.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-var m=Object.defineProperty;var o=(e,t)=>m(e,"name",{value:t,configurable:!0});import{createFjallClickHouseClient as p}from"@fjall/clickhouse";import{getErrorMessage as s,maskSensitiveOutput as a}from"@fjall/util";import d from"pg";import{runSchemaGate as f}from"./runSchemaGate.js";import{SCHEMA_GATE_EXIT as S}from"./types.js";const{Client:g}=d,w="FjallSchemaGate",i=1e4;function r(e,t,n={}){process.stdout.write(`${JSON.stringify({timestamp:new Date().toISOString(),level:e,namespace:w,message:t,...n})}
-`)}o(r,"log");function u(e,t){return new g({connectionString:e,connectionTimeoutMillis:i,query_timeout:i,statement_timeout:i,...t?{ssl:{rejectUnauthorized:!1}}:{}})}o(u,"buildPgClient");const C={async connectPg(e){const t=u(e,!0);try{return await t.connect(),t}catch(n){if(!/does not support SSL/i.test(s(n)))throw n;await t.end().catch(l=>{r("warn","Postgres TLS probe cleanup failed",{error:a(s(l))})}),r("info","Server does not support TLS \u2014 connecting in plaintext");const c=u(e,!1);return await c.connect(),c}},createChClient(e){return p({url:e.url,username:e.username,password:e.password,...e.caCert!==void 0?{caCert:e.caCert}:{},request_timeout:i})},sleep:o(e=>new Promise(t=>setTimeout(t,e)),"sleep"),log:r};for(const[e,t]of[["SIGTERM",143],["SIGINT",130]])process.on(e,()=>{r("warn",`Received ${e} \u2014 exiting without a verdict`),process.exit(t)});f(process.env,C).then(e=>{process.exit(e)}).catch(e=>{r("error","Gate crashed",{error:a(s(e))}),process.exit(S.configError)});
+var f=Object.defineProperty;var a=(e,r)=>f(e,"name",{value:r,configurable:!0});import{createFjallClickHouseClient as l}from"@fjall/clickhouse";import{getErrorMessage as o,maskSensitiveOutput as i}from"@fjall/util";import{sleepAbortable as d}from"@fjall/util/migration";import w from"pg";import{DB_TIMEOUT_MS as s,LIVENESS_PING_TIMEOUT_MS as g}from"./constants.js";import{runSchemaGate as S}from"./runSchemaGate.js";import{SCHEMA_GATE_EXIT as h}from"./types.js";const{Client:C}=w,_="FjallSchemaGate";function n(e,r,t={}){process.stdout.write(`${JSON.stringify({timestamp:new Date().toISOString(),level:e,namespace:_,message:r,...t})}
+`)}a(n,"log");function u(e,r){return new C({connectionString:e,connectionTimeoutMillis:s,query_timeout:s,statement_timeout:s,...r?{ssl:{rejectUnauthorized:!1}}:{}})}a(u,"buildPgClient");const T={async connectPg(e){const r=u(e,!0);try{return await r.connect(),r}catch(t){if(!/does not support SSL/i.test(o(t)))throw t;await r.end().catch(p=>{n("warn","Postgres TLS probe cleanup failed",{error:i(o(p))})}),n("info","Server does not support TLS \u2014 connecting in plaintext");const c=u(e,!1);return await c.connect(),c}},createChClient(e){return l({url:e.url,username:e.username,password:e.password,...e.caCert!==void 0?{caCert:e.caCert}:{},request_timeout:s})},async pingCh(e){let r;try{r=l({url:e.url,...e.caCert!==void 0?{caCert:e.caCert}:{},request_timeout:g});const t=await r.ping({select:!1});return t.success||n("warn","Liveness ping failed",{error:i(o(t.error))}),t.success}catch(t){return n("warn","Liveness ping threw",{error:i(o(t))}),!1}finally{r!==void 0&&await r.close().catch(t=>{n("warn","Liveness ping client close failed",{error:i(o(t))})})}},sleep:d,random:Math.random,now:Date.now,log:n},m=new AbortController;for(const[e,r]of[["SIGTERM",143],["SIGINT",130]])process.on(e,()=>{n("warn",`Received ${e} \u2014 exiting without a verdict`),m.abort(),process.exit(r)});S(process.env,T,m.signal).then(e=>{process.exit(e)}).catch(e=>{n("error","Gate crashed",{error:i(o(e))}),process.exit(h.configError)});

package/dist/classifyPgError.d.ts

@@ -0,0 +1,26 @@
+import type { GateErrorClassification } from "./types.js";
+/**
+ * Postgres SQLSTATE codes the gate branches on (`pg`'s `DatabaseError.code`).
+ * Single source for every class set below.
+ */
+export declare const PG_ERROR_CODES: {
+    readonly UNDEFINED_TABLE: "42P01";
+    readonly TOO_MANY_CONNECTIONS: "53300";
+    readonly CANNOT_CONNECT_NOW: "57P03";
+    readonly INVALID_PASSWORD: "28P01";
+    readonly INVALID_AUTHORIZATION_SPECIFICATION: "28000";
+    readonly INSUFFICIENT_PRIVILEGE: "42501";
+    readonly INVALID_CATALOG_NAME: "3D000";
+};
+export type PgErrorCode = (typeof PG_ERROR_CODES)[keyof typeof PG_ERROR_CODES];
+/**
+ * Classifies any error raised on the Postgres path into the same verdict
+ * shape `classifyClickHouseError` produces — `absent` (migrations table
+ * missing), `busy` (connection cap / server not accepting connections),
+ * `denied` (auth, missing grant, unknown database), `unreachable` (network,
+ * TLS, `pg`'s own timeouts) or `indeterminate`.
+ *
+ * Pre-masked producer: `message` has been through `maskSensitiveOutput` and
+ * bounded AFTER masking — sinks must not re-mask.
+ */
+export declare function classifyPgError(err: unknown): GateErrorClassification;

package/dist/classifyPgError.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var _=(E,t)=>o(E,"name",{value:t,configurable:!0});import{getErrorMessage as I,maskSensitiveOutput as A}from"@fjall/util";import{truncateMasked as S}from"./errorMessage.js";const n={UNDEFINED_TABLE:"42P01",TOO_MANY_CONNECTIONS:"53300",CANNOT_CONNECT_NOW:"57P03",INVALID_PASSWORD:"28P01",INVALID_AUTHORIZATION_SPECIFICATION:"28000",INSUFFICIENT_PRIVILEGE:"42501",INVALID_CATALOG_NAME:"3D000"},T=new Set([n.UNDEFINED_TABLE]),C=new Set([n.TOO_MANY_CONNECTIONS,n.CANNOT_CONNECT_NOW]),c=new Set([n.INVALID_PASSWORD,n.INVALID_AUTHORIZATION_SPECIFICATION,n.INSUFFICIENT_PRIVILEGE,n.INVALID_CATALOG_NAME]),r=new Set(["ECONNREFUSED","ECONNRESET","ETIMEDOUT","ENOTFOUND","EAI_AGAIN","EHOSTUNREACH","ECONNABORTED","EPROTO","ABORT_ERR"]),i=/^(?:ERR_(?:TLS|SSL|OSSL)_|CERT_|UNABLE_TO_|DEPTH_ZERO_SELF_SIGNED_CERT$|SELF_SIGNED_CERT_IN_CHAIN$|HOSTNAME_MISMATCH$)/,a=/^timeout expired$|^Query read timeout$|^Connection terminated|socket hang up/i;function D(E){if(typeof E!="object"||E===null||!("code"in E))return;const t=E.code;return typeof t=="string"&&t!==""?t:void 0}_(D,"readCodeProperty");function u(E){return typeof E=="object"&&E!==null&&"name"in E&&E.name==="AbortError"}_(u,"isAbortError");function f(E){const t=I(E),e=D(E),s=S(A(t)),N=s!==""?s:e??"",O=e!==void 0&&{code:e};if(e!==void 0){if(T.has(e))return{class:"absent",code:e,message:N};if(C.has(e))return{class:"busy",code:e,message:N};if(c.has(e))return{class:"denied",code:e,message:N};if(r.has(e)||i.test(e))return{class:"unreachable",code:e,message:N}}return u(E)||a.test(t)?{class:"unreachable",...O,message:N}:{class:"indeterminate",...O,message:N}}_(f,"classifyPgError");export{n as PG_ERROR_CODES,f as classifyPgError};

package/dist/constants.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Client-side bound on one connect / query. The gate identity carries a
+ * server-side `max_execution_time = 10` (CONST), so client and server agree
+ * on how long a single probe may run.
+ */
+export declare const DB_TIMEOUT_MS = 10000;
+/**
+ * Bound on a post-verdict client close. The verdict is already in hand — a
+ * close that outlives this is abandoned (the process exits right after,
+ * dropping the socket).
+ */
+export declare const CLIENT_CLOSE_TIMEOUT_MS = 2000;
+/** Bound on the forensic `/ping` liveness probe issued after a failed ClickHouse attempt. */
+export declare const LIVENESS_PING_TIMEOUT_MS = 3000;
+/** Worst case one more attempt can cost: probe + close + liveness ping. */
+export declare const ATTEMPT_COST_MS: number;
+/** Slack kept between the retry budget and the ECS `startTimeout` for the final log lines and process exit. */
+export declare const START_TIMEOUT_HEADROOM_MS = 15000;
+/**
+ * Retry budget for `busy` and `indeterminate` failures. Derived from the
+ * construct's `startTimeout` so the two cannot drift: the run — verdict
+ * included — must finish inside the window ECS allows the container.
+ */
+export declare const VERIFY_BUDGET_MS: number;
+/**
+ * Retry budget for `unreachable` failures. Class-sized: a server that does
+ * not answer at all does not deserve the whole window — the deploy should
+ * fail faster and say so.
+ */
+export declare const UNREACHABLE_BUDGET_MS = 45000;
+/** Full-jitter exponential backoff base: attempt n sleeps `random() * min(cap, base * 2^(n-1))`. */
+export declare const BACKOFF_BASE_MS = 1000;
+/** Ceiling on the backoff window before jitter. */
+export declare const BACKOFF_CAP_MS = 10000;
+/** Longest masked error message kept in a log line or outcome detail. */
+export declare const MAX_ERROR_LENGTH = 500;

package/dist/constants.js

@@ -0,0 +1 @@
+import{SCHEMA_GATE_START_TIMEOUT_SECONDS as _}from"@fjall/util/migration";const T=1e4,o=2e3,E=3e3,M=T+o+E,t=15e3,A=_*1e3-t,O=45e3,r=1e3,p=1e4,c=500;export{M as ATTEMPT_COST_MS,r as BACKOFF_BASE_MS,p as BACKOFF_CAP_MS,o as CLIENT_CLOSE_TIMEOUT_MS,T as DB_TIMEOUT_MS,E as LIVENESS_PING_TIMEOUT_MS,c as MAX_ERROR_LENGTH,t as START_TIMEOUT_HEADROOM_MS,O as UNREACHABLE_BUDGET_MS,A as VERIFY_BUDGET_MS};

package/dist/errorMessage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bound an ALREADY-MASKED message. Mask before truncate: cutting a
+ * credential mid-token breaks the mask regex anchors, so the full string is
+ * masked first and only the masked output is shortened.
+ */
+export declare function truncateMasked(masked: string): string;
+/** Masked, bounded message for any thrown value — safe for every sink. */
+export declare function maskedError(err: unknown): string;

package/dist/errorMessage.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var t=(r,o)=>n(r,"name",{value:o,configurable:!0});import{getErrorMessage as i,maskSensitiveOutput as u}from"@fjall/util";import{MAX_ERROR_LENGTH as e}from"./constants.js";function p(r){return r.length>e?`${r.slice(0,e)}...`:r}t(p,"truncateMasked");function m(r){return p(u(i(r)))}t(m,"maskedError");export{m as maskedError,p as truncateMasked};

package/dist/index.d.ts

@@ -1,2 +1,7 @@
-export { CONNECTION_ATTEMPTS, RETRY_DELAY_MS, runSchemaGate, } from "./runSchemaGate.js";
-export { SCHEMA_GATE_EXIT, type SchemaGateChClientOpts, type SchemaGateChHandle, type SchemaGateDeps, type SchemaGateExitCode, type SchemaGateLogLevel, type SchemaGateLogger, type SchemaGatePgHandle, } from "./types.js";
+export { PG_ERROR_CODES, type PgErrorCode, classifyPgError, } from "./classifyPgError.js";
+export { ATTEMPT_COST_MS, BACKOFF_BASE_MS, BACKOFF_CAP_MS, CLIENT_CLOSE_TIMEOUT_MS, DB_TIMEOUT_MS, LIVENESS_PING_TIMEOUT_MS, MAX_ERROR_LENGTH, START_TIMEOUT_HEADROOM_MS, UNREACHABLE_BUDGET_MS, VERIFY_BUDGET_MS, } from "./constants.js";
+export { type OutcomeBase, type TargetOutcome } from "./outcomes.js";
+export { type ReducibleOutcome, reduceOutcomes, type TargetOutcomeKind, } from "./reduceOutcomes.js";
+export { runSchemaGate } from "./runSchemaGate.js";
+export { SCHEMA_GATE_EXIT, type GateErrorClass, type GateErrorClassification, type SchemaGateChClientOpts, type SchemaGateChHandle, type SchemaGateChPingOpts, type SchemaGateDeps, type SchemaGateExitCode, type SchemaGateExitKind, type SchemaGateLogLevel, type SchemaGateLogger, type SchemaGatePgHandle, } from "./types.js";
+export { type GateTarget, type Liveness, type RetryResult, type WithRetryOpts, withRetry, } from "./withRetry.js";

package/dist/index.js

@@ -1 +1 @@
-import{CONNECTION_ATTEMPTS as r,RETRY_DELAY_MS as _,runSchemaGate as e}from"./runSchemaGate.js";import{SCHEMA_GATE_EXIT as A}from"./types.js";export{r as CONNECTION_ATTEMPTS,_ as RETRY_DELAY_MS,A as SCHEMA_GATE_EXIT,e as runSchemaGate};
+import{PG_ERROR_CODES as T,classifyPgError as r}from"./classifyPgError.js";import{ATTEMPT_COST_MS as M,BACKOFF_BASE_MS as o,BACKOFF_CAP_MS as O,CLIENT_CLOSE_TIMEOUT_MS as e,DB_TIMEOUT_MS as A,LIVENESS_PING_TIMEOUT_MS as R,MAX_ERROR_LENGTH as t,START_TIMEOUT_HEADROOM_MS as C,UNREACHABLE_BUDGET_MS as I,VERIFY_BUDGET_MS as m}from"./constants.js";import{reduceOutcomes as B}from"./reduceOutcomes.js";import{runSchemaGate as U}from"./runSchemaGate.js";import{SCHEMA_GATE_EXIT as x}from"./types.js";import{withRetry as F}from"./withRetry.js";export{M as ATTEMPT_COST_MS,o as BACKOFF_BASE_MS,O as BACKOFF_CAP_MS,e as CLIENT_CLOSE_TIMEOUT_MS,A as DB_TIMEOUT_MS,R as LIVENESS_PING_TIMEOUT_MS,t as MAX_ERROR_LENGTH,T as PG_ERROR_CODES,x as SCHEMA_GATE_EXIT,C as START_TIMEOUT_HEADROOM_MS,I as UNREACHABLE_BUDGET_MS,m as VERIFY_BUDGET_MS,r as classifyPgError,B as reduceOutcomes,U as runSchemaGate,F as withRetry};

package/dist/outcomes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-target verdicts: the shape each verifier produces, the mapping from a
+ * retry failure to that shape, and the final forensic log line per kind.
+ * Kept apart from the orchestrator so a new outcome kind is added in one
+ * place and both the exhaustive log switch and `reduceOutcomes` reject a
+ * missed variant at compile time.
+ */
+import type { SchemaGateDeps } from "./types.js";
+import type { GateTarget, Liveness, RetryResult } from "./withRetry.js";
+export interface OutcomeBase {
+    target: GateTarget;
+    expected: string;
+    attempts: number;
+    elapsedMs: number;
+}
+export type TargetOutcome = OutcomeBase & ({
+    kind: "pass";
+    actual: string | null;
+} | {
+    kind: "refused";
+    actual: string | null;
+    detail?: string;
+} | {
+    kind: "denied";
+    code?: string;
+    detail: string;
+} | {
+    kind: "busy";
+    code?: string;
+    scope?: "user" | "server";
+    detail: string;
+    abortedBySibling: boolean;
+} | {
+    kind: "unreachable";
+    code?: string;
+    /** The server answered with an error the gate cannot classify — it was NOT absent. */
+    indeterminate: boolean;
+    liveness?: Liveness;
+    detail: string;
+    abortedBySibling: boolean;
+});
+/** Map a retry failure to the outcome the reducer and the final log consume. */
+export declare function outcomeFromFailure(target: GateTarget, expected: string, result: Extract<RetryResult<unknown>, {
+    ok: false;
+}>, absentDetail: string): TargetOutcome;
+/**
+ * One final line per target. Every non-pass line carries `attempts` and
+ * `elapsedMs`; the indeterminate arm says "indeterminate error", never
+ * "unreachable" — the forensic log must not claim the server was absent when
+ * it answered.
+ */
+export declare function logOutcome(deps: SchemaGateDeps, o: TargetOutcome): void;

package/dist/outcomes.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var c=(t,e)=>g(t,"name",{value:e,configurable:!0});import{SCHEMA_GATE_EXIT_HINTS as l}from"@fjall/util/migration";import{truncateMasked as h}from"./errorMessage.js";function y(t,e,r,i){const{classification:n,attempts:u,elapsedMs:f,abortedBySibling:o}=r,a={target:t,expected:e,attempts:u,elapsedMs:f},d=n.code!==void 0&&{code:n.code},s=h(n.message);switch(n.class){case"absent":return{...a,kind:"refused",actual:null,detail:i};case"denied":return{...a,kind:"denied",...d,detail:s};case"busy":return{...a,kind:"busy",...d,...n.scope!==void 0&&{scope:n.scope},detail:s,abortedBySibling:o};case"unreachable":case"indeterminate":return{...a,kind:"unreachable",...d,indeterminate:n.class==="indeterminate",...r.liveness!==void 0&&{liveness:r.liveness},detail:s,abortedBySibling:o};default:{const b=n.class;throw new Error(`unhandled error class ${String(b)}`)}}}c(y,"outcomeFromFailure");function v(t,e){const r={target:e.target,expected:e.expected,attempts:e.attempts,elapsedMs:e.elapsedMs};switch(e.kind){case"pass":t.log("info","Schema version satisfied",{target:e.target,expected:e.expected,actual:e.actual});return;case"refused":t.log("error","REFUSED \u2014 schema version not satisfied",{...r,actual:e.actual,...e.detail!==void 0&&{detail:e.detail}});return;case"denied":t.log("error","DENIED \u2014 gate identity rejected by the server",{...r,...e.code!==void 0&&{code:e.code},error:e.detail,hint:l.denied});return;case"busy":t.log("error","BUSY \u2014 server refused the probe a slot for the whole budget",{...r,...e.code!==void 0&&{code:e.code},...e.scope!==void 0&&{scope:e.scope},error:e.detail,abortedBySibling:e.abortedBySibling,hint:l.busy});return;case"unreachable":t.log("error",e.indeterminate?"Verification target failed with an indeterminate error after retries":"Verification target unreachable after retries",{...r,...e.code!==void 0&&{code:e.code},indeterminate:e.indeterminate,...e.liveness!==void 0&&{liveness:e.liveness},error:e.detail,abortedBySibling:e.abortedBySibling,hint:l.connectionError});return;default:{const i=e;throw new Error(`unhandled outcome ${String(i)}`)}}}c(v,"logOutcome");export{v as logOutcome,y as outcomeFromFailure};

package/dist/reduceOutcomes.d.ts

@@ -0,0 +1,19 @@
+import type { SchemaGateExitKind } from "./types.js";
+export type TargetOutcomeKind = "pass" | "refused" | "busy" | "denied" | "unreachable";
+/**
+ * What the reducer sees per target: a verified outcome kind, or
+ * `configError` for a target whose verification rejected before it could
+ * produce one.
+ */
+export interface ReducibleOutcome {
+    kind: TargetOutcomeKind | "configError";
+}
+/**
+ * Reduce every target's outcome to one exit kind. Precedence:
+ * `configError` > `refused` > `denied` > `busy` > `connectionError` > `pass`
+ * — definitive evidence outranks indeterminate, and of the two
+ * indeterminate kinds `busy` carries the more specific cure. An empty list
+ * reduces to `pass` (the caller guards "nothing to verify" before reaching
+ * here).
+ */
+export declare function reduceOutcomes(outcomes: readonly ReducibleOutcome[]): SchemaGateExitKind;

package/dist/reduceOutcomes.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var n=(e,r)=>t(e,"name",{value:r,configurable:!0});const s={configError:0,refused:1,denied:2,busy:3,connectionError:4,pass:5};function u(e){switch(e){case"pass":return"pass";case"refused":return"refused";case"denied":return"denied";case"busy":return"busy";case"unreachable":return"connectionError";case"configError":return"configError";default:{const r=e;throw new Error(`unhandled outcome kind ${String(r)}`)}}}n(u,"exitKindFor");function i(e){let r="pass";for(const c of e){const o=u(c.kind);s[o]<s[r]&&(r=o)}return r}n(i,"reduceOutcomes");export{i as reduceOutcomes};

package/dist/runSchemaGate.d.ts

@@ -8,22 +8,24 @@
  * migrations must boot), and returns an exit code from the taxonomy in
  * `types.ts`.
  *
- * Connection attempts are bounded: `CONNECTION_ATTEMPTS` tries,
- * `RETRY_DELAY_MS` apart, per target. Targets verify in parallel so the
- * worst-case wall clock stays inside the dependent containers'
- * `startTimeout` (120s) with headroom.
+ * Every failure is classified (`classifyClickHouseError` from
+ * `@fjall/clickhouse`, `classifyPgError` here) so the verdict says what the
+ * server did — answered and refused a slot (`busy`), answered and rejected
+ * the identity (`denied`), or did not answer (`connectionError`) — and the
+ * retry policy in `withRetry.ts` waits out transient classes inside a budget
+ * derived from the container's ECS `startTimeout`. Targets verify in
+ * parallel; a definitive verdict on one aborts the other's backoff.
+ *
+ * The ClickHouse half authenticates as the read-only `fjall_schema_gate`
+ * identity (`FJALL_SCHEMA_GATE_CH_*` env), never as the schema admin. The
+ * OCI image (`Dockerfile`) is unchanged by this: it is a build of this
+ * package.
  */
 import { type SchemaGateDeps, type SchemaGateExitCode } from "./types.js";
-export declare const CONNECTION_ATTEMPTS = 3;
-export declare const RETRY_DELAY_MS = 5000;
-/**
- * Bound on how long a post-verdict client close may hold up the exit path.
- * The verdict is already in hand — a close that outlives this is abandoned
- * (the process exits immediately after, dropping the socket).
- */
-export declare const CLIENT_CLOSE_TIMEOUT_MS = 2000;
 /**
  * Run every configured verification target and reduce to one exit code.
- * See `SCHEMA_GATE_EXIT` for the taxonomy and its precedence rules.
+ * See `SCHEMA_GATE_EXIT` for the taxonomy and `reduceOutcomes` for the
+ * precedence rules. `externalSignal` (process shutdown) composes with the
+ * sibling-verdict controller so either stops an in-flight backoff.
  */
-export declare function runSchemaGate(env: Record<string, string | undefined>, deps: SchemaGateDeps): Promise<SchemaGateExitCode>;
+export declare function runSchemaGate(env: Record<string, string | undefined>, deps: SchemaGateDeps, externalSignal?: AbortSignal): Promise<SchemaGateExitCode>;

package/dist/runSchemaGate.js

@@ -1 +1 @@
-var R=Object.defineProperty;var i=(e,t)=>R(e,"name",{value:t,configurable:!0});import{verifyExpectedClickHouseSchemaVersion as k}from"@fjall/clickhouse";import{maskSensitiveOutput as H}from"@fjall/util";import{EXPECTED_CH_SCHEMA_VERSION_ENV as m,EXPECTED_SCHEMA_VERSION_ENV as p,EXPECTED_SCHEMA_VERSION_TOOL_ENV as C,SCHEMA_ADMIN_PASSWORD_ENV as M,SCHEMA_ADMIN_USER_ENV as b,SCHEMA_GATE_CH_CA_CERT_ENV as P,SCHEMA_GATE_CH_DATABASE_ENV as V,SCHEMA_GATE_CH_URL_ENV as D,SCHEMA_GATE_DB_PASSWORD_ENV as G,SCHEMA_GATE_DB_URL_BASE_ENV as S,SCHEMA_GATE_DB_USER_ENV as O,verifyExpectedSchemaVersion as U}from"@fjall/util/migration";import{SCHEMA_GATE_EXIT as f}from"./types.js";const g=3,x=5e3,w=500,v="42P01",I=new Set(["60","81"]),$=2e3,L=new Set(["postgresql:","postgres:"]);class _ extends Error{static{i(this,"GateConfigError")}}function d(e){const t=e instanceof Error?e.message:String(e),a=H(t);return a.length>w?`${a.slice(0,w)}...`:a}i(d,"maskedError");function E(e,t,a){const r=e[t];if(r===void 0||r==="")throw new _(`${a}, but ${t} is missing or empty. The construct injects both together \u2014 an incomplete set points at an author override or a framework bug.`);return r}i(E,"requireEnv");function B(e,t,a){let r;try{r=new URL(e)}catch{throw new _(`${S} is not a parseable URL`)}if(!L.has(r.protocol))throw new _(`${S} has scheme '${r.protocol}' \u2014 the materialised gate supports the postgres engine family only. Set schemaGate: { materialise: false } for this service.`);return r.username=encodeURIComponent(t),r.password=encodeURIComponent(a),r.searchParams.delete("sslmode"),r.toString()}i(B,"composePgUrl");function y(e){return typeof e=="object"&&e!==null&&"code"in e&&e.code===v}i(y,"isUndefinedTableError");function A(e){if(typeof e!="object"||e===null)return!1;const t=e.code;return typeof t=="string"&&I.has(t)}i(A,"isChNeverMigratedError");async function T(e,t,a){await Promise.race([a().catch(r=>{e.log("warn",`${t} client close failed`,{error:d(r)})}),e.sleep($)])}i(T,"closeWithTimeout");async function N(e,t,a){let r;for(let n=1;n<=g;n++)try{return await a()}catch(s){if(r=s,y(s)||A(s))throw s;e.log("warn","Verification attempt failed",{target:t,attempt:n,of:g,error:d(s)}),n<g&&await e.sleep(x)}throw r}i(N,"withRetry");async function X(e,t,a){const r=`${p} is set`,n=E(e,C,r);if(n!=="prisma")throw new _(`${C}='${n}' \u2014 the materialised gate supports tool "prisma" only (a custom tool's metadata query cannot be expressed through the env contract). Set schemaGate: { materialise: false } for this service.`);const s=E(e,S,r),u=E(e,O,r),l=E(e,G,r),o=B(s,u,l);try{const c=await N(t,"postgres",async()=>{const h=await t.connectPg(o);try{return await U({tool:"prisma",expected:a,client:h})}finally{await T(t,"Postgres",()=>h.end())}});return{target:"postgres",kind:c.matches?"pass":"refused",expected:a,actual:c.actual}}catch(c){return y(c)?{target:"postgres",kind:"refused",expected:a,actual:null,detail:"migrations table absent \u2014 the database has never been migrated while the deployed image expects a schema version"}:{target:"postgres",kind:"connection-error",expected:a,detail:d(c)}}}i(X,"verifyPostgres");async function j(e,t,a){const r=`${m} is set`,n=E(e,D,r),s=E(e,b,r),u=E(e,M,r),l=e[P],o=e[V];try{const c=await N(t,"clickhouse",async()=>{const h=t.createChClient({url:n,username:s,password:u,...l!==void 0&&l!==""?{caCert:l}:{}});try{return await k({client:h,expected:a,...o!==void 0&&o!==""?{database:o}:{}})}finally{await T(t,"ClickHouse",()=>h.close())}});return{target:"clickhouse",kind:c.matches?"pass":"refused",expected:a,actual:c.actual}}catch(c){return A(c)?{target:"clickhouse",kind:"refused",expected:a,actual:null,detail:"migrations audit table absent \u2014 the ClickHouse database has never been migrated while the deployed image expects a schema version"}:{target:"clickhouse",kind:"connection-error",expected:a,detail:d(c)}}}i(j,"verifyClickHouse");async function J(e,t){const a=e[p],r=e[m],n=a!==void 0&&a!=="",s=r!==void 0&&r!=="";if(!n&&!s)return t.log("error","Nothing to verify \u2014 no expected-version env present",{hint:`neither ${p} nor ${m} is set; the construct should never materialise a gate container without one`}),f.configError;const u=[];n&&u.push(X(e,t,a)),s&&u.push(j(e,t,r));let l;try{l=await Promise.all(u)}catch(o){return o instanceof _?(t.log("error","Gate configuration invalid",{error:d(o)}),f.configError):(t.log("error","Gate failed unexpectedly",{error:d(o)}),f.configError)}for(const o of l)o.kind==="pass"?t.log("info","Schema version satisfied",{target:o.target,expected:o.expected,actual:o.actual??null}):o.kind==="refused"?t.log("error","REFUSED \u2014 schema version not satisfied",{target:o.target,expected:o.expected,actual:o.actual??null,...o.detail!==void 0?{detail:o.detail}:{}}):t.log("error","Verification target unreachable after retries",{target:o.target,expected:o.expected,attempts:g,...o.detail!==void 0?{error:o.detail}:{}});return l.some(o=>o.kind==="refused")?f.refused:l.some(o=>o.kind==="connection-error")?f.connectionError:f.pass}i(J,"runSchemaGate");export{$ as CLIENT_CLOSE_TIMEOUT_MS,g as CONNECTION_ATTEMPTS,x as RETRY_DELAY_MS,J as runSchemaGate};
+var b=Object.defineProperty;var i=(e,t)=>b(e,"name",{value:t,configurable:!0});import{classifyClickHouseError as N,verifyExpectedClickHouseSchemaVersion as M}from"@fjall/clickhouse";import{EXPECTED_CH_SCHEMA_VERSION_ENV as p,EXPECTED_SCHEMA_VERSION_ENV as g,EXPECTED_SCHEMA_VERSION_TOOL_ENV as A,SCHEMA_GATE_CH_CA_CERT_ENV as P,SCHEMA_GATE_CH_DATABASE_ENV as R,SCHEMA_GATE_CH_PASSWORD_ENV as k,SCHEMA_GATE_CH_URL_ENV as G,SCHEMA_GATE_CH_USER_ENV as V,SCHEMA_GATE_DB_PASSWORD_ENV as v,SCHEMA_GATE_DB_URL_BASE_ENV as C,SCHEMA_GATE_DB_USER_ENV as D,verifyExpectedSchemaVersion as I}from"@fjall/util/migration";import{classifyPgError as O}from"./classifyPgError.js";import{CLIENT_CLOSE_TIMEOUT_MS as U}from"./constants.js";import{maskedError as S}from"./errorMessage.js";import{logOutcome as $,outcomeFromFailure as w}from"./outcomes.js";import{reduceOutcomes as L}from"./reduceOutcomes.js";import{SCHEMA_GATE_EXIT as y}from"./types.js";import{withRetry as T}from"./withRetry.js";const B=new Set(["postgresql:","postgres:"]),x="migrations table absent \u2014 the database has never been migrated while the deployed image expects a schema version",F="migrations audit table absent \u2014 the ClickHouse database has never been migrated while the deployed image expects a schema version",X=new Set(["refused","denied"]);class _ extends Error{static{i(this,"GateConfigError")}}function h(e,t,r){const s=e[t];if(s===void 0||s==="")throw new _(`${r}, but ${t} is missing or empty. The construct injects both together \u2014 an incomplete set points at an author override or a framework bug.`);return s}i(h,"requireEnv");function q(e,t,r){let s;try{s=new URL(e)}catch{throw new _(`${C} is not a parseable URL`)}if(!B.has(s.protocol))throw new _(`${C} has scheme '${s.protocol}' \u2014 the materialised gate supports the postgres engine family only. Set schemaGate: { materialise: false } for this service.`);return s.username=encodeURIComponent(t),s.password=encodeURIComponent(r),s.searchParams.delete("sslmode"),s.toString()}i(q,"composePgUrl");async function H(e,t,r){await Promise.race([r().catch(s=>{e.log("warn",`${t} client close failed`,{error:S(s)})}),e.sleep(U)])}i(H,"closeWithTimeout");async function W(e,t,r,s){const n=`${g} is set`,l=h(e,A,n);if(l!=="prisma")throw new _(`${A}='${l}' \u2014 the materialised gate supports tool "prisma" only (a custom tool's metadata query cannot be expressed through the env contract). Set schemaGate: { materialise: false } for this service.`);const f=h(e,C,n),u=h(e,D,n),E=h(e,v,n),m=q(f,u,E),o=await T(t,{target:"postgres",signal:s,classify:O,attempt:i(async()=>{const a=await t.connectPg(m);try{return await I({tool:"prisma",expected:r,client:a})}finally{await H(t,"Postgres",()=>a.end())}},"attempt")});return o.ok?{target:"postgres",expected:r,attempts:o.attempts,elapsedMs:o.elapsedMs,kind:o.value.matches?"pass":"refused",actual:o.value.actual}:w("postgres",r,o,x)}i(W,"verifyPostgres");async function j(e,t,r,s){const n=`${p} is set`,l=h(e,G,n),f=h(e,V,n),u=h(e,k,n),E=e[P],m=e[R],o=E!==void 0&&E!==""&&{caCert:E},a=await T(t,{target:"clickhouse",signal:s,classify:N,liveness:i(()=>t.pingCh({url:l,...o}),"liveness"),attempt:i(async()=>{const c=t.createChClient({url:l,username:f,password:u,...o});try{return await M({client:c,expected:r,...m!==void 0&&m!==""?{database:m}:{}})}finally{await H(t,"ClickHouse",()=>c.close())}},"attempt")});return a.ok?{target:"clickhouse",expected:r,attempts:a.attempts,elapsedMs:a.elapsedMs,kind:a.value.matches?"pass":"refused",actual:a.value.actual}:w("clickhouse",r,a,F)}i(j,"verifyClickHouse");async function oe(e,t,r){const s=e[g],n=e[p],l=s!==void 0&&s!=="",f=n!==void 0&&n!=="";if(!l&&!f)return t.log("error","Nothing to verify \u2014 no expected-version env present",{hint:`neither ${g} nor ${p} is set; the construct should never materialise a gate container without one`}),y.configError;const u=new AbortController,E=r===void 0?u.signal:AbortSignal.any([r,u.signal]),m=i(c=>c.then(d=>(X.has(d.kind)&&u.abort(),d),d=>{throw u.abort(),d}),"settleFast"),o=[];l&&o.push(m(W(e,t,s,E))),f&&o.push(m(j(e,t,n,E)));const a=[];for(const c of await Promise.allSettled(o)){if(c.status==="fulfilled"){$(t,c.value),a.push(c.value);continue}c.reason instanceof _?t.log("error","Gate configuration invalid",{error:S(c.reason)}):t.log("error","Gate failed unexpectedly",{error:S(c.reason)}),a.push({kind:"configError"})}return y[L(a)]}i(oe,"runSchemaGate");export{oe as runSchemaGate};

package/dist/types.d.ts

@@ -1,32 +1,33 @@
 /**
- * Exit taxonomy for the materialised gate container. The dependent app
- * containers declare `dependsOn: [{ container: "fjall-schema-gate",
- * condition: "SUCCESS" }]`, so ANY non-zero exit stops the task pre-RUNNING
- * and counts toward the deployment circuit breaker's stage-1 arithmetic —
- * the codes exist for the forensic log and the deploy-time ECS tail, not for
- * ECS itself.
+ * Exit taxonomy for the materialised gate container. The codes live in
+ * `@fjall/util/migration` (`SCHEMA_GATE_EXIT`) because the runner emits
+ * them, deploy-core's deployment tail translates them, and the constructs'
+ * docs cite them — re-exported here so this package's public surface and
+ * its own `bin.ts` read one name.
  *
  * - `pass` (0) — every configured target verified; app containers start.
  * - `refused` (1) — a target's live schema does not satisfy the expected
- *   version (forward skew, or a never-migrated database). The gate did its
- *   job; the deploy must roll back or the migration must land first.
- * - `configError` (2) — the gate could not even attempt verification:
- *   missing/empty env, unsupported tool or engine family, or an internal
- *   error. Points at a construct bug or an author override.
- * - `connectionError` (3) — a target was unreachable after the bounded
- *   retry budget. Indeterminate: the schema may be fine.
+ *   version (forward skew, or a never-migrated database).
+ * - `configError` (2) — the gate could not even attempt verification.
+ * - `connectionError` (3) — the server could not be reached (or answered
+ *   with an error the gate cannot classify) for the whole budget.
+ * - `busy` (4) — the server answered every attempt but refused the probe a
+ *   slot (ClickHouse 202 / 201, Postgres 53300 / 57P03) for the whole budget.
+ * - `denied` (5) — the server rejected the gate identity or its grants.
+ *   Definitive after one attempt.
  *
- * Precedence when targets disagree: `configError` is detected before any
- * connection is attempted; a verified `refused` outranks `connectionError`
- * (a refusal is definitive evidence, an unreachable sibling is not).
+ * Precedence: `configError` > `refused` > `denied` > `busy` >
+ * `connectionError` > `pass` — see `reduceOutcomes`.
  */
-export declare const SCHEMA_GATE_EXIT: {
-    readonly pass: 0;
-    readonly refused: 1;
-    readonly configError: 2;
-    readonly connectionError: 3;
-};
-export type SchemaGateExitCode = (typeof SCHEMA_GATE_EXIT)[keyof typeof SCHEMA_GATE_EXIT];
+export { SCHEMA_GATE_EXIT, type SchemaGateExitCode, type SchemaGateExitKind, } from "@fjall/util/migration";
+/**
+ * Failure classification shared by both engines. The union is owned by
+ * `@fjall/clickhouse` (`classifyClickHouseError`); the Postgres classifier
+ * produces the same shape (never `scope`) so the retry policy and outcome
+ * mapping consume one type. Coupled discriminated union — re-exported, not
+ * redeclared.
+ */
+export type { ClickHouseErrorClass as GateErrorClass, ClickHouseErrorClassification as GateErrorClassification, } from "@fjall/clickhouse";
 export type SchemaGateLogLevel = "info" | "warn" | "error";
 /**
  * Structured one-line JSON log sink. The container's stdout lands in the
@@ -58,14 +59,31 @@ export interface SchemaGateChClientOpts {
     password: string;
     caCert?: string;
 }
+export interface SchemaGateChPingOpts {
+    url: string;
+    caCert?: string;
+}
 /**
- * Injectable seams. `bin.ts` supplies the real drivers; tests supply fakes
- * that can express every failure shape (refusal, missing table, connect
- * timeout) — a fake that cannot express the bug shape cannot catch it.
+ * Injectable seams. `bin.ts` supplies the real drivers and clocks; tests
+ * supply fakes that can express every failure shape (refusal, missing
+ * table, a 202 for the whole budget, a sibling verdict mid-backoff) and make
+ * a 105-second budget run in microseconds — a fake that cannot express the
+ * bug shape cannot catch it.
  */
 export interface SchemaGateDeps {
     connectPg(connectionUrl: string): Promise<SchemaGatePgHandle>;
     createChClient(opts: SchemaGateChClientOpts): SchemaGateChHandle;
-    sleep(ms: number): Promise<void>;
+    /**
+     * Bounded liveness probe of the ClickHouse `/ping` endpoint (which does not
+     * authenticate). Resolves `false` on any failure and never throws — the
+     * result is forensic only and never changes a verdict.
+     */
+    pingCh(opts: SchemaGateChPingOpts): Promise<boolean>;
+    /** Abort-aware sleep: resolves early (never rejects) when `signal` fires. */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    /** Uniform sample in [0, 1) for backoff jitter. */
+    random(): number;
+    /** Millisecond clock the retry budget is measured against. */
+    now(): number;
     log: SchemaGateLogger;
 }

package/dist/types.js

@@ -1 +1 @@
-const r={pass:0,refused:1,configError:2,connectionError:3};export{r as SCHEMA_GATE_EXIT};
+import{SCHEMA_GATE_EXIT as r}from"@fjall/util/migration";export{r as SCHEMA_GATE_EXIT};

package/dist/withRetry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Retry policy for one verification target. The loop runs until a verdict:
+ *
+ * - success → done.
+ * - `absent` → stop (a definitive refusal — the table has never existed).
+ * - `denied` → stop after this one attempt (no retry will change it).
+ * - `busy` / `unreachable` / `indeterminate` → full-jitter exponential
+ *   backoff, bounded by a budget sized to the class of the MOST RECENT
+ *   failure: `unreachable` gets `UNREACHABLE_BUDGET_MS`, the rest
+ *   `VERIFY_BUDGET_MS`. The stop rule is checked before sleeping —
+ *   `elapsed + delay + ATTEMPT_COST_MS > budget` ends the run with the last
+ *   classification — so the gate always exits with a verdict before ECS's
+ *   `startTimeout` cuts it off.
+ *
+ * Attempt count is a consequence of the budget, not a constant: the
+ * 2026-08-25 incident (3 × 5s against a minutes-long OPTIMIZE holder) is
+ * exactly the shape a fixed count cannot wait out.
+ */
+import type { GateErrorClassification, SchemaGateDeps } from "./types.js";
+export type Liveness = "alive" | "dead";
+export type GateTarget = "postgres" | "clickhouse";
+export interface WithRetryOpts<T> {
+    target: GateTarget;
+    attempt: () => Promise<T>;
+    classify: (err: unknown) => GateErrorClassification;
+    /** Fires when a sibling target reaches a definitive verdict or the process is shutting down. */
+    signal: AbortSignal;
+    /**
+     * Forensic liveness probe run after an `unreachable` / `indeterminate`
+     * failure. Never changes the class — "the server answered `/ping` while
+     * every query failed" is a different investigation from "nothing answered".
+     */
+    liveness?: () => Promise<boolean>;
+}
+export type RetryResult<T> = {
+    ok: true;
+    value: T;
+    attempts: number;
+    elapsedMs: number;
+} | {
+    ok: false;
+    classification: GateErrorClassification;
+    attempts: number;
+    elapsedMs: number;
+    abortedBySibling: boolean;
+    liveness?: Liveness;
+};
+export declare function withRetry<T>(deps: SchemaGateDeps, opts: WithRetryOpts<T>): Promise<RetryResult<T>>;

package/dist/withRetry.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var a=(e,t)=>w(e,"name",{value:t,configurable:!0});import{ATTEMPT_COST_MS as M,BACKOFF_BASE_MS as m,BACKOFF_CAP_MS as y,LIVENESS_PING_TIMEOUT_MS as _,UNREACHABLE_BUDGET_MS as v,VERIFY_BUDGET_MS as S}from"./constants.js";function h(e){return e.class==="busy"||e.class==="unreachable"||e.class==="indeterminate"}a(h,"isRetryable");function E(e){return e.class==="unreachable"||e.class==="indeterminate"}a(E,"wantsLiveness");function A(e){return e.class==="unreachable"?v:S}a(A,"budgetFor");function B(e,t){const r=Math.min(y,m*2**(t-1));return Math.floor(e.random()*r)}a(B,"backoffDelay");async function T(e,t,r){return await Promise.race([t(),e.sleep(_,r).then(()=>!1)])?"alive":"dead"}a(T,"probeLiveness");async function C(e,t){const r=e.now();let l=0,s;for(;;){l+=1;let n;try{return{ok:!0,value:await t.attempt(),attempts:l,elapsedMs:e.now()-r}}catch(o){n=t.classify(o)}const c=h(n);c&&t.liveness!==void 0&&E(n)&&(s=await T(e,t.liveness,t.signal));const u=e.now()-r,d=A(n),i=c?B(e,l):null,f=i!==null&&u+i+M<=d,b=f&&!t.signal.aborted;e.log("warn","Verification attempt failed",{target:t.target,attempt:l,class:n.class,...n.code!==void 0&&{code:n.code},...n.scope!==void 0&&{scope:n.scope},error:n.message,elapsedMs:u,nextDelayMs:b?i:null,budgetMs:d,...s!==void 0&&{liveness:s}});const g=a(o=>({ok:!1,classification:n,attempts:l,elapsedMs:e.now()-r,abortedBySibling:o,...s!==void 0&&{liveness:s}}),"failed");if(!f)return g(t.signal.aborted);if(b&&await e.sleep(i,t.signal),t.signal.aborted)return e.log("warn","Retry abandoned \u2014 abort signalled before the next attempt",{target:t.target,attempt:l,abortedBySibling:!0}),g(!0)}}a(C,"withRetry");export{C as withRetry};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/schema-gate",
-  "version": "20.0.0",
+  "version": "21.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -51,8 +51,8 @@
   },
   "dependencies": {
     "@clickhouse/client": "^1.23.1",
-    "@fjall/clickhouse": "^20.0.0",
-    "@fjall/util": "^20.0.0",
+    "@fjall/clickhouse": "^21.1.0",
+    "@fjall/util": "^21.1.0",
     "pg": "^8.16.3"
   },
   "engines": {