@frockbot/configuration-core 0.1.3 → 0.1.4

package/src/package-settings.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import type { PackageSettingDefinition } from "@frockbot/kernel-composition";
 import {
+  decodeInstalledPackageSettingsPatchV1,
+  decodeModelBindingV1,
   decodePackageSettingsPatchV1,
   decodePackageSettingValuesV1,
   emptyPackageSettingValuesV1,
@@ -128,6 +130,104 @@ describe("the Package setting values codec", () => {
     expect(() =>
       decodePackageSettingsPatchV1(botScoped, { tone: "terse" }),
     ).toThrow(/not a User-level setting/);
+    expect(
+      decodePackageSettingsPatchV1(botScoped, { tone: "terse" }, "bot"),
+    ).toEqual({ tone: "terse" });
+  });
+
+  test("validates the model role's exact structured value at either scope", () => {
+    const modelRole = [
+      definition({
+        id: "model",
+        role: "model",
+        scopes: ["user", "bot"],
+        schema: {
+          type: "object",
+          properties: {
+            connectionId: { type: "string" },
+            providerModelId: { type: "string" },
+          },
+          required: ["connectionId", "providerModelId"],
+          additionalProperties: false,
+        },
+      }),
+    ];
+    const model = {
+      connectionId: "ollama-work",
+      providerModelId: "glm-5.3-flash:cloud",
+    };
+    expect(decodePackageSettingsPatchV1(modelRole, { model })).toEqual({
+      model,
+    });
+    expect(decodePackageSettingsPatchV1(modelRole, { model }, "bot")).toEqual({
+      model,
+    });
+    expect(() =>
+      decodePackageSettingsPatchV1(modelRole, {
+        model: { ...model, extra: true },
+      }),
+    ).toThrow(/invalid fields/);
+  });
+
+  test("rejects hidden, symbol, inherited, and prototype-shaped fields", () => {
+    const hidden = { verbose: true };
+    Object.defineProperty(hidden, "secret", { value: "hidden" });
+    expect(() => decodePackageSettingsPatchV1(declared, hidden)).toThrow(
+      /invalid fields/,
+    );
+
+    const symbol = { verbose: true, [Symbol("extra")]: true };
+    expect(() => decodePackageSettingsPatchV1(declared, symbol)).toThrow(
+      /invalid fields/,
+    );
+
+    const inherited = Object.create({ verbose: true });
+    expect(() => decodePackageSettingsPatchV1(declared, inherited)).toThrow(
+      /plain object|inherited fields/,
+    );
+
+    expect(() =>
+      decodeModelBindingV1({
+        connectionId: "constructor",
+        providerModelId: "model-1",
+      }),
+    ).toThrow(/connectionId is invalid/);
+  });
+
+  test("validates a Bot command against the installed manifest version", () => {
+    const installations = [{ packageId: "preferences", version: "1.0.0" }];
+    const packages = [
+      { packageId: "preferences", version: "1.0.0", settings: declared },
+    ];
+    const validate = (packageId: string, values: unknown) =>
+      decodeInstalledPackageSettingsPatchV1({
+        packageId,
+        values,
+        scope: "bot",
+        installations,
+        packages,
+      });
+    const botSetting = [
+      definition({ id: "tone", scopes: ["bot"], schema: { type: "string" } }),
+    ];
+    packages[0] = {
+      packageId: "preferences",
+      version: "1.0.0",
+      settings: botSetting,
+    };
+
+    expect(validate("preferences", { tone: "terse" })).toEqual({
+      tone: "terse",
+    });
+    expect(() => validate("missing", { tone: "terse" })).toThrow(
+      'Package "missing" is not installed',
+    );
+    expect(() => validate("preferences", { unknown: "value" })).toThrow(
+      /not declared/,
+    );
+    expect(() => validate("preferences", { tone: 42 })).toThrow(
+      /must be a string/,
+    );
   });
 
   test("refuses a secret, whatever its schema says", () => {

package/src/package-settings.ts

@@ -1,5 +1,5 @@
 // Package-level setting *values*: the durable configuration one installed
-// Package carries for one User.
+// Package carries for one User or one of that User's Bots.
 //
 // A manifest declares `configuration.settings` — the knobs a Package offers —
 // and until now nothing anywhere held a value for one, so every Package read
@@ -7,10 +7,10 @@
 // command and that durable state.
 //
 // WHAT BELONGS HERE, AND WHAT DOES NOT. A Package-level setting is
-// configuration scoped to the User: a default model, a ceiling, an endpoint
-// root. A *secret* never is. A credential reaches the keyring through a
-// Connection and only through one, so a definition that declares itself secret
-// is refused here with that answer rather than stored.
+// configuration scoped to the User or Bot: a model choice, a ceiling, an
+// endpoint root. A *secret* never is. A credential reaches the keyring through
+// a Connection and only through one, so a definition that declares itself
+// secret is refused here with that answer rather than stored.
 //
 // STRICT IN, LENIENT OUT. A write is validated against the exact schema the
 // Package declared: an unknown setting id, a wrong type, a value outside its
@@ -26,23 +26,30 @@ import type {
   PackageSettingSchemaValue,
 } from "@frockbot/kernel-composition";
 import { ConfigurationDecodeError } from "./errors.js";
-import { isPublicIdentifier } from "./identifiers.js";
+import { isConnectionIdentifier, isPublicIdentifier } from "./identifiers.js";
 
 /**
- * What one Package-level setting may hold. Scalars only: a Package-level value
- * is a knob a User turns on a generated form, and an object or an array is a
- * document, which belongs in a Package's own durable state rather than in the
- * User's settings bag.
+ * The provider-neutral model identity selected by a model-role Package
+ * setting. This is a reference to a Connection, never a credential.
  */
-export type PackageSettingValueV1 = string | number | boolean;
+export interface ModelBindingV1 {
+  connectionId: string;
+  providerModelId: string;
+}
 
-/** The durable record of one installed Package's setting values. */
+/**
+ * What one Package-level setting may hold. Ordinary settings remain scalars;
+ * ADR 0019 adds exactly one structured exception, the model role's binding.
+ */
+export type PackageSettingValueV1 = string | number | boolean | ModelBindingV1;
+
+/** The durable record of one installed Package's setting values at one scope. */
 export interface PackageSettingValuesV1 {
   schemaVersion: 1;
   values: Record<string, PackageSettingValueV1>;
 }
 
-/** The durable per-User ceiling on how many values one Package may hold. */
+/** The durable per-scope ceiling on how many values one Package may hold. */
 export const MAX_PACKAGE_SETTINGS_V1 = 32;
 
 /** The ceiling on one text value, whatever the schema's own `maxLength`. */
@@ -57,7 +64,63 @@ function record(value: unknown, label: string): Record<string, unknown> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new ConfigurationDecodeError(`${label} must be an object`);
   }
-  return value as Record<string, unknown>;
+  const candidate = value as Record<string, unknown>;
+  const prototype = Object.getPrototypeOf(candidate);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new ConfigurationDecodeError(`${label} must be a plain object`);
+  }
+  for (const key in candidate) {
+    if (!Object.hasOwn(candidate, key)) {
+      throw new ConfigurationDecodeError(`${label} has inherited fields`);
+    }
+  }
+  for (const key of Reflect.ownKeys(candidate)) {
+    const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+    if (
+      typeof key !== "string" ||
+      !descriptor ||
+      !("value" in descriptor) ||
+      !descriptor.enumerable
+    ) {
+      throw new ConfigurationDecodeError(`${label} has invalid fields`);
+    }
+  }
+  return candidate;
+}
+
+function boundedText(value: unknown, label: string, maximum: number): string {
+  if (typeof value !== "string") {
+    throw new ConfigurationDecodeError(`${label} must be a string`);
+  }
+  const normalized = value.trim();
+  if (!normalized || normalized.length > maximum) {
+    throw new ConfigurationDecodeError(`${label} is invalid`);
+  }
+  return normalized;
+}
+
+/** The exact model binding DTO, decoded wherever it crosses a durable seam. */
+export function decodeModelBindingV1(value: unknown): ModelBindingV1 {
+  const binding = record(value, "model");
+  const keys = Reflect.ownKeys(binding);
+  if (
+    keys.length !== 2 ||
+    !Object.hasOwn(binding, "connectionId") ||
+    !Object.hasOwn(binding, "providerModelId")
+  ) {
+    throw new ConfigurationDecodeError("model has invalid fields");
+  }
+  if (!isConnectionIdentifier(binding.connectionId)) {
+    throw new ConfigurationDecodeError("model.connectionId is invalid");
+  }
+  return {
+    connectionId: binding.connectionId,
+    providerModelId: boundedText(
+      binding.providerModelId,
+      "model.providerModelId",
+      256,
+    ),
+  };
 }
 
 /**
@@ -169,13 +232,13 @@ function checkNumber(
  * One value, against the definition its Package declared.
  *
  * The scope check is the constitution's, not a convenience: Package
- * availability is User-level, so a User-level bag holds a `user`-scoped
- * setting. A `connection`-scoped one belongs to a Connection and a `bot`-only
- * one to a Bot, and neither has a home here.
+ * availability is User-level, while each value still has the manifest scope
+ * that owns it. A `connection`-scoped value always belongs to a Connection.
  */
 export function decodePackageSettingValueV1(
   definition: PackageSettingDefinition,
   value: unknown,
+  scope: "user" | "bot" = "user",
 ): PackageSettingValueV1 {
   const settingId = definition.id;
   // Defensive, and deliberately not dead: `PackageSettingDefinition` carries no
@@ -187,13 +250,14 @@ export function decodePackageSettingValueV1(
       `Package setting "${settingId}" is a secret: use a Connection`,
     );
   }
-  if (!definition.scopes.includes("user")) {
+  if (!definition.scopes.includes(scope)) {
     throw new ConfigurationDecodeError(
       definition.scopes.includes("connection")
         ? `Package setting "${settingId}" is Connection-scoped: use a Connection`
-        : `Package setting "${settingId}" is not a User-level setting`,
+        : `Package setting "${settingId}" is not a ${scope === "user" ? "User" : "Bot"}-level setting`,
     );
   }
+  if (definition.role === "model") return decodeModelBindingV1(value);
   const schema = definition.schema;
   const declared = scalarType(schema, settingId);
   if (
@@ -250,13 +314,14 @@ function definitionsById(
 }
 
 /**
- * The `values` a `user/set-package-settings` command carries: a *partial*
- * update, so only the ids it names are decoded. Every one of them must be a
- * setting the Package declares at User scope.
+ * The `values` a User- or Bot-scoped Package settings command carries: a
+ * *partial* update, so only the ids it names are decoded. Every one must be a
+ * setting the installed Package version declares at the requested scope.
  */
 export function decodePackageSettingsPatchV1(
   definitions: readonly PackageSettingDefinition[],
   input: unknown,
+  scope: "user" | "bot" = "user",
 ): Record<string, PackageSettingValueV1> {
   const values = record(input, "values");
   const entries = Object.entries(values);
@@ -264,7 +329,7 @@ export function decodePackageSettingsPatchV1(
     throw new ConfigurationDecodeError("Package settings are too many");
   }
   const declared = definitionsById(definitions);
-  const decoded: Record<string, PackageSettingValueV1> = {};
+  const decoded: Array<[string, PackageSettingValueV1]> = [];
   for (const [settingId, value] of entries) {
     if (!isPublicIdentifier(settingId)) {
       throw new ConfigurationDecodeError("Package setting id is invalid");
@@ -275,15 +340,129 @@ export function decodePackageSettingsPatchV1(
         `Package setting "${settingId}" is not declared by this Package`,
       );
     }
-    decoded[settingId] = decodePackageSettingValueV1(definition, value);
+    decoded.push([
+      settingId,
+      decodePackageSettingValueV1(definition, value, scope),
+    ]);
+  }
+  return Object.fromEntries(decoded);
+}
+
+/** A non-empty list of declared setting ids to remove at one scope. */
+export function decodePackageSettingIdsV1(
+  definitions: readonly PackageSettingDefinition[],
+  input: unknown,
+  scope: "user" | "bot" = "user",
+): string[] {
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new ConfigurationDecodeError("unset names no setting");
+  }
+  if (input.length > MAX_PACKAGE_SETTINGS_V1) {
+    throw new ConfigurationDecodeError("unset is too large");
+  }
+  const declared = definitionsById(definitions);
+  const decoded = input.map((settingId) => {
+    if (!isPublicIdentifier(settingId)) {
+      throw new ConfigurationDecodeError("Package setting id is invalid");
+    }
+    const definition = declared.get(settingId);
+    if (!definition) {
+      throw new ConfigurationDecodeError(
+        `Package setting "${settingId}" is not declared by this Package`,
+      );
+    }
+    if (!definition.scopes.includes(scope)) {
+      throw new ConfigurationDecodeError(
+        `Package setting "${settingId}" is not a ${scope === "user" ? "User" : "Bot"}-level setting`,
+      );
+    }
+    return settingId;
+  });
+  if (new Set(decoded).size !== decoded.length) {
+    throw new ConfigurationDecodeError("unset repeats a setting");
   }
   return decoded;
 }
 
+export interface InstalledPackageSettingsV1 {
+  packageId: string;
+  version: string;
+}
+
+export interface PackageSettingsDefinitionV1 {
+  packageId: string;
+  version: string;
+  settings: readonly PackageSettingDefinition[];
+}
+
+/**
+ * The installed-version lookup shared by the User and Bot authorities before
+ * either merges a partial settings command. The lookup and schema validation
+ * are one fail-closed operation, so neither writer can accidentally validate
+ * against a catalog version the User did not install.
+ */
+export function decodeInstalledPackageSettingsPatchV1(input: {
+  packageId: string;
+  values: unknown;
+  scope: "user" | "bot";
+  installations: readonly InstalledPackageSettingsV1[];
+  packages: readonly PackageSettingsDefinitionV1[];
+}): Record<string, PackageSettingValueV1> {
+  const installation = input.installations.find(
+    (candidate) => candidate.packageId === input.packageId,
+  );
+  if (!installation) {
+    throw new ConfigurationDecodeError(
+      `Package "${input.packageId}" is not installed`,
+    );
+  }
+  const pkg = input.packages.find(
+    (candidate) =>
+      candidate.packageId === installation.packageId &&
+      candidate.version === installation.version,
+  );
+  if (!pkg) {
+    throw new ConfigurationDecodeError(
+      `Installed Package "${installation.packageId}" version "${installation.version}" has no manifest`,
+    );
+  }
+  return decodePackageSettingsPatchV1(pkg.settings, input.values, input.scope);
+}
+
+/** Installed-version lookup and validation for a settings deletion. */
+export function decodeInstalledPackageSettingIdsV1(input: {
+  packageId: string;
+  unset: unknown;
+  scope: "user" | "bot";
+  installations: readonly InstalledPackageSettingsV1[];
+  packages: readonly PackageSettingsDefinitionV1[];
+}): string[] {
+  const installation = input.installations.find(
+    (candidate) => candidate.packageId === input.packageId,
+  );
+  if (!installation) {
+    throw new ConfigurationDecodeError(
+      `Package "${input.packageId}" is not installed`,
+    );
+  }
+  const pkg = input.packages.find(
+    (candidate) =>
+      candidate.packageId === installation.packageId &&
+      candidate.version === installation.version,
+  );
+  if (!pkg) {
+    throw new ConfigurationDecodeError(
+      `Installed Package "${installation.packageId}" version "${installation.version}" has no manifest`,
+    );
+  }
+  return decodePackageSettingIdsV1(pkg.settings, input.unset, input.scope);
+}
+
 /** The durable record, decoded whole. */
 export function decodePackageSettingValuesV1(
   definitions: readonly PackageSettingDefinition[],
   input: unknown,
+  scope: "user" | "bot" = "user",
 ): PackageSettingValuesV1 {
   const value = record(input, "Package setting values");
   if (value.schemaVersion !== 1) {
@@ -292,15 +471,15 @@ export function decodePackageSettingValuesV1(
     );
   }
   if (
-    Object.keys(value).some(
-      (key) => key !== "schemaVersion" && key !== "values",
-    )
+    Reflect.ownKeys(value).length !== 2 ||
+    !Object.hasOwn(value, "schemaVersion") ||
+    !Object.hasOwn(value, "values")
   ) {
     throw new ConfigurationDecodeError("Package setting values are invalid");
   }
   return {
     schemaVersion: 1,
-    values: decodePackageSettingsPatchV1(definitions, value.values),
+    values: decodePackageSettingsPatchV1(definitions, value.values, scope),
   };
 }
 
@@ -317,6 +496,7 @@ export function decodePackageSettingValuesV1(
 export function resolvePackageSettingValuesV1(
   definitions: readonly PackageSettingDefinition[],
   stored: Readonly<Record<string, unknown>> | undefined,
+  scope: "user" | "bot" = "user",
 ): Record<string, PackageSettingValueV1> {
   if (!stored) return {};
   const resolved: Record<string, PackageSettingValueV1> = {};
@@ -326,6 +506,7 @@ export function resolvePackageSettingValuesV1(
       resolved[definition.id] = decodePackageSettingValueV1(
         definition,
         stored[definition.id],
+        scope,
       );
     } catch {
       continue;