@starci/hfs 4.13.0 → 4.15.0

package/stack/remote.mjs

@@ -228,7 +228,7 @@ function ciValues(ctx, config) {
     if (!present)
         return { values: ctx.env, sealed: false };
     const map = openSealedMember(ctx, config, CI_MEMBER);
-    return { values: Object.fromEntries(CI_VARIABLES.map((name) => [name, typeof map[name] === 'string' ? map[name] : undefined])), sealed: true };
+    return { values: Object.fromEntries([...CI_VARIABLES, 'VPS_GATE'].map((name) => [name, typeof map[name] === 'string' ? map[name] : undefined])), sealed: true };
 }
 function ciInputs(ctx, values, sealed) {
     for (const name of CI_VARIABLES)
@@ -258,9 +258,10 @@ export async function connectCi(ctx, config, { execute = false } = {}) {
     const { values, sealed } = ciValues(ctx, config);
     const inputs = ciInputs(ctx, values, sealed);
     const alias = config.remote.host;
+    const gated = values.VPS_GATE === '1';
     const origin = sealed ? `the sealed member ${CI_MEMBER}` : 'VPS_SSH_KEY';
-    const plan = [`${dir}/deploy_key (0600) from ${origin}`, `${dir}/known_hosts (0644) from ${sealed ? CI_MEMBER : 'VPS_KNOWN_HOSTS'}`, `a Host ${alias} block in ${dir}/config`, `DOCKER_HOST=ssh://${alias} in GITHUB_ENV`];
-    const data = { host: alias, files: ['deploy_key', 'known_hosts', 'config'], sealed };
+    const plan = [...(gated ? ['STARCI_SSH_GATE=1 in GITHUB_ENV (the key is forced through starci-ssh-gate)'] : []), `${dir}/deploy_key (0600) from ${origin}`, `${dir}/known_hosts (0644) from ${sealed ? CI_MEMBER : 'VPS_KNOWN_HOSTS'}`, `a Host ${alias} block in ${dir}/config`, `DOCKER_HOST=ssh://${alias} in GITHUB_ENV`];
+    const data = { host: alias, files: ['deploy_key', 'known_hosts', 'config'], sealed, gated };
     if (!execute)
         return { ok: true, lines: plan.map((item) => `dry run: would write ${item}`), data };
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -268,7 +269,7 @@ export async function connectCi(ctx, config, { execute = false } = {}) {
     writeWithMode(path.join(dir, 'known_hosts'), inputs.known, 0o644);
     fs.appendFileSync(path.join(dir, 'config'), sshBlock(alias, inputs), { mode: 0o600 });
     fs.appendFileSync(ctx.env.GITHUB_ENV, `DOCKER_HOST=ssh://${alias}
-`);
+${gated ? 'STARCI_SSH_GATE=1' + String.fromCharCode(10) : ''}`);
     // The log of a public repository is public: mask the host, the account and the releases root before any later line can carry them.
     const masks = sealed ? [inputs.host, inputs.user, config.remote.releasesBase].filter((value) => typeof value === 'string' && value.length >= 4).map((value) => `::add-mask::${value}`) : [];
     return { ok: true, lines: [...masks, ...plan.map((item) => `wrote ${item}`)], data };

package/stack/rollback-guard.d.mts

@@ -0,0 +1,10 @@
+/** What the guard found. */
+export interface ContractFinding {
+    blocked: boolean;
+    migrations: string[];
+    reason: string;
+}
+/** Judges a rollback to `target` against the attempt documents of the journal (oldest first). */
+export declare function contractFinding(documents: readonly Record<string, unknown>[], target: string): ContractFinding;
+/** Refuses `STACK_ROLLBACK_CONTRACT` when the finding blocks and the owner did not acknowledge the data effect; returns the notice line when it did. */
+export declare function enforceContractGuard(finding: ContractFinding, acknowledged: boolean): string[];

package/stack/rollback-guard.mjs

@@ -0,0 +1,41 @@
+// rollback-guard.mjs - the guard of a manual rollback to an older release.
+// A rollback restores service specs, never data (PROJECT-STACKS-6). A contract migration destroys what the code of the releases before the previous
+// one still uses, so rolling back to such a release after a contract migration ran leaves it on a schema it cannot read. The journal knows both: each
+// attempt that accepted a release carries an `accept` phase, and each attempt that applied contract migrations carries them in `contract`.
+//   chain      the accepted releases in the order the journal accepted them (a rollback is one more entry)
+//   a contract migration applied by the attempt that accepted chain[i] is safe for chain[i] and chain[i-1] (the deploy only runs it once the previous
+//   release no longer uses what it drops), and unsafe for every release accepted for the last time before chain[i-1].
+// A target the journal cannot place is refused as soon as any contract migration is recorded; `--data-acknowledged` is the owner's yes to the loss window.
+import { refusal } from './errors.mjs';
+const accepted = (document) => Array.isArray(document.phases) && document.phases.some((phase) => phase !== null && typeof phase === 'object' && phase.phase === 'accept' && phase.verdict === 'ok');
+const contractOf = (document) => (Array.isArray(document.contract) ? document.contract.filter((name) => typeof name === 'string') : []);
+/** Judges a rollback to `target` against the attempt documents of the journal (oldest first). */
+export function contractFinding(documents, target) {
+    const chain = [];
+    const marks = [];
+    for (const document of documents) {
+        if (typeof document.releaseId !== 'string' || !accepted(document))
+            continue;
+        chain.push(document.releaseId);
+        const migrations = contractOf(document);
+        if (migrations.length > 0)
+            marks.push({ index: chain.length - 1, migrations });
+    }
+    if (marks.length === 0)
+        return { blocked: false, migrations: [], reason: '' };
+    const at = chain.lastIndexOf(target);
+    const unsafe = marks.filter((mark) => at === -1 || at < mark.index - 1);
+    if (unsafe.length === 0)
+        return { blocked: false, migrations: [], reason: '' };
+    const migrations = unsafe.flatMap((mark) => mark.migrations);
+    const where = at === -1 ? `the journal has no record of release ${target} being accepted, and` : `release ${target} was accepted before the release that ran them, and`;
+    return { blocked: true, migrations, reason: `${where} contract migration(s) ${migrations.join(', ')} ran since: the schema no longer fits that release` };
+}
+/** Refuses `STACK_ROLLBACK_CONTRACT` when the finding blocks and the owner did not acknowledge the data effect; returns the notice line when it did. */
+export function enforceContractGuard(finding, acknowledged) {
+    if (!finding.blocked)
+        return [];
+    if (!acknowledged)
+        throw refusal('STACK_ROLLBACK_CONTRACT', `${finding.reason}. A rollback restores services, never data: restore the backup first, or pass --data-acknowledged to roll back anyway; nothing was changed`);
+    return [`--data-acknowledged: rolling back past ${finding.migrations.join(', ')}; the schema may not fit this release`];
+}

package/stack/ssh-gate.d.mts

@@ -0,0 +1,35 @@
+/** What an argument is: each kind is a closed alphabet, checked by the client (TypeScript) and by the gate (POSIX sh) alike. */
+export type ArgKind = 'base' | 'release' | 'pointer' | 'token' | 'trigger' | 'attempt' | 'seconds';
+/** One named operation: its arguments by kind, whether it reads stdin, and the sh body that runs with the arguments as $1.... */
+export interface GateOp {
+    readonly name: string;
+    readonly args: readonly ArgKind[];
+    readonly stdin: boolean;
+    readonly body: string;
+}
+/** The closed alphabet of each argument kind. */
+export declare const ARG_TESTS: Readonly<Record<ArgKind, (value: string) => boolean>>;
+/**
+ * The named operations of the release store. `lock-acquire`: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by
+ * rename, a lock unrefreshed for $4 seconds is moved aside (one rename wins) and claimed anew; prints `acquired` or `busy <trigger> <age>`.
+ */
+export declare const GATE_OPS: readonly GateOp[];
+/** The operation called `name`; an unknown name is a defect of the caller. */
+export declare function gateOp(name: string): GateOp;
+/** The command the CI transport sends: `starci-op <name> <argument>...` (every argument is plain characters, so nothing needs quoting). */
+export declare function gatedCommand(name: string, args: readonly string[]): string;
+/** The same operation as one command for a key without the gate: the body under `sh -c` with the arguments as positional parameters. */
+export declare function inlineCommand(name: string, args: readonly string[]): string;
+/** The POSIX sh text of `starci-ssh-gate`, to install executable at /usr/local/bin/starci-ssh-gate on the manager. */
+export declare function gateScript(): string;
+/** True when the CI transport was set up for a key that has the gate (`connect` exports STARCI_SSH_GATE=1 for a sealed `vps-ci` member that says `VPS_GATE: "1"`). */
+export declare const gateIsOn: (env: NodeJS.ProcessEnv | undefined) => boolean;
+/** Where the gate is installed on the manager, and the forced-command word of the authorized_keys line. */
+export declare const GATE_PATH = "/usr/local/bin/starci-ssh-gate";
+/** The options of the CI key's line: `restrict` already denies everything optional; the explicit denials keep the line readable and survive a reader who forgets what `restrict` covers. */
+export declare const AUTHORIZED_OPTIONS: readonly string[];
+/**
+ * The authorized_keys line of the CI key from its PUBLIC key text. Only a one-line public key is accepted (a private key, a line that already carries options
+ * or a second line is refused); the key keeps the comment it was generated with, which names it for revocation.
+ */
+export declare function authorizedKeysLine(publicKey: string): string;

package/stack/ssh-gate.mjs

@@ -0,0 +1,145 @@
+// ssh-gate.mjs - the forced command of the CI SSH key on the manager (`starci-ssh-gate`) and the named operations it admits.
+// The CI key reaches the manager's Docker socket, which is root on that host; its line in authorized_keys is therefore
+//   restrict,command="starci-ssh-gate" ssh-ed25519 AAAA... <comment>
+// and the gate admits exactly two kinds of request:
+//   `docker system dial-stdio`                   the transport of DOCKER_HOST=ssh://<alias> (the docker CLI starts it itself)
+//   `starci-op <name> <argument>...`             one of the named operations below, each argument validated by its kind
+// Everything else - a shell, an unknown name, a wrong argument count, an argument outside its closed alphabet - is refused with exit 126 and no echo of
+// the request. The operations are the release store's remote protocol (release-store.mts): the same script bodies run for the owner's key (through
+// `sh -c`, without the gate) and for the CI key (through the gate), so the gate admits no script the store does not itself run.
+// A body reads its arguments as $1... ($0 is `starci-op`) and its stdin; it holds no free text.
+import { refusal } from './errors.mjs';
+import { shellQuote } from './remote.mjs';
+const RELEASE_ID = /^[0-9a-f]{16}$/u;
+const TOKEN = /^[0-9a-f]{32}$/u;
+const ATTEMPT = /^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$/u;
+const BASE = /^\/[A-Za-z0-9._/-]+$/u;
+/** The closed alphabet of each argument kind. */
+export const ARG_TESTS = Object.freeze({
+    base: (value) => BASE.test(value) && !value.includes('..'),
+    release: (value) => RELEASE_ID.test(value),
+    pointer: (value) => value === 'current' || value === 'previous',
+    token: (value) => TOKEN.test(value),
+    trigger: (value) => value === 'ci' || value === 'dispatch' || value === 'urgent',
+    attempt: (value) => ATTEMPT.test(value),
+    seconds: (value) => /^[0-9]{1,6}$/u.test(value),
+});
+const OWNER_READ = 'if [ -r "$l/owner" ]; then read -r held_token held_trigger held_stamp < "$l/owner"; else held_token=none; held_trigger=unknown; held_stamp=$(stat -c %Y "$l" 2>/dev/null) || held_stamp=0; fi; case "$held_stamp" in \'\'|*[!0-9]*) held_stamp=0;; esac';
+/** Prints the release the pointer `$2` under `$1` names, or an empty line for an absent link; a failing readlink fails the script. */
+const POINTER = 'if [ -L "$1/$2" ]; then basename "$(readlink "$1/$2")"; else printf \'\\n\'; fi';
+/**
+ * The named operations of the release store. `lock-acquire`: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by
+ * rename, a lock unrefreshed for $4 seconds is moved aside (one rename wins) and claimed anew; prints `acquired` or `busy <trigger> <age>`.
+ */
+export const GATE_OPS = Object.freeze([
+    { name: 'pointer', args: ['base', 'pointer'], stdin: false, body: POINTER },
+    { name: 'list', args: ['base'], stdin: false, body: `for n in current previous; do if [ -L "$1/$n" ]; then basename "$(readlink "$1/$n")"; else printf '\\n'; fi; done; if [ -d "$1/releases" ]; then ls -1t "$1/releases"; fi` },
+    { name: 'read', args: ['base', 'release'], stdin: false, body: `set -e; s="$1/releases/$2"; for f in stack.yaml release.json; do test -r "$s/$f"; base64 < "$s/$f" | tr -d '\\n'; printf '\\n'; done` },
+    { name: 'store', args: ['base', 'release'], stdin: true, body: 'set -e; d="$1/releases/$2"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf \'%s\' "$stack" | base64 -d > "$d/stack.yaml"; printf \'%s\' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"' },
+    { name: 'accept', args: ['base', 'release'], stdin: false, body: 'set -e; cd "$1"; id="$2"; test -d "releases/$id"; if [ -L current ] && [ "$(basename "$(readlink current)")" != "$id" ]; then ln -sfn "$(readlink current)" previous; fi; ln -sfn "releases/$id" current.new; mv -Tf current.new current' },
+    {
+        name: 'lock-acquire', args: ['base', 'token', 'trigger', 'seconds'], stdin: false,
+        body: [
+            'b="$1"; tok="$2"; trg="$3"; ttl="$4"; l="$b/deploy.lock"; now=$(date +%s); mkdir -p "$b" || exit 1',
+            'claim() { printf \'%s %s %s\\n\' "$tok" "$trg" "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo acquired && exit 0; exit 1; }',
+            'if mkdir "$l" 2>/dev/null; then claim; fi',
+            OWNER_READ,
+            'age=$((now - held_stamp)); if [ "$age" -gt "$ttl" ]; then if mv "$l" "$l.stale.$tok" 2>/dev/null; then rm -rf "$l.stale.$tok"; if mkdir "$l" 2>/dev/null; then claim; fi; fi; fi',
+            'case "$held_trigger" in ci|dispatch|urgent) ;; *) held_trigger=unknown;; esac; echo "busy $held_trigger $age"',
+        ].join('; '),
+    },
+    { name: 'lock-refresh', args: ['base', 'token'], stdin: false, body: 'l="$1/deploy.lock"; now=$(date +%s); if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = "$2" ]; then printf \'%s %s %s\\n\' "$t" "$g" "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo held; else echo lost; fi; else echo lost; fi' },
+    { name: 'lock-release', args: ['base', 'token'], stdin: false, body: 'l="$1/deploy.lock"; if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = "$2" ]; then rm -rf "$l" && echo released; else echo lost; fi; else echo lost; fi' },
+    { name: 'journal-write', args: ['base', 'attempt'], stdin: true, body: 'set -e; d="$1/deploys"; mkdir -p "$d"; IFS= read -r doc; printf \'%s\' "$doc" | base64 -d > "$d/.$2.tmp"; mv -f "$d/.$2.tmp" "$d/$2.json"' },
+    { name: 'journal-index', args: ['base'], stdin: true, body: 'set -e; mkdir -p "$1/deploys"; IFS= read -r line; printf \'%s\\n\' "$(printf \'%s\' "$line" | base64 -d)" >> "$1/deploys.jsonl"' },
+    // The newest 500 attempt documents, one base64 line each, oldest first (attempt ids sort by their UTC time).
+    { name: 'journal-read', args: ['base'], stdin: false, body: 'd="$1/deploys"; [ -d "$d" ] || exit 0; names=$(ls -1 "$d") || exit 1; printf \'%s\\n\' "$names" | tail -n 500 | while IFS= read -r f; do case "$f" in ' + `${'[0-9]'.repeat(8)}T${'[0-9]'.repeat(6)}Z-${'[0-9a-f]'.repeat(8)}.json` + ') base64 < "$d/$f" | tr -d \'\\n\'; printf \'\\n\';; esac; done' },
+]);
+const BY_NAME = new Map(GATE_OPS.map((op) => [op.name, op]));
+/** The operation called `name`; an unknown name is a defect of the caller. */
+export function gateOp(name) {
+    const op = BY_NAME.get(name);
+    if (!op)
+        throw refusal('STACK_GATE_OP', `${name} is not an operation of the ssh gate`);
+    return op;
+}
+function checkedArguments(op, args) {
+    if (args.length !== op.args.length)
+        throw refusal('STACK_GATE_ARGUMENT', `${op.name} takes ${op.args.length} argument(s)`);
+    op.args.forEach((kind, index) => {
+        if (!ARG_TESTS[kind](args[index]))
+            throw refusal('STACK_GATE_ARGUMENT', `argument ${index + 1} of ${op.name} is not a plain ${kind}`);
+    });
+    return args;
+}
+/** The command the CI transport sends: `starci-op <name> <argument>...` (every argument is plain characters, so nothing needs quoting). */
+export function gatedCommand(name, args) {
+    const op = gateOp(name);
+    return ['starci-op', op.name, ...checkedArguments(op, args)].join(' ');
+}
+/** The same operation as one command for a key without the gate: the body under `sh -c` with the arguments as positional parameters. */
+export function inlineCommand(name, args) {
+    const op = gateOp(name);
+    return `sh -c ${shellQuote(op.body)} starci-op ${checkedArguments(op, args).map(shellQuote).join(' ')}`;
+}
+const VALIDATOR = Object.freeze({
+    base: 'v_base', release: 'v_release', pointer: 'v_pointer', token: 'v_token', trigger: 'v_trigger', attempt: 'v_attempt', seconds: 'v_seconds',
+});
+/** The sh variable that holds the body of an operation. */
+const bodyVariable = (name) => `OP_${name.replaceAll('-', '_')}`;
+/** The POSIX sh text of `starci-ssh-gate`, to install executable at /usr/local/bin/starci-ssh-gate on the manager. */
+export function gateScript() {
+    const digits = (count, set = '[0-9]') => set.repeat(count);
+    const bodies = GATE_OPS.map((op) => `${bodyVariable(op.name)}=${shellQuote(op.body)}`);
+    const cases = GATE_OPS.map((op) => {
+        const checks = op.args.map((kind, index) => `${VALIDATOR[kind]} "$${index + 1}"`).join(' && ');
+        return `  ${op.name}) [ $# -eq ${op.args.length} ]${checks ? ` && ${checks}` : ''} || refuse; exec sh -c "$${bodyVariable(op.name)}" starci-op "$@";;`;
+    });
+    return [
+        '#!/bin/sh',
+        '# starci-ssh-gate: the forced command of the CI key (generated by `starci app stack ci-key --print-gate`; do not edit, regenerate).',
+        '# Admits `docker system dial-stdio` and the named operations of the release store, nothing else. A refusal says nothing about the request.',
+        'PATH="$PATH:/usr/local/bin:/usr/bin:/bin"',
+        "refuse() { echo 'starci-ssh-gate: command refused' >&2; exit 126; }",
+        'v_base() { case "$1" in /*) ;; *) return 1;; esac; case "$1" in *[!A-Za-z0-9._/-]*|*..*) return 1;; esac; }',
+        'v_hex() { case "$2" in \'\'|*[!0-9a-f]*) return 1;; esac; [ "${#2}" -eq "$1" ]; }',
+        'v_release() { v_hex 16 "$1"; }',
+        'v_token() { v_hex 32 "$1"; }',
+        'v_pointer() { case "$1" in current|previous) ;; *) return 1;; esac; }',
+        'v_trigger() { case "$1" in ci|dispatch|urgent) ;; *) return 1;; esac; }',
+        `v_attempt() { case "$1" in ${digits(8)}T${digits(6)}Z-${digits(8, '[0-9a-f]')}) ;; *) return 1;; esac; v_hex 8 "\${1#*Z-}"; }`,
+        'v_seconds() { case "$1" in \'\'|*[!0-9]*) return 1;; esac; [ "${#1}" -le 6 ]; }',
+        ...bodies,
+        'cmd=${SSH_ORIGINAL_COMMAND-}',
+        '[ -n "$cmd" ] || refuse',
+        'if [ "$cmd" = \'docker system dial-stdio\' ]; then exec docker system dial-stdio; fi',
+        "IFS=' '; set -f",
+        'set -- $cmd',
+        '[ $# -ge 2 ] && [ "$1" = starci-op ] || refuse',
+        'op=$2; shift 2',
+        'case "$op" in',
+        ...cases,
+        '  *) refuse;;',
+        'esac',
+        '',
+    ].join('\n');
+}
+/** True when the CI transport was set up for a key that has the gate (`connect` exports STARCI_SSH_GATE=1 for a sealed `vps-ci` member that says `VPS_GATE: "1"`). */
+export const gateIsOn = (env) => env?.STARCI_SSH_GATE === '1';
+/** Where the gate is installed on the manager, and the forced-command word of the authorized_keys line. */
+export const GATE_PATH = '/usr/local/bin/starci-ssh-gate';
+/** The options of the CI key's line: `restrict` already denies everything optional; the explicit denials keep the line readable and survive a reader who forgets what `restrict` covers. */
+export const AUTHORIZED_OPTIONS = Object.freeze(['restrict', 'command="starci-ssh-gate"', 'no-pty', 'no-port-forwarding', 'no-agent-forwarding', 'no-X11-forwarding', 'no-user-rc']);
+const KEY_LINE = /^(ssh-ed25519|ecdsa-sha2-nistp(?:256|384|521)|ssh-rsa|sk-ssh-ed25519@openssh\.com) [A-Za-z0-9+/]+={0,3}(?: [A-Za-z0-9._@:+=-]+)?$/u;
+/**
+ * The authorized_keys line of the CI key from its PUBLIC key text. Only a one-line public key is accepted (a private key, a line that already carries options
+ * or a second line is refused); the key keeps the comment it was generated with, which names it for revocation.
+ */
+export function authorizedKeysLine(publicKey) {
+    const text = publicKey.trim();
+    if (text.includes('PRIVATE KEY'))
+        throw refusal('STACK_CI_KEY_PRIVATE', 'that is a private key: give the public half (.pub) of the CI key');
+    if (!KEY_LINE.test(text))
+        throw refusal('STACK_CI_KEY_PUBLIC', 'the CI public key must be one line: <type> <base64> [comment], with no options in front');
+    return `${AUTHORIZED_OPTIONS.join(',')} ${text}`;
+}

package/stack/status.d.mts

@@ -39,7 +39,9 @@ export declare function compareWithRelease(expected: ExpectedRelease, live: read
 /** The collaborators of a status (the specs inject stubs). */
 export interface StatusDeps {
     ssh: (ctx: StackContext, config: DeployConfig, options: SshOptions) => Runner | Promise<Runner>;
-    releaseStore: (config: DeployConfig, ssh: Runner) => ReleaseStore;
+    releaseStore: (config: DeployConfig, ssh: Runner, options?: {
+        gated?: boolean | undefined;
+    }) => ReleaseStore;
     observedServices: (ctx: StackContext, config: DeployConfig) => ObservedService[];
 }
 /**

package/stack/status.mjs

@@ -11,6 +11,7 @@ import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { canonical } from './converge.mjs';
 import { lines as splitLines, toolOutput } from './context.mjs';
 import { createReleaseStore } from './release-store.mjs';
+import { gateIsOn } from './ssh-gate.mjs';
 const DIGEST = /@(sha256:[0-9a-f]{64})$/u;
 const IMAGE_FIELD = /^[A-Za-z0-9][A-Za-z0-9./_:@-]*$/u;
 /** The `sha256:...` digest an image reference pins, or null. */
@@ -89,7 +90,7 @@ export async function statusStack(ctx, config, options = {}, deps = {}) {
     const d = { ...DEFAULT_DEPS, ...deps };
     const run = await d.ssh(ctx, config, { sshCmd: options.sshCmd ?? null });
     try {
-        const store = d.releaseStore(config, run);
+        const store = d.releaseStore(config, run, { gated: gateIsOn(ctx.env) });
         const current = await store.current();
         const live = d.observedServices(ctx, config);
         if (!current)

package/templates/be/skeleton-lite/src/modules/platform/database/database.client.spec.ts

@@ -74,23 +74,42 @@ describe("callDbFunction", () => {
 })
 
 describe("advisoryXactLock", () => {
-    it("locks the 64-bit hash of the key for the transaction", async () => {
+    it("hashes the key, then locks the hash for the transaction, both as function calls", async () => {
         const client = await setup()
-        const manager = mockEntityManager({ query: ["SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [{}]] })
+        const manager = mockEntityManager({
+            query: [
+                ['SELECT * FROM "pg_catalog"."hashtextextended"($1, $2)', [{ hashtextextended: "42" }]],
+                ['SELECT * FROM "pg_catalog"."pg_advisory_xact_lock"($1)', [{}]],
+            ],
+        })
 
         await expect(client.advisoryXactLock(manager, "jobs:mail")).resolves.toBeUndefined()
 
-        expect(manager.query).toHaveBeenCalledWith("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", ["jobs:mail"])
+        expect(manager.query).toHaveBeenNthCalledWith(1, 'SELECT * FROM "pg_catalog"."hashtextextended"($1, $2)', ["jobs:mail", 0])
+        expect(manager.query).toHaveBeenNthCalledWith(2, 'SELECT * FROM "pg_catalog"."pg_advisory_xact_lock"($1)', ["42"])
+    })
+
+    it.each([
+        ["no row", []],
+        ["a row with no hash", [{}]],
+        ["a hash that is not a number", [{ hashtextextended: null }]],
+    ])("refuses %s before it locks", async (_case, rows) => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ['SELECT * FROM "pg_catalog"."hashtextextended"($1, $2)', rows] })
+
+        await expect(client.advisoryXactLock(manager, "jobs:mail")).rejects.toMatchObject({ code: DatabaseErrorCode.ReturningRowRejected })
+
+        expect(manager.query).toHaveBeenCalledTimes(1)
     })
 })
 
 describe("notify", () => {
-    it("sends the payload on the channel", async () => {
+    it("sends the payload on the channel as a function call", async () => {
         const client = await setup()
-        const manager = mockEntityManager({ query: ["SELECT pg_notify($1, $2)", [{}]] })
+        const manager = mockEntityManager({ query: ['SELECT * FROM "pg_catalog"."pg_notify"($1, $2)', [{}]] })
 
         await expect(client.notify(manager, "jobs", '{"id":"job-1"}')).resolves.toBeUndefined()
 
-        expect(manager.query).toHaveBeenCalledWith("SELECT pg_notify($1, $2)", ["jobs", '{"id":"job-1"}'])
+        expect(manager.query).toHaveBeenCalledWith('SELECT * FROM "pg_catalog"."pg_notify"($1, $2)', ["jobs", '{"id":"job-1"}'])
     })
 })

package/templates/be/skeleton-lite/src/modules/platform/database/database.client.ts

@@ -82,12 +82,22 @@ export const callDbFunction = <T>(manager: EntityManager, name: string, args: Re
     return manager.query<Array<T>>(`SELECT * FROM "${target.schema}"."${target.name}"(${parameters})`, [...args])
 }
 
-/** Takes a transaction-scoped advisory lock on the 64-bit hash of `key`; it is released when the manager's transaction ends. */
+/** The refusal of a hash answer that is not the number the lock takes. */
+const hashRejected = (key: string): DatabaseError =>
+    new DatabaseError({ code: DatabaseErrorCode.ReturningRowRejected, params: { name: "hashtextextended", key } })
+
+/**
+ * Takes a transaction-scoped advisory lock on the 64-bit hash of `key`; it is released when the manager's transaction ends.
+ * Both steps are `callDbFunction` calls of listed pg built-ins, so no SQL text is written here (R334).
+ */
 export const advisoryXactLock = async (manager: EntityManager, key: string): Promise<void> => {
-    await manager.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [key])
+    const rows = await callDbFunction<Record<string, unknown>>(manager, "hashtextextended", [key, 0])
+    const hash = rows[0]?.["hashtextextended"]
+    if (typeof hash !== "string" && typeof hash !== "number" && typeof hash !== "bigint") throw hashRejected(key)
+    await callDbFunction(manager, "pg_advisory_xact_lock", [hash])
 }
 
 /** Sends one NOTIFY on `channel` with `payload`, delivered when the manager's transaction commits. */
 export const notify = async (manager: EntityManager, channel: string, payload: string): Promise<void> => {
-    await manager.query("SELECT pg_notify($1, $2)", [channel, payload])
+    await callDbFunction(manager, "pg_notify", [channel, payload])
 }