@cueframe/kernel 0.0.1 → 0.1.1

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

@@ -1,168 +0,0 @@
-/**
- * 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.js

@@ -1,7 +0,0 @@
-/**
- * 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.js

@@ -1,69 +0,0 @@
-/**
- * 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.js

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

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

@@ -1,18 +0,0 @@
-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.js

@@ -1,95 +0,0 @@
-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.js

@@ -1,16 +0,0 @@
-import { z } from "zod";
-import { EntityId, ISODateTime, NonEmptyString } from "@cueframe/foundation/primitives";
-/**
- * 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 const DashboardInsight = z.object({
-    id: EntityId("dashboardInsights"),
-    orgId: NonEmptyString,
-    /** Hash of the input set that produced this snapshot (cache key). */
-    sourceHash: NonEmptyString,
-    heroInsight: NonEmptyString,
-    contentSuggestions: z.array(NonEmptyString),
-    generatedAt: ISODateTime,
-});

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

@@ -1,7 +0,0 @@
-export * from "./userSettings.js";
-export * from "./conversation.js";
-export * from "./uploadToken.js";
-export * from "./contextFile.js";
-export * from "./dashboardInsight.js";
-export * from "./sessionToken.js";
-export * from "./workingComposition.js";

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

@@ -1,49 +0,0 @@
-import { z } from "zod";
-import { EntityId, ISODateTime, NonEmptyString } from "@cueframe/foundation/primitives";
-/**
- * Short-lived, session-scoped, read-only bearer token used by a warm render
- * session container (Modal Sandbox) to subscribe to its working composition in Convex
- * without bundling org credentials into the container. Validated as a query
- * argument (the UploadToken precedent), not via Convex-native auth/JWT.
- */
-export const SessionTokenScope = z.enum(["session-read"]);
-export const SessionToken = z.object({
-    id: EntityId("sessionTokens"),
-    token: NonEmptyString,
-    sessionId: NonEmptyString,
-    projectId: EntityId("projects"),
-    orgId: NonEmptyString,
-    scope: SessionTokenScope,
-    expiresAt: ISODateTime,
-    // ── Session-state (the token row IS the session row; cleanup-dominant) ──
-    /** The warm sandbox this session is bound to, set once it's created. The
-     *  session reconnects by this id (provider.get) per render — the platform-native
-     *  persistent-resource pattern. */
-    sandboxId: NonEmptyString.optional(),
-    /** Epoch-ms when the warm box became ready (stamped alongside `sandboxId`). The
-     *  billable-uptime clock start — `closeSession` bills `compose_session_minutes`
-     *  from here. Absent = the box never booted, so nothing to bill. Stored as a raw
-     *  number (epoch-ms) like `expiresAt`, for cheap arithmetic. */
-    readyAt: z.number().optional(),
-    /** The `_scheduled_functions` id of the pending durable auto-close
-     *  (`ctx.scheduler.runAfter`). Cancelled + rescheduled on activity (keep-alive),
-     *  fired on idle to reap the sandbox — crash-proof cleanup, not durability. */
-    scheduledCloseId: NonEmptyString.optional(),
-    /** The session-scoped SCRATCH composition (a derived sibling of the project's
-     *  active composition). Author-ops during the session mutate THIS row, never
-     *  active; `promoteScratch` commits it and `closeSession` discards it. Absent
-     *  until the session derives one (or the project had no active to derive from). */
-    scratchCompositionId: EntityId("compositions").optional(),
-    /** SERVER-owned evidence box (the sessionless score/preview ops). Managed
-     *  sessions bill per-op only (uptime metering skips them — flat per-op is the
-     *  public contract), run a SHORT idle TTL, never mint a scratch composition,
-     *  and are the only rows the managed resolver may reuse or evict. */
-    managed: z.boolean().optional(),
-    /** Async-evidence lease: the jobId currently staging/judging on this box. A
-     *  second evidence op on the same box while the lease is live gets 409
-     *  box_busy instead of silently bumping the working-composition version out
-     *  from under the in-flight judge. Cleared at the job terminal; expiry is the
-     *  crash backstop. */
-    leaseJobId: NonEmptyString.optional(),
-    leaseExpiresAt: z.number().optional(),
-});

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

@@ -1,16 +0,0 @@
-import { z } from "zod";
-import { EntityId, ISODateTime, NonEmptyString } from "@cueframe/foundation/primitives";
-/**
- * Short-lived bearer token used by Tus / Uppy Companion to upload files
- * directly to R2 without bundling org credentials into the browser.
- */
-export const UploadTokenScope = z.enum(["tus", "companion"]);
-export const UploadToken = z.object({
-    id: EntityId("uploadTokens"),
-    token: NonEmptyString,
-    userId: NonEmptyString,
-    projectId: EntityId("projects").optional(),
-    orgId: NonEmptyString.optional(),
-    scope: UploadTokenScope.optional(),
-    expiresAt: ISODateTime,
-});

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

@@ -1,12 +0,0 @@
-import { z } from "zod";
-import { EntityId, NonEmptyString } from "@cueframe/foundation/primitives";
-/**
- * Per-user preferences. Sparse by design — every field is optional, so
- * downstream readers should use defaults rather than asserting presence.
- */
-export const UserSettings = z.object({
-    id: EntityId("userSettings"),
-    userId: NonEmptyString,
-    enableUnderstanding: z.boolean().optional(),
-    activeBrandKitId: EntityId("brandKits").optional(),
-});

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

@@ -1,20 +0,0 @@
-import { z } from "zod";
-import { EntityId, NonEmptyString } from "@cueframe/foundation/primitives";
-/**
- * The single in-progress composition source for a warm render session. Both the
- * Director compose loop (per attempt) and a client debug session write here; the
- * in-container daemon subscribes to it via `getWorkingComposition`. The project
- * `compositions` row and per-candidate `compositionRuns` rows remain the
- * settle-time SSOT + history — this is the live, reactive surface only.
- */
-export const WorkingComposition = z.object({
-    id: EntityId("workingCompositions"),
-    sessionId: NonEmptyString,
-    projectId: EntityId("projects"),
-    orgId: NonEmptyString,
-    // Wire composition stored loose (mirrors compositionRuns.composition v.any()).
-    composition: z.unknown(),
-    // Monotonic per-session edit counter — the read-your-writes handshake key.
-    version: z.number(),
-    updatedAt: z.number(),
-});

package/dist/_members/brand-derivation/constants.js

@@ -1,20 +0,0 @@
-/**
- * Derivation constants — pure data, ZERO side effects, ZERO heavy imports.
- *
- * This module deliberately imports NOTHING (no apca-w3, no culori). Render-side
- * consumers (e.g. @cueframe/primitives) need only the ramp poles / floors and
- * must not drag the contrast MATH (apca-w3 + culori) into their bundle just for
- * two string constants. `contrastSafe.ts` re-exports these so the package root
- * stays the single source of truth; leaf consumers import from
- * `@cueframe/brand-derivation/constants`.
- */
-/** Version of the derivation RULES. Bump when the math changes; downstream stamps
- *  this so re-derivation is explicit, never a silent fleet-wide shift.
- *  v2: Tier-2 derivation expansion — adds surface/card/gridLine/accentMuted fills
- *  and textOnAccent/textOnSurface paired foregrounds. Re-derives the fleet. */
-export const DERIVATION_VERSION = 2;
-/** Forward-only APCA floors. The clamp only ever INCREASES legibility. */
-export const FLOORS = { body: 75, nonBody: 60, headline: 45 };
-/** The two neutral poles. `onDark` (white) is the safe default text color when the
- *  background is unknown; `onLight` (near-black) is the safe plate / dark pole. */
-export const NEUTRAL_RAMP = { onDark: "#FFFFFF", onLight: "#0A0A0A" };

package/dist/_members/brand-derivation/contrastSafe.js

@@ -1,114 +0,0 @@
-import { APCAcontrast, sRGBtoY } from "apca-w3";
-import { converter } from "culori";
-// DERIVATION_VERSION / FLOORS / NEUTRAL_RAMP live in the side-effect-free
-// `./constants` module (no apca-w3/culori) so render-side consumers can import
-// the poles without dragging the contrast math into their bundle. Re-exported
-// here so the package root stays the single source of truth.
-export { DERIVATION_VERSION, FLOORS, NEUTRAL_RAMP } from "./constants";
-import { FLOORS, NEUTRAL_RAMP } from "./constants";
-// Leaf-package color parsing via culori — this package must NOT import composition-model.
-const toRgb = converter("rgb");
-function hexToRgb(hex) {
-    const c = toRgb(hex);
-    if (!c)
-        return [0, 0, 0]; // unparseable → black; the clamp still guarantees a floor
-    return [Math.round(c.r * 255), Math.round(c.g * 255), Math.round(c.b * 255)];
-}
-/** Linear-RGB mix of two hex colors: ratio 0 → `a`, ratio 1 → `b`. Parses `#RGB` / `#RRGGBB`;
- *  returns `#rrggbb` lowercase. Mirrors composition-model's `colorMix` (we can't import it — leaf
- *  package boundary). On an unparseable input the clamp downstream still guarantees a floor. */
-function colorMix(a, b, ratio) {
-    const [ar, ag, ab] = hexToRgb(a);
-    const [br, bg, bb] = hexToRgb(b);
-    const t = Math.max(0, Math.min(1, ratio));
-    const inv = 1 - t;
-    const r = Math.round(ar * inv + br * t);
-    const g = Math.round(ag * inv + bg * t);
-    const bl = Math.round(ab * inv + bb * t);
-    return "#" + [r, g, bl].map((v) => v.toString(16).padStart(2, "0")).join("");
-}
-/** Lc magnitude between two hex colors (APCA is signed by polarity; the floor wants the magnitude).
- *  APCAcontrast is typed `number | string` (a string sentinel for out-of-range luminance, which
- *  sRGBtoY's 0..1 output never produces); coerce to a number at this single boundary. */
-function lc(fg, bg) {
-    return Math.abs(Number(APCAcontrast(sRGBtoY(hexToRgb(fg)), sRGBtoY(hexToRgb(bg)))));
-}
-/** sRGB relative luminance Y∈[0,1] of a hex color, via apca-w3's `sRGBtoY`.
- *  Exported so composition-side legibility (which compares text against a
- *  SAMPLED backdrop luminance, not a second hex) can put text + backdrop on the
- *  same Y scale without re-deriving the transfer curve. */
-export function relativeLuminance(hex) {
-    return sRGBtoY(hexToRgb(hex));
-}
-/** APCA Lc magnitude between two relative-luminance values (text fg over bg).
- *  This is the primitive the composition FLOOR's worst-tile legibility check
- *  consumes: it samples per-tile backdrop luminance from the rendered frame and
- *  asks "does the caption text clear the floor over the WORST tile?". Polarity-
- *  signed APCA is reduced to a magnitude (the floor wants legibility, not which
- *  way the polarity runs). Keep the APCA math in THIS package — the floor must
- *  not re-implement it (single source of truth, no proxy). */
-export function apcaLcFromLuminance(fgY, bgY) {
-    return Math.abs(Number(APCAcontrast(fgY, bgY)));
-}
-/** APCA Lc magnitude between two hex colors (fg over bg). Hex-input sibling of
- *  `apcaLcFromLuminance`; the brand cascade and tests use it directly. */
-export function apcaLc(fg, bg) {
-    return lc(fg, bg);
-}
-/** Return `fg` if it clears `floor` over `bg`; else the most legible of {fg, ramp poles} over `bg`
- *  (never lower contrast than the input — forward-only by construction). Exported so the brand
- *  cascade (composition-model) can re-clamp its own derived de-emphasis tokens (e.g. the muted
- *  text mix) back up to a floor without re-implementing the APCA math at the package boundary. */
-export function clampToFloor(fg, bg, floor) {
-    if (lc(fg, bg) >= floor)
-        return fg;
-    const candidates = [fg, NEUTRAL_RAMP.onDark, NEUTRAL_RAMP.onLight];
-    return candidates.reduce((best, c) => (lc(c, bg) > lc(best, bg) ? c : best));
-}
-/** Caption legibility is UNCONDITIONAL. If the brand background can host caption text at the body
- *  floor, keep it as the scrim. Otherwise fall to a neutral plate (near-black scrim + white fg),
- *  where the pole-over-pole APCA (~106) clears the floor for ANY brand. */
-function deriveCaption(seedText, background) {
-    const onBrand = clampToFloor(seedText, background, FLOORS.body);
-    if (lc(onBrand, background) >= FLOORS.body) {
-        return { captionScrim: background, captionFg: onBrand };
-    }
-    return { captionScrim: NEUTRAL_RAMP.onLight, captionFg: NEUTRAL_RAMP.onDark }; // near-black plate, white fg
-}
-/** Derive a contrast-safe palette from a brand seed.
- *  Captions are an UNCONDITIONAL floor: a plate-backed neutral fallback guarantees
- *  `Lc(captionFg, captionScrim) >= FLOORS.body` for any brand background.
- *  `text` / `textMuted` directly on a hostile brand background are best-achievable / forward-only
- *  (the monotone clamp never lowers a brand's own contrast); a tuned solid-background plate for
- *  body text on hostile backgrounds is Phase 1. */
-export function deriveContrastSafe(seed) {
-    const background = seed.background;
-    const text = clampToFloor(seed.text, background, FLOORS.body);
-    const accent = seed.accent;
-    const { captionScrim, captionFg } = deriveCaption(seed.text, background);
-    // Tier-2 fills: nudge the background toward text for raised surfaces / hairline rhythm.
-    const surface = colorMix(background, text, 0.06); // bg nudged toward text (raised panel)
-    const card = colorMix(background, text, 0.1); // one tonal step above surface
-    const gridLine = colorMix(background, text, 0.08); // hairline rhythm guide
-    const accentMuted = colorMix(accent, background, 0.35); // accent faded for secondary states
-    // textOnAccent is BEST-ACHIEVABLE, not floor-guaranteed: a saturated accent caps APCA below the
-    // body floor (e.g. white over #ff4438 ≈ 65.66), so the clamp returns the most legible pole it can
-    // reach, not necessarily one clearing FLOORS.body. The design NEVER puts body text on raw accent —
-    // body legibility lives on accentMuted / surface / background, where the floor IS guaranteed.
-    const textOnAccent = clampToFloor(text, accent, FLOORS.body);
-    const textOnSurface = clampToFloor(text, surface, FLOORS.body);
-    return {
-        background,
-        text,
-        textMuted: clampToFloor(seed.text, background, FLOORS.nonBody),
-        accent,
-        captionScrim,
-        captionFg,
-        surface,
-        card,
-        gridLine,
-        accentMuted,
-        textOnAccent,
-        textOnSurface,
-    };
-}

package/dist/_members/brand-derivation/index.js

@@ -1 +0,0 @@
-export * from "./contrastSafe";