@moretea-labs/forge 1.6.0 → 1.7.1

package/scripts/benchmark-route-session-concurrency.ts

@@ -12,6 +12,9 @@ import { createMcpToolContext } from '../src/cli/mcp/server';
 import { callMultiRepositoryTool } from '../src/cli/mcp/multi-repository';
 import { callRuntimeTool } from '../src/runtime/gateway/mcp/runtime-tools';
 import { createWorkContract } from '../src/runtime/control-plane/facade/work-contract-store';
+import { createRequirement } from '../src/runtime/control-plane/persistence/requirement-store';
+import { startGoalWorkloop } from '../src/runtime/control-plane/facade/goal-workloop';
+import { withPrimaryWorkAdmissionLockAsync } from '../src/runtime/control-plane/facade/semantic-admission';
 import { executionIdentityForRepository } from '../src/runtime/control-plane/execution/execution-identity';
 import { acquireRuntimeOwnership } from '../src/runtime/root/ownership';
 import { ensureActiveRuntimeRelease } from '../src/runtime/root/release-store';
@@ -47,6 +50,30 @@ interface Sample {
   metrics?: Record<string, number>;
 }
 
+interface SemanticAdmissionWorkerResult {
+  index: number;
+  requirementId: string;
+  status: string;
+  decision: string;
+  created: boolean;
+  authorityWorkId?: string;
+  criticalSectionMs: number;
+  criticalSectionCpuMs: number;
+  totalAdmissionMs: number;
+}
+
+interface SemanticAdmissionBurstResult {
+  controllers: number;
+  createdAuthorities: number;
+  uniqueAuthorityCount: number;
+  deterministicResolutions: number;
+  criticalSectionP50Ms: number;
+  criticalSectionP95Ms: number;
+  criticalSectionCpuP95Ms: number;
+  totalAdmissionP95Ms: number;
+  success: boolean;
+}
+
 function phases(): Phases {
   return Object.fromEntries(PHASES.map((phase) => [phase, 0])) as Phases;
 }
@@ -178,6 +205,138 @@ async function guarded(operation: () => Promise<Sample>): Promise<Sample> {
   }
 }
 
+function cliValue(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1]?.trim() : undefined;
+}
+
+async function semanticAdmissionWorker(): Promise<void> {
+  const controllerHome = cliValue('--controller-home');
+  const repoId = cliValue('--repo-id');
+  const storeRoot = cliValue('--store-root');
+  const requirementId = cliValue('--requirement-id');
+  const mode = cliValue('--semantic-mode');
+  const index = Number(cliValue('--worker-index'));
+  const startAt = Number(cliValue('--start-at'));
+  if (!controllerHome || !repoId || !storeRoot || !requirementId || !['same', 'independent'].includes(mode ?? '') || !Number.isFinite(index) || !Number.isFinite(startAt)) {
+    throw new Error('semantic admission worker arguments are incomplete');
+  }
+  const delayMs = Math.max(0, startAt - Date.now());
+  if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  let criticalSectionMs = 0;
+  let criticalSectionCpuMs = 0;
+  const started = performance.now();
+  const facade = await withPrimaryWorkAdmissionLockAsync({ controllerHome, repoId }, () => {
+    const entered = performance.now();
+    const cpuEntered = process.cpuUsage();
+    const value = startGoalWorkloop({
+      workStore: { controllerHome, repoId },
+      handoffStore: { root: join(storeRoot, 'handoff') },
+      repoId,
+      checkoutId: `semantic-${mode}-${index}`,
+      principalId: `semantic-principal-${index}`,
+      controllerInstanceId: `semantic-controller-${index}`,
+      sourceRevision: 'semantic-admission-benchmark',
+      semanticAdmissionLocked: true,
+    }, {
+      objective: mode === 'same'
+        ? 'Own the semantic admission benchmark requirement'
+        : `Own independent semantic admission requirement ${index}`,
+      requirementId,
+      requestedBy: 'chatgpt',
+      modeInput: {
+        scopeClear: true,
+        mutation: true,
+        expectedFiles: 4,
+        expectedChangedLines: 200,
+        requiresRecovery: true,
+        risk: 'local_repo_write',
+      },
+    });
+    criticalSectionMs = elapsed(entered);
+    const cpuElapsed = process.cpuUsage(cpuEntered);
+    criticalSectionCpuMs = (cpuElapsed.user + cpuElapsed.system) / 1_000;
+    return value;
+  });
+  const data = facade.data && typeof facade.data === 'object' ? facade.data as Record<string, unknown> : {};
+  const work = data.work && typeof data.work === 'object' ? data.work as Record<string, unknown> : undefined;
+  const recommendedWork = data.recommendedWork && typeof data.recommendedWork === 'object' ? data.recommendedWork as Record<string, unknown> : undefined;
+  const candidates = Array.isArray(data.candidates) ? data.candidates as Record<string, unknown>[] : [];
+  const authorityWorkId = [work?.workId, recommendedWork?.workId, candidates[0]?.workId]
+    .find((value): value is string => typeof value === 'string' && value.length > 0);
+  const result: SemanticAdmissionWorkerResult = {
+    index,
+    requirementId,
+    status: facade.status,
+    decision: typeof data.admissionDecision === 'string'
+      ? data.admissionDecision
+      : data.workContractCreated === true ? 'create_new' : 'unknown',
+    created: data.workContractCreated === true,
+    ...(authorityWorkId ? { authorityWorkId } : {}),
+    criticalSectionMs: Math.round(criticalSectionMs * 1000) / 1000,
+    criticalSectionCpuMs: Math.round(criticalSectionCpuMs * 1000) / 1000,
+    totalAdmissionMs: Math.round(elapsed(started) * 1000) / 1000,
+  };
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+async function runSemanticAdmissionBurst(input: {
+  controllerHome: string;
+  repoId: string;
+  storeRoot: string;
+  mode: 'same' | 'independent';
+  controllers?: number;
+}): Promise<SemanticAdmissionBurstResult> {
+  const controllers = input.controllers ?? 32;
+  mkdirSync(input.storeRoot, { recursive: true });
+  const startAt = Date.now() + 1_500;
+  const scriptPath = process.argv[1]!;
+  const children = Array.from({ length: controllers }, (_, index) => {
+    const requirementId = input.mode === 'same'
+      ? 'REQ-semantic-admission-benchmark-shared'
+      : `REQ-semantic-admission-benchmark-${index}`;
+    return Bun.spawn([
+      process.execPath,
+      scriptPath,
+      '--semantic-admission-worker',
+      '--controller-home', input.controllerHome,
+      '--repo-id', input.repoId,
+      '--store-root', input.storeRoot,
+      '--requirement-id', requirementId,
+      '--semantic-mode', input.mode,
+      '--worker-index', String(index),
+      '--start-at', String(startAt),
+    ], { stdout: 'pipe', stderr: 'pipe' });
+  });
+  const rows = await Promise.all(children.map(async (child) => {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    if (exitCode !== 0) throw new Error(`semantic admission worker failed (${exitCode}): ${stderr || stdout}`);
+    return JSON.parse(stdout.trim()) as SemanticAdmissionWorkerResult;
+  }));
+  const createdAuthorities = rows.filter((row) => row.created).length;
+  const authorityIds = new Set(rows.map((row) => row.authorityWorkId).filter((value): value is string => Boolean(value)));
+  const deterministicResolutions = rows.filter((row) => row.created || row.decision === 'reuse_existing' || row.decision === 'resolution_required').length;
+  const criticalValues = rows.map((row) => row.criticalSectionMs);
+  const success = input.mode === 'same'
+    ? createdAuthorities === 1 && authorityIds.size === 1 && deterministicResolutions === controllers
+    : createdAuthorities === controllers && authorityIds.size === controllers && deterministicResolutions === controllers;
+  return {
+    controllers,
+    createdAuthorities,
+    uniqueAuthorityCount: authorityIds.size,
+    deterministicResolutions,
+    criticalSectionP50Ms: percentile(criticalValues, 0.50),
+    criticalSectionP95Ms: percentile(criticalValues, 0.95),
+    criticalSectionCpuP95Ms: percentile(rows.map((row) => row.criticalSectionCpuMs), 0.95),
+    totalAdmissionP95Ms: percentile(rows.map((row) => row.totalAdmissionMs), 0.95),
+    success,
+  };
+}
+
 async function main(): Promise<void> {
   const iterationsIndex = process.argv.indexOf('--iterations');
   const outputIndex = process.argv.indexOf('--output');
@@ -190,6 +349,38 @@ async function main(): Promise<void> {
     const first = repositoryFixture(root, controllerHome, 'repository-a');
     const second = repositoryFixture(root, controllerHome, 'repository-b');
     const firstIsolated = worktreeFixture(root, controllerHome, first);
+    createRequirement({ controllerHome }, {
+      requirementId: 'REQ-semantic-admission-benchmark-shared',
+      title: 'Semantic admission benchmark shared authority',
+      outcomeStatement: 'Measure deterministic concurrent admission for one shared Requirement authority.',
+    });
+    for (let index = 0; index < 32; index += 1) {
+      createRequirement({ controllerHome }, {
+        requirementId: `REQ-semantic-admission-benchmark-${index}`,
+        title: `Semantic admission benchmark independent authority ${index}`,
+        outcomeStatement: 'Measure deterministic concurrent admission for an independent Requirement authority.',
+      });
+    }
+    const sameAuthorityAdmission = await runSemanticAdmissionBurst({ controllerHome, repoId: first.repository.repoId, storeRoot: join(root, 'semantic-same-authority'), mode: 'same' });
+    const independentRequirementAdmission = await runSemanticAdmissionBurst({ controllerHome, repoId: first.repository.repoId, storeRoot: join(root, 'semantic-independent-requirements'), mode: 'independent' });
+    const semanticAdmissionCriticalWallP95Ms = Math.max(sameAuthorityAdmission.criticalSectionP95Ms, independentRequirementAdmission.criticalSectionP95Ms);
+    const semanticAdmissionCriticalCpuP95Ms = Math.max(sameAuthorityAdmission.criticalSectionCpuP95Ms, independentRequirementAdmission.criticalSectionCpuP95Ms);
+    const semanticAdmission = {
+      sameAuthority: sameAuthorityAdmission,
+      independentRequirements: independentRequirementAdmission,
+      acceptance: {
+        minimumControllers: 32,
+        criticalSectionCpuP95ThresholdMs: 10,
+        criticalSectionCpuP95TargetMs: 5,
+        criticalSectionWallP95GuardrailMs: 100,
+        observedCriticalSectionCpuP95Ms: semanticAdmissionCriticalCpuP95Ms,
+        observedCriticalSectionWallP95Ms: semanticAdmissionCriticalWallP95Ms,
+        passed: sameAuthorityAdmission.success
+          && independentRequirementAdmission.success
+          && semanticAdmissionCriticalCpuP95Ms <= 10
+          && semanticAdmissionCriticalWallP95Ms <= 100,
+      },
+    };
     const results = new Map<string, Sample[]>();
     const run = async (name: string, operation: () => Promise<Sample>) => {
       results.set(name, [...(results.get(name) ?? []), await guarded(operation)]);
@@ -200,10 +391,11 @@ async function main(): Promise<void> {
         const timing = phases();
         const started = performance.now();
         const projectionStarted = performance.now();
-        const value = await callRuntimeTool(first.context, 'controller_context_pack', {
+        const value = await callRuntimeTool(first.context, 'rh_context', {
           repo_id: first.repository.repoId,
-          variant: 'summary',
-          force_refresh: true,
+          operation: 'search',
+          query: 'benchmark repository context cold read',
+          structural_context: 'off',
         });
         timing.projectionMs = elapsed(projectionStarted);
         timing.gitObservationMs = timing.projectionMs;
@@ -218,9 +410,11 @@ async function main(): Promise<void> {
         const timing = phases();
         const started = performance.now();
         const projectionStarted = performance.now();
-        const value = await callRuntimeTool(first.context, 'controller_context_pack', {
+        const value = await callRuntimeTool(first.context, 'rh_context', {
           repo_id: first.repository.repoId,
-          variant: 'summary',
+          operation: 'search',
+          query: 'benchmark repository context cold read',
+          structural_context: 'off',
         });
         timing.projectionMs = elapsed(projectionStarted);
         const serializationStarted = performance.now();
@@ -696,7 +890,9 @@ async function main(): Promise<void> {
         sameCheckoutContention: 'leaseWaitMs is the bounded end-to-end admission time for the conflicting second Process, including identity/persistence work around the Lease decision.',
         checkIdentity: 'The cache identity is derived from repository-scoped storage plus content revision, check definition digest, environment/toolchain fingerprint, timeout contract, and reuse scope. Session and request ids are subscribers, not cache-key inputs.',
         checkCacheMetrics: 'physicalExecutions/logicalSubscribers/coalesced/cacheHits/invalidations/crossCheckoutReuses are summed across measured iterations.',
+        semanticAdmission: 'Two 32-process bursts share one repository-scoped semantic admission lock: one contends for a single Requirement authority and one admits 32 independent Requirement identities. Critical-section latency measures only canonical ownership resolution and persistence inside the lock.',
       },
+      semanticAdmission,
       scenarios: Object.fromEntries([...results].map(([name, samples]) => [name, summarize(samples)])),
     };
     const serialized = `${JSON.stringify(report, null, 2)}\n`;
@@ -705,10 +901,15 @@ async function main(): Promise<void> {
       writeFileSync(outputPath, serialized);
     }
     process.stdout.write(serialized);
+    if (!semanticAdmission.acceptance.passed) process.exitCode = 1;
   } finally {
     clearRuntimeWriteClaimForTests();
     rmSync(root, { recursive: true, force: true });
   }
 }
 
-await main();
+if (process.argv.includes('--semantic-admission-worker')) {
+  await semanticAdmissionWorker();
+} else {
+  await main();
+}

package/scripts/benchmark-thin-harness-mcp-e2e.ts

@@ -37,6 +37,7 @@ import {
 } from '../src/runtime/resources/leases/store';
 import type { MultiRepositoryMcpToolContext } from '../src/cli/mcp/multi-repository';
 import { waitForProcess } from '../src/runtime/execution/process-runtime/runtime';
+import { isLightweightProcessId, waitForLightweightProcess } from '../src/runtime/execution/process-runtime/lightweight-managed';
 
 function git(root: string, args: string[]): void {
   const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf-8' });
@@ -245,7 +246,12 @@ async function sampleCase(
   // the next sample so a correct same-checkout resource claim is not misreported
   // as a benchmark regression.
   if (phases.path === 'process_managed' && processId) {
-    await waitForProcess(fixture.controllerHome, fixture.repository.repoId, processId, { timeoutMs: 10_000 });
+    const settled = isLightweightProcessId(processId)
+      ? await waitForLightweightProcess(fixture.controllerHome, fixture.repository.repoId, processId, { timeoutMs: 10_000 })
+      : await waitForProcess(fixture.controllerHome, fixture.repository.repoId, processId, { timeoutMs: 10_000 });
+    if (!settled.completed) {
+      throw new Error(`BENCHMARK_PROCESS_DID_NOT_SETTLE: ${processId}`);
+    }
   }
   return {
     ...phases,

package/scripts/benchmark-typescript-navigation.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env bun
+
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { performance } from 'perf_hooks';
+import {
+  clearTypeScriptNavigationCache,
+  navigateTypeScriptSymbol,
+  type TypeScriptNavigationKind,
+} from '../src/runtime/context/typescript-navigation';
+
+interface BenchmarkCase {
+  label: string;
+  path: string;
+  symbol: string;
+  marker: string;
+}
+
+const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+const cases: BenchmarkCase[] = [
+  {
+    label: 'repository command execution',
+    path: 'src/cli/repositories/command-executor.ts',
+    symbol: 'executeRepositoryCommand',
+    marker: 'export function executeRepositoryCommand(',
+  },
+  {
+    label: 'MCP repository dispatch',
+    path: 'src/cli/mcp/repository-tools.ts',
+    symbol: 'callRepositoryTool',
+    marker: 'export async function callRepositoryTool(',
+  },
+  {
+    label: 'canonical Runtime proxy',
+    path: 'src/cli/mcp/server.ts',
+    symbol: 'createCanonicalRuntimeProxy',
+    marker: 'export function createCanonicalRuntimeProxy(',
+  },
+  {
+    label: 'Runtime MCP dispatch',
+    path: 'src/runtime/gateway/mcp/runtime-tools.ts',
+    symbol: 'callRuntimeTool',
+    marker: 'export async function callRuntimeTool(',
+  },
+  {
+    label: 'Lightweight command execution',
+    path: 'src/runtime/execution/process-runtime/lightweight-managed.ts',
+    symbol: 'startLightweightRepositoryCommand',
+    marker: 'export async function startLightweightRepositoryCommand(',
+  },
+];
+const requestedSymbols = new Set(
+  String(process.env.FORGE_TSNAV_BENCHMARK_SYMBOLS ?? '')
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean),
+);
+const benchmarkCases = requestedSymbols.size === 0
+  ? cases
+  : cases.filter((case_) => requestedSymbols.has(case_.symbol));
+if (benchmarkCases.length === 0) {
+  throw new Error(`No benchmark cases match FORGE_TSNAV_BENCHMARK_SYMBOLS=${[...requestedSymbols].join(',')}`);
+}
+
+function target(case_: BenchmarkCase): { line: number; column: number } {
+  const text = readFileSync(resolve(repoRoot, case_.path), 'utf8');
+  const markerOffset = text.indexOf(case_.marker);
+  if (markerOffset < 0) throw new Error(`marker not found for ${case_.label}: ${case_.marker}`);
+  const symbolOffset = markerOffset + case_.marker.indexOf(case_.symbol);
+  const before = text.slice(0, symbolOffset);
+  const lines = before.split('\n');
+  return { line: lines.length, column: (lines.at(-1)?.length ?? 0) + 1 };
+}
+
+function navigate(case_: BenchmarkCase, navigation: TypeScriptNavigationKind) {
+  const point = target(case_);
+  return navigateTypeScriptSymbol(repoRoot, { navigation, path: case_.path, ...point });
+}
+
+function lexicalMatches(symbol: string): string[] {
+  try {
+    const output = execFileSync('git', ['grep', '-n', '-w', symbol, '--', 'src', 'scripts', 'tests'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      maxBuffer: 8 * 1024 * 1024,
+    }).trim();
+    return output ? output.split('\n') : [];
+  } catch {
+    return [];
+  }
+}
+
+function percentile(values: number[], ratio: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((left, right) => left - right);
+  const index = Math.min(sorted.length - 1, Math.floor(sorted.length * ratio));
+  return Math.round((sorted[index] ?? 0) * 100) / 100;
+}
+
+const results = [];
+for (const case_ of benchmarkCases) {
+  clearTypeScriptNavigationCache();
+  // This first reference call represents the user-visible cold path.
+  const coldReferenceStartedAt = performance.now();
+  const coldReferences = navigate(case_, 'references');
+  const coldReferenceMs = performance.now() - coldReferenceStartedAt;
+
+  // Then separately initialize a fresh project through the cheap definition
+  // query and measure references on that already-built Language Service. This
+  // makes project construction and high-fanout reference cost visible instead
+  // of attributing both to one opaque cold number.
+  clearTypeScriptNavigationCache();
+  const projectSetupStartedAt = performance.now();
+  const coldDefinition = navigate(case_, 'definition');
+  const projectSetupMs = performance.now() - projectSetupStartedAt;
+  const firstReferenceStartedAt = performance.now();
+  const firstReferencesOnPreparedProject = navigate(case_, 'references');
+  const firstReferenceOnPreparedProjectMs = performance.now() - firstReferenceStartedAt;
+
+  const warmDurations: number[] = [];
+  let warmReferences = firstReferencesOnPreparedProject;
+  for (let index = 0; index < 3; index += 1) {
+    const startedAt = performance.now();
+    warmReferences = navigate(case_, 'references');
+    warmDurations.push(performance.now() - startedAt);
+  }
+  const definitions = navigate(case_, 'definition');
+  const implementations = navigate(case_, 'implementations');
+  const lexical = lexicalMatches(case_.symbol);
+
+  results.push({
+    label: case_.label,
+    symbol: case_.symbol,
+    target: { path: case_.path, ...target(case_) },
+    semantic: {
+      coldReferenceLocations: coldReferences.locations.length,
+      coldDefinitionLocations: coldDefinition.locations.length,
+      references: warmReferences.locations.length,
+      definitions: definitions.locations.length,
+      implementations: implementations.locations.length,
+      crossFileReferences: warmReferences.locations.filter((location) => location.path !== case_.path).length,
+      sampleReferences: warmReferences.locations.slice(0, 8),
+    },
+    lexical: {
+      exactMatches: lexical.length,
+      sampleMatches: lexical.slice(0, 8),
+    },
+    latencyMs: {
+      coldReferences: Math.round(coldReferenceMs * 100) / 100,
+      projectSetupViaDefinition: Math.round(projectSetupMs * 100) / 100,
+      firstReferencesOnPreparedProject: Math.round(firstReferenceOnPreparedProjectMs * 100) / 100,
+      warmReferences: warmDurations.map((value) => Math.round(value * 100) / 100),
+    },
+  });
+}
+clearTypeScriptNavigationCache();
+
+const preparedReferenceDurations = results.map((entry) => entry.latencyMs.firstReferencesOnPreparedProject);
+const warmReferenceDurations = results.flatMap((entry) => entry.latencyMs.warmReferences);
+const thresholds = {
+  firstReferencesOnPreparedProjectP95MaxMs: 250,
+  warmReferencesP95MaxMs: 150,
+};
+const assertions = {
+  allDefinitionsResolved: results.every((entry) => entry.semantic.definitions >= 1),
+  allReferencesResolved: results.every((entry) => entry.semantic.references >= 1),
+  allImplementationsResolved: results.every((entry) => entry.semantic.implementations >= 1),
+  crossFileSemanticReferencesResolved: results.every((entry) => entry.semantic.crossFileReferences >= 1),
+  preparedReferenceLatencyBounded: percentile(preparedReferenceDurations, 0.95) <= thresholds.firstReferencesOnPreparedProjectP95MaxMs,
+  warmReferenceLatencyBounded: percentile(warmReferenceDurations, 0.95) <= thresholds.warmReferencesP95MaxMs,
+};
+const output = {
+  repoRoot,
+  requestedSymbols: [...requestedSymbols],
+  cases: results,
+  summary: {
+    firstReferencesOnPreparedProjectP95Ms: percentile(preparedReferenceDurations, 0.95),
+    warmReferencesP95Ms: percentile(warmReferenceDurations, 0.95),
+  },
+  thresholds,
+  assertions,
+  passed: Object.values(assertions).every(Boolean),
+};
+console.log(JSON.stringify(output, null, 2));
+if (!output.passed) process.exitCode = 1;