@zxyycom/vibe-check 0.0.2 → 0.0.3

package/types/package-checks/host-environment/process/contract.d.ts

@@ -9,9 +9,12 @@ export interface ProcessFailure extends Error {
 }
 export type ProcessResult = {
     readonly error?: Error;
+    readonly isCanceled?: true;
+    readonly isMaxBuffer?: true;
     readonly signal: NodeJS.Signals | null;
     readonly status: number | null;
     readonly stderr: string;
+    readonly timedOut?: true;
     readonly stdout: string;
 };
 export type RunProcessSyncOptions = {
@@ -27,8 +30,11 @@ export type RunProcessSyncOptions = {
 };
 export type RunProcessOptions = {
     readonly args?: readonly string[];
+    readonly cancelSignal?: AbortSignal;
     readonly command: string;
     readonly cwd?: string | URL;
+    /** `false` uses only the supplied `env`; omission preserves Execa's inherited default. */
+    readonly extendEnv?: boolean;
     readonly env?: NodeJS.ProcessEnv;
     readonly label?: string;
     readonly maxBuffer?: number;
@@ -36,15 +42,17 @@ export type RunProcessOptions = {
     readonly windowsHide?: boolean;
 };
 export type ExecaResultLike = {
-    readonly code?: string;
-    readonly exitCode?: number;
-    readonly failed?: boolean;
-    readonly isMaxBuffer?: boolean;
-    readonly message?: string;
-    readonly originalMessage?: string;
-    readonly shortMessage?: string;
-    readonly signal?: NodeJS.Signals;
+    /** Execa's imported result types permit explicitly present `undefined` values. */
+    readonly code?: string | undefined;
+    readonly exitCode?: number | undefined;
+    readonly failed?: boolean | undefined;
+    readonly isCanceled?: boolean | undefined;
+    readonly isMaxBuffer?: boolean | undefined;
+    readonly message?: string | undefined;
+    readonly originalMessage?: string | undefined;
+    readonly shortMessage?: string | undefined;
+    readonly signal?: NodeJS.Signals | undefined;
     readonly stderr?: unknown;
     readonly stdout?: unknown;
-    readonly timedOut?: boolean;
+    readonly timedOut?: boolean | undefined;
 };

package/types/package-checks/json-schema-validation/default-check.d.ts

@@ -1,4 +1,5 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseJsonSchemaValidationData } from "./final-data.ts";
 import type { JsonSchemaValidationOptions, ResolvedJsonSchemaValidationOptions } from "./options.ts";
 /**
@@ -8,4 +9,6 @@ import type { JsonSchemaValidationOptions, ResolvedJsonSchemaValidationOptions }
  * @returns 固定 `json-schema-validation` identity、完整冻结 options、parser 与执行逻辑。
  * @throws {TypeError} input 不符合 closed authoring policy、identity 或 binding 不变量时抛出。
  */
-export declare function jsonSchemaValidation(options?: JsonSchemaValidationOptions): TypedCheckWithOptions<"json-schema-validation", ResolvedJsonSchemaValidationOptions, typeof parseJsonSchemaValidationData>;
+export declare function jsonSchemaValidation(options?: JsonSchemaValidationOptions<"json-schema-validation">): TypedCheckWithOptions<"json-schema-validation", ResolvedJsonSchemaValidationOptions, typeof parseJsonSchemaValidationData>;
+export declare function jsonSchemaValidation<const Id extends string>(options: JsonSchemaValidationOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedJsonSchemaValidationOptions, typeof parseJsonSchemaValidationData>;
+export declare function jsonSchemaValidation(options: JsonSchemaValidationOptions): TypedCheckWithOptions<string, ResolvedJsonSchemaValidationOptions, typeof parseJsonSchemaValidationData>;

package/types/package-checks/json-schema-validation/options.d.ts

@@ -1,3 +1,4 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 /** 已注册 schema 的 root `$id` 与配置 identity 之间的全 Check 统一规则。 */
 export type JsonSchemaIdentityMode = 
@@ -56,7 +57,7 @@ export interface JsonSchemaInstanceBinding {
     readonly schemaId: string;
 }
 /** `jsonSchemaValidation(options?)` 接受的可省略 authoring policy。 */
-export interface JsonSchemaValidationOptions {
+export interface JsonSchemaValidationOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
     /** schema/instance declarations 必须属于的 repository-file selection。 */
     readonly files?: ProjectFileSelectionOptions;
     /** 每个 local schema/instance document 允许的最大 raw byte 数；省略时为 1 MiB。 */

package/types/package-checks/json-validation/default-check.d.ts

@@ -1,4 +1,5 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseJsonValidationData } from "./final-data.ts";
 import type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./options.ts";
 /**
@@ -8,4 +9,6 @@ import type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./opt
  * @returns 固定 `json-validation` identity、完整冻结 options、final-data parser 与执行逻辑。
  * @throws {TypeError} input 含未知字段、非法文件选择或非法 byte limit 时抛出。
  */
-export declare function jsonValidation(options?: JsonValidationOptions): TypedCheckWithOptions<"json-validation", ResolvedJsonValidationOptions, typeof parseJsonValidationData>;
+export declare function jsonValidation(options?: JsonValidationOptions<"json-validation">): TypedCheckWithOptions<"json-validation", ResolvedJsonValidationOptions, typeof parseJsonValidationData>;
+export declare function jsonValidation<const Id extends string>(options: JsonValidationOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedJsonValidationOptions, typeof parseJsonValidationData>;
+export declare function jsonValidation(options: JsonValidationOptions): TypedCheckWithOptions<string, ResolvedJsonValidationOptions, typeof parseJsonValidationData>;

package/types/package-checks/json-validation/options.d.ts

@@ -1,6 +1,7 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 /** `jsonValidation(options?)` 接受的可省略 authoring policy。 */
-export interface JsonValidationOptions {
+export interface JsonValidationOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
     /** 参与本 Check 的 repository-file selection；省略字段使用 package defaults。 */
     readonly files?: ProjectFileSelectionOptions;
     /** 单个 JSON document 允许的最大 raw byte 数；省略时为 1 MiB。 */

package/types/package-checks/local-cache-options.d.ts

@@ -0,0 +1,9 @@
+/** Shared closed grammar for an explicitly owned, deletable local cache directory. */
+export type LocalCacheOptions = Readonly<{
+    readonly enabled: false;
+}> | Readonly<{
+    readonly enabled: true;
+    readonly directory: string;
+}>;
+export declare function resolveOptionalLocalCacheOptions(value: unknown): LocalCacheOptions | undefined;
+export declare function validLocalCacheOptions(value: unknown): value is LocalCacheOptions;

package/types/package-checks/maintenance-reminders/maintenance-reminders.d.ts

@@ -1,4 +1,5 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckAuthoringOptions, type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { MAINTENANCE_REMINDER_UNAVAILABLE_REASON, parseMaintenanceRemindersData, type MaintenanceReminderAssessment } from "./final-data.ts";
 export declare const MAINTENANCE_REMINDERS_CHECK_ID = "maintenance-reminders";
 declare const WHOLE_CHECK_UNAVAILABLE_CODE: Readonly<{
@@ -33,6 +34,11 @@ export interface MaintenanceReminderOptions {
         readonly executable: string;
     }>;
 }
+/** `maintenanceReminders` 的对象式构造输入，组合提醒政策与项目 Check 声明。 */
+export interface MaintenanceRemindersInput<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
+    /** 保留作者声明顺序的提醒政策条目。 */
+    readonly entries: readonly MaintenanceReminder[];
+}
 /** `maintenance-reminders` whole-Check unavailable outcome 的稳定 reason code。 */
 export type MaintenanceRemindersUnavailableCode = (typeof WHOLE_CHECK_UNAVAILABLE_CODE)[keyof typeof WHOLE_CHECK_UNAVAILABLE_CODE];
 export type FirstParentHistoryUnavailableReason = typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON.firstParentHistoryInvalid | typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON.firstParentHistoryUnavailable | typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON.headInvalid | typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON.headUnavailable;
@@ -68,9 +74,9 @@ export type ReminderMeasurement = Readonly<{
     readonly value: ReminderEvaluation;
 }>;
 /**
- * 创建一个固定 ID 的普通 Check，并在其局部最终数据中评估多条维护提醒。
+ * 创建一个维护提醒普通 Check，并在其局部最终数据中评估多条维护提醒。
  *
- * @remarks 构造函数只接收项目无法可靠推断的提醒政策；它补齐 Git 可执行文件、身份、可见性和直接执行逻辑。返回值仍是普通 Check，可按现有原生对象组合规则替换完整 `options` 分支。
+ * @remarks 传入 entries 数组会保留默认 identity；对象输入可同时声明项目 Check 字段。构造函数补齐 Git 可执行文件、默认展示和直接执行逻辑，返回值仍是普通 Check，可按现有原生对象组合规则替换完整 `options` 分支。
  * @example 创建一个单一 Check 的维护提醒
  * ```ts
  * import { defineConfig, maintenanceReminders, run } from "@zxyycom/vibe-check";
@@ -106,6 +112,9 @@ export type ReminderMeasurement = Readonly<{
  * ```
  */
 export declare function maintenanceReminders(entries: readonly MaintenanceReminder[]): TypedCheckWithOptions<typeof MAINTENANCE_REMINDERS_CHECK_ID, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+export declare function maintenanceReminders(input: MaintenanceRemindersInput<typeof MAINTENANCE_REMINDERS_CHECK_ID>): TypedCheckWithOptions<typeof MAINTENANCE_REMINDERS_CHECK_ID, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+export declare function maintenanceReminders<const Id extends string>(input: MaintenanceRemindersInput<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+export declare function maintenanceReminders(input: MaintenanceRemindersInput): TypedCheckWithOptions<string, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
 /** 在普通对象组合后验证完整的选项形状。 */
 export declare function validMaintenanceReminderOptions(value: unknown): value is MaintenanceReminderOptions;
 export {};

package/types/package-checks/markdown-link-validation/default-check.d.ts

@@ -1,4 +1,5 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseMarkdownLinkValidationData } from "./final-data.ts";
 import type { MarkdownLinkValidationOptions, ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 /**
@@ -30,4 +31,6 @@ import type { MarkdownLinkValidationOptions, ResolvedMarkdownLinkValidationOptio
  * if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
  * ```
  */
-export declare function markdownLinkValidation(options?: MarkdownLinkValidationOptions): TypedCheckWithOptions<"markdown-link-validation", ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;
+export declare function markdownLinkValidation(options?: MarkdownLinkValidationOptions<"markdown-link-validation">): TypedCheckWithOptions<"markdown-link-validation", ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;
+export declare function markdownLinkValidation<const Id extends string>(options: MarkdownLinkValidationOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;
+export declare function markdownLinkValidation(options: MarkdownLinkValidationOptions): TypedCheckWithOptions<string, ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;

package/types/package-checks/markdown-link-validation/options.d.ts

@@ -1,13 +1,10 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { LocalCacheOptions } from "../local-cache-options.ts";
 export type MarkdownRootExternalTargetMode = "ignore" | "report" | "validate";
 /** 调用方显式拥有的 Link-private parse-facts local cache policy。 */
-type MarkdownLinkValidationCacheOptions = Readonly<{
-    readonly enabled: false;
-}> | Readonly<{
-    readonly enabled: true;
-    readonly directory: string;
-}>;
+type MarkdownLinkValidationCacheOptions = LocalCacheOptions;
 /** 可省略的 Markdown validation work limits。 */
 export interface MarkdownLinkValidationLimitOptions {
     readonly maxMarkdownBytes?: number;
@@ -15,7 +12,7 @@ export interface MarkdownLinkValidationLimitOptions {
     readonly maxTargetReads?: number;
 }
 /** `markdownLinkValidation(options?)` 接受的可省略 authoring policy。 */
-export interface MarkdownLinkValidationOptions {
+export interface MarkdownLinkValidationOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
     /** 参与本 Check 的 Markdown source selection；省略字段使用 package defaults。 */
     readonly files?: ProjectFileSelectionOptions;
     /** local-reference finding 是否使本 Check failed；省略时为 non-blocking。 */

package/types/package-checks/markdown-lint/adapter.d.ts

@@ -0,0 +1,10 @@
+import { type MarkdownLintRuleName } from "./options.ts";
+export interface MarkdownLintBackendFinding {
+    readonly lineNumber: number;
+    readonly range: readonly [number, number] | null;
+    readonly rule: MarkdownLintRuleName;
+}
+/** Runs the fixed markdownlint Promise strings API and validates its raw protocol. */
+export declare function lintMarkdownString(sourcePath: string, sourceText: string, rules: readonly MarkdownLintRuleName[]): Promise<readonly MarkdownLintBackendFinding[] | "backend-failed" | "backend-protocol-invalid">;
+/** Validates one backend or restored-cache range against the current source line. */
+export declare function parseMarkdownLintRange(value: unknown, line: string): readonly [number, number] | null | undefined;

package/types/package-checks/markdown-lint/default-check.d.ts

@@ -0,0 +1,37 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
+import { parseMarkdownLintData } from "./final-data.ts";
+import type { MarkdownLintOptions, ResolvedMarkdownLintOptions } from "./options.ts";
+/**
+ * 构造使用稳定闭合规则与受限输入的 Markdown 结构检查。
+ * 精确 findingWaivers 只在完整 traversal 后应用；原 Finding、计数与缓存 facts 保留。
+ *
+ * @param options - 省略时采用八项 recommended 规则；非空 rules 数组完整替换该集合。
+ * @returns 使用默认或指定 checkId 的 typed Check，携带完整冻结 options、parser 与执行逻辑。
+ * @throws {TypeError} options 含未知字段、未知/重复规则、非法 limits 或 findingWaivers 时抛出。
+ * @example 最小用法
+ * ```ts
+ * import { defineConfig, markdownLint, run } from "@zxyycom/vibe-check";
+ *
+ * const check = markdownLint({ findingPolicy: "blocking" });
+ * const definition = defineConfig({
+ *   checks: [check],
+ *   outputs: {
+ *     diagnosticLogging: { enabled: false },
+ *     machinePublication: { enabled: false },
+ *     progressRendering: { enabled: false }
+ *   }
+ * });
+ *
+ * const result = await run(definition);
+ * if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+ * const outcome = result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome;
+ * if (outcome?.status !== "passed" && outcome?.status !== "not-applicable") {
+ *   throw new Error(`Markdown lint did not pass: ${outcome?.status ?? "no outcome"}`);
+ * }
+ * if (outcome.status === "not-applicable") console.warn("No Markdown input selected; no lint evidence.");
+ * ```
+ */
+export declare function markdownLint(options?: MarkdownLintOptions<"markdown-lint">): TypedCheckWithOptions<"markdown-lint", ResolvedMarkdownLintOptions, typeof parseMarkdownLintData>;
+export declare function markdownLint<const Id extends string>(options: MarkdownLintOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedMarkdownLintOptions, typeof parseMarkdownLintData>;
+export declare function markdownLint(options: MarkdownLintOptions): TypedCheckWithOptions<string, ResolvedMarkdownLintOptions, typeof parseMarkdownLintData>;

package/types/package-checks/markdown-lint/execution.d.ts

@@ -0,0 +1,24 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import type { MarkdownLintFinalData } from "./final-data.ts";
+import type { ResolvedMarkdownLintOptions } from "./options.ts";
+import { type MarkdownLintRecordCandidate } from "./records.ts";
+import { type MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+export type { MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+export declare const MARKDOWN_LINT_CHECK_DEFINITION: {
+    readonly checkId: "markdown-lint";
+    readonly displayName: "Markdown lint";
+};
+type Traversal = Readonly<{
+    readonly kind: "complete";
+    readonly candidates: readonly MarkdownLintRecordCandidate[];
+    readonly sourceFileCount: number;
+}> | Readonly<{
+    readonly kind: "unavailable";
+    readonly reason: MarkdownLintUnavailableReason;
+}>;
+/** Executes one bounded, ordered lint pass over the exact selected Markdown source paths. */
+export declare function executeMarkdownLint(context: CheckExecutionContext<ResolvedMarkdownLintOptions>): Promise<CheckResult<MarkdownLintFinalData>>;
+/** Reconciles only a complete traversal, then publishes all evidence and the live policy outcome. */
+export declare function publishMarkdownLintTraversal(context: CheckExecutionContext<ResolvedMarkdownLintOptions>, traversal: Extract<Traversal, {
+    readonly kind: "complete";
+}>, rejectedPaths: readonly string[]): CheckResult<MarkdownLintFinalData>;

package/types/package-checks/markdown-lint/final-data.d.ts

@@ -0,0 +1,8 @@
+/** 已完成 `markdownLint` execution 的 canonical final data。 */
+export interface MarkdownLintFinalData {
+    readonly sourceFileCount: number;
+    readonly findingCount: number;
+    readonly rejectedInputCount: number;
+}
+/** 解析并验证 `markdownLint` 完成结果中的 canonical final data。 */
+export declare function parseMarkdownLintData(data: unknown): MarkdownLintFinalData;

package/types/package-checks/markdown-lint/finding-messages.d.ts

@@ -0,0 +1,6 @@
+import type { CheckMessage } from "../../check/check.ts";
+import type { FindingWaiverReconciliation } from "../../package-tools/finding-waivers/reconciliation.ts";
+import { type MarkdownLintRecordCandidate } from "./records.ts";
+export declare function markdownLintFindingMessages(candidates: readonly MarkdownLintRecordCandidate[], rejectedPaths: readonly string[], blocking: boolean): readonly CheckMessage[];
+/** Explains every configured waiver without turning accepted findings into error messages. */
+export declare function markdownLintWaiverMessages(reconciliation: FindingWaiverReconciliation<MarkdownLintRecordCandidate>): readonly CheckMessage[];

package/types/package-checks/markdown-lint/finding-waiver-identity.d.ts

@@ -0,0 +1,3 @@
+import { type MarkdownLintFindingIdentity } from "./options.ts";
+/** Validates and detaches the complete public location used for exact waiver matching. */
+export declare function resolveMarkdownLintFindingIdentity(value: unknown): MarkdownLintFindingIdentity | undefined;

package/types/package-checks/markdown-lint/findings-cache.d.ts

@@ -0,0 +1,17 @@
+import { type MarkdownLintBackendFinding } from "./adapter.ts";
+import { type MarkdownLintCacheOptions, type MarkdownLintRuleName } from "./options.ts";
+import type { MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+type MarkdownLintCacheInput = Readonly<{
+    readonly sourcePath: string;
+    readonly sourceText: string;
+    readonly rules: readonly MarkdownLintRuleName[];
+    readonly cache: MarkdownLintCacheOptions;
+    readonly signal: AbortSignal;
+}>;
+export type MarkdownLintFactsResult = Readonly<{
+    readonly findings: readonly MarkdownLintBackendFinding[];
+    readonly source: "cache" | "computed" | "uncached";
+}> | MarkdownLintUnavailableReason;
+/** Reuses only validated per-source findings; all source reads and Check settlement remain live. */
+export declare function lintMarkdownWithCache(input: MarkdownLintCacheInput): Promise<MarkdownLintFactsResult>;
+export {};

package/types/package-checks/markdown-lint/options-resolution.d.ts

@@ -0,0 +1,3 @@
+import { type ResolvedMarkdownLintOptions } from "./options.ts";
+/** Resolves closed partial authoring options into an immutable complete policy. */
+export declare function resolveMarkdownLintOptions(value: unknown): ResolvedMarkdownLintOptions | undefined;

package/types/package-checks/markdown-lint/options-validation.d.ts

@@ -0,0 +1,2 @@
+import { type ResolvedMarkdownLintOptions } from "./options.ts";
+export declare function validMarkdownLintOptions(value: unknown): value is ResolvedMarkdownLintOptions;

package/types/package-checks/markdown-lint/options.d.ts

@@ -0,0 +1,65 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
+import type { LocalCacheOptions } from "../local-cache-options.ts";
+import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
+import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
+/** 由 Product 拥有且独立于 backend 名称的闭合 Markdown lint 规则目录。 */
+export declare const MARKDOWN_LINT_RULE_NAMES: readonly ["heading-increment", "no-reversed-links", "no-missing-space-atx", "fenced-code-language", "no-empty-links", "no-alt-text", "link-fragments", "reference-links-images", "table-column-count"];
+/** `markdownLint` 支持的稳定 Product-owned 规则名称。 */
+export type MarkdownLintRuleName = (typeof MARKDOWN_LINT_RULE_NAMES)[number];
+/** 可直接从 lint Record 复制的精确身份；完整 range 相同的多个 Finding 不可唯一豁免。 */
+export interface MarkdownLintFindingIdentity {
+    /** 规范化的 project-root-relative `/` 路径。 */
+    readonly path: string;
+    /** 闭合 Product catalog 中的规则名称。 */
+    readonly rule: MarkdownLintRuleName;
+    /** 一基 UTF-16 正安全整数位置；必须同行，end-exclusive column 不小于 start column。 */
+    readonly range: Readonly<{
+        readonly start: Readonly<{
+            readonly line: number;
+            readonly column: number;
+        }>;
+        readonly end: Readonly<{
+            readonly line: number;
+            readonly column: number;
+        }>;
+    }>;
+}
+/** 完整 traversal 后唯一匹配才应用的精确豁免；reason 会公开发布，不得包含秘密。 */
+export type MarkdownLintFindingWaiver = FindingWaiver<MarkdownLintFindingIdentity>;
+/** `markdownLint(options?)` 可接受的可省略 work limits。 */
+export interface MarkdownLintLimitOptions {
+    /** 单个 accepted Markdown source 的 UTF-8 字节上限。 */
+    readonly maxMarkdownBytes?: number;
+    /** 一次完整 traversal 中可积累的 lint finding 上限。 */
+    readonly maxFindings?: number;
+}
+/** 调用方拥有的逐文件 lint findings 本地缓存；省略时关闭。 */
+export type MarkdownLintCacheOptions = LocalCacheOptions;
+/** `markdownLint(options?)` 可接受的闭合 authoring policy。 */
+export interface MarkdownLintOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
+    /** 参与本 Check 的 source selection；省略时使用 package defaults。 */
+    readonly files?: ProjectFileSelectionOptions;
+    /** 未豁免 lint finding 是否使本 Check failed；省略时为 non-blocking。 */
+    readonly findingPolicy?: FindingPolicy;
+    /** 闭合的精确 Finding 豁免；保留原始证据，不改变输入、limits 或缓存 facts。 */
+    readonly findingWaivers?: readonly MarkdownLintFindingWaiver[];
+    /** 非空数组完整替换 recommended rule set。 */
+    readonly rules?: readonly MarkdownLintRuleName[];
+    /** 每次 execution 的 Markdown 内容与 finding work 上限。 */
+    readonly limits?: MarkdownLintLimitOptions;
+    /** 可删除、可信 absolute directory；只缓存由当前 bytes 和规则计算的逐文件 findings。 */
+    readonly cache?: MarkdownLintCacheOptions;
+}
+/** `markdown-lint` execution 消费的完整冻结 policy。 */
+export interface ResolvedMarkdownLintOptions {
+    readonly files: ProjectFileSelection;
+    readonly findingPolicy: FindingPolicy;
+    readonly findingWaivers: readonly MarkdownLintFindingWaiver[];
+    readonly rules: readonly MarkdownLintRuleName[];
+    readonly cache: MarkdownLintCacheOptions;
+    readonly limits: Readonly<{
+        readonly maxMarkdownBytes: number;
+        readonly maxFindings: number;
+    }>;
+}

package/types/package-checks/markdown-lint/records.d.ts

@@ -0,0 +1,39 @@
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
+import { type FindingWaiverAuditRecordData, type FindingWaiverRecordAudit } from "../code-quality-findings/finding-waiver-evidence.ts";
+import type { MarkdownLintBackendFinding } from "./adapter.ts";
+import type { MarkdownLintFindingIdentity, MarkdownLintRuleName } from "./options.ts";
+/** 一条保留原位置的 lint Finding；唯一命中 waiver 时仅附加公开理由。 */
+export type MarkdownLintFindingRecordData = Readonly<MarkdownLintFindingIdentity & {
+    readonly kind: "lint-finding";
+    readonly waiver?: Readonly<{
+        readonly reason: string;
+    }>;
+}>;
+/** 未使用或匹配多个 Markdown lint Findings 的精确 waiver audit Record data。 */
+export type MarkdownLintFindingWaiverAuditRecordData = FindingWaiverAuditRecordData<MarkdownLintFindingIdentity>;
+export type MarkdownLintInputRejectedRecordData = Readonly<{
+    readonly kind: "input-rejected";
+    readonly blocking: false;
+    readonly path: string;
+    readonly reason: "unsupported-file-type";
+}>;
+/** Markdown lint 发布的 Finding、input-rejection 或 finding-waiver audit Record data。 */
+export type MarkdownLintRecordData = MarkdownLintFindingRecordData | MarkdownLintInputRejectedRecordData | MarkdownLintFindingWaiverAuditRecordData;
+export interface MarkdownLintRecordCandidate {
+    readonly id: string;
+    readonly data: MarkdownLintFindingRecordData;
+}
+export declare function markdownLintFindingIdentity(candidate: MarkdownLintRecordCandidate): MarkdownLintFindingIdentity;
+export declare function markdownLintWaiverIdentity(waiver: MaterializedFindingWaiver): MarkdownLintFindingIdentity;
+export declare function markdownLintWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
+    readonly id: string;
+    readonly data: MarkdownLintFindingWaiverAuditRecordData;
+}>;
+export declare function orderedMarkdownLintCandidates(values: readonly Readonly<{
+    readonly path: string;
+    readonly finding: MarkdownLintBackendFinding;
+}>[], catalog: readonly MarkdownLintRuleName[]): readonly MarkdownLintRecordCandidate[];
+export declare function buildMarkdownLintInputRejectedRecord(path: string): Readonly<{
+    readonly id: string;
+    readonly data: MarkdownLintInputRejectedRecordData;
+}>;

package/types/package-checks/markdown-lint/unavailable-reasons.d.ts

@@ -0,0 +1,3 @@
+/** Markdown lint complete Check 的稳定 unavailable 原因。 */
+export type MarkdownLintUnavailableReason = "backend-failed" | "backend-protocol-invalid" | "cancelled" | "finding-limit-exceeded" | "invalid-options" | "project-root-unavailable" | "source-too-large" | "source-unavailable";
+export declare function markdownLintUnavailableMessage(reason: MarkdownLintUnavailableReason): string;

package/types/package-checks/secret-detection/default-check.d.ts

@@ -1,4 +1,5 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseSecretDetectionData } from "./final-data.ts";
 import type { ResolvedSecretDetectionOptions, SecretDetectionOptions } from "./options.ts";
 /**
@@ -8,4 +9,6 @@ import type { ResolvedSecretDetectionOptions, SecretDetectionOptions } from "./o
  * @returns 固定 `secret-detection` identity、完整冻结 options、final-data parser 与 execution。
  * @throws {TypeError} files 缺失、策略不完整或输入含未知字段时抛出。
  */
-export declare function secretDetection(options: SecretDetectionOptions): TypedCheckWithOptions<"secret-detection", ResolvedSecretDetectionOptions, typeof parseSecretDetectionData>;
+export declare function secretDetection(options: SecretDetectionOptions<"secret-detection">): TypedCheckWithOptions<"secret-detection", ResolvedSecretDetectionOptions, typeof parseSecretDetectionData>;
+export declare function secretDetection<const Id extends string>(options: SecretDetectionOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedSecretDetectionOptions, typeof parseSecretDetectionData>;
+export declare function secretDetection(options: SecretDetectionOptions): TypedCheckWithOptions<string, ResolvedSecretDetectionOptions, typeof parseSecretDetectionData>;

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

@@ -1,7 +1,8 @@
-import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 import type { ProjectFileSelection } from "../project-files/configuration.ts";
 /** `secretDetection(options)` 的明确 authoring policy。 */
-export interface SecretDetectionOptions {
+export interface SecretDetectionOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
     /** 必填的完整 project-file policy；只有它选中的 path 可以被读取或传给 detector。 */
     readonly files: ProjectFileSelection;
     /** 单个输入允许的最大 raw byte 数；超过时形成不可豁免的 coverage gap。 */

package/types/package-tools/admission-policy/define-admission-policy.d.ts

@@ -0,0 +1,26 @@
+import type { AdmissionPolicy, CustomAdmissionPreparationContext, CustomAdmissionStrategy, PreparedCustomAdmissionStrategy } from "../../project-definition/scheduler-policy.ts";
+type ExactAdmissionPolicy<T extends AdmissionPolicy> = T extends Readonly<{
+    readonly kind: "static";
+}> ? T & Record<Exclude<keyof T, "kind">, never> : T extends Readonly<{
+    readonly kind: "custom";
+}> ? T & Record<Exclude<keyof T, "kind" | "strategy">, never> & Readonly<{
+    readonly strategy: ExactCustomAdmissionStrategy<T["strategy"]>;
+}> : never;
+type ExactCustomAdmissionStrategy<T extends CustomAdmissionStrategy> = T extends Readonly<{
+    readonly kind: "simple";
+}> ? T & Record<Exclude<keyof T, "kind" | "decide">, never> : T extends Readonly<{
+    readonly kind: "prepared";
+}> ? T & Record<Exclude<keyof T, "kind" | "prepare">, never> & Readonly<{
+    readonly prepare: ExactCustomPreparation<T["prepare"]>;
+}> : never;
+type ExactCustomPreparation<T> = T extends (this: void, context: CustomAdmissionPreparationContext) => infer Result ? (this: void, context: CustomAdmissionPreparationContext) => ExactCustomPreparationResult<Result> : never;
+type ExactCustomPreparationResult<T> = T extends Promise<unknown> ? Promise<ExactPreparedCustomAdmissionStrategy<Awaited<T>>> : ExactPreparedCustomAdmissionStrategy<T>;
+type ExactPreparedCustomAdmissionStrategy<T> = T extends PreparedCustomAdmissionStrategy ? T & Record<Exclude<keyof T, "decide" | "terminalEffect">, never> : never;
+/**
+ * 保留 closed admission policy literal 的 TypeScript inference，不创建额外运行语义。
+ *
+ * @remarks inline policy 与此 helper 的结果完全等价。custom simple `decide` 同步运行；prepared
+ * strategy 为每个 graph-ready Run 解析独立 closure，调用方负责其 trusted host callback 的可重入性。
+ */
+export declare function defineAdmissionPolicy<const T extends AdmissionPolicy>(policy: ExactAdmissionPolicy<T>): T;
+export {};

package/types/{check → package-tools/finding-presentation}/finding-presentation.d.ts

@@ -1,4 +1,5 @@
-import type { CheckMessage, CheckResult } from "./check.ts";
+import type { CheckResult } from "../../check/check.ts";
+type CheckMessage = NonNullable<CheckResult["messages"]>[number];
 /**
  * 将 Check-owned Finding 投影为有界 terminal messages 所需的超限上下文。
  * 完整 Finding facts 与深入查看位置继续由调用方拥有。
@@ -23,3 +24,4 @@ export declare function presentCheckFindings<Finding>(input: {
 }): 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>;
+export {};

package/types/{finding-waivers → package-tools/finding-waivers}/reconciliation.d.ts

@@ -1,4 +1,4 @@
-import { type CanonicalJsonValue } from "../data-boundary/canonical-data.ts";
+import { type CanonicalJsonValue } from "../../data-boundary/canonical-data.ts";
 /** 由采用方声明、用于匹配一个 finding 的语义身份与豁免理由。 */
 export interface FindingWaiver<Identity> {
     /** 调用方定义的稳定 finding 身份；匹配时按 canonical JSON 结构比较。 */
@@ -47,8 +47,8 @@ export interface ReconcileFindingWaiversOptions<Finding, Identity> {
     readonly findings: readonly Finding[];
     /** 从完整 finding 提取调用方选择的稳定语义身份。 */
     readonly identify: (finding: Finding) => Identity;
-    /** 要与识别器输出进行 canonical structural matching 的 waiver。 */
-    readonly waivers: readonly FindingWaiver<Identity>[];
+    /** 要对账的 waiver；省略或 undefined 等同于空数组，仍验证全部 finding identity。 */
+    readonly waivers?: readonly FindingWaiver<Identity>[] | undefined;
 }
 /** 独立 waiver reconciliation 的完整输出，保留 finding 处置和每项配置审计。 */
 export interface FindingWaiverReconciliation<Finding> {

package/types/{learned-critical-path → package-tools/learned-critical-path}/duration-model/prediction.d.ts

@@ -1,4 +1,4 @@
-import { type CanonicalJsonValue } from "../../data-boundary/canonical-data.ts";
+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 {
@@ -27,6 +27,6 @@ export declare function createSchedulerHistoryIdentity(input: {
     readonly checkId: string;
     readonly flags: CanonicalJsonValue;
 }): string;
-/** Forms learned means first, then one project median prior, without invoking preflight. */
+/** Forms learned means first, then one project median prior, without invoking preparation. */
 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 → package-tools/learned-critical-path}/duration-model/preparation.d.ts

@@ -1,4 +1,4 @@
-import type { SchedulerMeasurementContext } from "../../project-definition/project-definition.ts";
+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";

package/types/{learned-critical-path → package-tools/learned-critical-path}/duration-model/recording.d.ts

@@ -1,4 +1,4 @@
-import type { SchedulerRawMeasurement } from "../../project-definition/project-definition.ts";
+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<{

package/types/{learned-critical-path → package-tools/learned-critical-path}/selection-layers.d.ts

@@ -1,4 +1,4 @@
-import type { AdmissionPolicyContext, SchedulerGraphSnapshot } from "../project-definition/project-definition.ts";
+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];

package/types/{learned-critical-path → package-tools/learned-critical-path}/static-decision.d.ts

@@ -1,3 +1,3 @@
-import type { AdmissionPolicyContext, AdmissionProposal } from "../project-definition/project-definition.ts";
+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 → package-tools/learned-critical-path}/strategy.d.ts

@@ -1,4 +1,4 @@
-import type { CustomAdmissionStrategy, SchedulerGraphSnapshot } from "../project-definition/project-definition.ts";
+import type { CustomAdmissionStrategy, SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
 /** 公开 learned critical-path prepared strategy 的调用方配置。 */
 export interface LearnedCriticalPathStrategyOptions {
     /** 调用方拥有的可丢弃 learned duration history 本地目录；必须是绝对路径。 */

package/types/project-definition/check-tree/authoring.d.ts

@@ -1,4 +1,5 @@
 import type { CheckDescriptor } from "../../check/descriptor.ts";
+import { type HandoffProviderIdentity } from "../../check/handoff-provider-identity.ts";
 import { type ParsedCheckFields, type ParsedCheckFieldPrelude, type TrustedDataParser } from "./check-fields-authoring.ts";
 import { type ParsedCheckCollection } from "./scheduling-authoring.ts";
 import type { ResourceUnitMapping } from "../resource-unit-mapping.ts";
@@ -11,7 +12,8 @@ export interface ParsedCheck {
     readonly dependsOn: ParsedCheckCollection | undefined;
     readonly displayName: string;
     readonly enabledByFlags: ParsedCheckFieldPrelude["enabledByFlags"];
-    readonly execution: ParsedCheckFieldPrelude["execution"];
+    readonly execute: ParsedCheckFieldPrelude["execute"];
+    readonly handoff: HandoffProviderIdentity | null;
     readonly maxParallel: number | undefined;
     readonly mutex: ParsedCheckCollection | undefined;
     readonly observes: ParsedCheckCollection | undefined;
@@ -19,8 +21,8 @@ export interface ParsedCheck {
     readonly options: object | null;
     readonly path: string;
     readonly parseData: TrustedDataParser | null;
-    readonly preflight: ParsedCheckFieldPrelude["preflight"];
-    readonly visibility: ParsedCheckFields["visibility"];
+    readonly prepare: ParsedCheckFieldPrelude["prepare"];
+    readonly omitQuietPassedRow: ParsedCheckFields["omitQuietPassedRow"];
 }
 export interface ParsedCheckTree {
     readonly checks: readonly ParsedCheck[];