@zxyycom/vibe-check 0.0.1 → 0.0.2

package/types/package-checks/project-files/public-collection.d.ts

@@ -0,0 +1,16 @@
+/** Public validation and immutable snapshot boundary for one project-file selection. */
+import type { ProjectFileSelection } from "./configuration.ts";
+/** 调用方请求一次项目文件收集时必须完整提供的 root 与 selection。 */
+export interface CollectProjectFilesOptions {
+    /** 显式 project root；relative path 相对当前工作目录解析，不能为空或含 U+0000。 */
+    readonly projectRoot: string;
+    /** 完整的显式 selection；本工具不推断任何 Check 默认值。 */
+    readonly selection: ProjectFileSelection;
+}
+/**
+ * 按一份完整的显式 selection 同步收集 project-root-relative slash paths。
+ *
+ * 成功结果是冻结的稳定去重排序快照，空数组表示没有匹配路径。非法参数同步抛出
+ * `TypeError`；选定 filesystem 或 Git source 的收集失败继续抛出普通 `Error`，不会回退来源。
+ */
+export declare function collectProjectFiles(authoredOptions: CollectProjectFilesOptions): readonly string[];

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

@@ -0,0 +1,12 @@
+/** A bounded, non-secret classification result for one explicitly selected file. */
+export type SecretDetectionInputClassification = Readonly<{
+    readonly kind: "coverage-gap";
+    readonly reason: SecretDetectionCoverageGapReason;
+} | {
+    readonly content: string;
+    readonly kind: "text";
+}>;
+/** Deterministic reasons why an explicitly selected file did not receive detector coverage. */
+export type SecretDetectionCoverageGapReason = "contains-nul" | "file-count-limit" | "file-byte-limit" | "invalid-utf8" | "total-byte-limit";
+/** Classifies already-read bytes without retaining or publishing their content on non-text branches. */
+export declare function classifySecretDetectionBytes(bytes: Uint8Array, maximumFileBytes: number): SecretDetectionInputClassification;

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

@@ -0,0 +1,11 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { parseSecretDetectionData } from "./final-data.ts";
+import type { ResolvedSecretDetectionOptions, SecretDetectionOptions } from "./options.ts";
+/**
+ * 构造只检查其必填、显式 `files` policy 所选择输入的 high-confidence secret Check。
+ *
+ * @param options - 必须声明完整 `files`；limits 和 finding waivers 使用本 Check 的固定安全策略。
+ * @returns 固定 `secret-detection` identity、完整冻结 options、final-data parser 与 execution。
+ * @throws {TypeError} files 缺失、策略不完整或输入含未知字段时抛出。
+ */
+export declare function secretDetection(options: SecretDetectionOptions): TypedCheckWithOptions<"secret-detection", ResolvedSecretDetectionOptions, typeof parseSecretDetectionData>;

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

@@ -0,0 +1,14 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import type { SecretDetectionFinalData } from "./final-data.ts";
+import { type SecretCoverageGap } from "./input-preparation.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+import { type SecretDetectionIssue } from "./secretlint/adapter.ts";
+export declare const SECRET_DETECTION_CHECK_DEFINITION: {
+    readonly checkId: "secret-detection";
+    readonly displayName: "Secret detection";
+};
+/** `secretDetection` 的 whole-Check unavailable reason；不携带 detector 或 file-system 原始详情。 */
+export type SecretDetectionUnavailableReasonCode = "detector-protocol-failed" | "detector-unavailable" | "execution-cancelled" | "invalid-options" | "scan-input-unavailable" | "source-unavailable";
+/** Executes the fixed in-process detector only for this Check's exact explicit input selection. */
+export declare function executeSecretDetection(context: CheckExecutionContext<ResolvedSecretDetectionOptions>): Promise<CheckResult<SecretDetectionFinalData>>;
+export declare function settleSecretDetectionFindings(context: CheckExecutionContext<ResolvedSecretDetectionOptions>, selectedFileCount: number, issues: readonly SecretDetectionIssue[], coverageGaps: readonly SecretCoverageGap[]): CheckResult<SecretDetectionFinalData>;

package/types/package-checks/secret-detection/final-data.d.ts

@@ -0,0 +1,15 @@
+/** `secretDetection` 正常完成时发布的安全计数。 */
+export interface SecretDetectionFinalData {
+    /** 已选择但未获得 bounded detector coverage 的文件数。 */
+    readonly coverageGapCount: number;
+    /** 所有安全投影后的 detector finding 数，包括已 waived 的 finding。 */
+    readonly findingCount: number;
+    /** 已获得 bounded text detector coverage 的文件数。 */
+    readonly scannedFileCount: number;
+    /** files policy 的 exact selection 数，恒等于 scannedFileCount 与 coverageGapCount 之和。 */
+    readonly selectedFileCount: number;
+    /** 安全 identity 被唯一 waiver 匹配的 finding 数。 */
+    readonly waivedFindingCount: number;
+}
+/** 验证并脱离一份 `secretDetection` canonical final-data object。 */
+export declare function parseSecretDetectionData(data: unknown): SecretDetectionFinalData;

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

@@ -0,0 +1,5 @@
+import type { SecretDetectionFindingIdentity } from "./options.ts";
+/** 解析只含安全路径、规则、结构标记和 occurrence ordinal 的 waiver identity。 */
+export declare function resolveSecretDetectionFindingIdentity(value: unknown): SecretDetectionFindingIdentity | undefined;
+export declare const secretDetectionPrivateKeyRuleId: "@secretlint/secretlint-rule-privatekey";
+export declare const secretDetectionTextDocumentStructuralClass: "text-document";

package/types/package-checks/secret-detection/input-preparation.d.ts

@@ -0,0 +1,24 @@
+import type { CheckExecutionContext } from "../../check/check.ts";
+import { type SecretDetectionCoverageGapReason } from "./classification.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+/** Private, already-classified text passed to this Check's private detector adapter. */
+export interface ApprovedTextInput {
+    readonly content: string;
+    readonly path: string;
+}
+/** A safe explanation for an exact selected input that did not receive detector coverage. */
+export interface SecretCoverageGap {
+    readonly path: string;
+    readonly reason: SecretDetectionCoverageGapReason;
+}
+export type PreparedSecretDetectionInputs = Readonly<{
+    readonly kind: "cancelled";
+} | {
+    readonly kind: "unavailable";
+} | {
+    readonly coverageGaps: readonly SecretCoverageGap[];
+    readonly inputs: readonly ApprovedTextInput[];
+    readonly kind: "complete";
+}>;
+/** Reads and classifies the already-selected paths before the detector can receive text. */
+export declare function prepareSecretDetectionInputs(context: CheckExecutionContext<ResolvedSecretDetectionOptions>, selectedPaths: readonly string[]): PreparedSecretDetectionInputs;

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

@@ -0,0 +1,6 @@
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+export declare const DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_BYTES = 1048576;
+export declare const DEFAULT_SECRET_DETECTION_MAXIMUM_TOTAL_BYTES = 8388608;
+export declare const DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_COUNT = 2048;
+/** 将 required exact file policy 和有限资源策略物化为完整、冻结 options。 */
+export declare function resolveSecretDetectionOptions(value: unknown): ResolvedSecretDetectionOptions | undefined;

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

@@ -0,0 +1,3 @@
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+/** Guards prepared options before a Run invokes a detector. */
+export declare function validSecretDetectionOptions(value: unknown): value is ResolvedSecretDetectionOptions;

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

@@ -0,0 +1,32 @@
+import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { ProjectFileSelection } from "../project-files/configuration.ts";
+/** `secretDetection(options)` 的明确 authoring policy。 */
+export interface SecretDetectionOptions {
+    /** 必填的完整 project-file policy；只有它选中的 path 可以被读取或传给 detector。 */
+    readonly files: ProjectFileSelection;
+    /** 单个输入允许的最大 raw byte 数；超过时形成不可豁免的 coverage gap。 */
+    readonly maximumFileBytes?: number;
+    /** 一次 invocation 中允许读取和检测的累计 raw byte 数；超过时形成 coverage gap。 */
+    readonly maximumTotalBytes?: number;
+    /** 一次 invocation 中允许处理的 selected file 数；超过时形成 coverage gap。 */
+    readonly maximumFileCount?: number;
+    /** 对安全 finding identity 的精确、可审计误报豁免。 */
+    readonly findingWaivers?: readonly FindingWaiver<SecretDetectionFindingIdentity>[];
+}
+/** 不含 raw value、message、hash 或 location 的 secret finding 身份。 */
+export interface SecretDetectionFindingIdentity {
+    readonly ordinal: number;
+    readonly path: string;
+    readonly ruleId: "@secretlint/secretlint-rule-privatekey";
+    readonly structuralClass: "text-document";
+}
+/** `secretDetection` execution 消费的完整冻结 options。 */
+export interface ResolvedSecretDetectionOptions {
+    readonly files: ProjectFileSelection;
+    readonly findingWaivers: readonly FindingWaiver<SecretDetectionFindingIdentity>[];
+    readonly maximumFileBytes: number;
+    readonly maximumFileCount: number;
+    readonly maximumTotalBytes: number;
+}
+/** `findingWaivers` 的 public authoring alias。 */
+export type SecretDetectionFindingWaiver = FindingWaiver<SecretDetectionFindingIdentity>;

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

@@ -0,0 +1,35 @@
+import type { FindingWaiverRecordAudit, FindingWaiverAuditRecordData } from "../code-quality-findings/finding-waiver-evidence.ts";
+import type { SecretDetectionCoverageGapReason } from "./classification.ts";
+import type { SecretDetectionIssue } from "./secretlint/adapter.ts";
+import type { SecretDetectionFindingIdentity } from "./options.ts";
+/** An actionable or waived high-confidence secret finding. No detector value or message is retained. */
+export interface SecretDetectionFindingRecordData {
+    readonly blocking: boolean;
+    readonly kind: "secret-finding";
+    readonly location: SecretDetectionIssue["location"];
+    readonly ordinal: number;
+    readonly path: string;
+    readonly ruleId: "@secretlint/secretlint-rule-privatekey";
+    readonly structuralClass: "text-document";
+    readonly waiver?: Readonly<{
+        readonly reason: string;
+    }>;
+}
+/** A deterministic exact-input coverage gap. It is never reconciled through finding waiver policy. */
+export interface SecretDetectionCoverageGapRecordData {
+    readonly blocking: true;
+    readonly kind: "coverage-gap";
+    readonly path: string;
+    readonly reason: SecretDetectionCoverageGapReason;
+}
+/** Unused or overmatched safe secret finding waiver evidence. */
+export type SecretDetectionFindingWaiverAuditRecordData = FindingWaiverAuditRecordData<SecretDetectionFindingIdentity>;
+/** `secretDetection` 发布的全部补充 Record data。 */
+export type SecretDetectionRecordData = SecretDetectionCoverageGapRecordData | SecretDetectionFindingRecordData | SecretDetectionFindingWaiverAuditRecordData;
+export declare function secretFindingIdentity(issue: SecretDetectionIssue): SecretDetectionFindingIdentity;
+export declare function secretFindingRecordId(identity: SecretDetectionFindingIdentity): string;
+export declare function secretCoverageGapRecordId(path: string): string;
+export declare function secretDetectionWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
+    readonly data: SecretDetectionFindingWaiverAuditRecordData;
+    readonly id: string;
+}>;

package/types/package-checks/secret-detection/secretlint/adapter.d.ts

@@ -0,0 +1,28 @@
+/** The only detector result shape allowed to leave this private adapter. */
+export interface SecretDetectionIssue {
+    readonly location: Readonly<{
+        readonly endColumn: number;
+        readonly endLine: number;
+        readonly startColumn: number;
+        readonly startLine: number;
+    }>;
+    readonly ordinal: number;
+    readonly path: string;
+    readonly ruleId: "@secretlint/secretlint-rule-privatekey";
+    readonly structuralClass: "text-document";
+}
+export type SecretlintDetectionResult = Readonly<{
+    readonly issues: readonly SecretDetectionIssue[];
+    readonly kind: "complete";
+} | {
+    readonly kind: "protocol-failed";
+} | {
+    readonly kind: "unavailable";
+}>;
+/**
+ * Runs the fixed local Secretlint rule set against already-approved in-memory text.
+ * Third-party result, message text, data, error, and source content never leave this module.
+ */
+export declare function detectSecretlintIssues(content: string, projectRelativePath: string): Promise<SecretlintDetectionResult>;
+/** Converts only allowlisted Secretlint message fields to the safe Check-local issue DTO. */
+export declare function adaptSecretlintMessages(messages: unknown, projectRelativePath: string): SecretlintDetectionResult;

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

@@ -1,28 +1,26 @@
 import type { CheckDescriptor } from "../../check/descriptor.ts";
-import { type CheckVisibility, type CheckExecution, type CheckPreflight } from "../../check/check.ts";
-type TrustedDataParser = (this: void, ...parameters: never[]) => unknown;
-export type ParsedCheckCollection = Readonly<{
-    readonly kind: "exact";
-    readonly values: readonly string[];
-} | {
-    readonly kind: "inherit";
-    readonly add: readonly string[];
-    readonly remove: readonly string[];
-}>;
+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";
+export type { ParsedCheckCollection } from "./scheduling-authoring.ts";
 export interface ParsedCheck {
+    readonly admissionPriority: number | undefined;
     readonly checkId: string;
     readonly checks: readonly ParsedCheck[];
     readonly definition: CheckDescriptor | null;
     readonly dependsOn: ParsedCheckCollection | undefined;
     readonly displayName: string;
-    readonly execution: CheckExecution | null;
+    readonly enabledByFlags: ParsedCheckFieldPrelude["enabledByFlags"];
+    readonly execution: ParsedCheckFieldPrelude["execution"];
     readonly maxParallel: number | undefined;
     readonly mutex: ParsedCheckCollection | undefined;
+    readonly observes: ParsedCheckCollection | undefined;
+    readonly resourceClaims: ResourceUnitMapping | undefined;
     readonly options: object | null;
     readonly path: string;
     readonly parseData: TrustedDataParser | null;
-    readonly preflight: CheckPreflight | null;
-    readonly visibility: CheckVisibility | null;
+    readonly preflight: ParsedCheckFieldPrelude["preflight"];
+    readonly visibility: ParsedCheckFields["visibility"];
 }
 export interface ParsedCheckTree {
     readonly checks: readonly ParsedCheck[];
@@ -38,4 +36,3 @@ export interface MeaninglessCheckWarning {
  * trusted project code, while every declarative field is copied and validated.
  */
 export declare function parseCheckTreeAuthoring(value: unknown): ParsedCheckTree | undefined;
-export {};

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

@@ -0,0 +1,25 @@
+import type { CheckDescriptor } from "../../check/descriptor.ts";
+import { type CheckVisibility, type CheckFlagEnablement, type CheckExecution, type CheckPreflight } from "../../check/check.ts";
+export type TrustedDataParser = (this: void, ...parameters: never[]) => unknown;
+export interface CheckAuthoringData extends Readonly<Record<string, unknown>> {
+    readonly checkId: string;
+    readonly displayName: string;
+}
+export interface ParsedCheckFields {
+    readonly definition: CheckDescriptor | null;
+    readonly enabledByFlags: CheckFlagEnablement | null;
+    readonly execution: CheckExecution | null;
+    readonly options: object | null;
+    readonly parseData: TrustedDataParser | null;
+    readonly preflight: CheckPreflight | null;
+    readonly visibility: CheckVisibility | null;
+}
+export interface ParsedCheckFieldPrelude {
+    readonly enabledByFlags: CheckFlagEnablement | null;
+    readonly execution: CheckExecution | null;
+    readonly parseData: TrustedDataParser | null;
+    readonly preflight: CheckPreflight | null;
+}
+export declare function parseCheckAuthoringData(value: unknown): CheckAuthoringData | undefined;
+export declare function parseCheckFieldPrelude(data: CheckAuthoringData): ParsedCheckFieldPrelude | undefined;
+export declare function parseCheckFields(data: CheckAuthoringData, prelude: ParsedCheckFieldPrelude): ParsedCheckFields | undefined;

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

@@ -0,0 +1,2 @@
+/** Snapshots one closed array as unique, non-empty authored identifiers. */
+export declare function parseUniqueIdentifiers(value: unknown): readonly string[] | undefined;

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

@@ -1,15 +1,20 @@
 import type { CheckDescriptor } from "../../check/descriptor.ts";
-import type { CheckExecution, CheckPreflight, CheckVisibility } from "../../check/check.ts";
+import type { CheckExecution, CheckFlagEnablement, CheckPreflight, CheckVisibility } from "../../check/check.ts";
 import { type MeaninglessCheckWarning, type ParsedCheckTree } from "./authoring.ts";
+import { type ResourceUnitMapping } from "../resource-unit-mapping.ts";
 export type { Check, InheritableCheckCollection } from "../../check/check.ts";
 export interface ResolvedCheckTreeLeaf {
+    readonly admissionPriority: number;
     readonly definition: CheckDescriptor;
     readonly dependsOn: readonly string[];
+    readonly enabledByFlags?: CheckFlagEnablement;
     readonly execution: CheckExecution;
     readonly maxParallel: number;
     readonly mutex: readonly string[];
+    readonly observes: readonly string[];
     readonly options: object;
     readonly preflight?: CheckPreflight;
+    readonly resourceClaims: ResourceUnitMapping;
     readonly visibility: CheckVisibility;
 }
 export interface ResolvedCheckTree {
@@ -21,5 +26,5 @@ export interface ResolvedCheckTree {
  * values to descendants; it never creates an execution dependency or output
  * hierarchy.
  */
-export declare function resolveCheckTree(value: unknown, rootMaxParallel: number): ResolvedCheckTree | undefined;
-export declare function resolveParsedCheckTree(parsed: ParsedCheckTree, rootMaxParallel: number): ResolvedCheckTree | undefined;
+export declare function resolveCheckTree(value: unknown, rootMaxParallel: number, resourceCapacities?: ResourceUnitMapping): ResolvedCheckTree | undefined;
+export declare function resolveParsedCheckTree(parsed: ParsedCheckTree, rootMaxParallel: number, resourceCapacities?: ResourceUnitMapping): ResolvedCheckTree | undefined;

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

@@ -0,0 +1,19 @@
+import { type ResourceUnitMapping } from "../resource-unit-mapping.ts";
+export type ParsedCheckCollection = Readonly<{
+    readonly kind: "exact";
+    readonly values: readonly string[];
+} | {
+    readonly kind: "inherit";
+    readonly add: readonly string[];
+    readonly remove: readonly string[];
+}>;
+export type ParsedCheckScheduling = Readonly<{
+    readonly admissionPriority: number | undefined;
+    readonly dependsOn: ParsedCheckCollection | undefined;
+    readonly maxParallel: number | undefined;
+    readonly mutex: ParsedCheckCollection | undefined;
+    readonly observes: ParsedCheckCollection | undefined;
+    readonly resourceClaims: ResourceUnitMapping | undefined;
+}>;
+/** Parses the closed relation, priority, and capacity fields for one authored Check. */
+export declare function parseCheckScheduling(data: Readonly<Record<string, unknown>>): ParsedCheckScheduling | undefined;

package/types/project-definition/declarative-snapshot.d.ts

@@ -0,0 +1,7 @@
+import type { DeclarativeProjectSnapshot, NormalizedCheck, ProjectDefinition } from "./project-definition.ts";
+/**
+ * Produces the immutable, callback-free Definition identity consumed by fingerprinting.
+ */
+export declare function createDeclarativeProjectSnapshot(definition: ProjectDefinition, checks: readonly NormalizedCheck[]): DeclarativeProjectSnapshot;
+/** Generates the stable SHA-256 fingerprint for one declarative Definition snapshot. */
+export declare function createDeclarativeFingerprint(snapshot: DeclarativeProjectSnapshot): string;

package/types/project-definition/output-defaults.d.ts

@@ -1,3 +1,4 @@
+import type { ProgressRenderingOutput, ResolvedProgressRenderingOutput } from "./progress-rendering-output.ts";
 /** Default Run-owned output values applied when a Project Definition omits an override. */
 export declare const DEFAULT_PROJECT_OUTPUTS: Readonly<{
     readonly machinePublication: Readonly<{
@@ -6,9 +7,15 @@ export declare const DEFAULT_PROJECT_OUTPUTS: Readonly<{
     }>;
     readonly progressRendering: Readonly<{
         enabled: true;
+        formatter: null;
+        messagePreviewLimit: 5;
+        recordPreviewLimit: 5;
+        textPreviewCodePointLimit: 240;
     }>;
     readonly diagnosticLogging: Readonly<{
         directory: ".log/vibe-check";
         enabled: false;
     }>;
 }>;
+/** Materializes compatible progress authoring into the single renderer-ready policy. */
+export declare function resolveProgressRenderingOutput(output: Partial<ProgressRenderingOutput>): ResolvedProgressRenderingOutput;

package/types/project-definition/output-validation.d.ts

@@ -1,3 +1,4 @@
 import type { ProjectOutputs } from "./project-definition.ts";
 export declare function parseOutputs(value: unknown): ProjectOutputs | undefined;
-export declare function isContainedRelativeDirectory(directory: string): boolean;
+/** Accepts trusted output targets without claiming filesystem containment. */
+export declare function isOutputDirectory(directory: string): boolean;

package/types/project-definition/progress-rendering-output.d.ts

@@ -0,0 +1,41 @@
+/** Progress formatter 只接收当前 selected preview 的默认正文，不接收 Check 或事实对象。 */
+export type ProgressPreviewFormatter = (this: void, context: Readonly<{
+    readonly kind: "record" | "message";
+    readonly text: string;
+    readonly maxCodePoints: number;
+}>) => string;
+/** 人读 progress rendering 的作者配置；省略 preview 字段时使用 Product 默认值。 */
+export interface ProgressRenderingOutput {
+    /** `false` 时不构造或写入 progress writer。 */
+    readonly enabled: boolean;
+    /** 每个 settled block 预览的 Record 数量；非负 safe integer，默认 `5`，`0` 只隐藏 detail。 */
+    readonly recordPreviewLimit?: number;
+    /** 每个 settled block 预览的 message 数量；非负 safe integer，默认 `5`，`0` 只隐藏 detail。 */
+    readonly messagePreviewLimit?: number;
+    /** 每条 preview 正文的 Unicode code point 上限；正 safe integer，默认 `240`。 */
+    readonly textPreviewCodePointLimit?: number;
+    /** `null` 或省略保持默认正文；函数返回文本仍由 Product escape 并限制长度。 */
+    readonly formatter?: ProgressPreviewFormatter | null;
+}
+/** 已补齐 defaults、可直接交给 progress renderer 的配置。 */
+export interface ResolvedProgressRenderingOutput {
+    readonly enabled: boolean;
+    readonly formatter: ProgressPreviewFormatter | null;
+    readonly messagePreviewLimit: number;
+    readonly recordPreviewLimit: number;
+    readonly textPreviewCodePointLimit: number;
+}
+/** Closed expectations shared with invocation diagnostics; never contains authored values. */
+export type ProgressRenderingFieldExpectation = "plain-data-object" | "boolean" | "function-or-null" | "non-negative-safe-integer" | "positive-safe-integer";
+type ProgressRenderingFieldsResult = Readonly<{
+    readonly ok: true;
+    readonly value: Partial<ProgressRenderingOutput>;
+} | {
+    readonly ok: false;
+    readonly key: string | null;
+    readonly reason: "unknown-key" | "invalid-value";
+    readonly expected?: ProgressRenderingFieldExpectation;
+}>;
+/** Parses the fields shared by Definition output and RunControls override grammar. */
+export declare function parseProgressRenderingFields(value: unknown): ProgressRenderingFieldsResult;
+export {};

package/types/project-definition/project-definition.d.ts

@@ -1,33 +1,50 @@
 import type { MeaninglessCheckWarning } from "./check-tree/authoring.ts";
 import type { CheckDescriptor } from "../check/descriptor.ts";
-import type { Check, CheckExecution, CheckPreflight, CheckVisibility } from "../check/check.ts";
+import type { Check, CheckExecution, CheckFlagEnablement, CheckPreflight, CheckResourceClaims, CheckVisibility } from "../check/check.ts";
+import type { ProgressRenderingOutput, ResolvedProgressRenderingOutput } from "./progress-rendering-output.ts";
+export { createDeclarativeFingerprint } from "./declarative-snapshot.ts";
 /** 一次 Project Run 的明确输出配置。 */
 export interface ProjectOutputs {
     /** `run.json` 与 `records.ndjson` publication。 */
     readonly machinePublication: Readonly<{
-        /** 相对目录以 project root 解析，默认 `artifacts/vibe-check`。 */
+        /** 相对目录从 project root 解析；绝对目录直接作为 target，默认 `artifacts/vibe-check`。 */
         readonly directory: string;
         /** `false` 时本次 Run 不发布 machine output。 */
         readonly enabled: boolean;
     }>;
-    /** 人读 progress rendering。 */
-    readonly progressRendering: Readonly<{
-        /** `false` 时不构造或写入 progress writer。 */
-        readonly enabled: boolean;
-    }>;
+    /** 人读 progress lifecycle 与 preview 配置。 */
+    readonly progressRendering: ProgressRenderingOutput;
     /** 仅供维护者读取的一次 invocation diagnostic log。 */
     readonly diagnosticLogging: Readonly<{
-        /** 相对目录以 project root 解析，默认 `.log/vibe-check`。 */
+        /** 相对目录从 project root 解析；绝对目录直接作为 target，默认 `.log/vibe-check`。 */
         readonly directory: string;
         /** `false` 时不创建 diagnostic writer 或 file。 */
         readonly enabled: boolean;
     }>;
 }
-/** 定义级的 Check 调度预算。 */
-export interface SchedulerPolicy {
-    readonly maxParallel: number;
+export type { ProgressPreviewFormatter, ProgressRenderingOutput, ResolvedProgressRenderingOutput } from "./progress-rendering-output.ts";
+/** 已解析的 Run outputs；只在 Product invocation 内部使用。 */
+export interface ResolvedProjectOutputs extends Omit<ProjectOutputs, "progressRendering"> {
+    readonly progressRendering: ResolvedProgressRenderingOutput;
 }
-/** 已补齐默认 outputs、可交给 run 执行的项目定义。 */
+/** callback-free Definition output 投影；仅供 declarative fingerprint 使用。 */
+export interface DeclarativeProjectOutputs extends Omit<ProjectOutputs, "progressRendering"> {
+    readonly progressRendering: Readonly<{
+        readonly enabled: boolean;
+        readonly formatter: "custom" | "default";
+        readonly messagePreviewLimit: number;
+        readonly recordPreviewLimit: number;
+        readonly textPreviewCodePointLimit: number;
+    }>;
+}
+export type { AdmissionPolicy, AdmissionPolicyContext, AdmissionPolicyMeasurement, AdmissionProposal, AdmissionCatalog, AdmissionGraph, AdmissionGraphInput, AdmissionInspection, AdmissionNonSelectableTask, AdmissionRejectionReason, AdmissionScopeLifecycle, AdmissionSelectionRejectionReason, AdmissionSelectionValidation, AdmissionSelectionValidationRejectionReason, AdmissionSettlementOutcome, AdmissionSettledTask, AdmissionState, AdmissionTransitionResult, CustomAdmissionPreparationContext, CustomAdmissionStrategy, PreparedCustomAdmissionStrategy, SchedulerDecisionMeasurementCumulative, SchedulerGraphSnapshot, SchedulerMeasurementActionObservation, SchedulerMeasurementActionObservationInterval, SchedulerMeasurementAdmission, SchedulerMeasurementContext, SchedulerMeasurementEffect, SchedulerMeasurementHook, SchedulerMeasurementIntervalContribution, SchedulerMeasurementPeakCounts, SchedulerMeasurementTiming, SchedulerMeasurementTimingFacts, SchedulerMeasurementTimingUnavailableReason, SchedulerPolicy, SchedulerRawMeasurement } from "./scheduler-policy.ts";
+import type { AdmissionPolicy, CustomAdmissionStrategy, CustomAdmissionPreparationContext, DeclarativeSchedulerPolicy, PreparedCustomAdmissionStrategy, SchedulerPolicy } from "./scheduler-policy.ts";
+/**
+ * `defineConfig(...)` 形成的可重复运行项目定义：声明检查内容、调度方式与默认输出。
+ *
+ * 本次 root、flags、signal、Check 产物与日志目标以及显式 aggregation 交给 `run` 的第二个参数；
+ * 其中的 output overrides 只改变当前调用，不修改这里的默认值。
+ */
 export interface ProjectDefinition {
     readonly apiVersion: "1";
     readonly checks: readonly Check[];
@@ -59,11 +76,15 @@ export type ProjectDefinitionValidationResult = Readonly<{
     readonly error: ProjectDefinitionDiagnostic;
 }>;
 export interface NormalizedCheckDeclaration {
+    readonly admissionPriority: number;
     readonly definition: CheckDescriptor;
     readonly dependsOn: readonly string[];
+    readonly enabledByFlags?: CheckFlagEnablement;
     readonly maxParallel: number;
     readonly mutex: readonly string[];
+    readonly observes: readonly string[];
     readonly options: object;
+    readonly resourceClaims: CheckResourceClaims;
     readonly visibility: CheckVisibility;
 }
 export interface NormalizedCheck extends NormalizedCheckDeclaration {
@@ -73,16 +94,40 @@ export interface NormalizedCheck extends NormalizedCheckDeclaration {
 export interface DeclarativeProjectSnapshot {
     readonly apiVersion: "1";
     readonly checks: readonly NormalizedCheckDeclaration[];
-    readonly outputs: ProjectOutputs;
-    readonly scheduler: SchedulerPolicy;
+    readonly outputs: DeclarativeProjectOutputs;
+    readonly scheduler: DeclarativeSchedulerPolicy;
 }
 export interface NormalizedProjectDefinition {
     readonly checks: readonly NormalizedCheck[];
     readonly declarative: DeclarativeProjectSnapshot;
     readonly definitionWarnings: readonly DefinitionWarning[];
+    /** Runtime scheduler policy；custom callback 保留在此处。 */
+    readonly scheduler: SchedulerPolicy;
 }
+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" | "complete">, 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;
 /** 使用 Product 默认输出创建普通 Project Definition。 */
 export declare function defineConfig<const T extends ProjectDefinitionInput>(value: T & Record<Exclude<keyof T, keyof ProjectDefinitionInput>, never>): ProjectDefinition;
 export declare function normalizeProjectDefinition(definition: ProjectDefinition): NormalizedProjectDefinition;
-export declare function createDeclarativeFingerprint(snapshot: DeclarativeProjectSnapshot): string;
-export {};

package/types/project-definition/resource-unit-mapping.d.ts

@@ -0,0 +1,4 @@
+export type ResourceUnitMapping = Readonly<Record<string, number>>;
+export declare const EMPTY_RESOURCE_UNIT_MAPPING: ResourceUnitMapping;
+/** Snapshots a canonical closed resource-to-positive-units mapping. */
+export declare function snapshotResourceUnitMapping(value: unknown): ResourceUnitMapping | undefined;