@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/package-tools/learned-critical-path/strategy.ts

@@ -0,0 +1,302 @@
+import { isAbsolute } from "node:path";
+
+import {
+  canonicalizeJsonValue,
+  type CanonicalJsonValue
+} from "../../data-boundary/canonical-data.ts";
+import type {
+  AdmissionPolicyContext,
+  AdmissionProposal,
+  CustomAdmissionStrategy,
+  SchedulerGraphSnapshot,
+  SchedulerMeasurementContext
+} from "../../project-definition/project-definition.ts";
+import { prepareSchedulerDurationModel } from "./duration-model/preparation.ts";
+import { learnedSelectionLayers } from "./selection-layers.ts";
+import { staticDecision } from "./static-decision.ts";
+import {
+  predictionForTask,
+  type SchedulerPredictionInput,
+  type SchedulerPredictionSnapshot
+} from "./duration-model/prediction.ts";
+import {
+  createSchedulerCriticalPathSnapshot,
+  criticalPathScoreForTask,
+  type SchedulerCriticalPathSnapshot
+} from "./critical-path-ranking.ts";
+
+/** 公开 learned critical-path prepared strategy 的调用方配置。 */
+export interface LearnedCriticalPathStrategyOptions {
+  /** 调用方拥有的可丢弃 learned duration history 本地目录；必须是绝对路径。 */
+  readonly stateDirectory: string;
+  /** 为每个公开 Task 提供 canonical-JSON-compatible 的调用方 identity projection。 */
+  readonly identityForTask: (task: SchedulerGraphSnapshot["tasks"][number]) => unknown;
+  /** 单个 identity 最多保留的样本数；默认 32。 */
+  readonly sampleWindow?: number;
+  /** 最多保留的 identity 数；默认 4096。 */
+  readonly maxHistorySeries?: number;
+  /** 正的 cold-start duration 权重（毫秒）；默认 1。 */
+  readonly coldStartDurationMs?: number;
+  /** 可选调用方 observation sink；observer fault 不改变 scheduling 或 Run facts。 */
+  readonly observe?: (event: LearnedCriticalPathObservation) => void | Promise<void>;
+}
+
+/** 调用方可选 observer 收到的有界 learned strategy 事件；selection-proposed 不表示 Scheduler 已接受 admission。 */
+export type LearnedCriticalPathObservation =
+  | Readonly<{
+      readonly kind: "history-unavailable";
+      readonly reason: "identity-invalid" | "setup-failed";
+    }>
+  | Readonly<{
+      readonly kind: "selection-proposed";
+      readonly taskId: string;
+      readonly estimatedDurationMs: number;
+      readonly criticalPathScore: number;
+      readonly sampleCount: number;
+      readonly source: "learned" | "project-prior" | "cold-start";
+    }>
+  | Readonly<{ readonly kind: "recording-unavailable" }>;
+
+/**
+ * 构造普通公开 prepared strategy。调用方拥有 history location 与 identity projection；
+ * Product 只按同一 custom strategy lifecycle 调用它，不为该 helper 增加特权。
+ */
+export function createLearnedCriticalPathStrategy(
+  options: LearnedCriticalPathStrategyOptions
+): CustomAdmissionStrategy {
+  if (typeof options.stateDirectory !== "string" || !isAbsolute(options.stateDirectory)) {
+    throw new TypeError("learned critical-path stateDirectory must be an absolute path");
+  }
+  const model = modelOptions(options);
+  return Object.freeze({
+    kind: "prepared" as const,
+    prepare: async ({ graph }) => {
+      const predictionInputs = predictionInputsFor(graph, options.identityForTask, model);
+      if (predictionInputs === undefined) {
+        observe(options, { kind: "history-unavailable", reason: "identity-invalid" });
+        return Object.freeze({ decide: staticDecision });
+      }
+      const durationModel = await prepareSchedulerDurationModel({
+        predictionInputs,
+        stateDirectory: options.stateDirectory,
+        coldStartDurationMs: model.coldStartDurationMs,
+        maxSamplesPerSeries: model.sampleWindow,
+        maxSeries: model.maxHistorySeries
+      });
+      if (durationModel.kind === "static-fallback") {
+        observe(options, { kind: "history-unavailable", reason: "setup-failed" });
+        return Object.freeze({ decide: staticDecision });
+      }
+      let criticalPath: SchedulerCriticalPathSnapshot;
+      try {
+        criticalPath = createSchedulerCriticalPathSnapshot(graph, durationModel.prediction);
+      } catch {
+        observe(options, { kind: "history-unavailable", reason: "setup-failed" });
+        return Object.freeze({ decide: staticDecision });
+      }
+      return Object.freeze({
+        decide: (context: AdmissionPolicyContext) =>
+          learnedDecision(context, durationModel.prediction, criticalPath, options),
+        terminalEffect: async (context: SchedulerMeasurementContext) => {
+          const recorded = await durationModel.record(context);
+          if (recorded.kind === "failed" || recorded.writeObservation === "failed") {
+            observe(options, { kind: "recording-unavailable" });
+          }
+        }
+      });
+    }
+  });
+}
+
+function modelOptions(options: LearnedCriticalPathStrategyOptions): Readonly<{
+  readonly coldStartDurationMs: number;
+  readonly maxHistorySeries: number;
+  readonly sampleWindow: number;
+}> {
+  const coldStartDurationMs = options.coldStartDurationMs ?? 1;
+  const maxHistorySeries = options.maxHistorySeries ?? 4_096;
+  const sampleWindow = options.sampleWindow ?? 32;
+  validatePositiveFinite(coldStartDurationMs, "coldStartDurationMs");
+  validateBoundedInteger(maxHistorySeries, "maxHistorySeries", 4_096);
+  validateBoundedInteger(sampleWindow, "sampleWindow", 32);
+  return Object.freeze({ coldStartDurationMs, maxHistorySeries, sampleWindow });
+}
+
+function validatePositiveFinite(value: number, name: string): void {
+  if (!Number.isFinite(value) || value <= 0)
+    throw new TypeError(`learned critical-path ${name} must be positive and finite`);
+}
+
+function validateBoundedInteger(value: number, name: string, maximum: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum)
+    throw new TypeError(`learned critical-path ${name} must be a positive safe integer`);
+}
+
+function predictionInputsFor(
+  graph: SchedulerGraphSnapshot,
+  identityForTask: LearnedCriticalPathStrategyOptions["identityForTask"],
+  model: Readonly<{
+    readonly coldStartDurationMs: number;
+    readonly maxHistorySeries: number;
+    readonly sampleWindow: number;
+  }>
+): readonly SchedulerPredictionInput[] | undefined {
+  const inputs: SchedulerPredictionInput[] = [];
+  for (const task of graph.tasks) {
+    let identity: CanonicalJsonValue | undefined;
+    try {
+      identity = canonicalizeJsonValue({ historyKey: identityForTask(task), model });
+    } catch {
+      return undefined;
+    }
+    if (identity === undefined) return undefined;
+    inputs.push(
+      Object.freeze({
+        authoredOptions: identity,
+        checkId: task.taskId,
+        flags: null,
+        taskId: task.taskId
+      })
+    );
+  }
+  return Object.freeze(inputs);
+}
+
+function learnedDecision(
+  context: AdmissionPolicyContext,
+  prediction: SchedulerPredictionSnapshot,
+  criticalPath: SchedulerCriticalPathSnapshot,
+  options: LearnedCriticalPathStrategyOptions
+): AdmissionProposal {
+  const selected = selectLearnedCandidate(context, criticalPath);
+  if (!selected.canAdmit) return Object.freeze({ kind: "wait" });
+  const taskPrediction = predictionForTask(prediction, selected.taskId);
+  const score = criticalPathScoreForTask(criticalPath, selected.taskId);
+  if (taskPrediction !== undefined && score !== undefined) {
+    observe(
+      options,
+      Object.freeze({
+        kind: "selection-proposed",
+        taskId: selected.taskId,
+        criticalPathScore: score,
+        estimatedDurationMs: taskPrediction.estimatedDurationMs,
+        sampleCount: taskPrediction.sampleCount,
+        source: taskPrediction.source
+      })
+    );
+  }
+  return Object.freeze({ kind: "select", taskId: selected.taskId });
+}
+
+function selectLearnedCandidate(
+  context: AdmissionPolicyContext,
+  criticalPath: SchedulerCriticalPathSnapshot
+): AdmissionPolicyContext["candidates"][number] {
+  const layers = learnedSelectionLayers(context);
+  if (layers.tightening.length > 0)
+    return requiredFirst(
+      sortConstrained(layers.tightening, layers.taskById, layers.scopeById, criticalPath)
+    );
+  if (layers.continuation.length > 0)
+    return requiredFirst(
+      sortConstrained(layers.continuation, layers.taskById, layers.scopeById, criticalPath)
+    );
+  return requiredFirst(
+    [...context.candidates].sort(learnedCandidateComparator(layers.taskById, criticalPath))
+  );
+}
+
+function learnedCandidateComparator(
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  criticalPath: SchedulerCriticalPathSnapshot
+): (
+  left: AdmissionPolicyContext["candidates"][number],
+  right: AdmissionPolicyContext["candidates"][number]
+) => number {
+  return (left, right) => compareLearnedTasks(taskById, criticalPath, left.taskId, right.taskId);
+}
+
+function sortConstrained(
+  candidates: readonly AdmissionPolicyContext["candidates"][number][],
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  scopeById: ReadonlyMap<string, SchedulerGraphSnapshot["scopes"][number]>,
+  criticalPath: SchedulerCriticalPathSnapshot
+): AdmissionPolicyContext["candidates"][number][] {
+  return [...candidates].sort(learnedConstrainedComparator(taskById, scopeById, criticalPath));
+}
+
+function learnedConstrainedComparator(
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  scopeById: ReadonlyMap<string, SchedulerGraphSnapshot["scopes"][number]>,
+  criticalPath: SchedulerCriticalPathSnapshot
+): (
+  left: AdmissionPolicyContext["candidates"][number],
+  right: AdmissionPolicyContext["candidates"][number]
+) => number {
+  return (left, right) => {
+    const leftScope = requiredLearnedScope(left, taskById, scopeById);
+    const rightScope = requiredLearnedScope(right, taskById, scopeById);
+    return (
+      leftScope.maxParallel - rightScope.maxParallel ||
+      compareLearnedTasks(taskById, criticalPath, left.taskId, right.taskId) ||
+      compareText(leftScope.id, rightScope.id) ||
+      compareText(left.taskId, right.taskId)
+    );
+  };
+}
+
+function requiredLearnedScope(
+  candidate: AdmissionPolicyContext["candidates"][number],
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  scopeById: ReadonlyMap<string, SchedulerGraphSnapshot["scopes"][number]>
+): SchedulerGraphSnapshot["scopes"][number] {
+  const task = taskById.get(candidate.taskId);
+  const scope =
+    task?.scopeId === null || task === undefined ? undefined : scopeById.get(task.scopeId);
+  if (scope === undefined) throw new Error("constrained task is missing a scope");
+  return scope;
+}
+function compareLearnedTasks(
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  criticalPath: SchedulerCriticalPathSnapshot,
+  leftId: string,
+  rightId: string
+): number {
+  const left = taskById.get(leftId);
+  const right = taskById.get(rightId);
+  if (left === undefined || right === undefined)
+    throw new Error("learned candidate is missing from graph");
+  const leftScore = criticalPathScoreForTask(criticalPath, leftId);
+  const rightScore = criticalPathScoreForTask(criticalPath, rightId);
+  if (leftScore === undefined || rightScore === undefined)
+    throw new Error("learned scheduler score is missing");
+  return (
+    rightScore - leftScore ||
+    right.admissionPriority - left.admissionPriority ||
+    compareText(leftId, rightId)
+  );
+}
+
+function observe(
+  options: LearnedCriticalPathStrategyOptions,
+  event: LearnedCriticalPathObservation
+): void {
+  try {
+    const observed = options.observe?.(event);
+    if (observed !== undefined) void Promise.resolve(observed).catch(() => undefined);
+  } catch {
+    // Caller observation is contained.
+  }
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function requiredFirst<T>(values: readonly T[]): T {
+  const first = values[0];
+  if (first === undefined) throw new Error("learned strategy requires a candidate");
+  return first;
+}

package/src/project-definition/check-tree/authoring.ts

@@ -1,41 +1,42 @@
 import type { CheckDescriptor } from "../../check/descriptor.ts";
 import {
-  isInheritedCheckCollection,
-  snapshotInheritedCheckCollection,
-  type CheckVisibility,
-  type CheckExecution,
-  type CheckPreflight,
-  type InheritedCheckCollection
-} from "../../check/check.ts";
-import { snapshotClosedArray, snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
-import { validateCheckDescriptor } from "../../check/descriptor-validation.ts";
-import { snapshotJsonObject } from "../../check/options-snapshot.ts";
-
-type TrustedDataParser = (this: void, ...parameters: never[]) => unknown;
-
-export type ParsedCheckCollection = Readonly<
-  | { readonly kind: "exact"; readonly values: readonly string[] }
-  | {
-      readonly kind: "inherit";
-      readonly add: readonly string[];
-      readonly remove: readonly string[];
-    }
->;
+  getDefinedHandoffProviderIdentity,
+  type HandoffProviderIdentity
+} from "../../check/handoff-provider-identity.ts";
+import { snapshotClosedArray } from "../../data-boundary/closed-values.ts";
+import {
+  parseCheckAuthoringData,
+  parseCheckFieldPrelude,
+  parseCheckFields,
+  type CheckAuthoringData,
+  type ParsedCheckFields,
+  type ParsedCheckFieldPrelude,
+  type TrustedDataParser
+} from "./check-fields-authoring.ts";
+import { parseCheckScheduling, type ParsedCheckCollection } from "./scheduling-authoring.ts";
+import type { ResourceUnitMapping } from "../resource-unit-mapping.ts";
+
+export type { ParsedCheckCollection } from "./scheduling-authoring.ts";
 
 export interface ParsedCheck {
+  readonly admissionPriority: number | undefined;
   readonly checkId: string;
   readonly checks: readonly ParsedCheck[];
   readonly definition: CheckDescriptor | null;
   readonly dependsOn: ParsedCheckCollection | undefined;
   readonly displayName: string;
-  readonly execution: CheckExecution | null;
+  readonly enabledByFlags: ParsedCheckFieldPrelude["enabledByFlags"];
+  readonly execute: ParsedCheckFieldPrelude["execute"];
+  readonly handoff: HandoffProviderIdentity | null;
   readonly maxParallel: number | undefined;
   readonly mutex: ParsedCheckCollection | undefined;
+  readonly observes: ParsedCheckCollection | undefined;
+  readonly resourceClaims: ResourceUnitMapping | undefined;
   readonly options: object | null;
   readonly path: string;
   readonly parseData: TrustedDataParser | null;
-  readonly preflight: CheckPreflight | null;
-  readonly visibility: CheckVisibility | null;
+  readonly prepare: ParsedCheckFieldPrelude["prepare"];
+  readonly omitQuietPassedRow: ParsedCheckFields["omitQuietPassedRow"];
 }
 
 export interface ParsedCheckTree {
@@ -53,43 +54,6 @@ interface ParseState {
   readonly warnings: MeaninglessCheckWarning[];
 }
 
-interface CheckAuthoringData extends Readonly<Record<string, unknown>> {
-  readonly checkId: string;
-  readonly displayName: string;
-}
-
-interface ParsedCheckFields {
-  readonly definition: CheckDescriptor | null;
-  readonly execution: CheckExecution | null;
-  readonly options: object | null;
-  readonly parseData: TrustedDataParser | null;
-  readonly preflight: CheckPreflight | null;
-  readonly visibility: CheckVisibility | null;
-}
-
-const CHECK_KEYS = [
-  "checkId",
-  "checks",
-  "dependsOn",
-  "displayName",
-  "execution",
-  "maxParallel",
-  "mutex",
-  "options",
-  "parseData",
-  "preflight",
-  "visibility"
-] as const;
-
-const CONTAINER_CHECK_FIELDS: ParsedCheckFields = Object.freeze({
-  definition: null,
-  execution: null,
-  options: null,
-  parseData: null,
-  preflight: null,
-  visibility: null
-});
-
 /**
  * Parses only the closed recursive authoring grammar. Execution callbacks are
  * trusted project code, while every declarative field is copied and validated.
@@ -111,82 +75,40 @@ export function parseCheckTreeAuthoring(value: unknown): ParsedCheckTree | undef
 }
 
 function parseCheck(value: unknown, path: string, state: ParseState): ParsedCheck | undefined {
-  const data = parseCheckData(value);
+  const handoffProviderIdentity = getDefinedHandoffProviderIdentity(value);
+  const data = parseCheckAuthoringData(value);
   if (data === undefined) return undefined;
-  const execution = parseExecution(data);
-  if (execution === undefined) return undefined;
-  const parseData = parseDataParser(data);
-  if (parseData === undefined) return undefined;
-  const preflight = parsePreflight(data);
-  if (preflight === undefined) return undefined;
+  const prelude = parseCheckFieldPrelude(data, handoffProviderIdentity);
+  if (prelude === undefined) return undefined;
   const checks = parseChildren(data, path, state);
   if (checks === undefined) return undefined;
-  const scheduling = parseScheduling(data);
+  const scheduling = parseCheckScheduling(data);
   if (scheduling === undefined) return undefined;
-  const fields = parseCheckFields(data, execution, parseData, preflight);
+  const fields = parseCheckFields(data, prelude);
   if (fields === undefined) return undefined;
   warnForMeaninglessCheck(data, checks, fields, path, state);
-
   return Object.freeze({
+    admissionPriority: scheduling.admissionPriority,
     checkId: data.checkId,
     checks,
     definition: fields.definition,
     dependsOn: scheduling.dependsOn,
     displayName: data.displayName,
-    execution: fields.execution,
+    enabledByFlags: fields.enabledByFlags,
+    execute: fields.execute,
+    handoff: fields.handoff,
     maxParallel: scheduling.maxParallel,
     mutex: scheduling.mutex,
+    observes: scheduling.observes,
+    resourceClaims: scheduling.resourceClaims,
     options: fields.options,
     path,
     parseData: fields.parseData,
-    preflight: fields.preflight,
-    visibility: fields.visibility
+    prepare: fields.prepare,
+    omitQuietPassedRow: fields.omitQuietPassedRow
   });
 }
 
-function parseCheckData(value: unknown): CheckAuthoringData | undefined {
-  const data = snapshotClosedRecord(value);
-  if (data === undefined) return undefined;
-  return hasValidCheckIdentity(data) ? data : undefined;
-}
-
-function hasValidCheckIdentity(
-  data: Readonly<Record<string, unknown>>
-): data is CheckAuthoringData {
-  return (
-    hasOnlyCheckKeys(data) &&
-    typeof data.checkId === "string" &&
-    data.checkId.length > 0 &&
-    typeof data.displayName === "string" &&
-    data.displayName.length > 0
-  );
-}
-
-function hasOnlyCheckKeys(data: Readonly<Record<string, unknown>>): boolean {
-  return Object.keys(data).every((key) => CHECK_KEYS.some((checkKey) => checkKey === key));
-}
-
-function parseExecution(data: CheckAuthoringData): CheckExecution | null | undefined {
-  if (!Object.hasOwn(data, "execution")) return null;
-  return isTrustedFunction<CheckExecution>(data.execution) ? data.execution : undefined;
-}
-
-function parseDataParser(data: CheckAuthoringData): TrustedDataParser | null | undefined {
-  if (!Object.hasOwn(data, "parseData") || data.parseData === undefined) return null;
-  return isTrustedFunction<TrustedDataParser>(data.parseData) ? data.parseData : undefined;
-}
-
-function parsePreflight(data: CheckAuthoringData): CheckPreflight | null | undefined {
-  if (!Object.hasOwn(data, "preflight")) return null;
-  return isTrustedFunction<CheckPreflight>(data.preflight) ? data.preflight : undefined;
-}
-
-function isTrustedFunction<FunctionType extends (...parameters: never[]) => unknown>(
-  value: unknown
-): value is FunctionType {
-  return typeof value === "function";
-}
-
 function parseChildren(
   data: CheckAuthoringData,
   path: string,
@@ -204,59 +126,6 @@ function parseChildren(
   return Object.freeze(checks);
 }
 
-function parseDefinition(data: CheckAuthoringData): CheckDescriptor | undefined {
-  const definition = validateCheckDescriptor({
-    checkId: data.checkId,
-    displayName: data.displayName
-  });
-  return definition.ok ? definition.value : undefined;
-}
-
-function parseOptions(data: CheckAuthoringData): object | undefined {
-  if (!Object.hasOwn(data, "options")) return Object.freeze({});
-  const options = snapshotClosedRecord(data.options);
-  if (options === undefined) return undefined;
-  return snapshotJsonObject(options);
-}
-
-function parseCheckFields(
-  data: CheckAuthoringData,
-  execution: CheckExecution | null,
-  parseData: TrustedDataParser | null,
-  preflight: CheckPreflight | null
-): ParsedCheckFields | undefined {
-  if (execution === null) {
-    return Object.hasOwn(data, "options") ||
-      Object.hasOwn(data, "visibility") ||
-      parseData !== null ||
-      preflight !== null
-      ? undefined
-      : CONTAINER_CHECK_FIELDS;
-  }
-  const definition = parseDefinition(data);
-  if (definition === undefined) return undefined;
-  const options = parseOptions(data);
-  if (options === undefined) return undefined;
-  const visibility = parseVisibility(data);
-  if (visibility === undefined) return undefined;
-  return Object.freeze({
-    definition,
-    execution,
-    options,
-    parseData,
-    preflight,
-    visibility
-  });
-}
-
-function parseVisibility(data: CheckAuthoringData): CheckVisibility | undefined {
-  if (!Object.hasOwn(data, "visibility")) return "always";
-  const visibility = data.visibility;
-  return visibility === undefined || visibility === "always" || visibility === "attention"
-    ? (visibility ?? "always")
-    : undefined;
-}
-
 function warnForMeaninglessCheck(
   data: CheckAuthoringData,
   checks: readonly ParsedCheck[],
@@ -264,69 +133,6 @@ function warnForMeaninglessCheck(
   path: string,
   state: ParseState
 ): void {
-  if (fields.execution !== null || checks.length > 0) return;
+  if (fields.execute !== null || checks.length > 0) return;
   state.warnings.push(Object.freeze({ code: "meaningless-check", path, checkId: data.checkId }));
 }
-
-function parseScheduling(data: CheckAuthoringData):
-  | Readonly<{
-      readonly dependsOn: ParsedCheckCollection | undefined;
-      readonly maxParallel: number | undefined;
-      readonly mutex: ParsedCheckCollection | undefined;
-    }>
-  | undefined {
-  const dependsOn = parseCollection(data, "dependsOn");
-  const mutex = parseCollection(data, "mutex");
-  const maxParallel = data.maxParallel;
-  if (
-    dependsOn === null ||
-    mutex === null ||
-    (maxParallel !== undefined &&
-      (typeof maxParallel !== "number" || !Number.isSafeInteger(maxParallel) || maxParallel <= 0))
-  )
-    return undefined;
-  return Object.freeze({
-    dependsOn: dependsOn ?? undefined,
-    maxParallel,
-    mutex: mutex ?? undefined
-  });
-}
-
-function parseCollection(
-  data: CheckAuthoringData,
-  field: "dependsOn" | "mutex"
-): ParsedCheckCollection | null | undefined {
-  if (!Object.hasOwn(data, field)) return undefined;
-  const value = data[field];
-  if (isInheritedCheckCollection(value)) return parseInheritedCollection(value);
-  const values = parseCollectionItems(value);
-  return values === undefined ? null : Object.freeze({ kind: "exact", values });
-}
-
-function parseInheritedCollection(
-  value: InheritedCheckCollection<unknown>
-): ParsedCheckCollection | null {
-  const data = snapshotInheritedCheckCollection(value);
-  if (data === undefined || !hasExactInheritedKeys(data)) return null;
-  const add = data.add === undefined ? Object.freeze([]) : parseCollectionItems(data.add);
-  const remove = data.remove === undefined ? Object.freeze([]) : parseCollectionItems(data.remove);
-  if (add === undefined || remove === undefined) return null;
-  return Object.freeze({ kind: "inherit", add, remove });
-}
-
-function hasExactInheritedKeys(data: Readonly<Record<string, unknown>>): boolean {
-  const keys = Object.keys(data);
-  return keys.length > 0 && keys.every((key) => key === "add" || key === "remove");
-}
-
-function parseCollectionItems(value: unknown): readonly string[] | undefined {
-  const items = snapshotClosedArray(value);
-  if (items === undefined) return undefined;
-  const values: string[] = [];
-  for (const item of items) {
-    const valid = typeof item === "string" && item.length > 0;
-    if (!valid) return undefined;
-    if (!values.includes(item)) values.push(item);
-  }
-  return Object.freeze(values);
-}