@zxyycom/vibe-check 0.0.1

package/types/check/check.d.ts

@@ -0,0 +1,350 @@
+import type { CanonicalJsonObject, CanonicalJsonValue } from "../data-boundary/canonical-json.ts";
+import type { InheritableCheckCollection } from "./inherited-collection.ts";
+export { inherit, isInheritedCheckCollection, snapshotInheritedCheckCollection } from "./inherited-collection.ts";
+export type { InheritCheckCollectionInput, InheritableCheckCollection, InheritedCheckCollection } from "./inherited-collection.ts";
+/** Check 无法给出 final data 时返回的受控 reason code。 */
+export type CheckReason = Readonly<{
+    /** 由 owning Check 定义、供调用方诊断的稳定 code。 */
+    readonly code: string;
+}>;
+/** `not-applicable` Check result 的可选 reason。 */
+export type CheckNotApplicableReason = CheckReason;
+/** author callback 明确返回 `unavailable` 时必须提供的 reason。 */
+export type CheckDeclaredUnavailableReason = CheckReason;
+/** `unavailable` Check outcome 的 reason；可列出导致当前 Check 不可用的上游 Check。 */
+export type CheckUnavailableReason = Readonly<{
+    /** 由当前 Check 或 Product 边界给出的受控原因。 */
+    readonly code: string;
+    /** 仅在上游关系有助于定位时给出的相关 Check IDs。 */
+    readonly checkIds?: readonly string[];
+}>;
+/** 终端 Check message 的 presentation severity。 */
+export type CheckMessageLevel = "info" | "warning" | "error";
+/** 由 Check author 附加到 terminal result 的补充消息。 */
+export interface CheckMessage {
+    /** 人读 presentation 使用的 severity。 */
+    readonly level: CheckMessageLevel;
+    /** owning Check namespace 内的稳定 message code。 */
+    readonly code: string;
+    /** 非空消息正文；Product 保留 author 提供的字符串。 */
+    readonly message: string;
+}
+/** 可附加到每个 {@link CheckResult} branch 的有序 terminal messages。 */
+export interface CheckResultMessages {
+    /** 省略、`undefined` 或空数组都表示没有 supplemental messages。 */
+    readonly messages?: readonly CheckMessage[];
+}
+/** 已结算 Check 在人读 progress 中的可见性。 */
+export type CheckVisibility = "always" | "attention";
+/**
+ * Check callback 的 terminal result。
+ *
+ * @typeParam FinalData - `passed` 或 `failed` 时保留为 canonical final data 的业务对象。
+ * @remarks `not-applicable` 与 `unavailable` 不携带 final data；普通 callback、Record 或取消失败由
+ * Product 转换为 `unavailable`，而不是抛出为 Run 的成功结果。
+ */
+export type CheckResult<FinalData extends object = object> = Readonly<({
+    /** Check 已产生通过的 final data。 */
+    readonly status: "passed";
+    /** 此 Check 的主要终态事实。 */
+    readonly data: FinalData;
+} | {
+    /** Check 已产生失败的 final data。 */
+    readonly status: "failed";
+    /** 此 Check 的主要终态事实。 */
+    readonly data: FinalData;
+} | {
+    /** Check 在当前 invocation 中不适用。 */
+    readonly status: "not-applicable";
+    /** 不适用的可选受控原因。 */
+    readonly reason?: CheckNotApplicableReason;
+} | {
+    /** Check 不能提供 terminal data。 */
+    readonly status: "unavailable";
+    /** 不可用的受控原因。 */
+    readonly reason: CheckDeclaredUnavailableReason;
+}) & CheckResultMessages>;
+/** 已 materialize 到 Core snapshot 的 Check terminal outcome。 */
+export type CheckOutcome = Readonly<{
+    /** 已 materialize 的通过 outcome。 */
+    readonly status: "passed";
+    /** 已 canonicalize 的 primary final fact。 */
+    readonly data: CanonicalJsonObject;
+} | {
+    /** 已 materialize 的失败 outcome。 */
+    readonly status: "failed";
+    /** 已 canonicalize 的 primary final fact。 */
+    readonly data: CanonicalJsonObject;
+} | {
+    /** 已 materialize 的不适用 outcome。 */
+    readonly status: "not-applicable";
+    /** 不适用的可选受控原因。 */
+    readonly reason?: CheckNotApplicableReason;
+} | {
+    /** 已 materialize 的不可用 outcome。 */
+    readonly status: "unavailable";
+    /** 包含相关 upstream Check IDs 的受控原因。 */
+    readonly reason: CheckUnavailableReason;
+}>;
+/** 将 callback options 转为不可变观察值的递归 utility type。 */
+export type DeepReadonly<T> = T extends string | number | boolean | null ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: DeepReadonly<T[Key]>;
+} : never;
+/** callback 写入 supplemental Record 时的 Check-local identity。 */
+interface RecordIdentityInput {
+    /** 在当前 Check 内唯一的 Record ID。 */
+    readonly id: string;
+}
+/** callback 写入 supplemental Records 的 Product-owned reporter。 */
+interface CheckRecordReporter {
+    /** 记录一个补充事实；它不决定 Check 的 terminal status。 */
+    report(identity: RecordIdentityInput, data: object): void;
+}
+/** 读取已声明 dependency final data 时的失败原因。 */
+export type DependencyReadError = Readonly<{
+    /** 当前 Check 未声明所请求的 dependency ID。 */
+    readonly code: "dependency-not-declared";
+    /** 被拒绝的 dependency ID。 */
+    readonly checkId: string;
+} | {
+    /** 已声明 upstream 没有可读取的 final data。 */
+    readonly code: "upstream-data-unavailable";
+    /** 没有 final data 的 direct dependency ID。 */
+    readonly checkId: string;
+    /** 阻止 readback 的 upstream terminal status。 */
+    readonly status: "not-applicable" | "unavailable";
+}>;
+/** {@link CheckDependencies.get} 的受控 readback 结果。 */
+export type DependencyReadResult = Readonly<{
+    /** 成功读取 direct dependency final data。 */
+    readonly ok: true;
+    /** 被读取的 direct dependency ID。 */
+    readonly checkId: string;
+    /** upstream 已结算为 `passed` 或 `failed` 的 status。 */
+    readonly status: "passed" | "failed";
+    /** 已与原对象脱离的上游依赖终态数据。 */
+    readonly data: CanonicalJsonObject;
+} | {
+    /** dependency data 不可读取。 */
+    readonly ok: false;
+    /** 失败的授权或 upstream-data reason。 */
+    readonly error: DependencyReadError;
+}>;
+/** 当前 Check 的已规范化直接 dependencies 的 data reader。 */
+export interface CheckDependencies {
+    /**
+     * 读取一个直接 dependency 的 canonical final data。
+     *
+     * @returns 已声明且为 `passed`/`failed` 的 dependency 返回其 data；未声明或没有 final data 时返回
+     * `ok: false`，不会授权 transitive dependency。
+     */
+    get(checkId: string): DependencyReadResult;
+}
+/** callback 可读取的、由 Product 规范化的项目上下文。 */
+export interface CheckProjectContext {
+    /** 本次 Run 使用的绝对项目根目录。 */
+    readonly root: string;
+    /** 已去重、排序的 caller-supplied flags。 */
+    readonly flags: readonly string[];
+}
+/**
+ * Check callback 收到的 Product-owned execution context。
+ *
+ * @typeParam Options - 此 Check preflight 后传给 execution 的 options shape。
+ */
+export interface CheckExecutionContext<Options extends object> {
+    /** 读取当前 Check 的已声明 direct dependencies。 */
+    readonly dependencies: CheckDependencies;
+    /** 深度只读、canonical 的 invocation-local prepared Check options。 */
+    readonly options: DeepReadonly<Options>;
+    /** 已规范化的项目根与 flags。 */
+    readonly project: CheckProjectContext;
+    /** 写入 supplemental Records 的 reporter。 */
+    readonly records: CheckRecordReporter;
+    /** 本次 invocation 的 cancellation signal。 */
+    readonly signal: AbortSignal;
+}
+/**
+ * 一个 Check 的 callback signature。
+ *
+ * @typeParam Options - callback 从 context 读取的 prepared options shape。
+ * @returns terminal Check result 或其 Promise。
+ */
+export type CheckExecution<Options extends object = object> = (this: void, context: CheckExecutionContext<Options>) => CheckResult | Promise<CheckResult>;
+/**
+ * 在 Check execution 前，可选地为本次 invocation 准备 options。
+ *
+ * @remarks `signal` 与同一次 callback execution 使用同一个 cancellation signal；实现应在可等待工作中
+ * 协作退出，而不是留下悬挂 work。bivariant callback 保持具体 options Check 可进入普通递归 Check
+ * collection；Product 仍只会用该 Check 自己的 authored options 调用它。精确结果见
+ * {@link CheckPreflightResult}。
+ */
+export type CheckPreflight<AuthoredOptions extends object = object, PreparedOptions extends object = AuthoredOptions> = {
+    bivarianceHack(this: void, options: DeepReadonly<AuthoredOptions>, signal: AbortSignal): CheckPreflightResult<PreparedOptions> | Promise<CheckPreflightResult<PreparedOptions>>;
+}["bivarianceHack"];
+/**
+ * Check-owned preflight 的判别结果。
+ *
+ * `failure/block` 不允许 fallback，直接以 owning reason 结算为 unavailable；`failure/continue` 必须给出
+ * fallback 并继续 execution。两种进入 execution 的值都只属于本次 invocation，Product canonicalize/freeze
+ * 后传递，不会改写 Definition 中 authored options。两个 failure 分支都必须给出 reason；continue reason
+ * 是 Check-owned diagnostic identity，当前不会单独 materialize 为 outcome，调用方通过 messages 与后续
+ * outcome 观察结果；block 物理上不含 fallback 字段。
+ */
+export type CheckPreflightResult<PreparedOptions extends object = object> = Readonly<{
+    readonly status: "success";
+    readonly preparedOptions: PreparedOptions;
+    readonly messages?: readonly CheckMessage[];
+} | {
+    readonly status: "failure";
+    readonly action: "block";
+    readonly reason: CheckDeclaredUnavailableReason;
+    readonly messages?: readonly CheckMessage[];
+} | {
+    readonly status: "failure";
+    readonly action: "continue";
+    readonly fallback: PreparedOptions;
+    readonly reason: CheckReason;
+    readonly messages?: readonly CheckMessage[];
+}>;
+/**
+ * 普通递归 Check authoring value 的共享字段。
+ *
+ * @typeParam AuthoredOptions - Definition 中的 declarative options shape。
+ * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。
+ * @remarks 该值可以同时有 `execution` 和 `checks`；只有 executable node 产生 final Check fact。
+ */
+interface CheckBase<AuthoredOptions extends object, PreparedOptions extends object> {
+    /** 在 Definition 内唯一的 stable Check ID。 */
+    readonly checkId: string;
+    /** 人读 progress 与 output 使用的非空名称。 */
+    readonly displayName: string;
+    /** Check-owned declarative options；默认 Check 的嵌套 branch 以普通对象组合替换。 */
+    readonly options?: AuthoredOptions;
+    /** 可执行节点的 callback；省略时此节点只承载递归 children。 */
+    execution?(this: void, context: CheckExecutionContext<PreparedOptions>): CheckResult | Promise<CheckResult>;
+    /** 继承 scheduling context 的 child Checks，不会单独形成 container result。 */
+    readonly checks?: readonly Check[];
+    /** 直接 prerequisite Check IDs，或对父 dependency collection 的显式 edit。 */
+    readonly dependsOn?: InheritableCheckCollection<string>;
+    /** 此 Check 及其 descendants 的最大并行预算。 */
+    readonly maxParallel?: number;
+    /** 共享资源名称，或对父 mutex collection 的显式 edit。 */
+    readonly mutex?: InheritableCheckCollection<string>;
+    /** 已结算 Check 的人读可见性；可执行节点默认 `always`。 */
+    readonly visibility?: CheckVisibility;
+}
+/**
+ * 判断两个 options shape 是否互相可赋值；互相可赋值时 execution 不需要 preparation 转换。
+ */
+type HasSameOptionsShape<AuthoredOptions extends object, PreparedOptions extends object> = [
+    AuthoredOptions
+] extends [PreparedOptions] ? [PreparedOptions] extends [AuthoredOptions] ? true : false : false;
+/** Prepared shape 不同时，preflight 是建立安全转换的必填边界。 */
+type CheckPreflightField<AuthoredOptions extends object, PreparedOptions extends object> = HasSameOptionsShape<AuthoredOptions, PreparedOptions> extends true ? Readonly<{
+    readonly preflight?: CheckPreflight<AuthoredOptions, PreparedOptions>;
+}> : Readonly<{
+    readonly preflight: CheckPreflight<AuthoredOptions, PreparedOptions>;
+}>;
+/**
+ * Project Definition 中的普通递归 Check authoring value。
+ *
+ * @typeParam AuthoredOptions - Definition 中的 declarative options shape。
+ * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。
+ * @remarks Definition 只闭合 authored JSON options；preflight 在同一 Run 的所有 execution 前作为全局
+ * barrier 执行。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preflight；同形时可以省略。它不进入
+ * declarative fingerprint 或 machine output。
+ */
+export type Check<AuthoredOptions extends object = object, PreparedOptions extends object = AuthoredOptions> = CheckBase<AuthoredOptions, PreparedOptions> & CheckPreflightField<AuthoredOptions, PreparedOptions>;
+export type EmptyCheckOptions = Readonly<Record<never, never>>;
+/**
+ * 防止宽泛的 parser 标注擦除 `PromiseLike`。canonical `then` field 可以保存 JSON data，
+ * 但不能保存使该值成为 thenable 的 callable。
+ */
+type NonThenableData = Readonly<{
+    readonly then?: CanonicalJsonValue;
+}>;
+/**
+ * 将 canonical dependency data 还原为 provider final-data shape 的同步 parser。
+ *
+ * @typeParam FinalData - provider 在 `passed`/`failed` result 中声明的 final-data shape。
+ * @remarks Product 不调用此 parser；provider 负责不受信任或跨版本 data 的业务验证。
+ */
+export type CheckDataParser<FinalData extends object = object> = (this: void, data: CanonicalJsonObject) => FinalData & NonThenableData;
+type CheckAuthoringBase<Id extends string, AuthoredOptions extends object, PreparedOptions extends object> = Omit<CheckBase<AuthoredOptions, PreparedOptions>, "checkId" | "execution" | "options"> & CheckPreflightField<AuthoredOptions, PreparedOptions> & Readonly<{
+    readonly checkId: Id;
+}>;
+interface OrdinaryCheckFields<PreparedOptions extends object> {
+    execution?(this: void, context: CheckExecutionContext<PreparedOptions>): CheckResult | Promise<CheckResult>;
+    readonly parseData?: never;
+}
+export type CheckWithOptions<Id extends string, AuthoredOptions extends object, PreparedOptions extends object = AuthoredOptions> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> & OrdinaryCheckFields<PreparedOptions> & Readonly<{
+    readonly options: AuthoredOptions;
+}>;
+export type CheckWithoutOptions<Id extends string> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> & OrdinaryCheckFields<EmptyCheckOptions> & Readonly<{
+    readonly options?: never;
+}>;
+interface TypedCheckFields<PreparedOptions extends object, Parser extends CheckDataParser> {
+    /**
+     * 将 canonical runtime data 还原为 provider data。
+     *
+     * 启发式边界：同版本且受信任的 provider 若由测试保证 data shape，可仅将它实现为
+     * identity/type anchor。这不验证 JavaScript 或基于 cast 的 producer、历史或跨版本 artifact，
+     * 也不验证不受信任输入。
+     */
+    readonly parseData: Parser;
+    execution(this: void, context: CheckExecutionContext<PreparedOptions>): CheckResult<NoInfer<ReturnType<Parser>>> | Promise<CheckResult<NoInfer<ReturnType<Parser>>>>;
+}
+export type TypedCheckWithOptions<Id extends string, AuthoredOptions extends object, Parser extends CheckDataParser, PreparedOptions extends object = AuthoredOptions> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> & TypedCheckFields<PreparedOptions, Parser> & Readonly<{
+    readonly options: AuthoredOptions;
+}>;
+export type TypedCheckWithoutOptions<Id extends string, Parser extends CheckDataParser> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> & TypedCheckFields<EmptyCheckOptions, Parser> & Readonly<{
+    readonly options?: never;
+}>;
+/**
+ * 定义一个 Check，同时保留 literal `checkId`、options 与 typed-provider parser 的 inference。
+ *
+ * @remarks 此函数负责 authoring inference；{@link run} 负责 Project Definition validation。
+ * @example 定义带 options、Records 与 messages 的自定义 Check
+ * ```ts
+ * function hasValidLicensePolicyOptions(options: object): boolean {
+ *   const denied: unknown = Reflect.get(options, "denied");
+ *   return (
+ *     Object.keys(options).length === 1 &&
+ *     Object.hasOwn(options, "denied") &&
+ *     Array.isArray(denied) &&
+ *     denied.every((license) => typeof license === "string")
+ *   );
+ * }
+ *
+ * const licensePolicy = defineCheck({
+ *   checkId: "license-policy",
+ *   displayName: "License policy",
+ *   options: { denied: ["GPL-3.0-only"] },
+ *   preflight(options) {
+ *     return hasValidLicensePolicyOptions(options)
+ *       ? { status: "success", preparedOptions: options }
+ *       : { status: "failure", action: "block", reason: { code: "invalid-options" } };
+ *   },
+ *   visibility: "attention",
+ *   execution({ options, records, signal }) {
+ *     if (signal.aborted) return { status: "unavailable", reason: { code: "cancelled" } };
+ *
+ *     const deniedCount = options.denied.length;
+ *     if (deniedCount > 0) {
+ *       records.report({ id: "denied-license" }, { count: deniedCount });
+ *       return {
+ *         status: "failed",
+ *         data: { deniedCount },
+ *         messages: [{ level: "warning", code: "denied-license", message: "Denied licenses found." }]
+ *       };
+ *     }
+ *     return { status: "passed", data: { deniedCount: 0 } };
+ *   }
+ * });
+ * ```
+ */
+export declare function defineCheck<const Id extends string, AuthoredOptions extends object, PreparedOptions extends object = AuthoredOptions>(value: CheckWithOptions<Id, AuthoredOptions, PreparedOptions>): CheckWithOptions<Id, AuthoredOptions, PreparedOptions>;
+export declare function defineCheck<const Id extends string>(value: CheckWithoutOptions<Id>): CheckWithoutOptions<Id>;
+export declare function defineCheck<const Id extends string, AuthoredOptions extends object, const Parser extends CheckDataParser, PreparedOptions extends object = AuthoredOptions>(value: TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>): TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>;
+export declare function defineCheck<const Id extends string, const Parser extends CheckDataParser>(value: TypedCheckWithoutOptions<Id, Parser>): TypedCheckWithoutOptions<Id, Parser>;

package/types/check/descriptor-validation.d.ts

@@ -0,0 +1,18 @@
+import type { CheckDescriptor } from "./descriptor.ts";
+export interface CheckDescriptorValidationIssue {
+    readonly path: string;
+    readonly code: "invalid-value";
+    readonly message: string;
+}
+export type CheckDescriptorValidationResult = Readonly<{
+    readonly ok: true;
+    readonly value: CheckDescriptor;
+} | {
+    readonly ok: false;
+    readonly issues: readonly [
+        CheckDescriptorValidationIssue,
+        ...CheckDescriptorValidationIssue[]
+    ];
+}>;
+/** Validates the minimal Check identity shared by Definition authoring and final facts. */
+export declare function validateCheckDescriptor(value: unknown): CheckDescriptorValidationResult;

package/types/check/descriptor.d.ts

@@ -0,0 +1,5 @@
+/** The declaration identity retained for one executable Check. */
+export interface CheckDescriptor {
+    readonly checkId: string;
+    readonly displayName: string;
+}

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

@@ -0,0 +1,35 @@
+declare const INHERITED_CHECK_COLLECTION: unique symbol;
+/** 使用 {@link inherit} 对父 Check 的 string collection 做显式增删的输入。 */
+export type InheritCheckCollectionInput<T> = Readonly<{
+    readonly add: readonly T[];
+    readonly remove?: readonly T[];
+} | {
+    readonly add?: readonly T[];
+    readonly remove: readonly T[];
+}>;
+/**
+ * 由 {@link inherit} 创建、带有不可伪造 marker 的 collection edit。
+ *
+ * @remarks Definition validation 不接受看起来相同的 plain object。
+ */
+export type InheritedCheckCollection<T> = InheritCheckCollectionInput<T> & Readonly<{
+    readonly [INHERITED_CHECK_COLLECTION]: true;
+}>;
+/**
+ * 可以直接替换父 collection 的数组，或由 {@link inherit} 表示的显式 edit。
+ *
+ * @typeParam T - collection item 类型。
+ */
+export type InheritableCheckCollection<T> = readonly T[] | InheritedCheckCollection<T>;
+/**
+ * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。
+ *
+ * @typeParam T - 要添加或移除的 collection item 类型。
+ * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。
+ * @returns 只有此函数创建的值会被 Definition validation 识别为 inherited collection。
+ */
+export declare function inherit<T>(value: InheritCheckCollectionInput<T>): InheritedCheckCollection<T>;
+export declare function isInheritedCheckCollection(value: unknown): value is InheritedCheckCollection<unknown>;
+/** Copies the trusted marker while preserving the authoring data's closed shape. */
+export declare function snapshotInheritedCheckCollection(value: InheritedCheckCollection<unknown>): Readonly<Record<string, unknown>> | undefined;
+export {};

package/types/check/options-snapshot.d.ts

@@ -0,0 +1,2 @@
+/** Copies a closed JSON object without retaining untyped authoring input. */
+export declare function snapshotJsonObject(value: unknown): object | undefined;

package/types/check-settlement/fact-validation.d.ts

@@ -0,0 +1,14 @@
+import type { CoreSnapshot } from "./facts.ts";
+export interface ValidationIssue {
+    readonly path: string;
+    readonly code: "duplicate" | "identity-mismatch" | "invalid-value" | "missing-field" | "unknown-field";
+    readonly message: string;
+}
+export type ValidationResult<T> = Readonly<{
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly issues: readonly [ValidationIssue, ...ValidationIssue[]];
+}>;
+export declare function validateCoreSnapshot(value: unknown): ValidationResult<CoreSnapshot>;

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

@@ -0,0 +1,19 @@
+import type { CheckDescriptor } from "../check/descriptor.ts";
+import type { CheckOutcome } from "../check/check.ts";
+export type { CanonicalJsonObject, CanonicalJsonPrimitive, CanonicalJsonValue } from "../data-boundary/canonical-data.ts";
+export type { CheckDescriptor, CheckOutcome };
+/** A Core Check has exactly one terminal outcome and no execution bookkeeping. */
+export interface CoreCheck extends CheckDescriptor {
+    readonly outcome: CheckOutcome;
+}
+/** A supplemental Record is owned by its structural `{ checkId, id }` identity. */
+export interface CoreRecord {
+    readonly checkId: string;
+    readonly id: string;
+    readonly data: import("../data-boundary/canonical-data.ts").CanonicalJsonObject;
+}
+/** The complete Product entity projection. Invocation metadata belongs to Run, not Core. */
+export interface CoreSnapshot {
+    readonly checks: readonly CoreCheck[];
+    readonly records: readonly CoreRecord[];
+}

package/types/check-settlement/outcome-normalization.d.ts

@@ -0,0 +1,9 @@
+import type { CheckOutcome } from "../check/check.ts";
+interface OutcomeNormalizationInput {
+    readonly knownCheckIds: ReadonlySet<string>;
+    readonly productOutcome: boolean;
+    readonly value: unknown;
+}
+/** Normalizes one live Check terminal value before the settlement session commits it. */
+export declare function normalizeCheckOutcome(input: OutcomeNormalizationInput): CheckOutcome | undefined;
+export {};

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

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

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

@@ -0,0 +1,41 @@
+import type { CheckDescriptor } from "../check/descriptor.ts";
+import type { CheckOutcome } from "../check/check.ts";
+import { type RecordSubmissionResult } from "./record-store.ts";
+import type { CoreSnapshot } from "./facts.ts";
+export type { RecordSubmissionResult } from "./record-store.ts";
+export interface CoreCheckRegistration {
+    readonly definition: CheckDescriptor;
+}
+/** Internal Record port bound to one currently executing Check. */
+export interface RecordSink {
+    report(identity: unknown, data: unknown): RecordSubmissionResult;
+}
+/** Only the Product Task adapter receives this Core lifecycle capability. */
+export interface TrustedCheckScope {
+    readonly records: RecordSink;
+    /** Core is the only author-result validation/canonicalization boundary. */
+    readonly settle: (outcome: unknown) => AuthorCheckSettlement;
+    /** Private Product lifecycle outcomes may include contained prerequisite IDs. */
+    readonly settleProduct: (outcome: CheckOutcome) => CheckOutcome;
+}
+/** Core's private marker for an author result that survived every settlement guard. */
+export interface AuthorCheckSettlement {
+    readonly authorResultAccepted: boolean;
+    readonly outcome: CheckOutcome;
+}
+export interface CoreCheckSession {
+    openCheckScope(checkId: string): TrustedCheckScope;
+    readSettledCheckOutcome(checkId: string): CheckOutcome;
+    closeUnresolvedAsCancelled(): readonly CancelledCheckClosure[];
+    freeze(): CoreSnapshot;
+}
+/** Product-private cancellation facts emitted at the exact Core closure boundary. */
+export interface CancelledCheckClosure {
+    readonly checkId: string;
+    readonly outcome: CheckOutcome;
+}
+/** A trusted integration bug is fatal to the invocation, not a Check outcome. */
+export declare class CoreInvariantFailure extends Error {
+    constructor(message: string);
+}
+export declare function createCoreCheckSession(registrations: readonly CoreCheckRegistration[]): CoreCheckSession;

package/types/data-boundary/canonical-data.d.ts

@@ -0,0 +1,13 @@
+import type { CanonicalJsonObject, CanonicalJsonValue } from "./canonical-json.ts";
+export type { CanonicalJsonObject, CanonicalJsonPrimitive, CanonicalJsonValue } from "./canonical-json.ts";
+/**
+ * Materializes arbitrary author data without property reads or JSON hooks.
+ * The returned graph is detached, prototype-safe, and deeply frozen before it
+ * becomes a Core fact. Canonical text order is applied explicitly at serialization.
+ */
+export declare function canonicalizeJsonObject(value: unknown): CanonicalJsonObject | undefined;
+export declare function canonicalizeJsonValue(value: unknown): CanonicalJsonValue | undefined;
+/** Serializes detached canonical JSON with explicit lexical object-key ordering. */
+export declare function canonicalJsonText(value: unknown): string;
+/** Emits canonical UTF-8 JSON without invoking author getters or `toJSON`. */
+export declare function canonicalJsonBytes(value: unknown): Uint8Array;

package/types/data-boundary/canonical-json.d.ts

@@ -0,0 +1,6 @@
+/** Package-private static shape for Product's detached canonical JSON facts. */
+export type CanonicalJsonPrimitive = boolean | null | number | string;
+export type CanonicalJsonValue = CanonicalJsonPrimitive | readonly CanonicalJsonValue[] | CanonicalJsonObject;
+export interface CanonicalJsonObject {
+    readonly [key: string]: CanonicalJsonValue;
+}

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

@@ -0,0 +1,8 @@
+export declare function snapshotPlainRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
+export declare function snapshotClosedRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
+export declare function snapshotClosedArray(value: unknown): readonly unknown[] | undefined;
+export declare function hasExactPlainRecordKeys(value: Readonly<Record<string, unknown>>, keys: readonly string[]): boolean;
+export declare function hasRequiredAndOptionalRecordKeys(value: Readonly<Record<string, unknown>>, keys: Readonly<{
+    readonly optional: readonly string[];
+    readonly required: readonly string[];
+}>): boolean;

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

@@ -0,0 +1,4 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isNonArrayRecord(value: unknown): value is Record<string, unknown>;
+export declare function isUnknownArray(value: unknown): value is unknown[];
+export declare function isStringArray(value: unknown): value is string[];

package/types/finding-waivers/reconciliation.d.ts

@@ -0,0 +1,66 @@
+import { type CanonicalJsonValue } from "../data-boundary/canonical-data.ts";
+/** 由采用方声明、用于匹配一个 finding 的语义身份与豁免理由。 */
+export interface FindingWaiver<Identity> {
+    /** 调用方定义的稳定 finding 身份；匹配时按 canonical JSON 结构比较。 */
+    readonly identity: Identity;
+    /** 解释该 finding 在当前范围内可被豁免的非空理由。 */
+    readonly reason: string;
+}
+/** helper 安全 materialize 后保留的 waiver evidence；identity 是 detached canonical JSON。 */
+export interface MaterializedFindingWaiver {
+    /** 从 authored identity materialize 的 detached、deep-frozen canonical JSON。 */
+    readonly identity: CanonicalJsonValue;
+    /** 从 authored reason materialize 的非空理由。 */
+    readonly reason: string;
+}
+/** 一项 finding waiver 的配置与匹配次数审计。 */
+export interface FindingWaiverAudit {
+    /** 被审计的 materialized authored waiver evidence，而非调用方可变输入引用。 */
+    readonly waiver: MaterializedFindingWaiver;
+    /** 该 waiver identity 在完整 finding 集合中匹配到的数量。 */
+    readonly matchCount: number;
+    /** 未使用、正常应用，或因过宽而没有应用。 */
+    readonly status: "unused" | "applied" | "overmatched";
+}
+/** reconciliation 后单个 finding 的可执行处置；只有 `waived` branch 携带 matched waiver。 */
+export type ReconciledFinding<Finding> = Readonly<{
+    /** 原始 finding；helper 不解释或改写它的领域字段。 */
+    readonly finding: Finding;
+    /** 没有匹配 waiver 的正常待处理 finding。 */
+    readonly disposition: "actionable";
+} | {
+    /** 原始 finding；helper 不解释或改写它的领域字段。 */
+    readonly finding: Finding;
+    /** 恰好匹配一项 waiver 的 finding。 */
+    readonly disposition: "waived";
+    /** applied waiver 的身份和理由。 */
+    readonly waiver: MaterializedFindingWaiver;
+} | {
+    /** 原始 finding；helper 不解释或改写它的领域字段。 */
+    readonly finding: Finding;
+    /** `overmatched` 保持为待处理，避免宽泛 waiver 静默覆盖多个 finding。 */
+    readonly disposition: "overmatched";
+}>;
+/** 调用方提供完整候选集、身份识别器和 waiver 配置的输入。 */
+export interface ReconcileFindingWaiversOptions<Finding, Identity> {
+    /** 必须是完整 finding 候选集合，helper 才能审计每项 waiver 的匹配次数。 */
+    readonly findings: readonly Finding[];
+    /** 从完整 finding 提取调用方选择的稳定语义身份。 */
+    readonly identify: (finding: Finding) => Identity;
+    /** 要与识别器输出进行 canonical structural matching 的 waiver。 */
+    readonly waivers: readonly FindingWaiver<Identity>[];
+}
+/** 独立 waiver reconciliation 的完整输出，保留 finding 处置和每项配置审计。 */
+export interface FindingWaiverReconciliation<Finding> {
+    /** 与 input finding 顺序相同的 reconciliation 结果。 */
+    readonly findings: readonly ReconciledFinding<Finding>[];
+    /** 与 input waiver 顺序相同的完整配置审计。 */
+    readonly waiverAudits: readonly FindingWaiverAudit[];
+}
+/**
+ * 按调用方定义的语义身份对完整 finding 集合和 waiver 配置做 canonical structural reconciliation。
+ *
+ * 每项 waiver 必须有唯一、可 canonicalize 的 identity 和非空 reason。匹配零项时产生 `unused` 审计；
+ * 匹配一项时该 finding 为 `waived`；匹配多项时产生 `overmatched` 审计，相关 finding 保持待处理。
+ */
+export declare function reconcileFindingWaivers<Finding, Identity>(options: ReconcileFindingWaiversOptions<Finding, Identity>): FindingWaiverReconciliation<Finding>;