@hasna/contacts 0.6.33 → 0.6.35

package/dist/cli/index.js

@@ -2210,7 +2210,10 @@ function uuid() {
   return crypto.randomUUID();
 }
 function now2() {
-  return new Date().toISOString();
+  const currentMs = Date.now();
+  const nextMs = currentMs > lastNowMs ? currentMs : lastNowMs + 1;
+  lastNowMs = nextMs;
+  return new Date(nextMs).toISOString();
 }
 function quoteIdentifier(identifier) {
   return `"${identifier.replaceAll('"', '""')}"`;
@@ -2248,7 +2251,7 @@ function runMigrations(db) {
     db.exec(`INSERT OR REPLACE INTO _migrations(version) VALUES(${i})`);
   }
 }
-var MIGRATIONS, _db = null;
+var MIGRATIONS, _db = null, lastNowMs = 0;
 var init_database = __esm(() => {
   init_sqlite_adapter();
   init_paths();
@@ -2820,6 +2823,81 @@ var init_database = __esm(() => {
   );
 
   CREATE INDEX IF NOT EXISTS idx_contacts_tombstones_deleted_at ON _contacts_tombstones(deleted_at);
+  `,
+    `
+  CREATE TABLE IF NOT EXISTS contact_project_membership_states (
+    contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+    project_id TEXT NOT NULL,
+    linked INTEGER NOT NULL CHECK(linked IN (0, 1)),
+    revision INTEGER NOT NULL DEFAULT 0 CHECK(revision >= 0),
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (contact_id, project_id)
+  );
+
+  INSERT OR IGNORE INTO contact_project_membership_states
+    (contact_id, project_id, linked, revision, updated_at)
+  SELECT contact_id, project_id, 1, 0, datetime('now')
+  FROM contact_projects;
+
+  CREATE TABLE IF NOT EXISTS contact_project_membership_receipts (
+    receipt_id TEXT PRIMARY KEY,
+    direction TEXT NOT NULL CHECK(direction IN ('attach', 'detach')),
+    contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+    project_id TEXT NOT NULL,
+    operation_id TEXT NOT NULL,
+    step_id TEXT NOT NULL,
+    expected_version TEXT NOT NULL,
+    before_json TEXT NOT NULL,
+    after_json TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    UNIQUE(operation_id, step_id)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_contact_project_membership_states_project
+    ON contact_project_membership_states(project_id, linked, contact_id);
+  CREATE INDEX IF NOT EXISTS idx_contact_project_membership_receipts_target
+    ON contact_project_membership_receipts(contact_id, project_id, created_at);
+
+  CREATE TRIGGER IF NOT EXISTS sync_contact_project_membership_state_after_insert
+  AFTER INSERT ON contact_projects
+  BEGIN
+    INSERT INTO contact_project_membership_states
+      (contact_id, project_id, linked, revision, updated_at)
+    VALUES (NEW.contact_id, NEW.project_id, 1, 1, datetime('now'))
+    ON CONFLICT(contact_id, project_id) DO UPDATE SET
+      linked = 1,
+      revision = CASE
+        WHEN contact_project_membership_states.linked = 1
+          THEN contact_project_membership_states.revision
+        ELSE contact_project_membership_states.revision + 1
+      END,
+      updated_at = CASE
+        WHEN contact_project_membership_states.linked = 1
+          THEN contact_project_membership_states.updated_at
+        ELSE datetime('now')
+      END;
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS sync_contact_project_membership_state_after_delete
+  AFTER DELETE ON contact_projects
+  WHEN EXISTS (SELECT 1 FROM contacts WHERE id = OLD.contact_id)
+  BEGIN
+    INSERT INTO contact_project_membership_states
+      (contact_id, project_id, linked, revision, updated_at)
+    VALUES (OLD.contact_id, OLD.project_id, 0, 1, datetime('now'))
+    ON CONFLICT(contact_id, project_id) DO UPDATE SET
+      linked = 0,
+      revision = CASE
+        WHEN contact_project_membership_states.linked = 0
+          THEN contact_project_membership_states.revision
+        ELSE contact_project_membership_states.revision + 1
+      END,
+      updated_at = CASE
+        WHEN contact_project_membership_states.linked = 0
+          THEN contact_project_membership_states.updated_at
+        ELSE datetime('now')
+      END;
+  END;
   `
   ];
 });
@@ -2990,6 +3068,219 @@ var init_tombstones = __esm(() => {
   init_database();
 });
 
+// src/types/project-memberships.ts
+var ContactProjectMembershipConflictError;
+var init_project_memberships = __esm(() => {
+  ContactProjectMembershipConflictError = class ContactProjectMembershipConflictError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "ContactProjectMembershipConflictError";
+    }
+  };
+});
+
+// src/db/project-memberships.ts
+import { createHash } from "crypto";
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function membershipVersion(contactId, projectId, linked, revision) {
+  return `cpmv_${digest(JSON.stringify([contactId, projectId, linked, revision])).slice(0, 32)}`;
+}
+function receiptId(input) {
+  return `cpmr_${digest(JSON.stringify([
+    input.operation_id,
+    input.step_id,
+    input.contact_id,
+    input.project_id
+  ])).slice(0, 32)}`;
+}
+function stateRow(contactId, projectId, db) {
+  const persisted = db.query(`SELECT contact_id, project_id, linked, revision
+     FROM contact_project_membership_states
+     WHERE contact_id = ? AND project_id = ?`).get(contactId, projectId);
+  if (persisted)
+    return persisted;
+  const linked = Boolean(db.query(`SELECT 1 AS present FROM contact_projects WHERE contact_id = ? AND project_id = ?`).get(contactId, projectId));
+  return { contact_id: contactId, project_id: projectId, linked: linked ? 1 : 0, revision: 0 };
+}
+function snapshot(row) {
+  const linked = Boolean(row.linked);
+  return {
+    contact_id: row.contact_id,
+    project_id: row.project_id,
+    linked,
+    version: membershipVersion(row.contact_id, row.project_id, linked, row.revision)
+  };
+}
+function required(value, name) {
+  const normalized = value.trim();
+  if (!normalized)
+    throw new Error(`${name} is required`);
+  return normalized;
+}
+function normalizeInput(input) {
+  return {
+    contact_id: required(input.contact_id, "contact_id"),
+    project_id: required(input.project_id, "project_id"),
+    operation_id: required(input.operation_id, "operation_id"),
+    step_id: required(input.step_id, "step_id"),
+    expected_version: required(input.expected_version, "expected_version")
+  };
+}
+function parseSnapshot(value) {
+  return JSON.parse(value);
+}
+function replay(row, direction, input) {
+  if (row.direction !== direction || row.contact_id !== input.contact_id || row.project_id !== input.project_id || row.expected_version !== input.expected_version) {
+    throw new ContactProjectMembershipConflictError(`operation_id/step_id already accepted for a different contact-project membership mutation`);
+  }
+  return {
+    outcome: "duplicate_of_accepted",
+    operation_id: row.operation_id,
+    step_id: row.step_id,
+    before: parseSnapshot(row.before_json),
+    after: parseSnapshot(row.after_json),
+    receipt_id: row.receipt_id
+  };
+}
+function transitionWithoutReceipt(contactId, projectId, linked, db) {
+  const beforeRow = stateRow(contactId, projectId, db);
+  const changed = Boolean(beforeRow.linked) !== linked;
+  const afterRow = {
+    ...beforeRow,
+    linked: linked ? 1 : 0,
+    revision: changed ? beforeRow.revision + 1 : beforeRow.revision
+  };
+  const changedAt = now2();
+  db.run(`INSERT INTO contact_project_membership_states
+       (contact_id, project_id, linked, revision, updated_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(contact_id, project_id) DO UPDATE SET
+       linked = excluded.linked,
+       revision = excluded.revision,
+       updated_at = excluded.updated_at`, [contactId, projectId, afterRow.linked, afterRow.revision, changedAt]);
+  if (linked) {
+    db.run(`INSERT OR IGNORE INTO contact_projects (contact_id, project_id) VALUES (?, ?)`, [contactId, projectId]);
+  } else {
+    db.run(`DELETE FROM contact_projects WHERE contact_id = ? AND project_id = ?`, [contactId, projectId]);
+  }
+  return changed;
+}
+function setContactProjectMembershipWithoutReceipt(contactId, projectId, linked, db = getDatabase()) {
+  const normalizedContactId = required(contactId, "contact_id");
+  const normalizedProjectId = required(projectId, "project_id");
+  return db.transaction(() => transitionWithoutReceipt(normalizedContactId, normalizedProjectId, linked, db));
+}
+function replaceContactProjectMembershipsWithoutReceipts(contactId, projectIds, db = getDatabase()) {
+  const normalizedContactId = required(contactId, "contact_id");
+  const normalizedProjectIds = [...new Set(projectIds.map((projectId) => required(projectId, "project_id")))];
+  return db.transaction(() => {
+    const currentRows = db.query(`SELECT project_id FROM contact_projects WHERE contact_id = ?`).all(normalizedContactId);
+    const desired = new Set(normalizedProjectIds);
+    const population = new Set([...currentRows.map((row) => row.project_id), ...normalizedProjectIds]);
+    for (const projectId of population) {
+      transitionWithoutReceipt(normalizedContactId, projectId, desired.has(projectId), db);
+    }
+    return normalizedProjectIds;
+  });
+}
+function readContactProjectMembership(contactId, projectId, db = getDatabase()) {
+  return snapshot(stateRow(required(contactId, "contact_id"), required(projectId, "project_id"), db));
+}
+function listContactProjectMemberships(projectId, maxItems, db = getDatabase()) {
+  const normalizedProjectId = required(projectId, "project_id");
+  if (!Number.isInteger(maxItems) || maxItems < 1)
+    throw new Error("max_items must be a positive integer");
+  const rows = db.query(`SELECT cp.contact_id, cp.project_id,
+            COALESCE(state.linked, 1) AS linked,
+            COALESCE(state.revision, 0) AS revision
+     FROM contact_projects cp
+     LEFT JOIN contact_project_membership_states state
+       ON state.contact_id = cp.contact_id AND state.project_id = cp.project_id
+     WHERE cp.project_id = ?
+     ORDER BY cp.contact_id ASC
+     LIMIT ?`).all(normalizedProjectId, maxItems + 1);
+  if (rows.length > maxItems) {
+    throw new Error(`contact project membership collection exceeds max_items=${maxItems}`);
+  }
+  const contactIds = rows.map((row) => row.contact_id);
+  return {
+    project_id: normalizedProjectId,
+    contact_ids: contactIds,
+    complete: true,
+    membership_revision: `cpml_${digest(JSON.stringify(rows.map((row) => snapshot(row)))).slice(0, 32)}`
+  };
+}
+function mutateContactProjectMembership(direction, rawInput, db = getDatabase()) {
+  const input = normalizeInput(rawInput);
+  return db.transaction(() => {
+    const existingReceipt = db.query(`SELECT direction, contact_id, project_id, operation_id, step_id, expected_version,
+              before_json, after_json, receipt_id
+       FROM contact_project_membership_receipts
+       WHERE operation_id = ? AND step_id = ?`).get(input.operation_id, input.step_id);
+    if (existingReceipt)
+      return replay(existingReceipt, direction, input);
+    const contact = db.query(`SELECT id FROM contacts WHERE id = ?`).get(input.contact_id);
+    if (!contact)
+      throw new Error(`contact not found: ${input.contact_id}`);
+    const beforeRow = stateRow(input.contact_id, input.project_id, db);
+    const before = snapshot(beforeRow);
+    if (before.version !== input.expected_version) {
+      throw new ContactProjectMembershipConflictError(`contact project membership expected_version conflict: expected ${input.expected_version}, current ${before.version}`);
+    }
+    const desiredLinked = direction === "attach";
+    const changed = before.linked !== desiredLinked;
+    const afterRow = {
+      ...beforeRow,
+      linked: desiredLinked ? 1 : 0,
+      revision: changed ? beforeRow.revision + 1 : beforeRow.revision
+    };
+    const changedAt = now2();
+    db.run(`INSERT INTO contact_project_membership_states
+        (contact_id, project_id, linked, revision, updated_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(contact_id, project_id) DO UPDATE SET
+         linked = excluded.linked,
+         revision = excluded.revision,
+         updated_at = excluded.updated_at`, [input.contact_id, input.project_id, afterRow.linked, afterRow.revision, changedAt]);
+    if (desiredLinked) {
+      db.run(`INSERT OR IGNORE INTO contact_projects (contact_id, project_id) VALUES (?, ?)`, [input.contact_id, input.project_id]);
+    } else {
+      db.run(`DELETE FROM contact_projects WHERE contact_id = ? AND project_id = ?`, [input.contact_id, input.project_id]);
+    }
+    const after = snapshot(afterRow);
+    const id = receiptId(input);
+    db.run(`INSERT INTO contact_project_membership_receipts (
+         receipt_id, direction, contact_id, project_id, operation_id, step_id,
+         expected_version, before_json, after_json, created_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      direction,
+      input.contact_id,
+      input.project_id,
+      input.operation_id,
+      input.step_id,
+      input.expected_version,
+      JSON.stringify(before),
+      JSON.stringify(after),
+      changedAt
+    ]);
+    return {
+      outcome: changed ? "accepted" : "duplicate_of_accepted",
+      operation_id: input.operation_id,
+      step_id: input.step_id,
+      before,
+      after,
+      receipt_id: id
+    };
+  });
+}
+var init_project_memberships2 = __esm(() => {
+  init_database();
+  init_project_memberships();
+});
+
 // src/db/contacts.ts
 var exports_contacts = {};
 __export(exports_contacts, {
@@ -3588,34 +3879,32 @@ function autoLinkContactToCompany(contactId, db) {
 }
 function linkContactToProject(contactId, projectId, db) {
   const d = db || getDatabase();
-  d.run(`INSERT OR IGNORE INTO contact_projects (contact_id, project_id) VALUES (?, ?)`, [contactId, projectId]);
+  setContactProjectMembershipWithoutReceipt(contactId, projectId, true, d);
 }
 function unlinkContactFromProject(contactId, projectId, db) {
   const d = db || getDatabase();
-  d.run(`DELETE FROM contact_projects WHERE contact_id = ? AND project_id = ?`, [contactId, projectId]);
+  setContactProjectMembershipWithoutReceipt(contactId, projectId, false, d);
 }
 function getContactProjectIds(contactId, db) {
   const d = db || getDatabase();
-  const rows = d.query(`SELECT project_id FROM contact_projects WHERE contact_id = ?`).all(contactId);
+  const rows = d.query(`SELECT project_id FROM contact_projects WHERE contact_id = ? ORDER BY project_id ASC`).all(contactId);
   return rows.map((r) => r.project_id);
 }
 function listContactIdsByProject(projectId, db) {
   const d = db || getDatabase();
-  const rows = d.query(`SELECT contact_id FROM contact_projects WHERE project_id = ?`).all(projectId);
+  const rows = d.query(`SELECT contact_id FROM contact_projects WHERE project_id = ? ORDER BY contact_id ASC`).all(projectId);
   return rows.map((r) => r.contact_id);
 }
 function setContactProjects(contactId, projectIds, db) {
   const d = db || getDatabase();
-  d.run(`DELETE FROM contact_projects WHERE contact_id = ?`, [contactId]);
-  for (const pid of projectIds) {
-    d.run(`INSERT OR IGNORE INTO contact_projects (contact_id, project_id) VALUES (?, ?)`, [contactId, pid]);
-  }
+  replaceContactProjectMembershipsWithoutReceipts(contactId, projectIds, d);
 }
 var init_contacts = __esm(() => {
   init_types();
   init_database();
   init_activity();
   init_tombstones();
+  init_project_memberships2();
 });
 
 // src/db/companies.ts
@@ -5265,7 +5554,7 @@ var init_org_chart = __esm(() => {
 // src/lib/vault.ts
 import { existsSync as existsSync4, readFileSync, writeFileSync, mkdirSync as mkdirSync3, unlinkSync } from "fs";
 import { join as join3 } from "path";
-import { createCipheriv, createDecipheriv, randomBytes, pbkdf2Sync, createHash } from "crypto";
+import { createCipheriv, createDecipheriv, randomBytes, pbkdf2Sync, createHash as createHash2 } from "crypto";
 function deriveKey(passphrase, salt) {
   return pbkdf2Sync(passphrase, salt, 1e5, 32, "sha512");
 }
@@ -5305,7 +5594,7 @@ function initVault(passphrase) {
     mkdirSync3(DOCUMENTS_DIR, { recursive: true });
   const salt = randomBytes(32);
   const key = deriveKey(passphrase, salt);
-  const keyHash = createHash("sha256").update(key).digest("hex");
+  const keyHash = createHash2("sha256").update(key).digest("hex");
   const config = { salt: salt.toString("hex"), key_hash: keyHash, created_at: new Date().toISOString() };
   writeFileSync(VAULT_CONFIG, JSON.stringify(config, null, 2));
   _derivedKey = key;
@@ -5320,7 +5609,7 @@ function unlockVault(passphrase) {
   const config = JSON.parse(readFileSync(VAULT_CONFIG, "utf-8"));
   const salt = Buffer.from(config.salt, "hex");
   const key = deriveKey(passphrase, salt);
-  const keyHash = createHash("sha256").update(key).digest("hex");
+  const keyHash = createHash2("sha256").update(key).digest("hex");
   if (keyHash !== config.key_hash)
     return false;
   _derivedKey = key;
@@ -6915,6 +7204,15 @@ class LocalStore {
   async listContactIdsByProject(projectId) {
     return listContactIdsByProject(projectId, this.db);
   }
+  async readContactProjectMembership(contactId, projectId) {
+    return readContactProjectMembership(contactId, projectId, this.db);
+  }
+  async listContactProjectMemberships(projectId, maxItems) {
+    return listContactProjectMemberships(projectId, maxItems, this.db);
+  }
+  async mutateContactProjectMembership(direction, input) {
+    return mutateContactProjectMembership(direction, input, this.db);
+  }
   async createCompany(input) {
     return createCompany(input, this.db);
   }
@@ -7537,20 +7835,33 @@ class ApiStore {
   async findContactByEmailAddress(address) {
     return this.getContactByEmail(address);
   }
-  async linkContactToProject() {
-    return unavailable("linkContactToProject");
+  async linkContactToProject(contactId, projectId) {
+    await this.client.transport.put(`/contacts/${this.enc(contactId)}/projects/${this.enc(projectId)}`);
+  }
+  async unlinkContactFromProject(contactId, projectId) {
+    await this.del(`/contacts/${this.enc(contactId)}/projects/${this.enc(projectId)}`);
+  }
+  async getContactProjectIds(contactId) {
+    return pick(await this.g(`/contacts/${this.enc(contactId)}/projects`), "project_ids") ?? [];
+  }
+  async setContactProjects(contactId, projectIds) {
+    await this.client.transport.put(`/contacts/${this.enc(contactId)}/projects`, { project_ids: projectIds });
   }
-  async unlinkContactFromProject() {
-    return unavailable("unlinkContactFromProject");
+  async listContactIdsByProject(projectId) {
+    return pick(await this.g(`/projects/${this.enc(projectId)}/contacts`), "contact_ids") ?? [];
   }
-  async getContactProjectIds() {
-    return unavailable("getContactProjectIds");
+  async readContactProjectMembership(contactId, projectId) {
+    return this.client.transport.get(`/projects/${this.enc(projectId)}/contact-memberships/${this.enc(contactId)}`);
   }
-  async setContactProjects() {
-    return unavailable("setContactProjects");
+  async listContactProjectMemberships(projectId, maxItems) {
+    return this.client.transport.get(`/projects/${this.enc(projectId)}/contact-memberships`, { query: { max_items: maxItems } });
   }
-  async listContactIdsByProject() {
-    return unavailable("listContactIdsByProject");
+  async mutateContactProjectMembership(direction, input) {
+    return this.client.transport.post(`/projects/${this.enc(input.project_id)}/contact-memberships/${this.enc(input.contact_id)}/${direction}`, {
+      operation_id: input.operation_id,
+      step_id: input.step_id,
+      expected_version: input.expected_version
+    });
   }
   async createCompany(input) {
     const res = await this.client.create("companies", stripUndefined(input));
@@ -8072,6 +8383,7 @@ var init_store = __esm(() => {
   init_database();
   init_storage();
   init_contacts();
+  init_project_memberships2();
   init_companies();
   init_tags();
   init_groups();
@@ -8685,7 +8997,7 @@ var exports_util = {};
 __export(exports_util, {
   unwrapMessage: () => unwrapMessage,
   stringifyPrimitive: () => stringifyPrimitive,
-  required: () => required,
+  required: () => required2,
   randomString: () => randomString,
   propertyKeyTypes: () => propertyKeyTypes,
   promiseAllObject: () => promiseAllObject,
@@ -9026,7 +9338,7 @@ function partial(Class, schema, mask) {
     checks: []
   });
 }
-function required(Class, schema, mask) {
+function required2(Class, schema, mask) {
   const oldShape = schema._zod.def.shape;
   const shape = { ...oldShape };
   if (mask) {
@@ -19753,7 +20065,7 @@ function parseObjectDef(def, refs) {
     type: "object",
     properties: {}
   };
-  const required2 = [];
+  const required3 = [];
   const shape = def.shape();
   for (const propName in shape) {
     let propDef = shape[propName];
@@ -19780,11 +20092,11 @@ function parseObjectDef(def, refs) {
     }
     result.properties[propName] = parsedDef;
     if (!propOptional) {
-      required2.push(propName);
+      required3.push(propName);
     }
   }
-  if (required2.length) {
-    result.required = required2;
+  if (required3.length) {
+    result.required = required3;
   }
   const additionalProperties = decideAdditionalProperties(def, refs);
   if (additionalProperties !== undefined) {
@@ -27141,8 +27453,8 @@ var require_discriminator = __commonJS((exports) => {
         if (!tagRequired)
           throw new Error(`discriminator: "${tagName}" must be required`);
         return oneOfMapping;
-        function hasRequired({ required: required2 }) {
-          return Array.isArray(required2) && required2.includes(tagName);
+        function hasRequired({ required: required3 }) {
+          return Array.isArray(required3) && required3.includes(tagName);
         }
         function addMappings(sch, i) {
           if (sch.const) {
@@ -30588,8 +30900,8 @@ var init_advanced = __esm(() => {
   advancedHandlers = {
     get_field_history: async (a) => json3({ history: await getStore().getFieldHistory(a.contact_id, a.field_name) }),
     get_contact_at: async (a) => {
-      const snapshot = await getStore().getContactAt(a.contact_id, a.timestamp);
-      return json3({ contact_id: a.contact_id, timestamp: a.timestamp, snapshot });
+      const snapshot2 = await getStore().getContactAt(a.contact_id, a.timestamp);
+      return json3({ contact_id: a.contact_id, timestamp: a.timestamp, snapshot: snapshot2 });
     },
     get_job_history: async (a) => json3({ history: await getStore().getJobHistory(a.contact_id) }),
     add_job_entry: async (a) => json3(await getStore().addJobEntry(a.contact_id, {
@@ -31080,11 +31392,11 @@ function jsonSchemaToZodType(schema) {
 }
 function jsonSchemaToZodObject(schema) {
   const objectSchema = schema && typeof schema === "object" ? schema : {};
-  const required2 = new Set(objectSchema.required ?? []);
+  const required3 = new Set(objectSchema.required ?? []);
   const shape = {};
   for (const [key, value] of Object.entries(objectSchema.properties ?? {})) {
     const propertySchema = jsonSchemaToZodType(value);
-    shape[key] = required2.has(key) ? propertySchema : propertySchema.optional();
+    shape[key] = required3.has(key) ? propertySchema : propertySchema.optional();
   }
   return describeSchema(exports_external.object(shape).passthrough(), objectSchema.description);
 }
@@ -32782,11 +33094,11 @@ function isLoopbackBindHost(hostname2) {
   const normalized = hostname2.trim().toLowerCase();
   return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(normalized);
 }
-function hasScope(principal, required2) {
-  const prefix = required2.split(":")[0];
-  return principal.scopes.has("*") || principal.scopes.has(required2) || principal.scopes.has(`${prefix}:*`);
+function hasScope(principal, required3) {
+  const prefix = required3.split(":")[0];
+  return principal.scopes.has("*") || principal.scopes.has(required3) || principal.scopes.has(`${prefix}:*`);
 }
-function authenticateContactsRequest(req, required2, context = { allowUnauthenticatedLoopback: false }) {
+function authenticateContactsRequest(req, required3, context = { allowUnauthenticatedLoopback: false }) {
   const configured = parseTokenRecords();
   const token = bearerToken(req) ?? req.headers.get("x-contacts-token");
   if (token) {
@@ -32794,8 +33106,8 @@ function authenticateContactsRequest(req, required2, context = { allowUnauthenti
     if (!matched)
       return { ok: false, status: 401, message: "Invalid contacts token" };
     const principal = { id: "api-token", scopes: matched.scopes, localDevelopment: false };
-    if (!hasScope(principal, required2))
-      return { ok: false, status: 403, message: `Missing scope: ${required2}` };
+    if (!hasScope(principal, required3))
+      return { ok: false, status: 403, message: `Missing scope: ${required3}` };
     return { ok: true, principal };
   }
   if (configured.length === 0 && context.allowUnauthenticatedLoopback) {
@@ -33708,6 +34020,102 @@ var init_pg_migrations = __esm(() => {
   CREATE INDEX IF NOT EXISTS idx_contacts_tombstones_deleted_at ON _contacts_tombstones(deleted_at);
 
   INSERT INTO _migrations (version) VALUES (12) ON CONFLICT DO NOTHING;
+  `,
+    `
+  -- The contact_tags primary key is (contact_id, tag_id), which does not
+  -- support the public tag_id filter efficiently. Keep this forward-only and
+  -- idempotent for populated cloud deployments.
+  CREATE INDEX IF NOT EXISTS idx_contact_tags_tag_contact ON contact_tags(tag_id, contact_id);
+
+  INSERT INTO _migrations (version) VALUES (13) ON CONFLICT DO NOTHING;
+  `,
+    `
+  CREATE TABLE IF NOT EXISTS contact_project_membership_states (
+    contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+    project_id TEXT NOT NULL,
+    linked BOOLEAN NOT NULL,
+    revision BIGINT NOT NULL DEFAULT 0 CHECK(revision >= 0),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (contact_id, project_id)
+  );
+
+  INSERT INTO contact_project_membership_states
+    (contact_id, project_id, linked, revision, updated_at)
+  SELECT contact_id, project_id, TRUE, 0, NOW()
+  FROM contact_projects
+  ON CONFLICT DO NOTHING;
+
+  CREATE TABLE IF NOT EXISTS contact_project_membership_receipts (
+    receipt_id TEXT PRIMARY KEY,
+    direction TEXT NOT NULL CHECK(direction IN ('attach', 'detach')),
+    contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+    project_id TEXT NOT NULL,
+    operation_id TEXT NOT NULL,
+    step_id TEXT NOT NULL,
+    expected_version TEXT NOT NULL,
+    before_json JSONB NOT NULL,
+    after_json JSONB NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE(operation_id, step_id)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_contact_project_membership_states_project
+    ON contact_project_membership_states(project_id, linked, contact_id);
+  CREATE INDEX IF NOT EXISTS idx_contact_project_membership_receipts_target
+    ON contact_project_membership_receipts(contact_id, project_id, created_at);
+
+  CREATE OR REPLACE FUNCTION sync_contact_project_membership_state_from_legacy()
+  RETURNS TRIGGER
+  LANGUAGE plpgsql
+  AS $$
+  DECLARE
+    target_contact_id TEXT;
+    target_project_id TEXT;
+    target_linked BOOLEAN;
+  BEGIN
+    IF TG_OP = 'INSERT' THEN
+      target_contact_id := NEW.contact_id;
+      target_project_id := NEW.project_id;
+      target_linked := TRUE;
+    ELSE
+      target_contact_id := OLD.contact_id;
+      target_project_id := OLD.project_id;
+      target_linked := FALSE;
+      IF NOT EXISTS (SELECT 1 FROM contacts WHERE id = target_contact_id) THEN
+        RETURN OLD;
+      END IF;
+    END IF;
+
+    INSERT INTO contact_project_membership_states
+      (contact_id, project_id, linked, revision, updated_at)
+    VALUES (target_contact_id, target_project_id, target_linked, 1, NOW())
+    ON CONFLICT (contact_id, project_id) DO UPDATE SET
+      linked = EXCLUDED.linked,
+      revision = CASE
+        WHEN contact_project_membership_states.linked IS DISTINCT FROM EXCLUDED.linked
+          THEN contact_project_membership_states.revision + 1
+        ELSE contact_project_membership_states.revision
+      END,
+      updated_at = CASE
+        WHEN contact_project_membership_states.linked IS DISTINCT FROM EXCLUDED.linked
+          THEN NOW()
+        ELSE contact_project_membership_states.updated_at
+      END;
+
+    IF TG_OP = 'INSERT' THEN
+      RETURN NEW;
+    END IF;
+    RETURN OLD;
+  END;
+  $$;
+
+  DROP TRIGGER IF EXISTS sync_contact_project_membership_state_from_legacy
+    ON contact_projects;
+  CREATE TRIGGER sync_contact_project_membership_state_from_legacy
+  AFTER INSERT OR DELETE ON contact_projects
+  FOR EACH ROW EXECUTE FUNCTION sync_contact_project_membership_state_from_legacy();
+
+  INSERT INTO _migrations (version) VALUES (14) ON CONFLICT DO NOTHING;
   `
   ];
 });
@@ -33810,6 +34218,7 @@ var init_cloud = __esm(() => {
 });
 
 // src/server/pg-store.ts
+import { createHash as createHash3 } from "crypto";
 function uuid3() {
   return crypto.randomUUID();
 }
@@ -33844,6 +34253,45 @@ function newUuid() {
 function nowIso() {
   return new Date().toISOString();
 }
+function contactProjectDigest(value) {
+  return createHash3("sha256").update(value).digest("hex");
+}
+function contactProjectMembershipVersion(row) {
+  return `cpmv_${contactProjectDigest(JSON.stringify([
+    row.contact_id,
+    row.project_id,
+    Boolean(row.linked),
+    Number(row.revision)
+  ])).slice(0, 32)}`;
+}
+function contactProjectMembershipSnapshot(row) {
+  return {
+    contact_id: row.contact_id,
+    project_id: row.project_id,
+    linked: Boolean(row.linked),
+    version: contactProjectMembershipVersion(row)
+  };
+}
+function parseMembershipSnapshot(value) {
+  if (typeof value === "string")
+    return JSON.parse(value);
+  return value;
+}
+function requiredMembershipValue(value, name) {
+  const normalized = value.trim();
+  if (!normalized)
+    throw new Error(`${name} is required`);
+  return normalized;
+}
+function normalizeMembershipMutationInput(input) {
+  return {
+    contact_id: requiredMembershipValue(input.contact_id, "contact_id"),
+    project_id: requiredMembershipValue(input.project_id, "project_id"),
+    operation_id: requiredMembershipValue(input.operation_id, "operation_id"),
+    step_id: requiredMembershipValue(input.step_id, "step_id"),
+    expected_version: requiredMembershipValue(input.expected_version, "expected_version")
+  };
+}
 function parseJson(value) {
   if (!value)
     return {};
@@ -33911,12 +34359,87 @@ function mapTag(row) {
     created_at: iso(row.created_at)
   };
 }
+function mapEmail(row) {
+  return {
+    id: String(row["id"]),
+    contact_id: row["contact_id"] ?? null,
+    company_id: row["company_id"] ?? null,
+    address: String(row["address"]),
+    type: row["type"],
+    is_primary: Boolean(row["is_primary"]),
+    created_at: iso(row["created_at"])
+  };
+}
+function mapPhone(row) {
+  return {
+    id: String(row["id"]),
+    contact_id: row["contact_id"] ?? null,
+    company_id: row["company_id"] ?? null,
+    number: String(row["number"]),
+    country_code: row["country_code"] ?? null,
+    type: row["type"],
+    is_primary: Boolean(row["is_primary"]),
+    created_at: iso(row["created_at"])
+  };
+}
 
 class ContactsPgStore {
   client;
   constructor(client) {
     this.client = client;
   }
+  async attachTags(contacts) {
+    const tagsByContactId = new Map(contacts.map((contact) => [contact.id, []]));
+    if (contacts.length === 0)
+      return [];
+    const rows = await this.client.many(`SELECT ct.contact_id, t.*
+       FROM contact_tags ct
+       JOIN tags t ON t.id = ct.tag_id
+       WHERE ct.contact_id = ANY($1::text[])
+       ORDER BY t.name ASC`, [contacts.map((contact) => contact.id)]);
+    for (const row of rows)
+      tagsByContactId.get(row.contact_id)?.push(mapTag(row));
+    return contacts.map((contact) => ({ ...contact, tags: tagsByContactId.get(contact.id) ?? [] }));
+  }
+  async attachContactMethods(contacts) {
+    if (contacts.length === 0)
+      return [];
+    const ids = contacts.map((contact) => contact.id);
+    const emailsByContactId = new Map(ids.map((id) => [id, []]));
+    const phonesByContactId = new Map(ids.map((id) => [id, []]));
+    const [emailRows, phoneRows] = await Promise.all([
+      this.client.many(`SELECT * FROM emails WHERE contact_id = ANY($1::text[]) ORDER BY created_at ASC`, [ids]),
+      this.client.many(`SELECT * FROM phones WHERE contact_id = ANY($1::text[]) ORDER BY created_at ASC`, [ids])
+    ]);
+    for (const row of emailRows)
+      emailsByContactId.get(String(row["contact_id"]))?.push(mapEmail(row));
+    for (const row of phoneRows)
+      phonesByContactId.get(String(row["contact_id"]))?.push(mapPhone(row));
+    return contacts.map((contact) => ({
+      ...contact,
+      emails: emailsByContactId.get(contact.id) ?? [],
+      phones: phonesByContactId.get(contact.id) ?? []
+    }));
+  }
+  async attachContactDetails(contacts) {
+    return this.attachContactMethods(await this.attachTags(contacts));
+  }
+  async insertContactMethods(contactId, emails, phones) {
+    for (const email2 of emails ?? []) {
+      await this.client.query(`INSERT INTO emails (id, contact_id, company_id, address, type, is_primary)
+         SELECT $1, $2, NULL, $3, $4, $5
+         WHERE NOT EXISTS (
+           SELECT 1 FROM emails WHERE contact_id = $2 AND LOWER(address) = LOWER($3)
+         )`, [uuid3(), contactId, email2.address, email2.type ?? "work", email2.is_primary ?? false]);
+    }
+    for (const phone of phones ?? []) {
+      await this.client.query(`INSERT INTO phones (id, contact_id, company_id, number, country_code, type, is_primary)
+         SELECT $1, $2, NULL, $3, $4, $5, $6
+         WHERE NOT EXISTS (
+           SELECT 1 FROM phones WHERE contact_id = $2 AND number = $3
+         )`, [uuid3(), contactId, phone.number, phone.country_code ?? null, phone.type ?? "mobile", phone.is_primary ?? false]);
+    }
+  }
   async listContacts(filter = {}) {
     const limit = Math.min(Math.max(filter.limit ?? 50, 1), 500);
     const offset = Math.max(filter.offset ?? 0, 0);
@@ -33930,6 +34453,10 @@ class ContactsPgStore {
       params.push(filter.status);
       where.push(`status = $${params.length}`);
     }
+    if (filter.tag_id) {
+      params.push(filter.tag_id);
+      where.push(`EXISTS (SELECT 1 FROM contact_tags ct WHERE ct.contact_id = contacts.id AND ct.tag_id = $${params.length})`);
+    }
     if (filter.q) {
       params.push(filter.q);
       where.push(`search_vector @@ plainto_tsquery('simple', $${params.length})`);
@@ -33938,11 +34465,13 @@ class ContactsPgStore {
     const countRow = await this.client.get(`SELECT COUNT(*)::text AS count FROM contacts ${whereSql}`, params);
     params.push(limit, offset);
     const rows = await this.client.many(`SELECT * FROM contacts ${whereSql} ORDER BY display_name ASC LIMIT $${params.length - 1} OFFSET $${params.length}`, params);
-    return { contacts: rows.map(mapContact), count: Number(countRow?.count ?? rows.length) };
+    return { contacts: await this.attachContactDetails(rows.map(mapContact)), count: Number(countRow?.count ?? rows.length) };
   }
   async getContact(id) {
     const row = await this.client.get(`SELECT * FROM contacts WHERE id = $1`, [id]);
-    return row ? mapContact(row) : null;
+    if (!row)
+      return null;
+    return (await this.attachContactDetails([mapContact(row)]))[0];
   }
   async createContact(input) {
     const id = uuid3();
@@ -33978,7 +34507,8 @@ class ContactsPgStore {
       input.priority ?? 3,
       input.timezone ?? null
     ]);
-    return mapContact(row);
+    await this.insertContactMethods(id, input.emails, input.phones);
+    return (await this.attachContactDetails([mapContact(row)]))[0];
   }
   async updateContact(id, input) {
     const allowed = {};
@@ -34013,17 +34543,192 @@ class ContactsPgStore {
       allowed.custom_fields = JSON.stringify(input.custom_fields);
     }
     const keys = Object.keys(allowed);
-    if (keys.length === 0)
+    const hasMethodAppends = Boolean(input.emails_add?.length || input.phones_add?.length);
+    if (keys.length === 0 && !hasMethodAppends)
       return this.getContact(id);
     const sets = keys.map((k, i) => `${k} = $${i + 2}`);
     sets.push(`updated_at = NOW()`);
     const row = await this.client.get(`UPDATE contacts SET ${sets.join(", ")} WHERE id = $1 RETURNING *`, [id, ...keys.map((k) => allowed[k])]);
-    return row ? mapContact(row) : null;
+    if (!row)
+      return null;
+    await this.insertContactMethods(id, input.emails_add, input.phones_add);
+    return (await this.attachContactDetails([mapContact(row)]))[0];
   }
   async deleteContact(id) {
     const result = await this.client.query(`DELETE FROM contacts WHERE id = $1`, [id]);
     return result.rowCount > 0;
   }
+  async linkContactToProject(contactId, projectId) {
+    await this.client.transaction(async (client) => {
+      await this.transitionContactProjectMembershipWithoutReceipt(client, contactId, projectId, true);
+    });
+  }
+  async unlinkContactFromProject(contactId, projectId) {
+    return this.client.transaction((client) => this.transitionContactProjectMembershipWithoutReceipt(client, contactId, projectId, false));
+  }
+  async getContactProjectIds(contactId) {
+    const rows = await this.client.many(`SELECT project_id
+       FROM contact_projects
+       WHERE contact_id = $1
+       ORDER BY project_id ASC`, [contactId]);
+    return rows.map((row) => row.project_id);
+  }
+  async setContactProjects(contactId, projectIds) {
+    const uniqueProjectIds = [...new Set(projectIds.map((projectId) => requiredMembershipValue(projectId, "project_id")))];
+    await this.client.transaction(async (client) => {
+      const current = await client.many(`SELECT project_id FROM contact_projects WHERE contact_id = $1`, [contactId]);
+      const desired = new Set(uniqueProjectIds);
+      const population = new Set([...current.map((row) => row.project_id), ...uniqueProjectIds]);
+      for (const projectId of population) {
+        await this.transitionContactProjectMembershipWithoutReceipt(client, contactId, projectId, desired.has(projectId));
+      }
+    });
+    return uniqueProjectIds;
+  }
+  async listContactIdsByProject(projectId) {
+    const rows = await this.client.many(`SELECT contact_id
+       FROM contact_projects
+       WHERE project_id = $1
+       ORDER BY contact_id ASC`, [projectId]);
+    return rows.map((row) => row.contact_id);
+  }
+  async contactProjectMembershipState(client, contactId, projectId, forUpdate = false) {
+    let row = await client.get(`SELECT contact_id, project_id, linked, revision
+       FROM contact_project_membership_states
+       WHERE contact_id = $1 AND project_id = $2${forUpdate ? " FOR UPDATE" : ""}`, [contactId, projectId]);
+    if (row)
+      return row;
+    const linked = Boolean(await client.get(`SELECT 1 AS present FROM contact_projects WHERE contact_id = $1 AND project_id = $2`, [contactId, projectId]));
+    if (!forUpdate) {
+      return { contact_id: contactId, project_id: projectId, linked, revision: 0 };
+    }
+    await client.execute(`INSERT INTO contact_project_membership_states
+         (contact_id, project_id, linked, revision, updated_at)
+       VALUES ($1, $2, $3, 0, NOW())
+       ON CONFLICT (contact_id, project_id) DO NOTHING`, [contactId, projectId, linked]);
+    row = await client.get(`SELECT contact_id, project_id, linked, revision
+       FROM contact_project_membership_states
+       WHERE contact_id = $1 AND project_id = $2
+       FOR UPDATE`, [contactId, projectId]);
+    if (!row)
+      throw new Error("failed to initialize contact project membership state");
+    return row;
+  }
+  async transitionContactProjectMembershipWithoutReceipt(client, contactId, projectId, linked) {
+    const normalizedContactId = requiredMembershipValue(contactId, "contact_id");
+    const normalizedProjectId = requiredMembershipValue(projectId, "project_id");
+    const before = await this.contactProjectMembershipState(client, normalizedContactId, normalizedProjectId, true);
+    const changed = Boolean(before.linked) !== linked;
+    const revision = Number(before.revision) + (changed ? 1 : 0);
+    await client.execute(`UPDATE contact_project_membership_states
+       SET linked = $3, revision = $4, updated_at = NOW()
+       WHERE contact_id = $1 AND project_id = $2`, [normalizedContactId, normalizedProjectId, linked, revision]);
+    if (linked) {
+      await client.execute(`INSERT INTO contact_projects (contact_id, project_id) VALUES ($1, $2)
+         ON CONFLICT (contact_id, project_id) DO NOTHING`, [normalizedContactId, normalizedProjectId]);
+    } else {
+      await client.execute(`DELETE FROM contact_projects WHERE contact_id = $1 AND project_id = $2`, [normalizedContactId, normalizedProjectId]);
+    }
+    return changed;
+  }
+  async readContactProjectMembership(contactId, projectId) {
+    return contactProjectMembershipSnapshot(await this.contactProjectMembershipState(this.client, contactId, projectId));
+  }
+  async listContactProjectMemberships(projectId, maxItems) {
+    if (!Number.isInteger(maxItems) || maxItems < 1)
+      throw new Error("max_items must be a positive integer");
+    const rows = await this.client.many(`SELECT cp.contact_id, cp.project_id,
+              COALESCE(state.linked, TRUE) AS linked,
+              COALESCE(state.revision, 0) AS revision
+       FROM contact_projects cp
+       LEFT JOIN contact_project_membership_states state
+         ON state.contact_id = cp.contact_id AND state.project_id = cp.project_id
+       WHERE cp.project_id = $1
+       ORDER BY cp.contact_id ASC
+       LIMIT $2`, [projectId, maxItems + 1]);
+    if (rows.length > maxItems) {
+      throw new Error(`contact project membership collection exceeds max_items=${maxItems}`);
+    }
+    return {
+      project_id: projectId,
+      contact_ids: rows.map((row) => row.contact_id),
+      complete: true,
+      membership_revision: `cpml_${contactProjectDigest(JSON.stringify(rows.map(contactProjectMembershipSnapshot))).slice(0, 32)}`
+    };
+  }
+  async mutateContactProjectMembership(direction, rawInput) {
+    const input = normalizeMembershipMutationInput(rawInput);
+    return this.client.transaction(async (client) => {
+      await client.execute(`SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))`, [input.operation_id, input.step_id]);
+      const receipt = await client.get(`SELECT direction, contact_id, project_id, operation_id, step_id, expected_version,
+                before_json, after_json, receipt_id
+         FROM contact_project_membership_receipts
+         WHERE operation_id = $1 AND step_id = $2`, [input.operation_id, input.step_id]);
+      if (receipt) {
+        if (receipt.direction !== direction || receipt.contact_id !== input.contact_id || receipt.project_id !== input.project_id || receipt.expected_version !== input.expected_version) {
+          throw new ContactProjectMembershipConflictError("operation_id/step_id already accepted for a different contact-project membership mutation");
+        }
+        return {
+          outcome: "duplicate_of_accepted",
+          operation_id: receipt.operation_id,
+          step_id: receipt.step_id,
+          before: parseMembershipSnapshot(receipt.before_json),
+          after: parseMembershipSnapshot(receipt.after_json),
+          receipt_id: receipt.receipt_id
+        };
+      }
+      const contact = await client.get(`SELECT id FROM contacts WHERE id = $1`, [input.contact_id]);
+      if (!contact)
+        throw new Error(`contact not found: ${input.contact_id}`);
+      const beforeRow = await this.contactProjectMembershipState(client, input.contact_id, input.project_id, true);
+      const before = contactProjectMembershipSnapshot(beforeRow);
+      if (before.version !== input.expected_version) {
+        throw new ContactProjectMembershipConflictError(`contact project membership expected_version conflict: expected ${input.expected_version}, current ${before.version}`);
+      }
+      const desiredLinked = direction === "attach";
+      const changed = before.linked !== desiredLinked;
+      const revision = Number(beforeRow.revision) + (changed ? 1 : 0);
+      const afterRow = { ...beforeRow, linked: desiredLinked, revision };
+      await client.execute(`UPDATE contact_project_membership_states
+         SET linked = $3, revision = $4, updated_at = NOW()
+         WHERE contact_id = $1 AND project_id = $2`, [input.contact_id, input.project_id, desiredLinked, revision]);
+      if (desiredLinked) {
+        await client.execute(`INSERT INTO contact_projects (contact_id, project_id) VALUES ($1, $2)
+           ON CONFLICT (contact_id, project_id) DO NOTHING`, [input.contact_id, input.project_id]);
+      } else {
+        await client.execute(`DELETE FROM contact_projects WHERE contact_id = $1 AND project_id = $2`, [input.contact_id, input.project_id]);
+      }
+      const after = contactProjectMembershipSnapshot(afterRow);
+      const id = `cpmr_${contactProjectDigest(JSON.stringify([
+        input.operation_id,
+        input.step_id,
+        input.contact_id,
+        input.project_id
+      ])).slice(0, 32)}`;
+      await client.execute(`INSERT INTO contact_project_membership_receipts (
+           receipt_id, direction, contact_id, project_id, operation_id, step_id,
+           expected_version, before_json, after_json
+         ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::jsonb)`, [
+        id,
+        direction,
+        input.contact_id,
+        input.project_id,
+        input.operation_id,
+        input.step_id,
+        input.expected_version,
+        JSON.stringify(before),
+        JSON.stringify(after)
+      ]);
+      return {
+        outcome: changed ? "accepted" : "duplicate_of_accepted",
+        operation_id: input.operation_id,
+        step_id: input.step_id,
+        before,
+        after,
+        receipt_id: id
+      };
+    });
+  }
   async listCompanies(filter = {}) {
     const limit = Math.min(Math.max(filter.limit ?? 50, 1), 500);
     const offset = Math.max(filter.offset ?? 0, 0);
@@ -35461,6 +36166,9 @@ function getContactsPgStore(client) {
   return cachedStore2;
 }
 var cachedStore2 = null;
+var init_pg_store = __esm(() => {
+  init_project_memberships();
+});
 
 // src/server/v1.ts
 function json5(body, status = 200) {
@@ -35479,6 +36187,94 @@ async function readJson(req) {
     return null;
   }
 }
+function contactListFilterFromUrl(url) {
+  return {
+    ...url.searchParams.get("company_id") ? { company_id: url.searchParams.get("company_id") } : {},
+    ...url.searchParams.get("status") ? { status: url.searchParams.get("status") } : {},
+    ...url.searchParams.get("tag_id") ? { tag_id: url.searchParams.get("tag_id") } : {},
+    ...url.searchParams.get("q") ? { q: url.searchParams.get("q") } : {},
+    ...url.searchParams.get("limit") ? { limit: Number(url.searchParams.get("limit")) } : {},
+    ...url.searchParams.get("offset") ? { offset: Number(url.searchParams.get("offset")) } : {}
+  };
+}
+async function handleContactProjectsRoute(req, method, segments, store) {
+  const resource = segments[1];
+  const id = segments[2];
+  const sub = segments[3];
+  if (resource === "contacts" && id && sub === "projects") {
+    const contact = await store.getContact(id);
+    if (!contact)
+      return error2(404, "contact not found");
+    const projectId = segments[4];
+    if (projectId) {
+      if (method === "PUT") {
+        await store.linkContactToProject(id, projectId);
+        return json5({ attached: true, contact_id: id, project_id: projectId });
+      }
+      if (method === "DELETE") {
+        const removed = await store.unlinkContactFromProject(id, projectId);
+        return json5({ removed, contact_id: id, project_id: projectId });
+      }
+      return error2(405, `method ${method} not allowed on /v1/contacts/:contact_id/projects/:project_id`);
+    }
+    if (method === "GET") {
+      return json5({ contact_id: id, project_ids: await store.getContactProjectIds(id) });
+    }
+    if (method === "PUT") {
+      const body = await readJson(req);
+      if (!body || !Array.isArray(body.project_ids) || !body.project_ids.every((value) => typeof value === "string" && value.trim().length > 0)) {
+        return error2(400, "project_ids must be an array of non-empty strings");
+      }
+      const projectIds = await store.setContactProjects(id, body.project_ids);
+      return json5({ contact_id: id, project_ids: projectIds });
+    }
+    return error2(405, `method ${method} not allowed on /v1/contacts/:contact_id/projects`);
+  }
+  if (resource === "projects" && id && sub === "contacts") {
+    if (method === "GET") {
+      return json5({ project_id: id, contact_ids: await store.listContactIdsByProject(id) });
+    }
+    return error2(405, `method ${method} not allowed on /v1/projects/:project_id/contacts`);
+  }
+  if (resource === "projects" && id && sub === "contact-memberships") {
+    const contactId = segments[4];
+    const action = segments[5];
+    if (!contactId) {
+      if (method !== "GET") {
+        return error2(405, `method ${method} not allowed on /v1/projects/:project_id/contact-memberships`);
+      }
+      const rawMaxItems = new URL(req.url).searchParams.get("max_items");
+      const maxItems = rawMaxItems === null ? 1000 : Number(rawMaxItems);
+      if (!Number.isInteger(maxItems) || maxItems < 1)
+        return error2(400, "max_items must be a positive integer");
+      return json5(await store.listContactProjectMemberships(id, maxItems));
+    }
+    if (!action) {
+      if (method !== "GET") {
+        return error2(405, `method ${method} not allowed on /v1/projects/:project_id/contact-memberships/:contact_id`);
+      }
+      const contact = await store.getContact(contactId);
+      if (!contact)
+        return error2(404, "contact not found");
+      return json5(await store.readContactProjectMembership(contactId, id));
+    }
+    if ((action === "attach" || action === "detach") && method === "POST") {
+      const body = await readJson(req);
+      if (!body || typeof body.operation_id !== "string" || typeof body.step_id !== "string" || typeof body.expected_version !== "string" || body.operation_id.trim().length === 0 || body.step_id.trim().length === 0 || body.expected_version.trim().length === 0) {
+        return error2(400, "operation_id, step_id, and expected_version are required non-empty strings");
+      }
+      return json5(await store.mutateContactProjectMembership(action, {
+        contact_id: contactId,
+        project_id: id,
+        operation_id: body.operation_id,
+        step_id: body.step_id,
+        expected_version: body.expected_version
+      }));
+    }
+    return error2(405, `method ${method} not allowed on contact-project membership route`);
+  }
+  return null;
+}
 async function handleV1Request(req, url) {
   const path = url.pathname;
   if (path !== "/v1" && !path.startsWith("/v1/"))
@@ -35513,6 +36309,9 @@ async function handleV1Request(req, url) {
     return v === null ? undefined : Number(v);
   };
   try {
+    const projectLinks = await handleContactProjectsRoute(req, method, segments, store);
+    if (projectLinks)
+      return projectLinks;
     if (resource === "contacts" && id && sub) {
       if (sub === "tags") {
         const tagId = segments[4];
@@ -35592,13 +36391,7 @@ async function handleV1Request(req, url) {
     if (resource === "contacts") {
       if (!id) {
         if (method === "GET") {
-          const result = await store.listContacts({
-            ...url.searchParams.get("company_id") ? { company_id: url.searchParams.get("company_id") } : {},
-            ...url.searchParams.get("status") ? { status: url.searchParams.get("status") } : {},
-            ...url.searchParams.get("q") ? { q: url.searchParams.get("q") } : {},
-            ...url.searchParams.get("limit") ? { limit: Number(url.searchParams.get("limit")) } : {},
-            ...url.searchParams.get("offset") ? { offset: Number(url.searchParams.get("offset")) } : {}
-          });
+          const result = await store.listContacts(contactListFilterFromUrl(url));
           return json5(result);
         }
         if (method === "POST") {
@@ -36220,6 +37013,8 @@ async function handleV1Request(req, url) {
     return error2(404, `unknown /v1 resource: ${resource ?? "(root)"}`);
   } catch (e) {
     const msg = e.message || "internal error";
+    if (e instanceof ContactProjectMembershipConflictError)
+      return error2(409, msg);
     if (/violates|constraint|invalid input|duplicate key/i.test(msg))
       return error2(400, msg);
     return error2(500, msg);
@@ -36227,7 +37022,9 @@ async function handleV1Request(req, url) {
 }
 var JSON_HEADERS;
 var init_v1 = __esm(() => {
+  init_project_memberships();
   init_cloud();
+  init_pg_store();
   JSON_HEADERS = { "Content-Type": "application/json" };
 });
 
@@ -36352,6 +37149,58 @@ function buildV1OpenApiDocument(version2 = getPackageVersion()) {
             color: { type: "string" },
             description: { type: "string" }
           }
+        },
+        ProjectIdsInput: {
+          type: "object",
+          required: ["project_ids"],
+          properties: {
+            project_ids: {
+              type: "array",
+              items: { type: "string", minLength: 1 },
+              uniqueItems: true
+            }
+          }
+        },
+        ContactProjectMembershipSnapshot: {
+          type: "object",
+          required: ["contact_id", "project_id", "linked", "version"],
+          properties: {
+            contact_id: { type: "string" },
+            project_id: { type: "string" },
+            linked: { type: "boolean" },
+            version: { type: "string" }
+          }
+        },
+        ContactProjectMembershipMutationInput: {
+          type: "object",
+          required: ["operation_id", "step_id", "expected_version"],
+          properties: {
+            operation_id: { type: "string", minLength: 1 },
+            step_id: { type: "string", minLength: 1 },
+            expected_version: { type: "string", minLength: 1 }
+          }
+        },
+        ContactProjectMembershipMutationResult: {
+          type: "object",
+          required: ["outcome", "operation_id", "step_id", "before", "after", "receipt_id"],
+          properties: {
+            outcome: { type: "string", enum: ["accepted", "duplicate_of_accepted"] },
+            operation_id: { type: "string" },
+            step_id: { type: "string" },
+            before: { $ref: "#/components/schemas/ContactProjectMembershipSnapshot" },
+            after: { $ref: "#/components/schemas/ContactProjectMembershipSnapshot" },
+            receipt_id: { type: "string" }
+          }
+        },
+        ContactProjectMembershipListResult: {
+          type: "object",
+          required: ["project_id", "contact_ids", "complete", "membership_revision"],
+          properties: {
+            project_id: { type: "string" },
+            contact_ids: { type: "array", items: { type: "string" } },
+            complete: { type: "boolean", const: true },
+            membership_revision: { type: "string" }
+          }
         }
       }
     },
@@ -36365,6 +37214,7 @@ function buildV1OpenApiDocument(version2 = getPackageVersion()) {
             { name: "q", in: "query", schema: { type: "string" } },
             { name: "company_id", in: "query", schema: { type: "string" } },
             { name: "status", in: "query", schema: { type: "string" } },
+            { name: "tag_id", in: "query", schema: { type: "string" } },
             { name: "limit", in: "query", schema: { type: "number" } },
             { name: "offset", in: "query", schema: { type: "number" } }
           ],
@@ -36551,6 +37401,167 @@ function buildV1OpenApiDocument(version2 = getPackageVersion()) {
           })
         }
       },
+      "/v1/contacts/{contact_id}/projects": {
+        get: {
+          operationId: "getContactProjectIds",
+          summary: "List project ids attached to a contact",
+          parameters: [
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: objResponse({
+            contact_id: { type: "string" },
+            project_ids: { type: "array", items: { type: "string" } }
+          })
+        },
+        put: {
+          operationId: "setContactProjects",
+          summary: "Atomically replace a contact's project memberships",
+          parameters: [
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { $ref: "#/components/schemas/ProjectIdsInput" } } }
+          },
+          responses: objResponse({
+            contact_id: { type: "string" },
+            project_ids: { type: "array", items: { type: "string" } }
+          })
+        }
+      },
+      "/v1/contacts/{contact_id}/projects/{project_id}": {
+        put: {
+          operationId: "linkContactToProject",
+          summary: "Attach a contact to a project idempotently",
+          parameters: [
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: objResponse({
+            attached: { type: "boolean" },
+            contact_id: { type: "string" },
+            project_id: { type: "string" }
+          })
+        },
+        delete: {
+          operationId: "unlinkContactFromProject",
+          summary: "Detach a contact from a project",
+          parameters: [
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: objResponse({
+            removed: { type: "boolean" },
+            contact_id: { type: "string" },
+            project_id: { type: "string" }
+          })
+        }
+      },
+      "/v1/projects/{project_id}/contacts": {
+        get: {
+          operationId: "listContactIdsByProject",
+          summary: "List contact ids attached to a project",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: objResponse({
+            project_id: { type: "string" },
+            contact_ids: { type: "array", items: { type: "string" } }
+          })
+        }
+      },
+      "/v1/projects/{project_id}/contact-memberships": {
+        get: {
+          operationId: "listContactProjectMemberships",
+          summary: "List the complete authoritative contact membership collection for a project",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "max_items", in: "query", required: true, schema: { type: "integer", minimum: 1 } }
+          ],
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ContactProjectMembershipListResult" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/v1/projects/{project_id}/contact-memberships/{contact_id}": {
+        get: {
+          operationId: "readContactProjectMembership",
+          summary: "Read one authoritative contact-project membership snapshot",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ContactProjectMembershipSnapshot" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/v1/projects/{project_id}/contact-memberships/{contact_id}/attach": {
+        post: {
+          operationId: "attachContactProjectMembership",
+          summary: "Attach a contact to a project under expected-version CAS with a replay-safe receipt",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ContactProjectMembershipMutationInput" }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ContactProjectMembershipMutationResult" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/v1/projects/{project_id}/contact-memberships/{contact_id}/detach": {
+        post: {
+          operationId: "detachContactProjectMembership",
+          summary: "Detach a contact from a project under expected-version CAS with a replay-safe receipt",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ContactProjectMembershipMutationInput" }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ContactProjectMembershipMutationResult" }
+                }
+              }
+            }
+          }
+        }
+      },
       "/v1/stats": {
         get: {
           operationId: "getStats",
@@ -36570,6 +37581,7 @@ var init_openapi = __esm(() => {
   init_package_version();
   contactSchema = {
     type: "object",
+    required: ["tags"],
     properties: {
       id: { type: "string" },
       first_name: { type: "string" },
@@ -36584,6 +37596,7 @@ var init_openapi = __esm(() => {
       sensitivity: { type: "string" },
       archived: { type: "boolean" },
       priority: { type: "number" },
+      tags: { type: "array", items: { $ref: "#/components/schemas/Tag" } },
       created_at: { type: "string" },
       updated_at: { type: "string" }
     }
@@ -38615,6 +39628,41 @@ Group not found: ${groupId}
     await store.removeContactFromGroup(contactId, groupId);
     console.log(chalk2.green(`
 \u2713 Removed ${contact?.display_name ?? contactId} from group ${group.name}
+`));
+  });
+  const projectsCmd = program2.command("projects").description("Manage contact project links");
+  projectsCmd.command("attach <contact-id> <project-id>").description("Attach a contact to a project idempotently").action(async (contactId, projectId) => {
+    const store = getStore();
+    await store.linkContactToProject(contactId, projectId);
+    console.log(chalk2.green(`
+\u2713 Attached ${contactId} to project ${projectId}
+`));
+  });
+  projectsCmd.command("list <contact-id>").description("List project ids attached to a contact").option("-j, --json", "Output JSON").action(async (contactId, opts) => {
+    const store = getStore();
+    const projectIds = await store.getContactProjectIds(contactId);
+    if (opts.json) {
+      console.log(JSON.stringify({ contact_id: contactId, project_ids: projectIds }, null, 2));
+      return;
+    }
+    if (projectIds.length === 0) {
+      console.log(chalk2.gray(`
+No project links found for ${contactId}.
+`));
+      return;
+    }
+    console.log();
+    for (const projectId of projectIds)
+      console.log(`  ${projectId}`);
+    console.log(chalk2.gray(`
+${projectIds.length} project link(s) for ${contactId}
+`));
+  });
+  projectsCmd.command("detach <contact-id> <project-id>").description("Detach a contact from a project").action(async (contactId, projectId) => {
+    const store = getStore();
+    await store.unlinkContactFromProject(contactId, projectId);
+    console.log(chalk2.green(`
+\u2713 Detached ${contactId} from project ${projectId}
 `));
   });
   program2.command("init").description("Show setup info, stats, and configuration").action(async () => {