@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/sync/push-event.ts

@@ -1,224 +0,0 @@
-/**
- * PushEvent — the wire-shared payload exchanged between every link in the
- * event-driven-hq-cloud-sync pipeline.
- *
- * Producers (the watcher) emit one PushEvent per local content change or
- * delete tombstone.
- * Consumers (the push endpoint / receiver / coalescer) decode the payload,
- * validate it, and act on it. Because the same shape crosses a network
- * boundary, it has its own dedicated module.
- *
- * Conventions
- * ───────────
- * - `kind` is `"upsert"` for content changes and `"delete"` for delete
- *   tombstones. Missing `kind` defaults to `"upsert"` for older producers.
- * - `contentHash` is required for upserts and absent for delete tombstones.
- *   It is `sha256:<64-lowercase-hex>`. The `<algorithm>:<hex>` prefix lets a
- *   future hash migration ship without breaking the wire format — consumers
- *   can branch on the prefix and fall back to refusing unknown algorithms.
- * - `mtime` and `eventTimestamp` are strict ISO-8601 datetime strings.
- *   `mtime` is the filesystem modification time of the source file at the
- *   moment of capture; `eventTimestamp` is when the watcher emitted the
- *   event. They diverge whenever the watcher coalesces or retries.
- * - `sequenceNumber` is a non-negative safe integer. Monotonicity per
- *   `originDeviceId` is a producer-side invariant — a single PushEvent
- *   can't be self-monotonic, so the schema only validates the bounds.
- * - Unknown extra fields are dropped silently by `decodePushEvent` to
- *   permit forwards-compatible additions on the producer side without
- *   forcing every consumer to upgrade in lockstep.
- *
- * Ported from indigoai-us/hq-pro PR #112 (src/sync/push-event.ts) into
- * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
- */
-
-import { z } from "zod";
-
-// ─── Constants ─────────────────────────────────────────────────────────────
-
-/**
- * `sha256:` + 64 lowercase hex chars. The algorithm prefix is mandatory so
- * future hash migrations stay non-breaking; consumers can switch on the
- * prefix and reject unknown algorithms explicitly.
- */
-export const CONTENT_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
-
-/**
- * Strict ISO-8601 datetime regex matching what `z.iso.datetime()` produces.
- *
- * Format: `YYYY-MM-DDTHH:MM:SS(.fff)?(Z|±HH:MM)`
- */
-export const ISO8601_DATETIME_PATTERN =
-  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
-
-// ─── Zod schema ────────────────────────────────────────────────────────────
-
-/**
- * Runtime schema for PushEvent. Unknown extra keys are dropped via the zod
- * default `.strip()` behavior — that is load-bearing for forwards
- * compatibility (see module JSDoc).
- */
-export const PushEventSchema = z
-  .object({
-    relativePath: z
-      .string()
-      .min(1, "relativePath must be a non-empty string"),
-    kind: z.enum(["upsert", "delete"]).optional().default("upsert"),
-    contentHash: z
-      .string()
-      .regex(
-        CONTENT_HASH_PATTERN,
-        "contentHash must match `sha256:<64 lowercase hex>`",
-      )
-      .optional(),
-    mtime: z
-      .string()
-      .regex(ISO8601_DATETIME_PATTERN, "mtime must be an ISO-8601 datetime")
-      .optional(),
-    originDeviceId: z
-      .string()
-      .min(1, "originDeviceId must be a non-empty string"),
-    originTenantId: z
-      .string()
-      .min(1, "originTenantId must be a non-empty string"),
-    sequenceNumber: z
-      .number()
-      .int("sequenceNumber must be an integer")
-      .min(0, "sequenceNumber must be non-negative")
-      .max(
-        Number.MAX_SAFE_INTEGER,
-        "sequenceNumber must be <= Number.MAX_SAFE_INTEGER",
-      ),
-    eventTimestamp: z
-      .string()
-      .regex(
-        ISO8601_DATETIME_PATTERN,
-        "eventTimestamp must be an ISO-8601 datetime",
-      ),
-  })
-  // `.strip()` is the zod 4 default; called explicitly here so the intent is
-  // obvious to future readers. Unknown keys MUST NOT throw — see module JSDoc.
-  .strip()
-  .refine(
-    (e) => e.kind === "delete" || (e.contentHash != null && e.mtime != null),
-    { message: "upsert requires contentHash and mtime" },
-  );
-
-/**
- * The canonical decoded PushEvent type. `kind` is always present after decode;
- * `contentHash` and `mtime` are present for upserts and absent for deletes.
- */
-export type PushEvent = z.output<typeof PushEventSchema>;
-
-/**
- * Input accepted by the schema. Kept public so encode callers can hand in
- * legacy upsert payloads where `kind` is absent.
- */
-export type PushEventInput = z.input<typeof PushEventSchema>;
-
-// ─── Errors ────────────────────────────────────────────────────────────────
-
-/**
- * Public alias for a single decode issue. Aliased here (rather than re-exporting
- * the `$`-prefixed zod internal symbol directly) so consumers can annotate
- * against `PushEventDecodeIssue` without importing zod internals. The alias is
- * structurally identical to `z.core.$ZodIssue`, so this is a non-breaking
- * narrowing of the public surface.
- */
-export type PushEventDecodeIssue = z.core.$ZodIssue;
-
-/**
- * Thrown by `decodePushEvent` (and `encodePushEvent` on invalid input) when
- * the payload fails validation. `.issues` carries the underlying zod issues
- * so callers can render structured diagnostics — see the test suite for an
- * example of asserting on the issue path.
- */
-export class PushEventDecodeError extends Error {
-  readonly issues: readonly PushEventDecodeIssue[];
-  readonly stage: "json-parse" | "schema-validation";
-
-  constructor(
-    message: string,
-    args: {
-      issues: readonly PushEventDecodeIssue[];
-      stage: "json-parse" | "schema-validation";
-      cause?: unknown;
-    },
-  ) {
-    super(message, args.cause === undefined ? undefined : { cause: args.cause });
-    this.name = "PushEventDecodeError";
-    this.issues = args.issues;
-    this.stage = args.stage;
-  }
-}
-
-// ─── Encode / Decode ───────────────────────────────────────────────────────
-
-/**
- * Validate `event` against `PushEventSchema` and return the canonical JSON
- * serialization. Validating on encode catches producer-side mistakes early
- * (and ensures the output always round-trips through `decodePushEvent`).
- *
- * Extra keys on `event` are dropped — the returned JSON string contains
- * only the declared PushEvent fields.
- */
-export function encodePushEvent(event: PushEventInput): string {
-  const parsed = PushEventSchema.safeParse(event);
-  if (!parsed.success) {
-    throw new PushEventDecodeError(
-      "encodePushEvent: input failed PushEvent schema validation",
-      { issues: parsed.error.issues, stage: "schema-validation" },
-    );
-  }
-  return JSON.stringify(parsed.data);
-}
-
-/**
- * Parse and validate an incoming PushEvent. Accepts either a raw JSON string
- * (the on-the-wire form) or an already-parsed object (handy for in-process
- * wiring and tests).
- *
- * - Unknown extra fields are dropped silently — see module JSDoc.
- * - Missing required fields throw `PushEventDecodeError` whose `.issues`
- *   exposes the underlying zod issues.
- * - Malformed JSON throws `PushEventDecodeError` with `stage:"json-parse"`
- *   and a synthetic issue at the root path.
- * - A JSON string that parses to a non-object value (e.g. `'42'`, `'"text"'`,
- *   `'null'`) surfaces as `stage: 'schema-validation'` — the JSON itself was
- *   syntactically valid, so it clears the parse stage before failing the
- *   object-shape check.
- */
-export function decodePushEvent(input: unknown): PushEvent {
-  let candidate: unknown = input;
-
-  if (typeof input === "string") {
-    try {
-      candidate = JSON.parse(input);
-    } catch (err) {
-      throw new PushEventDecodeError(
-        "decodePushEvent: input string is not valid JSON",
-        {
-          issues: [
-            {
-              code: "custom",
-              message:
-                err instanceof Error ? err.message : "invalid JSON input",
-              path: [],
-              input,
-            } as PushEventDecodeIssue,
-          ],
-          stage: "json-parse",
-          cause: err,
-        },
-      );
-    }
-  }
-
-  const parsed = PushEventSchema.safeParse(candidate);
-  if (!parsed.success) {
-    throw new PushEventDecodeError(
-      "decodePushEvent: payload failed PushEvent schema validation",
-      { issues: parsed.error.issues, stage: "schema-validation" },
-    );
-  }
-  return parsed.data;
-}