feat(studio): Phase 1a foundation - mode gate, op registry, object store

.env.example

@@ -40,6 +40,14 @@ DATABASE_URL=postgresql://nomos:nomos@localhost:5432/nomos
 # EMBEDDING_MODEL=gemini-embedding-001
 # VERTEX_AI_LOCATION=global
 
+# ─── Studio beauty-ops sidecar (optional, hosted Studio) ─────────
+# The deterministic retouch/reshape sidecar (nomos-studio-sidecar). When absent,
+# retouch falls back to the cloud (Gemini, consent-gated). Either point at an
+# already-running instance, OR let the daemon spawn `uv run` from a sibling clone.
+# NOMOS_STUDIO_SIDECAR_URL=http://127.0.0.1:8799
+# NOMOS_STUDIO_SIDECAR_PATH=../nomos-studio-sidecar
+# NOMOS_STUDIO_SIDECAR_PORT=8799
+
 # ─── Permission Mode (optional) ──────────────────────────────────
 # Controls how tool usage is handled: default, acceptEdits, plan, dontAsk
 # NOMOS_PERMISSION_MODE=acceptEdits

.gitignore

@@ -63,3 +63,8 @@ skills/webapp-testing/
 skills/xlsx/
 skills/.anthropic-skills-fetched
 .gstack/
+
+# Locally-installed agent skills (e.g. `npx skills add Banuba/ai-skills`) — a tool
+# for the assistant, not part of this repo.
+.claude/skills/
+skills-lock.json

CLAUDE.md

@@ -174,7 +174,7 @@ See `.env.example` for the full set of optional variables (model, permissions, c
 - **`sdk/`** -- Claude Agent SDK wrapper:
   - `session.ts` -- wraps `query()`, supports V2 session API with feature detection. `RunSessionParams` accepts `systemPrompt` (full override), `anthropicBaseUrl` (custom API endpoint), and `systemPromptAppend` (append to preset). The `ANTHROPIC_BASE_URL` env var is propagated to child processes via the `env` option.
   - `tools.ts` -- in-process MCP server exposing `memory_search` and `user_model_recall` tools
-  - `cost-tracker.ts` -- per-session and per-model token usage and USD cost tracking with `CostTracker` class, model pricing tiers, formatting utilities, and `getCostTracker()` singleton
+  - `cost-tracker.ts` -- per-session and per-model token usage and USD cost tracking with `CostTracker` class, model pricing tiers, and `getCostTracker()` singleton
   - `token-estimation.ts` -- heuristic-based token counting (`roughTokenCount`, `bytesPerTokenForFileType`, `roughTokenCountForBlock/Content/Messages`, `formatTokenCount`)
   - `retry.ts` -- `withRetry<T>()` async retry with exponential backoff + jitter, 429/529 handling, retry-after header parsing, persistent mode for daemon, abort signal support
   - `cache-break-detection.ts` -- `PromptCacheTracker` class that detects cache-invalidating changes to system prompt, tool schemas, model, or betas across API calls

eval/agent-eval.ts

@@ -1304,6 +1304,106 @@ async function runStyleProfiles(): Promise<void> {
   if (!KEEP) await db.deleteFrom("style_profiles").where("user_id", "in", [A, B]).execute();
 }
 
+async function runStudioLearn(): Promise<void> {
+  // Studio learning: drive the REAL capture -> distill -> store path. Four committed
+  // edits fill recordEditSignal's buffer and trip flushPhotoStyle, which distills them
+  // (forked Haiku) into an editable photo-style.md vault note + photo_style user_model
+  // entries -- the exact rows suggestEdits + auto-enhance read back to personalize.
+  // Asserts both durable effects, the apply-side read, and per-user isolation.
+  const { recordEditSignal, readPhotoStyle, flushPhotoStyle } =
+    await import("../src/studio/learn.ts");
+  const db = getKysely();
+  const A = "eval-photo-a";
+  const B = "eval-photo-b";
+  const clear = async (): Promise<void> => {
+    await db
+      .deleteFrom("vault_notes")
+      .where("user_id", "in", [A, B])
+      .where("path", "=", "photo-style.md")
+      .execute();
+    await db
+      .deleteFrom("user_model")
+      .where("user_id", "in", [A, B])
+      .where("category", "=", "photo_style")
+      .execute();
+  };
+  const styleNote = (): Promise<{ content: string } | undefined> =>
+    db
+      .selectFrom("vault_notes")
+      .select(["content"])
+      .where("user_id", "=", A)
+      .where("path", "=", "photo-style.md")
+      .executeTakeFirst();
+  const photoPrefCount = async (userId: string): Promise<number> =>
+    Number(
+      (
+        await db
+          .selectFrom("user_model")
+          .select((eb) => eb.fn.countAll<number>().as("n"))
+          .where("user_id", "=", userId)
+          .where("category", "=", "photo_style")
+          .executeTakeFirst()
+      )?.n ?? 0,
+    );
+  await clear();
+
+  // Capture + read gate on NOMOS_ADAPTIVE_MEMORY (same flag as all other learning).
+  const priorAdaptive = process.env.NOMOS_ADAPTIVE_MEMORY;
+  process.env.NOMOS_ADAPTIVE_MEMORY = "true";
+  try {
+    if (!hasLLM) {
+      skip(
+        "[studio-learn] distills applied edits into a photo-style vault note + user_model",
+        "no LLM provider configured",
+      );
+      return;
+    }
+
+    const edits = [
+      "warm up the photo and add a soft golden-hour glow",
+      "smooth the skin but keep the pores and natural texture",
+      "deepen the contrast and make the colors pop",
+      "brighten the eyes and gently whiten the teeth",
+    ];
+    const signals = edits.map((instruction) => ({ op: "editSemantic", instruction }));
+    // The real path: 4 edits fill the buffer and trip the flush (FLUSH_EVERY).
+    for (const s of signals) await recordEditSignal(A, s.op, s.instruction);
+
+    // recordEditSignal swallows flush errors by design (fire-and-forget); if nothing
+    // landed, drive the distiller directly so a genuine failure surfaces with a reason.
+    let note = await styleNote();
+    if (!note?.content) {
+      await flushPhotoStyle(A, signals);
+      note = await styleNote();
+    }
+
+    check(
+      "[studio-learn] writes an editable photo-style.md vault note",
+      !!note?.content && note.content.trim().length > 0,
+      note?.content?.slice(0, 80),
+    );
+    check(
+      "[studio-learn] accumulates photo_style preferences in the user model",
+      (await photoPrefCount(A)) >= 1,
+      `count=${await photoPrefCount(A)}`,
+    );
+    // Apply side: readPhotoStyle is what the engine (auto-enhance) + suggestEdits inject.
+    check(
+      "[studio-learn] readPhotoStyle surfaces the learned style for injection",
+      (await readPhotoStyle(A)).length > 0,
+    );
+    // Per-user scoped: B applied no edits, so it has neither the note nor any prefs.
+    check(
+      "[studio-learn] B (no edits) has no photo-style note or prefs (per-user scoped)",
+      (await readPhotoStyle(B)).length === 0 && (await photoPrefCount(B)) === 0,
+    );
+  } finally {
+    if (priorAdaptive === undefined) delete process.env.NOMOS_ADAPTIVE_MEMORY;
+    else process.env.NOMOS_ADAPTIVE_MEMORY = priorAdaptive;
+    if (!KEEP) await clear();
+  }
+}
+
 async function runWikiArticles(): Promise<void> {
   // Derived store: wiki_articles. Deterministic write + per-user isolation, then
   // the full LLM compile (2 Sonnet passes) pointed at a temp NOMOS_WIKI_DIR so it
@@ -2979,6 +3079,7 @@ async function runEval(): Promise<void> {
   await runRelationshipStats();
   await runManagedFiles();
   await runStyleProfiles();
+  await runStudioLearn();
   await runGraphMetadata();
   await runBacklinks();
   await runMetadataColumns();

eval/feature-manifest.ts

@@ -202,6 +202,127 @@ export const FEATURES: FeatureSpec[] = [
     entry: ["registerDeltaSyncJobs"],
     effects: [{ claim: "emits ingest:trigger for delta runs (behavioral)", notExercised: true }],
   },
+  {
+    id: "studio-gc",
+    summary:
+      "Daily Studio object/row cleanup per owner: expire unconfirmed uploads (assets stuck pending past a TTL) and aged intermediate edit results no longer at the chain head, dropping their objects. Originals + the live head output are kept; the DB is the single clock (rows expired before object delete).",
+    trigger: { kind: "cron", sentinel: "__studio_gc__", schedule: "24h", fanOut: true },
+    entry: ["runStudioGc", "runStudioGcForUser"],
+    effects: [
+      {
+        claim: "GC marks expired Studio rows (status = 'expired')",
+        sql: {
+          query: "SELECT count(*) FROM studio_edits WHERE status = 'expired'",
+          expect: "nonzero",
+        },
+        notExercised: true, // the eval does not age rows past the TTL
+      },
+    ],
+    invariants: [
+      "the original asset object is never deleted by GC",
+      "a row is marked expired before its object is deleted",
+      "every GC query is user_id-filtered",
+    ],
+  },
+
+  // ── Studio (hosted-only feature) ──
+  {
+    id: "studio",
+    summary:
+      "Hosted-only media asset + edit pipeline (gated). Immutable original + a non-destructive op chain: validate op -> consent gate (cloud ops only) -> append (optimistic concurrency: parent must be a done+output edit) + idempotency -> provider (local-sharp deterministic / mediapipe-sidecar deterministic / GCP generative) -> identity gate (face-risk ops) -> persist output + preview. Manual on-device renders (adjust/makeup/reshape/hair/body) commit via the deviceRender op (the client uploads its own pixels, re-encoded server-side). retouch routes to the deterministic sidecar when up, else the generative cloud fallback. Phase-3 depth ops (muscle/hairstyle/beard/relight/expand/sky) are generative. Per-user scoped.",
+    trigger: { kind: "turn", gate: "studio" },
+    entry: [
+      "buildStudioMcpServer",
+      "buildStudioEngine",
+      "assertIdentityPreserved",
+      "ensureStudioSidecar",
+      "listAssets",
+      "suggestEdits",
+    ],
+    effects: [
+      {
+        claim: "uploaded originals are recorded as studio_assets rows",
+        sql: { query: "SELECT count(*) FROM studio_assets", expect: "nonzero" },
+        notExercised: true,
+      },
+      {
+        claim: "each edit appends a completed studio_edits op row",
+        sql: {
+          query: "SELECT count(*) FROM studio_edits WHERE status = 'done'",
+          expect: "nonzero",
+        },
+        notExercised: true,
+      },
+      {
+        claim: "on-device renders commit as deviceRender edits (client-uploaded pixels)",
+        sql: {
+          query: "SELECT count(*) FROM studio_edits WHERE op = 'deviceRender' AND status = 'done'",
+          expect: "nonzero",
+        },
+        notExercised: true,
+      },
+      {
+        claim: "one-tap retouch records a done studio_edits row (sidecar or cloud fallback)",
+        sql: {
+          query: "SELECT count(*) FROM studio_edits WHERE op = 'retouch' AND status = 'done'",
+          expect: "nonzero",
+        },
+        notExercised: true,
+      },
+      {
+        claim: "Phase-3 generative depth ops record done studio_edits rows",
+        sql: {
+          query:
+            "SELECT count(*) FROM studio_edits WHERE op IN ('muscle','hairstyle','beard','relight','expand','sky') AND status = 'done'",
+          expect: "nonzero",
+        },
+        notExercised: true,
+      },
+      {
+        claim: "op params are stored as a jsonb object, never double-encoded",
+        noDoubleEncode: { table: "studio_edits", column: "params" },
+        notExercised: true,
+      },
+    ],
+    invariants: [
+      "the original asset row is never mutated by an edit",
+      "every studio_assets / studio_edits query is user_id-filtered (zero-trust)",
+      "every generative (cloud) op is gated by the cloudAI consent toggle",
+      "every face-touching generative op passes the identity gate (assertIdentityPreserved)",
+      "a retried edit with a committed idempotency_key returns the existing row, never re-charges",
+      "an edit only chains onto a parent that is done with an output (no half-built chain)",
+      "deviceRender requires client bytes and is free + never consent/identity-gated (WYSIWYG)",
+      "a client-supplied mask must resolve to a studio asset owned by the same user",
+    ],
+  },
+  {
+    id: "studio-learn",
+    summary:
+      "Studio learns the user's photo-editing taste from the edits they apply. Each committed editSemantic fires a signal (recordEditSignal); a background pass every few edits distills them (Haiku) into an editable photo-style.md vault note + photo_style user_model entries. It's injected back as personalized recommendations (suggestEdits style block) and a personalized auto-enhance (editSemantic personalize flag -> styleHint in the generative prompt), never overriding an explicit typed edit. Gated by NOMOS_ADAPTIVE_MEMORY; per-user scoped.",
+    trigger: { kind: "turn", gate: "studio" },
+    entry: ["recordEditSignal", "flushPhotoStyle", "readPhotoStyle"],
+    effects: [
+      {
+        // Exercised by runStudioLearn: 4 edits -> flushPhotoStyle distills the note.
+        claim: "learned editing taste is written as an editable photo-style.md vault note",
+        sql: {
+          query: "SELECT count(*) FROM vault_notes WHERE path = 'photo-style.md'",
+          expect: "nonzero",
+        },
+      },
+      {
+        claim: "structured photo_style preferences accumulate in the user model",
+        sql: {
+          query: "SELECT count(*) FROM user_model WHERE category = 'photo_style'",
+          expect: "nonzero",
+        },
+      },
+    ],
+    invariants: [
+      "learning is gated by NOMOS_ADAPTIVE_MEMORY and is per-user scoped",
+      "personalization biases auto-enhance + suggestions, never an explicit typed edit",
+    ],
+  },
 
   // ── Per-turn (memory-indexer) ──
   {

package.json

@@ -64,6 +64,7 @@
     "@bufbuild/protobuf": "^2.12.0",
     "@connectrpc/connect": "^2.1.1",
     "@connectrpc/connect-node": "^2.1.1",
+    "@google/genai": "^2.8.0",
     "@googleworkspace/cli": "^0.22.5",
     "@grpc/grpc-js": "^1.14.3",
     "@grpc/proto-loader": "^0.8.0",
@@ -99,6 +100,7 @@
     "playwright": "^1.50.0",
     "postgres": "^3.4.7",
     "react": "^19.2.4",
+    "sharp": "^0.35.1",
     "strip-ansi": "^7.2.0",
     "ws": "^8.19.0",
     "zod": "^4.3.6"