@zxyycom/vibe-check 0.0.1 → 0.0.2

package/types/project-run/task-scheduler/execution-state.d.ts

@@ -1,9 +1,17 @@
+import type { SchedulerMeasurementContext, SchedulerMeasurementHook } from "../../project-definition/project-definition.ts";
 import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope, TaskGraph } from "./graph.ts";
+import { type AdmissionSelectionPolicy } from "./admission-selection-policy.ts";
 import type { DiagnosticLogger } from "../diagnostic-logging/logger.ts";
 import type { SchedulerSnapshot } from "./scheduler-decision.ts";
+import type { AdmissionPolicyFaultCategory } from "./scheduler-admission-decision.ts";
+import type { SchedulerPerformanceDiagnosticsInput } from "./measurement/diagnostics.ts";
+import { type AdmissionCoreEffect, type AdmissionCoreState } from "./admission-core/core.ts";
 export type TaskSettlement<TResult> = Readonly<{
     readonly kind: "completed";
     readonly value: TResult;
+} | {
+    readonly kind: "prerequisite-unsatisfied";
+    readonly value: TResult;
 } | {
     readonly kind: "failed";
     readonly error: unknown;
@@ -20,17 +28,45 @@ export interface SettledTask<TResult> {
 export interface TaskExecutionContext {
     readonly signal: AbortSignal | undefined;
 }
+export interface PreAdmissionTaskResult<TResult> {
+    readonly taskId: string;
+    readonly value: TResult;
+}
+/** Product-private effect hook used to prove that the real shell replays the shared core. */
+export interface SchedulerAdmissionCoreEffect {
+    readonly effect: AdmissionCoreEffect;
+    readonly state: AdmissionCoreState;
+}
 export interface TaskGraphRun<TResult> {
+    readonly admissionPolicyFault: AdmissionPolicyFaultCategory | undefined;
     readonly cancelled: boolean;
     /** One entry per static graph Task, in static graph order. */
     readonly settlements: readonly SettledTask<TResult>[];
+    /** Product-private terminal facts retained after terminal Hooks have been drained. */
+    readonly terminalMeasurement?: SchedulerMeasurementContext;
 }
 export interface RunTaskGraphOptions<TResult> {
+    /** Product-private policy handoff; package consumers cannot author this through the public API. */
+    readonly admissionPolicy?: AdmissionSelectionPolicy;
     readonly diagnosticLogger?: DiagnosticLogger;
+    /** Explicit enabled-only handoff; no Scheduler behavior is inferred from a logger shape. */
+    readonly performanceDiagnostics?: SchedulerPerformanceDiagnosticsInput;
+    /** Runtime-only terminal consumers; their context is formed after Scheduler drain. */
+    readonly measurementHooks?: readonly SchedulerMeasurementHook[];
+    readonly onMeasurementHookFailure?: () => void;
+    readonly onMeasurementHooksSettled?: () => void;
+    /** Product-private test observer; no package consumer can supply this through `run`. */
+    readonly onAdmissionCoreEffect?: (effect: SchedulerAdmissionCoreEffect) => void;
     readonly graph: TaskGraph;
+    /** Product-private Task results formed without Scheduler admission in the current Run. */
+    readonly preAdmissionTaskResults?: readonly PreAdmissionTaskResult<TResult>[];
     readonly maxParallel: number;
     readonly signal?: AbortSignal;
     readonly execute: (task: PlannedTask, context: TaskExecutionContext) => TResult | Promise<TResult>;
+    /** Maps a completed Task's opaque product value to prerequisite satisfaction. */
+    readonly isPrerequisiteSatisfied?: (value: TResult) => boolean;
+    /** Lets a product close a blocked Task before any terminal observer can be admitted. */
+    readonly onTaskBlocked?: (task: PlannedTask, dependencyIds: readonly string[]) => void;
 }
 export type RunningTaskCompletion<TResult> = Readonly<{
     readonly taskId: string;
@@ -46,18 +82,24 @@ export interface RuntimeScope {
     isActive: boolean;
 }
 export interface SchedulerState<TResult> {
+    /** The shared immutable legality/transition state; Task and Promise ownership remains below. */
+    admissionCore: AdmissionCoreState;
+    readonly admissionPolicy: AdmissionSelectionPolicy;
     readonly diagnosticLogger: DiagnosticLogger | undefined;
     readonly graph: PlannedTaskGraph;
+    readonly isPrerequisiteSatisfied: RunTaskGraphOptions<TResult>["isPrerequisiteSatisfied"];
     readonly maxParallel: number;
     readonly signal: AbortSignal | undefined;
     readonly execute: RunTaskGraphOptions<TResult>["execute"];
+    readonly onTaskBlocked: RunTaskGraphOptions<TResult>["onTaskBlocked"];
+    readonly onAdmissionCoreEffect: RunTaskGraphOptions<TResult>["onAdmissionCoreEffect"];
     readonly pending: PlannedTask[];
     readonly runningById: Map<string, RunningTask<TResult>>;
     readonly runningMutexes: Set<string>;
     readonly settlementsByTaskId: Map<string, TaskSettlement<TResult>>;
     readonly scopesById: ReadonlyMap<string, RuntimeScope>;
-    reservationTaskId: string | undefined;
     isCancelled: boolean;
+    admissionPolicyFault: AdmissionPolicyFaultCategory | undefined;
 }
 export declare function createSchedulerState<TResult>(graph: PlannedTaskGraph, options: RunTaskGraphOptions<TResult>): SchedulerState<TResult>;
 /** Projects mutable execution state into the pure scheduler-decision input. */

package/types/project-run/task-scheduler/forced-block-effect-replay.d.ts

@@ -0,0 +1,9 @@
+import { type AdmissionCoreEffect, type AdmissionCoreState } from "./admission-core/core.ts";
+import type { SchedulerTrigger } from "./scheduler-decision.ts";
+import type { SchedulerState } from "./execution-state.ts";
+import type { SchedulerPerformanceDiagnostics } from "./measurement/diagnostics.ts";
+/**
+ * Adapts only canonical forced blocked effects to the real Scheduler shell.
+ * Direct admission, running settlement, and cancellation remain in the root shell.
+ */
+export declare function replayCoreForcedBlocks<TResult>(state: SchedulerState<TResult>, effects: readonly AdmissionCoreEffect[], effectStates: readonly AdmissionCoreState[], diagnostics: SchedulerPerformanceDiagnostics | undefined, trigger: SchedulerTrigger): void;

package/types/project-run/task-scheduler/graph-validation.d.ts

@@ -1,11 +1,12 @@
-import type { PlannedTask, PlannedTaskScope } from "./graph.ts";
+import type { NamedResourceUnits, PlannedTask, PlannedTaskScope } from "./graph.ts";
 interface PreparedTaskGraphValidationInput {
+    readonly resourceCapacities: readonly NamedResourceUnits[];
     readonly rootMaxParallel: number | undefined;
     readonly scopeById: ReadonlyMap<string, PlannedTaskScope>;
     readonly scopes: readonly PlannedTaskScope[];
     readonly taskById: ReadonlyMap<string, PlannedTask>;
     readonly tasks: readonly PlannedTask[];
 }
-/** Validates dependency and scope relations after graph-shaped input is normalized. */
+/** Validates direct relations and scope structure after graph-shaped input is normalized. */
 export declare function validatePreparedTaskGraph(input: PreparedTaskGraphValidationInput): void;
 export {};

package/types/project-run/task-scheduler/graph.d.ts

@@ -1,7 +1,15 @@
+import type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
+export interface NamedResourceUnits {
+    readonly resourceId: string;
+    readonly units: number;
+}
 export interface TaskNode {
+    readonly admissionPriority?: number;
     readonly id: string;
     readonly dependsOn?: readonly string[];
     readonly mutex?: readonly string[];
+    readonly observes?: readonly string[];
+    readonly resourceClaims?: Readonly<Record<string, number>>;
     readonly scopeId?: string;
 }
 /**
@@ -16,13 +24,17 @@ export interface TaskScope {
     readonly terminalTaskId: string;
 }
 export interface TaskGraph {
+    readonly resourceCapacities?: Readonly<Record<string, number>>;
     readonly tasks: readonly TaskNode[];
     readonly scopes?: readonly TaskScope[];
 }
 export interface PlannedTask {
+    readonly admissionPriority: number;
     readonly id: string;
     readonly dependsOn: readonly string[];
     readonly mutex: readonly string[];
+    readonly observes: readonly string[];
+    readonly resourceClaims: readonly NamedResourceUnits[];
     readonly scopeId: string | undefined;
 }
 export interface PlannedTaskScope {
@@ -32,6 +44,9 @@ export interface PlannedTaskScope {
     readonly terminalTaskId: string;
 }
 export interface PlannedTaskGraph {
+    readonly resourceCapacities: readonly NamedResourceUnits[];
+    /** Immutable public projection shared by every decision and terminal measurement in one run. */
+    readonly schedulerGraphSnapshot: SchedulerGraphSnapshot;
     readonly tasks: readonly PlannedTask[];
     readonly scopes: readonly PlannedTaskScope[];
 }

package/types/project-run/task-scheduler/measurement/diagnostics.d.ts

@@ -0,0 +1,47 @@
+import type { AdmissionPolicyMeasurement, SchedulerMeasurementEffect, SchedulerMeasurementHook, SchedulerRawMeasurement } from "../../../project-definition/project-definition.ts";
+import { type DiagnosticLogger } from "../../diagnostic-logging/logger.ts";
+/** Explicit, enabled-only private handoff; the Scheduler never infers this from logger behavior. */
+export type SchedulerPerformanceDiagnosticsInput = Readonly<{
+    readonly clock: Readonly<{
+        now(): number;
+    }>;
+    readonly declarativeFingerprint: string;
+    readonly logger?: DiagnosticLogger;
+}>;
+export type AdmissionViablePendingTask = Readonly<{
+    readonly kind: "admissible-pending" | "capacity-blocked" | "mutex-blocked";
+    readonly taskId: string;
+}>;
+export type SchedulerPerformanceState = Readonly<{
+    readonly admissionViablePendingTasks: readonly AdmissionViablePendingTask[];
+    readonly effectiveMaxParallel: number;
+    readonly rootMaxParallel: number;
+    readonly running: number;
+}>;
+/**
+ * Scheduler-owned, invocation-local lifecycle projection. Clock boundaries and
+ * numeric interval accumulation remain private collaborators of this owner.
+ */
+export declare class SchedulerPerformanceDiagnostics {
+    #private;
+    constructor(input: SchedulerPerformanceDiagnosticsInput, initial: SchedulerPerformanceState);
+    measureControlPath<T>(operation: () => T): T;
+    observeDecision(observation: () => void): void;
+    /** Flushes the old state before admission changes the real Scheduler state. */
+    beforeAdmission(taskId: string, runningTaskIds: readonly string[]): void;
+    /** Flushes the old state before blocked/cancelled changes the real Scheduler state. */
+    beforePendingSettlement(taskIds?: readonly string[]): void;
+    /** Flushes the old running interval before removing the actual running Task. */
+    beforeRunningSettlement(taskId: string): void;
+    beforeAcceptedWait(): void;
+    captureState(state: SchedulerPerformanceState): void;
+    rawMeasurement(): SchedulerRawMeasurement;
+    beginSelectedPolicyAction(taskId: string): void;
+    beginWaitPolicyAction(): void;
+    recordEffect(effect: SchedulerMeasurementEffect): void;
+    policyMeasurement(): AdmissionPolicyMeasurement;
+    completePendingActionObservation(): void;
+    admittedTaskIds(): readonly string[];
+    /** Internal default terminal hook; it contains writer failure without runner special-casing. */
+    defaultSummaryHook(): SchedulerMeasurementHook | undefined;
+}

package/types/project-run/task-scheduler/measurement/integrals.d.ts

@@ -0,0 +1,27 @@
+import type { SchedulerMeasurementIntervalContribution } from "../../../project-definition/project-definition.ts";
+import type { AdmissionViablePendingTask, SchedulerPerformanceState } from "./diagnostics.ts";
+export type AdmissionDelayBreakdown = Readonly<{
+    readonly admissiblePendingMs: number;
+    readonly capacityBlockedMs: number;
+    readonly mutexBlockedMs: number;
+}>;
+export type SchedulerPerformancePeaks = Readonly<{
+    readonly admissionViablePendingTaskCount: number;
+    readonly admissiblePendingTaskCount: number;
+    readonly capacityBlockedTaskCount: number;
+    readonly mutexBlockedTaskCount: number;
+}>;
+/** Accumulates interval-weighted capacity and admission-delay measurements. */
+export declare class SchedulerPerformanceIntegrals {
+    #private;
+    installPendingProjection(pendingTasks: readonly AdmissionViablePendingTask[], timingAvailable: boolean): void;
+    /** Returns false when an interval cannot be represented as finite non-negative totals. */
+    addInterval(elapsedMs: number, state: SchedulerPerformanceState): boolean;
+    takeAdmissionDelay(taskId: string): AdmissionDelayBreakdown | undefined;
+    pendingAdmissionDelays(): readonly Readonly<{
+        readonly admissionDelay: AdmissionDelayBreakdown;
+        readonly taskId: string;
+    }>[];
+    peaks(): SchedulerPerformancePeaks;
+    totals(): SchedulerMeasurementIntervalContribution;
+}

package/types/project-run/task-scheduler/measurement/policy.d.ts

@@ -0,0 +1,10 @@
+import type { AdmissionPolicyMeasurement, SchedulerDecisionMeasurementCumulative, SchedulerMeasurementEffect, SchedulerMeasurementIntervalContribution, SchedulerMeasurementTiming } from "../../../project-definition/project-definition.ts";
+/** Owns the immutable prefix of observations formed after accepted custom-policy actions. */
+export declare class SchedulerPolicyMeasurement {
+    #private;
+    beginSelected(taskId: string, baseline: SchedulerMeasurementIntervalContribution): void;
+    beginWait(baseline: SchedulerMeasurementIntervalContribution): void;
+    recordEffect(effect: SchedulerMeasurementEffect): void;
+    complete(totals: SchedulerMeasurementIntervalContribution, timing: SchedulerMeasurementTiming): void;
+    snapshot(cumulative: SchedulerDecisionMeasurementCumulative): AdmissionPolicyMeasurement;
+}

package/types/project-run/task-scheduler/measurement/summary.d.ts

@@ -0,0 +1,3 @@
+import type { SchedulerRawMeasurement } from "../../../project-definition/project-definition.ts";
+/** Projects raw Scheduler measurement into the bounded diagnostic summary. */
+export declare function summaryFromSchedulerMeasurement(raw: SchedulerRawMeasurement): Readonly<Record<string, unknown>>;

package/types/project-run/task-scheduler/measurement/timing.d.ts

@@ -0,0 +1,33 @@
+import type { SchedulerMeasurementIntervalContribution, SchedulerMeasurementTiming, SchedulerMeasurementTimingUnavailableReason } from "../../../project-definition/project-definition.ts";
+import type { SchedulerPerformanceState } from "./diagnostics.ts";
+import { SchedulerPerformanceIntegrals, type AdmissionDelayBreakdown, type SchedulerPerformancePeaks } from "./integrals.ts";
+export type SchedulerPerformanceTimingSnapshot = Readonly<{
+    readonly acceptedWaitCount: number;
+    readonly acceptedWaitMs: number;
+    readonly decisionObservationMs: number;
+    readonly maxRunning: number;
+    readonly peaks: SchedulerPerformancePeaks;
+    readonly schedulerControlPathMs: number;
+    readonly startedAtMonotonicMs: number | undefined;
+    readonly timing: SchedulerMeasurementTiming;
+    readonly totals: SchedulerMeasurementIntervalContribution;
+}>;
+/** Owns monotonic clock boundaries and delegates numeric interval accumulation. */
+export declare class SchedulerPerformanceTiming {
+    #private;
+    constructor(clock: Readonly<{
+        now(): number;
+    }>, initial: SchedulerPerformanceState);
+    /** Accounts a synchronous shell operation, never an await or author callback. */
+    measureControlPath<T>(operation: () => T): T;
+    /** Keeps decision writer work separate from the shell control-path projection. */
+    observeDecision(observation: () => void): void;
+    boundary(): number | undefined;
+    beginAcceptedWait(): void;
+    closeAcceptedWait(boundary: number): void;
+    captureState(state: SchedulerPerformanceState): void;
+    takeAdmissionDelay(taskId: string): AdmissionDelayBreakdown | undefined;
+    pendingAdmissionDelays(): ReturnType<SchedulerPerformanceIntegrals["pendingAdmissionDelays"]>;
+    snapshot(): SchedulerPerformanceTimingSnapshot;
+    invalidate(reason: SchedulerMeasurementTimingUnavailableReason): void;
+}

package/types/project-run/task-scheduler/scheduler-admission-decision.d.ts

@@ -1,8 +1,20 @@
-import { type SchedulerInspection } from "./scheduler-decision-inspection.ts";
+import type { AdmissionPolicyContext } from "../../project-definition/project-definition.ts";
+import type { AdmissionSelectionPolicy } from "./admission-selection-policy.ts";
 import { type SchedulerDecision, type SchedulerDecisionContext, type SchedulerTrigger } from "./scheduler-decision-model.ts";
+import type { SchedulerInspection } from "./scheduler-decision-inspection.ts";
+import { type AdmissionCoreState } from "./admission-core/core.ts";
 export interface SchedulerDecisionCycle {
+    readonly admissionCore: AdmissionCoreState;
     readonly context: SchedulerDecisionContext;
+    readonly policy: AdmissionSelectionPolicy;
+    /** Invoked immediately before the private policy seam enters a custom callback. */
+    readonly measurement?: () => AdmissionPolicyContext["measurement"];
     readonly state: SchedulerInspection;
     readonly trigger: SchedulerTrigger;
 }
 export declare function decideAdmission(cycle: SchedulerDecisionCycle): SchedulerDecision;
+export type AdmissionPolicyFaultCategory = "callback-threw" | "thenable-proposal" | "malformed-proposal" | "non-candidate-select" | "capacity-invalid-select" | "lifecycle-invalid-select" | "undrainable-wait";
+export declare class AdmissionPolicyFault extends Error {
+    readonly category: AdmissionPolicyFaultCategory;
+    constructor(category: AdmissionPolicyFaultCategory);
+}

package/types/project-run/task-scheduler/scheduler-decision-inspection.d.ts

@@ -1,24 +1,25 @@
-import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope } from "./graph.ts";
-import type { SchedulerAwaitReason, SchedulerDecisionContext, SchedulerSettlementKind, SchedulerSnapshot } from "./scheduler-decision-model.ts";
+import type { PlannedTask, PlannedTaskGraph } from "./graph.ts";
+import type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
+import type { SchedulerCapacity, SchedulerDecisionContext, SchedulerSettlementKind } from "./scheduler-decision-model.ts";
 export interface SchedulerInspection {
-    readonly activeScopeIds: ReadonlySet<string>;
+    readonly activeScopeIds: readonly string[];
     readonly graph: PlannedTaskGraph;
+    readonly isAbortRequested: boolean;
+    readonly isCancelled: boolean;
     readonly maxParallel: number;
     readonly pendingTasks: readonly PlannedTask[];
-    readonly reservationTaskId: string | undefined;
-    readonly runningMutexes: ReadonlySet<string>;
-    readonly runningTaskIds: ReadonlySet<string>;
-    readonly settlementKindByTaskId: ReadonlyMap<string, SchedulerSettlementKind>;
+    readonly runningMutexes: readonly string[];
+    readonly resources: readonly Readonly<{
+        readonly available: number;
+        readonly capacity: number;
+        readonly inUse: number;
+        readonly resourceId: string;
+    }>[];
+    readonly runningTaskIds: readonly string[];
+    readonly settledTasks: readonly Readonly<{
+        readonly kind: SchedulerSettlementKind;
+        readonly taskId: string;
+    }>[];
 }
-export declare function inspectSnapshot(snapshot: SchedulerSnapshot): SchedulerInspection;
-export declare function decisionContext(state: SchedulerInspection): SchedulerDecisionContext;
-export declare function selectBlockedTask(state: SchedulerInspection): Readonly<{
-    readonly dependencyIds: readonly string[];
-    readonly task: PlannedTask;
-}> | undefined;
-export declare function isDependencyMutexEligible(task: PlannedTask, state: SchedulerInspection): boolean;
-export declare function capacityWaitReason(state: SchedulerInspection): SchedulerAwaitReason;
-export declare function canAdmit(state: SchedulerInspection, task: PlannedTask): boolean;
-export declare function activationScopeFor(state: SchedulerInspection, task: PlannedTask): PlannedTaskScope | undefined;
-export declare function selectTighteningTask(state: SchedulerInspection, eligibleTasks: readonly PlannedTask[], effectiveMaxParallel: number): PlannedTask | undefined;
-export declare function selectConstrainedContinuation(state: SchedulerInspection, eligibleTasks: readonly PlannedTask[], effectiveMaxParallel: number): PlannedTask | undefined;
+export declare function decisionContext(state: SchedulerInspection, graphIdentity: SchedulerGraphSnapshot): SchedulerDecisionContext;
+export declare function capacityFor(state: SchedulerInspection): SchedulerCapacity;

package/types/project-run/task-scheduler/scheduler-decision-model.d.ts

@@ -1,5 +1,6 @@
 import type { PlannedTaskGraph } from "./graph.ts";
-export type SchedulerSettlementKind = "completed" | "failed" | "blocked" | "cancelled-before-start";
+import type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
+export type SchedulerSettlementKind = "completed" | "prerequisite-unsatisfied" | "failed" | "blocked" | "cancelled-before-start";
 export type SchedulerTrigger = Readonly<{
     readonly kind: "execution-started";
 }> | Readonly<{
@@ -21,7 +22,6 @@ export interface SchedulerSnapshot {
     readonly isAbortRequested: boolean;
     readonly isCancelled: boolean;
     readonly pendingTaskIds: readonly string[];
-    readonly reservationTaskId: string | undefined;
     readonly runningMutexes: readonly string[];
     readonly runningTaskIds: readonly string[];
     readonly settledTasks: readonly Readonly<{
@@ -39,32 +39,48 @@ export interface SchedulerCapacity {
 export interface SchedulerBlockerSummary {
     readonly dependency: number;
     readonly mutex: number;
+    readonly resourceCapacity: number;
     readonly rootCapacity: boolean;
     readonly scopeCapacity: boolean;
 }
-export interface SchedulerReservationContext {
-    readonly taskId: string | null;
-}
-export interface SchedulerDecisionContext {
-    readonly blockers: SchedulerBlockerSummary;
-    readonly capacity: SchedulerCapacity;
-    readonly reservation: SchedulerReservationContext;
+/** The sole public Scheduler graph DTO; task identity is always `taskId`. */
+export type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
+export interface SchedulerAdmissionCandidateFact {
+    readonly canAdmit: boolean;
+    readonly taskId: string;
 }
-export type ReservationUpdate = Readonly<{
-    readonly kind: "unchanged";
+export type SchedulerAdmissionProposal = Readonly<{
+    readonly kind: "select";
+    readonly taskId: string;
 }> | Readonly<{
-    readonly kind: "set";
+    readonly kind: "wait";
+}>;
+export type SchedulerAdmissionHardGuard = Readonly<{
+    readonly canAdmit: true;
+    readonly isCandidate: true;
+    readonly kind: "select";
+    readonly lifecycleOpen: true;
     readonly taskId: string;
 }> | Readonly<{
-    readonly kind: "clear";
+    readonly kind: "wait";
+    readonly runningCanDrain: true;
 }>;
-export type SchedulerAdmissionReason = "reservation" | "tightening-scope" | "constrained-continuation" | "canonical-order";
-export type SchedulerAwaitReason = "cancellation-drain" | "dependency-or-mutex" | "running-drain" | "root-capacity" | "active-scope-capacity" | "reserved-tightening-scope";
+export interface SchedulerDecisionContext {
+    readonly blockers: SchedulerBlockerSummary;
+    readonly capacity: SchedulerCapacity;
+    readonly graphIdentity: SchedulerGraphSnapshot;
+}
 export type SchedulerDecision = SchedulerDecisionContext & (Readonly<{
+    readonly admissionPriority: number;
+    readonly candidates: readonly SchedulerAdmissionCandidateFact[];
     readonly eligibleCount: number;
+    readonly hardGuard: Extract<SchedulerAdmissionHardGuard, {
+        readonly kind: "select";
+    }>;
     readonly kind: "admit";
-    readonly reason: SchedulerAdmissionReason;
-    readonly reservationUpdate: ReservationUpdate;
+    readonly proposal: Extract<SchedulerAdmissionProposal, {
+        readonly kind: "select";
+    }>;
     readonly scopeToActivate: string | null;
     readonly taskId: string;
     readonly trigger: SchedulerTrigger;
@@ -74,10 +90,13 @@ export type SchedulerDecision = SchedulerDecisionContext & (Readonly<{
     readonly taskId: string;
     readonly trigger: SchedulerTrigger;
 }> | Readonly<{
+    readonly candidates: readonly SchedulerAdmissionCandidateFact[];
     readonly eligibleCount: number;
+    readonly hardGuard: Extract<SchedulerAdmissionHardGuard, {
+        readonly kind: "wait";
+    }>;
     readonly kind: "await-running";
-    readonly reason: SchedulerAwaitReason;
-    readonly reservationUpdate: ReservationUpdate;
+    readonly proposal: SchedulerAdmissionProposal | null;
     readonly trigger: SchedulerTrigger;
 }> | Readonly<{
     readonly kind: "cancel-pending";
@@ -88,7 +107,4 @@ export type SchedulerDecision = SchedulerDecisionContext & (Readonly<{
     readonly kind: "complete";
     readonly trigger: SchedulerTrigger;
 }>);
-export declare function reservationUnchanged(): ReservationUpdate;
-export declare function reservationSet(taskId: string): ReservationUpdate;
-export declare function reservationClear(): ReservationUpdate;
 export declare function freezeDecision(decision: SchedulerDecision): SchedulerDecision;

package/types/project-run/task-scheduler/scheduler-decision.d.ts

@@ -1,8 +1,11 @@
+import type { AdmissionSelectionPolicy } from "./admission-selection-policy.ts";
+import type { AdmissionPolicyContext } from "../../project-definition/project-definition.ts";
 import type { SchedulerDecision, SchedulerSnapshot, SchedulerTrigger } from "./scheduler-decision-model.ts";
+import { type AdmissionCoreState } from "./admission-core/core.ts";
 export type { SchedulerDecision, SchedulerSettlementKind, SchedulerSnapshot, SchedulerTrigger } from "./scheduler-decision-model.ts";
 /**
  * Computes the next generic task-engine action from an immutable state projection.
  * Starting work, awaiting promises, cancellation, and diagnostic output remain in
  * the imperative scheduler shell.
  */
-export declare function decideScheduler(snapshot: SchedulerSnapshot, trigger: SchedulerTrigger): SchedulerDecision;
+export declare function decideScheduler(snapshot: SchedulerSnapshot, trigger: SchedulerTrigger, policy?: AdmissionSelectionPolicy, measurement?: () => AdmissionPolicyContext["measurement"], admissionCore?: AdmissionCoreState): SchedulerDecision;

package/types/project-run/task-scheduler/scheduler-observation.d.ts

@@ -0,0 +1,14 @@
+import { type DiagnosticObservation } from "../diagnostic-logging/logger.ts";
+import type { SchedulerDecision } from "./scheduler-decision.ts";
+import type { SchedulerState } from "./execution-state.ts";
+import type { SchedulerPerformanceDiagnostics, SchedulerPerformanceState } from "./measurement/diagnostics.ts";
+import type { AdmissionPolicyFault } from "./scheduler-admission-decision.ts";
+/** Fault logging is observational and therefore excluded from Scheduler control-path timing. */
+export declare function observeAdmissionPolicyFault<TResult>(state: SchedulerState<TResult>, fault: AdmissionPolicyFault): void;
+export declare function observeSchedulerDecision<TResult>(state: SchedulerState<TResult>, decision: SchedulerDecision, diagnostics: SchedulerPerformanceDiagnostics | undefined): void;
+/** One immutable graph record makes the enclosing scheduler channel the self-contained evidence unit. */
+export declare function observeSchedulerGraph<TResult>(state: SchedulerState<TResult>): void;
+export declare function schedulerGraphFingerprint(graph: unknown): string;
+/** Logger failures are observational and must not revise Scheduler lifecycle state. */
+export declare function observeSchedulerDiagnostic<TResult>(state: SchedulerState<TResult>, observation: DiagnosticObservation): void;
+export declare function performanceState<TResult>(state: SchedulerState<TResult>): SchedulerPerformanceState;

package/types/project-run/task-scheduler/scheduler-task-lifecycle.d.ts

@@ -0,0 +1,18 @@
+import { type RunningTaskCompletion, type SchedulerState, type TaskGraphRun } from "./execution-state.ts";
+import type { SchedulerDecision } from "./scheduler-decision.ts";
+import type { AdmissionPolicyFault } from "./scheduler-admission-decision.ts";
+export declare function applyAdmissionPolicyFault<TResult>(state: SchedulerState<TResult>, fault: AdmissionPolicyFault): void;
+export declare function applyAdmission<TResult>(state: SchedulerState<TResult>, decision: Extract<SchedulerDecision, {
+    readonly kind: "admit";
+}>): void;
+export declare function applyBlockedSettlement<TResult>(state: SchedulerState<TResult>, decision: Extract<SchedulerDecision, {
+    readonly kind: "settle-blocked";
+}>): void;
+/** Applies one canonical private forced-block effect after the shared reducer selected it. */
+export declare function applyForcedBlockedSettlement<TResult>(state: SchedulerState<TResult>, taskId: string, dependencyIds: readonly string[]): void;
+export declare function applyCancellation<TResult>(state: SchedulerState<TResult>, decision: Extract<SchedulerDecision, {
+    readonly kind: "cancel-pending";
+}>): void;
+export declare function nextRunningSettlement<TResult>(state: SchedulerState<TResult>): Promise<RunningTaskCompletion<TResult>>;
+export declare function settleRunningTask<TResult>(state: SchedulerState<TResult>, result: RunningTaskCompletion<TResult>): void;
+export declare function buildTaskGraphRun<TResult>(state: SchedulerState<TResult>): TaskGraphRun<TResult>;

package/types/project-run/task-scheduler/scheduler-terminal-measurement.d.ts

@@ -0,0 +1,9 @@
+import type { SchedulerMeasurementContext } from "../../project-definition/project-definition.ts";
+import type { RunTaskGraphOptions, SchedulerState } from "./execution-state.ts";
+import type { SchedulerPerformanceDiagnostics } from "./measurement/diagnostics.ts";
+/** Delivers the terminal measurement to the internal summary and caller hooks exactly once. */
+export declare function observeTerminalMeasurement<TResult>(input: Readonly<{
+    readonly diagnostics: SchedulerPerformanceDiagnostics;
+    readonly options: RunTaskGraphOptions<TResult>;
+    readonly state: SchedulerState<TResult>;
+}>): Promise<SchedulerMeasurementContext>;

package/dist/esm/package-checks/file-metrics/scc/csv.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"csv.mjs","sourceRoot":"","sources":["../../../../../src/package-checks/file-metrics/scc/csv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,OAAO,GAAY,KAAK,CAAC,GAAG,EAAE;QAClC,GAAG,EAAE,IAAI;QACT,kBAAkB,EAAE,IAAI;QACxB,gBAAgB,EAAE,IAAI;QACtB,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IAEH,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;AACjF,CAAC","sourcesContent":["import { parse } from \"csv-parse/sync\";\n\nexport function parseCsvRows(csv: string): string[][] {\n  const records: unknown = parse(csv, {\n    bom: true,\n    relax_column_count: true,\n    skip_empty_lines: true,\n    trim: true\n  });\n\n  if (!Array.isArray(records) || !records.every(isStringRow)) {\n    throw new Error(\"CSV parser returned non-string rows\");\n  }\n\n  return records;\n}\n\nfunction isStringRow(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === \"string\");\n}\n"]}

package/dist/esm/package-checks/function-metrics/lizard/availability.mjs

@@ -1,64 +0,0 @@
-import { errorMessage } from "../../host-environment/error-message.mjs";
-import { runProcess } from "../../host-environment/process/command.mjs";
-export async function checkLizard(rootDir, dependency) {
-    try {
-        const result = await runProcess({
-            args: ["--version"],
-            command: dependency.executable,
-            cwd: rootDir
-        });
-        return availabilityFromVersionResult(result);
-    }
-    catch (error) {
-        return unavailableLizard({
-            error: `lizard version error: ${errorMessage(error)}`,
-            reason: "execution-error"
-        });
-    }
-}
-function availabilityFromVersionResult(result) {
-    if (result.signal !== null) {
-        const output = commandOutput(result);
-        return unavailableLizard({
-            error: `lizard --version failed, signal ${result.signal}${output ? `: ${output}` : ""}`,
-            reason: "execution-error"
-        });
-    }
-    if (result.error)
-        return processErrorAvailability(result.error);
-    const output = commandOutput(result);
-    if (result.status !== 0) {
-        return unavailableLizard({
-            error: `lizard --version failed, ${processTermination(result)}${output ? `: ${output}` : ""}`,
-            reason: "execution-error"
-        });
-    }
-    if (output === "") {
-        return unavailableLizard({
-            error: "lizard --version returned empty output",
-            reason: "contract-error"
-        });
-    }
-    return Object.freeze({ available: true, version: output });
-}
-function processErrorAvailability(error) {
-    const isMissingTool = Object.hasOwn(error, "code") && Reflect.get(error, "code") === "ENOENT";
-    return unavailableLizard({
-        error: isMissingTool
-            ? `lizard command unavailable: ${error.message}`
-            : `lizard version error: ${error.message}`,
-        reason: isMissingTool ? "tool-unavailable" : "execution-error"
-    });
-}
-function unavailableLizard({ error, reason }) {
-    return Object.freeze({ available: false, error, reason });
-}
-function commandOutput(result) {
-    return (result.stdout || "").trim() || (result.stderr || "").trim();
-}
-function processTermination(result) {
-    return typeof result.status === "number"
-        ? `exit ${result.status}`
-        : `signal ${result.signal || "unknown"}`;
-}
-//# sourceMappingURL=availability.mjs.map

package/dist/esm/package-checks/function-metrics/lizard/availability.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"availability.mjs","sourceRoot":"","sources":["../../../../../src/package-checks/function-metrics/lizard/availability.ts"],"names":[],"mappings":"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","sourcesContent":["import { errorMessage } from \"../../host-environment/error-message.ts\";\nimport { runProcess } from \"../../host-environment/process/command.ts\";\nimport type { ResolvedFunctionMetricsScannerOptions } from \"../options.ts\";\n\ntype LizardAvailability = Readonly<\n  | {\n      readonly available: true;\n      readonly version: string;\n    }\n  | {\n      readonly available: false;\n      readonly error: string;\n      readonly reason: \"contract-error\" | \"execution-error\" | \"tool-unavailable\";\n    }\n>;\n\ninterface UnavailableLizardInput {\n  readonly error: string;\n  readonly reason: Extract<LizardAvailability, { available: false }>[\"reason\"];\n}\n\ntype ToolCommandResult = Awaited<ReturnType<typeof runProcess>>;\n\nexport async function checkLizard(\n  rootDir: string,\n  dependency: ResolvedFunctionMetricsScannerOptions\n): Promise<LizardAvailability> {\n  try {\n    const result = await runProcess({\n      args: [\"--version\"],\n      command: dependency.executable,\n      cwd: rootDir\n    });\n    return availabilityFromVersionResult(result);\n  } catch (error: unknown) {\n    return unavailableLizard({\n      error: `lizard version error: ${errorMessage(error)}`,\n      reason: \"execution-error\"\n    });\n  }\n}\n\nfunction availabilityFromVersionResult(result: ToolCommandResult): LizardAvailability {\n  if (result.signal !== null) {\n    const output = commandOutput(result);\n    return unavailableLizard({\n      error: `lizard --version failed, signal ${result.signal}${output ? `: ${output}` : \"\"}`,\n      reason: \"execution-error\"\n    });\n  }\n  if (result.error) return processErrorAvailability(result.error);\n  const output = commandOutput(result);\n  if (result.status !== 0) {\n    return unavailableLizard({\n      error: `lizard --version failed, ${processTermination(result)}${output ? `: ${output}` : \"\"}`,\n      reason: \"execution-error\"\n    });\n  }\n  if (output === \"\") {\n    return unavailableLizard({\n      error: \"lizard --version returned empty output\",\n      reason: \"contract-error\"\n    });\n  }\n  return Object.freeze({ available: true, version: output });\n}\n\nfunction processErrorAvailability(error: Error): LizardAvailability {\n  const isMissingTool = Object.hasOwn(error, \"code\") && Reflect.get(error, \"code\") === \"ENOENT\";\n  return unavailableLizard({\n    error: isMissingTool\n      ? `lizard command unavailable: ${error.message}`\n      : `lizard version error: ${error.message}`,\n    reason: isMissingTool ? \"tool-unavailable\" : \"execution-error\"\n  });\n}\n\nfunction unavailableLizard({ error, reason }: UnavailableLizardInput): LizardAvailability {\n  return Object.freeze({ available: false, error, reason });\n}\n\nfunction commandOutput(result: ToolCommandResult): string {\n  return (result.stdout || \"\").trim() || (result.stderr || \"\").trim();\n}\n\nfunction processTermination(result: ToolCommandResult): string {\n  return typeof result.status === \"number\"\n    ? `exit ${result.status}`\n    : `signal ${result.signal || \"unknown\"}`;\n}\n"]}

package/dist/esm/package-checks/function-metrics/lizard/csv.mjs

@@ -1,17 +0,0 @@
-import { parse } from "csv-parse/sync";
-export function parseCsvRows(csv) {
-    const records = parse(csv, {
-        bom: true,
-        relax_column_count: true,
-        skip_empty_lines: true,
-        trim: true
-    });
-    if (!Array.isArray(records) || !records.every(isStringRow)) {
-        throw new Error("CSV parser returned non-string rows");
-    }
-    return records;
-}
-function isStringRow(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-//# sourceMappingURL=csv.mjs.map

package/dist/esm/package-checks/function-metrics/lizard/csv.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"csv.mjs","sourceRoot":"","sources":["../../../../../src/package-checks/function-metrics/lizard/csv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,OAAO,GAAY,KAAK,CAAC,GAAG,EAAE;QAClC,GAAG,EAAE,IAAI;QACT,kBAAkB,EAAE,IAAI;QACxB,gBAAgB,EAAE,IAAI;QACtB,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IAEH,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;AACjF,CAAC","sourcesContent":["import { parse } from \"csv-parse/sync\";\n\nexport function parseCsvRows(csv: string): string[][] {\n  const records: unknown = parse(csv, {\n    bom: true,\n    relax_column_count: true,\n    skip_empty_lines: true,\n    trim: true\n  });\n\n  if (!Array.isArray(records) || !records.every(isStringRow)) {\n    throw new Error(\"CSV parser returned non-string rows\");\n  }\n\n  return records;\n}\n\nfunction isStringRow(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === \"string\");\n}\n"]}