@frockbot/configuration-core 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/configuration-core",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/connection-core": "0.1.4",
-    "@frockbot/kernel-composition": "0.1.4"
+    "@frockbot/connection-core": "0.2.0",
+    "@frockbot/kernel-composition": "0.2.0"
   },
   "devDependencies": {
     "@types/bun": "1.3.6",

package/src/bot-identity.test.ts

@@ -1,8 +1,8 @@
 // Bot identity: the title, the name's provenance, and the sidebar-hidden flag.
 //
 // The first test is the one that matters most: a Bot settings record written
-// before any of this existed must still decode, because widening a durable DTO
-// with optional fields is the only migration this project permits.
+// before any of this existed must still decode. Optional additions need no
+// transform; incompatible stored shapes use explicit forward migrations.
 import { describe, expect, test } from "bun:test";
 import {
   applyBotProfilePatchV1,

package/src/index.test.ts

@@ -18,6 +18,8 @@ import {
   decodeUserConfigurationReadRpcV1,
   decodeUserSettingsViewV1,
   initializeBotSettingsV1,
+  migrateStoredBotSettingsV1,
+  migrateStoredUserSettingsV1,
   modelBindingFailureV1,
   resolveBotExecutionPlanV1,
   resolveBotModelBindingV1,
@@ -32,6 +34,190 @@ import {
   isRpcIdentifier,
 } from "./identifiers.js";
 
+describe("stored configuration migrations", () => {
+  test("migrates the pre-account-wide User record without honouring removed features", () => {
+    // Literal durable shape from eb0283edcce5daea976a21a9f6a6414bedc6e2bc,
+    // the first parent of PR #134's merge commit.
+    const stored = {
+      schemaVersion: 1,
+      revision: 7,
+      profile: { name: "Existing User" },
+      packages: [
+        {
+          packageId: "provider-ollama-cloud",
+          version: "0.0.1",
+          state: "installed" as const,
+          values: { "web-search-max-results": 5 },
+        },
+      ],
+      connections: [
+        {
+          connectionId: "ollama-1",
+          packageId: "provider-ollama-cloud",
+          connectionTypeId: "ollama-cloud-account",
+          displayName: "Work",
+          state: "ready" as const,
+          safeMetadata: {
+            region: "au",
+            dependentAssignments: [
+              {
+                botId: "bot-1",
+                generation: "assignment-1",
+                packageId: "provider-ollama-cloud",
+                capabilityId: "ollama-cloud-models",
+                claimOrder: 7,
+                status: "acknowledged",
+              },
+            ],
+          },
+        },
+      ],
+      newBotModelTemplate: {
+        connectionId: "ollama-1",
+        providerModelId: "glm-5.3-flash:cloud",
+      },
+      newBotModelTemplateSource: "user",
+    };
+
+    expect(
+      decodeUserSettingsViewV1(migrateStoredUserSettingsV1(stored)),
+    ).toEqual({
+      schemaVersion: 1,
+      revision: 7,
+      profile: { name: "Existing User" },
+      packages: stored.packages,
+      connections: [
+        {
+          ...stored.connections[0],
+          safeMetadata: { region: "au" },
+        },
+      ],
+    });
+    expect(stored.connections[0]?.safeMetadata).toHaveProperty(
+      "dependentAssignments",
+    );
+  });
+
+  test("keeps unknown User, Package, and Connection fields strict", () => {
+    const current = {
+      schemaVersion: 1,
+      revision: 0,
+      profile: { name: "Existing User" },
+      packages: [],
+      connections: [],
+    };
+    for (const stored of [
+      { ...current, unknown: true },
+      {
+        ...current,
+        packages: [
+          {
+            packageId: "settings",
+            version: "0.0.1",
+            state: "installed",
+            unknown: true,
+          },
+        ],
+      },
+      {
+        ...current,
+        connections: [
+          {
+            connectionId: "connection-1",
+            packageId: "provider-ollama-cloud",
+            connectionTypeId: "ollama-cloud-account",
+            displayName: "Work",
+            state: "ready",
+            safeMetadata: {},
+            unknown: true,
+          },
+        ],
+      },
+    ]) {
+      expect(() =>
+        decodeUserSettingsViewV1(migrateStoredUserSettingsV1(stored)),
+      ).toThrow(ConfigurationDecodeError);
+    }
+    expect(migrateStoredUserSettingsV1(current)).toBe(current);
+  });
+
+  test("migrates the pre-account-wide Bot record to an empty Package value bag", () => {
+    // Literal durable shape from eb0283edcce5daea976a21a9f6a6414bedc6e2bc,
+    // the first parent of PR #134's merge commit.
+    const stored = {
+      schemaVersion: 1,
+      botId: "primary",
+      revision: 4,
+      profile: { name: "Primary" },
+      notifications: { enabled: true },
+      assignments: [
+        {
+          assignmentId: "ollama-model",
+          packageId: "provider-ollama-cloud",
+          capabilityId: "ollama-cloud-models",
+          connectionId: "ollama-1",
+          state: "enabled",
+        },
+      ],
+      assignmentOperations: [
+        {
+          commandId: "replace-model",
+          kind: "replacing",
+          assignmentId: "ollama-model",
+          state: "retrying",
+          target: {
+            assignmentId: "ollama-model",
+            packageId: "provider-ollama-cloud",
+            capabilityId: "ollama-cloud-models",
+            connectionId: "ollama-1",
+          },
+        },
+      ],
+      model: {
+        connectionId: "ollama-1",
+        providerModelId: "glm-5.3-flash:cloud",
+      },
+    };
+
+    expect(decodeBotSettingsViewV1(migrateStoredBotSettingsV1(stored))).toEqual(
+      {
+        schemaVersion: 1,
+        botId: "primary",
+        revision: 4,
+        profile: { name: "Primary" },
+        notifications: { enabled: true },
+        packageValues: {},
+      },
+    );
+  });
+
+  test("keeps unknown Bot fields strict and current records unchanged", () => {
+    const current = initializeBotSettingsV1("primary");
+    expect(migrateStoredBotSettingsV1(current)).toBe(current);
+    const { packageValues: _packageValues, ...withoutPackageValues } = current;
+    expect(
+      decodeBotSettingsViewV1(
+        migrateStoredBotSettingsV1({
+          ...withoutPackageValues,
+          modelAssignment: {
+            connectionId: "ollama-1",
+            providerModelId: "glm-5.3-flash:cloud",
+          },
+        }),
+      ),
+    ).toEqual(current);
+    expect(() =>
+      decodeBotSettingsViewV1(
+        migrateStoredBotSettingsV1({
+          ...current,
+          assignments: [],
+          unknown: true,
+        }),
+      ),
+    ).toThrow(ConfigurationDecodeError);
+  });
+});
+
 describe("shared public identifier policy", () => {
   test("accepts the bounded cross-runtime identifier grammar", () => {
     expect(isPublicIdentifier("Bot_1.release-candidate")).toBe(true);

package/src/index.ts

@@ -136,6 +136,8 @@ export interface PackageInstallationView {
   catalogId?: string;
   /** The immutable Catalog generation `catalogId` was read from. */
   catalogGeneration?: string;
+  /** Exact non-first-party bundle admitted from the Catalog, when it carries code. */
+  contentHash?: string;
   provenance?: PackageProvenanceV1;
   /** The setup values the install carried, as GrokBot's `InstallPlugin{values}`. */
   values?: Record<string, JsonValue | ModelBindingV1>;
@@ -145,9 +147,9 @@ export interface PackageInstallationView {
  * A durable pending decision for the User: this Connection needs authorizing
  * before it will do anything again.
  *
- * It carries **no URL**, and that is the whole design. A Bot may write one —
- * `mcp_authenticate_server` does, and so does a mount that met a 401 — but a
- * redirect is minted only by an authenticated User action. A single-use
+ * It carries **no URL**, and that is the whole design. A mount that meets a
+ * 401 may write one, but a Bot has no command that requests authorization and
+ * a redirect is minted only by an authenticated User action. A single-use
  * ten-minute link stored in a projection every client reads, and replayed into
  * every transcript, would outlive the decision it belonged to and would let a
  * Bot hand its User a link it authored. The card is drawn from this record and
@@ -300,6 +302,7 @@ export type ConfigurationCommandV1 =
        */
       catalogId?: string;
       catalogGeneration?: string;
+      contentHash?: string;
       values?: Record<string, JsonValue>;
     })
   | (CommandMetaV1 & {
@@ -1190,7 +1193,7 @@ export function decodeConfigurationCommandV1(
       const command = exactCommand(
         input,
         ["packageId", "version"],
-        ["catalogId", "catalogGeneration", "values", "enabled"],
+        ["catalogId", "catalogGeneration", "contentHash", "values", "enabled"],
       );
       // A Catalog install is all three of identity, generation and (optional)
       // values or none of them: half a Catalog install would be an install
@@ -1208,6 +1211,14 @@ export function decodeConfigurationCommandV1(
           "install values require a Catalog entry",
         );
       }
+      if (
+        command.catalogId === undefined &&
+        command.contentHash !== undefined
+      ) {
+        throw new ConfigurationDecodeError(
+          "install contentHash requires a Catalog entry",
+        );
+      }
       if (
         command.enabled !== undefined &&
         typeof command.enabled !== "boolean"
@@ -1228,6 +1239,14 @@ export function decodeConfigurationCommandV1(
                 command.catalogGeneration,
                 "catalogGeneration",
               ),
+              ...(command.contentHash === undefined
+                ? {}
+                : {
+                    contentHash: compositionHash(
+                      command.contentHash,
+                      "contentHash",
+                    ),
+                  }),
             }),
         ...(command.values === undefined
           ? {}
@@ -1614,7 +1633,14 @@ function packageInstallation(value: unknown): PackageInstallationView {
     value,
     "Package installation",
     ["packageId", "version", "state"],
-    ["failure", "catalogId", "catalogGeneration", "provenance", "values"],
+    [
+      "failure",
+      "catalogId",
+      "catalogGeneration",
+      "contentHash",
+      "provenance",
+      "values",
+    ],
   );
   if (
     installation.state !== "installed" &&
@@ -1648,6 +1674,11 @@ function packageInstallation(value: unknown): PackageInstallationView {
             "catalogGeneration",
           ),
         }),
+    ...(installation.contentHash === undefined
+      ? {}
+      : {
+          contentHash: compositionHash(installation.contentHash, "contentHash"),
+        }),
     ...(installation.provenance === undefined
       ? {}
       : { provenance: installation.provenance }),
@@ -1777,6 +1808,115 @@ function schemaVersion(value: Record<string, unknown>): void {
   }
 }
 
+function storedPlainRecordV1(
+  value: unknown,
+): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function storedDataValueV1(
+  value: Record<string, unknown>,
+  key: string,
+): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}
+
+function cloneStoredRecordV1(
+  value: Record<string, unknown>,
+  changes: Readonly<Record<string, unknown>>,
+  removed: readonly string[] = [],
+): Record<string, unknown> {
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of removed) delete descriptors[key];
+  for (const [key, next] of Object.entries(changes)) {
+    const descriptor = descriptors[key];
+    descriptors[key] =
+      descriptor && "value" in descriptor
+        ? { ...descriptor, value: next }
+        : {
+            configurable: true,
+            enumerable: true,
+            value: next,
+            writable: true,
+          };
+  }
+  return Object.create(Object.getPrototypeOf(value), descriptors) as Record<
+    string,
+    unknown
+  >;
+}
+
+const PRE_ACCOUNT_WIDE_USER_FIELDS_V1 = [
+  "newBotModelTemplate",
+  "newBotModelTemplateSource",
+] as const;
+const PRE_ACCOUNT_WIDE_CONNECTION_METADATA_FIELDS_V1 = [
+  "dependentAssignments",
+] as const;
+
+/**
+ * Migrates one raw User settings record across known durable shapes before the
+ * current exact-field decoder sees it. Commit 1571b62 removed the model
+ * template and commit d6730ad removed the Connection dependency ledger along
+ * with the Assignment feature; migration drops those fields without
+ * interpreting them.
+ */
+export function migrateStoredUserSettingsV1(stored: unknown): unknown {
+  const settings = storedPlainRecordV1(stored);
+  if (!settings || storedDataValueV1(settings, "schemaVersion") !== 1) {
+    return stored;
+  }
+
+  let changed = false;
+  const removedSettingsFields = PRE_ACCOUNT_WIDE_USER_FIELDS_V1.filter((key) =>
+    Object.hasOwn(settings, key),
+  );
+  changed ||= removedSettingsFields.length > 0;
+
+  const storedConnections = storedDataValueV1(settings, "connections");
+  let connections = storedConnections;
+  if (Array.isArray(storedConnections)) {
+    let connectionsChanged = false;
+    const nextConnections = storedConnections.map((storedConnection) => {
+      const connection = storedPlainRecordV1(storedConnection);
+      if (!connection) return storedConnection;
+      const storedMetadata = storedDataValueV1(connection, "safeMetadata");
+      const metadata = storedPlainRecordV1(storedMetadata);
+      if (!metadata) return storedConnection;
+      const removedMetadataFields =
+        PRE_ACCOUNT_WIDE_CONNECTION_METADATA_FIELDS_V1.filter((key) =>
+          Object.hasOwn(metadata, key),
+        );
+      if (removedMetadataFields.length === 0) return storedConnection;
+      connectionsChanged = true;
+      const safeMetadata = cloneStoredRecordV1(
+        metadata,
+        {},
+        removedMetadataFields,
+      );
+      return cloneStoredRecordV1(connection, { safeMetadata });
+    });
+    if (connectionsChanged) {
+      changed = true;
+      connections = nextConnections;
+    }
+  }
+
+  if (!changed) return stored;
+  return cloneStoredRecordV1(
+    settings,
+    connections === storedConnections ? {} : { connections },
+    removedSettingsFields,
+  );
+}
+
 export function decodeUserSettingsViewV1(input: unknown): UserSettingsViewV1 {
   const value = exactRecord(
     input,
@@ -1896,6 +2036,35 @@ export function decodeBotSettingsViewV1(input: unknown): BotSettingsViewV1 {
   };
 }
 
+const PRE_ACCOUNT_WIDE_BOT_FIELDS_V1 = [
+  "assignments",
+  "assignmentOperations",
+  "model",
+  // Some pre-release records used this name for the same removed feature.
+  "modelAssignment",
+] as const;
+
+/**
+ * Migrates one raw Bot settings record across known durable shapes before the
+ * current exact-field decoder sees it. The removed Assignment/model fields are
+ * discarded; their presence identifies the shape that predates packageValues.
+ */
+export function migrateStoredBotSettingsV1(stored: unknown): unknown {
+  const settings = storedPlainRecordV1(stored);
+  if (!settings || storedDataValueV1(settings, "schemaVersion") !== 1) {
+    return stored;
+  }
+  const removed = PRE_ACCOUNT_WIDE_BOT_FIELDS_V1.filter((key) =>
+    Object.hasOwn(settings, key),
+  );
+  if (removed.length === 0) return stored;
+  return cloneStoredRecordV1(
+    settings,
+    Object.hasOwn(settings, "packageValues") ? {} : { packageValues: {} },
+    removed,
+  );
+}
+
 export function decodeConfigurationViewV1(input: unknown): ConfigurationViewV1 {
   const value = record(input, "configuration");
   return "botId" in value
@@ -1957,6 +2126,11 @@ const COMPOSITION_GENERATION_STATUSES_V1: readonly CompositionGenerationStatusVi
 
 export type CompositionProvenanceViewV1 =
   | { kind: "first-party" }
+  | {
+      kind: "catalog";
+      catalogId: string;
+      catalogGeneration: string;
+    }
   | { kind: "user"; userId: string; authoredAt: string }
   | {
       kind: "bot";
@@ -1971,7 +2145,14 @@ export type CompositionOriginViewV1 =
   | { kind: "bootstrap" }
   | { kind: "bot-authored"; runId: string; sessionId: string; turnId: string }
   | { kind: "user-install"; userId: string }
-  | { kind: "revert"; revertsTo: string; userId: string };
+  | { kind: "revert"; revertsTo: string; userId: string }
+  | {
+      kind: "revert";
+      revertsTo: string;
+      botId: string;
+      runId: string;
+      turnId: string;
+    };
 
 export interface CompositionMemberViewV1 {
   packageId: string;
@@ -2109,6 +2290,25 @@ function compositionProvenanceView(
     exactRecord(input, "Composition provenance", ["kind"]);
     return { kind: "first-party" };
   }
+  if (kind === "catalog") {
+    const value = exactRecord(input, "Composition provenance", [
+      "kind",
+      "catalogId",
+      "catalogGeneration",
+    ]);
+    return {
+      kind: "catalog",
+      catalogId: identifier(
+        value.catalogId,
+        "Composition provenance catalogId",
+      ),
+      catalogGeneration: text(
+        value.catalogGeneration,
+        "Composition provenance catalogGeneration",
+        256,
+      ),
+    };
+  }
   if (kind === "user") {
     const value = exactRecord(input, "Composition provenance", [
       "kind",
@@ -2176,18 +2376,32 @@ function compositionOriginView(input: unknown): CompositionOriginViewV1 {
     };
   }
   if (kind === "revert") {
-    const value = exactRecord(input, "Composition origin", [
+    const value = record(input, "Composition origin");
+    const revertsTo = decodeCompositionGenerationIdV1(
+      value.revertsTo,
+      "Composition origin revertsTo",
+    );
+    if (Object.hasOwn(value, "userId")) {
+      exactRecord(input, "Composition origin", ["kind", "revertsTo", "userId"]);
+      return {
+        kind: "revert",
+        revertsTo,
+        userId: text(value.userId, "Composition origin userId", 256),
+      };
+    }
+    const bot = exactRecord(input, "Composition origin", [
       "kind",
       "revertsTo",
-      "userId",
+      "botId",
+      "runId",
+      "turnId",
     ]);
     return {
       kind: "revert",
-      revertsTo: decodeCompositionGenerationIdV1(
-        value.revertsTo,
-        "Composition origin revertsTo",
-      ),
-      userId: text(value.userId, "Composition origin userId", 256),
+      revertsTo,
+      botId: decodeBotIdV1(bot.botId),
+      runId: text(bot.runId, "Composition origin runId", 128),
+      turnId: text(bot.turnId, "Composition origin turnId", 128),
     };
   }
   throw new ConfigurationDecodeError("Composition origin kind is invalid");