@zxyycom/vibe-check 0.0.1 → 0.0.2

package/types/check/finding-presentation.d.ts

@@ -0,0 +1,25 @@
+import type { CheckMessage, CheckResult } from "./check.ts";
+/**
+ * 将 Check-owned Finding 投影为有界 terminal messages 所需的超限上下文。
+ * 完整 Finding facts 与深入查看位置继续由调用方拥有。
+ */
+export interface FindingOverflowContext<Finding> {
+    readonly omittedFindings: readonly Finding[];
+    readonly omittedCount: number;
+    readonly presentedCount: number;
+    readonly totalCount: number;
+}
+/**
+ * 将调用方已经稳定排序的 Finding 投影为有界 Check messages。
+ *
+ * `limit`、安全字段和超限后的深入查看说明都由 producing Check 决定。Product 不读取 Finding
+ * shape，也不猜测完整明细位于 Records、artifact、transcript 或其它位置。
+ */
+export declare function presentCheckFindings<Finding>(input: {
+    readonly findings: readonly Finding[];
+    readonly limit: number;
+    readonly message: (finding: Finding, index: number) => CheckMessage;
+    readonly omittedMessage: (context: FindingOverflowContext<Finding>) => CheckMessage;
+}): readonly CheckMessage[];
+/** Appends presentation-only messages without changing the owning terminal result. */
+export declare function appendCheckMessages<Data extends object>(result: CheckResult<Data>, messages: readonly CheckMessage[]): CheckResult<Data>;

package/types/check/inherited-collection.d.ts

@@ -22,7 +22,7 @@ export type InheritedCheckCollection<T> = InheritCheckCollectionInput<T> & Reado
  */
 export type InheritableCheckCollection<T> = readonly T[] | InheritedCheckCollection<T>;
 /**
- * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。
+ * 创建可用于 `dependsOn`、`observes` 或 `mutex` 的受信任继承编辑。
  *
  * @typeParam T - 要添加或移除的 collection item 类型。
  * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。

package/types/check-settlement/reason-shape.d.ts

@@ -0,0 +1,5 @@
+export type ClosedCheckReason = Readonly<Record<string, unknown>> & Readonly<{
+    readonly code: string;
+}>;
+/** Recognizes the shared closed reason shape before owner-specific ID validation. */
+export declare function isClosedCheckReason(value: Readonly<Record<string, unknown>> | undefined, allowCheckIds: boolean): value is ClosedCheckReason;

package/types/check-settlement/record-store.d.ts

@@ -4,11 +4,11 @@ export type RecordDiagnostic = "record-conflict" | "record-invalid";
 export interface CoreRecordSlot {
     readonly checkId: string;
     readonly diagnostics: Set<RecordDiagnostic>;
-    readonly recordIds: Set<string>;
 }
-/** Holds one Check's minimal Records without inventing a composite string identity. */
+/** Holds Check-local supplemental Records without inventing a composite string identity. */
 export declare class CoreRecordStore {
     #private;
     report(slot: CoreRecordSlot, rawIdentity: unknown, rawData: unknown): RecordSubmissionResult;
+    recordsForCheckInCanonicalOrder(checkId: string): readonly CoreRecord[];
     recordsInCanonicalOrder(): readonly CoreRecord[];
 }

package/types/check-settlement/session.d.ts

@@ -1,7 +1,7 @@
 import type { CheckDescriptor } from "../check/descriptor.ts";
 import type { CheckOutcome } from "../check/check.ts";
 import { type RecordSubmissionResult } from "./record-store.ts";
-import type { CoreSnapshot } from "./facts.ts";
+import type { CoreRecord, CoreSnapshot } from "./facts.ts";
 export type { RecordSubmissionResult } from "./record-store.ts";
 export interface CoreCheckRegistration {
     readonly definition: CheckDescriptor;
@@ -26,6 +26,8 @@ export interface AuthorCheckSettlement {
 export interface CoreCheckSession {
     openCheckScope(checkId: string): TrustedCheckScope;
     readSettledCheckOutcome(checkId: string): CheckOutcome;
+    /** Product-private readback used only after this Check's terminal settlement. */
+    readSettledCheckRecords(checkId: string): readonly CoreRecord[];
     closeUnresolvedAsCancelled(): readonly CancelledCheckClosure[];
     freeze(): CoreSnapshot;
 }

package/types/data-boundary/closed-values.d.ts

@@ -1,8 +1,16 @@
 export declare function snapshotPlainRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
 export declare function snapshotClosedRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
+/** Snapshots a closed plain record only when it has exactly the declared own keys. */
+export declare function snapshotExactClosedRecord(value: unknown, keys: readonly string[]): Readonly<Record<string, unknown>> | undefined;
 export declare function snapshotClosedArray(value: unknown): readonly unknown[] | undefined;
 export declare function hasExactPlainRecordKeys(value: Readonly<Record<string, unknown>>, keys: readonly string[]): boolean;
 export declare function hasRequiredAndOptionalRecordKeys(value: Readonly<Record<string, unknown>>, keys: Readonly<{
     readonly optional: readonly string[];
     readonly required: readonly string[];
 }>): boolean;
+export interface ClosedPolicyRecordKeys {
+    readonly optional?: readonly string[];
+    readonly required?: readonly string[];
+}
+/** Snapshots an authoring record whose keys are limited to one required/optional policy. */
+export declare function snapshotClosedPolicyRecord(value: unknown, keys: ClosedPolicyRecordKeys): Readonly<Record<string, unknown>> | undefined;

package/types/data-boundary/value-shapes.d.ts

@@ -2,3 +2,6 @@ export declare function isRecord(value: unknown): value is Record<string, unknow
 export declare function isNonArrayRecord(value: unknown): value is Record<string, unknown>;
 export declare function isUnknownArray(value: unknown): value is unknown[];
 export declare function isStringArray(value: unknown): value is string[];
+export declare function isNonEmptyString(value: unknown): value is string;
+export declare function isPositiveSafeInteger(value: unknown): value is number;
+export declare function isNonNegativeSafeInteger(value: unknown): value is number;

package/types/index.d.ts

@@ -1,13 +1,15 @@
 /**
- * Vibe Check 是由项目在 Bun runtime 中调用的 TypeScript API，用于定义并执行项目质量 Check。
+ * Vibe Check 是由项目在 Node runtime 中调用的 TypeScript API，用于定义并执行项目质量 Check。
  * 所有公开能力从 package root 导入；package `README.md` 说明 consumer authoring、结果读取和分发范围。
  *
  * @packageDocumentation
  */
+export { cacheJsonByKey } from "./cache/cache-json-by-key.ts";
+export type { CacheJsonByKeyOptions, CacheJsonByKeyResult } from "./cache/cache-json-by-key.ts";
 export { duplicateDetection } from "./package-checks/duplicate-detection/default-check.ts";
 export { parseDuplicateDetectionData } from "./package-checks/duplicate-detection/final-data.ts";
 export type { DuplicateDetectionFinalData } from "./package-checks/duplicate-detection/final-data.ts";
-export type { DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./package-checks/duplicate-detection/options.ts";
+export type { DuplicateDetectionFindingIdentity, DuplicateDetectionFindingLocation, DuplicateDetectionFindingWaiver, DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./package-checks/duplicate-detection/options.ts";
 export type { DuplicateDetectionUnavailableReasonCode } from "./package-checks/duplicate-detection/execution.ts";
 export type { DuplicateDetectionRecordData } from "./package-checks/duplicate-detection/records.ts";
 export { fileMetrics } from "./package-checks/file-metrics/constructor.ts";
@@ -19,13 +21,19 @@ export type { FileMetricsRecordData } from "./package-checks/file-metrics/record
 export { functionMetrics } from "./package-checks/function-metrics/constructor.ts";
 export { parseFunctionMetricsData } from "./package-checks/function-metrics/final-data.ts";
 export type { FunctionMetricsFinalData } from "./package-checks/function-metrics/final-data.ts";
-export type { FunctionMetricsOptions, ResolvedFunctionMetricsOptions } from "./package-checks/function-metrics/options.ts";
+export type { FunctionMetricsFindingIdentity, FunctionMetricsFindingMetric, FunctionMetricsFindingWaiver, FunctionMetricsOptions, ResolvedFunctionMetricsOptions } from "./package-checks/function-metrics/options.ts";
 export type { FunctionMetricsUnavailableReasonCode } from "./package-checks/function-metrics/execution.ts";
 export type { FunctionMetricsRecordData } from "./package-checks/function-metrics/records.ts";
+export { secretDetection } from "./package-checks/secret-detection/default-check.ts";
+export { parseSecretDetectionData } from "./package-checks/secret-detection/final-data.ts";
+export type { SecretDetectionFinalData } from "./package-checks/secret-detection/final-data.ts";
+export type { ResolvedSecretDetectionOptions, SecretDetectionFindingIdentity, SecretDetectionFindingWaiver, SecretDetectionOptions } from "./package-checks/secret-detection/options.ts";
+export type { SecretDetectionUnavailableReasonCode } from "./package-checks/secret-detection/execution.ts";
+export type { SecretDetectionRecordData } from "./package-checks/secret-detection/records.ts";
 export { jsonSchemaValidation } from "./package-checks/json-schema-validation/default-check.ts";
 export { parseJsonSchemaValidationData } from "./package-checks/json-schema-validation/final-data.ts";
 export type { JsonSchemaValidationFinalData } from "./package-checks/json-schema-validation/final-data.ts";
-export type { JsonSchemaValidationOptions, ResolvedJsonSchemaValidationOptions } from "./package-checks/json-schema-validation/options.ts";
+export type { JsonSchemaIdentity, JsonSchemaIdentityMode, JsonSchemaInstanceBinding, JsonSchemaReferenceResolution, JsonSchemaReferenceSource, JsonSchemaValidationOptions, RegisteredJsonSchema, ResolvedJsonSchemaValidationOptions } from "./package-checks/json-schema-validation/options.ts";
 export type { JsonSchemaDocumentReason, JsonSchemaValidationRecordData, JsonSchemaValidationRecordReason, JsonSchemaValidationUnavailableCode } from "./package-checks/json-schema-validation/json-schema-validation.ts";
 export { jsonValidation } from "./package-checks/json-validation/default-check.ts";
 export { parseJsonValidationData } from "./package-checks/json-validation/final-data.ts";
@@ -45,13 +53,20 @@ export type { MarkdownLinkValidationRecordData } from "./package-checks/markdown
 export type { MarkdownLinkFindingReason } from "./package-checks/markdown-link-validation/local-resolver.ts";
 export type { FindingPolicy } from "./package-checks/code-quality-findings/policy.ts";
 export { reconcileFindingWaivers } from "./finding-waivers/reconciliation.ts";
+export { presentCheckFindings } from "./check/finding-presentation.ts";
 export type { FindingWaiver, FindingWaiverAudit, FindingWaiverReconciliation, MaterializedFindingWaiver, ReconciledFinding, ReconcileFindingWaiversOptions } from "./finding-waivers/reconciliation.ts";
 export { defaultProjectFileSelection } from "./package-checks/project-files/configuration.ts";
+export { collectProjectFiles } from "./package-checks/project-files/public-collection.ts";
+export type { CollectProjectFilesOptions } from "./package-checks/project-files/public-collection.ts";
 export type { ProjectFileSelection, ProjectFileSelectionOptions, ProjectFileSource } from "./package-checks/project-files/configuration.ts";
 export { defineCheck, inherit } from "./check/check.ts";
-export type { Check, CheckExecution, CheckExecutionContext, CheckPreflight, CheckPreflightResult, CheckOutcome, CheckResult, CheckUnavailableReason, InheritableCheckCollection } from "./check/check.ts";
-export { defineConfig } from "./project-definition/project-definition.ts";
-export type { ProjectOutputs, ProjectDefinition, SchedulerPolicy } from "./project-definition/project-definition.ts";
+export type { Check, CheckDependencies, CheckExecution, CheckExecutionContext, CheckPreflight, CheckPreflightResult, CheckResourceClaims, CheckOutcome, CheckResult, CheckUnavailableReason, InheritableCheckCollection } from "./check/check.ts";
+export { defineAdmissionPolicy, defineConfig } from "./project-definition/project-definition.ts";
+export { createLearnedCriticalPathStrategy } from "./learned-critical-path/strategy.ts";
+export type { LearnedCriticalPathObservation, LearnedCriticalPathStrategyOptions } from "./learned-critical-path/strategy.ts";
+export { createAdmissionGraph } from "./project-run/task-scheduler/admission-core/core.ts";
+export type { AdmissionPolicy, AdmissionPolicyContext, AdmissionPolicyMeasurement, AdmissionProposal, AdmissionCatalog, AdmissionGraph, AdmissionGraphInput, AdmissionInspection, AdmissionNonSelectableTask, AdmissionRejectionReason, AdmissionScopeLifecycle, AdmissionSelectionRejectionReason, AdmissionSelectionValidation, AdmissionSelectionValidationRejectionReason, AdmissionSettlementOutcome, AdmissionSettledTask, AdmissionState, AdmissionTransitionResult, CustomAdmissionPreparationContext, CustomAdmissionStrategy, PreparedCustomAdmissionStrategy, ProgressPreviewFormatter, ProjectOutputs, ProjectDefinition, SchedulerDecisionMeasurementCumulative, SchedulerGraphSnapshot, SchedulerMeasurementContext, SchedulerMeasurementHook, SchedulerMeasurementIntervalContribution, SchedulerMeasurementActionObservationInterval, SchedulerMeasurementActionObservation, SchedulerMeasurementEffect, SchedulerRawMeasurement, SchedulerPolicy } from "./project-definition/project-definition.ts";
 export type { CheckAggregate, CheckAggregation, RunControls } from "./project-run/controls/contract.ts";
 export { run } from "./project-run/run.ts";
+export type { RunOutputStatus, RunOutputStatuses } from "./project-run/outputs/status.ts";
 export type { RunResult } from "./project-run/result.ts";

package/types/learned-critical-path/duration-model/bounded-history.d.ts

@@ -0,0 +1,34 @@
+export declare const SCHEDULER_HISTORY_ENVELOPE_VERSION = "scheduler-history-envelope-v1";
+export declare const SCHEDULER_HISTORY_FILE_NAME = "scheduler-history.json";
+export declare const SCHEDULER_HISTORY_MODEL_VERSION = "scheduler-duration-model-v1";
+export declare const MAX_SCHEDULER_HISTORY_SAMPLES_PER_SERIES = 32;
+export declare const MAX_SCHEDULER_HISTORY_SERIES = 4096;
+/** Bound persisted task-active durations so aggregates remain exact safe integers. */
+export declare const MAX_SCHEDULER_HISTORY_DURATION_MS = 2147483647;
+/** Persisted terminal kind vocabulary; duration storage does not depend on Scheduler ownership. */
+export type SchedulerDurationSettlementKind = "completed" | "prerequisite-unsatisfied" | "failed" | "blocked" | "cancelled-before-start";
+export interface SchedulerHistorySample {
+    readonly durationMs: number;
+    readonly observationSequence: number;
+    readonly settlementKind: SchedulerDurationSettlementKind;
+}
+export interface SchedulerHistorySeries {
+    readonly identityDigest: string;
+    readonly latestObservationSequence: number;
+    readonly samples: readonly SchedulerHistorySample[];
+}
+/** Immutable, Product-private local model; the only persisted state is its closed envelope. */
+export interface SchedulerHistoryModel {
+    readonly latestObservationSequence: number;
+    readonly series: readonly SchedulerHistorySeries[];
+}
+export declare function emptySchedulerHistory(): SchedulerHistoryModel;
+export declare function schedulerHistorySeries(history: SchedulerHistoryModel, identityDigest: string): SchedulerHistorySeries | undefined;
+export declare function freezeSchedulerHistoryModel(input: {
+    readonly latestObservationSequence: number;
+    readonly series: readonly SchedulerHistorySeries[];
+}): SchedulerHistoryModel;
+export declare function isSchedulerHistoryIdentityDigest(value: unknown): value is string;
+export declare function isSchedulerSettlementKind(value: unknown): value is SchedulerDurationSettlementKind;
+export declare function isBoundedDurationMs(value: unknown): value is number;
+export declare function isObservationSequence(value: unknown): value is number;

package/types/learned-critical-path/duration-model/prediction.d.ts

@@ -0,0 +1,32 @@
+import { type CanonicalJsonValue } from "../../data-boundary/canonical-data.ts";
+import { type SchedulerHistoryModel } from "./bounded-history.ts";
+export type SchedulerPredictionSource = "learned" | "project-prior" | "cold-start";
+export interface SchedulerPredictionInput {
+    readonly authoredOptions: CanonicalJsonValue;
+    readonly checkId: string;
+    readonly flags: CanonicalJsonValue;
+    readonly taskId: string;
+}
+export interface SchedulerTaskPrediction {
+    readonly estimatedDurationMs: number;
+    readonly identityDigest: string;
+    readonly meanDurationMs: number | null;
+    readonly p90DurationMs: number | null;
+    readonly sampleCount: number;
+    readonly source: SchedulerPredictionSource;
+    readonly taskId: string;
+}
+/** Frozen before Scheduler admission; it does not retain authored options or flag values. */
+export interface SchedulerPredictionSnapshot {
+    readonly digest: string;
+    readonly modelVersion: string;
+    readonly predictions: readonly SchedulerTaskPrediction[];
+}
+export declare function createSchedulerHistoryIdentity(input: {
+    readonly authoredOptions: CanonicalJsonValue;
+    readonly checkId: string;
+    readonly flags: CanonicalJsonValue;
+}): string;
+/** Forms learned means first, then one project median prior, without invoking preflight. */
+export declare function createSchedulerPredictionSnapshot(history: SchedulerHistoryModel, inputs: readonly SchedulerPredictionInput[], coldStartDurationMs?: number): SchedulerPredictionSnapshot;
+export declare function predictionForTask(snapshot: SchedulerPredictionSnapshot, taskId: string): SchedulerTaskPrediction | undefined;

package/types/learned-critical-path/duration-model/preparation.d.ts

@@ -0,0 +1,28 @@
+import type { SchedulerMeasurementContext } from "../../project-definition/project-definition.ts";
+import { type SchedulerHistoryRecordingObservation } from "./recording.ts";
+import { type SchedulerPredictionInput, type SchedulerPredictionSnapshot } from "./prediction.ts";
+import { loadSchedulerHistory, writeSchedulerHistory } from "./storage.ts";
+export type SchedulerDurationModelPreparation = Readonly<{
+    readonly kind: "ready";
+    readonly prediction: SchedulerPredictionSnapshot;
+    readonly readObservation: Awaited<ReturnType<typeof loadSchedulerHistory>>["observation"];
+    readonly retainedSeriesCount: number;
+    readonly record: (terminalMeasurement: SchedulerMeasurementContext) => Promise<SchedulerDurationModelRecordObservation>;
+}> | Readonly<{
+    readonly kind: "static-fallback";
+}>;
+export type SchedulerDurationModelRecordObservation = Readonly<{
+    readonly kind: "recorded";
+    readonly recording: SchedulerHistoryRecordingObservation;
+    readonly writeObservation: Awaited<ReturnType<typeof writeSchedulerHistory>>;
+}> | Readonly<{
+    readonly kind: "failed";
+}>;
+/** Prepares one immutable duration prediction and its terminal record capability outside Scheduler. */
+export declare function prepareSchedulerDurationModel(input: {
+    readonly predictionInputs: readonly SchedulerPredictionInput[];
+    readonly stateDirectory: string;
+    readonly coldStartDurationMs?: number;
+    readonly maxSamplesPerSeries?: number;
+    readonly maxSeries?: number;
+}): Promise<SchedulerDurationModelPreparation>;

package/types/learned-critical-path/duration-model/recording.d.ts

@@ -0,0 +1,28 @@
+import type { SchedulerRawMeasurement } from "../../project-definition/project-definition.ts";
+import { type SchedulerDurationSettlementKind, type SchedulerHistoryModel } from "./bounded-history.ts";
+import { type SchedulerPredictionSnapshot } from "./prediction.ts";
+export type SchedulerHistoryRecordingObservation = Readonly<{
+    readonly acceptedSampleCount: number;
+    readonly retainedSeriesCount: number;
+    readonly status: "recorded";
+}> | Readonly<{
+    readonly acceptedSampleCount: 0;
+    readonly retainedSeriesCount: number;
+    readonly status: "timing-unavailable";
+}>;
+export interface SchedulerHistoryRecording {
+    readonly history: SchedulerHistoryModel;
+    readonly observation: SchedulerHistoryRecordingObservation;
+}
+/** Merges only trusted terminal Scheduler occupancy intervals; unavailable timing creates no samples. */
+export declare function recordSchedulerHistory(input: {
+    readonly history: SchedulerHistoryModel;
+    readonly prediction: SchedulerPredictionSnapshot;
+    readonly rawMeasurement: SchedulerRawMeasurement;
+    readonly settledTasks: readonly Readonly<{
+        readonly kind: SchedulerDurationSettlementKind;
+        readonly taskId: string;
+    }>[];
+    readonly maxSamplesPerSeries?: number;
+    readonly maxSeries?: number;
+}): SchedulerHistoryRecording;

package/types/learned-critical-path/duration-model/storage.d.ts

@@ -0,0 +1,12 @@
+import { type SchedulerHistoryModel } from "./bounded-history.ts";
+export type SchedulerHistoryReadObservation = "loaded" | "missing" | "invalid" | "incompatible" | "failed";
+export type SchedulerHistoryWriteObservation = "stored" | "failed";
+export interface SchedulerHistoryLoad {
+    readonly history: SchedulerHistoryModel;
+    readonly observation: SchedulerHistoryReadObservation;
+}
+/** Reads untrusted local state and always degrades to an empty model on an I/O or format fault. */
+export declare function loadSchedulerHistory(stateDirectory: string): Promise<SchedulerHistoryLoad>;
+/** Publishes a full closed model through a same-directory temporary file and atomic replacement. */
+export declare function writeSchedulerHistory(stateDirectory: string, history: SchedulerHistoryModel): Promise<SchedulerHistoryWriteObservation>;
+export declare function schedulerHistoryPath(stateDirectory: string): string;

package/types/learned-critical-path/selection-layers.d.ts

@@ -0,0 +1,14 @@
+import type { AdmissionPolicyContext, SchedulerGraphSnapshot } from "../project-definition/project-definition.ts";
+type Candidate = AdmissionPolicyContext["candidates"][number];
+type Task = SchedulerGraphSnapshot["tasks"][number];
+type Scope = SchedulerGraphSnapshot["scopes"][number];
+export interface LearnedSelectionLayers {
+    readonly continuation: readonly Candidate[];
+    readonly scopeById: ReadonlyMap<string, Scope>;
+    readonly taskById: ReadonlyMap<string, Task>;
+    readonly tightening: readonly Candidate[];
+}
+/** Projects the public graph and boundary facts into the Scheduler's two constrained selection layers. */
+export declare function learnedSelectionLayers(context: AdmissionPolicyContext): LearnedSelectionLayers;
+export declare function scopeForCandidate(candidate: Candidate, taskById: ReadonlyMap<string, Task>, scopeById: ReadonlyMap<string, Scope>): Scope | undefined;
+export {};

package/types/learned-critical-path/static-decision.d.ts

@@ -0,0 +1,3 @@
+import type { AdmissionPolicyContext, AdmissionProposal } from "../project-definition/project-definition.ts";
+/** Preserves ordinary static selection when learned preparation cannot form a ranking. */
+export declare function staticDecision(context: AdmissionPolicyContext): AdmissionProposal;

package/types/learned-critical-path/strategy.d.ts

@@ -0,0 +1,35 @@
+import type { CustomAdmissionStrategy, SchedulerGraphSnapshot } from "../project-definition/project-definition.ts";
+/** 公开 learned critical-path prepared strategy 的调用方配置。 */
+export interface LearnedCriticalPathStrategyOptions {
+    /** 调用方拥有的可丢弃 learned duration history 本地目录；必须是绝对路径。 */
+    readonly stateDirectory: string;
+    /** 为每个公开 Task 提供 canonical-JSON-compatible 的调用方 identity projection。 */
+    readonly identityForTask: (task: SchedulerGraphSnapshot["tasks"][number]) => unknown;
+    /** 单个 identity 最多保留的样本数；默认 32。 */
+    readonly sampleWindow?: number;
+    /** 最多保留的 identity 数；默认 4096。 */
+    readonly maxHistorySeries?: number;
+    /** 正的 cold-start duration 权重（毫秒）；默认 1。 */
+    readonly coldStartDurationMs?: number;
+    /** 可选调用方 observation sink；observer fault 不改变 scheduling 或 Run facts。 */
+    readonly observe?: (event: LearnedCriticalPathObservation) => void | Promise<void>;
+}
+/** 调用方可选 observer 收到的有界 learned strategy 事件；selection-proposed 不表示 Scheduler 已接受 admission。 */
+export type LearnedCriticalPathObservation = Readonly<{
+    readonly kind: "history-unavailable";
+    readonly reason: "identity-invalid" | "setup-failed";
+}> | Readonly<{
+    readonly kind: "selection-proposed";
+    readonly taskId: string;
+    readonly estimatedDurationMs: number;
+    readonly criticalPathScore: number;
+    readonly sampleCount: number;
+    readonly source: "learned" | "project-prior" | "cold-start";
+}> | Readonly<{
+    readonly kind: "recording-unavailable";
+}>;
+/**
+ * 构造普通公开 prepared strategy。调用方拥有 history location 与 identity projection；
+ * Product 只按同一 custom strategy lifecycle 调用它，不为该 helper 增加特权。
+ */
+export declare function createLearnedCriticalPathStrategy(options: LearnedCriticalPathStrategyOptions): CustomAdmissionStrategy;

package/types/package-checks/code-quality-findings/finding-waiver-authoring.d.ts

@@ -0,0 +1,7 @@
+import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+/**
+ * Snapshots the shared closed waiver envelope while leaving identity grammar to the producing Check.
+ */
+export declare function resolveFindingWaiverAuthoring<Identity>(value: unknown, resolveIdentity: (value: unknown) => Identity | undefined): readonly FindingWaiver<Identity>[] | undefined;
+/** Validates the complete resolved waiver list through the same authoring boundary. */
+export declare function validResolvedFindingWaivers<Identity>(value: unknown, resolveIdentity: (value: unknown) => Identity | undefined): value is readonly FindingWaiver<Identity>[];

package/types/package-checks/code-quality-findings/finding-waiver-evidence.d.ts

@@ -0,0 +1,34 @@
+import type { CheckExecutionContext } from "../../check/check.ts";
+import type { FindingWaiverAudit, FindingWaiverReconciliation } from "../../finding-waivers/reconciliation.ts";
+interface CodeQualityFindingCandidate {
+    readonly data: Readonly<{
+        readonly blocking: boolean;
+    }>;
+    readonly id: string;
+}
+type FindingRecordContext = Pick<CheckExecutionContext<object>, "records">;
+export type FindingWaiverRecordAudit = Readonly<Omit<FindingWaiverAudit, "status"> & {
+    readonly status: "overmatched" | "unused";
+}>;
+export type FindingWaiverAuditRecordData<Identity> = Readonly<{
+    readonly identity: Identity;
+    readonly kind: "finding-waiver-audit";
+    readonly matchCount: number;
+    readonly reason: string;
+    readonly status: "overmatched" | "unused";
+}>;
+/** Builds the common immutable data shared by Check-owned waiver audit Records. */
+export declare function buildFindingWaiverAuditRecordData<Identity>(identity: Identity, audit: FindingWaiverRecordAudit): FindingWaiverAuditRecordData<Identity>;
+/** Builds the shared hash-addressed audit Record used by structured identities. */
+export declare function buildHashedFindingWaiverAuditRecord<Identity>(identity: Identity, audit: FindingWaiverRecordAudit): Readonly<{
+    readonly data: FindingWaiverAuditRecordData<Identity>;
+    readonly id: string;
+}>;
+/** Publishes every reconciled metric Finding while preserving applied waiver evidence. */
+export declare function reportReconciledCodeQualityFindingRecords<Finding extends CodeQualityFindingCandidate>(context: FindingRecordContext, reconciliation: FindingWaiverReconciliation<Finding>): void;
+/** Publishes only unused/overmatched audit rows built by the identity-owning Check. */
+export declare function reportFindingWaiverAudits<Finding, AuditData extends object>(context: FindingRecordContext, reconciliation: FindingWaiverReconciliation<Finding>, buildRecord: (audit: FindingWaiverRecordAudit) => Readonly<{
+    readonly data: AuditData;
+    readonly id: string;
+}>): void;
+export {};

package/types/package-checks/code-quality-findings/policy.d.ts

@@ -5,7 +5,9 @@ export type FindingPolicy = (typeof FINDING_POLICIES)[number];
 export declare const DEFAULT_FINDING_POLICY: FindingPolicy;
 /** 三个代码质量 Check 正常完成时返回的精确 finding 计数。 */
 export interface FindingSummary {
+    /** 仍可处置且采用 blocking policy 的 finding 数；waived finding 不计入。 */
     readonly blockingFindingCount: number;
+    /** Check 发现的全部 finding 数，包括已 waived 或 non-blocking 的 finding。 */
     readonly findingCount: number;
 }
 /** 一项 finding 在 Check 自己结算前的领域中性处置。 */
@@ -16,5 +18,7 @@ export interface FindingSettlement {
 }
 export declare function resolveFindingPolicy(value: unknown, fallback?: FindingPolicy): FindingPolicy | undefined;
 export declare function validFindingPolicy(value: unknown): value is FindingPolicy;
+/** Resolves the closed, non-empty named area map shared by code-quality Checks. */
+export declare function resolveCodeAreaPolicyMap<Area>(value: unknown, defaultArea: () => Area, resolveArea: (candidate: unknown) => Area | undefined): Readonly<Record<string, Area>> | undefined;
 export declare function isBlockingFinding(policies: readonly FindingPolicy[]): boolean;
 export declare function settleFindings(findings: readonly FindingSettlement[]): CheckResult<FindingSummary>;

package/types/package-checks/duplicate-detection/area-policy.d.ts

@@ -1,3 +1,3 @@
 import type { DuplicateCodeFragment, DuplicateDetectionAreaInput } from "./measurement-model.ts";
-/** Restores every matching code area and applies the strictest involved policy. */
+/** Retains fragments whose locations share an area and applies its strictest policy. */
 export declare function applyDuplicateAreaPolicy(fragments: readonly DuplicateCodeFragment[], areas: readonly DuplicateDetectionAreaInput[]): readonly DuplicateCodeFragment[] | undefined;

package/types/package-checks/duplicate-detection/finding-messages.d.ts

@@ -0,0 +1,7 @@
+import type { CheckMessage } from "../../check/check.ts";
+import type { FindingWaiverReconciliation } from "../../finding-waivers/reconciliation.ts";
+import { type DuplicateRecordCandidate } from "./records.ts";
+/** Projects duplicate Records into bounded, project-relative terminal summaries. */
+export declare function duplicateFindingMessages(candidates: readonly DuplicateRecordCandidate[]): readonly CheckMessage[];
+/** 将每项 duplicate-detection waiver audit 投影为可行动的 terminal message。 */
+export declare function duplicateWaiverMessages(reconciliation: FindingWaiverReconciliation<DuplicateRecordCandidate>): readonly CheckMessage[];

package/types/package-checks/duplicate-detection/finding-waiver-identity.d.ts

@@ -0,0 +1,3 @@
+import type { DuplicateDetectionFindingIdentity, DuplicateDetectionFindingLocation } from "./options.ts";
+export declare function resolveDuplicateDetectionFindingIdentity(value: unknown): DuplicateDetectionFindingIdentity | undefined;
+export declare function compareDuplicateFindingLocations(left: DuplicateDetectionFindingLocation, right: DuplicateDetectionFindingLocation): number;

package/types/package-checks/duplicate-detection/jscpd/command-resolution.d.ts

@@ -13,7 +13,7 @@ export type ResolvedJscpdCommand = Readonly<{
 }>;
 /**
  * package-provided scanner 的可移植 marker。真实 executable 只由私有 jscpd adapter 解析，避免公共
- * Definition 与 fingerprint 保存 consumer-specific Bun 或 package path。
+ * Definition 与 fingerprint 保存 consumer-specific runtime 或 package path。
  */
 export declare const DEFAULT_JSCPD_COMMAND: DuplicateDetectionScannerCommand;
 export declare function isPackageJscpdCommand(command: DuplicateDetectionScannerCommand): command is Extract<DuplicateDetectionScannerCommand, {

package/types/package-checks/duplicate-detection/options.d.ts

@@ -1,5 +1,6 @@
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
 export type DuplicateDetectionScannerCommand = 
 /** 使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
 Readonly<{
@@ -23,9 +24,22 @@ export interface DuplicateDetectionScannerOptions {
     /** 省略时使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
     readonly command?: DuplicateDetectionScannerCommand;
 }
+/** duplicate-detection identity 的 locations 数组中的一段 project-relative range。 */
+export interface DuplicateDetectionFindingLocation {
+    readonly endLine: number;
+    readonly path: string;
+    readonly startLine: number;
+}
+/** duplicate-detection 用于精确识别一条可豁免 finding 的稳定字段。 */
+export interface DuplicateDetectionFindingIdentity {
+    readonly locations: readonly DuplicateDetectionFindingLocation[];
+    readonly metric: "duplicate-tokens";
+}
+/** 一项 duplicate-detection finding 的声明式豁免。 */
+export type DuplicateDetectionFindingWaiver = FindingWaiver<DuplicateDetectionFindingIdentity>;
 /** 重复代码区域可省略并由构造函数补齐的文件策略。 */
 export type DuplicateDetectionFileOptions = ProjectFileSelectionOptions;
-/** 可独立选择文件、阈值和 finding policy 的重复代码区域。 */
+/** 同时拥有文件选择、比较边界、阈值和 finding policy 的重复代码区域。 */
 export interface DuplicateDetectionCodeAreaOptions {
     /** 显式区域必须声明本字段；其中各子字段可省略并使用 package 默认值。 */
     readonly files: DuplicateDetectionFileOptions;
@@ -43,6 +57,8 @@ export interface DuplicateDetectionOptions {
     readonly cache?: DuplicateDetectionCacheOptions;
     /** 省略时为 `non-blocking`；区域可局部覆盖。 */
     readonly findingPolicy?: FindingPolicy;
+    /** 省略时没有豁免；identity 使用 Finding 发布的完整排序 location ranges。 */
+    readonly findingWaivers?: readonly DuplicateDetectionFindingWaiver[];
     readonly scanner?: DuplicateDetectionScannerOptions;
 }
 /** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
@@ -52,6 +68,7 @@ export interface ResolvedDuplicateDetectionOptions {
         readonly enabled: boolean;
     }>;
     readonly codeAreas: Readonly<Record<string, ResolvedDuplicateDetectionCodeAreaOptions>>;
+    readonly findingWaivers: readonly DuplicateDetectionFindingWaiver[];
     readonly scanner: ResolvedDuplicateDetectionScannerOptions;
 }
 export interface ResolvedDuplicateDetectionCodeAreaOptions {

package/types/package-checks/duplicate-detection/records.d.ts

@@ -1,7 +1,9 @@
+import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import { type FindingWaiverAuditRecordData, type FindingWaiverRecordAudit } from "../code-quality-findings/finding-waiver-evidence.ts";
 import type { DuplicateCodeFragment } from "./measurement-model.ts";
-import type { ResolvedDuplicateDetectionOptions } from "./options.ts";
+import type { DuplicateDetectionFindingIdentity, ResolvedDuplicateDetectionOptions } from "./options.ts";
 /** 一条可信重复片段 supplemental Record 的 data。 */
-export type DuplicateDetectionRecordData = Readonly<{
+export type DuplicateDetectionFindingRecordData = Readonly<{
     readonly blocking: boolean;
     readonly codeAreas: readonly string[];
     readonly lineCount: number;
@@ -12,11 +14,26 @@ export type DuplicateDetectionRecordData = Readonly<{
     }>[];
     readonly metric: "duplicate-tokens";
     readonly tokenCount: number;
+    /** 精确匹配 waiver 时保留理由，并令该 finding 不再参与 actionable settlement。 */
+    readonly waiver?: Readonly<{
+        readonly reason: string;
+    }>;
 }>;
+/** 未使用或过宽 duplicate-detection waiver 的 supplemental audit Record data。 */
+export type DuplicateDetectionFindingWaiverAuditRecordData = FindingWaiverAuditRecordData<DuplicateDetectionFindingIdentity>;
+/** duplicateDetection 发布的 normal finding 或 waiver-audit Record data。 */
+export type DuplicateDetectionRecordData = DuplicateDetectionFindingRecordData | DuplicateDetectionFindingWaiverAuditRecordData;
 export interface DuplicateRecordCandidate {
-    readonly data: DuplicateDetectionRecordData;
+    readonly data: DuplicateDetectionFindingRecordData;
     readonly id: string;
 }
+export declare function duplicateDetectionFindingIdentity(candidate: DuplicateRecordCandidate): DuplicateDetectionFindingIdentity;
+export declare function duplicateDetectionWaiverIdentity(waiver: MaterializedFindingWaiver): DuplicateDetectionFindingIdentity;
+/** 为一项未使用或过宽 waiver 构造 Check-owned audit Record。 */
+export declare function duplicateDetectionWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
+    readonly data: DuplicateDetectionFindingWaiverAuditRecordData;
+    readonly id: string;
+}>;
 /** Builds Check-owned supplemental facts without adding a Product record catalog. */
 export declare function buildDuplicateRecordCandidates(fragments: readonly DuplicateCodeFragment[], codeAreas: ResolvedDuplicateDetectionOptions["codeAreas"]): readonly DuplicateRecordCandidate[] | undefined;
 export declare function isValidDuplicateFragment(fragment: DuplicateCodeFragment): boolean;

package/types/package-checks/file-metrics/finding-messages.d.ts

@@ -0,0 +1,4 @@
+import type { CheckMessage } from "../../check/check.ts";
+import type { FileRecordCandidate } from "./records.ts";
+/** Projects actionable file-metric Records into bounded terminal summaries. */
+export declare function fileMetricFindingMessages(findings: readonly FileRecordCandidate[]): readonly CheckMessage[];

package/types/package-checks/file-metrics/records.d.ts

@@ -1,6 +1,7 @@
 import type { FileMetric } from "./measurement-model.ts";
 import type { FileMetricsFindingIdentity, ResolvedFileMetricsCodeAreaOptions } from "./options.ts";
-import type { FindingWaiverAudit, MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import { type FindingWaiverAuditRecordData, type FindingWaiverRecordAudit } from "../code-quality-findings/finding-waiver-evidence.ts";
 interface FileMetricsAreaPolicyContext {
     readonly areaIdsByPath: ReadonlyMap<string, readonly string[]>;
     readonly codeAreas: Readonly<Record<string, ResolvedFileMetricsCodeAreaOptions>>;
@@ -19,13 +20,7 @@ export type FileMetricsFindingRecordData = Readonly<{
     }>;
 }>;
 /** 未使用或过宽 file-metrics waiver 的 supplemental audit Record data。 */
-export type FileMetricsFindingWaiverAuditRecordData = Readonly<{
-    readonly identity: FileMetricsFindingIdentity;
-    readonly kind: "finding-waiver-audit";
-    readonly matchCount: number;
-    readonly reason: string;
-    readonly status: "overmatched" | "unused";
-}>;
+export type FileMetricsFindingWaiverAuditRecordData = FindingWaiverAuditRecordData<FileMetricsFindingIdentity>;
 /** file-metrics 发布的 finding 或 waiver-audit supplemental Record data。 */
 export type FileMetricsRecordData = FileMetricsFindingRecordData | FileMetricsFindingWaiverAuditRecordData;
 export interface FileRecordCandidate {
@@ -33,10 +28,10 @@ export interface FileRecordCandidate {
     readonly id: string;
 }
 /** 仅为未使用和过宽 waiver 构造补充 audit Record；正常 applied waiver 由 finding Record 自己保留。 */
-export declare function fileMetricsWaiverAuditRecord(audit: FindingWaiverAudit): Readonly<{
+export declare function fileMetricsWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
     readonly data: FileMetricsFindingWaiverAuditRecordData;
     readonly id: string;
-}> | undefined;
+}>;
 export declare function fileMetricsWaiverIdentity(waiver: MaterializedFindingWaiver): FileMetricsFindingIdentity;
 /** Converts trusted scanner metrics into area-policy-owned supplemental facts. */
 export declare function buildFileRecordCandidates(metrics: readonly FileMetric[], areaPolicy: FileMetricsAreaPolicyContext): readonly FileRecordCandidate[] | undefined;