@zxyycom/vibe-check 0.0.1

package/src/check/options-snapshot.ts

@@ -0,0 +1,80 @@
+import { snapshotClosedArray, snapshotClosedRecord } from "../data-boundary/closed-values.ts";
+
+type JsonSnapshot = object | readonly unknown[] | string | number | boolean | null;
+
+/** Copies a closed JSON object without retaining untyped authoring input. */
+export function snapshotJsonObject(value: unknown): object | undefined {
+  const snapshot = snapshotJson(value, new Set<object>());
+  return isJsonObject(snapshot) ? snapshot : undefined;
+}
+
+function isJsonObject(value: JsonSnapshot | undefined): value is object {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function snapshotJson(value: unknown, ancestors: Set<object>): JsonSnapshot | undefined {
+  const primitive = snapshotJsonPrimitive(value);
+  if (primitive !== undefined || value === null) return primitive;
+  if (typeof value !== "object") return undefined;
+  if (ancestors.has(value)) return undefined;
+
+  const items = snapshotClosedArray(value);
+  if (items !== undefined) return snapshotJsonArray(value, items, ancestors);
+
+  const data = snapshotClosedRecord(value);
+  if (data === undefined) return undefined;
+  return snapshotJsonRecord(value, data, ancestors);
+}
+
+function snapshotJsonPrimitive(value: unknown): string | number | boolean | null | undefined {
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return value;
+}
+
+function snapshotJsonArray(
+  value: object,
+  items: readonly unknown[],
+  ancestors: Set<object>
+): readonly JsonSnapshot[] | undefined {
+  ancestors.add(value);
+  try {
+    const snapshot: JsonSnapshot[] = [];
+    for (const item of items) {
+      const parsed = snapshotJson(item, ancestors);
+      if (parsed === undefined) return undefined;
+      snapshot.push(parsed);
+    }
+    return Object.freeze(snapshot);
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function snapshotJsonRecord(
+  value: object,
+  data: Readonly<Record<string, unknown>>,
+  ancestors: Set<object>
+): object | undefined {
+  ancestors.add(value);
+  try {
+    // Assignment to an ordinary object treats an own `__proto__` JSON key as
+    // a prototype mutation. Define the data property so every closed JSON key
+    // remains data and the detached snapshot retains its ordinary prototype.
+    const snapshot: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(data)) {
+      const parsed = snapshotJson(item, ancestors);
+      if (parsed === undefined) return undefined;
+      Object.defineProperty(snapshot, key, {
+        configurable: true,
+        enumerable: true,
+        value: parsed,
+        writable: true
+      });
+    }
+    return Object.freeze(snapshot);
+  } finally {
+    ancestors.delete(value);
+  }
+}

package/src/check-settlement/fact-validation.ts

@@ -0,0 +1,289 @@
+import { canonicalizeJsonObject } from "../data-boundary/canonical-data.ts";
+import type { CheckOutcome } from "../check/check.ts";
+import { validateCheckDescriptor } from "../check/descriptor-validation.ts";
+import type { CoreCheck, CoreRecord, CoreSnapshot } from "./facts.ts";
+import { snapshotClosedArray, snapshotClosedRecord } from "../data-boundary/closed-values.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 function validateCoreSnapshot(value: unknown): ValidationResult<CoreSnapshot> {
+  const snapshot = snapshotClosedRecord(value);
+  if (snapshot === undefined || !hasExactKeys(snapshot, ["checks", "records"])) {
+    return invalid("$", "Core snapshot must contain only checks and records");
+  }
+  const checksInput = snapshotClosedArray(snapshot.checks);
+  const recordsInput = snapshotClosedArray(snapshot.records);
+  if (checksInput === undefined || recordsInput === undefined) {
+    return invalid("$", "Core snapshot entities must be dense arrays");
+  }
+  const checks = validateChecks(checksInput);
+  if (!checks.ok) return checks;
+  const reasonReferences = validateReasonReferences(checks.value);
+  if (!reasonReferences.ok) return reasonReferences;
+  const records = validateRecords(recordsInput, checks.value);
+  if (!records.ok) return records;
+  return accepted(Object.freeze({ checks: checks.value, records: records.value }));
+}
+
+function validateReasonReferences(checks: readonly CoreCheck[]): ValidationResult<void> {
+  const knownCheckIds = new Set(checks.map((check) => check.checkId));
+  for (const [index, check] of checks.entries()) {
+    if (check.outcome.status !== "unavailable" || check.outcome.reason.checkIds === undefined)
+      continue;
+    const seen = new Set<string>();
+    for (const checkId of check.outcome.reason.checkIds) {
+      if (!knownCheckIds.has(checkId) || seen.has(checkId))
+        return invalid(
+          `$.checks[${index}].outcome.reason.checkIds`,
+          "Unavailable reason references are invalid"
+        );
+      seen.add(checkId);
+    }
+  }
+  return accepted(undefined);
+}
+
+function validateChecks(values: readonly unknown[]): ValidationResult<readonly CoreCheck[]> {
+  const checks: CoreCheck[] = [];
+  const checkIds = new Set<string>();
+  let previousCheckId: string | undefined;
+  for (const [index, value] of values.entries()) {
+    const check = snapshotClosedRecord(value);
+    if (check === undefined || !hasExactKeys(check, ["checkId", "displayName", "outcome"])) {
+      return invalid(`$.checks[${index}]`, "Core Check must be closed");
+    }
+    const definition = validateCheckDescriptor({
+      checkId: check.checkId,
+      displayName: check.displayName
+    });
+    if (!definition.ok) return definition;
+    if (checkIds.has(definition.value.checkId)) {
+      return invalid(`$.checks[${index}].checkId`, "Duplicate Core Check checkId", "duplicate");
+    }
+    if (
+      previousCheckId !== undefined &&
+      compareText(previousCheckId, definition.value.checkId) >= 0
+    ) {
+      return invalid(`$.checks[${index}].checkId`, "Core Checks must be sorted by checkId");
+    }
+    const outcome = validateOutcome(check.outcome, `$.checks[${index}].outcome`);
+    if (!outcome.ok) return outcome;
+    checks.push(Object.freeze({ ...definition.value, outcome: outcome.value }));
+    checkIds.add(definition.value.checkId);
+    previousCheckId = definition.value.checkId;
+  }
+  return accepted(Object.freeze(checks));
+}
+
+function validateRecords(
+  values: readonly unknown[],
+  checks: readonly CoreCheck[]
+): ValidationResult<readonly CoreRecord[]> {
+  const ownerIds = new Set(checks.map((check) => check.checkId));
+  const recordIdsByCheckId = new Map<string, Set<string>>();
+  const records: CoreRecord[] = [];
+  let previous: Readonly<{ readonly checkId: string; readonly id: string }> | undefined;
+  for (const [index, value] of values.entries()) {
+    const record = validateRecordRow(value, index, ownerIds);
+    if (!record.ok) return record;
+    const current = record.value;
+    const ids = recordIdsByCheckId.get(current.checkId) ?? new Set<string>();
+    if (ids.has(current.id)) {
+      return invalid(`$.records[${index}].id`, "Duplicate Check-local Record id", "duplicate");
+    }
+    if (
+      previous !== undefined &&
+      (compareText(previous.checkId, current.checkId) > 0 ||
+        (previous.checkId === current.checkId && compareText(previous.id, current.id) >= 0))
+    ) {
+      return invalid(`$.records[${index}]`, "Core Records must be sorted by checkId then id");
+    }
+    ids.add(current.id);
+    recordIdsByCheckId.set(current.checkId, ids);
+    records.push(current);
+    previous = { checkId: current.checkId, id: current.id };
+  }
+  return accepted(Object.freeze(records));
+}
+
+function validateRecordRow(
+  value: unknown,
+  index: number,
+  ownerIds: ReadonlySet<string>
+): ValidationResult<CoreRecord> {
+  const record = snapshotClosedRecord(value);
+  if (record === undefined || !hasExactKeys(record, ["checkId", "id", "data"]))
+    return invalid(`$.records[${index}]`, "Core Record must be closed");
+  if (
+    typeof record.checkId !== "string" ||
+    !ownerIds.has(record.checkId) ||
+    typeof record.id !== "string" ||
+    record.id.length === 0
+  ) {
+    return invalid(`$.records[${index}]`, "Core Record identity is invalid", "identity-mismatch");
+  }
+  const data = canonicalizeJsonObject(record.data);
+  return data === undefined
+    ? invalid(`$.records[${index}].data`, "Core Record data is invalid")
+    : accepted(Object.freeze({ checkId: record.checkId, id: record.id, data }));
+}
+
+function validateOutcome(value: unknown, path: string): ValidationResult<CheckOutcome> {
+  const outcome = snapshotClosedRecord(value);
+  if (outcome === undefined || typeof outcome.status !== "string") {
+    return invalid(path, "Check outcome is invalid");
+  }
+  if (outcome.status === "passed" || outcome.status === "failed")
+    return validateFinalOutcome(outcome, path);
+  if (outcome.status === "not-applicable") return validateNotApplicableOutcome(outcome, path);
+  if (outcome.status === "unavailable") return validateUnavailableOutcome(outcome, path);
+  return invalid(`${path}.status`, "Unknown Check outcome status");
+}
+
+function validateFinalOutcome(
+  outcome: Readonly<Record<string, unknown>>,
+  path: string
+): ValidationResult<CheckOutcome> {
+  if (outcome.status === "passed" || outcome.status === "failed") {
+    if (!hasExactKeys(outcome, ["status", "data"]))
+      return invalid(path, "Final outcome is not closed");
+    const data = canonicalizeJsonObject(outcome.data);
+    return data === undefined
+      ? invalid(`${path}.data`, "Final data is invalid")
+      : accepted(Object.freeze({ status: outcome.status, data }));
+  }
+  return invalid(`${path}.status`, "Unknown Check outcome status");
+}
+
+function validateNotApplicableOutcome(
+  outcome: Readonly<Record<string, unknown>>,
+  path: string
+): ValidationResult<CheckOutcome> {
+  if (!hasOptionalKeys(outcome, ["status"], ["reason"]))
+    return invalid(path, "Not-applicable outcome is not closed");
+  const reason = validateReason(outcome.reason, false);
+  return reason === null
+    ? invalid(`${path}.reason`, "Not-applicable reason is invalid")
+    : accepted(
+        Object.freeze(
+          reason === undefined ? { status: "not-applicable" } : { status: "not-applicable", reason }
+        )
+      );
+}
+
+function validateUnavailableOutcome(
+  outcome: Readonly<Record<string, unknown>>,
+  path: string
+): ValidationResult<CheckOutcome> {
+  if (!hasExactKeys(outcome, ["status", "reason"]))
+    return invalid(path, "Unavailable outcome is not closed");
+  const reason = validateReason(outcome.reason, true);
+  return reason === null || reason === undefined
+    ? invalid(`${path}.reason`, "Unavailable reason is invalid")
+    : accepted(Object.freeze({ status: "unavailable", reason }));
+}
+
+function validateReason(
+  value: unknown,
+  allowCheckIds: boolean
+): Readonly<{ readonly code: string; readonly checkIds?: readonly string[] }> | null | undefined {
+  if (value === undefined) return undefined;
+  const reason = snapshotClosedRecord(value);
+  if (!isClosedReason(reason, allowCheckIds)) return null;
+  if (!hasOptionalKeys(reason, ["code"], allowCheckIds ? ["checkIds"] : [])) return null;
+  if (!Object.hasOwn(reason, "checkIds")) return Object.freeze({ code: reason.code });
+  const normalizedCheckIds = normalizedReasonCheckIds(reason.checkIds, allowCheckIds);
+  if (normalizedCheckIds === undefined) return null;
+  return Object.freeze({ code: reason.code, checkIds: Object.freeze(normalizedCheckIds) });
+}
+
+function isClosedReason(
+  value: Readonly<Record<string, unknown>> | undefined,
+  allowCheckIds: boolean
+): value is Readonly<Record<string, unknown>> & Readonly<{ readonly code: string }> {
+  return (
+    value !== undefined &&
+    typeof value.code === "string" &&
+    value.code.length > 0 &&
+    hasOptionalKeys(value, ["code"], allowCheckIds ? ["checkIds"] : [])
+  );
+}
+
+function normalizedReasonCheckIds(
+  value: unknown,
+  allowCheckIds: boolean
+): readonly string[] | undefined {
+  const checkIds = snapshotClosedArray(value);
+  if (
+    !allowCheckIds ||
+    checkIds === undefined ||
+    checkIds.length === 0 ||
+    checkIds.some((checkId) => typeof checkId !== "string" || !isSettlementCheckReference(checkId))
+  )
+    return undefined;
+  const normalizedCheckIds: string[] = [];
+  for (const checkId of checkIds) {
+    if (typeof checkId !== "string") return undefined;
+    normalizedCheckIds.push(checkId);
+  }
+  return Object.freeze(normalizedCheckIds);
+}
+
+function hasExactKeys(value: Readonly<Record<string, unknown>>, keys: readonly string[]): boolean {
+  return (
+    Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key))
+  );
+}
+
+function hasOptionalKeys(
+  value: Readonly<Record<string, unknown>>,
+  required: readonly string[],
+  optional: readonly string[]
+): boolean {
+  const supported = new Set([...required, ...optional]);
+  return (
+    required.every((key) => Object.hasOwn(value, key)) &&
+    Object.keys(value).every((key) => supported.has(key))
+  );
+}
+
+function accepted<T>(value: T): ValidationResult<T> {
+  return Object.freeze({ ok: true, value });
+}
+
+function invalid(
+  path: string,
+  message: string,
+  code: ValidationIssue["code"] = "invalid-value"
+): ValidationResult<never> {
+  const issue = Object.freeze({ path, code, message }) satisfies ValidationIssue;
+  const issues: readonly [ValidationIssue, ...ValidationIssue[]] = [issue];
+  return Object.freeze({
+    ok: false,
+    issues: Object.freeze(issues)
+  });
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function isSettlementCheckReference(value: string): boolean {
+  return value.length > 0;
+}

package/src/check-settlement/facts.ts

@@ -0,0 +1,27 @@
+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/src/check-settlement/outcome-normalization.ts

@@ -0,0 +1,118 @@
+import type { CheckOutcome } from "../check/check.ts";
+import { canonicalizeJsonObject } from "../data-boundary/canonical-data.ts";
+import { snapshotClosedArray, snapshotClosedRecord } from "../data-boundary/closed-values.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 function normalizeCheckOutcome(input: OutcomeNormalizationInput): CheckOutcome | undefined {
+  const outcome = snapshotClosedRecord(input.value);
+  if (outcome === undefined || typeof outcome.status !== "string") return undefined;
+  if (outcome.status === "passed" || outcome.status === "failed") {
+    return normalizeFinalOutcome(outcome);
+  }
+  if (outcome.status === "not-applicable") {
+    return normalizeNotApplicableOutcome(outcome, input.knownCheckIds);
+  }
+  if (outcome.status === "unavailable") {
+    return normalizeUnavailableOutcome(outcome, input.productOutcome, input.knownCheckIds);
+  }
+  return undefined;
+}
+
+function normalizeFinalOutcome(
+  outcome: Readonly<Record<string, unknown>>
+): CheckOutcome | undefined {
+  if (outcome.status !== "passed" && outcome.status !== "failed") return undefined;
+  if (!hasExactKeys(outcome, ["status", "data"])) return undefined;
+  const data = canonicalizeJsonObject(outcome.data);
+  return data === undefined ? undefined : Object.freeze({ status: outcome.status, data });
+}
+
+function normalizeNotApplicableOutcome(
+  outcome: Readonly<Record<string, unknown>>,
+  knownCheckIds: ReadonlySet<string>
+): CheckOutcome | undefined {
+  if (!hasOptionalKeys(outcome, ["status"], ["reason"])) return undefined;
+  if (outcome.reason === undefined) return Object.freeze({ status: "not-applicable" });
+  const reason = normalizeReason(outcome.reason, false, knownCheckIds);
+  return reason === undefined ? undefined : Object.freeze({ status: "not-applicable", reason });
+}
+
+function normalizeUnavailableOutcome(
+  outcome: Readonly<Record<string, unknown>>,
+  productOutcome: boolean,
+  knownCheckIds: ReadonlySet<string>
+): CheckOutcome | undefined {
+  if (!hasExactKeys(outcome, ["status", "reason"])) return undefined;
+  const reason = normalizeReason(outcome.reason, productOutcome, knownCheckIds);
+  return reason === undefined ? undefined : Object.freeze({ status: "unavailable", reason });
+}
+
+function normalizeReason(
+  value: unknown,
+  allowCheckIds: boolean,
+  knownCheckIds: ReadonlySet<string>
+): Readonly<{ readonly code: string; readonly checkIds?: readonly string[] }> | undefined {
+  const reason = snapshotClosedRecord(value);
+  if (!isClosedSessionReason(reason, allowCheckIds)) return undefined;
+  if (!Object.hasOwn(reason, "checkIds")) return Object.freeze({ code: reason.code });
+  const checkIds = normalizedSessionReasonCheckIds(reason.checkIds, allowCheckIds, knownCheckIds);
+  return checkIds === undefined ? undefined : Object.freeze({ code: reason.code, checkIds });
+}
+
+function isClosedSessionReason(
+  value: Readonly<Record<string, unknown>> | undefined,
+  allowCheckIds: boolean
+): value is Readonly<Record<string, unknown>> & Readonly<{ readonly code: string }> {
+  return (
+    value !== undefined &&
+    typeof value.code === "string" &&
+    value.code.length > 0 &&
+    hasOptionalKeys(value, ["code"], allowCheckIds ? ["checkIds"] : [])
+  );
+}
+
+function normalizedSessionReasonCheckIds(
+  value: unknown,
+  allowCheckIds: boolean,
+  knownCheckIds: ReadonlySet<string>
+): readonly string[] | undefined {
+  const rawCheckIds = snapshotClosedArray(value);
+  if (!allowCheckIds || rawCheckIds === undefined || rawCheckIds.length === 0) return undefined;
+  const checkIds: string[] = [];
+  for (const checkId of rawCheckIds) {
+    if (
+      typeof checkId !== "string" ||
+      checkId.length === 0 ||
+      !knownCheckIds.has(checkId) ||
+      checkIds.includes(checkId)
+    ) {
+      return undefined;
+    }
+    checkIds.push(checkId);
+  }
+  return Object.freeze(checkIds);
+}
+
+function hasExactKeys(value: Readonly<Record<string, unknown>>, keys: readonly string[]): boolean {
+  return (
+    Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key))
+  );
+}
+
+function hasOptionalKeys(
+  value: Readonly<Record<string, unknown>>,
+  required: readonly string[],
+  optional: readonly string[]
+): boolean {
+  const supported = new Set([...required, ...optional]);
+  return (
+    required.every((key) => Object.hasOwn(value, key)) &&
+    Object.keys(value).every((key) => supported.has(key))
+  );
+}

package/src/check-settlement/record-store.ts

@@ -0,0 +1,73 @@
+import { canonicalizeJsonObject } from "../data-boundary/canonical-data.ts";
+import type { CoreRecord } from "./facts.ts";
+import { snapshotClosedRecord } from "../data-boundary/closed-values.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 class CoreRecordStore {
+  readonly #recordsByCheckId = new Map<string, Map<string, CoreRecord>>();
+
+  public report(
+    slot: CoreRecordSlot,
+    rawIdentity: unknown,
+    rawData: unknown
+  ): RecordSubmissionResult {
+    const id = recordId(rawIdentity);
+    const data = canonicalizeJsonObject(rawData);
+    if (id === undefined || data === undefined) return this.#reject(slot, "record-invalid");
+    if (slot.recordIds.has(id)) return this.#reject(slot, "record-conflict");
+
+    const record: CoreRecord = Object.freeze({ checkId: slot.checkId, id, data });
+    let records = this.#recordsByCheckId.get(slot.checkId);
+    if (records === undefined) {
+      records = new Map<string, CoreRecord>();
+      this.#recordsByCheckId.set(slot.checkId, records);
+    }
+    records.set(id, record);
+    slot.recordIds.add(id);
+    return "committed";
+  }
+
+  public recordsInCanonicalOrder(): readonly CoreRecord[] {
+    const records: CoreRecord[] = [];
+    for (const checkId of [...this.#recordsByCheckId.keys()].sort(compareText)) {
+      const byId = this.#recordsByCheckId.get(checkId);
+      if (byId === undefined) continue;
+      for (const id of [...byId.keys()].sort(compareText)) {
+        const record = byId.get(id);
+        if (record !== undefined) records.push(record);
+      }
+    }
+    return Object.freeze(records);
+  }
+
+  #reject(slot: CoreRecordSlot, diagnostic: RecordDiagnostic): "rejected" {
+    slot.diagnostics.add(diagnostic);
+    return "rejected";
+  }
+}
+
+function recordId(value: unknown): string | undefined {
+  const identity = snapshotClosedRecord(value);
+  return identity !== undefined &&
+    Object.keys(identity).length === 1 &&
+    Object.hasOwn(identity, "id") &&
+    typeof identity.id === "string" &&
+    identity.id.length > 0
+    ? identity.id
+    : undefined;
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}