@frockbot/kernel-composition 0.0.0 → 0.1.0

package/src/compiler.ts

@@ -0,0 +1,288 @@
+import { decodeFrockBotManifest, type FrockBotManifest } from "./manifest.ts";
+import { satisfies, valid } from "semver";
+
+export type JsonValue =
+  null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+export interface ApplicationPackageSelection {
+  specifier: string;
+  version: string;
+  config?: JsonValue;
+  grants: string[];
+}
+
+export interface ApplicationSource {
+  schemaVersion: 1;
+  packages: ApplicationPackageSelection[];
+}
+
+export interface ResolvedPackageSource {
+  specifier: string;
+  manifest: unknown;
+}
+
+export type ApplicationPackageResolver = (
+  specifier: string,
+  version: string,
+) => Promise<ResolvedPackageSource>;
+
+export type ApplicationPackageDeclarationResolver = (
+  specifier: string,
+  version: string,
+) => ResolvedPackageSource;
+
+export interface CompiledPackage {
+  id: string;
+  specifier: string;
+  version: string;
+  config: JsonValue;
+  grants: string[];
+  manifest: FrockBotManifest;
+}
+
+export interface ApplicationPlan {
+  schemaVersion: 1;
+  applicationHash: string;
+  packages: CompiledPackage[];
+  contributions: {
+    backend: string[];
+    runtime: string[];
+    client: string[];
+    desktop: string[];
+    mobile: string[];
+  };
+}
+
+export type ApplicationDeclarationPlan = Omit<
+  ApplicationPlan,
+  "applicationHash"
+>;
+
+export interface CompileApplicationOptions {
+  frockbotVersion: string;
+}
+
+export function canonicalJson(value: unknown): string {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error("application data must be finite");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value !== "object") {
+    throw new Error("application data must be JSON serializable");
+  }
+  return `{${Object.entries(value)
+    .filter(([, entry]) => entry !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
+    .join(",")}}`;
+}
+
+export async function sha256(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(value),
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function assertVersion(version: string, label: string): void {
+  if (!valid(version))
+    throw new Error(`${label} must be a valid semver version`);
+}
+
+function validateGrants(pkg: CompiledPackage): void {
+  const grants = new Set(pkg.grants);
+  if (grants.size !== pkg.grants.length) {
+    throw new Error(`package "${pkg.id}" contains duplicate grants`);
+  }
+  for (const permission of pkg.manifest.permissions) {
+    if (!grants.has(permission)) {
+      throw new Error(`package "${pkg.id}" is missing grant "${permission}"`);
+    }
+  }
+  for (const grant of grants) {
+    if (!pkg.manifest.permissions.includes(grant)) {
+      throw new Error(
+        `package "${pkg.id}" received undeclared grant "${grant}"`,
+      );
+    }
+  }
+}
+
+function orderedPackages(
+  packages: Map<string, CompiledPackage>,
+): CompiledPackage[] {
+  const order: CompiledPackage[] = [];
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+
+  const visit = (id: string): void => {
+    if (visited.has(id)) return;
+    if (visiting.has(id))
+      throw new Error(`package dependency cycle includes "${id}"`);
+    const pkg = packages.get(id);
+    if (!pkg) throw new Error(`package "${id}" is missing`);
+    visiting.add(id);
+    for (const [dependencyId, range] of Object.entries(
+      pkg.manifest.dependencies,
+    ).sort(([left], [right]) => left.localeCompare(right))) {
+      const dependency = packages.get(dependencyId);
+      if (!dependency) {
+        throw new Error(
+          `package "${pkg.id}" requires missing package "${dependencyId}"`,
+        );
+      }
+      if (!satisfies(dependency.version, range)) {
+        throw new Error(
+          `package "${pkg.id}" requires ${dependencyId}@${range}, received ${dependency.version}`,
+        );
+      }
+      visit(dependencyId);
+    }
+    visiting.delete(id);
+    visited.add(id);
+    order.push(pkg);
+  };
+
+  for (const id of [...packages.keys()].sort()) visit(id);
+  return order;
+}
+
+function validateClientComposition(packages: readonly CompiledPackage[]): void {
+  const clients = packages.flatMap((pkg) => {
+    const client = pkg.manifest.contributions.client;
+    return client ? [{ id: pkg.id, client }] : [];
+  });
+  const roots = clients.flatMap(({ id, client }) =>
+    client.mounts.filter((mount) => mount.slot === "root").map(() => id),
+  );
+  if (roots.length > 1) {
+    throw new Error(`multiple client roots declared by: ${roots.join(", ")}`);
+  }
+  const outlets = new Set(clients.flatMap(({ client }) => client.outlets));
+  for (const { id, client } of clients) {
+    for (const mount of client.mounts) {
+      if (mount.slot !== "root" && !outlets.has(mount.slot)) {
+        throw new Error(
+          `package "${id}" mounts undeclared client slot "${mount.slot}"`,
+        );
+      }
+    }
+  }
+}
+
+export function compileApplicationDeclarations(
+  source: ApplicationSource,
+  resolvePackage: ApplicationPackageDeclarationResolver,
+  options: CompileApplicationOptions,
+): ApplicationDeclarationPlan {
+  if (source.schemaVersion !== 1) {
+    throw new Error("unsupported application source version");
+  }
+  assertVersion(options.frockbotVersion, "FrockBot version");
+  const byId = new Map<string, CompiledPackage>();
+  const specifiers = new Set<string>();
+
+  for (const selection of source.packages) {
+    if (specifiers.has(selection.specifier)) {
+      throw new Error(`duplicate package specifier "${selection.specifier}"`);
+    }
+    specifiers.add(selection.specifier);
+    assertVersion(
+      selection.version,
+      `package "${selection.specifier}" version`,
+    );
+    const resolved = resolvePackage(selection.specifier, selection.version);
+    if (resolved.specifier !== selection.specifier) {
+      throw new Error(
+        `resolver returned the wrong package for "${selection.specifier}"`,
+      );
+    }
+    const manifest = decodeFrockBotManifest(resolved.manifest);
+    if (manifest.version !== selection.version) {
+      throw new Error(
+        `package "${manifest.id}" manifest version does not match selection`,
+      );
+    }
+    if (!satisfies(options.frockbotVersion, manifest.compatibility.frockbot)) {
+      throw new Error(
+        `package "${manifest.id}" is incompatible with FrockBot ${options.frockbotVersion}`,
+      );
+    }
+    if (byId.has(manifest.id)) {
+      throw new Error(`duplicate package id "${manifest.id}"`);
+    }
+    const pkg: CompiledPackage = {
+      id: manifest.id,
+      specifier: selection.specifier,
+      version: selection.version,
+      config: selection.config ?? null,
+      grants: [...selection.grants].sort(),
+      manifest,
+    };
+    validateGrants(pkg);
+    byId.set(pkg.id, pkg);
+  }
+
+  const packages = orderedPackages(byId);
+  validateClientComposition(packages);
+  return {
+    schemaVersion: 1 as const,
+    packages,
+    contributions: {
+      backend: packages
+        .filter((pkg) => pkg.manifest.contributions.backend)
+        .map((pkg) => pkg.id),
+      runtime: packages
+        .filter((pkg) => pkg.manifest.contributions.runtime)
+        .map((pkg) => pkg.id),
+      client: packages
+        .filter((pkg) => pkg.manifest.contributions.client)
+        .map((pkg) => pkg.id),
+      desktop: packages
+        .filter((pkg) => pkg.manifest.contributions.desktop)
+        .map((pkg) => pkg.id),
+      mobile: packages
+        .filter((pkg) => pkg.manifest.contributions.mobile)
+        .map((pkg) => pkg.id),
+    },
+  };
+}
+
+export async function compileApplicationPlan(
+  source: ApplicationSource,
+  resolvePackage: ApplicationPackageResolver,
+  options: CompileApplicationOptions,
+): Promise<ApplicationPlan> {
+  const resolved = new Map<string, ResolvedPackageSource>();
+  for (const selection of source.packages) {
+    resolved.set(
+      `${selection.specifier}\0${selection.version}`,
+      await resolvePackage(selection.specifier, selection.version),
+    );
+  }
+  const unsigned = compileApplicationDeclarations(
+    source,
+    (specifier, version) => {
+      const pkg = resolved.get(`${specifier}\0${version}`);
+      if (!pkg) throw new Error(`unknown package: ${specifier}`);
+      return pkg;
+    },
+    options,
+  );
+  return {
+    ...unsigned,
+    applicationHash: await sha256(canonicalJson(unsigned)),
+  };
+}

package/src/generation.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test";
+import {
+  assertCompositionArtifactSetHashV1,
+  bootstrapGeneration,
+  compositionArtifactSetHashV1,
+  decodeCompositionGenerationV1,
+  type CompositionGenerationV1,
+} from "./generation.ts";
+
+const CREATED_AT = "2026-08-31T00:00:00.000Z";
+
+function manifest(id: string) {
+  return { id, version: "0.0.1", displayName: id };
+}
+
+function bootstrap(): Promise<CompositionGenerationV1> {
+  return bootstrapGeneration(
+    [
+      {
+        packageId: "tools",
+        specifier: "@frockbot/plugin-tools",
+        version: "0.0.1",
+        manifest: manifest("tools"),
+      },
+      {
+        packageId: "models",
+        specifier: "@frockbot/plugin-models",
+        version: "0.0.1",
+        manifest: manifest("models"),
+      },
+    ],
+    { createdAt: CREATED_AT },
+  );
+}
+
+describe("Composition generation v1", () => {
+  test("bootstraps one first-party generation from declared Contributions", async () => {
+    const generation = await bootstrap();
+
+    expect(generation.origin).toEqual({ kind: "bootstrap" });
+    expect(generation.status).toBe("pending");
+    expect(generation.createdAt).toBe(CREATED_AT);
+    expect(generation.members.map((member) => member.packageId)).toEqual([
+      "models",
+      "tools",
+    ]);
+    expect(
+      generation.members.every(
+        (member) =>
+          member.provenance.kind === "first-party" &&
+          member.artifact === undefined,
+      ),
+    ).toBe(true);
+    expect(generation.generationId.startsWith(`${CREATED_AT}:`)).toBe(true);
+    await assertCompositionArtifactSetHashV1(generation);
+  });
+
+  test("keys the generation by its resolved artifact set", async () => {
+    const first = await bootstrap();
+    const second = await bootstrap();
+
+    expect(second.artifactSetHash).toBe(first.artifactSetHash);
+    expect(second.generationId).toBe(first.generationId);
+    expect(
+      await compositionArtifactSetHashV1([...first.members].reverse()),
+    ).toBe(first.artifactSetHash);
+  });
+
+  test("the v1 codec rejects unknown fields", async () => {
+    const generation = await bootstrap();
+
+    expect(() =>
+      decodeCompositionGenerationV1({ ...generation, extra: true }),
+    ).toThrow("composition generation has invalid fields");
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...generation,
+        members: [{ ...generation.members[0], extra: true }],
+      }),
+    ).toThrow("composition generation.members[0] has invalid fields");
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...generation,
+        origin: { kind: "bootstrap", userId: "user-1" },
+      }),
+    ).toThrow("composition generation.origin has invalid fields");
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...generation,
+        members: [
+          {
+            ...generation.members[0],
+            provenance: {
+              ...generation.members[0]!.provenance,
+              authoredAt: CREATED_AT,
+            },
+          },
+        ],
+      }),
+    ).toThrow(
+      "composition generation.members[0].provenance has invalid fields",
+    );
+  });
+
+  test("the v1 codec rejects malformed hashes and mismatched provenance", async () => {
+    const generation = await bootstrap();
+
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...generation,
+        artifactSetHash: "not-a-digest",
+      }),
+    ).toThrow("composition generation.artifactSetHash must be a sha-256 hex");
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...generation,
+        artifactSetHash: generation.artifactSetHash.toUpperCase(),
+      }),
+    ).toThrow("composition generation.artifactSetHash must be a sha-256 hex");
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...generation,
+        members: [{ ...generation.members[0], manifestHash: "abc" }],
+      }),
+    ).toThrow("composition generation.members[0].manifestHash");
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...generation,
+        members: [{ ...generation.members[0], version: "9.9.9" }],
+      }),
+    ).toThrow("does not match its member");
+    expect(() =>
+      decodeCompositionGenerationV1({ ...generation, status: "mounted" }),
+    ).toThrow("composition generation.status is invalid");
+    expect(() =>
+      decodeCompositionGenerationV1({ ...generation, schemaVersion: 2 }),
+    ).toThrow("composition generation.schemaVersion is unsupported");
+  });
+
+  test("rejects a generation whose recorded artifact set hash is wrong", async () => {
+    const generation = await bootstrap();
+
+    await expect(
+      assertCompositionArtifactSetHashV1({
+        ...generation,
+        artifactSetHash: "b".repeat(64),
+      }),
+    ).rejects.toThrow("mismatched artifact set hash");
+  });
+
+  test("decodes an isolate member with its content-addressed artifact", async () => {
+    const generation = await bootstrap();
+    const members = [
+      {
+        packageId: "authored",
+        specifier: "bot://authored",
+        version: "0.0.1",
+        manifestHash: "c".repeat(64),
+        provenance: {
+          kind: "bot" as const,
+          packageId: "authored",
+          version: "0.0.1",
+          botId: "primary",
+          sessionId: "user-1:primary",
+          turnId: "turn-1",
+          runId: "run-1",
+          authoredAt: CREATED_AT,
+        },
+        artifact: {
+          contentHash: "d".repeat(64),
+          size: 1024,
+          mediaType: "application/javascript" as const,
+          bundlerVersion: "0.2.3",
+        },
+      },
+    ];
+    const decoded = decodeCompositionGenerationV1({
+      ...generation,
+      artifactSetHash: await compositionArtifactSetHashV1(members),
+      members,
+      origin: {
+        kind: "bot-authored",
+        runId: "run-1",
+        sessionId: "user-1:primary",
+        turnId: "turn-1",
+      },
+    });
+
+    expect(decoded.members[0]?.artifact?.contentHash).toBe("d".repeat(64));
+    await assertCompositionArtifactSetHashV1(decoded);
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...decoded,
+        members: [
+          {
+            ...members[0],
+            artifact: { ...members[0]!.artifact, mediaType: "text/plain" },
+          },
+        ],
+      }),
+    ).toThrow("mediaType is invalid");
+  });
+});