declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/.test/useWakeOfLivedb.ts

@@ -0,0 +1,209 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = wake the shared aurora-serverless cluster before a suite runs, when this
+ *         service reaches it — whether it OWNS the db or only invokes peers that do.
+ * .why =
+ *   - the non-prod cluster is aurora-serverless-v2 at min-capacity 0, so it auto-pauses
+ *     when idle; the first downstream query after a pause cold-starts past the 90s test
+ *     timeout and flakes the suite (svc-gateway hit this on mAddCrewMember + the quote suites)
+ *   - a gateway/fan-out service owns NO db of its own, so a db-ownership signal misses it.
+ *     the signal that it REACHES the shared cluster is a tunnel declared in its config —
+ *     `config/prep.json`'s `database.tunnel`. that is the self-gate: a tunnel means a query
+ *     lands on the cluster (direct or via a peer), so wake it; no tunnel means no-op.
+ *   - `rhx use.rds.capacity` opens an ssm tunnel to the cluster and waits for it to accept
+ *     connections, which resumes it for every consumer (incl. deployed lambdas), not just
+ *     the local caller
+ *   - best-effort: a warm db, absent tunnel alias, or absent skill must NEVER break the
+ *     suite, so a wake failure is surfaced loud to stderr (not swallowed) and the suite
+ *     proceeds — a wake is a latency nicety, not a correctness gate; the suite's own
+ *     assertions are the gate
+ *   - ci is skipped: creds arrive via oidc and the local ssm-tunnel path is unavailable there,
+ *     so ci wakes via the dedicated `start:livedb:prep` workflow step instead
+ * .note = this is the LIVEDB half of a suite's db needs — the shared prep cluster its peers query.
+ *         it RESUMES a paused cluster. its pair, `useWakeOfTestdb`, is the LOCAL own-db half: it
+ *         only PREFLIGHTS the local testdb (it cannot start it, so it fails loud with a `start:testdb`
+ *         fix). the two form a symmetric pair; the name reads "wake" for symmetry, the act differs.
+ *         the wake fires for prep OR test access: both reach the deployed prep peers.
+ * .note = `reaches` names HOW the caller reaches the cluster, so the gate reads a signal the caller
+ *         actually has:
+ *         - `via-tunnel` = a node service; gate on `config/prep.json`'s `database.tunnel`
+ *         - `via-gateway` = an expo app, which owns no `config/` dir and reaches the cluster through
+ *           its gateway's peers; its acceptance + integration suites reach a deployment by
+ *           construction, so the test kind itself is the signal and no config gate applies
+ */
+export const useWakeOfLivedb = async (input: {
+  env: 'test' | 'prep' | 'prod' | null;
+  reaches: 'via-tunnel' | 'via-gateway';
+}): Promise<void> => {
+  // decide whether to wake, and which cluster: ci and prod never wake; test + prep wake prep
+  const decision = getWakeDecision({
+    access: input.env,
+    ci: process.env.CI ?? null,
+  });
+  if (!decision.wake) return;
+  const env = decision.access;
+
+  // gate a node service on a declared db tunnel: it is the signal this service reaches the shared
+  // cluster, whether it owns the db (persist-with-rds) or only invokes peers that query it (a gateway).
+  // absent config = no cluster to wake; a malformed config fails loud (names the file), never silent.
+  if (input.reaches === 'via-tunnel' && !asReachesSharedClusterFromConfig({ env }))
+    return;
+
+  // the wake blocks suite start on a local run, so its budget is consumer-bounded: a generous
+  // default (a cold aurora-serverless-v2 resume can exceed 60s), overridable DOWN via
+  // LIVEDB_WAKE_TIMEOUT_MS so a consumer can fail fast on a hung tunnel rather than wait the full cap
+  const timeoutMs = Number(process.env.LIVEDB_WAKE_TIMEOUT_MS) || 180000;
+
+  // best-effort wake: a wake-command failure (a non-zero exit, a timeout kill, an absent binary) is
+  // non-fatal — a warm db or absent skill must not break the suite. but an error that bears no
+  // child-process shape is a malfunction in this module's own logic, so rethrow it (rule.forbid.failhide):
+  // the catch tolerates only the allowlisted wake failures and surfaces the rest.
+  try {
+    wakeSharedCluster({ env, timeoutMs });
+  } catch (error) {
+    if (!isWakeCommandFailure({ error })) throw error;
+    // a non-Error failure shape (e.g. a child-process `{ status, signal }` object) must read
+    // legibly on stderr: `String({...})` yields the useless `[object Object]`, so serialize it.
+    const message =
+      error instanceof Error ? error.message : JSON.stringify(error);
+    warnWakeFailed({ env, message });
+  }
+};
+
+/**
+ * .what = decide whether a run wakes the shared cluster, and which cluster it wakes.
+ * .why  = a pure transformer leaf: the prod refusal and the prep default are the two arms a wrong
+ *         edit turns into a capacity write against production, so they live in one named, clamped
+ *         decision rather than inline in the orchestrator.
+ *         - ci → no wake (ci wakes via its own workflow step; the local ssm path is absent there)
+ *         - prod → no wake (prod never scales to 0; a wake there is an unprompted prod write)
+ *         - test, prep, or undeclared → wake prep, the cluster both test and prep access reach
+ *           (both query the deployed prep peers); an undeclared access never falls to prod
+ */
+export const getWakeDecision = (input: {
+  access: 'test' | 'prep' | 'prod' | null;
+  ci: string | null;
+}): { wake: boolean; access: 'test' | 'prep' | 'prod' } => {
+  if (input.access === 'prod') return { wake: false, access: 'prod' };
+  if (input.ci) return { wake: false, access: 'prep' };
+  return { wake: true, access: 'prep' };
+};
+
+/**
+ * .what = read the raw text of this service's `config/<env>.json`, or null when absent.
+ * .why  = a communicator leaf: the sole filesystem i/o of the wake gate, named so the
+ *         orchestrator composes it rather than embeds an inline `existsSync`/`readFileSync`.
+ * .note = an absent config is benign (a service that declares none reaches no known cluster),
+ *         so absence returns null and the pure decide-step below folds it to false. this leaf
+ *         performs i/o only; it never parses or decides.
+ */
+const readConfigText = (input: {
+  env: 'test' | 'prep' | 'prod';
+}): string | null => {
+  const configPath = join(process.cwd(), 'config', `${input.env}.json`);
+  if (!existsSync(configPath)) return null;
+  return readFileSync(configPath, 'utf8');
+};
+
+/**
+ * .what = decide, from raw config text, whether this service reaches the shared cluster.
+ * .why  = a pure transformer leaf: no i/o, deterministic. a `database.tunnel` in the config =
+ *         a query lands on the cluster (direct or via a peer), so the service reaches it.
+ *         the one fact — does this service reach the cluster — has one shape here, read off
+ *         the same `database.tunnel` signal everywhere, so two readers cannot drift.
+ */
+const asReachesSharedClusterFromConfigText = (input: {
+  text: string;
+}): boolean => {
+  return !!JSON.parse(input.text)?.database?.tunnel;
+};
+
+/**
+ * .what = compose the config read + tunnel decision into a single what-not-how signal.
+ * .why  = the composer of the two leaves above, so `useWakeOfLivedb` reads one intent rather than
+ *         an inline read-parse-decode a reader must simulate.
+ * .note = an absent config folds to false (no known cluster → no wake). but a present-yet-
+ *         unparseable config is NOT benign: it means the consumer authored a config the setup
+ *         cannot read, so a silent `false` would conflate a broken config with an absent tunnel.
+ *         so a parse failure throws a ConstraintError (caller-must-fix, exit 2) that names the
+ *         file + the fix, rather than a raw engine SyntaxError with no file and no remediation.
+ */
+const asReachesSharedClusterFromConfig = (input: {
+  env: 'test' | 'prep' | 'prod';
+}): boolean => {
+  const text = readConfigText({ env: input.env });
+  if (text === null) return false; // no config = no known cluster (benign)
+  try {
+    return asReachesSharedClusterFromConfigText({ text });
+  } catch (cause) {
+    // allowlist the ONLY error the parse-decide leaf can throw — a SyntaxError on malformed json.
+    // an error of any other shape is a malfunction in this module's own logic, not a config the
+    // consumer mis-authored, so surface it unwrapped rather than relabel it a parse failure
+    // (rule.forbid.failhide: a catch allowlists its expected errors and rethrows the rest).
+    if (!(cause instanceof SyntaxError)) throw cause;
+    // a config the consumer authored but the setup cannot parse is a real defect, not "no cluster" —
+    // throw with the path so a malformed config names the file to repair (never a silent false)
+    const configPath = join(process.cwd(), 'config', `${input.env}.json`);
+    throw new ConstraintError(
+      `useWakeOfLivedb: could not parse ${configPath} as JSON — fix the malformed config so the wake gate can read its database.tunnel signal`,
+      { cause },
+    );
+  }
+};
+
+/**
+ * .what = wake the shared cluster by an ssm tunnel that resumes it for every consumer.
+ * .why  = a communicator leaf: the sole subprocess i/o of the wake, named so the orchestrator
+ *         composes it rather than embeds an inline `execSync`. `rhx use.rds.capacity` opens the
+ *         tunnel and waits for the cluster to accept connections, which resumes it (incl. for
+ *         deployed lambdas), not just the local caller.
+ */
+const wakeSharedCluster = (input: {
+  env: 'test' | 'prep' | 'prod';
+  timeoutMs: number;
+}): void => {
+  execSync(`rhx use.rds.capacity --env ${input.env}`, {
+    stdio: 'inherit',
+    timeout: input.timeoutMs,
+  });
+};
+
+/**
+ * .what = surface a wake failure loud to stderr, non-fatal.
+ * .why  = a communicator leaf: the failure sink of the wake, named so the orchestrator composes
+ *         it rather than embeds an inline `process.stderr.write`. a real wake failure — a
+ *         miswired command, an absent skill, a broken rhx binary — must be visible, never hidden;
+ *         the suite proceeds and a downstream cold-start timeout flake is the likely symptom.
+ */
+const warnWakeFailed = (input: {
+  env: 'test' | 'prep' | 'prod';
+  message: string;
+}): void => {
+  process.stderr.write(
+    `useWakeOfLivedb: 'rhx use.rds.capacity --env ${input.env}' failed (non-fatal): ${input.message}\n`,
+  );
+};
+
+/**
+ * .what = decide whether an error is a wake-command failure (safe to tolerate) vs a code malfunction.
+ * .why  = a pure transformer leaf: the allowlist `rule.forbid.failhide` demands. an execSync failure
+ *         bears a child-process shape — a numeric `status` (a non-zero exit), a string `signal` (a
+ *         timeout kill), or a `code` of `ENOENT` (an absent binary) or `ETIMEDOUT` (the cap).
+ *         those are the wake failures the suite intends to tolerate. an error with none of that shape
+ *         is a genuine malfunction in this module's own logic, so the catch rethrows it, never warns
+ *         it away — a best-effort op still distinguishes the failures it ignores from the ones it must not.
+ */
+const isWakeCommandFailure = (input: { error: unknown }): boolean => {
+  const error = input.error;
+  if (!error || typeof error !== 'object') return false;
+  const shape = error as { status?: unknown; signal?: unknown; code?: unknown };
+  if (typeof shape.status === 'number') return true; // child exited non-zero
+  if (typeof shape.signal === 'string') return true; // child killed by a signal (a timeout)
+  if (shape.code === 'ENOENT' || shape.code === 'ETIMEDOUT') return true; // absent binary, cap hit
+  return false; // any other `code` (EACCES, EMFILE, …) is not a wake failure, so it rethrows
+};

package/dist/__snapshots__/actionPins.declapract.integration.test.ts.snap

@@ -3,31 +3,30 @@
 exports[`action pins given: [case1] every yaml template declared under a practice .github tree when: [t2] the refs are read together then: the pin table reads as declared -- if the diff surprises you, a bump reached more or fewer sites than intended 1`] = `
 [
   "Entle/action-pagerduty-alert@e6ca54cd88948b8a50f5bb1071dfa5bdb149ce7e — 1 site",
-  "actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 — 19 sites",
-  "actions/checkout@11d5960a326750d5838078e36cf38b85af677262 — 22 sites",
+  "actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 — 20 sites",
+  "actions/checkout@11d5960a326750d5838078e36cf38b85af677262 — 23 sites",
   "actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 — 3 sites",
   "actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 — 1 site",
-  "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 — 18 sites",
+  "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 — 19 sites",
   "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 — 1 site",
   "amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 — 1 site",
-  "aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a — 13 sites",
+  "aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a — 14 sites",
   "expo/expo-github-action@c7b66a9c327a43a8fa7c0158e7f30d6040d2481e — 2 sites",
-  "hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd — 3 sites",
+  "hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd — 2 sites",
   "pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 — 1 site",
 ]
 `;
 
 exports[`action pins given: [case2] every yaml under this repo's own .github tree when: [t2] the refs are read together then: the pin table reads as declared -- if the diff surprises you, a bump reached more or fewer sites than intended 1`] = `
 [
-  "actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 — 12 sites",
-  "actions/checkout@11d5960a326750d5838078e36cf38b85af677262 — 12 sites",
-  "actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 — 3 sites",
+  "actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 — 13 sites",
+  "actions/checkout@11d5960a326750d5838078e36cf38b85af677262 — 13 sites",
+  "actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 — 4 sites",
   "actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 — 1 site",
-  "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 — 11 sites",
+  "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 — 12 sites",
   "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 — 1 site",
   "amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 — 1 site",
   "aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a — 4 sites",
-  "hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd — 1 site",
   "pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 — 1 site",
 ]
 `;

package/dist/__snapshots__/ancientTargetPublished.declapract.integration.test.ts.snap

@@ -1,8 +1,8 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
-exports[`the EnvAccess target op emits only slugs the dual-publish scaffold publishes (case=2 no-404) given: the ancient/contemp target ops and the serverless accessByStage scaffold when: the per-tier emitted slugs are derived for both target ops then: the target-slug shape matches snapshot: per-tier target slug vs published stages 1`] = `
+exports[`the EnvAccess target op emits only slugs the dual-publish scaffold publishes (case=2 no-404) given: the ancient/contemp target ops and the serverless accessByStage scaffold when: the per-access emitted slugs are derived for both target ops then: the target-slug shape matches snapshot: per-access target slug vs published stages 1`] = `
 {
-  "perTier": [
+  "perAccess": [
     {
       "access": "prep",
       "ancient": "dev",
@@ -29,7 +29,7 @@ exports[`the EnvAccess target op emits only slugs the dual-publish scaffold publ
     "prep": "prep",
     "prod": "prod",
   },
-  "deployedTiers": [
+  "deployedAccesses": [
     "prep",
     "prod",
   ],

package/dist/__snapshots__/typecheckBestPracticeTemplates.declapract.integration.test.ts.snap

@@ -0,0 +1,96 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`typecheck best-practice templates given: [usecase] app-react-native-expo applied to a bare repo when: [t1] the emitted tree is compiled with the emitted tsconfig then: the tsc diagnostics match snapshot: app-react-native-expo — tsc --noEmit diagnostics 1`] = `""`;
+
+exports[`typecheck best-practice templates given: [usecase] app-react-native-expo applied to a bare repo when: [t2] the twice-applied repo is planned again then: the files left for a human to author match snapshot: app-react-native-expo — files flagged for a human 1`] = `
+[
+  ".agent/keyrack.yml",
+  "src/**/*.integration.test.ts",
+  "src/**/*.test.ts",
+  "src/contract/**/*.ts",
+  "src/domain.objects/**/*.ts",
+  "src/domain.objects/index.ts",
+  "src/domain.operations/**/*.ts",
+]
+`;
+
+exports[`typecheck best-practice templates given: [usecase] lambda-service applied to a bare repo when: [t1] the emitted tree is compiled with the emitted tsconfig then: the tsc diagnostics match snapshot: lambda-service — tsc --noEmit diagnostics 1`] = `""`;
+
+exports[`typecheck best-practice templates given: [usecase] lambda-service applied to a bare repo when: [t2] the twice-applied repo is planned again then: the files left for a human to author match snapshot: lambda-service — files flagged for a human 1`] = `
+[
+  ".agent/keyrack.yml",
+  "blackbox/**/*.acceptance.test.ts",
+  "blackbox/lambdas/*.acceptance.test.ts",
+  "src/domain.objects/**/*.ts",
+  "src/domain.objects/index.ts",
+  "src/domain.operations/**/*.ts",
+  "serverless.yml",
+]
+`;
+
+exports[`typecheck best-practice templates given: [usecase] lambda-service-with-dynamodb applied to a bare repo when: [t1] the emitted tree is compiled with the emitted tsconfig then: the tsc diagnostics match snapshot: lambda-service-with-dynamodb — tsc --noEmit diagnostics 1`] = `""`;
+
+exports[`typecheck best-practice templates given: [usecase] lambda-service-with-dynamodb applied to a bare repo when: [t2] the twice-applied repo is planned again then: the files left for a human to author match snapshot: lambda-service-with-dynamodb — files flagged for a human 1`] = `
+[
+  ".agent/keyrack.yml",
+  "blackbox/**/*.acceptance.test.ts",
+  "blackbox/lambdas/*.acceptance.test.ts",
+  "src/domain.objects/**/*.ts",
+  "src/domain.objects/index.ts",
+  "src/domain.operations/**/*.ts",
+  "serverless.yml",
+]
+`;
+
+exports[`typecheck best-practice templates given: [usecase] lambda-service-with-rds applied to a bare repo when: [t1] the emitted tree is compiled with the emitted tsconfig then: the tsc diagnostics match snapshot: lambda-service-with-rds — tsc --noEmit diagnostics 1`] = `""`;
+
+exports[`typecheck best-practice templates given: [usecase] lambda-service-with-rds applied to a bare repo when: [t2] the twice-applied repo is planned again then: the files left for a human to author match snapshot: lambda-service-with-rds — files flagged for a human 1`] = `
+[
+  ".agent/keyrack.yml",
+  "blackbox/**/*.acceptance.test.ts",
+  "blackbox/lambdas/*.acceptance.test.ts",
+  "src/domain.objects/**/*.ts",
+  "src/domain.objects/index.ts",
+  "src/domain.operations/**/*.ts",
+  "serverless.yml",
+]
+`;
+
+exports[`typecheck best-practice templates given: [usecase] npm-package applied to a bare repo when: [t1] the emitted tree is compiled with the emitted tsconfig then: the tsc diagnostics match snapshot: npm-package — tsc --noEmit diagnostics 1`] = `""`;
+
+exports[`typecheck best-practice templates given: [usecase] npm-package applied to a bare repo when: [t2] the twice-applied repo is planned again then: the files left for a human to author match snapshot: npm-package — files flagged for a human 1`] = `
+[
+  ".agent/keyrack.yml",
+  "src/**/*.integration.test.ts",
+  "src/contract/**/*.ts",
+  "src/domain.objects/**/*.ts",
+  "src/domain.objects/index.ts",
+  "src/domain.operations/**/*.ts",
+]
+`;
+
+exports[`typecheck best-practice templates given: [usecase] rhachet-roles-package applied to a bare repo when: [t1] the emitted tree is compiled with the emitted tsconfig then: the tsc diagnostics match snapshot: rhachet-roles-package — tsc --noEmit diagnostics 1`] = `""`;
+
+exports[`typecheck best-practice templates given: [usecase] rhachet-roles-package applied to a bare repo when: [t2] the twice-applied repo is planned again then: the files left for a human to author match snapshot: rhachet-roles-package — files flagged for a human 1`] = `
+[
+  ".agent/keyrack.yml",
+  "src/**/*.integration.test.ts",
+  "src/contract/**/*.ts",
+  "src/domain.objects/**/*.ts",
+  "src/domain.objects/index.ts",
+  "src/domain.operations/**/*.ts",
+]
+`;
+
+exports[`typecheck best-practice templates given: [usecase] typescript-project applied to a bare repo when: [t1] the emitted tree is compiled with the emitted tsconfig then: the tsc diagnostics match snapshot: typescript-project — tsc --noEmit diagnostics 1`] = `""`;
+
+exports[`typecheck best-practice templates given: [usecase] typescript-project applied to a bare repo when: [t2] the twice-applied repo is planned again then: the files left for a human to author match snapshot: typescript-project — files flagged for a human 1`] = `
+[
+  ".agent/keyrack.yml",
+  "src/**/*.integration.test.ts",
+  "src/contract/**/*.ts",
+  "src/domain.objects/**/*.ts",
+  "src/domain.objects/index.ts",
+  "src/domain.operations/**/*.ts",
+]
+`;

package/dist/__snapshots__/useCases.rhachet-roles-package.declapract.integration.test.ts.snap

@@ -0,0 +1,29 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`useCases.yml — rhachet-roles-package given: [case1] the declared usecases when: [t0] rhachet-roles-package is resolved then: its resolved set matches snapshot: rhachet-roles-package practices 1`] = `
+[
+  "bottleneck",
+  "cache",
+  "cicd-common",
+  "cicd-package",
+  "conventional-commits",
+  "directory-structure-src",
+  "domain",
+  "errors",
+  "format",
+  "git",
+  "husky",
+  "lint",
+  "node",
+  "node-package",
+  "nonpublished-modules",
+  "package-json-order",
+  "pnpm",
+  "provision-github",
+  "rhachet",
+  "tests-any",
+  "tests-node",
+  "typescript-any",
+  "typescript-node",
+]
+`;

package/dist/__snapshots__/workflowCallerCalleeReconciliation.declapract.integration.test.ts.snap

@@ -141,13 +141,6 @@ exports[`reusable workflows reconcile caller against callee (#573 · #580) given
       "secrets": [],
       "secretsRequired": [],
     },
-    {
-      "base": "test.yml",
-      "inputs": [],
-      "inputsRequired": [],
-      "secrets": [],
-      "secretsRequired": [],
-    },
   ],
   "callers": [
     {
@@ -217,6 +210,23 @@ exports[`reusable workflows reconcile caller against callee (#573 · #580) given
         "wish-path",
       ],
     },
+    {
+      "base": ".declastruct.yml",
+      "job": "github",
+      "secretKeys": [
+        "creds-github-app-private-key",
+      ],
+      "secretsInherit": false,
+      "withKeys": [
+        "access",
+        "creds-github-app-id",
+        "creds-github-app-owner",
+        "github-environment-apply",
+        "github-environment-plan",
+        "scope",
+        "wish-path",
+      ],
+    },
     {
       "base": ".deploy-expo.yml",
       "job": "prep",
@@ -405,16 +415,6 @@ exports[`reusable workflows reconcile caller against callee (#573 · #580) given
         "creds-aws-role-arn",
       ],
     },
-    {
-      "base": ".test.yml",
-      "job": "suite",
-      "secretKeys": [],
-      "secretsInherit": true,
-      "withKeys": [
-        "creds-aws-region",
-        "creds-aws-role-arn",
-      ],
-    },
     {
       "base": ".test.yml",
       "job": "test",

package/dist/__snapshots__/workflowJobScopeIdToken.declapract.integration.test.ts.snap

@@ -0,0 +1,38 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`workflow templates grant id-token at job scope (#550) given: [case1] every workflow template under src/practices when: [t1] each workflow is read for its grants then: the grant table reads as declared 1`] = `
+[
+  "src/practices/cicd-app-react-native-expo/best-practice/.github/workflows/.deploy-expo.yml :: deploy-os",
+  "src/practices/cicd-app-react-native-expo/best-practice/.github/workflows/.deploy-expo.yml :: deploy-web",
+  "src/practices/cicd-common/best-practice/.github/workflows/.declastruct.yml :: plan",
+  "src/practices/cicd-common/best-practice/.github/workflows/.declastruct.yml :: apply",
+  "src/practices/cicd-common/best-practice/.github/workflows/.test.yml :: test-shards-integration",
+  "src/practices/cicd-common/best-practice/.github/workflows/.test.yml :: test-shards-acceptance",
+  "src/practices/cicd-common/best-practice/.github/workflows/.test.yml :: test-evaluation",
+  "src/practices/cicd-package/best-practice/.github/workflows/.publish-npm.yml :: publish",
+  "src/practices/cicd-service/best-practice/.github/workflows/.deploy-sls.yml :: deploy",
+  "src/practices/cicd-service/best-practice/.github/workflows/.deploy-sls.yml :: assure",
+  "src/practices/cicd-service/best-practice/.github/workflows/.deploy-sls.yml :: prune",
+  "src/practices/cicd-service/best-practice/.github/workflows/.sql-schema-control.yml :: plan",
+  "src/practices/cicd-service/best-practice/.github/workflows/.sql-schema-control.yml :: apply",
+  "src/practices/cicd-service/best-practice/.github/workflows/.terraform.yml :: plan",
+  "src/practices/cicd-service/best-practice/.github/workflows/.terraform.yml :: apply",
+]
+`;
+
+exports[`workflow templates grant id-token at job scope (#550) given: [case2] a corpus that is defective on purpose when: [t0] the corpus is read the way the walk reads a real one then: each report names its offender -- the text a maintainer meets on red 1`] = `
+{
+  "grantsWithoutMinter": [
+    "demo/.github/workflows/.demo.yml :: lint",
+  ],
+  "jobBlocksWithoutContentsRead": [
+    "demo/.github/workflows/.demo.yml :: lint",
+  ],
+  "mintersWithoutGrant": [
+    "demo/.github/workflows/.demo.yml :: deploy",
+  ],
+  "workflowScopeGrants": [
+    "demo/.github/workflows/.demo.yml",
+  ],
+}
+`;

package/dist/__snapshots__/workflowPrBuild.declapract.integration.test.ts.snap

@@ -0,0 +1,10 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`the pr gate runs the production build (#678) and the evaluation suite (#669) given: [case1] every workflow template under src/practices when: [t2] the jobs of .test.yml are read then: the jobs that build, in order, read as declared 1`] = `
+[
+  "test-types",
+  "test-shards-integration",
+  "test-shards-acceptance",
+  "test-evaluation",
+]
+`;

package/dist/actionPinsBump.declapract.integration.test.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import yaml from 'yaml';
+
+/**
+ * .what = holds this repo's OWN scheduled bump path for the sha-pinned actions (#556)
+ * .why  = every workflow template here is delivered by EQUALS, so a consumer that bumps a pin by
+ *         hand is reverted on its next apply. the bump must happen at the source, on a schedule,
+ *         or the pins rot in place. this asserts the schedule exists, runs the bump command over
+ *         both surfaces, re-records the pin table, and gates its pr on the actionPins clamp.
+ * .note = the pin choice itself is unit-tested in `utils/actionPins/asActionPinTargetTag`;
+ *         the shape (40-hex sha, tag tail, one sha per repo) is held by `actionPins`.
+ */
+
+const WORKFLOW_PATH = join(__dirname, '..', '.github/workflows/bump-action-pins.yml');
+
+describe("this repo's scheduled action-pin bump (#556)", () => {
+  given('[case1] the bump workflow under .github/workflows', () => {
+    const scene = useBeforeAll(() => {
+      const present = existsSync(WORKFLOW_PATH);
+      const parsed = present ? yaml.parse(readFileSync(WORKFLOW_PATH, 'utf-8')) : null;
+      const runs: string[] = Object.values(
+        (parsed?.jobs ?? {}) as Record<string, { steps?: { run?: string }[] }>,
+      ).flatMap((job) => (job.steps ?? []).map((step) => step.run ?? ''));
+      return { present, parsed, runs };
+    });
+
+    when('[t0] it is read', () => {
+      then('it exists -- if red, the pins have no bump path', () => {
+        expect(scene.present).toEqual(true);
+      });
+
+      then('it runs on a schedule and on demand', () => {
+        const on = scene.parsed?.on ?? scene.parsed?.[true as unknown as string] ?? {};
+        expect(Object.keys(on)).toEqual(expect.arrayContaining(['schedule', 'workflow_dispatch']));
+      });
+
+      then('it runs the bump command in apply mode', () => {
+        expect(scene.runs.join('\n')).toContain(
+          'src/utils/actionPins/bumpActionPins.ts --mode apply',
+        );
+      });
+
+      then('it re-records the pin table and holds the actionPins clamp before the pr opens', () => {
+        const text = scene.runs.join('\n');
+        expect(text).toContain('--testPathPatterns=actionPins');
+        expect(text).toContain('RESNAP=true');
+        expect(text.indexOf('actionPins')).toBeLessThan(text.indexOf('gh pr create'));
+      });
+    });
+  });
+});