feat(q2): cloud sync protocol + Provenant API scaffold

Local↔cloud sync engine for Provenant hosted product:
- Wire protocol types (cloud-sync-types.ts)
- CloudSyncEngine with push/pull/status, delta collection, generational
  projection (young=full, mature=digest, old=anchors), offline resilience
- CloudSyncManager lifecycle wrapper with debounce + periodic sync
- Sync state schema (cloud_sync_state, cloud_sync_cursors tables)
- 3 MCP tools: cloud_sync_push, cloud_sync_pull, cloud_sync_status
- CLI: stackmemory sync push/pull/status
- Config extension: apiKey, autoSync, syncIntervalMinutes
- 22 unit tests covering engine, projection, conflicts, cursors

Cloud-side scaffold (packages/provenant-api/):
- CF Worker with /v1/sync/push, /v1/sync/pull, /v1/sync/status
- Neon Postgres schema migration (api_keys, sync_entities, sync_cursors)
- API key auth middleware

Author: StackMemory Bot (CLI)

packages/provenant-api/.dev.vars.example

@@ -0,0 +1,2 @@
+# Copy to .dev.vars and fill in values
+DATABASE_URL=postgresql://user:password@ep-xxx.us-east-2.aws.neon.tech/provenant?sslmode=require

packages/provenant-api/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@stackmemoryai/provenant-api",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Provenant hosted sync API — Cloudflare Workers + Neon Postgres",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "db:migrate": "node src/migrate.js",
+    "typegen": "wrangler types"
+  },
+  "dependencies": {
+    "@neondatabase/serverless": "^1.0.0"
+  },
+  "devDependencies": {
+    "wrangler": "^4.41.0"
+  }
+}

packages/provenant-api/src/auth.js

@@ -0,0 +1,50 @@
+/**
+ * Auth middleware — API key validation
+ * Reads Bearer token, hashes it, looks up in api_keys table.
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * @param {Request} request
+ * @param {{ DATABASE_URL: string }} env
+ * @param {import('@neondatabase/serverless').NeonQueryFunction} sql
+ * @returns {Promise<{ projectId: string; email: string } | Response>}
+ */
+export async function authenticate(request, env, sql) {
+  const authHeader = request.headers.get('Authorization');
+  if (!authHeader?.startsWith('Bearer ')) {
+    return new Response(
+      JSON.stringify({ error: 'Missing Authorization header' }),
+      {
+        status: 401,
+        headers: { 'Content-Type': 'application/json' },
+      }
+    );
+  }
+
+  const token = authHeader.slice(7);
+  const keyHash = createHash('sha256').update(token).digest('hex');
+
+  const rows = await sql`
+    SELECT id, user_email, project_id FROM api_keys
+    WHERE key_hash = ${keyHash}
+      AND revoked_at IS NULL
+  `;
+
+  if (rows.length === 0) {
+    return new Response(JSON.stringify({ error: 'Invalid API key' }), {
+      status: 401,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const key = rows[0];
+
+  // Update last_used_at (fire-and-forget)
+  sql`UPDATE api_keys SET last_used_at = NOW() WHERE id = ${key.id}`.catch(
+    () => {}
+  );
+
+  return { projectId: key.project_id, email: key.user_email };
+}

packages/provenant-api/src/index.js

@@ -0,0 +1,246 @@
+/**
+ * Provenant Sync API — Cloudflare Worker
+ *
+ * Endpoints:
+ *   POST /v1/sync/push   — Accept entities from local clients
+ *   POST /v1/sync/pull   — Return entities since cursor
+ *   GET  /v1/sync/status  — Server-side sync status
+ *   GET  /health          — Health check
+ */
+
+import { neon } from '@neondatabase/serverless';
+import { authenticate } from './auth.js';
+
+export default {
+  /**
+   * @param {Request} request
+   * @param {{ DATABASE_URL: string; SYNC_OVERFLOW: R2Bucket }} env
+   */
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    const path = url.pathname;
+
+    // Health check — no auth
+    if (path === '/health' && request.method === 'GET') {
+      return json({ status: 'ok', version: '0.1.0' });
+    }
+
+    // CORS preflight
+    if (request.method === 'OPTIONS') {
+      return new Response(null, {
+        status: 204,
+        headers: corsHeaders(),
+      });
+    }
+
+    // All sync endpoints require auth
+    const sql = neon(env.DATABASE_URL);
+    const authResult = await authenticate(request, env, sql);
+    if (authResult instanceof Response) return authResult;
+
+    const { projectId, email } = authResult;
+    const clientId = request.headers.get('X-Client-Id') || 'unknown';
+
+    try {
+      switch (`${request.method} ${path}`) {
+        case 'POST /v1/sync/push':
+          return await handlePush(request, sql, projectId, clientId);
+        case 'POST /v1/sync/pull':
+          return await handlePull(request, sql, projectId, clientId);
+        case 'GET /v1/sync/status':
+          return await handleStatus(sql, projectId, clientId);
+        default:
+          return json({ error: 'Not found' }, 404);
+      }
+    } catch (err) {
+      console.error('Sync API error:', err);
+      return json({ error: 'Internal server error' }, 500);
+    }
+  },
+};
+
+/**
+ * POST /v1/sync/push
+ * Accept entities from a local client, upsert into Neon.
+ */
+async function handlePush(request, sql, projectId, clientId) {
+  const body = await request.json();
+
+  if (body.protocolVersion !== 1) {
+    return json({ error: 'Unsupported protocol version' }, 400);
+  }
+
+  const entities = body.entities || [];
+  if (entities.length === 0) {
+    return json({
+      accepted: 0,
+      rejected: [],
+      serverCursor: new Date().toISOString(),
+    });
+  }
+
+  const rejected = [];
+  let accepted = 0;
+  const conflicts = [];
+
+  for (const entity of entities) {
+    try {
+      // Check for conflict (newest_wins)
+      const existing = await sql`
+        SELECT version FROM sync_entities
+        WHERE project_id = ${projectId}
+          AND table_name = ${entity.table}
+          AND id = ${entity.id}
+      `;
+
+      if (existing.length > 0 && existing[0].version > entity.version) {
+        conflicts.push({
+          id: entity.id,
+          table: entity.table,
+          serverVersion: Number(existing[0].version),
+          clientVersion: entity.version,
+        });
+        continue;
+      }
+
+      // Upsert
+      await sql`
+        INSERT INTO sync_entities (id, project_id, table_name, version, tier, data, client_id)
+        VALUES (${entity.id}, ${projectId}, ${entity.table}, ${entity.version}, ${entity.tier}, ${JSON.stringify(entity.data)}, ${clientId})
+        ON CONFLICT (project_id, table_name, id)
+        DO UPDATE SET
+          version = EXCLUDED.version,
+          tier = EXCLUDED.tier,
+          data = EXCLUDED.data,
+          client_id = EXCLUDED.client_id,
+          pushed_at = NOW()
+      `;
+      accepted++;
+    } catch (err) {
+      rejected.push({ id: entity.id, reason: String(err) });
+    }
+  }
+
+  const serverCursor = new Date().toISOString();
+
+  // Update client cursor
+  await sql`
+    INSERT INTO sync_cursors (project_id, client_id, direction, cursor_value)
+    VALUES (${projectId}, ${clientId}, 'push', ${serverCursor}::timestamptz)
+    ON CONFLICT (project_id, client_id, direction)
+    DO UPDATE SET cursor_value = EXCLUDED.cursor_value, updated_at = NOW()
+  `;
+
+  return json({
+    accepted,
+    rejected,
+    serverCursor,
+    ...(conflicts.length > 0 ? { conflicts } : {}),
+  });
+}
+
+/**
+ * POST /v1/sync/pull
+ * Return entities pushed by other clients since the given cursor.
+ */
+async function handlePull(request, sql, projectId, clientId) {
+  const body = await request.json();
+  const since = body.since || new Date(0).toISOString();
+  const limit = Math.min(body.limit || 100, 500);
+  const tables = body.tables; // optional filter
+
+  let rows;
+  if (tables && tables.length > 0) {
+    rows = await sql`
+      SELECT id, table_name, version, tier, data
+      FROM sync_entities
+      WHERE project_id = ${projectId}
+        AND pushed_at > ${since}::timestamptz
+        AND client_id != ${clientId}
+        AND table_name = ANY(${tables})
+      ORDER BY pushed_at ASC
+      LIMIT ${limit + 1}
+    `;
+  } else {
+    rows = await sql`
+      SELECT id, table_name, version, tier, data
+      FROM sync_entities
+      WHERE project_id = ${projectId}
+        AND pushed_at > ${since}::timestamptz
+        AND client_id != ${clientId}
+      ORDER BY pushed_at ASC
+      LIMIT ${limit + 1}
+    `;
+  }
+
+  const hasMore = rows.length > limit;
+  const entities = rows.slice(0, limit).map((r) => ({
+    table: r.table_name,
+    id: r.id,
+    version: Number(r.version),
+    tier: r.tier,
+    data: typeof r.data === 'string' ? JSON.parse(r.data) : r.data,
+  }));
+
+  // Server cursor = pushed_at of last returned entity, or `since` if empty
+  const serverCursor =
+    entities.length > 0
+      ? new Date().toISOString() // approximate — good enough for alpha
+      : since;
+
+  // Update pull cursor
+  await sql`
+    INSERT INTO sync_cursors (project_id, client_id, direction, cursor_value)
+    VALUES (${projectId}, ${clientId}, 'pull', ${serverCursor}::timestamptz)
+    ON CONFLICT (project_id, client_id, direction)
+    DO UPDATE SET cursor_value = EXCLUDED.cursor_value, updated_at = NOW()
+  `;
+
+  return json({ entities, serverCursor, hasMore });
+}
+
+/**
+ * GET /v1/sync/status
+ */
+async function handleStatus(sql, projectId, clientId) {
+  const cursors = await sql`
+    SELECT direction, cursor_value FROM sync_cursors
+    WHERE project_id = ${projectId} AND client_id = ${clientId}
+  `;
+
+  const pushCursor = cursors.find((c) => c.direction === 'push');
+  const pullCursor = cursors.find((c) => c.direction === 'pull');
+
+  const entityCount = await sql`
+    SELECT COUNT(*)::int as count FROM sync_entities
+    WHERE project_id = ${projectId}
+  `;
+
+  return json({
+    projectId,
+    clientId,
+    lastPushAt: pushCursor?.cursor_value || null,
+    lastPullAt: pullCursor?.cursor_value || null,
+    totalEntities: entityCount[0]?.count || 0,
+  });
+}
+
+// --- Helpers ---
+
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+      ...corsHeaders(),
+    },
+  });
+}
+
+function corsHeaders() {
+  return {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Client-Id',
+  };
+}