declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/serverless/.declapract.integration.test.ts

@@ -0,0 +1,230 @@
+import fs from 'fs/promises';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
+
+jest.setTimeout(180_000);
+
+/**
+ * .what = holds the serverless `package.json` deploy commands to the dual-publish split —
+ *         the council-gated fulcrum that a wrong guess would ship as a permanent 2×-deploy.
+ * .why  = the `package.json` is a CONTAINS template with no `fix`, so no unit test covers it.
+ *         per `rule.require.clamp-edge-cases`, the deploy-split (and the contemp prune it needs)
+ *         owes a clamp. this reads the template + pins the split shape.
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the filesystem (the
+ *         template file). no credential, no network.
+ * .teeth = (a) `deploy:release` MUST invoke BOTH halves — a revert to a single-fleet release
+ *          reddens it; (b) `deploy:prune` MUST also prune the contemp `-prep-` fleet — a revert
+ *          to the ancient-only prune (the B1 leak) reddens it.
+ */
+
+const PACKAGE_JSON_PATH = `${__dirname}/best-practice/package.json`;
+const SERVERLESS_YML_PATH = `${__dirname}/best-practice/serverless.yml`;
+
+describe('serverless practice — the dual-publish deploy split (north-star clamp)', () => {
+  given('[case1] the shipped serverless package.json template', () => {
+    const scene = useBeforeAll(() => ({
+      scripts: JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf8')).scripts as Record<
+        string,
+        string
+      >,
+    }));
+
+    when('[t0] the deploy commands are read', () => {
+      then('the ancient release publishes the dev-below-prod slug', () => {
+        expect(scene.scripts['deploy:release:ancient']).toContain(
+          "[ \"${ACCESS:-}\" = 'prep' ] && echo 'dev'",
+        );
+        expect(scene.scripts['deploy:release:ancient']).toContain(
+          '--stage "${SLS_STAGE:-}"',
+        );
+      });
+
+      then('the contemp release publishes the prep slug', () => {
+        expect(scene.scripts['deploy:release:contemp']).toContain('--stage prep');
+      });
+
+      then('deploy:release runs BOTH fleets (the dual-publish teeth)', () => {
+        expect(scene.scripts['deploy:release']).toContain(
+          'npm run deploy:release:ancient',
+        );
+        expect(scene.scripts['deploy:release']).toContain(
+          'npm run deploy:release:contemp',
+        );
+      });
+
+      then('deploy:prod publishes the ancient fleet only (prod is prod on both axes)', () => {
+        expect(scene.scripts['deploy:prod']).toContain(
+          'npm run deploy:release:ancient',
+        );
+        expect(scene.scripts['deploy:prod']).not.toContain(
+          'npm run deploy:release:contemp',
+        );
+      });
+
+      then('deploy:prune also prunes the contemp -prep- fleet (the B1 leak clamp)', () => {
+        expect(scene.scripts['deploy:prune']).toContain('--stage prep');
+      });
+    });
+  });
+
+  given('[case2] the shipped serverless.yml template', () => {
+    const scene = useBeforeAll(() => ({
+      yml: readFileSync(SERVERLESS_YML_PATH, 'utf8'),
+    }));
+
+    when('[t0] the domain-driven-cache IAM grant is read', () => {
+      then('it grants the cache family with the stage segment globbed (#597)', () => {
+        // the shared cache is one table addressed by a single name (below prod that name is -dev-);
+        // a globbed grant covers -dev-, -prep-, -prod- in one line, so the contemp -prep- fleet's
+        // -dev- cache read is authorized. supersedes the earlier D27 two-line stage+access grant.
+        expect(scene.yml).toContain(
+          'table/infrastructure-*-table-domain-driven-cache',
+        );
+      });
+
+      then('no stage- or access-templated cache grant survives (the #597 teeth)', () => {
+        // a templated grant covers only the deployed fleet's own slug — the exact #597 break where
+        // the contemp -prep- fleet AccessDenied on the shared -dev- cache. the glob replaces both.
+        expect(scene.yml).not.toContain(
+          'table/infrastructure-${self:provider.stage}-table-domain-driven-cache',
+        );
+        expect(scene.yml).not.toContain(
+          'table/infrastructure-${self:custom.access}-table-domain-driven-cache',
+        );
+      });
+
+      then('the glue-db grants read the single hoisted custom.access var (D: no 4x dup)', () => {
+        // teeth: the accessByStage lookup is declared ONCE, as custom.access; a partial edit that
+        // re-inlined the lookup at one arn site (and missed another) is the D27-reopen hazard.
+        expect(scene.yml).toContain(
+          "access: ${self:custom.accessByStage.${opt:stage}, 'prep'}",
+        );
+        // exactly one occurrence of the raw accessByStage lookup — the hoisted var, nowhere else
+        expect(
+          (scene.yml.match(/accessByStage\.\$\{opt:stage\}/g) || []).length,
+        ).toBe(1);
+      });
+    });
+
+    when('[t1] the glue db + table IAM grants are read', () => {
+      // the vision names the cache AND the glue db as the SAME stage/access disease (D27). the
+      // cache dual-grant alone is a point-fix; the glue db + table owe the identical dual-grant, or
+      // the ancient stack's access-keyed glue lookup 403s exactly the way the cache did.
+      then('the glue db grants BOTH the stage-keyed and access-keyed name', () => {
+        expect(scene.yml).toContain(
+          'database/@declapract{variable.databaseName}_${self:provider.stage}',
+        );
+        // teeth: drop the access-keyed glue db grant and the glue instance of D27 reopens.
+        expect(scene.yml).toContain(
+          'database/@declapract{variable.databaseName}_${self:custom.access}',
+        );
+      });
+
+      then('the glue table grants BOTH the stage-keyed and access-keyed name', () => {
+        expect(scene.yml).toContain(
+          'table/@declapract{variable.databaseName}_${self:provider.stage}/*',
+        );
+        // teeth: drop the access-keyed glue table grant and the glue instance of D27 reopens.
+        expect(scene.yml).toContain(
+          'table/@declapract{variable.databaseName}_${self:custom.access}/*',
+        );
+      });
+    });
+  });
+});
+
+/**
+ * .what = end-to-end proof of the serverless.yml fix through the REAL declapract apply pipeline,
+ *         run against a genTempDir clone of a legacy consumer repo.
+ * .why  = serverless.yml.declapract.ts is a 17-transform fold of regex-over-structured-text
+ *         rewrites — per rule.require.declapract-integration-tests a transform-blocks fix REQUIRES
+ *         a test that runs the REAL executeApply, not a static template read. this proves what the
+ *         unit suite cannot: the `.declapract.ts` companion matched to `best-practice/serverless.yml`,
+ *         the file glob→match, the emitted file a consumer receives on disk, and a second-apply
+ *         fixed point.
+ * .note = INTEGRATION: reads the filesystem + runs executeApply against a temp clone. no credential,
+ *         no network. the fixture lives under a `.test` dot-dir (excluded from tsconfig/jest globs),
+ *         and mounts THIS repo's real `src` via the `src`→`src` symlink so declapract resolves the
+ *         serverless practice from source.
+ * .teeth = the env-block trio proves the CHAIN ORDER: withConnectionReuse anchors the legacy
+ *          NODE_ENV form and MUST run before withNodeEnvProduction rewrites that value to
+ *          `production`. so the presence of the connection-reuse flag beside a `NODE_ENV: production`
+ *          line proves the order held — a reorder that ran the production rewrite first would erase
+ *          the anchor and the flag would never land (the r007.b3 order-dependence clamp + the
+ *          r001.b1 pipeline clamp in one).
+ */
+describe('serverless practice — the real executeApply pipeline (r001.b1)', () => {
+  given('[case1] a legacy consumer serverless.yml (old runtime, legacy env block)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-serverless-fix',
+      clone: './src/practices/serverless/.test/assets/demo-repo-with-serverless',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const ymlPath = 'serverless.yml';
+    const read = () => fs.readFile(path.join(tempDir, ymlPath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'serverless',
+        file: ymlPath,
+      });
+
+    when('[t0] the legacy input (before any fix)', () => {
+      then('the serverless.yml input matches snapshot', async () => {
+        expect(await read()).toMatchSnapshot('serverless.yml — before');
+      });
+    });
+
+    when('[t1] the serverless fix is applied', () => {
+      useThen('apply the serverless fix', async () => applyFix());
+
+      then('the node runtime is bumped to the pinned major', async () => {
+        const yml = await read();
+        expect(yml).toContain('runtime: nodejs22.x');
+        expect(yml).not.toContain('nodejs14.x');
+      });
+
+      then('the legacy NODE_ENV value is rewritten to production', async () => {
+        const yml = await read();
+        expect(yml).toContain('NODE_ENV: production');
+        expect(yml).not.toContain('stageToNodeEnvMapping');
+      });
+
+      then('the connection-reuse flag lands beside the production NODE_ENV (chain-order teeth)', async () => {
+        const yml = await read();
+        // withConnectionReuse ran BEFORE withNodeEnvProduction: it anchored the legacy NODE_ENV form
+        // and inserted the flag on the next line, then the production rewrite hit the same line. the
+        // flag on the line after `NODE_ENV: production` proves the order held.
+        expect(yml).toContain(
+          'NODE_ENV: production # deploy with production optimizations of all resources, to make `prep` and `prod` stage deployments equivalent functionally (i.e., the same code paths in prep and prod)\n    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true',
+        );
+      });
+
+      then('the utc timezone guard is inserted under the env block', async () => {
+        const yml = await read();
+        expect(yml).toContain('TZ: UTC # guarantee');
+      });
+
+      then('the emitted file matches snapshot', async () => {
+        expect(await read()).toMatchSnapshot('serverless.yml — after');
+      });
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      const passes = useThen('a second fix over its own output', async () => {
+        const before = await read(); // post-first-fix
+        await applyFix(); // second apply
+        const after = await read();
+        return { before, after };
+      });
+
+      then('the second fix is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: src/examples
+  practices: src/practices
+  use-cases: src/useCases.yml

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/declapract.use.yml

@@ -0,0 +1,8 @@
+declarations: './'
+useCase: lambda-service-with-rds
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  infrastructureNamespaceId: 'testns'
+  databaseName: 'testdb'
+  slackWebhookUrl: 'https://hooks.slack.test/webhook'

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/serverless.yml

@@ -0,0 +1,8 @@
+service: test-project
+
+provider:
+  name: aws
+  runtime: nodejs14.x
+  stage: ${opt:stage}
+  environment:
+    NODE_ENV: ${self:custom.stageToNodeEnvMapping.${self:provider.stage}}

package/dist/practices/serverless/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,43 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`serverless practice — the real executeApply pipeline (r001.b1) given: [case1] a legacy consumer serverless.yml (old runtime, legacy env block) when: [t0] the legacy input (before any fix) then: the serverless.yml input matches snapshot: serverless.yml — before 1`] = `
+"service: test-project
+
+provider:
+  name: aws
+  runtime: nodejs14.x
+  stage: \${opt:stage}
+  environment:
+    NODE_ENV: \${self:custom.stageToNodeEnvMapping.\${self:provider.stage}}
+"
+`;
+
+exports[`serverless practice — the real executeApply pipeline (r001.b1) given: [case1] a legacy consumer serverless.yml (old runtime, legacy env block) when: [t1] the serverless fix is applied then: the emitted file matches snapshot: serverless.yml — after 1`] = `
+"# @declapract:review — could not auto-insert \`ACCESS: \${self:custom.access}\` + \`COMMIT: \${env:COMMIT}\` under \`environment:\` because no \`STAGE: \${self:provider.stage}\` env var was present to convert; add both as children of your \`environment:\` block by hand — the failing \`declapract plan\` diff names them.
+service: test-project
+
+variablesResolutionMode: 20210326
+
+package:
+  artifact: .artifact/contents.zip
+
+plugins:
+  - serverless-prune-plugin
+
+custom:
+  accessByStage:
+    dev: prep # stage=dev deploys to $service-dev but uses ACCESS=prep (config/prep.json)
+    prep: prep # stage=prep deploys to $service-prep also with ACCESS=prep; one service answers to both the -dev and -prep fleets while callers migrate
+    prod: prod
+  access: \${self:custom.accessByStage.\${opt:stage}, 'prep'} # the resolved access for this deploy — one source, referenced by the ACCESS env var + every access-keyed resource arn below, so a partial edit cannot re-split the stage/access axes
+
+provider:
+  name: aws
+  runtime: nodejs22.x
+  stage: \${opt:stage}
+  environment:
+    TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success
+    NODE_ENV: production # deploy with production optimizations of all resources, to make \`prep\` and \`prod\` stage deployments equivalent functionally (i.e., the same code paths in prep and prod)
+    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true # https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html
+"
+`;

package/dist/practices/serverless/__snapshots__/cache-grant-stage-globbed.declapract.integration.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`serverless shared-cache IAM grant globs the stage segment (#597) given: [case1] the shared domain-driven cache grant when: [t0] serverless.yml is read then: the emitted cache grant line matches snapshot: serverless cache IAM grant 1`] = `"- arn:aws:dynamodb:\${aws:region}:\${aws:accountId}:table/infrastructure-*-table-domain-driven-cache # global cache: one SHARED table, name-globbed so every fleet's role can read it — see .declapract.readme.md"`;

package/dist/practices/serverless/__snapshots__/deployment-bucket-account-scoped.declapract.integration.test.ts.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`serverless deployment bucket is account-scoped by stage (#596) given: [case2] the provider.deploymentBucket reference when: [t0] serverless.yml is read then: the emitted deploymentBucketByStage map matches snapshot: serverless deploymentBucketByStage map 1`] = `
+"  deploymentBucketByStage: # the deployment bucket is ACCOUNT-scoped: it must live in the account the deploy role assumes, so it is keyed by stage like accessByStage above
+    dev: serverless-deployment-@declapract{variable.infrastructureNamespaceId}-dev # prep-account bucket
+    prep: serverless-deployment-@declapract{variable.infrastructureNamespaceId}-dev # prep-account bucket, shared with the -dev fleet, so no separate -prep bucket need exist
+    prod: serverless-deployment-@declapract{variable.infrastructureNamespaceId}-prod # prod-account bucket — a prod deploy assumes the prod-account oidc role, which has no cross-account grant to the prep-account -dev bucket
+"
+`;

package/dist/practices/serverless/__snapshots__/divergentStageGuard.declapract.integration.test.ts.snap

@@ -0,0 +1,15 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`divergent-stage guard — the shipped templates cannot re-split the stage/access axis given: [case4] the deploy-command ACCESS fall-through when: [t0] every deploy command that derives SLS_STAGE is read then: the shipped deploy commands match snapshot (a reworded message reddens): serverless deploy commands 1`] = `
+{
+  "deploy": "if [ "\${ACCESS:-}" = 'prod' ]; then npm run deploy:prod; elif [ "\${ACCESS:-}" = 'prep' ]; then npm run deploy:prep; else echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi",
+  "deploy:prep": "ACCESS=prep npm run deploy:release",
+  "deploy:prod": "ACCESS=prod npm run deploy:release:ancient && npm run deploy:send-notification",
+  "deploy:prune": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && npx sls prune -n 7 --stage "\${SLS_STAGE:-}" && if [ "\${ACCESS:-}" = 'prep' ]; then npx sls prune -n 7 --stage prep; fi",
+  "deploy:release": "npm run deploy:release:ancient && npm run deploy:release:contemp",
+  "deploy:release:ancient": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && npm run build && sls deploy --verbose --stage "\${SLS_STAGE:-}"",
+  "deploy:release:contemp": "export COMMIT=$(npx sdk-environment get commit) && if [ "\${ACCESS:-}" = 'prep' ]; then sls deploy --verbose --stage prep; else echo '🛑 skip contemp dual-publish: ACCESS is not prep (contemp publishes the -prep- fleet only)'; fi",
+  "deploy:send-notification": "curl -X POST -H 'Content-type: application/json' --data "{\\"text\\":\\"$([ -z "\${DEPLOYER_NAME:-}" ] && git config user.name || echo "\${DEPLOYER_NAME:-}") has deployed $npm_package_name@v$npm_package_version:
+https://github.com/@declapract{variable.organizationName}/$npm_package_name/tree/v$npm_package_version\\"}" @declapract{variable.slackWebhookUrl}",
+}
+`;

package/dist/practices/serverless/__snapshots__/serverless.yml.declapract.integration.test.ts.snap

@@ -0,0 +1,165 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`serverless.yml given: a legacy serverless.yml — the full composed fix (snapshot + idempotency) then: the full composed fix matches snapshot (after): legacy serverless.yml — after 1`] = `
+"# @declapract:review — could not auto-insert \`ACCESS: \${self:custom.access}\` + \`COMMIT: \${env:COMMIT}\` under \`environment:\` because no \`STAGE: \${self:provider.stage}\` env var was present to convert; add both as children of your \`environment:\` block by hand — the failing \`declapract plan\` diff names them.
+service: svc-orders # orders domain service
+
+variablesResolutionMode: 20210326
+
+plugins:
+  - serverless-prune-plugin
+
+package:
+  artifact: .artifact/contents.zip
+
+custom:
+  accessByStage:
+    dev: prep # stage=dev deploys to $service-dev but uses ACCESS=prep (config/prep.json)
+    prep: prep # stage=prep deploys to $service-prep also with ACCESS=prep; one service answers to both the -dev and -prep fleets while callers migrate
+    prod: prod
+  access: \${self:custom.accessByStage.\${opt:stage}, 'prep'} # the resolved access for this deploy — one source, referenced by the ACCESS env var + every access-keyed resource arn below, so a partial edit cannot re-split the stage/access axes
+  deploymentBucketByStage: # the deployment bucket is ACCOUNT-scoped: it must live in the account the deploy role assumes, so it is keyed by stage like accessByStage above
+    dev: serverless-deployment-dev # prep-account bucket
+    prep: serverless-deployment-dev # prep-account bucket, shared with the -dev fleet, so no separate -prep bucket need exist
+    prod: serverless-deployment-prod # prod-account bucket — a prod deploy assumes the prod-account oidc role, which has no cross-account grant to the prep-account -dev bucket
+
+provider:
+  name: aws
+  runtime: nodejs22.x
+  memorySize: 1024
+  timeout: 60 # default timeout to 1min, for resilience against increased cold start times; individual functions can override this
+  stage: \${opt:stage}
+  environment:
+    TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success
+    NODE_ENV: production # deploy with production optimizations of all resources, to make \`prep\` and \`prod\` stage deployments equivalent functionally (i.e., the same code paths in prep and prod)
+    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true # https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html
+  deploymentBucket: \${self:custom.deploymentBucketByStage.\${opt:stage}, 'serverless-deployment-dev'} # account-scoped via deploymentBucketByStage above; provision the -prod bucket in the prod account before the first prod deploy, or a prod deploy trades a cross-account-deny for an absent-bucket error
+  iamRoleStatements:
+    # parameter store access
+    - Effect: Allow
+      Action:
+        - ssm:GetParameter
+        - ssm:GetParameters
+      Resource: arn:aws:ssm:\${aws:region}:\${aws:accountId}:parameter/*
+    # allow access inference from account name
+    - Effect: Allow
+      Action:
+        - account:GetAccountInformation
+      Resource: '*'
+    # allow invocation of other lambdas
+    - Effect: Allow
+      Action:
+        - lambda:InvokeFunction
+      Resource: '*'"
+`;
+
+exports[`serverless.yml given: a legacy serverless.yml — the full composed fix (snapshot + idempotency) then: the legacy input matches snapshot (before): legacy serverless.yml — before 1`] = `
+"service: svc-orders # orders domain service
+
+plugins:
+  - serverless-offline # local invoke for dev
+  - serverless-pseudo-parameters # obsolete once native vars land
+  - serverless-prune-plugin
+
+provider:
+  name: aws
+  runtime: nodejs18.x
+  memorySize: 1024
+  timeout: 10
+  stage: \${opt:stage}
+  environment:
+    NODE_ENV: \${self:custom.stageToNodeEnvMapping.\${self:provider.stage}}
+  deploymentBucket: serverless-deployment-\${self:provider.stage}
+  iamRoleStatements:
+    ## paramstore access
+    - Effect: Allow
+      Action: 'ssm:GetParameters'
+      Resource: arn:aws:ssm:#{AWS::Region}:#{AWS::AccountId}:parameter/*
+    # allow inferring access from account alias
+    - Effect: Allow
+      Action:
+        - iam:ListAccountAliases
+      Resource: '*'
+    ## allow invocation of other lambdas
+    - Effect: Allow
+      Action:
+        - lambda:InvokeFunction
+      Resource: '*'"
+`;
+
+exports[`serverless.yml given: a legacy sls.yaml that already holds a section under different content (r7 clobber-refusal) then: the section soft-skip injects an actionable @declapract:review marker, not a silent stall: section soft-skip custom clobber — review marker 1`] = `
+"service: svc-hascustom
+
+variablesResolutionMode: 20210326
+
+# @declapract:review — a \`custom:\` block is already present; merge the declared \`custom\` keys (from the failing \`declapract plan\` diff) into your extant \`custom:\` block by hand — auto-insert was declined to avoid a yaml last-wins clobber that would drop your block.
+custom:
+  domain: api.example.com
+
+package:
+  artifact: .artifact/contents.zip
+
+plugins:
+  - serverless-prune-plugin
+
+provider:
+  name: aws
+  stage: \${opt:stage}"
+`;
+
+exports[`serverless.yml given: a sls.yaml whose environment block exists but the anchors miss (r7 soft-skip) then: withUtcTimezone emits an actionable review marker when NODE_ENV sits below another env var: withUtcTimezone shuffled-env — review marker 1`] = `
+"# @declapract:review — could not auto-insert \`TZ: UTC\` under \`environment:\` because NODE_ENV is not the block's first key (the positional anchor missed); add \`TZ: UTC\` as a child of your \`environment:\` block by hand — the failing \`declapract plan\` diff names it.
+service: svc-shuffled
+
+variablesResolutionMode: 20210326
+
+package:
+  artifact: .artifact/contents.zip
+
+plugins:
+  - serverless-prune-plugin
+
+custom:
+  accessByStage:
+    dev: prep # stage=dev deploys to $service-dev but uses ACCESS=prep (config/prep.json)
+    prep: prep # stage=prep deploys to $service-prep also with ACCESS=prep; one service answers to both the -dev and -prep fleets while callers migrate
+    prod: prod
+  access: \${self:custom.accessByStage.\${opt:stage}, 'prep'} # the resolved access for this deploy — one source, referenced by the ACCESS env var + every access-keyed resource arn below, so a partial edit cannot re-split the stage/access axes
+
+provider:
+  name: aws
+  environment:
+    ACCESS: \${self:custom.access} # sdk-environment access, to target the correct config + resources (e.g., hit prep db -vs- prod db)
+    COMMIT: \${env:COMMIT} # sdk-environment commit slug, must be set by deploy command
+    NODE_ENV: production
+    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true # https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html"
+`;
+
+exports[`serverless.yml given: a sls.yaml with STAGE env var then: the composed fix over this example matches snapshot: STAGE example — after 1`] = `
+"service: svc-example
+
+variablesResolutionMode: 20210326
+
+package:
+  artifact: .artifact/contents.zip
+
+plugins:
+  - serverless-prune-plugin
+
+custom:
+  accessByStage:
+    dev: prep # stage=dev deploys to $service-dev but uses ACCESS=prep (config/prep.json)
+    prep: prep # stage=prep deploys to $service-prep also with ACCESS=prep; one service answers to both the -dev and -prep fleets while callers migrate
+    prod: prod
+  access: \${self:custom.accessByStage.\${opt:stage}, 'prep'} # the resolved access for this deploy — one source, referenced by the ACCESS env var + every access-keyed resource arn below, so a partial edit cannot re-split the stage/access axes
+
+provider:
+  name: aws
+  stage: \${opt:stage}
+  environment:
+    TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success
+    NODE_ENV: production
+    ACCESS: \${self:custom.access} # sdk-environment access, to target the correct config + resources (e.g., hit prep db -vs- prod db)
+    COMMIT: \${env:COMMIT} # sdk-environment commit slug, must be set by deploy command
+    AWS_NODEJS_CONNECTION_REUSE_ENABLED: true"
+`;

package/dist/practices/serverless/best-practice/.declapract.readme.md

@@ -0,0 +1,111 @@
+# serverless
+
+the serverless-framework deploy config for a lambda service.
+
+## dual-publish, across the ancient→contemp transition
+
+`custom.accessByStage` maps the deploy slug (`stage`) to the access (`ACCESS`):
+
+```yaml
+accessByStage:
+  dev: prep # stage=dev deploys $service-dev (ancient slug), runs ACCESS=prep
+  prep: prep # stage=prep deploys $service-prep (contemp slug), also ACCESS=prep
+  prod: prod
+```
+
+so a single `prep`-access service dual-publishes BOTH fleets from one artifact:
+`deploy:release` runs `deploy:release:ancient` (`--stage dev`) then `deploy:release:contemp`
+(`--stage prep`). `deploy:prune` prunes the ancient fleet always and the contemp (`-prep-`) fleet
+when `ACCESS=prep`, so neither accumulates unpruned versions. `deploy:prod` publishes the ancient
+(`prod`) fleet only — prod is `prod` on both axes, so it has no divergent slug.
+
+### why prod does NOT dual-publish (the contemp→prod edge)
+
+the dual-publish exists to bridge ONE divergence: below prod, `access=prep` deploys under a `-dev-`
+slug (ancient) while migrated callers address the `-prep-` slug (contemp). prod has no such
+divergence — `access=prod ⟺ stage=prod` — so there is one `-prod-` fleet and no second slug to
+publish.
+
+a contemp→prod 404 is therefore unreachable, because the `sdkAwsLambdaEnvAccess{Ancient|Contemp}`
+target helper resolves against the CALLER's OWN `access`, not a fixed `-prep-` string. a prod-access
+caller resolves BOTH `Ancient` and `Contemp` to `prod` (there is no dev/prep split at prod), so it
+always addresses the published `-prod-` fleet. the `-prep-` slug is only ever emitted by a
+`prep`-access caller, which addresses `prep`-tier peers — never a prod service. a `prep`-access
+caller that reaches a prod service is a cross-tier call, which is not a supported pattern and is not
+what dual-publish covers. so prod's ancient-only publish leaves no cross-service call uncovered.
+
+the north-star of the fix-lambdas wish is to retire the `stage` axis entirely; this dual-publish is
+the transition scaffold, built to be torn down once every peer addresses self by `access`. see
+`.behavior/v2026_08_31.fix-lambdas-3/1.vision.yield.md`.
+
+### the transition cost — watch the Lambda code-storage cap
+
+dual-publish doubles a service's deployed function count AND its code-storage footprint in the
+test/prep account, for the life of the transition. AWS Lambda's per-region **code storage is a
+75 GB soft cap**. before a fleet-wide dual-publish, confirm `usage × 2 < 75 GB` via
+`aws lambda get-account-settings` (the `AccountLimit.TotalCodeSize` vs `AccountUsage.TotalCodeSize`
+fields). the cap is soft (raisable by a support request), the 2× is transition-only, and it drops
+back to 1× at the north-star endpoint when the `-dev-` publish retires. function count has no hard
+cap, and concurrency is unaffected (the `-dev-` fleet takes ~no traffic).
+
+### this practice ships the ADD half only; the REMOVE half waits on an opt-in marker
+
+this practice adds the `accessByStage` insert + the dual IAM grants. it ships no paired remove.
+
+the remove half waits on an explicit opt-in marker that a consumer has completed its migration —
+the marker cannot be inferred from the filesystem, because a fresh scaffold and a fully-migrated
+consumer both hold zero `AccessAncient` imports, so any auto-strip re-adds and re-strips on each
+`declapract fix`. the marker also authorizes case=1's one-axis deletion.
+
+the transform that adds the scaffold is labeled in `serverless.yml.declapract.ts`. the full
+rationale is in the vision's settled design §2.
+
+## the deployment bucket is account-scoped, not just stage-scoped (#596)
+
+`custom.deploymentBucketByStage` keys the serverless deployment bucket by stage, the same shape as
+`accessByStage`:
+
+```yaml
+deploymentBucketByStage:
+  dev: serverless-deployment-<ns>-dev   # prep-account bucket (ancient slug)
+  prep: serverless-deployment-<ns>-dev  # prep-account bucket, shared with dev
+  prod: serverless-deployment-<ns>-prod # prod-account bucket
+```
+
+the deployment bucket is not merely service-scoped — it is **account-scoped**: it must live in the
+same account the deploy role assumes. a prod deploy assumes the prod-account oidc role
+(`ahbode-prod-oidc-for-apply`), which has no cross-account grant to the prep-account `-dev` bucket, so
+a single hardcoded `-dev` bucket fails a prod deploy at bucket lookup
+(`s3:GetBucketLocation ... not authorized`). the map keeps ancient (`dev`) + contemp (`prep`) on the
+one shared prep-account `-dev` bucket, and points `prod` at a prod-account `-prod` bucket, so every
+deploy's bucket sits in the account of its role.
+
+the -prod bucket must be provisioned in the prod account (e.g. via the terraform under
+`provision/aws/environments/prod/`), or the fix trades a cross-account-deny for an absent-bucket
+error. this is the deploy-bucket facet of the same prep→dev account divergence the `accessByStage` +
+dual-IAM sections above address; it collapses with the rest at the north-star `stage`→`access`
+endpoint.
+
+## the domain-driven-cache IAM — the middle segment is name-globbed, not templated (D27, #597)
+
+the `iamRoleStatements` grant for the global cache table globs the middle name segment, rather than
+template it on `provider.stage` or `custom.access`:
+
+```yaml
+Resource:
+  - arn:aws:dynamodb:...:table/infrastructure-*-table-domain-driven-cache
+```
+
+the cache is one SHARED dynamodb table addressed by a single name (below prod that name is `-dev-`),
+while a dual-publish service runs two fleets whose roles key on different slugs (ancient `dev`,
+contemp `prep`). a slug-templated grant covers only the deployed fleet's own slug — so the contemp
+`-prep-` fleet's `-dev-` cache read AccessDenies, and a with-simple-cache read-back throws a 500
+instead of a null. this was a real break on svc-gateway `prep / assure`: 3 chat endpoints 500'd on
+the contemp fleet only, and cloudwatch named the AccessDeny on
+`infrastructure-dev-table-domain-driven-cache` (#597).
+
+the glob covers `-dev-`, `-prep-`, and `-prod-` in one line. it stays least-privilege:
+account-scoped (`${aws:accountId}`) and name-scoped to the one cache family — it widens only across
+the middle segment, the axis the fleets differ on. the glob already covers every slug, so it needs
+no change at the north-star `stage`→`access` endpoint. tracked in the wish roster (D27,
+north-star tier-C).

package/dist/practices/serverless/best-practice/package.json

@@ -5,11 +5,13 @@
     "if-env": "@declapract{check.minVersion('1.0.4')}"
   },
   "scripts": {
-    "deploy:prune": "export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ \"$ACCESS\" = 'prep' ] && echo 'dev' || echo \"$ACCESS\") && npx sls prune -n 7 --stage $SLS_STAGE",
-    "deploy:release": "export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ \"$ACCESS\" = 'prep' ] && echo 'dev' || echo \"$ACCESS\") && npm run build && sls deploy --verbose --stage $SLS_STAGE",
-    "deploy:send-notification": "curl -X POST -H 'Content-type: application/json' --data \"{\\\"text\\\":\\\"$([ -z $DEPLOYER_NAME ] && git config user.name || echo $DEPLOYER_NAME) has deployed $npm_package_name@v$npm_package_version:\nhttps://github.com/@declapract{variable.organizationName}/$npm_package_name/tree/v$npm_package_version\\\"}\" @declapract{variable.slackWebhookUrl}",
+    "deploy:prune": "if [ \"${ACCESS:-}\" != 'prep' ] && [ \"${ACCESS:-}\" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ \"${ACCESS:-}\" = 'prep' ] && echo 'dev' || echo \"${ACCESS:-}\") && npx sls prune -n 7 --stage \"${SLS_STAGE:-}\" && if [ \"${ACCESS:-}\" = 'prep' ]; then npx sls prune -n 7 --stage prep; fi",
+    "deploy:release:ancient": "if [ \"${ACCESS:-}\" != 'prep' ] && [ \"${ACCESS:-}\" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ \"${ACCESS:-}\" = 'prep' ] && echo 'dev' || echo \"${ACCESS:-}\") && npm run build && sls deploy --verbose --stage \"${SLS_STAGE:-}\"",
+    "deploy:release:contemp": "export COMMIT=$(npx sdk-environment get commit) && if [ \"${ACCESS:-}\" = 'prep' ]; then sls deploy --verbose --stage prep; else echo '🛑 skip contemp dual-publish: ACCESS is not prep (contemp publishes the -prep- fleet only)'; fi",
+    "deploy:release": "npm run deploy:release:ancient && npm run deploy:release:contemp",
+    "deploy:send-notification": "curl -X POST -H 'Content-type: application/json' --data \"{\\\"text\\\":\\\"$([ -z \"${DEPLOYER_NAME:-}\" ] && git config user.name || echo \"${DEPLOYER_NAME:-}\") has deployed $npm_package_name@v$npm_package_version:\nhttps://github.com/@declapract{variable.organizationName}/$npm_package_name/tree/v$npm_package_version\\\"}\" @declapract{variable.slackWebhookUrl}",
     "deploy:prep": "ACCESS=prep npm run deploy:release",
-    "deploy:prod": "ACCESS=prod npm run deploy:release && npm run deploy:send-notification",
-    "deploy": "if-env ACCESS=prod && npm run deploy:prod && exit 0 || if-env ACCESS=prep && npm run deploy:prep && exit 0 || echo '🛑 invalid ACCESS, must be prod or prep' && exit 1"
+    "deploy:prod": "ACCESS=prod npm run deploy:release:ancient && npm run deploy:send-notification",
+    "deploy": "if [ \"${ACCESS:-}\" = 'prod' ]; then npm run deploy:prod; elif [ \"${ACCESS:-}\" = 'prep' ]; then npm run deploy:prep; else echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi"
   }
 }