[pranems]

Summary

Isolate the reviewed two-file standalone non-UTC freshness test correction
from 84d11af7658d91c3d3392831a088b89f54279b1d as a master-based prerequisite.
Replace redundant nested Jest startup with a real Node leaf, without changing
the 30-second child or 35-second parent deadline or any application behavior.

The real-source receipt additionally checks the actual entrypoint and loader,
New York January offset 300, exactly one snapshot read and both UTC timestamps.
No product/version/lockfile/Hono or performance-runner changes are included.
Product version remains 0.55.58.

Linked Defect / Plan Reference

• DELIVERY_PLAN.md defect ID: Related [security] pinned dependency review needed #248 protected-publication prerequisite; this PR does not remediate or close the Hono advisory.
• Audit doc reference: docs/ENDPOINT_SNAPSHOT_REVISION.md, "Test-harness prerequisite: real non-UTC leaf (2026-10-23)".
• ADR (if applicable): N/A, test-only correction using existing tooling.

The independent Hono branch and all its commits remain preserved at
e18d32c04855e8acf88c8a3e02c9ec7b447cfb21. Qualification #251 remains
preserved at f6f03a523b6370eccc63f1499c3c111dd5cdf200. No checkpoint053
Linux/leaf-finalization or other performance-tooling changes were imported.

TDD Process

• RED test written first; observed it fail for the expected reason
  • The existing real-child test's retained ordinary full-hook failure is the
    observed RED: spawnSync node.exe ETIMEDOUT, elapsed 30,119ms, null exit
    status, SIGTERM, 6,209 units passed and one failed.
  • This was a child deadline failure, not a timestamp-value assertion failure;
    the old isolated PASS is not substituted for it.
• GREEN: minimal implementation that turns the test green
  • All 21 focused freshness cases pass with the existing deadlines.
• Refactor (if any) keeps the test green
  • No production refactor. Actual production UTC interpretation was restored
    byte-identically after the negative control.
• Permanent regression guard added (where applicable - see existing patterns in api/src/security/)
  • The actual child must report standalone entrypoint/loader, offset, read
    count and exact timestamps; fixture asserts it is the direct main module.
  • Reinstating the former nested launcher fails on the missing leaf receipt,
    even when its selected child test exits successfully (19.832s).
  • Removing the actual source's UTC interpretation makes both timestamps
    05:00Z rather than 00:00Z and fails the real-leaf assertion (5.374s).
    Neither negative-control edit is committed.

Feature / Bug-Fix Commit Checklist (standing rule)

Every behavioral change must include all that apply. Tick or strike through with N/A + reason.

• Unit Tests - service-level and controller-level coverage of the new behavior
  • Existing service freshness file retains all 21 cases; no controller behavior changes.
• E2E Tests - end-to-end spec under api/test/e2e/ exercising the feature through HTTP
  • N/A for new coverage: no HTTP behavior change. Existing protected HTTP suite passes 2,514 tests with 42 existing backend skips.
• Live Integration Tests - new section in scripts/live-test.ps1 runnable against local + Docker + Azure
  • N/A: test-harness-only prerequisite; no live mutation or new wire contract.
• Feature Documentation - dedicated doc in docs/ with architecture, RFC references, Mermaid diagrams, test coverage
  • Existing endpoint-snapshot doc updated with focused proof, RCA and scope; no new architecture or RFC claim.
• INDEX.md Update - add the new doc reference to docs/INDEX.md
  • N/A: existing indexed document, no new documentation entry.
• CHANGELOG.md Update - [Unreleased] entry with full test counts and feature summary
  • Focused case count is unchanged at 21; final protected totals are below.
• Session & Context Updates - Session_starter.md and docs/CONTEXT_INSTRUCTIONS.md
• Version Management - bump api/package.json (and any other version refs) when behavior changed
  • N/A: no product behavior change; manifests and lockfiles remain byte-identical to master.
• Response Contract Tests - API responses contain ONLY documented fields (key allowlist assertion at unit + E2E + live)
  • N/A: no response contract change; exact child receipt uses full-object equality.

Validation Output

Source tip:   5a42eb09bbfc5d2a011911e6b01cc114f0665f8c
Focused:      21 / 21 freshness cases PASS after production restoration, 4.423s
Unit:         6,210 / 6,210 PASS (213 suites)
E2E:          2,514 PASS, 42 existing backend skips (118 passing suites)
Lint:         0 errors, owning gate PASS
Protected:    25 / 25 normal Fast gates PASS, 689.1s
Web:          tsc + production build PASS; CI Vitest 1,655 / 1,655 PASS (124 files)
Em-dash:      introduced diff clean
Exact-tip CI: push + PR Build Test Image, CodeQL and Docs freshness PASS
Hosted review: COMMENTED, approval recommended, no findings or review threads
Human GitHub approval: not claimed; normal configured-gate merge recorded below

Exact commands and outcomes:

• npm --prefix api test -- --runInBand --runTestsByPath src/modules/endpoint/services/endpoint-cache-freshness.spec.ts: PASS 21/21, initially 5.961s and after both negative controls/restoration 4.423s.
• With only the former launcher reinstated, npm --prefix api test -- --runInBand --runTestsByPath src/modules/endpoint/services/endpoint-cache-freshness.spec.ts --testNamePattern='checks PostgreSQL timestamp hydration in a real non-UTC Node process': expected FAIL on missing leaf receipt; old selected child succeeds.
• With actual production UTC interpretation temporarily removed, the same one-test command: expected FAIL on both real timestamp values; production restored exactly.
• From api, npx --no-install eslint src/modules/endpoint/services/endpoint-cache-freshness.spec.ts: PASS.
• node --check api/test/fixtures/endpoint-timezone-probe.cjs: PASS.
• From api, with TZ=America/New_York and PERSISTENCE_BACKEND=prisma, node --require ts-node/register/transpile-only test/fixtures/endpoint-timezone-probe.cjs: PASS; actual leaf receipt retained.
• pwsh -NoProfile -File scripts/audit-doc-freshness.ps1 -BaseRef origin/master -Quiet: PASS, 27 docs.
• $env:VITEST_MAX_WORKERS='2'; $env:PREPUSH_MODE='Fast'; git push -u origin test/timezone-leaf-prerequisite-20261023: PASS, normal hook, all 25 gates.
• Owning hook ran npm test and npm run test:e2e -- --maxWorkers=2 --testPathIgnorePatterns 'endpoint-scoped-logs.e2e-spec.ts' --testPathIgnorePatterns 'log-config.e2e-spec.ts' under its unchanged InMemory environment: both PASS with counts above.
• git diff --quiet origin/master -- api/package.json web/package.json package-lock.json api/package-lock.json web/package-lock.json api/src/modules/endpoint/services/endpoint.service.ts: PASS, no product/dependency/production delta.
• Hosted Ubuntu/Node 24 CI ran the existing workflow's npm test from api: PASS, 6,210 tests / 213 suites; unchanged InMemory HTTP command above: PASS, 2,514 tests / 118 suites and 42 existing backend skips.
• Hosted CI ran npm test from web: PASS, 1,655 tests / 124 files; npm run build from web: PASS.

Exact-tip hosted evidence, all at 5a42eb09bbfc5d2a011911e6b01cc114f0665f8c:

Evidence	Result
Push Build Test Image 39960769700	PASS
PR Build Test Image 39960938143	PASS, including unchanged container smoke and image scan
CodeQL 39960938089	PASS
Docs freshness 39960938060	PASS
Hosted Copilot review 5628884972	COMMENTED, approval recommended, no open issues

The review body and inline-thread query were both inspected: there are no findings
and no review threads to address or resolve. This is not human approval.
Only the separately authorized normal prerequisite merge occurred; no Hono
merge, deployment, performance rerun or candidate admission occurred.
The workflow's test-image build and isolated smoke are CI checks, not a live
deployment or qualification of the separate future Hono candidate.

Normal prerequisite merge: immediately rechecked exact head, all seven
successful checks, clean mergeability and absence of comments/threads.
Operator-authorized non-admin gh pr merge --merge --match-head-commit 5a42eb09bbfc5d2a011911e6b01cc114f0665f8c merged this PR at
fc962a65e03b2a0cb1ad86b96b88c473d6d07b7d. No squash, rebase, admin bypass
or human GitHub approval is claimed. The actual configured rules did not
require a separate GitHub approval.

Authoritative merged-source Build Test Image 39962553306
and CodeQL 39962437032
PASS at that exact merge SHA. One hosted matrix owns this proof; no duplicate
manual full matrix was run. Immutable CI test-image digest:
sha256:93ab5bd73465bdd215eeb2e3471022188d854d97a730d50b752c17e00eb238b0.
It still contains the old dependencies and is not patched-Hono proof.

Retained focused and protected logs:
test-results/timezone-prerequisite-20261023/.
Original observed RED:
test-results/hono-security-20261023/bootstrap-push-final.log.

Standing Rules Acknowledgment

• No em-dash (Unicode U+2014) anywhere in the diff. Verified via Select-String -Pattern ([char]0x2014).
• No git commit --amend on history that has been pushed.
• No new credentials, tokens, or secrets committed to source. Forbidden patterns regression spec at api/src/security/forbidden-source-patterns.spec.ts will catch known anti-patterns.
• Migrations are additive-only (expand-contract for column changes). Migration linter at api/src/scripts/lint-migrations.ts enforces this. N/A: no migrations.

Destructive Migration Override (skip if not applicable)

N/A: no database or migration changes.

• This PR contains a NEW destructive Prisma migration (DROP TABLE/COLUMN, ALTER COLUMN ... TYPE, RENAME, INSERT ... SELECT FROM)
• I have set ALLOW_DESTRUCTIVE_MIGRATION=1 in the CI environment for this PR
• Justification (required if box above is ticked):

  <!-- Why this destructive change is necessary, what the rollback path is, and which release window it ships in -->
  

Reviewer Hint

Diff areas worth special attention from the reviewer:

• The parent executes a real leaf rather than another Jest suite; the child
  timeout remains 30,000ms and the parent remains 35,000ms.
• The leaf calls actual source and reports actual process identity. It copies
  neither timestamp conversion nor cache-freshness logic.
• No dependency/version/lockfile, gate-orchestrator or performance source is changed.
• Reverting this prerequisite restores only the old test harness; Hono remediation
  stays independently reviewable.
• All frozen performance failures and migration, operational, cleanup and human
  visual-verification holds remain unchanged. No merge, deployment, benchmark
  rerun, candidate admission or waiver is requested.

Self-improvement: applied, permanent actual runtime launcher receipt.
Design disposition: accepted, a cohesive test-only fixture needs no speculative
application abstraction or process framework.

[Copilot]

🟢 Approval recommended

The bounded test-harness change preserves production behavior and timestamp coverage, with no unresolved review findings.

No open issues 🎉

What changed in this PR

This test-only prerequisite replaces nested Jest startup with a standalone Node process for endpoint timestamp hydration checks. It leaves production behavior, dependencies, versioning, and performance qualification unchanged; Hono remediation remains separate.

Changes:

• Load the actual TypeScript service and repository through the existing ts-node loader.
• Assert the child’s entrypoint, loader, timezone offset, snapshot-read count, and UTC timestamps while preserving both deadlines.
• Document the timeout failure, negative controls, and scope boundaries.

Design disposition: accepted; the small, cohesive fixture needs no new application abstraction. Self-improvement: applied through permanent runtime identity assertions.

File	Description
Session_starter.md	Records prerequisite scope, evidence, and remaining publication steps.
docs/​strategy/​ENGINEERING_LESSONS_AND_PATTERNS.md	Documents standalone-process testing and runtime identity checks.
docs/​ENDPOINT_SNAPSHOT_REVISION.md	Explains the timeout, correction, and negative-control evidence.
docs/​CONTEXT_INSTRUCTIONS.md	Updates delivery context without changing release holds.
CHANGELOG.md	Records the test-only correction and unchanged product scope.
api/​test/​fixtures/​endpoint-timezone-probe.cjs	Adds a real-source Node fixture emitting timestamp and runtime evidence.
api/​src/​modules/​endpoint/​services/​endpoint-cache-freshness.spec.ts	Launches the fixture and validates its complete receipt within existing deadlines.

_{Review effort: Balanced}