@zxyycom/vibe-check 0.0.1

package/src/finding-waivers/reconciliation.ts

@@ -0,0 +1,176 @@
+import {
+  canonicalizeJsonValue,
+  canonicalJsonText,
+  type CanonicalJsonObject,
+  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 function reconcileFindingWaivers<Finding, Identity>(
+  options: ReconcileFindingWaiversOptions<Finding, Identity>
+): FindingWaiverReconciliation<Finding> {
+  const waivers = materializeWaivers(options.waivers);
+  const matchCounts = new Array<number>(waivers.length).fill(0);
+  const waiverIndexesByIdentity = new Map<string, number>();
+  for (const [index, waiver] of waivers.entries()) {
+    const identity = canonicalIdentity(waiver.identity, "waiver identity");
+    if (waiverIndexesByIdentity.has(identity)) {
+      throw new TypeError("Finding waivers must not declare duplicate canonical identities");
+    }
+    waiverIndexesByIdentity.set(identity, index);
+  }
+
+  const matchedWaiverIndexes = options.findings.map((finding) => {
+    const identity = canonicalIdentity(options.identify(finding), "finding identity");
+    const waiverIndex = waiverIndexesByIdentity.get(identity);
+    if (waiverIndex !== undefined) matchCounts[waiverIndex] += 1;
+    return waiverIndex;
+  });
+  const waiverAudits = Object.freeze(
+    waivers.map((waiver, index) =>
+      Object.freeze({
+        matchCount: matchCounts[index] ?? 0,
+        status: waiverAuditStatus(matchCounts[index] ?? 0),
+        waiver
+      })
+    )
+  );
+  const findings = Object.freeze(
+    options.findings.map((finding, index) => {
+      const waiverIndex = matchedWaiverIndexes[index];
+      const audit = waiverIndex === undefined ? undefined : waiverAudits[waiverIndex];
+      return reconciledFinding(finding, audit);
+    })
+  );
+  return Object.freeze({ findings, waiverAudits });
+}
+
+function materializeWaivers<Identity>(
+  waivers: readonly FindingWaiver<Identity>[]
+): readonly MaterializedFindingWaiver[] {
+  const canonicalWaivers = canonicalizeJsonValue(waivers);
+  if (canonicalWaivers === undefined || !isCanonicalArray(canonicalWaivers)) {
+    throw new TypeError("Finding waivers must be canonical JSON arrays");
+  }
+  return Object.freeze(canonicalWaivers.map(materializeWaiver));
+}
+
+function materializeWaiver(value: CanonicalJsonValue): MaterializedFindingWaiver {
+  if (
+    !isCanonicalObject(value) ||
+    !Object.hasOwn(value, "identity") ||
+    !Object.hasOwn(value, "reason")
+  ) {
+    throw new TypeError("Finding waivers must declare canonical identity and reason fields");
+  }
+  const reason = value.reason;
+  if (typeof reason !== "string" || reason.length === 0) {
+    throw new TypeError("Finding waiver reasons must be non-empty strings");
+  }
+  return Object.freeze({ identity: value.identity, reason });
+}
+
+function isCanonicalObject(value: CanonicalJsonValue): value is CanonicalJsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isCanonicalArray(value: CanonicalJsonValue): value is readonly CanonicalJsonValue[] {
+  return Array.isArray(value);
+}
+
+function canonicalIdentity(identity: unknown, kind: string): string {
+  try {
+    return canonicalJsonText(identity);
+  } catch {
+    throw new TypeError(`Finding ${kind} must be canonical JSON`);
+  }
+}
+
+function waiverAuditStatus(matchCount: number): FindingWaiverAudit["status"] {
+  if (matchCount === 0) return "unused";
+  return matchCount === 1 ? "applied" : "overmatched";
+}
+
+function reconciledFinding<Finding>(
+  finding: Finding,
+  audit: FindingWaiverAudit | undefined
+): ReconciledFinding<Finding> {
+  if (audit === undefined) return Object.freeze({ disposition: "actionable", finding });
+  if (audit.status === "applied") {
+    return Object.freeze({ disposition: "waived", finding, waiver: audit.waiver });
+  }
+  return Object.freeze({ disposition: "overmatched", finding });
+}

package/src/index.ts

@@ -0,0 +1,123 @@
+/**
+ * Vibe Check 是由项目在 Bun runtime 中调用的 TypeScript API，用于定义并执行项目质量 Check。
+ * 所有公开能力从 package root 导入；package `README.md` 说明 consumer authoring、结果读取和分发范围。
+ *
+ * @packageDocumentation
+ */
+export { duplicateDetection } from "./package-checks/duplicate-detection/default-check.ts";
+export { parseDuplicateDetectionData } from "./package-checks/duplicate-detection/final-data.ts";
+export type { DuplicateDetectionFinalData } from "./package-checks/duplicate-detection/final-data.ts";
+export type {
+  DuplicateDetectionOptions,
+  ResolvedDuplicateDetectionOptions
+} from "./package-checks/duplicate-detection/options.ts";
+export type { DuplicateDetectionUnavailableReasonCode } from "./package-checks/duplicate-detection/execution.ts";
+export type { DuplicateDetectionRecordData } from "./package-checks/duplicate-detection/records.ts";
+export { fileMetrics } from "./package-checks/file-metrics/constructor.ts";
+export { parseFileMetricsData } from "./package-checks/file-metrics/final-data.ts";
+export type { FileMetricsFinalData } from "./package-checks/file-metrics/final-data.ts";
+export type {
+  FileMetricsFindingIdentity,
+  FileMetricsFindingWaiver,
+  FileMetricsOptions,
+  ResolvedFileMetricsOptions
+} from "./package-checks/file-metrics/options.ts";
+export type { FileMetricsUnavailableReasonCode } from "./package-checks/file-metrics/execution.ts";
+export type { FileMetricsRecordData } from "./package-checks/file-metrics/records.ts";
+export { functionMetrics } from "./package-checks/function-metrics/constructor.ts";
+export { parseFunctionMetricsData } from "./package-checks/function-metrics/final-data.ts";
+export type { FunctionMetricsFinalData } from "./package-checks/function-metrics/final-data.ts";
+export type {
+  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 { 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 {
+  JsonSchemaValidationOptions,
+  ResolvedJsonSchemaValidationOptions
+} from "./package-checks/json-schema-validation/options.ts";
+export type {
+  JsonSchemaDocumentReason,
+  JsonSchemaValidationRecordData,
+  JsonSchemaValidationRecordReason,
+  JsonSchemaValidationUnavailableCode
+} from "./package-checks/json-schema-validation/json-schema-validation.ts";
+export { jsonValidation } from "./package-checks/json-validation/default-check.ts";
+export { parseJsonValidationData } from "./package-checks/json-validation/final-data.ts";
+export type { JsonValidationFinalData } from "./package-checks/json-validation/final-data.ts";
+export type {
+  JsonValidationOptions,
+  ResolvedJsonValidationOptions
+} from "./package-checks/json-validation/options.ts";
+export type {
+  JsonValidationRecordData,
+  JsonValidationRecordReason,
+  JsonValidationUnavailableCode
+} from "./package-checks/json-validation/json-validation.ts";
+export { maintenanceReminders } from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
+export type {
+  MaintenanceReminder,
+  MaintenanceReminderOptions,
+  MaintenanceRemindersUnavailableCode
+} from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
+export { parseMaintenanceRemindersData } from "./package-checks/maintenance-reminders/final-data.ts";
+export type {
+  MaintenanceReminderAssessment,
+  MaintenanceReminderUnavailableReason,
+  MaintenanceRemindersFinalData
+} from "./package-checks/maintenance-reminders/final-data.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";
+export type {
+  MarkdownLinkValidationOptions,
+  ResolvedMarkdownLinkValidationOptions
+} from "./package-checks/markdown-link-validation/options.ts";
+export type { MarkdownLinkValidationUnavailableReason } from "./package-checks/markdown-link-validation/execution.ts";
+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 type {
+  FindingWaiver,
+  FindingWaiverAudit,
+  FindingWaiverReconciliation,
+  MaterializedFindingWaiver,
+  ReconciledFinding,
+  ReconcileFindingWaiversOptions
+} from "./finding-waivers/reconciliation.ts";
+export { defaultProjectFileSelection } from "./package-checks/project-files/configuration.ts";
+export type {
+  ProjectFileSelection,
+  ProjectFileSelectionOptions,
+  ProjectFileSource
+} from "./package-checks/project-files/configuration.ts";
+export { defineCheck, inherit } from "./check/check.ts";
+export type {
+  Check,
+  CheckExecution,
+  CheckExecutionContext,
+  CheckPreflight,
+  CheckPreflightResult,
+  CheckOutcome,
+  CheckResult,
+  CheckUnavailableReason,
+  InheritableCheckCollection
+} from "./check/check.ts";
+export { defineConfig } from "./project-definition/project-definition.ts";
+export type {
+  ProjectOutputs,
+  ProjectDefinition,
+  SchedulerPolicy
+} from "./project-definition/project-definition.ts";
+export type {
+  CheckAggregate,
+  CheckAggregation,
+  RunControls
+} from "./project-run/controls/contract.ts";
+export { run } from "./project-run/run.ts";
+export type { RunResult } from "./project-run/result.ts";

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

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+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 {
+  readonly canonical: string;
+  readonly contents: string;
+  readonly temp: string;
+}
+
+interface PublicationCandidates {
+  readonly recordsNdjson: string;
+  readonly runJson: string;
+}
+
+/** Writes an already validated two-file candidate set through owned temporary paths. */
+export function publishPublicationCandidatesV4(
+  artifactDir: string,
+  candidates: PublicationCandidates
+): void {
+  fs.mkdirSync(artifactDir, { recursive: true });
+  const files = publicationCandidatePaths(artifactDir, randomUUID(), candidates);
+  let hasReplacedCanonicalPath = false;
+  try {
+    cleanupOwnedTemps(artifactDir);
+    for (const file of files) {
+      fs.writeFileSync(file.temp, file.contents, { encoding: "utf8", flag: "wx" });
+    }
+    for (const file of files) {
+      fs.renameSync(file.temp, file.canonical);
+      hasReplacedCanonicalPath = true;
+    }
+    cleanupRetiredArtifacts(artifactDir);
+  } catch (error: unknown) {
+    if (hasReplacedCanonicalPath) cleanupPublicationV4BestEffort(artifactDir);
+    else cleanupOwnedTempsBestEffort(artifactDir);
+    throw error;
+  }
+}
+
+export function cleanupPublicationV4(artifactDir: string): void {
+  removePaths([
+    ...artifactPaths(artifactDir, CANONICAL_NAMES),
+    ...artifactPaths(artifactDir, RETIRED_NAMES),
+    ...ownedTempPaths(artifactDir)
+  ]);
+}
+
+export function cleanupPublicationV4BestEffort(artifactDir: string): void {
+  try {
+    cleanupPublicationV4(artifactDir);
+  } catch {
+    // Failure cleanup cannot conceal the original publication failure.
+  }
+}
+
+function publicationCandidatePaths(
+  artifactDir: string,
+  token: string,
+  candidates: PublicationCandidates
+): readonly PublicationCandidatePath[] {
+  return [
+    {
+      canonical: join(artifactDir, "run.json"),
+      contents: candidates.runJson,
+      temp: join(artifactDir, `.vibe-check-publication-${token}-run.json.tmp`)
+    },
+    {
+      canonical: join(artifactDir, "records.ndjson"),
+      contents: candidates.recordsNdjson,
+      temp: join(artifactDir, `.vibe-check-publication-${token}-records.ndjson.tmp`)
+    }
+  ];
+}
+
+function cleanupOwnedTemps(artifactDir: string): void {
+  removePaths(ownedTempPaths(artifactDir));
+}
+
+function cleanupOwnedTempsBestEffort(artifactDir: string): void {
+  try {
+    cleanupOwnedTemps(artifactDir);
+  } catch {
+    // Failure cleanup cannot conceal the original publication failure.
+  }
+}
+
+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));
+}
+
+function ownedTempPaths(artifactDir: string): readonly string[] {
+  return fs
+    .readdirSync(artifactDir, { withFileTypes: true })
+    .filter((entry) => entry.name.startsWith(OWNED_TEMP_PREFIX))
+    .map((entry) => join(artifactDir, entry.name))
+    .sort();
+}
+
+function removePaths(paths: readonly string[]): void {
+  let firstFailure: unknown;
+  for (const path of paths) {
+    try {
+      fs.rmSync(path, { force: true, recursive: true });
+    } catch (error: unknown) {
+      firstFailure ??= error;
+    }
+  }
+  if (firstFailure !== undefined) throw firstFailure;
+}

package/src/machine-output/v4/freeze-publication-value.ts

@@ -0,0 +1,12 @@
+/**
+ * Output projections are validated or freshly constructed plain data. Freeze
+ * them before they cross a publication boundary so later consumers cannot
+ * drift from the one validated model.
+ */
+export function freezePublicationValue<T>(value: T): T {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) freezePublicationValue(child);
+  }
+  return value;
+}

package/src/machine-output/v4/projection.ts

@@ -0,0 +1,36 @@
+import { MACHINE_RECORD_V4_IDENTITY, MACHINE_RUN_V4_IDENTITY } from "./schema-identities.ts";
+import type { TrustedPublicationModelV4 } from "./publication-model.ts";
+import { createRecordsFingerprintV4 } from "./records-fingerprint.ts";
+import type { MachineRecordV4, MachineRunV4 } from "./schema.ts";
+import { freezePublicationValue } from "./freeze-publication-value.ts";
+
+export interface MachinePublicationV4 {
+  readonly records: readonly MachineRecordV4[];
+  readonly run: MachineRunV4;
+}
+
+export function projectMachinePublicationV4(
+  model: TrustedPublicationModelV4
+): MachinePublicationV4 {
+  const records = Object.freeze(
+    model.snapshot.records.map((record): MachineRecordV4 =>
+      freezePublicationValue({
+        checkId: record.checkId,
+        data: record.data,
+        id: record.id,
+        schemaVersion: MACHINE_RECORD_V4_IDENTITY
+      })
+    )
+  );
+  const run: MachineRunV4 = {
+    checks: model.snapshot.checks.map((check): MachineRunV4["checks"][number] => ({
+      checkId: check.checkId,
+      displayName: check.displayName,
+      outcome: check.outcome
+    })),
+    invocation: { ...model.invocation },
+    recordsFingerprint: createRecordsFingerprintV4(records),
+    schemaVersion: MACHINE_RUN_V4_IDENTITY
+  };
+  return Object.freeze({ records, run: freezePublicationValue(run) });
+}

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

@@ -0,0 +1,89 @@
+import { validateCoreSnapshot } from "../../check-settlement/fact-validation.ts";
+import { createRecordsFingerprintV4 } from "./records-fingerprint.ts";
+import type { MachineRecordV4, MachineRunV4 } from "./schema.ts";
+import { setInvariantFailure, type ValidationFailure } from "./validation-result.ts";
+
+export function validatePublicationInvariants(
+  run: MachineRunV4,
+  records: readonly MachineRecordV4[]
+): ValidationFailure | null {
+  const checkOrder = validateCheckOrder(run);
+  if (checkOrder !== null) return checkOrder;
+  const recordOrder = validateRecordOrder(records);
+  if (recordOrder !== null) return recordOrder;
+  const ownership = validateRecordOwnership(run, records);
+  if (ownership !== null) return ownership;
+  const core = validateProjectedCore(run, records);
+  if (core !== null) return core;
+  return createRecordsFingerprintV4(records) === run.recordsFingerprint
+    ? null
+    : setInvariantFailure(
+        "records-fingerprint",
+        "records.ndjson",
+        "Records fingerprint must match the complete canonical Record row set."
+      );
+}
+
+function validateCheckOrder(run: MachineRunV4): ValidationFailure | null {
+  let previous: string | undefined;
+  for (const check of run.checks) {
+    if (previous !== undefined && previous >= check.checkId) {
+      return setInvariantFailure(
+        "check-canonical-order",
+        "run.json",
+        "Checks must be uniquely sorted by checkId."
+      );
+    }
+    previous = check.checkId;
+  }
+  return null;
+}
+
+function validateRecordOrder(records: readonly MachineRecordV4[]): ValidationFailure | null {
+  let previous: readonly [string, string] | undefined;
+  for (const [index, record] of records.entries()) {
+    const current = [record.checkId, record.id] as const;
+    if (
+      previous !== undefined &&
+      (previous[0] > current[0] || (previous[0] === current[0] && previous[1] >= current[1]))
+    ) {
+      return setInvariantFailure(
+        "record-canonical-order",
+        "records.ndjson",
+        "Records must be uniquely sorted by the composite { checkId, id } identity.",
+        index
+      );
+    }
+    previous = current;
+  }
+  return null;
+}
+
+function validateRecordOwnership(
+  run: MachineRunV4,
+  records: readonly MachineRecordV4[]
+): ValidationFailure | null {
+  const knownChecks = new Set(run.checks.map((check) => check.checkId));
+  const unknownIndex = records.findIndex((record) => !knownChecks.has(record.checkId));
+  return unknownIndex === -1
+    ? null
+    : setInvariantFailure(
+        "record-check-ownership",
+        "records.ndjson",
+        "Every Record must name a published owning Check.",
+        unknownIndex
+      );
+}
+
+function validateProjectedCore(
+  run: MachineRunV4,
+  records: readonly MachineRecordV4[]
+): ValidationFailure | null {
+  const snapshot = validateCoreSnapshot({
+    checks: run.checks,
+    records: records.map(({ schemaVersion: _schemaVersion, ...record }) => record)
+  });
+  return snapshot.ok
+    ? null
+    : setInvariantFailure("core-snapshot", "run.json", "Published Core facts are invalid.");
+}

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

@@ -0,0 +1,38 @@
+import type { CoreSnapshot } from "../../check-settlement/facts.ts";
+import { MACHINE_V4_TIMESTAMP_PATTERN } from "./schema-identities.ts";
+
+const machineV4TimestampPattern = new RegExp(MACHINE_V4_TIMESTAMP_PATTERN);
+
+export interface PublicationInvocationV4 {
+  readonly invocationId: string;
+  readonly projectRoot: ".";
+  readonly timestamp: string;
+}
+
+/** Trusted Core facts and validated invocation metadata for v4 candidate projection. */
+export interface TrustedPublicationModelV4 {
+  readonly invocation: PublicationInvocationV4;
+  readonly snapshot: CoreSnapshot;
+}
+
+export function createPublicationModelV4(
+  input: Readonly<{ invocation: PublicationInvocationV4; snapshot: CoreSnapshot }>
+): TrustedPublicationModelV4 {
+  validateInvocation(input.invocation);
+  return Object.freeze({
+    invocation: Object.freeze({ ...input.invocation }),
+    snapshot: input.snapshot
+  });
+}
+
+function validateInvocation(invocation: PublicationInvocationV4): void {
+  if (
+    typeof invocation.invocationId !== "string" ||
+    invocation.invocationId.length === 0 ||
+    invocation.projectRoot !== "." ||
+    typeof invocation.timestamp !== "string" ||
+    !machineV4TimestampPattern.test(invocation.timestamp)
+  ) {
+    throw new TypeError("Publication invocation metadata is invalid");
+  }
+}

package/src/machine-output/v4/publish.ts

@@ -0,0 +1,23 @@
+import { projectMachinePublicationV4 } from "./projection.ts";
+import { serializeMachinePublicationV4 } from "./serializers.ts";
+import { validateMachinePublicationSetV4 } from "./validation.ts";
+import { type TrustedPublicationModelV4 } from "./publication-model.ts";
+import { publishPublicationCandidatesV4 } from "./atomic-publication.ts";
+
+export { cleanupPublicationV4, cleanupPublicationV4BestEffort } from "./atomic-publication.ts";
+
+/** Publishes only the validated two-file machine set; human projection is not a v4 concern. */
+export function publishScanV4(
+  input: Readonly<{ artifactDir: string; model: TrustedPublicationModelV4 }>
+): void {
+  const machine = projectMachinePublicationV4(input.model);
+  const candidates = serializeMachinePublicationV4(machine);
+  const validation = validateMachinePublicationSetV4({
+    recordsNdjson: Buffer.from(candidates.recordsNdjson, "utf8"),
+    runJson: Buffer.from(candidates.runJson, "utf8")
+  });
+  if (!validation.ok) {
+    throw new Error(`Machine publication v4 validation failed: ${validation.diagnostic.message}`);
+  }
+  publishPublicationCandidatesV4(input.artifactDir, candidates);
+}

package/src/machine-output/v4/records-fingerprint.ts

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+
+import { canonicalJsonBytes } from "../../data-boundary/canonical-data.ts";
+import type { MachineRecordV4 } from "./schema.ts";
+
+export const MACHINE_RECORDS_V4_FINGERPRINT_PREFIX = "check-record/v2/records/sha256:";
+
+/** Binds the complete, canonically ordered v4 Record row set, including empty. */
+export function createRecordsFingerprintV4(records: readonly MachineRecordV4[]): string {
+  const bytes = canonicalJsonBytes(records);
+  return `${MACHINE_RECORDS_V4_FINGERPRINT_PREFIX}${createHash("sha256").update(bytes).digest("hex")}`;
+}

package/src/machine-output/v4/schema-identities.ts

@@ -0,0 +1,8 @@
+export const MACHINE_RUN_V4_SCHEMA_ID = "urn:vibe-check:schema:run:v4";
+export const MACHINE_RECORD_V4_SCHEMA_ID = "urn:vibe-check:schema:record:v4";
+export const MACHINE_RUN_V4_IDENTITY = "vibe-check.run.v4";
+export const MACHINE_RECORD_V4_IDENTITY = "vibe-check.record.v4";
+export const MACHINE_V4_TIMESTAMP_PATTERN =
+  "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$";
+export const MACHINE_RUN_V4_SCHEMA_PATH = "docs/schemas/vibe-check-run.schema.json";
+export const MACHINE_RECORD_V4_SCHEMA_PATH = "docs/schemas/vibe-check-record.schema.json";