@miragon/pulse-widget-shell 0.0.0-stage → 0.21.0

package/dist/profile-migrations.d.ts

@@ -0,0 +1,71 @@
+import { type ProfileRecord } from "./profile-record.js";
+/** One record-level migration: reshapes the raw JSON of its FROM version in place. */
+type ProfileMigration = (raw: Record<string, unknown>) => void;
+/**
+ * The oldest record version this build reads as stored — the start of the
+ * migration history. No history predates it (#322): records an earlier
+ * pre-production build wrote at an older version are ADOPTED at the
+ * baseline, never upgraded. Their fields this build does not know (the flat
+ * module preferences of v1/v2) stay inert in the raw document — saves keep
+ * them, the per-field projection ignores them — so those preferences read as
+ * their defaults, while the fields every record has carried (`language`,
+ * `modules`) survive. A missing or out-of-range `schemaVersion`
+ * reads as the baseline too.
+ */
+export declare const PROFILE_MIGRATION_BASELINE = 3;
+/**
+ * Record-level migrations, keyed by the version they upgrade FROM: one entry
+ * for every version from {@link PROFILE_MIGRATION_BASELINE} up to
+ * `PROFILE_SCHEMA_VERSION`, so every `PROFILE_SCHEMA_VERSION` bump adds
+ * exactly one entry here and a stored record upgrades on read instead of
+ * losing its preferences. Migrations transform the raw JSON — the migrated
+ * result still goes through the per-field `projectProfileRecord`, which is
+ * the actual gate.
+ *
+ * Exported ONLY for the completeness test in `profile-migrations.test.ts`,
+ * which fails the moment a `PROFILE_SCHEMA_VERSION` bump forgets its entry —
+ * without it that mistake would surface as preferences read un-migrated.
+ */
+export declare const PROFILE_MIGRATIONS: Readonly<Record<number, ProfileMigration>>;
+/** The history {@link migrateStoredProfile} walks — the shipped one unless a test injects its own. */
+interface ProfileMigrationHistory {
+    baseline: number;
+    current: number;
+    migrations: Readonly<Record<number, ProfileMigration>>;
+}
+/** A stored document after {@link migrateStoredProfile}, plus the version it is now at. */
+export interface MigratedProfileDocument {
+    /** A shallow copy of the stored JSON, upgraded as far as the migrations reach. */
+    doc: Record<string, unknown>;
+    version: number;
+}
+/**
+ * Upgrade a persisted profile document of ANY schema version as far as this
+ * build can — the RAW half of the read gate, shared by the read path
+ * ({@link parseStoredProfile}) and the save path (`mergeStoredProfile`):
+ *
+ *   - a version below the baseline is adopted AT the baseline (see
+ *     {@link PROFILE_MIGRATION_BASELINE});
+ *   - from there it upgrades through {@link PROFILE_MIGRATIONS} step by step;
+ *   - a NEWER version (written by a newer build — rolling deploy, rollback)
+ *     passes through untouched: an older build never reshapes it;
+ *   - a missing migration (a build bug the completeness test catches) stops at
+ *     the stuck version, so a fixed build can still upgrade the document.
+ *
+ * Unknown keys always survive. `undefined` only for JSON that is no object.
+ */
+export declare function migrateStoredProfile(json: unknown, history?: ProfileMigrationHistory): MigratedProfileDocument | undefined;
+/**
+ * Parse a persisted profile document into the current typed record — the
+ * read gate shared by every store (mirroring the toolkit's tolerant
+ * `parseDashboardRecord`): {@link migrateStoredProfile}, then the per-FIELD
+ * projection `projectProfileRecord`, so one value this build cannot validate
+ * degrades only that field and a newer build's document reads best-effort
+ * instead of as "no record" (which the next save would have written defaults
+ * over). Pass the store `key` as the record id; without one the stored `id`
+ * is used, and a document carrying none reads as `undefined`, like JSON that
+ * is no object.
+ */
+export declare function parseStoredProfile(json: unknown, key?: string): ProfileRecord | undefined;
+export {};
+//# sourceMappingURL=profile-migrations.d.ts.map

package/dist/profile-migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-migrations.d.ts","sourceRoot":"","sources":["../src/profile-migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAE9E,sFAAsF;AACtF,KAAK,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;AAE9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAM,CAAA;AAEhF,sGAAsG;AACtG,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAA;CACvD;AAQD,2FAA2F;AAC3F,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,uBAAyC,GACjD,uBAAuB,GAAG,SAAS,CAuBrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAKzF"}

package/dist/profile-migrations.js

@@ -0,0 +1,88 @@
+import { PROFILE_SCHEMA_VERSION } from "./profile-constants.js";
+import { projectProfileRecord } from "./profile-record.js";
+/**
+ * The oldest record version this build reads as stored — the start of the
+ * migration history. No history predates it (#322): records an earlier
+ * pre-production build wrote at an older version are ADOPTED at the
+ * baseline, never upgraded. Their fields this build does not know (the flat
+ * module preferences of v1/v2) stay inert in the raw document — saves keep
+ * them, the per-field projection ignores them — so those preferences read as
+ * their defaults, while the fields every record has carried (`language`,
+ * `modules`) survive. A missing or out-of-range `schemaVersion`
+ * reads as the baseline too.
+ */
+export const PROFILE_MIGRATION_BASELINE = 3;
+/**
+ * Record-level migrations, keyed by the version they upgrade FROM: one entry
+ * for every version from {@link PROFILE_MIGRATION_BASELINE} up to
+ * `PROFILE_SCHEMA_VERSION`, so every `PROFILE_SCHEMA_VERSION` bump adds
+ * exactly one entry here and a stored record upgrades on read instead of
+ * losing its preferences. Migrations transform the raw JSON — the migrated
+ * result still goes through the per-field `projectProfileRecord`, which is
+ * the actual gate.
+ *
+ * Exported ONLY for the completeness test in `profile-migrations.test.ts`,
+ * which fails the moment a `PROFILE_SCHEMA_VERSION` bump forgets its entry —
+ * without it that mistake would surface as preferences read un-migrated.
+ */
+export const PROFILE_MIGRATIONS = {};
+const SHIPPED_HISTORY = {
+    baseline: PROFILE_MIGRATION_BASELINE,
+    current: PROFILE_SCHEMA_VERSION,
+    migrations: PROFILE_MIGRATIONS,
+};
+/**
+ * Upgrade a persisted profile document of ANY schema version as far as this
+ * build can — the RAW half of the read gate, shared by the read path
+ * ({@link parseStoredProfile}) and the save path (`mergeStoredProfile`):
+ *
+ *   - a version below the baseline is adopted AT the baseline (see
+ *     {@link PROFILE_MIGRATION_BASELINE});
+ *   - from there it upgrades through {@link PROFILE_MIGRATIONS} step by step;
+ *   - a NEWER version (written by a newer build — rolling deploy, rollback)
+ *     passes through untouched: an older build never reshapes it;
+ *   - a missing migration (a build bug the completeness test catches) stops at
+ *     the stuck version, so a fixed build can still upgrade the document.
+ *
+ * Unknown keys always survive. `undefined` only for JSON that is no object.
+ */
+export function migrateStoredProfile(json, history = SHIPPED_HISTORY) {
+    if (typeof json !== "object" || json === null || Array.isArray(json))
+        return undefined;
+    const doc = { ...json };
+    const { baseline, current, migrations } = history;
+    const rawVersion = doc.schemaVersion;
+    // `Number.isInteger` is false for anything but an integer NUMBER.
+    let version = Number.isInteger(rawVersion) ? Math.max(rawVersion, baseline) : baseline;
+    doc.schemaVersion = version;
+    while (version < current) {
+        const migrate = migrations[version];
+        if (!migrate) {
+            console.error(`[widget-shell] No profile migration from schema v${version} — reading the stored record best-effort and keeping it un-migrated`);
+            break;
+        }
+        migrate(doc);
+        version += 1;
+        doc.schemaVersion = version;
+    }
+    return { doc, version };
+}
+/**
+ * Parse a persisted profile document into the current typed record — the
+ * read gate shared by every store (mirroring the toolkit's tolerant
+ * `parseDashboardRecord`): {@link migrateStoredProfile}, then the per-FIELD
+ * projection `projectProfileRecord`, so one value this build cannot validate
+ * degrades only that field and a newer build's document reads best-effort
+ * instead of as "no record" (which the next save would have written defaults
+ * over). Pass the store `key` as the record id; without one the stored `id`
+ * is used, and a document carrying none reads as `undefined`, like JSON that
+ * is no object.
+ */
+export function parseStoredProfile(json, key) {
+    const migrated = migrateStoredProfile(json);
+    if (!migrated)
+        return undefined;
+    const id = key ?? (typeof migrated.doc.id === "string" ? migrated.doc.id : undefined);
+    return id === undefined ? undefined : projectProfileRecord(migrated.doc, id);
+}
+//# sourceMappingURL=profile-migrations.js.map

package/dist/profile-migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-migrations.js","sourceRoot":"","sources":["../src/profile-migrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,oBAAoB,EAAsB,MAAM,qBAAqB,CAAA;AAK9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA+C,EAAE,CAAA;AAShF,MAAM,eAAe,GAA4B;IAC/C,QAAQ,EAAE,0BAA0B;IACpC,OAAO,EAAE,sBAAsB;IAC/B,UAAU,EAAE,kBAAkB;CAC/B,CAAA;AASD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAa,EACb,UAAmC,eAAe;IAElD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAA;IACtF,MAAM,GAAG,GAA4B,EAAE,GAAI,IAAgC,EAAE,CAAA;IAE7E,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAA;IACjD,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,CAAA;IACpC,kEAAkE;IAClE,IAAI,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,UAAoB,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;IAChG,GAAG,CAAC,aAAa,GAAG,OAAO,CAAA;IAE3B,OAAO,OAAO,GAAG,OAAO,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;QACnC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CACX,oDAAoD,OAAO,qEAAqE,CACjI,CAAA;YACD,MAAK;QACP,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,CAAA;QACZ,OAAO,IAAI,CAAC,CAAA;QACZ,GAAG,CAAC,aAAa,GAAG,OAAO,CAAA;IAC7B,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAA;AACzB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAa,EAAE,GAAY;IAC5D,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;IAC3C,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAA;IAC/B,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC,OAAO,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IACrF,OAAO,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;AAC9E,CAAC"}

package/dist/profile-migrations.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=profile-migrations.test.d.ts.map

package/dist/profile-migrations.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-migrations.test.d.ts","sourceRoot":"","sources":["../src/profile-migrations.test.ts"],"names":[],"mappings":""}

package/dist/profile-migrations.test.js

@@ -0,0 +1,200 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PROFILE_MIGRATION_BASELINE, PROFILE_MIGRATIONS, migrateStoredProfile, parseStoredProfile, } from "./profile-migrations.js";
+import { PROFILE_SCHEMA_VERSION } from "./profile-constants.js";
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+const CURRENT = {
+    id: "user-1",
+    language: "de",
+    modules: { analytics: { defaultPeriod: "14d" }, camunda7: { defaultEngineId: "prod-a" } },
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-02T00:00:00.000Z",
+    schemaVersion: PROFILE_SCHEMA_VERSION,
+};
+/** Shapes the pre-production builds persisted before the baseline: flat module fields. */
+const V1_RECORD = {
+    id: "user-1",
+    language: "de",
+    theme: "dark",
+    pinnedDashboardIds: ["d1"],
+    analyticsDefaultPeriod: "30d",
+    analyticsMinBucketSize: 25,
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-02T00:00:00.000Z",
+    schemaVersion: 1,
+};
+const V2_RECORD = {
+    id: "user-1",
+    language: "de",
+    theme: "dark",
+    defaultEngineId: "prod-a",
+    allowedEngineIds: ["prod-a"],
+    modules: { analytics: { defaultPeriod: "14d" } },
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-02T00:00:00.000Z",
+    schemaVersion: 2,
+};
+/**
+ * The baseline as shipped, pinned HERE rather than read from the export: the
+ * completeness range below starts at it, so a baseline raised in step with a
+ * `PROFILE_SCHEMA_VERSION` bump would empty that range and let the bump pass
+ * without its migration — every stored record of the old version would then
+ * be adopted at the new one without its reshape. Moving the baseline drops
+ * migration history, which is an owner decision of its own, never part of a
+ * schema bump.
+ */
+const SHIPPED_BASELINE = 3;
+describe("PROFILE_MIGRATIONS completeness", () => {
+    it("keeps the migration baseline where it shipped", () => {
+        expect(PROFILE_MIGRATION_BASELINE).toBe(SHIPPED_BASELINE);
+    });
+    it("carries an entry for every version from the baseline up to PROFILE_SCHEMA_VERSION", () => {
+        // The failure mode this guards: a PROFILE_SCHEMA_VERSION bump without its
+        // migration entry ships, and every stored record reads un-migrated.
+        const expected = Array.from({ length: PROFILE_SCHEMA_VERSION - SHIPPED_BASELINE }, (_, i) => SHIPPED_BASELINE + i);
+        const actual = Object.keys(PROFILE_MIGRATIONS)
+            .map(Number)
+            .sort((a, b) => a - b);
+        expect(actual).toEqual(expected);
+    });
+});
+describe("parseStoredProfile", () => {
+    it("passes a current-version record through unchanged", () => {
+        expect(parseStoredProfile(CURRENT)).toEqual(CURRENT);
+    });
+    // No migration history predates the baseline (#322): an older record is
+    // adopted, never upgraded — and must still read without an error.
+    it.each([
+        ["v1", V1_RECORD, {}],
+        ["v2", V2_RECORD, V2_RECORD.modules],
+    ])("reads a %s record from before the baseline fail-soft: its flat fields drop to the defaults", (_, stored, modules) => {
+        const error = vi.spyOn(console, "error").mockImplementation(() => { });
+        expect(parseStoredProfile(stored)).toEqual({
+            id: "user-1",
+            language: "de",
+            modules,
+            createdAt: stored.createdAt,
+            updatedAt: stored.updatedAt,
+            schemaVersion: PROFILE_SCHEMA_VERSION,
+        });
+        expect(error).not.toHaveBeenCalled();
+    });
+    it("reads a missing or out-of-range schemaVersion as the baseline", () => {
+        const versionless = { ...CURRENT };
+        delete versionless.schemaVersion;
+        expect(parseStoredProfile(versionless)).toEqual(CURRENT);
+        expect(parseStoredProfile({ ...CURRENT, schemaVersion: 0 })).toEqual(CURRENT);
+        expect(parseStoredProfile({ ...CURRENT, schemaVersion: 2.5 })).toEqual(CURRENT);
+    });
+    it("reads a record from a NEWER build best-effort, without running any migration", () => {
+        const parsed = parseStoredProfile({
+            ...CURRENT,
+            newCoreField: true,
+            schemaVersion: PROFILE_SCHEMA_VERSION + 1,
+        });
+        // Untouched: a newer build's document is never reshaped by an older one.
+        expect(parsed).toEqual(CURRENT);
+    });
+    it("reads a record with the retired theme preference: the key never reaches the view", () => {
+        // Widgets follow the host's theme; a `theme` an earlier build saved is
+        // an unknown key now — no migration, no error, no reset of the rest.
+        expect(parseStoredProfile({ ...CURRENT, theme: "dark" })).toEqual(CURRENT);
+        expect(parseStoredProfile({ ...CURRENT, theme: 42 })).toEqual(CURRENT);
+    });
+    it("keeps the system language preference — following the host is a stored choice", () => {
+        expect(parseStoredProfile({ ...CURRENT, language: "system" })?.language).toBe("system");
+    });
+    it("degrades an invalid field to ITS default and keeps every other field", () => {
+        // The language default is `system` (follow the host), never a forced locale.
+        expect(parseStoredProfile({ ...CURRENT, language: "fr" })).toMatchObject({
+            language: "system",
+            modules: CURRENT.modules,
+        });
+        expect(parseStoredProfile({ ...CURRENT, userId: 7 })).toMatchObject({
+            language: "de",
+            modules: CURRENT.modules,
+            userId: undefined,
+        });
+        expect(parseStoredProfile({ ...CURRENT, modules: "garbage" })?.modules).toEqual({});
+    });
+    it("prefers the store key over the stored id and repairs missing timestamps", () => {
+        expect(parseStoredProfile(CURRENT, "other-key")?.id).toBe("other-key");
+        const sparse = parseStoredProfile({ schemaVersion: 3 }, "k");
+        expect(sparse).toMatchObject({ id: "k", language: "system", modules: {} });
+        expect(sparse?.createdAt).toBe(sparse?.updatedAt);
+        expect(parseStoredProfile({ schemaVersion: 3, updatedAt: "2026-02-02T00:00:00.000Z" }, "k")).toMatchObject({
+            createdAt: "2026-02-02T00:00:00.000Z",
+            updatedAt: "2026-02-02T00:00:00.000Z",
+        });
+    });
+    it("reads garbage as absent", () => {
+        expect(parseStoredProfile(null)).toBeUndefined();
+        expect(parseStoredProfile("nope")).toBeUndefined();
+        expect(parseStoredProfile(["an", "array"])).toBeUndefined();
+        // No id stored (or none that is a string) and no store key to fall back to.
+        expect(parseStoredProfile({ schemaVersion: 0 })).toBeUndefined();
+        expect(parseStoredProfile({ ...CURRENT, id: 42 })).toBeUndefined();
+    });
+});
+describe("migrateStoredProfile", () => {
+    it("adopts a pre-baseline document at the baseline, keeping its unknown keys raw", () => {
+        expect(migrateStoredProfile(V1_RECORD)).toEqual({
+            doc: { ...V1_RECORD, schemaVersion: PROFILE_MIGRATION_BASELINE },
+            version: PROFILE_MIGRATION_BASELINE,
+        });
+    });
+    it("reports the version the document ends at", () => {
+        expect(migrateStoredProfile(CURRENT)?.version).toBe(PROFILE_SCHEMA_VERSION);
+        expect(migrateStoredProfile({ ...CURRENT, schemaVersion: 42 })?.version).toBe(42);
+        // Anything but an integer number reads as the baseline — never NaN.
+        for (const schemaVersion of [undefined, "4", 4.5, null]) {
+            expect(migrateStoredProfile({ ...CURRENT, schemaVersion })?.version).toBe(PROFILE_MIGRATION_BASELINE);
+        }
+        expect(migrateStoredProfile(undefined)).toBeUndefined();
+        expect(migrateStoredProfile(null)).toBeUndefined();
+        expect(migrateStoredProfile([CURRENT])).toBeUndefined();
+    });
+    it("never mutates the stored JSON it was handed", () => {
+        const stored = { ...V1_RECORD };
+        const snapshot = structuredClone(stored);
+        migrateStoredProfile(stored);
+        expect(stored).toEqual(snapshot);
+    });
+    // The walk itself, against a synthetic history: the shipped one has no
+    // step yet (the baseline IS the current version), but the next
+    // PROFILE_SCHEMA_VERSION bump runs exactly this loop.
+    const history = {
+        baseline: 1,
+        current: 3,
+        migrations: {
+            1: (raw) => {
+                raw.steps = [...(raw.steps ?? []), 1];
+            },
+            2: (raw) => {
+                raw.steps = [...(raw.steps ?? []), 2];
+            },
+        },
+    };
+    it("upgrades step by step from the stored version, stamping each step", () => {
+        expect(migrateStoredProfile({ schemaVersion: 1 }, history)).toEqual({
+            doc: { schemaVersion: 3, steps: [1, 2] },
+            version: 3,
+        });
+        expect(migrateStoredProfile({ schemaVersion: 2 }, history)).toEqual({
+            doc: { schemaVersion: 3, steps: [2] },
+            version: 3,
+        });
+    });
+    it("stops at a version without its step (a build bug) and keeps the document there", () => {
+        const error = vi.spyOn(console, "error").mockImplementation(() => { });
+        const gap = { ...history, migrations: { 1: history.migrations[1] } };
+        expect(migrateStoredProfile({ schemaVersion: 1 }, gap)).toEqual({
+            doc: { schemaVersion: 2, steps: [1] },
+            version: 2,
+        });
+        expect(error).toHaveBeenCalledTimes(1);
+        expect(error).toHaveBeenCalledWith(expect.stringContaining("No profile migration from schema v2"));
+    });
+});
+//# sourceMappingURL=profile-migrations.test.js.map

package/dist/profile-migrations.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-migrations.test.js","sourceRoot":"","sources":["../src/profile-migrations.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC5D,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAE/D,SAAS,CAAC,GAAG,EAAE;IACb,EAAE,CAAC,eAAe,EAAE,CAAA;AACtB,CAAC,CAAC,CAAA;AAEF,MAAM,OAAO,GAAG;IACd,EAAE,EAAE,QAAQ;IACZ,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,eAAe,EAAE,QAAQ,EAAE,EAAE;IACzF,SAAS,EAAE,0BAA0B;IACrC,SAAS,EAAE,0BAA0B;IACrC,aAAa,EAAE,sBAAsB;CACtC,CAAA;AAED,0FAA0F;AAC1F,MAAM,SAAS,GAAG;IAChB,EAAE,EAAE,QAAQ;IACZ,QAAQ,EAAE,IAAI;IACd,KAAK,EAAE,MAAM;IACb,kBAAkB,EAAE,CAAC,IAAI,CAAC;IAC1B,sBAAsB,EAAE,KAAK;IAC7B,sBAAsB,EAAE,EAAE;IAC1B,SAAS,EAAE,0BAA0B;IACrC,SAAS,EAAE,0BAA0B;IACrC,aAAa,EAAE,CAAC;CACjB,CAAA;AACD,MAAM,SAAS,GAAG;IAChB,EAAE,EAAE,QAAQ;IACZ,QAAQ,EAAE,IAAI;IACd,KAAK,EAAE,MAAM;IACb,eAAe,EAAE,QAAQ;IACzB,gBAAgB,EAAE,CAAC,QAAQ,CAAC;IAC5B,OAAO,EAAE,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE;IAChD,SAAS,EAAE,0BAA0B;IACrC,SAAS,EAAE,0BAA0B;IACrC,aAAa,EAAE,CAAC;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,gBAAgB,GAAG,CAAC,CAAA;AAE1B,QAAQ,CAAC,iCAAiC,EAAE,GAAG,EAAE;IAC/C,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,0BAA0B,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mFAAmF,EAAE,GAAG,EAAE;QAC3F,0EAA0E;QAC1E,oEAAoE;QACpE,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CACzB,EAAE,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,EAAE,EACrD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,gBAAgB,GAAG,CAAC,CAC/B,CAAA;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC;aAC3C,GAAG,CAAC,MAAM,CAAC;aACX,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACxB,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClC,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IACtD,CAAC,CAAC,CAAA;IAEF,wEAAwE;IACxE,kEAAkE;IAClE,EAAE,CAAC,IAAI,CAAC;QACN,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC;QACrB,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC;KACrC,CAAC,CACA,4FAA4F,EAC5F,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE;QACrB,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACrE,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;YACzC,EAAE,EAAE,QAAQ;YACZ,QAAQ,EAAE,IAAI;YACd,OAAO;YACP,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,aAAa,EAAE,sBAAsB;SACtC,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAA;IACtC,CAAC,CACF,CAAA;IAED,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,WAAW,GAA4B,EAAE,GAAG,OAAO,EAAE,CAAA;QAC3D,OAAO,WAAW,CAAC,aAAa,CAAA;QAChC,MAAM,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACxD,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC7E,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IACjF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACtF,MAAM,MAAM,GAAG,kBAAkB,CAAC;YAChC,GAAG,OAAO;YACV,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,sBAAsB,GAAG,CAAC;SAC1C,CAAC,CAAA;QACF,yEAAyE;QACzE,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IACjC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kFAAkF,EAAE,GAAG,EAAE;QAC1F,uEAAuE;QACvE,qEAAqE;QACrE,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC1E,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IACxE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACtF,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACzF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sEAAsE,EAAE,GAAG,EAAE;QAC9E,6EAA6E;QAC7E,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;YACvE,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAA;QACF,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;YAClE,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,SAAS;SAClB,CAAC,CAAA;QACF,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IACrF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;QACjF,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;QACtE,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;QAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAA;QAC1E,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;QACjD,MAAM,CACJ,kBAAkB,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,SAAS,EAAE,0BAA0B,EAAE,EAAE,GAAG,CAAC,CACrF,CAAC,aAAa,CAAC;YACd,SAAS,EAAE,0BAA0B;YACrC,SAAS,EAAE,0BAA0B;SACtC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QAChD,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QAClD,MAAM,CAAC,kBAAkB,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QAC3D,4EAA4E;QAC5E,MAAM,CAAC,kBAAkB,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QAChE,MAAM,CAAC,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;IACpE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACtF,MAAM,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;YAC9C,GAAG,EAAE,EAAE,GAAG,SAAS,EAAE,aAAa,EAAE,0BAA0B,EAAE;YAChE,OAAO,EAAE,0BAA0B;SACpC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,oBAAoB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAA;QAC3E,MAAM,CAAC,oBAAoB,CAAC,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACjF,oEAAoE;QACpE,KAAK,MAAM,aAAa,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;YACxD,MAAM,CAAC,oBAAoB,CAAC,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CACvE,0BAA0B,CAC3B,CAAA;QACH,CAAC;QACD,MAAM,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QACvD,MAAM,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QAClD,MAAM,CAAC,oBAAoB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;IACzD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,MAAM,GAAG,EAAE,GAAG,SAAS,EAAE,CAAA;QAC/B,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;QACxC,oBAAoB,CAAC,MAAM,CAAC,CAAA;QAC5B,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClC,CAAC,CAAC,CAAA;IAEF,uEAAuE;IACvE,+DAA+D;IAC/D,sDAAsD;IACtD,MAAM,OAAO,GAAG;QACd,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;QACV,UAAU,EAAE;YACV,CAAC,EAAE,CAAC,GAA4B,EAAE,EAAE;gBAClC,GAAG,CAAC,KAAK,GAAG,CAAC,GAAG,CAAE,GAAG,CAAC,KAA8B,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;YACjE,CAAC;YACD,CAAC,EAAE,CAAC,GAA4B,EAAE,EAAE;gBAClC,GAAG,CAAC,KAAK,GAAG,CAAC,GAAG,CAAE,GAAG,CAAC,KAA8B,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;YACjE,CAAC;SACF;KACF,CAAA;IAED,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,MAAM,CAAC,oBAAoB,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;YAClE,GAAG,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;YACxC,OAAO,EAAE,CAAC;SACX,CAAC,CAAA;QACF,MAAM,CAAC,oBAAoB,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;YAClE,GAAG,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE;YACrC,OAAO,EAAE,CAAC;SACX,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gFAAgF,EAAE,GAAG,EAAE;QACxF,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACrE,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;QACpE,MAAM,CAAC,oBAAoB,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;YAC9D,GAAG,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE;YACrC,OAAO,EAAE,CAAC;SACX,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;QACtC,MAAM,CAAC,KAAK,CAAC,CAAC,oBAAoB,CAChC,MAAM,CAAC,gBAAgB,CAAC,qCAAqC,CAAC,CAC/D,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/profile-record.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { type LanguagePref } from "./profile-constants.js";
+/**
+ * The persisted profile record — deliberately connector-free: the
+ * cross-module preference every module may read (`language`), the per-module
+ * `modules.<module>` slice transport, and server-managed metadata. There is
+ * no theme preference: widgets follow the host's theme. A record an earlier
+ * build saved with a `theme` still reads — the key is unknown here, stays in
+ * the raw document and never reaches the typed view.
+ * Everything a connector wants to persist lives in ITS slice (validated
+ * fail-soft by the owning module), never as a new top-level field here.
+ *
+ * `id` is the profile key (the OAuth caller's id, or `anonymous` for an
+ * explicitly declared local caller — see `resolveProfileKey` in `profile.ts`);
+ * `userId` is the owner a save stamped (absent on the anonymous record).
+ */
+export declare const profileRecordSchema: z.ZodObject<{
+    language: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        de: "de";
+        system: "system";
+    }>>;
+    modules: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    id: z.ZodString;
+    userId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    schemaVersion: z.ZodDefault<z.ZodLiteral<3>>;
+}, z.core.$strip>;
+export type ProfileRecord = z.infer<typeof profileRecordSchema>;
+/**
+ * Save input: any subset of the record's user-settable fields. Omitted fields
+ * keep their current value (the store merges over the existing record);
+ * `modules` slices merge per module key, one level deep — a save carrying
+ * `modules.analytics` spreads over the stored analytics slice (explicit
+ * `undefined` clears a field) and leaves other modules' slices untouched.
+ *
+ * A plain type, not a zod schema: validation happens at each module's TOOL
+ * boundary (with a default-free schema — see `withoutDefaults` in
+ * `profile.ts`), not in the store.
+ */
+export interface ProfileRecordSaveInput {
+    language?: LanguagePref;
+    modules?: Record<string, unknown>;
+}
+/** A fully-defaulted record for a key that has never been saved. */
+export declare function defaultProfileRecord(key: string): ProfileRecord;
+/**
+ * The typed VIEW of a stored profile document (current-shape, or written by a
+ * NEWER build), degrading per FIELD: a value this build cannot validate — a
+ * locale added later, a non-object `modules` — falls back to that field's
+ * default while everything else survives. Keys this build does not know are
+ * not part of the view, but they stay in the stored document: saves merge over
+ * the RAW document (`mergeStoredProfile` in `profile-store.ts`), never over
+ * this projection. Timestamps a hand-edited document lacks fall back to each
+ * other, then to `""` (the next save stamps both). `id` is the caller's (the
+ * store key wins).
+ */
+export declare function projectProfileRecord(doc: Record<string, unknown>, id: string): ProfileRecord;
+//# sourceMappingURL=profile-record.d.ts.map

package/dist/profile-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-record.d.ts","sourceRoot":"","sources":["../src/profile-record.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAqC,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE7F;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;iBAoB9B,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAS/D;AAWD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAc5F"}

package/dist/profile-record.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { LANGUAGES, PROFILE_SCHEMA_VERSION } from "./profile-constants.js";
+/**
+ * The persisted profile record — deliberately connector-free: the
+ * cross-module preference every module may read (`language`), the per-module
+ * `modules.<module>` slice transport, and server-managed metadata. There is
+ * no theme preference: widgets follow the host's theme. A record an earlier
+ * build saved with a `theme` still reads — the key is unknown here, stays in
+ * the raw document and never reaches the typed view.
+ * Everything a connector wants to persist lives in ITS slice (validated
+ * fail-soft by the owning module), never as a new top-level field here.
+ *
+ * `id` is the profile key (the OAuth caller's id, or `anonymous` for an
+ * explicitly declared local caller — see `resolveProfileKey` in `profile.ts`);
+ * `userId` is the owner a save stamped (absent on the anonymous record).
+ */
+export const profileRecordSchema = z.object({
+    language: z
+        .enum(LANGUAGES)
+        .default("system")
+        .describe('UI + summary language; "system" follows the host locale (summaries then stay English).'),
+    modules: z
+        .record(z.string(), z.unknown())
+        .default({})
+        .describe("Per-module settings slices, keyed by module name (e.g. `analytics`, `camunda7`). Each " +
+        "module owns its slice's schema, validates it fail-soft on read, and writes it through " +
+        "its own save tool — this record only transports the slices."),
+    id: z.string(),
+    userId: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    schemaVersion: z.literal(PROFILE_SCHEMA_VERSION).default(PROFILE_SCHEMA_VERSION),
+});
+/** A fully-defaulted record for a key that has never been saved. */
+export function defaultProfileRecord(key) {
+    const now = new Date().toISOString();
+    return {
+        ...profileRecordSchema.omit({ id: true, createdAt: true, updatedAt: true }).parse({}),
+        id: key,
+        userId: undefined,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+const nonEmptyString = (value) => typeof value === "string" && value.length > 0 ? value : undefined;
+/** The field's own value when it validates, else the field's default. */
+function fieldOrDefault(schema, value) {
+    const parsed = schema.safeParse(value);
+    return parsed.success ? parsed.data : schema.parse(undefined);
+}
+/**
+ * The typed VIEW of a stored profile document (current-shape, or written by a
+ * NEWER build), degrading per FIELD: a value this build cannot validate — a
+ * locale added later, a non-object `modules` — falls back to that field's
+ * default while everything else survives. Keys this build does not know are
+ * not part of the view, but they stay in the stored document: saves merge over
+ * the RAW document (`mergeStoredProfile` in `profile-store.ts`), never over
+ * this projection. Timestamps a hand-edited document lacks fall back to each
+ * other, then to `""` (the next save stamps both). `id` is the caller's (the
+ * store key wins).
+ */
+export function projectProfileRecord(doc, id) {
+    const whole = profileRecordSchema.safeParse(doc);
+    if (whole.success)
+        return { ...whole.data, id };
+    const { shape } = profileRecordSchema;
+    const updatedAt = nonEmptyString(doc.updatedAt) ?? nonEmptyString(doc.createdAt) ?? "";
+    return {
+        language: fieldOrDefault(shape.language, doc.language),
+        modules: fieldOrDefault(shape.modules, doc.modules),
+        id,
+        userId: fieldOrDefault(shape.userId, doc.userId),
+        createdAt: nonEmptyString(doc.createdAt) ?? updatedAt,
+        updatedAt,
+        schemaVersion: PROFILE_SCHEMA_VERSION,
+    };
+}
+//# sourceMappingURL=profile-record.js.map

package/dist/profile-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-record.js","sourceRoot":"","sources":["../src/profile-record.ts"],"names":[],"mappings":"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"}

package/dist/profile-slice.d.ts

@@ -0,0 +1,53 @@
+import type { z } from "zod";
+import type { ProfileSource } from "./profile.js";
+/**
+ * The `profile.modules.<module>` slice contract, shared by every module so
+ * the subtle rules cannot drift: WHOSE record a save touches (the canonical
+ * keyless refusal), HOW a slice patch is saved (the patch alone, merged by
+ * the store over the RAW stored slice under its lock, so foreign and
+ * concurrently saved fields survive), and HOW a slice reads (fail-soft per
+ * FIELD, so one bad value cannot reset the rest).
+ */
+/**
+ * Fail-soft slice read: absent slices and garbage degrade to the schema's
+ * defaults — and degradation is per FIELD, not per slice: a single invalid
+ * value (say, one written by a newer build and then rolled back) drops to its
+ * own default while every other saved preference survives. Fields the schema
+ * doesn't know stay out of the VIEW but are preserved in storage: a save
+ * ({@link saveModuleSlice}) merges over the raw stored slice.
+ *
+ * Read-side only — save inputs keep validating loudly at the tool boundary;
+ * a write must never silently coerce.
+ */
+export declare function parseModuleSlice<T extends z.ZodRawShape>(schema: z.ZodObject<T>, slice: unknown): z.output<z.ZodObject<T>>;
+/**
+ * Resolve the profile key for a durable write, refusing without one. Settings
+ * are saved per signed-in user: a request without OAuth resolves no key (see
+ * `resolveProfileKey`) — writing anyway would silently share one record across
+ * unrelated callers, so every module's save tool throws this same,
+ * operator-actionable error instead.
+ */
+export declare function requireProfileKey(ctx?: unknown): string;
+/**
+ * Persist a partial update of `module`'s slice: hand the store the PATCH
+ * alone, never a slice pre-read outside the store's lock. Every
+ * `ProfileStore` merges a `modules.<module>` patch one level deep over the
+ * RAW stored slice INSIDE its per-key serialization (the postgres
+ * transaction lock, the filesystem store's per-key mutex, the in-memory
+ * store's synchronous merge), so a concurrent save of another field in the
+ * same slice (or of another module's slice) survives, fields a newer build
+ * wrote survive, and no defaults are materialized into storage. A field set
+ * to `undefined` in the patch CLEARS the stored value; an absent field keeps
+ * it.
+ *
+ * Returns the saved slice, raw (the caller parses it fail-soft for its
+ * report): read off the record `save` returns (every shipped store returns
+ * it), or read back when a custom port implementation returns nothing.
+ */
+export declare function saveModuleSlice(store: {
+    get: ProfileSource["get"];
+    save: NonNullable<ProfileSource["save"]>;
+}, key: string, module: string, patch: Record<string, unknown>, opts?: {
+    userId?: string;
+}): Promise<unknown>;
+//# sourceMappingURL=profile-slice.d.ts.map

package/dist/profile-slice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-slice.d.ts","sourceRoot":"","sources":["../src/profile-slice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,cAAc,CAAA;AAE/D;;;;;;;GAOG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EACtD,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,KAAK,EAAE,OAAO,GACb,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAY1B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,MAAM,CAQvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE;IAAE,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,EAC9E,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,OAAO,CAAC,CAIlB"}