@you-agent-factory/client 0.0.0

package/src/index.js

@@ -0,0 +1,5 @@
+export {
+  FactoryRecordingValidationError,
+  parseFactoryRecording,
+  safeParseFactoryRecording,
+} from "./recording-parser.js";

package/src/index.ts

@@ -0,0 +1,17 @@
+export type {
+  FactoryDefinition,
+  FactoryEvent,
+  FactoryEventType,
+  FactoryRecording,
+} from "./contracts.js";
+export type { components, operations, paths } from "./generated/openapi.js";
+export type {
+  FactoryRecordingParseResult,
+  FactoryRecordingValidationIssue,
+  FactoryRecordingValidationIssueCode,
+} from "./recording-parser.js";
+export {
+  FactoryRecordingValidationError,
+  parseFactoryRecording,
+  safeParseFactoryRecording,
+} from "./recording-parser.js";

package/src/recording-parser.d.ts

@@ -0,0 +1,37 @@
+import type { FactoryRecording } from "./contracts.js";
+
+export type FactoryRecordingValidationIssueCode =
+  | "INVALID_SHAPE"
+  | "UNSUPPORTED_RECORDING_VERSION"
+  | "UNSUPPORTED_EVENT_VERSION"
+  | "DUPLICATE_EVENT_ID"
+  | "MIXED_SESSION_ID"
+  | "NON_CANONICAL_ORDER"
+  | "MISSING_TOPOLOGY_BOOTSTRAP";
+
+export interface FactoryRecordingValidationIssue {
+  code: FactoryRecordingValidationIssueCode;
+  path: string;
+  message: string;
+  eventIndex?: number;
+  eventId?: string;
+}
+
+export class FactoryRecordingValidationError extends Error {
+  readonly issues: readonly FactoryRecordingValidationIssue[];
+  constructor(issues: readonly FactoryRecordingValidationIssue[]);
+}
+
+export type FactoryRecordingParseResult =
+  | { success: true; data: FactoryRecording }
+  | {
+      success: false;
+      error: FactoryRecordingValidationError;
+      issues: readonly FactoryRecordingValidationIssue[];
+    };
+
+export function safeParseFactoryRecording(
+  input: unknown,
+): FactoryRecordingParseResult;
+
+export function parseFactoryRecording(input: unknown): FactoryRecording;

package/src/recording-parser.js

@@ -0,0 +1,230 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import recordingSchema from "./generated/factory-recording.schema.json" with {
+  type: "json",
+};
+
+const TOPOLOGY_EVENT_TYPE = "INITIAL_STRUCTURE_REQUEST";
+
+// The standalone schema intentionally retains its OpenAPI discriminator as a
+// raw-data annotation. Mutation-affecting Ajv options stay explicitly disabled.
+const ajv = new Ajv2020({
+  allErrors: true,
+  coerceTypes: false,
+  removeAdditional: false,
+  strict: false,
+  useDefaults: false,
+});
+addFormats(ajv);
+const validateShape = ajv.compile(recordingSchema);
+
+export class FactoryRecordingValidationError extends Error {
+  constructor(issues) {
+    super(`Invalid Factory Recording: ${issues.length} validation issue(s)`);
+    this.name = "FactoryRecordingValidationError";
+    this.issues = Object.freeze([...issues]);
+  }
+}
+
+export function safeParseFactoryRecording(input) {
+  if (!validateShape(input)) {
+    return failure(shapeIssues(validateShape.errors ?? []));
+  }
+
+  const issues = semanticIssues(input);
+  return issues.length === 0 ? { success: true, data: input } : failure(issues);
+}
+
+export function parseFactoryRecording(input) {
+  const result = safeParseFactoryRecording(input);
+  if (!result.success) {
+    throw result.error;
+  }
+  return result.data;
+}
+
+function failure(issues) {
+  const error = new FactoryRecordingValidationError(issues);
+  return { success: false, error, issues: error.issues };
+}
+
+function shapeIssues(errors) {
+  return errors.map((error) => {
+    const path = issuePath(error);
+    const eventIndex = eventIndexFromPath(path);
+    const versionCode = versionIssueCode(error);
+    return {
+      code: versionCode ?? "INVALID_SHAPE",
+      path,
+      message: versionCode
+        ? `Unsupported schema version at ${path}.`
+        : `${path} ${error.message ?? "does not match the Factory Recording schema"}.`,
+      ...(eventIndex === undefined ? {} : { eventIndex }),
+    };
+  });
+}
+
+function issuePath(error) {
+  const property =
+    error.keyword === "required"
+      ? error.params.missingProperty
+      : error.keyword === "additionalProperties"
+        ? error.params.additionalProperty
+        : undefined;
+  if (typeof property !== "string") {
+    return error.instancePath || "/";
+  }
+  return `${error.instancePath}/${property.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+}
+
+function versionIssueCode(error) {
+  if (error.keyword !== "enum") {
+    return undefined;
+  }
+  if (error.instancePath === "/schemaVersion") {
+    return "UNSUPPORTED_RECORDING_VERSION";
+  }
+  return /^\/events\/\d+\/schemaVersion$/.test(error.instancePath)
+    ? "UNSUPPORTED_EVENT_VERSION"
+    : undefined;
+}
+
+function eventIndexFromPath(path) {
+  const match = /^\/events\/(\d+)(?:\/|$)/.exec(path);
+  return match ? Number(match[1]) : undefined;
+}
+
+function semanticIssues(recording) {
+  const issues = [];
+  const eventIds = new Set();
+  let hasTopology = false;
+
+  for (const [eventIndex, event] of recording.events.entries()) {
+    const location = { eventIndex, eventId: event.id };
+    if (eventIds.has(event.id)) {
+      issues.push({
+        code: "DUPLICATE_EVENT_ID",
+        path: `/events/${eventIndex}/id`,
+        message: `Event id ${JSON.stringify(event.id)} appears more than once.`,
+        ...location,
+      });
+    }
+    eventIds.add(event.id);
+
+    if (event.context.sessionId !== recording.sessionId) {
+      issues.push({
+        code: "MIXED_SESSION_ID",
+        path: `/events/${eventIndex}/context/sessionId`,
+        message: `Event sessionId must equal recording sessionId ${JSON.stringify(recording.sessionId)}.`,
+        ...location,
+      });
+    }
+
+    if (event.type === TOPOLOGY_EVENT_TYPE) {
+      hasTopology = true;
+    }
+
+    if (
+      eventIndex > 0 &&
+      compareEvents(recording.events[eventIndex - 1], event) > 0
+    ) {
+      issues.push({
+        code: "NON_CANONICAL_ORDER",
+        path: `/events/${eventIndex}`,
+        message:
+          "Event is out of canonical tick, sequence, eventTime, and id order.",
+        ...location,
+      });
+    }
+  }
+
+  if (!hasTopology) {
+    issues.push({
+      code: "MISSING_TOPOLOGY_BOOTSTRAP",
+      path: "/events",
+      message: `Recording must contain an ${TOPOLOGY_EVENT_TYPE} event.`,
+    });
+  }
+
+  return issues;
+}
+
+function compareEvents(left, right) {
+  return (
+    compareNumber(left.context.tick, right.context.tick) ||
+    compareNumber(left.context.sequence, right.context.sequence) ||
+    compareEventTime(left.context.eventTime, right.context.eventTime) ||
+    left.id.localeCompare(right.id)
+  );
+}
+
+function compareEventTime(left, right) {
+  const leftInstant = parseEventTime(left);
+  const rightInstant = parseEventTime(right);
+  return (
+    compareNumber(leftInstant.wholeSecond, rightInstant.wholeSecond) ||
+    compareNumber(leftInstant.phase, rightInstant.phase) ||
+    compareFraction(leftInstant.fraction, rightInstant.fraction)
+  );
+}
+
+function parseEventTime(value) {
+  const match =
+    /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2})$/i.exec(
+      value,
+    );
+  // Shape validation, including RFC 3339 format validation, runs before this
+  // semantic comparison. Keep this guard explicit if that boundary changes.
+  if (!match) {
+    throw new TypeError(`Validated eventTime is not RFC 3339: ${value}`);
+  }
+  const [, year, month, day, hour, minute, second, fraction, zone] = match;
+  const offsetSeconds =
+    zone.toUpperCase() === "Z"
+      ? 0
+      : (zone[0] === "+" ? 1 : -1) *
+        (Number(zone.slice(1, 3)) * 60 + Number(zone.slice(4, 6))) *
+        60;
+  const secondNumber = Number(second);
+  return {
+    wholeSecond:
+      daysFromCivil(Number(year), Number(month), Number(day)) * 86_400 +
+      Number(hour) * 3_600 +
+      Number(minute) * 60 +
+      secondNumber -
+      offsetSeconds,
+    // A leap second shares the next ordinary second's arithmetic boundary,
+    // but occurs immediately before it.
+    phase: secondNumber === 60 ? -1 : 0,
+    fraction: fraction ?? "",
+  };
+}
+
+function daysFromCivil(year, month, day) {
+  const adjustedYear = year - (month <= 2 ? 1 : 0);
+  const era = Math.floor(adjustedYear / 400);
+  const yearOfEra = adjustedYear - era * 400;
+  const adjustedMonth = month + (month > 2 ? -3 : 9);
+  const dayOfYear = Math.floor((153 * adjustedMonth + 2) / 5) + day - 1;
+  const dayOfEra =
+    yearOfEra * 365 +
+    Math.floor(yearOfEra / 4) -
+    Math.floor(yearOfEra / 100) +
+    dayOfYear;
+  return era * 146_097 + dayOfEra;
+}
+
+function compareFraction(left, right) {
+  const width = Math.max(left.length, right.length);
+  const normalizedLeft = left.padEnd(width, "0");
+  const normalizedRight = right.padEnd(width, "0");
+  return normalizedLeft === normalizedRight
+    ? 0
+    : normalizedLeft < normalizedRight
+      ? -1
+      : 1;
+}
+
+function compareNumber(left, right) {
+  return left === right ? 0 : left < right ? -1 : 1;
+}