@zxyycom/vibe-check 0.0.1 → 0.0.3

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/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,14 @@
+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";
+/**
+ * 构造只检查其必填、显式 `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<"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/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,33 @@
+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<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
+    /** 必填的完整 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/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/package-tools/cache/cache-json-by-key.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `cacheJsonByKey` 的 caller-owned identity、payload parser 与 computation。
+ *
+ * `key` 必须覆盖所有会改变 computation 结果的输入、实现、options、toolchain 与声明的外部状态；
+ * 不能放入 secret 或低熵敏感值。`directory` 是调用方信任、可自行删除的本地状态空间。
+ */
+type NonThenable<T extends object> = T & Readonly<{
+    readonly then?: undefined;
+}>;
+/** Caller-keyed JSON cache 的 options。 */
+export interface CacheJsonByKeyOptions<T extends object> {
+    /** cache miss、读取失败或 payload 无效时执行的 sync/async computation。 */
+    readonly compute: () => unknown;
+    /** 调用方信任、可自行清理的 absolute local directory。 */
+    readonly directory: string;
+    /** 覆盖所有影响 computation 结果的完整 semantic key；不得包含 secret 或低熵敏感值。 */
+    readonly key: string;
+    /** 调用方为这一类缓存选择的非空 identity namespace。 */
+    readonly namespace: string;
+    /** 同步验证 cached/computed canonical JSON object，并返回调用方的 typed value。 */
+    readonly parse: (value: unknown) => NonThenable<T>;
+    /** 调用方控制、在 payload 或 computation contract 改变时更新的非空版本。 */
+    readonly version: string;
+}
+/** `cacheJsonByKey` 返回的闭合 cache observation 与本次 parser value。 */
+export type CacheJsonByKeyResult<T extends object> = Readonly<{
+    /** 已读取并通过 parser 验证现有 payload。 */
+    readonly read: "hit";
+    /** 本次 value 来自 cache，不调用 `compute`。 */
+    readonly source: "cache";
+    /** `parse` 返回的调用方 typed value。 */
+    readonly value: T;
+    /** cache hit 不尝试重新写入。 */
+    readonly write: "not-attempted";
+}> | Readonly<{
+    /** 没有 entry、读取失败，或已有 payload 未通过 identity/parser 验证。 */
+    readonly read: "failed" | "invalid" | "miss";
+    /** 本次 value 来自成功的 `compute` 与 `parse`。 */
+    readonly source: "computed";
+    /** `parse` 返回的调用方 typed value。 */
+    readonly value: T;
+    /** 新 payload 已存储，或存储失败但 typed value 仍可使用。 */
+    readonly write: "failed" | "stored";
+}>;
+/**
+ * 按 caller 提供的完整 semantic key 复用本地 canonical JSON object。
+ *
+ * cache hit 不会跳过或重放 Check settlement、Records、messages、duration 或 side effects。读取或写入失败
+ * 只通过返回的 observation 可见；只要 `compute` 与 `parse` 成功，就仍返回本次 computation 的 value。
+ * 不提供依赖发现、默认目录、lock/single-flight、TTL/LRU、cleanup、remote cache 或 tamper protection。
+ */
+export declare function cacheJsonByKey<T extends object>(authoredOptions: CacheJsonByKeyOptions<T>): Promise<CacheJsonByKeyResult<T>>;
+export {};

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

@@ -0,0 +1,27 @@
+import type { CheckResult } from "../../check/check.ts";
+type CheckMessage = NonNullable<CheckResult["messages"]>[number];
+/**
+ * 将 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>;
+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/package-tools/learned-critical-path/critical-path-ranking.d.ts

@@ -0,0 +1,19 @@
+import type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
+/** The pure ranking algorithm only needs immutable estimated durations keyed by Task ID. */
+export interface SchedulerCriticalPathPredictionSnapshot {
+    readonly predictions: readonly Readonly<{
+        readonly estimatedDurationMs: number;
+        readonly taskId: string;
+    }>[];
+}
+export interface SchedulerCriticalPathScore {
+    readonly criticalPathScore: number;
+    readonly taskId: string;
+}
+/** A graph-derived immutable score table; it retains no dependency or authored-input payload. */
+export interface SchedulerCriticalPathSnapshot {
+    readonly scores: readonly SchedulerCriticalPathScore[];
+}
+/** Computes directed dependsOn + observes downstream scores once before Scheduler admission. */
+export declare function createSchedulerCriticalPathSnapshot(graph: SchedulerGraphSnapshot, prediction: SchedulerCriticalPathPredictionSnapshot): SchedulerCriticalPathSnapshot;
+export declare function criticalPathScoreForTask(snapshot: SchedulerCriticalPathSnapshot, taskId: string): number | undefined;

package/types/package-tools/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/package-tools/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 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/package-tools/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/package-tools/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/package-tools/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;