@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/data-boundary/closed-values.ts

@@ -15,6 +15,7 @@ function ownDataShape(value: object): OwnDataShape | undefined {
   if (
     keys.some((key) => {
       const descriptor = descriptors[key];
+      if (descriptor === undefined) return true;
       return descriptor.get !== undefined || descriptor.set !== undefined;
     })
   )
@@ -60,18 +61,38 @@ export function snapshotClosedRecord(
     const shape = ownDataShape(value);
     if (
       shape === undefined ||
-      shape.keys.some((key) => shape.descriptors[key].enumerable !== true)
+      shape.keys.some((key) => shape.descriptors[key]?.enumerable !== true)
     ) {
       return undefined;
     }
-    return Object.freeze(
-      Object.fromEntries(shape.keys.map((key) => [key, shape.descriptors[key].value as unknown]))
-    );
+    const entries = shape.keys.map((key) => {
+      const descriptor = shape.descriptors[key];
+      if (descriptor === undefined) throw new TypeError(`Missing own descriptor: ${key}`);
+      return [key, descriptor.value as unknown] as const;
+    });
+    return Object.freeze(Object.fromEntries(entries));
   } catch {
     return undefined;
   }
 }
 
+/**
+ * 取得字段集合恰好匹配调用方字段表的闭合普通记录外层浅快照。
+ *
+ * 输入必须是使用 `Object.prototype` 或 null prototype 的非数组对象，且每个自有属性都是可枚举数据属性。
+ * 调用方持有的 `keys` 必须是稳定、无重复的字符串列表；缺字段、多字段、symbol 键、存取器或不可枚举属性
+ * 均返回 `undefined`。成功结果是使用 `Object.prototype` 的冻结浅副本：只固定外层字段，保留 callback、
+ * `undefined` 与嵌套对象或数组的原引用，调用方仍须逐字段验证。这不是 JSON 验证器；不调用 getter，
+ * 但反射 Proxy 可能执行其 trap，反射失败时返回 `undefined`。
+ */
+export function snapshotExactClosedRecord(
+  value: unknown,
+  keys: readonly string[]
+): Readonly<Record<string, unknown>> | undefined {
+  const record = snapshotClosedRecord(value);
+  return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;
+}
+
 function closedArrayLength(shape: OwnDataShape): number | undefined {
   const descriptor = shape.descriptors.length;
   if (typeof descriptor?.value !== "number" || descriptor.enumerable !== false) return undefined;
@@ -85,12 +106,20 @@ function closedArrayItems(shape: OwnDataShape, length: number): readonly unknown
   const items: unknown[] = [];
   for (let index = 0; index < length; index += 1) {
     const descriptor = shape.descriptors[String(index)];
-    if (descriptor === undefined || descriptor.enumerable !== true) return undefined;
+    if (descriptor?.enumerable !== true) return undefined;
     items.push(descriptor.value as unknown);
   }
   return Object.freeze(items);
 }
 
+/**
+ * 取得标准无空洞数组的外层浅快照。
+ *
+ * 输入必须使用 `Array.prototype`，除标准 `length` 和可枚举索引外没有其它自有属性，也不能包含存取器；
+ * 稀疏数组、额外属性或其它不符合条件的输入返回 `undefined`。成功结果是冻结浅副本，只固定数组结构，
+ * 保留 callback、`undefined` 与嵌套值的原引用，不检查元素的业务类型或 JSON 合法性。不调用存取器，
+ * 但反射 Proxy 可能执行其 trap，反射失败时返回 `undefined`。
+ */
 export function snapshotClosedArray(value: unknown): readonly unknown[] | undefined {
   try {
     if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) return undefined;
@@ -124,3 +153,23 @@ export function hasRequiredAndOptionalRecordKeys(
     Object.keys(value).every((key) => supportedKeys.has(key))
   );
 }
+
+export interface ClosedPolicyRecordKeys {
+  readonly optional?: readonly string[];
+  readonly required?: readonly string[];
+}
+
+/** Snapshots an authoring record whose keys are limited to one required/optional policy. */
+export function snapshotClosedPolicyRecord(
+  value: unknown,
+  keys: ClosedPolicyRecordKeys
+): Readonly<Record<string, unknown>> | undefined {
+  const record = snapshotClosedRecord(value);
+  return record !== undefined &&
+    hasRequiredAndOptionalRecordKeys(record, {
+      optional: keys.optional ?? [],
+      required: keys.required ?? []
+    })
+    ? record
+    : undefined;
+}

package/src/data-boundary/config-glob.ts

@@ -0,0 +1,17 @@
+import { minimatch } from "minimatch";
+
+import { toSlashPath } from "./project-path.ts";
+
+/**
+ * Product config glob's single matcher boundary. Candidates use slash form;
+ * dot paths participate only when an explicit glob matches them.
+ */
+export function matchesAnyConfigGlob(
+  candidatePath: string,
+  configGlobs: readonly string[]
+): boolean {
+  const normalizedCandidatePath = toSlashPath(candidatePath);
+  return configGlobs.some((configGlob) =>
+    minimatch(normalizedCandidatePath, configGlob, { dot: true })
+  );
+}

package/src/data-boundary/project-path.ts

@@ -0,0 +1,21 @@
+/** Converts a host path spelling to the Product's slash-path form. */
+export function toSlashPath(filePath: string): string {
+  return filePath.replace(/\\/g, "/");
+}
+
+/** Recognizes one stable project-root-relative slash path. */
+export function isNormalizedProjectRelativePath(value: unknown): value is string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.startsWith("/") ||
+    value.includes("\\") ||
+    value.includes("\u0000") ||
+    /^[A-Za-z]:/u.test(value)
+  ) {
+    return false;
+  }
+  return value
+    .split("/")
+    .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}

package/src/data-boundary/value-shapes.ts

@@ -13,3 +13,15 @@ export function isUnknownArray(value: unknown): value is unknown[] {
 export function isStringArray(value: unknown): value is string[] {
   return isUnknownArray(value) && value.every((item) => typeof item === "string");
 }
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+export function isPositiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+export function isNonNegativeSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}

package/src/index.ts

@@ -1,13 +1,34 @@
 /**
- * Vibe Check 是由项目在 Bun runtime 中调用的 TypeScript API，用于定义并执行项目质量 Check。
+ * Vibe Check 是由项目在 Node runtime 中调用的 TypeScript API，用于定义并执行项目质量 Check。
  * 所有公开能力从 package root 导入；package `README.md` 说明 consumer authoring、结果读取和分发范围。
  *
  * @packageDocumentation
  */
+export { cacheJsonByKey } from "./package-tools/cache/cache-json-by-key.ts";
+export type {
+  CacheJsonByKeyOptions,
+  CacheJsonByKeyResult
+} from "./package-tools/cache/cache-json-by-key.ts";
+export {
+  canonicalizeJsonObject,
+  canonicalizeJsonValue,
+  canonicalJsonBytes,
+  canonicalJsonText
+} from "./data-boundary/canonical-data.ts";
+export type {
+  CanonicalJsonObject,
+  CanonicalJsonPrimitive,
+  CanonicalJsonValue
+} from "./data-boundary/canonical-data.ts";
+export { snapshotClosedArray, snapshotExactClosedRecord } from "./data-boundary/closed-values.ts";
 export { duplicateDetection } from "./package-checks/duplicate-detection/default-check.ts";
+export type { PackageCheckAuthoringOptions } from "./package-checks/check-authoring.ts";
 export { parseDuplicateDetectionData } from "./package-checks/duplicate-detection/final-data.ts";
 export type { DuplicateDetectionFinalData } from "./package-checks/duplicate-detection/final-data.ts";
 export type {
+  DuplicateDetectionFindingIdentity,
+  DuplicateDetectionFindingLocation,
+  DuplicateDetectionFindingWaiver,
   DuplicateDetectionOptions,
   ResolvedDuplicateDetectionOptions
 } from "./package-checks/duplicate-detection/options.ts";
@@ -28,16 +49,36 @@ export { functionMetrics } from "./package-checks/function-metrics/constructor.t
 export { parseFunctionMetricsData } from "./package-checks/function-metrics/final-data.ts";
 export type { FunctionMetricsFinalData } from "./package-checks/function-metrics/final-data.ts";
 export type {
+  FunctionMetricsFindingIdentity,
+  FunctionMetricsFindingMetric,
+  FunctionMetricsFindingWaiver,
   FunctionMetricsOptions,
   ResolvedFunctionMetricsOptions
 } from "./package-checks/function-metrics/options.ts";
 export type { FunctionMetricsUnavailableReasonCode } from "./package-checks/function-metrics/execution.ts";
 export type { FunctionMetricsRecordData } from "./package-checks/function-metrics/records.ts";
+export { secretDetection } from "./package-checks/secret-detection/default-check.ts";
+export { parseSecretDetectionData } from "./package-checks/secret-detection/final-data.ts";
+export type { SecretDetectionFinalData } from "./package-checks/secret-detection/final-data.ts";
+export type {
+  ResolvedSecretDetectionOptions,
+  SecretDetectionFindingIdentity,
+  SecretDetectionFindingWaiver,
+  SecretDetectionOptions
+} from "./package-checks/secret-detection/options.ts";
+export type { SecretDetectionUnavailableReasonCode } from "./package-checks/secret-detection/execution.ts";
+export type { SecretDetectionRecordData } from "./package-checks/secret-detection/records.ts";
 export { jsonSchemaValidation } from "./package-checks/json-schema-validation/default-check.ts";
 export { parseJsonSchemaValidationData } from "./package-checks/json-schema-validation/final-data.ts";
 export type { JsonSchemaValidationFinalData } from "./package-checks/json-schema-validation/final-data.ts";
 export type {
+  JsonSchemaIdentity,
+  JsonSchemaIdentityMode,
+  JsonSchemaInstanceBinding,
+  JsonSchemaReferenceResolution,
+  JsonSchemaReferenceSource,
   JsonSchemaValidationOptions,
+  RegisteredJsonSchema,
   ResolvedJsonSchemaValidationOptions
 } from "./package-checks/json-schema-validation/options.ts";
 export type {
@@ -58,10 +99,28 @@ export type {
   JsonValidationRecordReason,
   JsonValidationUnavailableCode
 } from "./package-checks/json-validation/json-validation.ts";
+export { commandCheck } from "./package-checks/command-check/command-check.ts";
+export type {
+  AfterCommand,
+  AfterCommandContext,
+  AfterCommandExecution,
+  CommandCheck,
+  CommandCheckEnvironment,
+  CommandCheckWithAfterCommand,
+  CommandEnvironmentContext,
+  CommandEnvironmentResolver,
+  CompletedCommand,
+  CommandCheckFinalData,
+  CommandCheckInput,
+  CommandCheckOutput,
+  CommandCheckUnavailableReasonCode,
+  TypedCommandCheck
+} from "./package-checks/command-check/command-check.ts";
 export { maintenanceReminders } from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
 export type {
   MaintenanceReminder,
   MaintenanceReminderOptions,
+  MaintenanceRemindersInput,
   MaintenanceRemindersUnavailableCode
 } from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
 export { parseMaintenanceRemindersData } from "./package-checks/maintenance-reminders/final-data.ts";
@@ -70,6 +129,21 @@ export type {
   MaintenanceReminderUnavailableReason,
   MaintenanceRemindersFinalData
 } from "./package-checks/maintenance-reminders/final-data.ts";
+export { markdownLint } from "./package-checks/markdown-lint/default-check.ts";
+export { parseMarkdownLintData } from "./package-checks/markdown-lint/final-data.ts";
+export type { MarkdownLintFinalData } from "./package-checks/markdown-lint/final-data.ts";
+export type {
+  MarkdownLintFindingIdentity,
+  MarkdownLintFindingWaiver,
+  MarkdownLintOptions,
+  MarkdownLintRuleName,
+  ResolvedMarkdownLintOptions
+} from "./package-checks/markdown-lint/options.ts";
+export type {
+  MarkdownLintFindingWaiverAuditRecordData,
+  MarkdownLintRecordData
+} from "./package-checks/markdown-lint/records.ts";
+export type { MarkdownLintUnavailableReason } from "./package-checks/markdown-lint/execution.ts";
 export { markdownLinkValidation } from "./package-checks/markdown-link-validation/default-check.ts";
 export { parseMarkdownLinkValidationData } from "./package-checks/markdown-link-validation/final-data.ts";
 export type { MarkdownLinkValidationFinalData } from "./package-checks/markdown-link-validation/final-data.ts";
@@ -81,7 +155,8 @@ export type { MarkdownLinkValidationUnavailableReason } from "./package-checks/m
 export type { MarkdownLinkValidationRecordData } from "./package-checks/markdown-link-validation/records.ts";
 export type { MarkdownLinkFindingReason } from "./package-checks/markdown-link-validation/local-resolver.ts";
 export type { FindingPolicy } from "./package-checks/code-quality-findings/policy.ts";
-export { reconcileFindingWaivers } from "./finding-waivers/reconciliation.ts";
+export { reconcileFindingWaivers } from "./package-tools/finding-waivers/reconciliation.ts";
+export { presentCheckFindings } from "./package-tools/finding-presentation/finding-presentation.ts";
 export type {
   FindingWaiver,
   FindingWaiverAudit,
@@ -89,35 +164,89 @@ export type {
   MaterializedFindingWaiver,
   ReconciledFinding,
   ReconcileFindingWaiversOptions
-} from "./finding-waivers/reconciliation.ts";
+} from "./package-tools/finding-waivers/reconciliation.ts";
 export { defaultProjectFileSelection } from "./package-checks/project-files/configuration.ts";
+export { collectProjectFiles } from "./package-checks/project-files/public-collection.ts";
+export type { CollectProjectFilesOptions } from "./package-checks/project-files/public-collection.ts";
 export type {
   ProjectFileSelection,
   ProjectFileSelectionOptions,
   ProjectFileSource
 } from "./package-checks/project-files/configuration.ts";
 export { defineCheck, inherit } from "./check/check.ts";
+export { all, any, changeFlag, exactlyOne, none, not, notAll } from "./check/flag-enablement.ts";
 export type {
   Check,
+  CheckDependencies,
   CheckExecution,
   CheckExecutionContext,
-  CheckPreflight,
-  CheckPreflightResult,
+  CheckFlagCondition,
+  CheckFlagEnablement,
+  CheckPreparation,
+  CheckPreparationResult,
+  CheckProjectContext,
+  CheckResourceClaims,
   CheckOutcome,
+  ProjectChanges,
   CheckResult,
   CheckUnavailableReason,
   InheritableCheckCollection
 } from "./check/check.ts";
+export { defineAdmissionPolicy } from "./package-tools/admission-policy/define-admission-policy.ts";
 export { defineConfig } from "./project-definition/project-definition.ts";
+export { createLearnedCriticalPathStrategy } from "./package-tools/learned-critical-path/strategy.ts";
 export type {
+  LearnedCriticalPathObservation,
+  LearnedCriticalPathStrategyOptions
+} from "./package-tools/learned-critical-path/strategy.ts";
+export { createAdmissionGraph } from "./project-run/task-scheduler/admission-core/core.ts";
+export type {
+  AdmissionPolicy,
+  AdmissionPolicyContext,
+  AdmissionPolicyMeasurement,
+  AdmissionProposal,
+  AdmissionCatalog,
+  AdmissionGraph,
+  AdmissionGraphInput,
+  AdmissionInspection,
+  AdmissionNonSelectableTask,
+  AdmissionRejectionReason,
+  AdmissionScopeLifecycle,
+  AdmissionSelectionRejectionReason,
+  AdmissionSelectionValidation,
+  AdmissionSelectionValidationRejectionReason,
+  AdmissionSettlementOutcome,
+  AdmissionSettledTask,
+  AdmissionState,
+  AdmissionTransitionResult,
+  CustomAdmissionPreparationContext,
+  CustomAdmissionStrategy,
+  PreparedCustomAdmissionStrategy,
+  ProgressPreviewFormatter,
   ProjectOutputs,
   ProjectDefinition,
+  SchedulerDecisionMeasurementCumulative,
+  SchedulerGraphSnapshot,
+  SchedulerMeasurementContext,
+  SchedulerTerminalEffect,
+  SchedulerMeasurementIntervalContribution,
+  SchedulerMeasurementActionObservationInterval,
+  SchedulerMeasurementActionObservation,
+  SchedulerMeasurementEffect,
+  SchedulerRawMeasurement,
   SchedulerPolicy
 } from "./project-definition/project-definition.ts";
+export type {
+  ProjectChangeFlagRegion,
+  ProjectChangeSource,
+  ProjectChangesConfiguration
+} from "./project-definition/project-changes.ts";
+export type { CoreCheck } from "./check-settlement/facts.ts";
 export type {
   CheckAggregate,
   CheckAggregation,
   RunControls
 } from "./project-run/controls/contract.ts";
 export { run } from "./project-run/run.ts";
+export type { RunOutputStatus, RunOutputStatuses } from "./project-run/outputs/status.ts";
 export type { RunResult } from "./project-run/result.ts";

package/src/machine-output/v4/atomic-publication.ts

@@ -3,12 +3,6 @@ import fs from "node:fs";
 import { join } from "node:path";
 
 const CANONICAL_NAMES = ["records.ndjson", "run.json"] as const;
-const RETIRED_NAMES = [
-  "metrics.json",
-  "report.md",
-  "warnings-all.ndjson",
-  "warnings.ndjson"
-] as const;
 const OWNED_TEMP_PREFIX = ".vibe-check-publication-";
 
 interface PublicationCandidatePath {
@@ -39,7 +33,6 @@ export function publishPublicationCandidatesV4(
       fs.renameSync(file.temp, file.canonical);
       hasReplacedCanonicalPath = true;
     }
-    cleanupRetiredArtifacts(artifactDir);
   } catch (error: unknown) {
     if (hasReplacedCanonicalPath) cleanupPublicationV4BestEffort(artifactDir);
     else cleanupOwnedTempsBestEffort(artifactDir);
@@ -48,11 +41,7 @@ export function publishPublicationCandidatesV4(
 }
 
 export function cleanupPublicationV4(artifactDir: string): void {
-  removePaths([
-    ...artifactPaths(artifactDir, CANONICAL_NAMES),
-    ...artifactPaths(artifactDir, RETIRED_NAMES),
-    ...ownedTempPaths(artifactDir)
-  ]);
+  removePaths([...artifactPaths(artifactDir, CANONICAL_NAMES), ...ownedTempPaths(artifactDir)]);
 }
 
 export function cleanupPublicationV4BestEffort(artifactDir: string): void {
@@ -94,10 +83,6 @@ function cleanupOwnedTempsBestEffort(artifactDir: string): void {
   }
 }
 
-function cleanupRetiredArtifacts(artifactDir: string): void {
-  removePaths(artifactPaths(artifactDir, RETIRED_NAMES));
-}
-
 function artifactPaths(artifactDir: string, names: readonly string[]): readonly string[] {
   return names.map((name) => join(artifactDir, name));
 }
@@ -119,5 +104,7 @@ function removePaths(paths: readonly string[]): void {
       firstFailure ??= error;
     }
   }
-  if (firstFailure !== undefined) throw firstFailure;
+  if (firstFailure === undefined) return;
+  if (firstFailure instanceof Error) throw firstFailure;
+  throw new Error("publication cleanup failed", { cause: firstFailure });
 }

package/src/package-checks/check-authoring.ts

@@ -0,0 +1,136 @@
+import type {
+  Check,
+  CheckFlagEnablement,
+  CheckResourceClaims,
+  InheritableCheckCollection
+} from "../check/check.ts";
+import { snapshotClosedArray, snapshotClosedPolicyRecord } from "../data-boundary/closed-values.ts";
+import { parseFlagEnablementControl } from "../project-definition/check-tree/check-fields-authoring.ts";
+import { parseCheckScheduling } from "../project-definition/check-tree/scheduling-authoring.ts";
+
+/** 固定身份随包 Check 构造器与领域 policy 并列接收的项目声明字段；Project Definition 保留语义校验所有权。 */
+export interface PackageCheckAuthoringOptions<Id extends string = string> {
+  /** Overrides the constructor's package default identity. */
+  readonly checkId?: Id;
+  /** Overrides the constructor's package default presentation name. */
+  readonly displayName?: string;
+  readonly enabledByFlags?: CheckFlagEnablement;
+  readonly checks?: readonly Check[];
+  readonly dependsOn?: InheritableCheckCollection<string>;
+  readonly observes?: InheritableCheckCollection<string>;
+  readonly maxParallel?: number;
+  readonly admissionPriority?: number;
+  readonly mutex?: InheritableCheckCollection<string>;
+  readonly resourceClaims?: CheckResourceClaims;
+  /** `false` explicitly restores the package default of rendering quiet passed rows. */
+  readonly omitQuietPassedRow?: boolean;
+}
+
+/** 自定义随包 Check identity 时必须声明与返回类型一致的 runtime `checkId`。 */
+export type PackageCheckIdentityInput<Id extends string> = Readonly<{ readonly checkId: Id }>;
+
+const PACKAGE_CHECK_AUTHORING_KEYS = [
+  "admissionPriority",
+  "checkId",
+  "checks",
+  "dependsOn",
+  "displayName",
+  "enabledByFlags",
+  "maxParallel",
+  "mutex",
+  "observes",
+  "omitQuietPassedRow",
+  "resourceClaims"
+] as const;
+
+type PackageCheckDefinition<Id extends string> = Readonly<{
+  readonly checkId: Id;
+  readonly displayName: string;
+  readonly enabledByFlags?: CheckFlagEnablement;
+  readonly checks?: readonly Check[];
+  readonly dependsOn?: InheritableCheckCollection<string>;
+  readonly observes?: InheritableCheckCollection<string>;
+  readonly maxParallel?: number;
+  readonly admissionPriority?: number;
+  readonly mutex?: InheritableCheckCollection<string>;
+  readonly resourceClaims?: CheckResourceClaims;
+  readonly omitQuietPassedRow?: true;
+}>;
+
+/** 对一个 closed 构造输入执行安全 shape 校验，并分流领域 policy 与普通 Check 声明字段。 */
+export function resolvePackageCheckAuthoringInput<const Id extends string>(
+  input: PackageCheckAuthoringOptions<Id> & object,
+  domainKeys: readonly string[],
+  defaults: Readonly<{
+    readonly checkId: string;
+    readonly displayName: string;
+    readonly omitQuietPassedRow?: true;
+  }>
+):
+  | Readonly<{
+      readonly definition: PackageCheckDefinition<Id>;
+      readonly domainOptions: Readonly<Record<string, unknown>>;
+    }>
+  | undefined {
+  const snapshot = snapshotClosedPolicyRecord(input, {
+    optional: [...domainKeys, ...PACKAGE_CHECK_AUTHORING_KEYS]
+  });
+  if (snapshot === undefined) return undefined;
+
+  const checkId = snapshot.checkId ?? defaults.checkId;
+  const displayName = snapshot.displayName ?? defaults.displayName;
+  if (!isNonEmptyString(checkId) || !isNonEmptyString(displayName)) return undefined;
+  if (
+    (snapshot.omitQuietPassedRow !== undefined &&
+      typeof snapshot.omitQuietPassedRow !== "boolean") ||
+    !hasSafeProjectFieldShapes(snapshot)
+  ) {
+    return undefined;
+  }
+  const omitQuietPassedRow =
+    snapshot.omitQuietPassedRow === undefined
+      ? defaults.omitQuietPassedRow === true
+      : snapshot.omitQuietPassedRow === true;
+
+  const domainOptions = Object.freeze(
+    Object.fromEntries(
+      domainKeys.flatMap((key) => (Object.hasOwn(snapshot, key) ? [[key, snapshot[key]]] : []))
+    )
+  );
+  const definition = Object.freeze({
+    ...(snapshot.admissionPriority === undefined
+      ? {}
+      : { admissionPriority: snapshot.admissionPriority }),
+    ...(snapshot.checks === undefined ? {} : { checks: snapshot.checks }),
+    ...(snapshot.dependsOn === undefined ? {} : { dependsOn: snapshot.dependsOn }),
+    ...(snapshot.enabledByFlags === undefined ? {} : { enabledByFlags: snapshot.enabledByFlags }),
+    ...(snapshot.maxParallel === undefined ? {} : { maxParallel: snapshot.maxParallel }),
+    ...(snapshot.mutex === undefined ? {} : { mutex: snapshot.mutex }),
+    ...(snapshot.observes === undefined ? {} : { observes: snapshot.observes }),
+    ...(omitQuietPassedRow ? { omitQuietPassedRow: true as const } : {}),
+    ...(snapshot.resourceClaims === undefined ? {} : { resourceClaims: snapshot.resourceClaims }),
+    // Runtime defaults are strings; constructor signatures bind this field to the input literal type.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- The runtime default is fixed by the constructor, while the public signature retains an input literal ID.
+    checkId: checkId as Id,
+    displayName
+  }) satisfies PackageCheckDefinition<Id>;
+  return Object.freeze({ definition, domainOptions });
+}
+
+function hasSafeProjectFieldShapes(
+  input: Readonly<Record<string, unknown>>
+): input is Readonly<Record<string, unknown>> & PackageCheckAuthoringOptions {
+  const scheduling = parseCheckScheduling(input);
+  if (scheduling === undefined) return false;
+  if (
+    input.enabledByFlags !== undefined &&
+    parseFlagEnablementControl(input.enabledByFlags) === undefined
+  ) {
+    return false;
+  }
+  return input.checks === undefined || snapshotClosedArray(input.checks) !== undefined;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}

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

@@ -0,0 +1,46 @@
+import { canonicalJsonText } from "../../data-boundary/canonical-data.ts";
+import {
+  snapshotClosedArray,
+  snapshotClosedPolicyRecord
+} from "../../data-boundary/closed-values.ts";
+import { isNonEmptyString } from "../../data-boundary/value-shapes.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
+
+/**
+ * Snapshots the shared closed waiver envelope while leaving identity grammar to the producing Check.
+ */
+export function resolveFindingWaiverAuthoring<Identity>(
+  value: unknown,
+  resolveIdentity: (value: unknown) => Identity | undefined
+): readonly FindingWaiver<Identity>[] | undefined {
+  if (value === undefined) return Object.freeze([]);
+  const candidates = snapshotClosedArray(value);
+  if (candidates === undefined) return undefined;
+
+  const waivers: FindingWaiver<Identity>[] = [];
+  const seenIdentities = new Set<string>();
+  for (const candidate of candidates) {
+    const authored = snapshotClosedPolicyRecord(candidate, { required: ["identity", "reason"] });
+    if (authored === undefined || !isNonEmptyString(authored.reason)) return undefined;
+    const identity = resolveIdentity(authored.identity);
+    if (identity === undefined) return undefined;
+    let identityKey: string;
+    try {
+      identityKey = canonicalJsonText(identity);
+    } catch {
+      return undefined;
+    }
+    if (seenIdentities.has(identityKey)) return undefined;
+    seenIdentities.add(identityKey);
+    waivers.push(Object.freeze({ identity, reason: authored.reason }));
+  }
+  return Object.freeze(waivers);
+}
+
+/** Validates the complete resolved waiver list through the same authoring boundary. */
+export function validResolvedFindingWaivers<Identity>(
+  value: unknown,
+  resolveIdentity: (value: unknown) => Identity | undefined
+): value is readonly FindingWaiver<Identity>[] {
+  return value !== undefined && resolveFindingWaiverAuthoring(value, resolveIdentity) !== undefined;
+}