@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/check/flag-enablement.ts

@@ -0,0 +1,76 @@
+/** 一个递归 flag presence 条件表达式。字符串是唯一 leaf；operator 保留 author child 顺序和 multiplicity。 */
+export type CheckFlagCondition =
+  | string
+  | Readonly<{
+      readonly kind: "all" | "any" | "none" | "not-all" | "exactly-one";
+      readonly conditions: readonly [CheckFlagCondition, ...CheckFlagCondition[]];
+    }>
+  | Readonly<{
+      readonly kind: "not";
+      readonly condition: CheckFlagCondition;
+    }>;
+
+type CheckFlagConditionSetKind = "all" | "any" | "none" | "not-all" | "exactly-one";
+type NonEmptyFlagConditions = readonly [CheckFlagCondition, ...CheckFlagCondition[]];
+type CheckFlagConditionSet<Kind extends CheckFlagConditionSetKind> = Readonly<{
+  readonly kind: Kind;
+  readonly conditions: NonEmptyFlagConditions;
+}>;
+type CheckFlagNegation = Readonly<{
+  readonly kind: "not";
+  readonly condition: CheckFlagCondition;
+}>;
+
+/** 构造 `all` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function all(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"all"> {
+  return conditionSet("all", conditions);
+}
+
+/** 构造 `any` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function any(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"any"> {
+  return conditionSet("any", conditions);
+}
+
+/** 构造 `none` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function none(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"none"> {
+  return conditionSet("none", conditions);
+}
+
+/** 构造 `not-all` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function notAll(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"not-all"> {
+  return conditionSet("not-all", conditions);
+}
+
+/** 构造 `exactly-one` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function exactlyOne(
+  ...conditions: NonEmptyFlagConditions
+): CheckFlagConditionSet<"exactly-one"> {
+  return conditionSet("exactly-one", conditions);
+}
+
+/** 构造 `not` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function not(condition: CheckFlagCondition): CheckFlagNegation {
+  return { condition, kind: "not" };
+}
+
+/** 为一个已声明的 project change ID 生成保留 flag token。 */
+export function changeFlag<const Id extends string>(id: Id): `vibe-check:change:${Id}` {
+  return `vibe-check:change:${id}`;
+}
+
+function conditionSet<Kind extends CheckFlagConditionSetKind>(
+  kind: Kind,
+  conditions: NonEmptyFlagConditions
+): CheckFlagConditionSet<Kind> {
+  return { kind, conditions };
+}
+
+/** executable Check 的 flag 选择控制。 */
+export interface CheckFlagEnablement {
+  readonly when: CheckFlagCondition;
+  /**
+   * 条件命中时是否启动本 Check 的传递 `dependsOn` prerequisite；省略时只选择直接命中 Check。
+   * `observes` 不参与此选择，且 dependency 自己的 flag 条件不会阻止已启动 prerequisite。
+   */
+  readonly propagateDependsOn?: true;
+}

package/src/check/handoff-provider-identity.ts

@@ -0,0 +1,34 @@
+declare const HANDOFF_PROVIDER_IDENTITY_BRAND: unique symbol;
+
+/** Opaque same-package identity retained only by Definition and invocation execution. */
+export type HandoffProviderIdentity = Readonly<{
+  readonly [HANDOFF_PROVIDER_IDENTITY_BRAND]: true;
+}>;
+
+const handoffProviderIdentities = new WeakMap<object, HandoffProviderIdentity>();
+
+class HandoffProviderIdentityValue implements HandoffProviderIdentity {
+  declare readonly [HANDOFF_PROVIDER_IDENTITY_BRAND]: true;
+}
+
+/** Registers the identity that makes a `handoff: true` Check authentic to this package runtime. */
+export function registerHandoffProviderIdentity(value: object): void {
+  handoffProviderIdentities.set(value, Object.freeze(new HandoffProviderIdentityValue()));
+}
+
+/** Returns the same-package identity registered by `defineCheck`. */
+export function getDefinedHandoffProviderIdentity(
+  value: unknown
+): HandoffProviderIdentity | undefined {
+  return typeof value === "object" && value !== null
+    ? handoffProviderIdentities.get(value)
+    : undefined;
+}
+
+/** Preserves a Definition-validated provider identity during materialization. */
+export function bindHandoffProviderIdentity(
+  value: object,
+  identity: HandoffProviderIdentity
+): void {
+  handoffProviderIdentities.set(value, identity);
+}

package/src/check/inherited-collection.ts

@@ -28,7 +28,7 @@ const inheritedCollections = new WeakSet();
 type InheritedCollectionEntry = "data" | "invalid" | "marker";
 
 /**
- * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。
+ * 创建可用于 `dependsOn`、`observes` 或 `mutex` 的受信任继承编辑。
  *
  * @typeParam T - 要添加或移除的 collection item 类型。
  * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。
@@ -82,7 +82,7 @@ function snapshotInheritedCollectionEntry(
 ): InheritedCollectionEntry {
   if (!isDataDescriptor(descriptor)) return "invalid";
   if (key === INHERITED_CHECK_COLLECTION) {
-    return descriptor.enumerable || descriptor.value !== true ? "invalid" : "marker";
+    return descriptor.enumerable === true || descriptor.value !== true ? "invalid" : "marker";
   }
   if (typeof key !== "string" || descriptor.enumerable !== true) return "invalid";
   Object.defineProperty(snapshot, key, {

package/src/check/project-changes.ts

@@ -0,0 +1,14 @@
+/** 已配置的 project change preparation 产生的 file-centric evidence。 */
+export type ProjectChanges = Readonly<
+  | {
+      readonly ok: true;
+      readonly files: readonly Readonly<{
+        readonly path: string;
+        readonly flags: readonly string[];
+      }>[];
+    }
+  | {
+      readonly ok: false;
+      readonly reason: Readonly<{ readonly code: string }>;
+    }
+>;

package/src/check/project-context.ts

@@ -0,0 +1,11 @@
+import type { ProjectChanges } from "./project-changes.ts";
+
+/** 每次 Run 共享、冻结的 caller project context。 */
+export interface CheckProjectContext {
+  /** 本次 Run 使用的绝对项目根目录。 */
+  readonly root: string;
+  /** 已去重、排序的 invocation-effective flags（caller flags 与派生 change flags）。 */
+  readonly flags: readonly string[];
+  /** 只在当前 Project Definition 配置 change preparation 时存在。 */
+  readonly changes?: ProjectChanges;
+}

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

@@ -2,7 +2,13 @@ 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";
+import {
+  hasExactPlainRecordKeys,
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedRecord
+} from "../data-boundary/closed-values.ts";
+import { isClosedCheckReason } from "./reason-shape.ts";
 
 export interface ValidationIssue {
   readonly path: string;
@@ -22,7 +28,7 @@ export type ValidationResult<T> = Readonly<
 
 export function validateCoreSnapshot(value: unknown): ValidationResult<CoreSnapshot> {
   const snapshot = snapshotClosedRecord(value);
-  if (snapshot === undefined || !hasExactKeys(snapshot, ["checks", "records"])) {
+  if (snapshot === undefined || !hasExactPlainRecordKeys(snapshot, ["checks", "records"])) {
     return invalid("$", "Core snapshot must contain only checks and records");
   }
   const checksInput = snapshotClosedArray(snapshot.checks);
@@ -63,7 +69,10 @@ function validateChecks(values: readonly unknown[]): ValidationResult<readonly C
   let previousCheckId: string | undefined;
   for (const [index, value] of values.entries()) {
     const check = snapshotClosedRecord(value);
-    if (check === undefined || !hasExactKeys(check, ["checkId", "displayName", "outcome"])) {
+    if (
+      check === undefined ||
+      !hasExactPlainRecordKeys(check, ["checkId", "displayName", "outcome"])
+    ) {
       return invalid(`$.checks[${index}]`, "Core Check must be closed");
     }
     const definition = validateCheckDescriptor({
@@ -126,7 +135,7 @@ function validateRecordRow(
   ownerIds: ReadonlySet<string>
 ): ValidationResult<CoreRecord> {
   const record = snapshotClosedRecord(value);
-  if (record === undefined || !hasExactKeys(record, ["checkId", "id", "data"]))
+  if (record === undefined || !hasExactPlainRecordKeys(record, ["checkId", "id", "data"]))
     return invalid(`$.records[${index}]`, "Core Record must be closed");
   if (
     typeof record.checkId !== "string" ||
@@ -159,7 +168,7 @@ function validateFinalOutcome(
   path: string
 ): ValidationResult<CheckOutcome> {
   if (outcome.status === "passed" || outcome.status === "failed") {
-    if (!hasExactKeys(outcome, ["status", "data"]))
+    if (!hasExactPlainRecordKeys(outcome, ["status", "data"]))
       return invalid(path, "Final outcome is not closed");
     const data = canonicalizeJsonObject(outcome.data);
     return data === undefined
@@ -173,7 +182,12 @@ function validateNotApplicableOutcome(
   outcome: Readonly<Record<string, unknown>>,
   path: string
 ): ValidationResult<CheckOutcome> {
-  if (!hasOptionalKeys(outcome, ["status"], ["reason"]))
+  if (
+    !hasRequiredAndOptionalRecordKeys(outcome, {
+      optional: ["reason"],
+      required: ["status"]
+    })
+  )
     return invalid(path, "Not-applicable outcome is not closed");
   const reason = validateReason(outcome.reason, false);
   return reason === null
@@ -189,7 +203,7 @@ function validateUnavailableOutcome(
   outcome: Readonly<Record<string, unknown>>,
   path: string
 ): ValidationResult<CheckOutcome> {
-  if (!hasExactKeys(outcome, ["status", "reason"]))
+  if (!hasExactPlainRecordKeys(outcome, ["status", "reason"]))
     return invalid(path, "Unavailable outcome is not closed");
   const reason = validateReason(outcome.reason, true);
   return reason === null || reason === undefined
@@ -203,26 +217,20 @@ function validateReason(
 ): 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 (!isClosedCheckReason(reason, allowCheckIds)) return null;
+  if (
+    !hasRequiredAndOptionalRecordKeys(reason, {
+      optional: allowCheckIds ? ["checkIds"] : [],
+      required: ["code"]
+    })
+  )
+    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
@@ -243,24 +251,6 @@ function normalizedReasonCheckIds(
   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 });
 }

package/src/check-settlement/facts.ts

@@ -8,7 +8,7 @@ export type {
 } from "../data-boundary/canonical-data.ts";
 export type { CheckDescriptor, CheckOutcome };
 
-/** A Core Check has exactly one terminal outcome and no execution bookkeeping. */
+/** Core Check 恰有一个 terminal outcome，不携带 execution bookkeeping。 */
 export interface CoreCheck extends CheckDescriptor {
   readonly outcome: CheckOutcome;
 }

package/src/check-settlement/outcome-normalization.ts

@@ -1,6 +1,12 @@
 import type { CheckOutcome } from "../check/check.ts";
 import { canonicalizeJsonObject } from "../data-boundary/canonical-data.ts";
-import { snapshotClosedArray, snapshotClosedRecord } from "../data-boundary/closed-values.ts";
+import {
+  hasExactPlainRecordKeys,
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedRecord
+} from "../data-boundary/closed-values.ts";
+import { isClosedCheckReason } from "./reason-shape.ts";
 
 interface OutcomeNormalizationInput {
   readonly knownCheckIds: ReadonlySet<string>;
@@ -28,7 +34,7 @@ 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;
+  if (!hasExactPlainRecordKeys(outcome, ["status", "data"])) return undefined;
   const data = canonicalizeJsonObject(outcome.data);
   return data === undefined ? undefined : Object.freeze({ status: outcome.status, data });
 }
@@ -37,7 +43,13 @@ function normalizeNotApplicableOutcome(
   outcome: Readonly<Record<string, unknown>>,
   knownCheckIds: ReadonlySet<string>
 ): CheckOutcome | undefined {
-  if (!hasOptionalKeys(outcome, ["status"], ["reason"])) return undefined;
+  if (
+    !hasRequiredAndOptionalRecordKeys(outcome, {
+      optional: ["reason"],
+      required: ["status"]
+    })
+  )
+    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 });
@@ -48,7 +60,7 @@ function normalizeUnavailableOutcome(
   productOutcome: boolean,
   knownCheckIds: ReadonlySet<string>
 ): CheckOutcome | undefined {
-  if (!hasExactKeys(outcome, ["status", "reason"])) return undefined;
+  if (!hasExactPlainRecordKeys(outcome, ["status", "reason"])) return undefined;
   const reason = normalizeReason(outcome.reason, productOutcome, knownCheckIds);
   return reason === undefined ? undefined : Object.freeze({ status: "unavailable", reason });
 }
@@ -59,24 +71,12 @@ function normalizeReason(
   knownCheckIds: ReadonlySet<string>
 ): Readonly<{ readonly code: string; readonly checkIds?: readonly string[] }> | undefined {
   const reason = snapshotClosedRecord(value);
-  if (!isClosedSessionReason(reason, allowCheckIds)) return undefined;
+  if (!isClosedCheckReason(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,
@@ -98,21 +98,3 @@ function normalizedSessionReasonCheckIds(
   }
   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/reason-shape.ts

@@ -0,0 +1,20 @@
+import { hasRequiredAndOptionalRecordKeys } from "../data-boundary/closed-values.ts";
+
+export type ClosedCheckReason = Readonly<Record<string, unknown>> &
+  Readonly<{ readonly code: string }>;
+
+/** Recognizes the shared closed reason shape before owner-specific ID validation. */
+export function isClosedCheckReason(
+  value: Readonly<Record<string, unknown>> | undefined,
+  allowCheckIds: boolean
+): value is ClosedCheckReason {
+  return (
+    value !== undefined &&
+    typeof value.code === "string" &&
+    value.code.length > 0 &&
+    hasRequiredAndOptionalRecordKeys(value, {
+      optional: allowCheckIds ? ["checkIds"] : [],
+      required: ["code"]
+    })
+  );
+}

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

@@ -3,15 +3,16 @@ import type { CoreRecord } from "./facts.ts";
 import { snapshotClosedRecord } from "../data-boundary/closed-values.ts";
 
 export type RecordSubmissionResult = "committed" | "rejected";
+
+const EMPTY_RECORDS: readonly CoreRecord[] = Object.freeze([]);
 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. */
+/** Holds Check-local supplemental Records without inventing a composite string identity. */
 export class CoreRecordStore {
   readonly #recordsByCheckId = new Map<string, Map<string, CoreRecord>>();
 
@@ -23,30 +24,32 @@ export class CoreRecordStore {
     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?.has(id) === true) return this.#reject(slot, "record-conflict");
     if (records === undefined) {
       records = new Map<string, CoreRecord>();
       this.#recordsByCheckId.set(slot.checkId, records);
     }
+    const record: CoreRecord = Object.freeze({ checkId: slot.checkId, id, data });
     records.set(id, record);
-    slot.recordIds.add(id);
     return "committed";
   }
 
+  public recordsForCheckInCanonicalOrder(checkId: string): readonly CoreRecord[] {
+    const recordsById = this.#recordsByCheckId.get(checkId);
+    if (recordsById === undefined) return EMPTY_RECORDS;
+    return Object.freeze(
+      [...recordsById.values()].sort((left, right) => compareText(left.id, right.id))
+    );
+  }
+
   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);
+    return Object.freeze(
+      [...this.#recordsByCheckId.keys()]
+        .sort(compareText)
+        .flatMap((checkId) => this.recordsForCheckInCanonicalOrder(checkId))
+    );
   }
 
   #reject(slot: CoreRecordSlot, diagnostic: RecordDiagnostic): "rejected" {

package/src/check-settlement/session.ts

@@ -6,7 +6,7 @@ import {
   type RecordDiagnostic,
   type RecordSubmissionResult
 } from "./record-store.ts";
-import type { CoreCheck, CoreSnapshot } from "./facts.ts";
+import type { CoreCheck, CoreRecord, CoreSnapshot } from "./facts.ts";
 import { validateCheckDescriptor } from "../check/descriptor-validation.ts";
 import { normalizeCheckOutcome } from "./outcome-normalization.ts";
 
@@ -39,6 +39,8 @@ export interface AuthorCheckSettlement {
 export interface CoreCheckSession {
   openCheckScope(checkId: string): TrustedCheckScope;
   readSettledCheckOutcome(checkId: string): CheckOutcome;
+  /** Product-private readback used only after this Check's terminal settlement. */
+  readSettledCheckRecords(checkId: string): readonly CoreRecord[];
   closeUnresolvedAsCancelled(): readonly CancelledCheckClosure[];
   freeze(): CoreSnapshot;
 }
@@ -95,8 +97,7 @@ function createSlots(registrations: readonly CoreCheckRegistration[]): CoreSlot[
       checkId: definition.value.checkId,
       definition: definition.value,
       diagnostics: new Set(),
-      lifecycle: { kind: "registered" },
-      recordIds: new Set()
+      lifecycle: { kind: "registered" }
     });
   }
   return slots.sort((left, right) =>
@@ -139,6 +140,14 @@ class CoreCheckSessionImpl implements CoreCheckSession {
     return slot.lifecycle.outcome;
   }
 
+  public readSettledCheckRecords(checkId: string): readonly CoreRecord[] {
+    const slot = this.#slotFor(checkId);
+    if (slot.lifecycle.kind !== "settled") {
+      coreInvariant("Core settled Check Records are not available");
+    }
+    return this.#recordStore.recordsForCheckInCanonicalOrder(checkId);
+  }
+
   public closeUnresolvedAsCancelled(): readonly CancelledCheckClosure[] {
     if (this.#snapshot !== undefined) {
       coreInvariant("Cancelled closure cannot mutate a frozen Core snapshot");

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

@@ -9,20 +9,38 @@ export type {
 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.
+ * 将输入规范化为独立且递归冻结的 canonical JSON 对象副本。
+ *
+ * 递归内容只接受普通对象或 null-prototype 对象、标准无空洞数组和有限 JSON 基本值；仅当顶层结果是
+ * 非数组对象时返回该副本。输出对象使用 null prototype，输出对象和数组均独立于输入且递归冻结。不调用
+ * getter 或 `toJSON`；无效输入、循环引用或反射失败返回 `undefined`。反射 Proxy 时仍可能执行其 trap，
+ * 不隔离 trap 的副作用。
  */
 export function canonicalizeJsonObject(value: unknown): CanonicalJsonObject | undefined {
   const canonical = canonicalize(value, new Set<object>());
   return canonical !== undefined && isCanonicalJsonObject(canonical) ? canonical : undefined;
 }
 
+/**
+ * 将输入规范化为独立且递归冻结的 canonical JSON 值副本。
+ *
+ * 接受 `null`、boolean、string、有限 number、普通对象或 null-prototype 对象，以及标准无空洞数组；
+ * `-0` 转换为 `0`，输出对象使用 null prototype。拒绝存取器、稀疏数组、不可枚举的自有属性、非有限
+ * number 和其它 prototype。不调用 getter 或 `toJSON`；无效输入、循环引用或反射失败返回 `undefined`。
+ * 反射 Proxy 时仍可能执行其 trap，不隔离 trap 的副作用。`CanonicalJsonPrimitive` 的 `number` 在
+ * TypeScript 中仍可表示 `NaN`，有限性只能由本函数在运行时检查。
+ */
 export function canonicalizeJsonValue(value: unknown): CanonicalJsonValue | undefined {
   return canonicalize(value, new Set<object>());
 }
 
-/** Serializes detached canonical JSON with explicit lexical object-key ordering. */
+/**
+ * 规范化输入后生成确定性的无额外空白 JSON 文本。
+ *
+ * 对象键按固定的 lexical `<` 顺序输出，不承诺遵循外部 canonical-JSON 标准。即使同一对象已经过
+ * 规范化，`JSON.stringify` 仍按 ECMAScript 的整数索引键顺序输出，不能替代本函数。输入规则与 Proxy
+ * 边界同 `canonicalizeJsonValue`；无效输入或无法反射的 Proxy 均抛出 `TypeError`。
+ */
 export function canonicalJsonText(value: unknown): string {
   const canonical = canonicalizeJsonValue(value);
   if (canonical === undefined) {
@@ -31,7 +49,12 @@ export function canonicalJsonText(value: unknown): string {
   return canonicalText(canonical);
 }
 
-/** Emits canonical UTF-8 JSON without invoking author getters or `toJSON`. */
+/**
+ * 规范化输入后生成与 `canonicalJsonText` 相同的确定性 UTF-8 JSON 字节。
+ *
+ * 函数自行完成规范化与固定键排序，不要求调用方先取得 canonical JSON 值。输入规则、Proxy 边界和
+ * `TypeError` 失败方式与 `canonicalJsonText` 相同。
+ */
 export function canonicalJsonBytes(value: unknown): Uint8Array {
   return encoder.encode(canonicalJsonText(value));
 }
@@ -79,7 +102,7 @@ function denseCanonicalArrayLength(value: readonly unknown[]): number | undefine
   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;
+  if (!isDataDescriptor(lengthDescriptor) || lengthDescriptor.enumerable === true) return undefined;
   const length = lengthDescriptor.value;
   if (
     typeof length !== "number" ||
@@ -140,8 +163,6 @@ function canonicalizeObject(
 
 type DataDescriptor = Omit<PropertyDescriptor, "get" | "set" | "value"> &
   Readonly<{
-    get?: undefined;
-    set?: undefined;
     value: unknown;
   }>;
 
@@ -173,7 +194,13 @@ function canonicalText(value: CanonicalJsonValue): string {
   }
   return `{${Object.keys(value)
     .sort(compareText)
-    .map((key) => `${JSON.stringify(key)}:${canonicalText(value[key])}`)
+    .map((key) => {
+      const entry = value[key];
+      if (entry === undefined) {
+        throw new TypeError(`Canonical JSON object is missing declared key: ${key}`);
+      }
+      return `${JSON.stringify(key)}:${canonicalText(entry)}`;
+    })
     .join(",")}}`;
 }
 

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

@@ -1,11 +1,28 @@
-/** Package-private static shape for Product's detached canonical JSON facts. */
+/**
+ * Canonical JSON 基本值的静态结构类型。
+ *
+ * TypeScript 的 `number` 无法在静态层区分有限值与 `NaN` / `Infinity`；因此此类型不能证明值已经由
+ * canonical API 规范化。运行时只接受有限 number，并将 `-0` 转换为 `0`。
+ */
 export type CanonicalJsonPrimitive = boolean | null | number | string;
 
+/**
+ * Canonical JSON 值的递归只读静态结构类型。
+ *
+ * 它描述基本值、数组和对象能够如何组合，便于声明参数和结果；不证明值已经通过 canonical API 的
+ * 运行时规范化、递归冻结或循环检查。
+ */
 export type CanonicalJsonValue =
   | CanonicalJsonPrimitive
   | readonly CanonicalJsonValue[]
   | CanonicalJsonObject;
 
+/**
+ * Canonical JSON 对象的只读静态结构类型。
+ *
+ * 该类型不证明值来自 canonical API。API 实际返回的对象使用 null prototype，没有继承的对象方法；
+ * 检查属性时使用 `Object.hasOwn`，不要调用 `value.hasOwnProperty`。
+ */
 export interface CanonicalJsonObject {
   readonly [key: string]: CanonicalJsonValue;
 }