@memoryengine/client 0.1.0

package/src/schemas/engram.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { temporalQuerySchema } from "./engram";
+
+describe("temporalQuerySchema", () => {
+  test("accepts empty object", () => {
+    expect(temporalQuerySchema.safeParse({}).success).toBe(true);
+  });
+
+  test("accepts single contains filter", () => {
+    const result = temporalQuerySchema.safeParse({
+      contains: "2024-01-01T00:00:00Z",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts single overlaps filter", () => {
+    const result = temporalQuerySchema.safeParse({
+      overlaps: ["2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z"],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts single within filter", () => {
+    const result = temporalQuerySchema.safeParse({
+      within: ["2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z"],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects contains + overlaps", () => {
+    const result = temporalQuerySchema.safeParse({
+      contains: "2024-01-01T00:00:00Z",
+      overlaps: ["2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z"],
+    });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues[0]?.message).toContain(
+        "exactly one of: contains, overlaps, within",
+      );
+    }
+  });
+
+  test("rejects contains + within", () => {
+    const result = temporalQuerySchema.safeParse({
+      contains: "2024-01-01T00:00:00Z",
+      within: ["2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z"],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects all three filters", () => {
+    const result = temporalQuerySchema.safeParse({
+      contains: "2024-01-01T00:00:00Z",
+      overlaps: ["2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z"],
+      within: ["2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z"],
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/engram.ts

@@ -0,0 +1,194 @@
+/**
+ * Engram schemas - shared between server and client
+ *
+ * Server: imports schemas for validation
+ * Client: imports inferred types for type safety
+ */
+import { z } from "zod";
+import {
+  contentField,
+  idField,
+  metaField,
+  treeField,
+  treeFilterField,
+} from "./fields";
+
+// ===== Input Schemas =====
+
+export const temporalSchema = z
+  .object({
+    start: z.string().describe("ISO timestamp for start of time range"),
+    end: z
+      .string()
+      .optional()
+      .describe("ISO timestamp for end (omit for point-in-time)"),
+  })
+  .describe("Time range for the memory");
+
+export const temporalQuerySchema = z
+  .object({
+    contains: z
+      .string()
+      .optional()
+      .describe("Find memories containing this point in time"),
+    overlaps: z
+      .tuple([z.string(), z.string()])
+      .optional()
+      .describe("[start, end] - find memories overlapping this range"),
+    within: z
+      .tuple([z.string(), z.string()])
+      .optional()
+      .describe("[start, end] - find memories fully within this range"),
+  })
+  .refine(
+    (data) => {
+      const defined = [data.contains, data.overlaps, data.within].filter(
+        (v) => v !== undefined,
+      );
+      return defined.length <= 1;
+    },
+    {
+      message:
+        "Temporal filter must use exactly one of: contains, overlaps, within",
+    },
+  )
+  .describe("Temporal filter for search");
+
+export const createEngramSchema = z.object({
+  id: idField.optional(),
+  content: contentField,
+  meta: metaField.optional(),
+  tree: treeField
+    .optional()
+    .describe(
+      "Hierarchical path (e.g., work.projects.me). Defaults to root path when omitted",
+    ),
+  temporal: temporalSchema.optional(),
+});
+
+export const batchCreateEngramSchema = z.object({
+  engrams: z.array(createEngramSchema).max(1000),
+});
+
+export const updateEngramSchema = z.object({
+  id: idField,
+  content: contentField.optional(),
+  meta: metaField.optional(),
+  tree: treeField.optional(),
+  temporal: temporalSchema.optional(),
+});
+
+export const getEngramSchema = z.object({
+  id: idField,
+});
+
+export const deleteEngramSchema = z.object({
+  id: idField,
+});
+
+export const mvEngramSchema = z.object({
+  source: treeField.min(1),
+  destination: treeField,
+  dry_run: z.boolean().optional().default(false),
+});
+
+export const mvEngramResultSchema = z.object({
+  moved: z.number().int(),
+  source: z.string(),
+  destination: z.string(),
+});
+
+export const searchEngramSchema = z
+  .object({
+    semantic: z.string().optional(),
+    fulltext: z.string().optional(),
+    meta: metaField.optional(),
+    tree: treeFilterField.optional(),
+    temporal: temporalQuerySchema.optional(),
+    limit: z.number().int().positive().max(1000).optional().default(100),
+    candidateLimit: z
+      .number()
+      .int()
+      .positive()
+      .min(1)
+      .max(1000)
+      .optional()
+      .default(30),
+    hybrid: z
+      .object({
+        weights: z
+          .object({
+            fulltext: z
+              .number()
+              .min(0)
+              .max(1)
+              .optional()
+              .describe("Weight for BM25 keyword matching (0-1)"),
+            semantic: z
+              .number()
+              .min(0)
+              .max(1)
+              .optional()
+              .describe("Weight for semantic similarity (0-1)"),
+          })
+          .optional()
+          .describe("Weights for hybrid search ranking (RRF)"),
+      })
+      .optional(),
+  })
+  .refine(
+    (data) =>
+      data.semantic || data.fulltext || data.meta || data.tree || data.temporal,
+    { message: "At least one search criterion required" },
+  );
+
+// ===== Output Schemas =====
+
+export const engramSchema = z.object({
+  id: idField,
+  content: contentField,
+  meta: metaField,
+  tree: treeField,
+  temporal: z.string().nullable(),
+  has_embedding: z.boolean().optional(),
+  created_at: z.string(),
+  updated_at: z.string().nullable(),
+});
+
+export const engramWithScoreSchema = engramSchema.extend({
+  score: z.number(),
+});
+
+export const searchEngramResultSchema = z.object({
+  results: z.array(engramWithScoreSchema),
+  total: z.number(),
+  limit: z.number(),
+});
+
+export const batchCreateResultSchema = z.object({
+  ids: z.array(z.uuidv7()),
+});
+
+export const deleteResultSchema = z.object({
+  success: z.literal(true),
+});
+
+// ===== Inferred Types (auto-generated from schemas) =====
+
+export type Temporal = z.infer<typeof temporalSchema>;
+export type TemporalQuery = z.infer<typeof temporalQuerySchema>;
+
+export type CreateEngramParams = z.infer<typeof createEngramSchema>;
+export type BatchCreateEngramParams = z.infer<typeof batchCreateEngramSchema>;
+export type UpdateEngramParams = z.infer<typeof updateEngramSchema>;
+export type GetEngramParams = z.infer<typeof getEngramSchema>;
+export type DeleteEngramParams = z.infer<typeof deleteEngramSchema>;
+export type SearchEngramParams = z.infer<typeof searchEngramSchema>;
+
+export type Engram = z.infer<typeof engramSchema>;
+export type EngramWithScore = z.infer<typeof engramWithScoreSchema>;
+export type SearchEngramResult = z.infer<typeof searchEngramResultSchema>;
+export type BatchCreateResult = z.infer<typeof batchCreateResultSchema>;
+export type DeleteResult = z.infer<typeof deleteResultSchema>;
+export type MvEngramParams = z.infer<typeof mvEngramSchema>;
+export type MvEngramResult = z.infer<typeof mvEngramResultSchema>;

package/src/schemas/fields.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { treeFilterField } from "./fields";
+
+describe("treeFilterField", () => {
+  test("accepts ltxtquery with plain labels", () => {
+    expect(treeFilterField.safeParse("knowledge & postgresql").success).toBe(
+      true,
+    );
+  });
+
+  test("accepts ltxtquery with underscored labels", () => {
+    expect(treeFilterField.safeParse("reference & sql_commands").success).toBe(
+      true,
+    );
+  });
+
+  test("accepts ltxtquery with negation", () => {
+    expect(treeFilterField.safeParse("api & !draft").success).toBe(true);
+  });
+
+  test("rejects ltxtquery with dotted path", () => {
+    const result = treeFilterField.safeParse("work.knowledge & postgresql");
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues[0]?.message).toContain(
+        "ltxtquery matches labels, not paths",
+      );
+    }
+  });
+
+  test("accepts lquery pattern (no &)", () => {
+    expect(treeFilterField.safeParse("work.*").success).toBe(true);
+  });
+
+  test("accepts exact ltree path (no &)", () => {
+    expect(treeFilterField.safeParse("work.projects.api").success).toBe(true);
+  });
+});

package/src/schemas/fields.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared field validators - single source of truth
+ *
+ * Both shared schemas and MCP tool schemas import from here.
+ * This prevents drift in core validation logic (e.g., uuidv7, content min length).
+ */
+import { z } from "zod";
+
+/** UUIDv7 for all engram IDs */
+export const idField = z.uuidv7();
+
+/** Memory content - non-empty string */
+export const contentField = z.string().min(1);
+
+/** Metadata - arbitrary key-value pairs */
+export const metaField = z.record(z.string(), z.unknown());
+
+/** Tree path - dot-separated hierarchy (write contexts) */
+export const treeField = z.string();
+
+/** Tree filter - ltree path, lquery pattern, or ltxtquery label search */
+export const treeFilterField = z.string().refine(
+  (val) => {
+    if (!val.includes("&")) return true;
+    const words = val
+      .replace(/[&|!()]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean);
+    return words.every((w) => !w.includes("."));
+  },
+  {
+    message:
+      'ltxtquery matches labels, not paths. Use individual labels with & (e.g., "knowledge & postgresql"), not dot-separated paths (e.g., "work.knowledge & postgresql").',
+  },
+);

package/src/schemas/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared schemas - import from here in both server and client
+ */
+
+// Auth schemas and types
+export * from "./auth";
+// Engram schemas and types
+export * from "./engram";
+// Shared field validators (single source of truth)
+export * from "./fields";
+// Principal schemas and types
+export * from "./principal";
+
+// RPC contract and type utilities
+export * from "./rpc";

package/src/schemas/principal.ts

@@ -0,0 +1,178 @@
+/**
+ * Principal management schemas - shared between server and client
+ */
+import { z } from "zod";
+import { principalSchema, successSchema } from "./auth";
+
+// ===== Input Schemas =====
+
+export const getPrincipalSchema = z.object({
+  name: z.string().min(1),
+});
+
+export const createPrincipalSchema = z.object({
+  name: z.string().min(1),
+  email: z.email().optional(),
+  password: z.string().min(8).optional(),
+  superuser: z.boolean().optional(),
+  createrole: z.boolean().optional(),
+  can_login: z.boolean().optional(),
+});
+
+export const deletePrincipalSchema = z.object({
+  name: z.string().min(1),
+});
+
+export const setPasswordSchema = z.object({
+  name: z.string().min(1),
+  password: z.string().min(8),
+});
+
+// ===== Tree Grant Schemas =====
+
+const treeActionSchema = z.enum(["read", "create", "update", "delete"]);
+
+export const grantTreeAccessSchema = z.object({
+  principal_name: z.string().min(1),
+  tree_path: z.string(),
+  actions: z.array(treeActionSchema).min(1),
+  with_grant_option: z.boolean().optional(),
+});
+
+export const revokeTreeAccessSchema = z.object({
+  principal_name: z.string().min(1),
+  tree_path: z.string(),
+});
+
+export const listTreeGrantsSchema = z.object({
+  principal_name: z.string().min(1).optional(),
+});
+
+export const checkTreeAccessSchema = z.object({
+  tree_path: z.string(),
+  action: treeActionSchema,
+});
+
+// ===== Role Membership Schemas =====
+
+export const addRoleMemberSchema = z.object({
+  role_name: z.string().min(1),
+  member_name: z.string().min(1),
+  with_admin_option: z.boolean().optional(),
+});
+
+export const removeRoleMemberSchema = z.object({
+  role_name: z.string().min(1),
+  member_name: z.string().min(1),
+});
+
+export const listRoleMembersSchema = z.object({
+  role_name: z.string().min(1),
+});
+
+export const listRolesForPrincipalSchema = z.object({
+  principal_name: z.string().min(1).optional(),
+});
+
+// ===== Tree Ownership Schemas =====
+
+export const setTreeOwnerSchema = z.object({
+  tree_path: z.string(),
+  principal_name: z.string().min(1),
+});
+
+export const removeTreeOwnerSchema = z.object({
+  tree_path: z.string(),
+});
+
+export const getTreeOwnerSchema = z.object({
+  tree_path: z.string(),
+});
+
+export const listTreeOwnersSchema = z.object({
+  principal_name: z.string().min(1).optional(),
+});
+
+// ===== Output Schemas =====
+
+export const principalListItemSchema = z.object({
+  id: z.uuidv7(),
+  email: z.email().nullable(),
+  name: z.string(),
+  superuser: z.boolean(),
+  createrole: z.boolean(),
+  can_login: z.boolean(),
+  created_at: z.string(),
+});
+
+export const principalDetailSchema = principalSchema.extend({
+  created_at: z.string(),
+});
+
+export const treeGrantSchema = z.object({
+  id: z.uuidv7(),
+  principal_id: z.uuidv7(),
+  tree_path: z.string(),
+  actions: z.array(z.string()),
+  with_grant_option: z.boolean(),
+  granted_by: z.uuidv7().nullable(),
+  created_at: z.string(),
+});
+
+export const roleMemberSchema = z.object({
+  id: z.uuidv7(),
+  name: z.string(),
+  email: z.email().nullable(),
+  superuser: z.boolean(),
+  can_login: z.boolean(),
+  with_admin_option: z.boolean(),
+  created_at: z.string(),
+});
+
+export const principalRoleSchema = z.object({
+  id: z.uuidv7(),
+  name: z.string(),
+  created_at: z.string(),
+});
+
+export const treeOwnerSchema = z.object({
+  tree_path: z.string(),
+  principal_id: z.uuidv7(),
+  principal_name: z.string(),
+  created_by: z.uuidv7().nullable(),
+  created_at: z.string(),
+});
+
+// Re-export success schema for convenience
+export { successSchema };
+
+// ===== Inferred Types =====
+
+export type GetPrincipalParams = z.infer<typeof getPrincipalSchema>;
+export type CreatePrincipalParams = z.infer<typeof createPrincipalSchema>;
+export type DeletePrincipalParams = z.infer<typeof deletePrincipalSchema>;
+export type SetPasswordParams = z.infer<typeof setPasswordSchema>;
+
+export type GrantTreeAccessParams = z.infer<typeof grantTreeAccessSchema>;
+export type RevokeTreeAccessParams = z.infer<typeof revokeTreeAccessSchema>;
+export type ListTreeGrantsParams = z.infer<typeof listTreeGrantsSchema>;
+export type CheckTreeAccessParams = z.infer<typeof checkTreeAccessSchema>;
+
+export type AddRoleMemberParams = z.infer<typeof addRoleMemberSchema>;
+export type RemoveRoleMemberParams = z.infer<typeof removeRoleMemberSchema>;
+export type ListRoleMembersParams = z.infer<typeof listRoleMembersSchema>;
+export type ListRolesForPrincipalParams = z.infer<
+  typeof listRolesForPrincipalSchema
+>;
+
+export type SetTreeOwnerParams = z.infer<typeof setTreeOwnerSchema>;
+export type RemoveTreeOwnerParams = z.infer<typeof removeTreeOwnerSchema>;
+export type GetTreeOwnerParams = z.infer<typeof getTreeOwnerSchema>;
+export type ListTreeOwnersParams = z.infer<typeof listTreeOwnersSchema>;
+
+export type PrincipalListItem = z.infer<typeof principalListItemSchema>;
+export type PrincipalDetail = z.infer<typeof principalDetailSchema>;
+export type TreeGrant = z.infer<typeof treeGrantSchema>;
+export type RoleMember = z.infer<typeof roleMemberSchema>;
+export type PrincipalRole = z.infer<typeof principalRoleSchema>;
+export type TreeOwner = z.infer<typeof treeOwnerSchema>;