@hegemonart/get-design-done 1.27.5 → 1.27.6

package/scripts/lib/cache/gdd-cache-manager.cjs

@@ -0,0 +1,292 @@
+/**
+ * scripts/lib/cache/gdd-cache-manager.cjs — Plan 27.6-03
+ *
+ * Cache-warming heuristic (Phase 10.1 cost-governance refinement,
+ * Phase 27.6 D-06): score each candidate entry as the multiplicative
+ * product of three [0,1]-normalized components — recency, frequency,
+ * cost — and warm the top-N entries per cycle.
+ *
+ * Eviction policy: LRU within the warmed set. When a new top-rank
+ * candidate arrives, it displaces the oldest-touched entry from the
+ * warmed slot (D-06 wording).
+ *
+ * Telemetry: each per-cycle decision emits a `cache.warm_decision`
+ * event via Phase 22 event-stream so the Phase 27.6-01 perf-analyzer
+ * can surface "false-positive rate exceeds threshold" proposals
+ * (D-02: 20% default; configurable via
+ * `.design/budget.json#cache_warming_falsepositive_threshold`).
+ *
+ * Pure functions + side-effects-via-appendEvent. No external deps
+ * beyond `node:` builtins and the lazy event-stream require.
+ *
+ * @module scripts/lib/cache/gdd-cache-manager
+ */
+'use strict';
+
+// `node:fs` and `node:path` are required by the contract (lazy
+// future-extension surface for budget.json reads); event-stream is
+// loaded lazily via try/catch so this library is consumable from pure
+// CommonJS runtimes that cannot strip TypeScript on the fly.
+const path = require('node:path'); // eslint-disable-line no-unused-vars
+const fs = require('node:fs');     // eslint-disable-line no-unused-vars
+
+/**
+ * Default top-N candidates warmed per cycle. Override per-call via
+ * `rankWarmCandidates({ entries, topN })` or via
+ * `.design/budget.json#cache_warm_topn` at the caller level.
+ *
+ * @type {number}
+ */
+const DEFAULT_TOPN = 10;
+
+/**
+ * Default false-positive tolerance threshold percentage (D-02).
+ * When more than this percent of warmed entries are evicted before
+ * being read in a single cycle, the heuristic emits a per-cycle
+ * `cache.warm_decision` summary event so the perf-analyzer can flag
+ * the heuristic as mis-tuned.
+ *
+ * Configurable per-call via the `falsePositiveThresholdPct` argument
+ * to `summarizeFalsePositiveRate`, or at the project level via
+ * `.design/budget.json#cache_warming_falsepositive_threshold`.
+ *
+ * @type {number}
+ */
+const DEFAULT_FALSE_POSITIVE_THRESHOLD_PCT = 20;
+
+/**
+ * Clamp a number to the [0, 1] range. Non-finite / non-numeric inputs
+ * collapse to 0 — by design, since a non-numeric component cannot
+ * meaningfully participate in the multiplicative score.
+ *
+ * @param {unknown} n
+ * @returns {number}
+ */
+function clamp01(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+/**
+ * Lazily resolve the Phase 22 event-stream `appendEvent` function.
+ * The event-stream is shipped as `index.ts` (TypeScript); under a
+ * pure-CommonJS runtime that cannot strip TS on the fly, the require
+ * will throw. We swallow that and return a no-op so this library
+ * stays usable in any caller — tests, CJS scripts, or the
+ * cache-manager slash skill — without forcing them to install a
+ * TS loader.
+ *
+ * @returns {(ev: object) => void}
+ */
+function getAppendEvent() {
+  try {
+    // Resolved relative to this file: `scripts/lib/cache/` → `../event-stream`.
+    const m = require('../event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch {
+    // Swallow — fall through to the no-op below. The event is
+    // best-effort telemetry; losing one decision is acceptable.
+  }
+  return function noopAppend(_ev) { /* event-stream unavailable */ };
+}
+
+/**
+ * Compute the multiplicative warming score for a single candidate
+ * (D-06). Each component is clamped to [0, 1] before multiplication;
+ * any zero component zeroes the entire score by design — all three
+ * dimensions (recency, frequency, cost) must be non-zero for an
+ * entry to be a warm candidate at all.
+ *
+ * @param {{recency_score:number, frequency_score:number, cost_score:number}} components
+ * @returns {number} score in [0, 1]
+ */
+function computeWarmingScore({ recency_score, frequency_score, cost_score } = {}) {
+  const r = clamp01(recency_score);
+  const f = clamp01(frequency_score);
+  const c = clamp01(cost_score);
+  return r * f * c;
+}
+
+/**
+ * Rank a list of cache candidates by multiplicative warming score and
+ * return the top-N as the warmed set, with the remainder as eviction
+ * candidates. Pure: no I/O, no event emission.
+ *
+ * Component normalization:
+ *   recency_score   = 1 / (1 + days_since_last_use)
+ *   frequency_score = uses_in_window / window_size              (clamped)
+ *   cost_score      = est_cost_usd / max(est_cost_usd)          (clamped)
+ *
+ * If all entries have `est_cost_usd === 0`, all cost_scores collapse
+ * to 0 (and therefore all final scores collapse to 0) — the heuristic
+ * never warms cost-free entries, by design.
+ *
+ * Eviction policy: entries beyond the top-N rank are returned in
+ * `evictionCandidates`. The caller (cache-manager skill) treats the
+ * warmed set as LRU internally — when a new entry beats an existing
+ * warmed entry, the LRU entry in the warmed set is the one displaced.
+ *
+ * @param {{
+ *   entries?: Array<{
+ *     key: string,
+ *     days_since_last_use?: number,
+ *     uses_in_window?: number,
+ *     window_size?: number,
+ *     est_cost_usd?: number,
+ *     last_touched_at?: string,
+ *   }>,
+ *   topN?: number,
+ * }} args
+ * @returns {{warmed: Array<object>, evictionCandidates: Array<object>}}
+ */
+function rankWarmCandidates({ entries, topN } = {}) {
+  const N = typeof topN === 'number' && topN > 0 ? Math.floor(topN) : DEFAULT_TOPN;
+  const list = Array.isArray(entries) ? entries : [];
+  if (list.length === 0) return { warmed: [], evictionCandidates: [] };
+
+  // Determine the per-cycle max cost for normalization. If everything
+  // is free, the cost dimension contributes 0 to every score (which
+  // zeroes the multiplicative product — that's intentional).
+  let maxCost = 0;
+  for (const e of list) {
+    const c = typeof e.est_cost_usd === 'number' && e.est_cost_usd > 0 ? e.est_cost_usd : 0;
+    if (c > maxCost) maxCost = c;
+  }
+
+  const scored = list.map((e) => {
+    const days = typeof e.days_since_last_use === 'number' && e.days_since_last_use >= 0
+      ? e.days_since_last_use
+      : Infinity;
+    const recency_score = days === Infinity ? 0 : 1 / (1 + days);
+
+    const usesIn = typeof e.uses_in_window === 'number' && e.uses_in_window >= 0
+      ? e.uses_in_window
+      : 0;
+    const win = typeof e.window_size === 'number' && e.window_size > 0
+      ? e.window_size
+      : 1;
+    const frequency_score = clamp01(usesIn / win);
+
+    const cost = typeof e.est_cost_usd === 'number' && e.est_cost_usd >= 0
+      ? e.est_cost_usd
+      : 0;
+    const cost_score = maxCost > 0 ? clamp01(cost / maxCost) : 0;
+
+    const score = computeWarmingScore({ recency_score, frequency_score, cost_score });
+    return { ...e, recency_score, frequency_score, cost_score, score };
+  });
+
+  // Sort by score descending. Stable order on ties is fine for v1.
+  scored.sort((a, b) => b.score - a.score);
+
+  const warmed = scored.slice(0, N);
+  const evictionCandidates = scored.slice(N);
+  return { warmed, evictionCandidates };
+}
+
+/**
+ * Emit one `cache.warm_decision` event recording the outcome of a
+ * single warmed entry: was it used before being evicted, or did the
+ * heuristic mis-warm (false-positive)?
+ *
+ * Called per warmed entry at eviction time by the cache layer. The
+ * 27.6-01 perf-analyzer aggregates these to compute per-cycle
+ * false-positive rates.
+ *
+ * Side effect only — returns void. The function is best-effort:
+ * if the event-stream is unavailable, the emission silently no-ops.
+ *
+ * @param {{
+ *   entry: {key:string, score:number, recency_score:number, frequency_score:number, cost_score:number},
+ *   usedBeforeEviction: boolean,
+ *   evictionEvent?: {at?: string, reason?: string},
+ *   sessionId?: string,
+ * }} args
+ * @returns {void}
+ */
+function evaluateWarmingDecision({ entry, usedBeforeEviction, evictionEvent, sessionId } = {}) {
+  const append = getAppendEvent();
+  const e = entry && typeof entry === 'object' ? entry : {};
+  append({
+    type: 'cache.warm_decision',
+    timestamp: new Date().toISOString(),
+    sessionId: typeof sessionId === 'string' && sessionId.length > 0
+      ? sessionId
+      : 'cache-manager',
+    payload: {
+      entry_key: typeof e.key === 'string' ? e.key : 'unknown',
+      score: typeof e.score === 'number' ? e.score : 0,
+      recency_score: typeof e.recency_score === 'number' ? e.recency_score : 0,
+      frequency_score: typeof e.frequency_score === 'number' ? e.frequency_score : 0,
+      cost_score: typeof e.cost_score === 'number' ? e.cost_score : 0,
+      used_before_eviction: !!usedBeforeEviction,
+      evicted_at: evictionEvent && typeof evictionEvent.at === 'string'
+        ? evictionEvent.at
+        : undefined,
+    },
+  });
+}
+
+/**
+ * Aggregate a cycle's worth of per-entry decisions into a single
+ * false-positive rate. If the rate exceeds the configured threshold
+ * (D-02 default 20%), emit a per-cycle summary `cache.warm_decision`
+ * event so the perf-analyzer can flag the heuristic as mis-tuned.
+ *
+ * Returns the computed rate + threshold context regardless of whether
+ * an event was emitted, so the caller can route the result into its
+ * own reporting surface (e.g. the cache-manager slash skill's status
+ * output).
+ *
+ * @param {{
+ *   decisions?: Array<{entry_key?:string, used_before_eviction?:boolean, score?:number}>,
+ *   falsePositiveThresholdPct?: number,
+ *   sessionId?: string,
+ * }} args
+ * @returns {{false_positive_rate:number, count:number, threshold_pct:number, exceeds_threshold:boolean}}
+ */
+function summarizeFalsePositiveRate({ decisions, falsePositiveThresholdPct, sessionId } = {}) {
+  const list = Array.isArray(decisions) ? decisions : [];
+  const total = list.length;
+  let evictedUnused = 0;
+  for (const d of list) {
+    if (d && d.used_before_eviction === false) evictedUnused++;
+  }
+  const false_positive_rate = total === 0 ? 0 : evictedUnused / total;
+  const threshold_pct = typeof falsePositiveThresholdPct === 'number' && Number.isFinite(falsePositiveThresholdPct)
+    ? falsePositiveThresholdPct
+    : DEFAULT_FALSE_POSITIVE_THRESHOLD_PCT;
+  const exceeds_threshold = false_positive_rate * 100 > threshold_pct;
+
+  if (exceeds_threshold) {
+    const append = getAppendEvent();
+    append({
+      type: 'cache.warm_decision',
+      timestamp: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' && sessionId.length > 0
+        ? sessionId
+        : 'cache-manager',
+      payload: {
+        entry_key: '<cycle-summary>',
+        score: 0,
+        recency_score: 0,
+        frequency_score: 0,
+        cost_score: 0,
+        false_positive_rate,
+      },
+    });
+  }
+
+  return { false_positive_rate, count: total, threshold_pct, exceeds_threshold };
+}
+
+module.exports = {
+  computeWarmingScore,
+  rankWarmCandidates,
+  evaluateWarmingDecision,
+  summarizeFalsePositiveRate,
+  DEFAULT_TOPN,
+  DEFAULT_FALSE_POSITIVE_THRESHOLD_PCT,
+};

package/scripts/lib/discuss-parallel-runner/index.ts

@@ -29,6 +29,7 @@
 
 import { OperationFailedError } from '../gdd-errors/index.ts';
 import { getLogger } from '../logger/index.ts';
+import { resolveConcurrency } from '../parallelism-engine/concurrency-tuner.cjs';
 
 import {
   spawnAggregator,
@@ -137,9 +138,12 @@ export async function run(
 ): Promise<DiscussRunnerResult> {
   const logger = getLogger();
   const specs = opts.discussants ?? DEFAULT_DISCUSSANTS;
+  // Phase 27.6 D-07: data-driven concurrency default. Falls back to
+  // min(cpu-1, 8) when no `parallelism.verdict` events exist in
+  // .design/telemetry/events.jsonl. Explicit `opts.concurrency` still wins.
   const concurrency = opts.concurrency !== undefined && opts.concurrency > 0
     ? opts.concurrency
-    : 4;
+    : resolveConcurrency();
   const cwd = opts.cwd ?? process.cwd();
 
   logger.info('discuss.runner.started', {

package/scripts/lib/explore-parallel-runner/index.ts

@@ -25,6 +25,7 @@
 import { resolve as resolvePath } from 'node:path';
 
 import { getLogger } from '../logger/index.ts';
+import { resolveConcurrency } from '../parallelism-engine/concurrency-tuner.cjs';
 
 import {
   isParallelismSafe,
@@ -120,7 +121,10 @@ export async function run(
 ): Promise<ExploreRunnerResult> {
   const specs: readonly MapperSpec[] = opts.mappers ?? DEFAULT_MAPPERS;
   const cwd: string = opts.cwd ?? process.cwd();
-  const concurrency: number = opts.concurrency ?? 4;
+  // Phase 27.6 D-07: data-driven concurrency default. Falls back to
+  // min(cpu-1, 8) when no `parallelism.verdict` events exist in
+  // .design/telemetry/events.jsonl. Explicit `opts.concurrency` still wins.
+  const concurrency: number = opts.concurrency ?? resolveConcurrency();
 
   const logger = getLogger().child('explore.runner');
 

package/scripts/lib/parallelism-engine/concurrency-tuner.cjs

@@ -0,0 +1,259 @@
+/**
+ * scripts/lib/parallelism-engine/concurrency-tuner.cjs — Plan 27.6-04
+ *
+ * Data-driven concurrency resolver per Phase 27.6 D-07. Reads the
+ * most-recent `parallelism.verdict` event from .design/telemetry/
+ * events.jsonl (Phase 22 stream) and computes:
+ *
+ *   resolveConcurrency = max(1, min(min(cpu-1, last_observed), ceiling))
+ *
+ * where:
+ *   cpu           = os.cpus().length (override via cpuCount opt)
+ *   last_observed = payload.observed_concurrency from the latest
+ *                   parallelism.verdict event (null if absent)
+ *   ceiling       = process.env.GDD_CONCURRENCY_CEILING (default 8)
+ *
+ * Hard ceiling of 8 prevents pathological process-spawn storms on
+ * high-core machines (D-07 wording: "Hard ceiling prevents pathological
+ * process-spawn storms").
+ *
+ * Public surface:
+ *   * resolveConcurrency({cpuCount?, lastObservedOptimum?, hardCeiling?,
+ *                        eventsPath?, baseDir?}) -> number  (>=1)
+ *   * readLastObservedOptimum({eventsPath?, baseDir?}) -> number|null
+ *   * emitParallelismVerdict({task_ids, verdict, reason,
+ *                            intended_concurrency?, observed_concurrency?,
+ *                            contention_detected?, wall_clock_ms?,
+ *                            sessionId?}) -> void
+ *   * DEFAULT_HARD_CEILING (=8)
+ *   * DEFAULT_EVENTS_PATH (='.design/telemetry/events.jsonl')
+ *
+ * The `parallelism.verdict` payload extension is purely additive
+ * (`intended_concurrency`, `observed_concurrency`, `contention_detected`,
+ * `wall_clock_ms` are all optional). Existing consumers that only read
+ * `{task_ids, verdict, reason}` keep working unchanged.
+ *
+ * No external deps. Lazy event-stream require for emit (best-effort
+ * telemetry — a failed event-stream load must not break the resolver).
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const DEFAULT_HARD_CEILING = 8;
+const DEFAULT_EVENTS_PATH = '.design/telemetry/events.jsonl';
+
+/**
+ * Lazy-require the event-stream module. Returns a no-op `appendEvent`
+ * when the module is unavailable so callers never have to wrap emit
+ * calls in try/catch themselves.
+ *
+ * @returns {(ev: object) => void}
+ */
+function getAppendEvent() {
+  try {
+    // Resolved relative to this file: scripts/lib/parallelism-engine/
+    // -> ../event-stream. The event-stream module is .ts; Node 22+
+    // with --experimental-strip-types (or Node 24 built-in TS) can
+    // require it. If require fails (e.g., older runtime, missing
+    // module), fall through to the no-op.
+    const m = require('../event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch {
+    // Swallow — best-effort telemetry. Losing one verdict is
+    // acceptable; breaking concurrency resolution is not.
+  }
+  return function noopAppend(_ev) {
+    /* event-stream unavailable */
+  };
+}
+
+/**
+ * Resolve the hard ceiling. Operator override via GDD_CONCURRENCY_CEILING
+ * env var (parsed as integer) takes precedence; the explicit `override`
+ * argument wins over the env. Default is 8 (D-07).
+ *
+ * @param {number|undefined} override
+ * @returns {number}
+ */
+function resolveCeiling(override) {
+  if (typeof override === 'number' && override >= 1) return Math.floor(override);
+  const env = process.env.GDD_CONCURRENCY_CEILING;
+  if (typeof env === 'string' && env.length > 0) {
+    const parsed = parseInt(env, 10);
+    if (Number.isFinite(parsed) && parsed >= 1) return parsed;
+  }
+  return DEFAULT_HARD_CEILING;
+}
+
+/**
+ * Compose the JSONL events path. Relative paths are joined to baseDir
+ * when supplied; absolute paths are returned as-is.
+ *
+ * @param {{eventsPath?: string, baseDir?: string}} opts
+ * @returns {string}
+ */
+function resolvePath({ eventsPath, baseDir }) {
+  let p = typeof eventsPath === 'string' && eventsPath.length > 0
+    ? eventsPath
+    : DEFAULT_EVENTS_PATH;
+  if (baseDir && !path.isAbsolute(p)) p = path.join(baseDir, p);
+  return p;
+}
+
+/**
+ * Read .design/telemetry/events.jsonl and return the
+ * `observed_concurrency` from the MOST RECENT parallelism.verdict event
+ * (sequential read order). Tolerates malformed lines and absent file.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.eventsPath] override events.jsonl path
+ * @param {string} [opts.baseDir]    base for relative eventsPath
+ * @returns {number|null}
+ */
+function readLastObservedOptimum({ eventsPath, baseDir } = {} ) {
+  const target = resolvePath({ eventsPath, baseDir });
+  if (!fs.existsSync(target)) return null;
+  let body;
+  try {
+    body = fs.readFileSync(target, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = body.split(/\r?\n/);
+  let lastOptimum = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const ev = JSON.parse(trimmed);
+      if (
+        ev
+        && ev.type === 'parallelism.verdict'
+        && ev.payload
+        && typeof ev.payload.observed_concurrency === 'number'
+      ) {
+        lastOptimum = Math.floor(ev.payload.observed_concurrency);
+      }
+    } catch {
+      // Tolerate malformed line — JSONL is best-effort.
+    }
+  }
+  return lastOptimum;
+}
+
+/**
+ * Resolve the recommended concurrency per D-07.
+ *
+ *   1. base       = max(1, cpuCount - 1)         // never below 1
+ *   2. optimum    = lastObservedOptimum         // explicit override
+ *                   ?? readLastObservedOptimum() // or read from JSONL
+ *   3. candidate  = optimum > 0 ? min(base, optimum) : base
+ *   4. ceiling    = override ?? GDD_CONCURRENCY_CEILING ?? 8
+ *   5. return max(1, min(candidate, ceiling))
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.cpuCount]            override os.cpus().length
+ * @param {number|null} [opts.lastObservedOptimum] explicit override; null/undefined triggers JSONL read
+ * @param {number} [opts.hardCeiling]         override the env/default ceiling
+ * @param {string} [opts.eventsPath]          override events.jsonl path
+ * @param {string} [opts.baseDir]             base for relative eventsPath
+ * @returns {number} integer >= 1
+ */
+function resolveConcurrency({
+  cpuCount,
+  lastObservedOptimum,
+  hardCeiling,
+  eventsPath,
+  baseDir,
+} = {}) {
+  const cpu = typeof cpuCount === 'number' && cpuCount >= 1
+    ? Math.floor(cpuCount)
+    : os.cpus().length;
+  const base = Math.max(1, cpu - 1);
+  let optimum = lastObservedOptimum;
+  if (optimum === undefined || optimum === null) {
+    optimum = readLastObservedOptimum({ eventsPath, baseDir });
+  }
+  const candidate = typeof optimum === 'number' && optimum >= 1
+    ? Math.min(base, Math.floor(optimum))
+    : base;
+  const ceiling = resolveCeiling(hardCeiling);
+  return Math.max(1, Math.min(candidate, ceiling));
+}
+
+/**
+ * Emit a `parallelism.verdict` event with the Phase 27.6 superset
+ * payload. Existing fields ({task_ids, verdict, reason}) are always
+ * present; the new fields (intended_concurrency, observed_concurrency,
+ * contention_detected, wall_clock_ms) are appended only when supplied.
+ *
+ * Side effect: appendEvent({type: 'parallelism.verdict', ...}). When
+ * event-stream is unavailable, this is a no-op (lazy require fallback).
+ *
+ * @param {object} opts
+ * @param {string[]} opts.task_ids
+ * @param {'parallel'|'sequential'} opts.verdict
+ * @param {string}  opts.reason
+ * @param {number}  [opts.intended_concurrency]
+ * @param {number}  [opts.observed_concurrency]
+ * @param {boolean} [opts.contention_detected]
+ * @param {number}  [opts.wall_clock_ms]
+ * @param {string}  [opts.sessionId]
+ * @returns {void}
+ */
+function emitParallelismVerdict({
+  task_ids,
+  verdict,
+  reason,
+  intended_concurrency,
+  observed_concurrency,
+  contention_detected,
+  wall_clock_ms,
+  sessionId,
+} = {}) {
+  const append = getAppendEvent();
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    task_ids: Array.isArray(task_ids) ? task_ids : [],
+    verdict: verdict === 'parallel' || verdict === 'sequential' ? verdict : 'sequential',
+    reason: typeof reason === 'string' ? reason : 'unspecified',
+  };
+  // Additive 27.6 fields — only include when set, to keep payloads
+  // compact and avoid noisy `undefined` keys on the wire.
+  if (typeof intended_concurrency === 'number') {
+    payload.intended_concurrency = intended_concurrency;
+  }
+  if (typeof observed_concurrency === 'number') {
+    payload.observed_concurrency = observed_concurrency;
+  }
+  if (typeof contention_detected === 'boolean') {
+    payload.contention_detected = contention_detected;
+  }
+  if (typeof wall_clock_ms === 'number') {
+    payload.wall_clock_ms = wall_clock_ms;
+  }
+  try {
+    append({
+      type: 'parallelism.verdict',
+      timestamp: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' && sessionId.length > 0
+        ? sessionId
+        : 'concurrency-tuner',
+      payload,
+    });
+  } catch {
+    // Best-effort telemetry. A failed write must never break the
+    // caller's wave-execution flow.
+  }
+}
+
+module.exports = {
+  resolveConcurrency,
+  readLastObservedOptimum,
+  emitParallelismVerdict,
+  DEFAULT_HARD_CEILING,
+  DEFAULT_EVENTS_PATH,
+};

package/scripts/lib/parallelism-engine/concurrency-tuner.d.cts

@@ -0,0 +1,53 @@
+// scripts/lib/parallelism-engine/concurrency-tuner.d.cts — types for concurrency-tuner.cjs (Phase 27.6 D-07).
+
+export interface ResolveConcurrencyOptions {
+  /** Override CPU count detection (defaults to `os.cpus().length`). */
+  cpuCount?: number;
+  /** Override last-observed optimum (else read from event-chain). */
+  lastObservedOptimum?: number;
+  /** Hard ceiling cap. Defaults to `DEFAULT_HARD_CEILING` (8). */
+  hardCeiling?: number;
+  /** Event-chain path override (else use `DEFAULT_EVENTS_PATH`). */
+  eventsPath?: string;
+  /** Base directory override (else `process.cwd()`). */
+  baseDir?: string;
+}
+
+export interface ReadLastObservedOptimumOptions {
+  eventsPath?: string;
+  baseDir?: string;
+}
+
+export interface EmitParallelismVerdictPayload {
+  task_ids?: string[];
+  verdict?: string;
+  reason?: string;
+  intended_concurrency?: number;
+  observed_concurrency?: number;
+  contention_detected?: boolean;
+  wall_clock_ms?: number;
+}
+
+/**
+ * Resolve the concurrency default per D-07: `min(cpu-1, last_observed_optimum, hard_ceiling)`.
+ * Falls back to `cpu-1` capped at `hard_ceiling` when no prior verdict exists.
+ */
+export function resolveConcurrency(opts?: ResolveConcurrencyOptions): number;
+
+/**
+ * Read the latest `parallelism.verdict` event's optimum from the event chain.
+ * Returns null when no prior verdict exists.
+ */
+export function readLastObservedOptimum(
+  opts?: ReadLastObservedOptimumOptions,
+): number | null;
+
+/**
+ * Emit a `parallelism.verdict` event (additive payload — back-compat preserved).
+ */
+export function emitParallelismVerdict(
+  payload?: EmitParallelismVerdictPayload,
+): void;
+
+export const DEFAULT_HARD_CEILING: number;
+export const DEFAULT_EVENTS_PATH: string;