enhance(#2872): record scope and runtime in the install manifest (#3323)

* enhance(#2872): record scope and runtime in the install manifest

gsd-file-manifest.json gains manifestVersion, runtime and scope, and a new
read-only Installed Surface Resolver Module reads both install scopes for a
runtime in one call -- the first code path in the repo that does.

Phase 3 of epic #2866 (ADR-2866). Blocks Phase 4 (#2873), which resolves
#2218: the resolver's shadowedBy field is that defect expressed as a value
for the first time. It ships computed-and-unread here.

Installed-ness is decided by manifest PRESENCE, never by the new fields, so
a manifest written by an older GSD stays fully functional and no user needs
to reinstall. Recorded runtime/scope are corroboration: a disagreement with
the probed config dir is reported as declaredScopeMatchesProbe: false, never
silently corrected.

readInstallManifest is widened additively -- version/timestamp/mode/files
keep their exact names, types and meanings for all four existing callers.
manifestVersion is a new field rather than a reinterpretation of version,
which holds the package version and is read by the golden-parity fixtures.

Stems are derived from the installed manifest's own file keys, the inverse
of Phase 2's filename composition, guarded by a fast-check round-trip
property plus a kebab-case charset check so a crafted manifest key cannot
put a traversal segment, control character or ANSI escape into a trigger
that Phase 4 renders back to the user.

Also fixes two defects found while working:
- bin/install.js hardcoded manifestVersion: 2 while the reader owned
  MANIFEST_SCHEMA_VERSION = 2. Now single-sourced, with a parity test.
- docs/installer-migrations.md documented an install-state schema of five
  snake_case fields that have never been written; InstallState has only ever
  been { schemaVersion, appliedMigrations }. Corrected with a dated note.

Verification runs on the remote runner.

* fix(#2872): fold review findings from three independent engines

Standards axis:
- convert the manifest-schema suite from a hybrid setup(t) closure to
  beforeEach/afterEach (CONTRIBUTING.md:319-354 Pattern 1). The hybrid was
  neither approved pattern and a new test forgetting the call got no warning.
- SCOPE_ORDER was declared twice with no parity test -- this repo's recorded
  generative-fix-divergence class. Give the ordering one owner: install-scope
  exports it frozen, the layout module and the resolver both import it, and a
  test locks it against scopeRank so the constant and the ranks cannot drift.
- drop the defaultReadManifest passthrough (Middle Man).

Spec axis:
- add the VOLATILE_FILES exclusion test and source comment the acceptance
  table promised and did not deliver. gsd-file-manifest.json stays excluded:
  the new fields are deterministic, but timestamp -- the original reason --
  is unchanged.

Security axis:
- bound the reported manifest runtime at 64 chars, matching the
  truncatePostureValue convention already used in this subsystem. It reached
  declaredRuntime unbounded while the adjacent stems were gated by SAFE_STEM;
  an inconsistent posture on the same attacker-influenceable document. The
  charset stays ungated on purpose -- declaredRuntimeMatchesProbe needs to see
  the real value -- so Phase 4 must sanitize before rendering, recorded in the
  design's Known limits.

Both new parity tests were verified to FAIL when the two sides are made to
disagree, then pass again on revert. Verification runs on the remote runner.

* chore(#2872): backfill changeset pr number to 3323

* fix(#2872): give git fixture construction its own timeout class

PR #3323's full test (windows-latest, 22, shard 2/3) failed with

  gitOrThrow: 'git init' failed -- outcome=timed_out exitCode=null
  gitOrThrow: 'git commit --allow-empty' failed -- outcome=timed_out

from drift-detection.test.cjs's beforeEach, a file this branch never touched.
Every other lane passed the same commit, including windows-latest node 24 on
all three shards, and next is green.

Root cause is a bound sized for the wrong class. DEFAULT_GIT_TIMEOUT_MS is
15000 and its own comment scopes it to plumbing READS -- rev-parse, branch,
log -- against an existing repo. createFixture uses it for six sequential
repo-CONSTRUCTION spawns: init, three config writes, add -A, commit. init and
commit each write dozens of files, and on Windows every spawn is
Defender-scanned. Sibling tests in the failing block took 15.6-22.0s against
a 15000ms bound.

This repo already diagnosed this exact shape once: timeouts.cjs's
HOOK_FANOUT_TIMEOUT_MS records PR #3285 failing in the SAME job with the SAME
outcome=timed_out exitCode=null signature at the SAME bound while every other
lane passed, and concludes 'a bound sized for the wrong class, not a slow
machine'. It was fixed by splitting out a heavier class-norm at 60000. Same
remedy here: GIT_FIXTURE_TIMEOUT_MS = 60000, 4x the bound that failed and half
INSTALL_TIMEOUT_MS.

DEFAULT_GIT_TIMEOUT_MS deliberately stays at 15000 -- a blanket raise would
stop a genuinely hung plumbing read from surfacing fast.

Verified the value reaches the spawn rather than being an ignored option:
spawnSync was monkeypatched before requiring the fixture module, and all six
git construction calls were captured carrying timeout: 60000.

This branch's two new test files shift shard composition, which is how a
pre-existing fragility landed in the heaviest shard on the slowest lane.
Fixed here rather than deferred, per the no-defer rule.

Verification runs on the remote runner.

---------

Co-authored-by: sim <sim@local>

tests/helpers/git-fixture.cjs

@@ -50,6 +50,31 @@ const { runGit, OUTCOME } = require('./process-seam.cjs');
  */
 const DEFAULT_GIT_TIMEOUT_MS = 15000;
 
+/**
+ * Timeout for git calls that CONSTRUCT a fixture repository, in milliseconds.
+ *
+ * A distinct class from `DEFAULT_GIT_TIMEOUT_MS` above, which is sized for
+ * plumbing READS (rev-parse, branch, log) against an existing repo.
+ * `createFixture` (`tests/fixtures/index.cjs`) issues SIX sequential spawns to
+ * build one repo — `init`, three `config` writes, `add -A`, `commit` — and
+ * `init`/`commit` each write dozens of files. On Windows every one of those
+ * spawns is Defender-scanned, so the construction sequence is materially
+ * heavier than any single read.
+ *
+ * CI (PR #3323, `full test (windows-latest, 22, shard 2/3)`) recorded
+ * `gitOrThrow: git init failed — outcome=timed_out exitCode=null` and the same
+ * for `git commit --allow-empty`, with sibling tests in the same block taking
+ * 15.6-22.0s, while every other lane — including windows-latest node 24, all
+ * three shards — passed the same commit. That is a bound sized for the wrong
+ * class, not a slow machine: the identical conclusion, in the identical job,
+ * that `HOOK_FANOUT_TIMEOUT_MS` records for PR #3285.
+ *
+ * 60000ms is 4x the bound that failed and half `INSTALL_TIMEOUT_MS` — the same
+ * ratio `HOOK_FANOUT_TIMEOUT_MS` uses, and the right order for a call that is
+ * far heavier than a plumbing read but much lighter than a full installer run.
+ */
+const GIT_FIXTURE_TIMEOUT_MS = 60000;
+
 /**
  * Throw on anything other than a clean (exit 0) process-seam result,
  * preserving the legacy `execSync`/`execFileSync` throw-on-failure idiom
@@ -147,4 +172,10 @@ function toLegacyResult(result) {
   return { status: result.exitCode, stdout: result.stdout, stderr: result.stderr };
 }
 
-module.exports = { gitOrThrow, throwIfFailed, toLegacyResult, DEFAULT_GIT_TIMEOUT_MS };
+module.exports = {
+  gitOrThrow,
+  throwIfFailed,
+  toLegacyResult,
+  DEFAULT_GIT_TIMEOUT_MS,
+  GIT_FIXTURE_TIMEOUT_MS,
+};

tests/helpers/install-shared.cjs

@@ -154,6 +154,11 @@ const PKG_VERSION = require('../../package.json').version;
 // that cause hash drift between local (PKG_VERSION=1.x.x) and CI (PKG_VERSION=1.x.x-rc.N):
 // the PKG_VERSION normalization below replaces only the *current* version, but
 // CHANGELOG.md references prior-release versions, so the normalized hash diverges.
+// gsd-file-manifest.json's exclusion was revisited deliberately for #2872: the
+// manifest gained `manifestVersion`/`runtime`/`scope` fields, all of which are
+// deterministic and would not by themselves force an exclusion, but `timestamp`
+// — the original reason this file is volatile — is unchanged by #2872, so the
+// exclusion still holds for exactly the same reason it always has.
 const VOLATILE_FILES = new Set([
   'gsd-file-manifest.json',
   'gsd-install-state.json',

tests/helpers/timeouts.cjs

@@ -21,7 +21,7 @@
  * sites onto a shared value that doesn't describe them.
  */
 
-const { DEFAULT_GIT_TIMEOUT_MS } = require('./git-fixture.cjs');
+const { DEFAULT_GIT_TIMEOUT_MS, GIT_FIXTURE_TIMEOUT_MS } = require('./git-fixture.cjs');
 
 /**
  * A single short CLI query or `node -e` probe against a temp fixture —
@@ -62,6 +62,13 @@ const HOOK_FANOUT_TIMEOUT_MS = 60000;
  */
 const GIT_TIMEOUT_MS = DEFAULT_GIT_TIMEOUT_MS;
 
+/**
+ * Git fixture CONSTRUCTION calls (init/config/add/commit) — a heavier class
+ * than `GIT_TIMEOUT_MS`. See `tests/helpers/git-fixture.cjs`'s
+ * `GIT_FIXTURE_TIMEOUT_MS` for the full rationale (PR #3323); re-exported
+ * here rather than restated so the two can never disagree.
+ */
+
 /**
  * Hooks bundling via `scripts/build-hooks.js` (not a full project build —
  * see per-site comments for sites that run a heavier build and therefore
@@ -83,6 +90,7 @@ module.exports = {
   PROBE_TIMEOUT_MS,
   HOOK_FANOUT_TIMEOUT_MS,
   GIT_TIMEOUT_MS,
+  GIT_FIXTURE_TIMEOUT_MS,
   BUILD_TIMEOUT_MS,
   INSTALL_TIMEOUT_MS,
 };