@av-pi-studio/protocol 0.0.1

package/dist/validation.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/**
+ * Shared validation conventions for Pi-Studio.
+ *
+ * Every wire frame and every on-disk JSON document is parsed through Zod before it is trusted
+ * (MAIN-SCOPE.md §9). These helpers are the backbone of "validate at every boundary" and are
+ * reused by the protocol message schemas and the file-based persistence stores.
+ *
+ * ## Append-only compatibility rules (always)
+ *
+ * Schemas are **append-only**. A 6-month-old client must still parse new-daemon messages and
+ * vice-versa. Concretely:
+ *
+ * - **New fields are optional with a default or transform.** Use {@link optionalWithDefault} so a
+ *   missing field deserializes to a known value instead of `undefined`.
+ * - **Never flip `optional` → `required`.** Once a field is optional it stays optional.
+ * - **Never remove a field.** Stop *sending* it if you must, but keep *reading* it.
+ * - **Never narrow a type** (e.g. `string` → enum, `nullable` → non-null). New enum values are
+ *   gated at serialization behind capability flags so old clients only ever receive values they
+ *   advertised support for.
+ *
+ * ## COMPAT(name) convention
+ *
+ * Back-compat shims are tagged so a single grep (`COMPAT(`) lists all pending cleanup work. Each
+ * tag records the version the shim was added in and the date it may be removed. Use {@link COMPAT}
+ * at the call site of a shim, e.g.:
+ *
+ * ```ts
+ * // COMPAT(legacy-provider-key): added 1.2.0, remove by 2026-12-31
+ * const normalized = COMPAT({ name: "legacy-provider-key", addedIn: "1.2.0", removeBy: "2026-12-31" });
+ * ```
+ */
+/** Metadata describing a back-compat shim. Grep `COMPAT(` to enumerate cleanup work. */
+export interface CompatTag {
+    /** Stable identifier for the shim (kebab-case). */
+    readonly name: string;
+    /** Version the shim was introduced in (semver). */
+    readonly addedIn: string;
+    /** ISO date (YYYY-MM-DD) after which the shim may be removed. */
+    readonly removeBy: string;
+}
+/**
+ * Marks a back-compat shim. Returns the tag unchanged so it can be used inline; its real value is
+ * the grep-able `COMPAT(` token and the structured metadata it carries.
+ */
+export declare function COMPAT(tag: CompatTag): CompatTag;
+/**
+ * Append-only field helper: declares a schema field that is optional on the wire/disk but always
+ * resolves to a concrete default once parsed. This is the sanctioned way to add new fields without
+ * breaking older producers that omit them.
+ */
+export declare function optionalWithDefault<S extends z.ZodTypeAny>(schema: S, defaultValue: z.infer<S>): z.ZodDefault<z.ZodOptional<S>>;
+/**
+ * Parse `value` with `schema`, returning the parsed value on success or `defaults` on any failure.
+ * Used by the file-based stores so corrupt/partial JSON falls back to defaults instead of crashing
+ * the daemon (architecture/persistence.md — "Corrupt/partial JSON → fall back to defaults").
+ */
+export declare function safeParseOrDefault<S extends z.ZodTypeAny>(schema: S, value: unknown, defaults: z.infer<S>): z.infer<S>;
+/**
+ * ISO-8601 timestamp string (UTC `Z` or explicit offset), e.g. `2026-06-11T15:00:00.000Z`.
+ * Timeline row timestamps are canonical, daemon-owned strings (MAIN-SCOPE.md §9).
+ */
+export declare const isoTimestampSchema: z.ZodString;
+/** RFC-4122 UUID string (the primary key shape for agents, chat rooms, messages, etc.). */
+export declare const uuidSchema: z.ZodString;
+/**
+ * base64url character set with no padding (`A–Z a–z 0–9 - _`). The encoding used for stable ids
+ * like the daemon `server-id` (`srv_<base64url>`).
+ */
+export declare const base64UrlSchema: z.ZodString;
+/** Returns true if `value` is a non-empty base64url string. */
+export declare function isBase64Url(value: string): boolean;
+/**
+ * Schema for a prefixed base64url id of the form `${prefix}_<base64url>` (e.g. `srv_AbC-123`).
+ */
+export declare function prefixedIdSchema(prefix: string): z.ZodString;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,wFAAwF;AACxF,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACxD,MAAM,EAAE,CAAC,EACT,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GACvB,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACvD,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GACnB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAGZ;AAMD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,aAAwC,CAAC;AAExE,2FAA2F;AAC3F,eAAO,MAAM,UAAU,aAAoB,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,eAAe,aAA6D,CAAC;AAE1F,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,SAAS,CAK5D"}

package/dist/validation.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+/**
+ * Marks a back-compat shim. Returns the tag unchanged so it can be used inline; its real value is
+ * the grep-able `COMPAT(` token and the structured metadata it carries.
+ */
+export function COMPAT(tag) {
+    return tag;
+}
+/**
+ * Append-only field helper: declares a schema field that is optional on the wire/disk but always
+ * resolves to a concrete default once parsed. This is the sanctioned way to add new fields without
+ * breaking older producers that omit them.
+ */
+export function optionalWithDefault(schema, defaultValue) {
+    return schema.optional().default(defaultValue);
+}
+/**
+ * Parse `value` with `schema`, returning the parsed value on success or `defaults` on any failure.
+ * Used by the file-based stores so corrupt/partial JSON falls back to defaults instead of crashing
+ * the daemon (architecture/persistence.md — "Corrupt/partial JSON → fall back to defaults").
+ */
+export function safeParseOrDefault(schema, value, defaults) {
+    const result = schema.safeParse(value);
+    return result.success ? result.data : defaults;
+}
+// ---------------------------------------------------------------------------
+// Shared primitive schemas
+// ---------------------------------------------------------------------------
+/**
+ * ISO-8601 timestamp string (UTC `Z` or explicit offset), e.g. `2026-06-11T15:00:00.000Z`.
+ * Timeline row timestamps are canonical, daemon-owned strings (MAIN-SCOPE.md §9).
+ */
+export const isoTimestampSchema = z.string().datetime({ offset: true });
+/** RFC-4122 UUID string (the primary key shape for agents, chat rooms, messages, etc.). */
+export const uuidSchema = z.string().uuid();
+/**
+ * base64url character set with no padding (`A–Z a–z 0–9 - _`). The encoding used for stable ids
+ * like the daemon `server-id` (`srv_<base64url>`).
+ */
+export const base64UrlSchema = z.string().regex(/^[A-Za-z0-9_-]+$/, "expected base64url");
+/** Returns true if `value` is a non-empty base64url string. */
+export function isBase64Url(value) {
+    return base64UrlSchema.safeParse(value).success;
+}
+/**
+ * Schema for a prefixed base64url id of the form `${prefix}_<base64url>` (e.g. `srv_AbC-123`).
+ */
+export function prefixedIdSchema(prefix) {
+    const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return z
+        .string()
+        .regex(new RegExp(`^${escaped}_[A-Za-z0-9_-]+$`), `expected ${prefix}_<base64url> id`);
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4CxB;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,GAAc;IACnC,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAS,EACT,YAAwB;IAExB,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAS,EACT,KAAc,EACd,QAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAE,MAAM,CAAC,IAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC;AACjE,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAExE,2FAA2F;AAC3F,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;AAE5C;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;AAE1F,+DAA+D;AAC/D,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC9D,OAAO,CAAC;SACL,MAAM,EAAE;SACR,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,OAAO,kBAAkB,CAAC,EAAE,YAAY,MAAM,iBAAiB,CAAC,CAAC;AAC3F,CAAC"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@av-pi-studio/protocol",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  }
+}