@cueframe/kernel 0.0.1

package/dist/_members/account-model/testing/conversationStoreContract.js

@@ -0,0 +1,168 @@
+/**
+ * THE CONVERSATION STORE CONTRACT — one executable statement, every store.
+ *
+ * A Director thread is persisted by TWO independent implementations: the
+ * desktop's sqlite (`cueframe/src-tauri/src/database/conversations.rs`) and the
+ * org's Convex documents (`services/convex/conversations.ts`), reached through
+ * an adapter each (`platform/tauri.ts`, `packages/web/adapter.ts`). A third
+ * "implementation" exists in the test double the app's own tests run against.
+ *
+ * THEY AGREED BY REVIEW DISCIPLINE, AND THAT FAILED. Three separate files
+ * carried prose saying both stores held the same rules. Two of those rules were
+ * true in one store only — the refusal to re-point a thread (Convex threw,
+ * sqlite silently accepted) and the immutability of a thread's creation time
+ * (Convex's `_creationTime`; sqlite's `INSERT OR REPLACE` rewrote it every
+ * turn). A third divergence was the live bug this whole effort started from:
+ * sqlite upserted on the app's id while Convex inserted a new document per
+ * turn, so one web conversation became N rows. Every one of those was invisible
+ * because each store was tested only against itself.
+ *
+ * This file is the fix: the facts as ASSERTIONS, parameterised over the store.
+ * A lane that wants to claim the contract runs it. There is no per-lane copy to
+ * drift, and a fact added here fails everywhere it is not yet true.
+ *
+ * WHY A PARAMETERISED SUITE AND NOT A DATA TABLE like `packages/plane`'s
+ * conformance rows: the plane's cases are STATELESS — the fixture travels in
+ * the request body, so a row is genuinely lane-agnostic data. Conversation
+ * storage is stateful CRUD over four verbs, where a fact reads "save this
+ * thrice, then list, then count". Encoding that as data needs an op-script
+ * schema plus an interpreter per lane; encoding it as a function needs neither.
+ *
+ * THESE ARE THE TWO MECHANISMS, and there are only two. `packages/plane/src/
+ * conformance.ts` holds stateless OPERATIONS both lanes serve; this shape holds
+ * stateful STORES behind one interface. CLAUDE.md carries the decision table —
+ * read it before inventing a third.
+ *
+ * WHY THE RUST LANE IS NOT DRIVEN FROM HERE: it lives behind `cargo test`, and
+ * reaching it from TypeScript means either a WebDriver stack (`tauri-driver`
+ * does not support macOS, the dev platform) or a codegen bridge — machinery
+ * several times the size of the 250 lines it would test. Instead the same facts
+ * are written as `#[tokio::test]`s in `database/mod.rs` UNDER THE SAME NAMES.
+ * Matching names are the seam: a fact that gains a test on one side and not the
+ * other is one grep away.
+ */
+const A = { id: "prj_a", home: "cloud" };
+const B = { id: "prj_b", home: "cloud" };
+function thread(id, project, over = {}) {
+    return {
+        id,
+        title: `thread ${id}`,
+        project,
+        createdAt: 1,
+        updatedAt: 1,
+        messages: "[]",
+        ...over,
+    };
+}
+export function describeConversationStoreContract(name, harness) {
+    const { describe, it, expect, makeStore } = harness;
+    const red = new Set(harness.knownRed ?? []);
+    const fact = (factName, fn) => (red.has(factName) ? it.fails : it)(factName, fn);
+    describe(`conversation store contract — ${name}`, () => {
+        fact("a_thread_is_one_row_however_many_turns", async () => {
+            const store = await makeStore();
+            for (let turn = 1; turn <= 3; turn++) {
+                await store.save(thread("conv_a", A, { updatedAt: 1000 + turn, messages: `[${turn}]` }));
+            }
+            // The id the app minted before any store saw the thread IS the identity.
+            // A store that keys writes on something else inserts per turn, and one
+            // conversation becomes N near-identical rows.
+            expect(await store.list(A)).toHaveLength(1);
+            const full = await store.get("conv_a", A);
+            expect(full?.messages).toBe("[3]");
+            expect(full?.updatedAt).toBe(1003);
+        });
+        fact("a_thread_is_addressed_by_the_project_pair", async () => {
+            const store = await makeStore();
+            await store.save(thread("conv_a", A));
+            await store.save(thread("conv_b", B));
+            expect((await store.list(A)).map((c) => c.id)).toEqual(["conv_a"]);
+            // UNREACHABLE, not merely unlisted: a thread fetchable by id under another
+            // project is a thread loadable into the wrong project's model context.
+            expect(await store.get("conv_a", B)).toBeNull();
+            expect((await store.get("conv_a", A))?.id).toBe("conv_a");
+        });
+        fact("one_id_in_two_homes_is_two_projects", async () => {
+            const store = await makeStore();
+            const asCloud = { id: "prj_shared", home: "cloud" };
+            const asLocal = { id: "prj_shared", home: "local" };
+            await store.save(thread("conv_cloud", asCloud));
+            // The pair is the key. Narrowing on the id alone would make the read's
+            // scope weaker than the address it claims to serve.
+            expect((await store.list(asCloud)).map((c) => c.id)).toEqual(["conv_cloud"]);
+            expect(await store.list(asLocal)).toEqual([]);
+            expect(await store.get("conv_cloud", asLocal)).toBeNull();
+        });
+        fact("the_workspace_is_a_scope_of_its_own", async () => {
+            const store = await makeStore();
+            await store.save(thread("conv_workspace", null));
+            await store.save(thread("conv_a", A));
+            // `null` is a MEANING — a thread started with no project open. It belongs
+            // to the workspace and survives every project switch precisely because it
+            // names no project.
+            expect((await store.list(null)).map((c) => c.id)).toEqual(["conv_workspace"]);
+            expect((await store.list(A)).map((c) => c.id)).toEqual(["conv_a"]);
+            expect(await store.get("conv_workspace", A)).toBeNull();
+            expect((await store.get("conv_workspace", null))?.id).toBe("conv_workspace");
+        });
+        fact("the_list_answers_without_the_turns", async () => {
+            const store = await makeStore();
+            await store.save(thread("conv_a", A, { messages: '["a very long transcript"]' }));
+            // A history rail draws titles. Shipping every thread's whole chat log to
+            // draw them is the read that runs on every project switch, and it grows
+            // without bound against a response-size limit.
+            const [entry] = await store.list(A);
+            // `as unknown as` — the meta type has no index signature, so a direct
+            // cast is the one TS refuses. Reading an ABSENT key is the point here.
+            expect(entry.messages).toEqual(undefined);
+            // …and the by-id read, which is what a restore needs, still carries them.
+            expect((await store.get("conv_a", A))?.messages).toBe('["a very long transcript"]');
+        });
+        fact("the_list_is_ordered_by_when_a_thread_was_last_used", async () => {
+            const store = await makeStore();
+            await store.save(thread("conv_old", A, { updatedAt: 1 }));
+            await store.save(thread("conv_new", A, { updatedAt: 2 }));
+            // The older thread gets a turn now. Creation order says it is last; what a
+            // history list is FOR says it is first.
+            await store.save(thread("conv_old", A, { updatedAt: 99 }));
+            expect((await store.list(A)).map((c) => c.id)).toEqual(["conv_old", "conv_new"]);
+        });
+        fact("a_threads_creation_time_is_the_stores_to_keep", async () => {
+            const store = await makeStore();
+            await store.save(thread("conv_a", A, { createdAt: 500, updatedAt: 500 }));
+            // A later save carrying a different createdAt must not move it: the caller
+            // re-derives that value from a list it may not have, so the store is the
+            // one thing in a position to know a thread's age.
+            await store.save(thread("conv_a", A, { createdAt: 9999, updatedAt: 2000 }));
+            const [entry] = await store.list(A);
+            expect(entry.createdAt).toBe(500);
+            expect(entry.updatedAt).toBe(2000);
+        });
+        fact("a_save_refuses_to_re_point_a_thread_at_another_project", async () => {
+            const store = await makeStore();
+            await store.save(thread("conv_a", A));
+            // A thread's project is decided at creation and never swaps. Quietly
+            // moving a history between projects is the contamination the addressing
+            // exists to prevent, spelled as a write instead of a read. (The one
+            // SANCTIONED re-point — moving a project to the cloud — has its own verb.)
+            await expect(store.save(thread("conv_a", B))).rejects.toThrow(/different project/);
+            expect(await store.get("conv_a", B)).toBeNull();
+            expect((await store.get("conv_a", A))?.id).toBe("conv_a");
+        });
+        fact("delete_takes_the_id_the_app_holds", async () => {
+            const store = await makeStore();
+            await store.save(thread("conv_a", A));
+            await store.remove("conv_a");
+            expect(await store.list(A)).toEqual([]);
+        });
+        fact("deleting_an_absent_thread_is_already_done", async () => {
+            const store = await makeStore();
+            // A delete of something that is not there is a delete that already
+            // happened; the caller has no other action to take, and its own `.catch`
+            // would swallow the error anyway — which is how "Delete removed nothing"
+            // went unnoticed for as long as it did.
+            await store.remove("conv_never");
+            expect(await store.list(A)).toEqual([]);
+        });
+    });
+}

package/dist/_members/account-model/testing/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Test-only exports. Deliberately NOT re-exported from the package root — this
+ * subpath injects a test runner's primitives and must never be reachable from
+ * production code by importing `@cueframe/account-model`.
+ */
+export { describeConversationStoreContract, type ConversationStoreUnderTest, type ContractHarness, type ContractConversation, type ContractConversationMeta, type ContractProjectRef, } from "./conversationStoreContract.js";
+export { describeRestorePointStoreContract, type RestorePointStoreUnderTest, type RestorePointHarness, type ContractRestorePointMeta, } from "./restorePointStoreContract.js";

package/dist/_members/account-model/testing/index.js

@@ -0,0 +1,7 @@
+/**
+ * Test-only exports. Deliberately NOT re-exported from the package root — this
+ * subpath injects a test runner's primitives and must never be reachable from
+ * production code by importing `@cueframe/account-model`.
+ */
+export { describeConversationStoreContract, } from "./conversationStoreContract.js";
+export { describeRestorePointStoreContract, } from "./restorePointStoreContract.js";

package/dist/_members/account-model/testing/restorePointStoreContract.d.ts

@@ -0,0 +1,52 @@
+/**
+ * THE RESTORE POINT STORE CONTRACT — one executable statement, every lane.
+ *
+ * Restore points are stored twice: the desktop keeps an index in sqlite with the
+ * snapshot in a JSONL beside it, the org's store keeps a pointer at a
+ * `compositionVersions` row it already has. Two implementations of one
+ * interface, which is the arrangement that produced every bug this codebase
+ * spent a day fixing in `conversations`.
+ *
+ * IT ALREADY WENT WRONG ONCE, EXACTLY AS PREDICTED. Both lanes had a
+ * `deleteRestorePointsForConversation`, both were written and tested in
+ * isolation, and NEITHER WAS CALLED — so deleting a conversation orphaned its
+ * points on disk and, on the cloud, left composition versions pinned where the
+ * thinning sweep could never reclaim them. Nothing noticed, because nothing
+ * asserted the behaviour across the seam.
+ *
+ * ONLY THE GENUINELY SHARED FACTS ARE HERE. Recording is desktop-only (the web
+ * records inside the server turn), so it is not in this contract — a fact that
+ * one lane satisfies by doing nothing is not a shared fact, it is a no-op
+ * wearing a method's name.
+ */
+export interface ContractRestorePointMeta {
+    id: string;
+    label: string;
+    createdAt: number;
+}
+/** The store surface under test — the shared half of the adapter's verbs. */
+export interface RestorePointStoreUnderTest {
+    list(conversationId: string): Promise<ContractRestorePointMeta[]>;
+    /** Put one in place, however this lane does it (test-only seam). */
+    seed(conversationId: string, point: {
+        id: string;
+        label: string;
+        createdAt: number;
+    }): Promise<void>;
+    deleteForConversation(conversationId: string): Promise<void>;
+}
+export interface RestorePointHarness {
+    describe: (name: string, fn: () => void) => void;
+    it: ((name: string, fn: () => Promise<void> | void) => void) & {
+        fails: (name: string, fn: () => Promise<void> | void) => void;
+    };
+    expect: (actual: unknown, message?: string) => {
+        toEqual: (expected: unknown) => void;
+        toBe: (expected: unknown) => void;
+        toHaveLength: (n: number) => void;
+    };
+    makeStore: () => Promise<RestorePointStoreUnderTest> | RestorePointStoreUnderTest;
+    /** Facts this lane does not hold yet, by name — becomes `it.fails`. */
+    knownRed?: readonly string[];
+}
+export declare function describeRestorePointStoreContract(name: string, harness: RestorePointHarness): void;

package/dist/_members/account-model/testing/restorePointStoreContract.js

@@ -0,0 +1,69 @@
+/**
+ * THE RESTORE POINT STORE CONTRACT — one executable statement, every lane.
+ *
+ * Restore points are stored twice: the desktop keeps an index in sqlite with the
+ * snapshot in a JSONL beside it, the org's store keeps a pointer at a
+ * `compositionVersions` row it already has. Two implementations of one
+ * interface, which is the arrangement that produced every bug this codebase
+ * spent a day fixing in `conversations`.
+ *
+ * IT ALREADY WENT WRONG ONCE, EXACTLY AS PREDICTED. Both lanes had a
+ * `deleteRestorePointsForConversation`, both were written and tested in
+ * isolation, and NEITHER WAS CALLED — so deleting a conversation orphaned its
+ * points on disk and, on the cloud, left composition versions pinned where the
+ * thinning sweep could never reclaim them. Nothing noticed, because nothing
+ * asserted the behaviour across the seam.
+ *
+ * ONLY THE GENUINELY SHARED FACTS ARE HERE. Recording is desktop-only (the web
+ * records inside the server turn), so it is not in this contract — a fact that
+ * one lane satisfies by doing nothing is not a shared fact, it is a no-op
+ * wearing a method's name.
+ */
+export function describeRestorePointStoreContract(name, harness) {
+    const { describe, it, expect, makeStore } = harness;
+    const red = new Set(harness.knownRed ?? []);
+    const fact = (factName, fn) => (red.has(factName) ? it.fails : it)(factName, fn);
+    describe(`restore point store contract — ${name}`, () => {
+        fact("lists a conversation's points, newest first", async () => {
+            const store = await makeStore();
+            await store.seed("conv_a", { id: "rp_old", label: "trim the intro", createdAt: 100 });
+            await store.seed("conv_a", { id: "rp_new", label: "add a title card", createdAt: 200 });
+            // Newest first, because the recent end is what a user reaches back to.
+            expect((await store.list("conv_a")).map((r) => r.id)).toEqual(["rp_new", "rp_old"]);
+        });
+        fact("answers only the asked conversation's points", async () => {
+            const store = await makeStore();
+            await store.seed("conv_a", { id: "rp_a", label: "a", createdAt: 1 });
+            await store.seed("conv_b", { id: "rp_b", label: "b", createdAt: 1 });
+            // A restore point names composition state, so one answered under the
+            // wrong conversation could put a different video's timeline on screen.
+            expect((await store.list("conv_a")).map((r) => r.id)).toEqual(["rp_a"]);
+            expect((await store.list("conv_b")).map((r) => r.id)).toEqual(["rp_b"]);
+        });
+        fact("carries the ask as the label — the list is legible", async () => {
+            const store = await makeStore();
+            await store.seed("conv_a", { id: "rp_1", label: "trim the intro", createdAt: 1 });
+            // "Restore to the state after 'trim the intro'" is something a person can
+            // pick out of a list. A row id never was.
+            expect((await store.list("conv_a"))[0].label).toBe("trim the intro");
+        });
+        fact("deleting a conversation takes its points with it", async () => {
+            const store = await makeStore();
+            await store.seed("conv_a", { id: "rp_1", label: "a", createdAt: 1 });
+            await store.seed("conv_b", { id: "rp_2", label: "b", createdAt: 1 });
+            await store.deleteForConversation("conv_a");
+            // THE FACT THAT WAS TRUE IN NEITHER LANE. Both had the method; neither
+            // had a caller. A point is a bookmark INTO a conversation and cannot
+            // outlive it — on the desktop it also holds a snapshot file, and on the
+            // cloud a PIN that stops the version ever being reclaimed.
+            expect(await store.list("conv_a")).toEqual([]);
+            expect(await store.list("conv_b"), "and only that conversation's").toHaveLength(1);
+        });
+        fact("deleting a conversation with no points is not an error", async () => {
+            const store = await makeStore();
+            // The common case for a conversation that only ever asked questions.
+            await store.deleteForConversation("conv_never");
+            expect(await store.list("conv_never")).toEqual([]);
+        });
+    });
+}

package/dist/_members/account-model/types/index.d.ts

@@ -0,0 +1,5 @@
+export type { UserSettings } from "../validators/userSettings.js";
+export type { Conversation, ConversationProject } from "../validators/conversation.js";
+export type { UploadToken, UploadTokenScope } from "../validators/uploadToken.js";
+export type { ContextFile } from "../validators/contextFile.js";
+export type { DashboardInsight } from "../validators/dashboardInsight.js";

package/dist/_members/account-model/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/_members/account-model/validators/contextFile.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+/**
+ * A user-curated context document the agent surfaces to the LLM (brand
+ * voice notes, audience specs, recurring constraints). `generatedFrom`
+ * lists the source IDs (mediaItems, conversations, etc.) that produced
+ * the current `content`; bumping `version` indicates a regeneration.
+ */
+export declare const ContextFile: z.ZodObject<{
+    id: z.ZodBranded<z.ZodString, "Id<contextFiles>">;
+    orgId: z.ZodString;
+    userId: z.ZodString;
+    filename: z.ZodString;
+    content: z.ZodString;
+    generatedFrom: z.ZodArray<z.ZodString, "many">;
+    version: z.ZodNumber;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string & z.BRAND<"Id<contextFiles>">;
+    userId: string;
+    updatedAt: string;
+    orgId: string;
+    filename: string;
+    content: string;
+    generatedFrom: string[];
+    version: number;
+}, {
+    id: string;
+    userId: string;
+    updatedAt: string;
+    orgId: string;
+    filename: string;
+    content: string;
+    generatedFrom: string[];
+    version: number;
+}>;
+export type ContextFile = z.infer<typeof ContextFile>;

package/dist/_members/account-model/validators/contextFile.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { EntityId, ISODateTime, NonEmptyString } from "@cueframe/foundation/primitives";
+/**
+ * A user-curated context document the agent surfaces to the LLM (brand
+ * voice notes, audience specs, recurring constraints). `generatedFrom`
+ * lists the source IDs (mediaItems, conversations, etc.) that produced
+ * the current `content`; bumping `version` indicates a regeneration.
+ */
+export const ContextFile = z.object({
+    id: EntityId("contextFiles"),
+    orgId: NonEmptyString,
+    userId: NonEmptyString,
+    filename: NonEmptyString,
+    content: z.string(),
+    generatedFrom: z.array(NonEmptyString),
+    version: z.number().int().nonnegative(),
+    updatedAt: ISODateTime,
+});

package/dist/_members/account-model/validators/conversation.d.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+/**
+ * A user's chat thread with the AI surface (Director, clips agent, etc.).
+ * `messages` is a JSON-encoded UI message log; the storage column is a
+ * single string blob to avoid Convex's per-row JSON shape constraints
+ * across long histories.
+ *
+ * THE `scope` FIELD IS GONE (2026-08-17). It recorded the PAGE the thread was
+ * last saved from, and it was a constant: the app writes
+ * `resolvePageScope(pathname).location`, and that resolver returns the editor
+ * scope on EVERY path — so every row ever written said `"editor"`, including
+ * workspace threads, and the enum declared here never contained that value.
+ * Nothing read it back (the one scope badge in the UI reads the LIVE
+ * `PageScope`, not the stored field). A constant nobody reads is not a column
+ * to correct, so it was deleted rather than fixed.
+ */
+/**
+ * The project a thread is ABOUT, and the home that owns it.
+ *
+ * `home` is carried rather than inferred: a local project's id is an absolute
+ * `.cueframe` path and a cloud project's is an org project id, and reading
+ * which from the shape of the string is the sniff the app's residency model
+ * exists to delete. Every conversation stored in the org is a cloud project's
+ * (or the workspace's), but the reference states that rather than leaving the
+ * reader to know it.
+ */
+export declare const ConversationProject: z.ZodObject<{
+    id: z.ZodString;
+    home: z.ZodEnum<["local", "cloud"]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    home: "local" | "cloud";
+}, {
+    id: string;
+    home: "local" | "cloud";
+}>;
+export type ConversationProject = z.infer<typeof ConversationProject>;
+export declare const Conversation: z.ZodObject<{
+    id: z.ZodBranded<z.ZodString, "Id<conversations>">;
+    /**
+     * THE THREAD'S IDENTITY, and the app is the one that mints it.
+     *
+     * A conversation exists in the client before any store has seen it: the
+     * Director opens a chat, the user types, and only when the turn ends does a
+     * row get written. So the id that names a thread has to be one the client
+     * chose (`conv_<nanoid>`), not one a store assigns — otherwise the first
+     * save is an INSERT under a name the client cannot predict, the client keeps
+     * using its own name, and every subsequent save inserts again. That is
+     * exactly what web did until 2026-08-17: an N-turn conversation became N
+     * rows, and Delete silently deleted nothing because the id the user's
+     * sidebar held had never named a document.
+     *
+     * The desktop always had this right — sqlite is an `INSERT OR REPLACE` keyed
+     * on the client id. This field makes the org's store agree, via a unique
+     * lookup on `by_userId_clientId`: writes are an upsert on the id the app
+     * chose, and Convex's `_id` goes back to being an internal detail nobody
+     * outside this table ever sees or stores.
+     */
+    clientId: z.ZodString;
+    userId: z.ZodString;
+    title: z.ZodString;
+    /**
+     * The project whose media, timeline and history this thread's turns are
+     * about. ABSENT is a meaning — a workspace thread, started on a surface with
+     * no project open — not a missing value: such a thread belongs to the user's
+     * workspace and survives every project switch precisely because it names no
+     * project. It is `optional` rather than nullable because rows written before
+     * the field existed have no project recorded, and nothing may invent one for
+     * them.
+     */
+    project: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        home: z.ZodEnum<["local", "cloud"]>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        home: "local" | "cloud";
+    }, {
+        id: string;
+        home: "local" | "cloud";
+    }>>;
+    /**
+     * When the thread was STARTED — supplied by the app, kept by the store.
+     *
+     * Stored rather than read off Convex's `_creationTime`, which is when the
+     * DOCUMENT was inserted and not when the conversation began. Those are the
+     * same moment for a thread born in the cloud and very different for one that
+     * arrives there later: moving a project to the cloud re-homes its threads
+     * (`adoptIntoProject`), and a months-old conversation would have shown up
+     * dated today. The desktop has always stored the app's value; this is the
+     * org's store agreeing, and it is what lets the same thread report the same
+     * age on both sides of a move.
+     *
+     * Immutable after the first write on both stores — a thread's age is a fact
+     * about the thread, not about its most recent turn.
+     */
+    createdAt: z.ZodString;
+    /**
+     * When the thread last had a turn — the key the history list sorts on.
+     *
+     * Stored rather than derived because the two things a store can offer for
+     * free are both wrong: Convex's `_creationTime` is when the thread STARTED
+     * (so a months-old thread the user just added a turn to sorts to the bottom,
+     * which is the opposite of what a history list is for), and a patch does not
+     * move it. The desktop has ordered by `updated_at DESC` since migration 015;
+     * this is the org's store agreeing.
+     */
+    updatedAt: z.ZodString;
+    /** JSON-encoded array of UI messages (role + content). */
+    messages: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string & z.BRAND<"Id<conversations>">;
+    userId: string;
+    clientId: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    messages: string;
+    project?: {
+        id: string;
+        home: "local" | "cloud";
+    } | undefined;
+}, {
+    id: string;
+    userId: string;
+    clientId: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    messages: string;
+    project?: {
+        id: string;
+        home: "local" | "cloud";
+    } | undefined;
+}>;
+export type Conversation = z.infer<typeof Conversation>;
+/**
+ * A thread as a history LIST needs it — everything but the turns.
+ *
+ * The list renders a title and nothing else, so shipping `messages` with it
+ * sends the entire chat log of every thread to draw ≤5 lines of text. That was
+ * merely wasteful while a thread was one row; it stops being merely wasteful
+ * on a store with a per-response size limit, and it is the same read that runs
+ * on every project switch.
+ *
+ * A TYPE, NOT A SCHEMA, and deliberately: `ConversationMeta` would naturally be
+ * `Conversation.omit({messages: true})`, but `ZodObject.omit()` is the
+ * "instantiation explosion" Zod 3's own v4 notes describe — it re-instantiates
+ * deep conditional generics and blew past TypeScript's depth limit (TS2589)
+ * where `@cueframe/convex-schemas` used it, silently degrading the derived
+ * table types to `{[x: string]: …}`. Nothing parses a meta at a boundary, so
+ * the shape is only ever needed as a type.
+ */
+export type ConversationMeta = Omit<Conversation, "messages">;

package/dist/_members/account-model/validators/conversation.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { EntityId, ISODateTime, NonEmptyString } from "@cueframe/foundation/primitives";
+/**
+ * A user's chat thread with the AI surface (Director, clips agent, etc.).
+ * `messages` is a JSON-encoded UI message log; the storage column is a
+ * single string blob to avoid Convex's per-row JSON shape constraints
+ * across long histories.
+ *
+ * THE `scope` FIELD IS GONE (2026-08-17). It recorded the PAGE the thread was
+ * last saved from, and it was a constant: the app writes
+ * `resolvePageScope(pathname).location`, and that resolver returns the editor
+ * scope on EVERY path — so every row ever written said `"editor"`, including
+ * workspace threads, and the enum declared here never contained that value.
+ * Nothing read it back (the one scope badge in the UI reads the LIVE
+ * `PageScope`, not the stored field). A constant nobody reads is not a column
+ * to correct, so it was deleted rather than fixed.
+ */
+/**
+ * The project a thread is ABOUT, and the home that owns it.
+ *
+ * `home` is carried rather than inferred: a local project's id is an absolute
+ * `.cueframe` path and a cloud project's is an org project id, and reading
+ * which from the shape of the string is the sniff the app's residency model
+ * exists to delete. Every conversation stored in the org is a cloud project's
+ * (or the workspace's), but the reference states that rather than leaving the
+ * reader to know it.
+ */
+export const ConversationProject = z.object({
+    id: NonEmptyString,
+    home: z.enum(["local", "cloud"]),
+});
+export const Conversation = z.object({
+    id: EntityId("conversations"),
+    /**
+     * THE THREAD'S IDENTITY, and the app is the one that mints it.
+     *
+     * A conversation exists in the client before any store has seen it: the
+     * Director opens a chat, the user types, and only when the turn ends does a
+     * row get written. So the id that names a thread has to be one the client
+     * chose (`conv_<nanoid>`), not one a store assigns — otherwise the first
+     * save is an INSERT under a name the client cannot predict, the client keeps
+     * using its own name, and every subsequent save inserts again. That is
+     * exactly what web did until 2026-08-17: an N-turn conversation became N
+     * rows, and Delete silently deleted nothing because the id the user's
+     * sidebar held had never named a document.
+     *
+     * The desktop always had this right — sqlite is an `INSERT OR REPLACE` keyed
+     * on the client id. This field makes the org's store agree, via a unique
+     * lookup on `by_userId_clientId`: writes are an upsert on the id the app
+     * chose, and Convex's `_id` goes back to being an internal detail nobody
+     * outside this table ever sees or stores.
+     */
+    clientId: NonEmptyString,
+    userId: NonEmptyString,
+    title: NonEmptyString,
+    /**
+     * The project whose media, timeline and history this thread's turns are
+     * about. ABSENT is a meaning — a workspace thread, started on a surface with
+     * no project open — not a missing value: such a thread belongs to the user's
+     * workspace and survives every project switch precisely because it names no
+     * project. It is `optional` rather than nullable because rows written before
+     * the field existed have no project recorded, and nothing may invent one for
+     * them.
+     */
+    project: ConversationProject.optional(),
+    /**
+     * When the thread was STARTED — supplied by the app, kept by the store.
+     *
+     * Stored rather than read off Convex's `_creationTime`, which is when the
+     * DOCUMENT was inserted and not when the conversation began. Those are the
+     * same moment for a thread born in the cloud and very different for one that
+     * arrives there later: moving a project to the cloud re-homes its threads
+     * (`adoptIntoProject`), and a months-old conversation would have shown up
+     * dated today. The desktop has always stored the app's value; this is the
+     * org's store agreeing, and it is what lets the same thread report the same
+     * age on both sides of a move.
+     *
+     * Immutable after the first write on both stores — a thread's age is a fact
+     * about the thread, not about its most recent turn.
+     */
+    createdAt: ISODateTime,
+    /**
+     * When the thread last had a turn — the key the history list sorts on.
+     *
+     * Stored rather than derived because the two things a store can offer for
+     * free are both wrong: Convex's `_creationTime` is when the thread STARTED
+     * (so a months-old thread the user just added a turn to sorts to the bottom,
+     * which is the opposite of what a history list is for), and a patch does not
+     * move it. The desktop has ordered by `updated_at DESC` since migration 015;
+     * this is the org's store agreeing.
+     */
+    updatedAt: ISODateTime,
+    /** JSON-encoded array of UI messages (role + content). */
+    messages: z.string(),
+});

package/dist/_members/account-model/validators/dashboardInsight.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/**
+ * Cached LLM-generated dashboard summary keyed off a `sourceHash` of the
+ * inputs that produced it. Surfaces a one-line hero insight plus a small
+ * batch of follow-up content suggestions on the home view.
+ */
+export declare const DashboardInsight: z.ZodObject<{
+    id: z.ZodBranded<z.ZodString, "Id<dashboardInsights>">;
+    orgId: z.ZodString;
+    /** Hash of the input set that produced this snapshot (cache key). */
+    sourceHash: z.ZodString;
+    heroInsight: z.ZodString;
+    contentSuggestions: z.ZodArray<z.ZodString, "many">;
+    generatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string & z.BRAND<"Id<dashboardInsights>">;
+    orgId: string;
+    sourceHash: string;
+    heroInsight: string;
+    contentSuggestions: string[];
+    generatedAt: string;
+}, {
+    id: string;
+    orgId: string;
+    sourceHash: string;
+    heroInsight: string;
+    contentSuggestions: string[];
+    generatedAt: string;
+}>;
+export type DashboardInsight = z.infer<typeof DashboardInsight>;