@zxyycom/vibe-check 0.0.1

package/src/check-settlement/session.ts

@@ -0,0 +1,257 @@
+import type { CheckDescriptor } from "../check/descriptor.ts";
+import type { CheckOutcome } from "../check/check.ts";
+import {
+  CoreRecordStore,
+  type CoreRecordSlot,
+  type RecordDiagnostic,
+  type RecordSubmissionResult
+} from "./record-store.ts";
+import type { CoreCheck, CoreSnapshot } from "./facts.ts";
+import { validateCheckDescriptor } from "../check/descriptor-validation.ts";
+import { normalizeCheckOutcome } from "./outcome-normalization.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 class CoreInvariantFailure extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "CoreInvariantFailure";
+  }
+}
+
+type CoreSlotLifecycle = Readonly<
+  | { readonly kind: "registered" }
+  | { readonly kind: "open" }
+  | { readonly kind: "settled"; readonly outcome: CheckOutcome }
+>;
+
+interface CoreSlot extends CoreRecordSlot {
+  readonly definition: CheckDescriptor;
+  lifecycle: CoreSlotLifecycle;
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function coreInvariant(message: string): never {
+  throw new CoreInvariantFailure(message);
+}
+
+function createSlots(registrations: readonly CoreCheckRegistration[]): CoreSlot[] {
+  const slots: CoreSlot[] = [];
+  const checkIds = new Set<string>();
+  for (const registration of registrations) {
+    if (registration === null || typeof registration !== "object") {
+      coreInvariant("Core Check registration is invalid");
+    }
+    const definition = validateCheckDescriptor(registration.definition);
+    if (!definition.ok) coreInvariant("Core Check registration definition is invalid");
+    if (checkIds.has(definition.value.checkId)) {
+      coreInvariant("Core Check registration has a duplicate checkId");
+    }
+    checkIds.add(definition.value.checkId);
+    slots.push({
+      checkId: definition.value.checkId,
+      definition: definition.value,
+      diagnostics: new Set(),
+      lifecycle: { kind: "registered" },
+      recordIds: new Set()
+    });
+  }
+  return slots.sort((left, right) =>
+    compareText(left.definition.checkId, right.definition.checkId)
+  );
+}
+
+class CoreCheckSessionImpl implements CoreCheckSession {
+  readonly #slots: CoreSlot[];
+  readonly #recordStore = new CoreRecordStore();
+  #snapshot: CoreSnapshot | undefined;
+
+  public constructor(registrations: readonly CoreCheckRegistration[]) {
+    this.#slots = createSlots(registrations);
+  }
+
+  public openCheckScope(checkId: string): TrustedCheckScope {
+    const slot = this.#slotFor(checkId);
+    if (this.#snapshot !== undefined || slot.lifecycle.kind !== "registered") {
+      coreInvariant("Core Check scope is not available");
+    }
+    slot.lifecycle = Object.freeze({ kind: "open" });
+    return Object.freeze({
+      records: Object.freeze({
+        report: (identity: unknown, data: unknown): RecordSubmissionResult => {
+          if (this.#snapshot !== undefined || slot.lifecycle.kind !== "open") return "rejected";
+          return this.#recordStore.report(slot, identity, data);
+        }
+      }),
+      settle: (outcome: unknown): AuthorCheckSettlement => this.#settleAuthorSlot(slot, outcome),
+      settleProduct: (outcome: CheckOutcome): CheckOutcome => this.#settleSlot(slot, outcome, true)
+    });
+  }
+
+  public readSettledCheckOutcome(checkId: string): CheckOutcome {
+    const slot = this.#slotFor(checkId);
+    if (slot.lifecycle.kind !== "settled") {
+      coreInvariant("Core settled Check is not available");
+    }
+    return slot.lifecycle.outcome;
+  }
+
+  public closeUnresolvedAsCancelled(): readonly CancelledCheckClosure[] {
+    if (this.#snapshot !== undefined) {
+      coreInvariant("Cancelled closure cannot mutate a frozen Core snapshot");
+    }
+    const closures: CancelledCheckClosure[] = [];
+    for (const slot of this.#slots) {
+      if (slot.lifecycle.kind !== "settled") {
+        const outcome = this.#commitTerminal(
+          slot,
+          Object.freeze({ status: "unavailable", reason: { code: "execution-cancelled" } }),
+          true
+        );
+        closures.push(Object.freeze({ checkId: slot.checkId, outcome }));
+      }
+    }
+    return Object.freeze(closures);
+  }
+
+  public freeze(): CoreSnapshot {
+    if (this.#snapshot !== undefined) return this.#snapshot;
+    const checks: CoreCheck[] = [];
+    for (const slot of this.#slots) {
+      if (slot.lifecycle.kind !== "settled") {
+        return coreInvariant("Core snapshot cannot freeze before every Check slot closes");
+      }
+      checks.push(coreCheckFor(slot));
+    }
+    this.#snapshot = Object.freeze({
+      checks: Object.freeze(checks),
+      records: this.#recordStore.recordsInCanonicalOrder()
+    });
+    return this.#snapshot;
+  }
+
+  #slotFor(checkId: string): CoreSlot {
+    if (typeof checkId !== "string") coreInvariant("Core Check scope requires a checkId");
+    const slot = this.#slots.find((candidate) => candidate.definition.checkId === checkId);
+    return slot ?? coreInvariant("Core Check scope does not own this checkId");
+  }
+
+  #checkIds(): ReadonlySet<string> {
+    return new Set(this.#slots.map((candidate) => candidate.checkId));
+  }
+
+  #settleSlot(slot: CoreSlot, outcome: unknown, productOutcome: boolean): CheckOutcome {
+    if (this.#snapshot !== undefined || slot.lifecycle.kind !== "open") {
+      return coreInvariant("Trusted Core Check settlement is duplicate, late, or out of scope");
+    }
+    return this.#commitTerminal(slot, outcome, productOutcome);
+  }
+
+  #settleAuthorSlot(slot: CoreSlot, terminal: unknown): AuthorCheckSettlement {
+    if (this.#snapshot !== undefined || slot.lifecycle.kind !== "open") {
+      return coreInvariant("Trusted Core Check settlement is duplicate, late, or out of scope");
+    }
+    const diagnostic = terminalDiagnostic(slot);
+    const normalized =
+      diagnostic === undefined
+        ? normalizeCheckOutcome({
+            knownCheckIds: this.#checkIds(),
+            productOutcome: false,
+            value: terminal
+          })
+        : undefined;
+    const outcome = normalized ?? unavailable(diagnostic ?? "invalid-execution-result");
+    slot.lifecycle = Object.freeze({ kind: "settled", outcome });
+    return Object.freeze({
+      authorResultAccepted: diagnostic === undefined && normalized !== undefined,
+      outcome
+    });
+  }
+
+  #commitTerminal(slot: CoreSlot, terminal: unknown, productOutcome = false): CheckOutcome {
+    if (slot.lifecycle.kind === "settled") {
+      coreInvariant("Core Check terminal closure is duplicate");
+    }
+    const diagnostic = terminalDiagnostic(slot);
+    const outcome =
+      diagnostic === undefined
+        ? (normalizeCheckOutcome({
+            knownCheckIds: this.#checkIds(),
+            productOutcome,
+            value: terminal
+          }) ?? unavailable("invalid-execution-result"))
+        : unavailable(diagnostic);
+    slot.lifecycle = Object.freeze({ kind: "settled", outcome });
+    return outcome;
+  }
+}
+
+function terminalDiagnostic(slot: CoreSlot): RecordDiagnostic | undefined {
+  if (slot.diagnostics.has("record-conflict")) return "record-conflict";
+  if (slot.diagnostics.has("record-invalid")) return "record-invalid";
+  return undefined;
+}
+
+function coreCheckFor(slot: CoreSlot): CoreCheck {
+  if (slot.lifecycle.kind !== "settled") {
+    coreInvariant("Core Check fact requires a settled slot");
+  }
+  return Object.freeze({
+    checkId: slot.definition.checkId,
+    displayName: slot.definition.displayName,
+    outcome: slot.lifecycle.outcome
+  });
+}
+
+function unavailable(code: string): CheckOutcome {
+  return Object.freeze({ status: "unavailable", reason: Object.freeze({ code }) });
+}
+
+export function createCoreCheckSession(
+  registrations: readonly CoreCheckRegistration[]
+): CoreCheckSession {
+  return new CoreCheckSessionImpl(registrations);
+}

package/src/data-boundary/canonical-data.ts

@@ -0,0 +1,188 @@
+import type { CanonicalJsonObject, CanonicalJsonValue } from "./canonical-json.ts";
+
+export type {
+  CanonicalJsonObject,
+  CanonicalJsonPrimitive,
+  CanonicalJsonValue
+} from "./canonical-json.ts";
+
+const encoder = new TextEncoder();
+
+/**
+ * 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 function canonicalizeJsonObject(value: unknown): CanonicalJsonObject | undefined {
+  const canonical = canonicalize(value, new Set<object>());
+  return canonical !== undefined && isCanonicalJsonObject(canonical) ? canonical : undefined;
+}
+
+export function canonicalizeJsonValue(value: unknown): CanonicalJsonValue | undefined {
+  return canonicalize(value, new Set<object>());
+}
+
+/** Serializes detached canonical JSON with explicit lexical object-key ordering. */
+export function canonicalJsonText(value: unknown): string {
+  const canonical = canonicalizeJsonValue(value);
+  if (canonical === undefined) {
+    throw new TypeError("Canonical JSON could not safely materialize the input");
+  }
+  return canonicalText(canonical);
+}
+
+/** Emits canonical UTF-8 JSON without invoking author getters or `toJSON`. */
+export function canonicalJsonBytes(value: unknown): Uint8Array {
+  return encoder.encode(canonicalJsonText(value));
+}
+
+function canonicalize(value: unknown, ancestors: Set<object>): CanonicalJsonValue | undefined {
+  if (value === null) return null;
+  const primitive = canonicalPrimitive(value);
+  if (primitive !== undefined) return primitive;
+  if (typeof value !== "object") return undefined;
+  if (!admitCanonicalObject(value, ancestors)) return undefined;
+
+  try {
+    return Array.isArray(value)
+      ? canonicalizeArray(value, ancestors)
+      : canonicalizeObject(value, ancestors);
+  } catch {
+    return undefined;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function canonicalPrimitive(value: unknown): CanonicalJsonValue | undefined {
+  if (typeof value === "boolean" || typeof value === "string") return value;
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Object.is(value, -0) ? 0 : value;
+}
+
+function admitCanonicalObject(value: object, ancestors: Set<object>): boolean {
+  if (ancestors.has(value)) return false;
+  ancestors.add(value);
+  return true;
+}
+
+function canonicalizeArray(
+  value: readonly unknown[],
+  ancestors: Set<object>
+): readonly CanonicalJsonValue[] | undefined {
+  const length = denseCanonicalArrayLength(value);
+  if (length === undefined) return undefined;
+  return canonicalArrayElements(value, length, ancestors);
+}
+
+function denseCanonicalArrayLength(value: readonly unknown[]): number | undefined {
+  if (Object.getPrototypeOf(value) !== Array.prototype) return undefined;
+  const keys = Reflect.ownKeys(value);
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+  if (!isDataDescriptor(lengthDescriptor) || lengthDescriptor.enumerable) return undefined;
+  const length = lengthDescriptor.value;
+  if (
+    typeof length !== "number" ||
+    !Number.isSafeInteger(length) ||
+    length < 0 ||
+    keys.length !== length + 1
+  )
+    return undefined;
+  if (!keys.includes("length")) return undefined;
+  return length;
+}
+
+function canonicalArrayElements(
+  value: readonly unknown[],
+  length: number,
+  ancestors: Set<object>
+): readonly CanonicalJsonValue[] | undefined {
+  const values: CanonicalJsonValue[] = [];
+  for (let index = 0; index < length; index += 1) {
+    const key = String(index);
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!isEnumerableDataDescriptor(descriptor)) return undefined;
+    const item = canonicalize(descriptor.value, ancestors);
+    if (item === undefined) return undefined;
+    values.push(item);
+  }
+  return Object.freeze(values);
+}
+
+function canonicalizeObject(
+  value: object,
+  ancestors: Set<object>
+): CanonicalJsonObject | undefined {
+  const prototype: unknown = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return undefined;
+  const keys: string[] = [];
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string") return undefined;
+    keys.push(key);
+  }
+
+  const snapshot: Record<string, CanonicalJsonValue> = {};
+  Object.setPrototypeOf(snapshot, null);
+  for (const key of keys.sort(compareText)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!isEnumerableDataDescriptor(descriptor)) return undefined;
+    const item = canonicalize(descriptor.value, ancestors);
+    if (item === undefined) return undefined;
+    Object.defineProperty(snapshot, key, {
+      configurable: false,
+      enumerable: true,
+      value: item,
+      writable: false
+    });
+  }
+  return Object.freeze(snapshot);
+}
+
+type DataDescriptor = Omit<PropertyDescriptor, "get" | "set" | "value"> &
+  Readonly<{
+    get?: undefined;
+    set?: undefined;
+    value: unknown;
+  }>;
+
+function isDataDescriptor(
+  descriptor: PropertyDescriptor | undefined
+): descriptor is DataDescriptor {
+  return (
+    descriptor !== undefined &&
+    descriptor.get === undefined &&
+    descriptor.set === undefined &&
+    Object.hasOwn(descriptor, "value")
+  );
+}
+
+function isEnumerableDataDescriptor(
+  descriptor: PropertyDescriptor | undefined
+): descriptor is DataDescriptor {
+  return isDataDescriptor(descriptor) && descriptor.enumerable === true;
+}
+
+function isCanonicalJsonObject(value: CanonicalJsonValue): value is CanonicalJsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function canonicalText(value: CanonicalJsonValue): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (isCanonicalJsonArray(value)) {
+    return `[${value.map((entry) => canonicalText(entry)).join(",")}]`;
+  }
+  return `{${Object.keys(value)
+    .sort(compareText)
+    .map((key) => `${JSON.stringify(key)}:${canonicalText(value[key])}`)
+    .join(",")}}`;
+}
+
+function isCanonicalJsonArray(value: CanonicalJsonValue): value is readonly CanonicalJsonValue[] {
+  return Array.isArray(value);
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

package/src/data-boundary/canonical-json.ts

@@ -0,0 +1,11 @@
+/** 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/src/data-boundary/closed-values.ts

@@ -0,0 +1,126 @@
+interface OwnDataShape {
+  readonly descriptors: Readonly<Record<string, PropertyDescriptor>>;
+  readonly keys: readonly string[];
+}
+
+function ownDataShape(value: object): OwnDataShape | undefined {
+  const descriptors: Readonly<Record<string, PropertyDescriptor>> =
+    Object.getOwnPropertyDescriptors(value);
+  const ownKeys = Reflect.ownKeys(descriptors);
+  const keys: string[] = [];
+  for (const key of ownKeys) {
+    if (typeof key !== "string") return undefined;
+    keys.push(key);
+  }
+  if (
+    keys.some((key) => {
+      const descriptor = descriptors[key];
+      return descriptor.get !== undefined || descriptor.set !== undefined;
+    })
+  )
+    return undefined;
+  return { descriptors, keys };
+}
+
+export function snapshotPlainRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  try {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return undefined;
+    }
+    const prototype: unknown = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      return undefined;
+    }
+    const descriptors: Readonly<Record<string, PropertyDescriptor>> =
+      Object.getOwnPropertyDescriptors(value);
+    if (
+      Object.values(descriptors).some(
+        (descriptor) => descriptor.get !== undefined || descriptor.set !== undefined
+      )
+    ) {
+      return undefined;
+    }
+    return Object.fromEntries(
+      Object.entries(descriptors)
+        .filter(([, descriptor]) => descriptor.enumerable === true)
+        .map(([key, descriptor]) => [key, descriptor.value as unknown])
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+export function snapshotClosedRecord(
+  value: unknown
+): Readonly<Record<string, unknown>> | undefined {
+  try {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const prototype: unknown = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) return undefined;
+    const shape = ownDataShape(value);
+    if (
+      shape === undefined ||
+      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]))
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+function closedArrayLength(shape: OwnDataShape): number | undefined {
+  const descriptor = shape.descriptors.length;
+  if (typeof descriptor?.value !== "number" || descriptor.enumerable !== false) return undefined;
+  const length = descriptor.value;
+  return Number.isSafeInteger(length) && length >= 0 && shape.keys.length === length + 1
+    ? length
+    : undefined;
+}
+
+function closedArrayItems(shape: OwnDataShape, length: number): readonly unknown[] | undefined {
+  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;
+    items.push(descriptor.value as unknown);
+  }
+  return Object.freeze(items);
+}
+
+export function snapshotClosedArray(value: unknown): readonly unknown[] | undefined {
+  try {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) return undefined;
+    const shape = ownDataShape(value);
+    if (shape === undefined) return undefined;
+    const length = closedArrayLength(shape);
+    return length === undefined ? undefined : closedArrayItems(shape, length);
+  } catch {
+    return undefined;
+  }
+}
+
+export function hasExactPlainRecordKeys(
+  value: Readonly<Record<string, unknown>>,
+  keys: readonly string[]
+): boolean {
+  const actualKeys = Object.keys(value);
+  return actualKeys.length === keys.length && actualKeys.every((key) => keys.includes(key));
+}
+
+export function hasRequiredAndOptionalRecordKeys(
+  value: Readonly<Record<string, unknown>>,
+  keys: Readonly<{
+    readonly optional: readonly string[];
+    readonly required: readonly string[];
+  }>
+): boolean {
+  const supportedKeys = new Set([...keys.required, ...keys.optional]);
+  return (
+    keys.required.every((key) => Object.hasOwn(value, key)) &&
+    Object.keys(value).every((key) => supportedKeys.has(key))
+  );
+}

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

@@ -0,0 +1,15 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function isNonArrayRecord(value: unknown): value is Record<string, unknown> {
+  return isRecord(value) && !Array.isArray(value);
+}
+
+export function isUnknownArray(value: unknown): value is unknown[] {
+  return Array.isArray(value);
+}
+
+export function isStringArray(value: unknown): value is string[] {
+  return isUnknownArray(value) && value.every((item) => typeof item === "string");
+}