@frockbot/kernel-composition 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-composition",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "exports": {
@@ -20,7 +20,7 @@
   "dependencies": {
     "cordis": "4.0.0-rc.8",
     "semver": "7.8.5",
-    "@frockbot/kernel-contracts": "0.3.0"
+    "@frockbot/kernel-contracts": "0.3.2"
   },
   "devDependencies": {
     "@types/bun": "1.4.0",

package/src/compiler.test.ts

@@ -245,3 +245,53 @@ describe("compileApplicationPlan", () => {
     );
   });
 });
+
+describe("artifact-backed application members", () => {
+  const artifact = {
+    contentHash: "a".repeat(64),
+    size: 128,
+    mediaType: "application/javascript" as const,
+    bundlerVersion: "frockbot-bundler@1",
+  };
+
+  test("carries a declared artifact onto the compiled package", () => {
+    const declarations = compileApplicationDeclarations(
+      {
+        schemaVersion: 1,
+        packages: [{ ...selection("@fixture/base"), artifact }],
+      },
+      (specifier) => ({ specifier, manifest: runtimeManifest("base") }),
+      { frockbotVersion: "1.0.0" },
+    );
+
+    expect(declarations.packages[0]?.artifact).toEqual(artifact);
+  });
+
+  test("leaves a member with no artifact first-party in-process", () => {
+    const declarations = compileApplicationDeclarations(
+      { schemaVersion: 1, packages: [selection("@fixture/base")] },
+      (specifier) => ({ specifier, manifest: runtimeManifest("base") }),
+      { frockbotVersion: "1.0.0" },
+    );
+
+    expect(declarations.packages[0]).not.toHaveProperty("artifact");
+  });
+
+  test("refuses an artifact the loader could not fetch", () => {
+    expect(() =>
+      compileApplicationDeclarations(
+        {
+          schemaVersion: 1,
+          packages: [
+            {
+              ...selection("@fixture/base"),
+              artifact: { ...artifact, contentHash: "nope" },
+            },
+          ],
+        },
+        (specifier) => ({ specifier, manifest: runtimeManifest("base") }),
+        { frockbotVersion: "1.0.0" },
+      ),
+    ).toThrow(/artifact.contentHash/);
+  });
+});

package/src/compiler.ts

@@ -3,6 +3,7 @@ import {
   isClientIframeContribution,
   type FrockBotManifest,
 } from "./manifest.ts";
+import { decodeArtifactRefV1, type ArtifactRefV1 } from "./generation.ts";
 import { satisfies, valid } from "semver";
 
 export type JsonValue =
@@ -13,6 +14,18 @@ export interface ApplicationPackageSelection {
   version: string;
   config?: JsonValue;
   grants: string[];
+  /**
+   * The immutable module bytes this member loads from.
+   *
+   * Absent ⇒ first-party, in-process: the application resolves the member's
+   * Contributions from its own Contribution table, which is how every member
+   * of the foundation application works today. Present ⇒ the member loads
+   * through the isolate host like a Bot-authored Package, even though its
+   * provenance is first-party — the shape ADR 0022 gives the Applets Package.
+   * Declaring one changes nothing about how the plan is compiled; it only
+   * records that the code is not in this bundle.
+   */
+  artifact?: ArtifactRefV1;
 }
 
 export interface ApplicationSource {
@@ -42,6 +55,8 @@ export interface CompiledPackage {
   config: JsonValue;
   grants: string[];
   manifest: FrockBotManifest;
+  /** Absent ⇒ first-party in-process; present ⇒ loaded from the artifact. */
+  artifact?: ArtifactRefV1;
 }
 
 export interface ApplicationPlan {
@@ -233,6 +248,13 @@ export function compileApplicationDeclarations(
     if (byId.has(manifest.id)) {
       throw new Error(`duplicate package id "${manifest.id}"`);
     }
+    const artifact =
+      selection.artifact === undefined
+        ? undefined
+        : decodeArtifactRefV1(
+            selection.artifact,
+            `package "${selection.specifier}" artifact`,
+          );
     const pkg: CompiledPackage = {
       id: manifest.id,
       specifier: selection.specifier,
@@ -240,6 +262,7 @@ export function compileApplicationDeclarations(
       config: selection.config ?? null,
       grants: [...selection.grants].sort(),
       manifest,
+      ...(artifact === undefined ? {} : { artifact }),
     };
     validateGrants(pkg);
     byId.set(pkg.id, pkg);

package/src/generation.ts

@@ -74,6 +74,62 @@ export type CompositionOriginV1 =
       turnId: string;
     };
 
+/**
+ * An Applet's tools inside one Bot's pinned Composition (ADR 0022 decision 4).
+ *
+ * Not a Package member: an Applet contributes no module to the Bot's isolate
+ * set, and a Bot can neither author, install, nor remove one. It follows the
+ * User's Applet directory, and it is recorded here so every admitted Turn
+ * records exactly which Applet generation's tools it ran under — a published
+ * generation activates at the next admitted Turn, and an in-flight Turn keeps
+ * the set it pinned. A tool call routes to the Applet Durable Object, which
+ * forwards it to the facet; the facet's storage is never Composition.
+ */
+export interface CompositionAppletMemberV1 {
+  kind: "applet";
+  appletId: string;
+  generationId: string;
+  tools: CompositionAppletToolV1[];
+  provenance: PackageProvenanceV1;
+}
+
+/**
+ * Plain JSON, spelled out.
+ *
+ * A Composition generation crosses a Durable Object RPC boundary, and `unknown`
+ * is not transferable there — a record typed with it collapses the whole
+ * answer to `never` at the call site. The schema really is JSON, so it says so.
+ */
+type CompositionJsonScalarV1 = null | boolean | number | string;
+type CompositionJsonDepth1V1 =
+  | CompositionJsonScalarV1
+  | CompositionJsonScalarV1[]
+  | { [key: string]: CompositionJsonScalarV1 };
+type CompositionJsonDepth2V1 =
+  | CompositionJsonScalarV1
+  | CompositionJsonDepth1V1[]
+  | { [key: string]: CompositionJsonDepth1V1 };
+type CompositionJsonDepth3V1 =
+  | CompositionJsonScalarV1
+  | CompositionJsonDepth2V1[]
+  | { [key: string]: CompositionJsonDepth2V1 };
+/**
+ * Bounded rather than recursive on purpose: a self-referential JSON type makes
+ * the Durable Object RPC serializability mapper give up ("type instantiation is
+ * excessively deep"), and a tool's input schema is four levels at the outside.
+ */
+export type CompositionJsonValueV1 =
+  | CompositionJsonScalarV1
+  | CompositionJsonDepth3V1[]
+  | { [key: string]: CompositionJsonDepth3V1 };
+
+/** One tool an Applet generation declares, as the Composition records it. */
+export interface CompositionAppletToolV1 {
+  name: string;
+  description: string;
+  inputSchema: { [key: string]: CompositionJsonValueV1 };
+}
+
 export type CompositionGenerationStatusV1 =
   "pending" | "active" | "superseded" | "failed" | "quarantined";
 
@@ -89,6 +145,13 @@ export interface CompositionGenerationV1 {
   createdAt: string;
   origin: CompositionOriginV1;
   members: CompositionMemberV1[];
+  /**
+   * The Applet members resolved from the User's Applet directory when this
+   * generation was created. Absent means none. They are their own list rather
+   * than a variant of `members` because they carry no Package, no manifest and
+   * no artifact, and every existing reader of `members` means "Package".
+   */
+  applets?: CompositionAppletMemberV1[];
   status: CompositionGenerationStatusV1;
 }
 
@@ -143,7 +206,11 @@ const GENERATION_REQUIRED_KEYS = [
   "members",
   "status",
 ] as const;
-const GENERATION_OPTIONAL_KEYS = ["parentGenerationId", "summary"] as const;
+const GENERATION_OPTIONAL_KEYS = [
+  "parentGenerationId",
+  "summary",
+  "applets",
+] as const;
 const MEMBER_REQUIRED_KEYS = [
   "packageId",
   "specifier",
@@ -159,6 +226,9 @@ const ARTIFACT_KEYS = [
   "bundlerVersion",
 ] as const;
 const MAX_COMPOSITION_MEMBERS = 512;
+const MAX_COMPOSITION_APPLETS = 64;
+const MAX_COMPOSITION_APPLET_TOOLS = 64;
+const COMPOSITION_APPLET_TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
 const SHA256_HEX = /^[0-9a-f]{64}$/;
 export const MAX_COMPOSITION_SUMMARY_V1 = 160;
 
@@ -260,7 +330,10 @@ function decodePackageProvenanceV1(
   return value as unknown as PackageProvenanceV1;
 }
 
-function decodeArtifactRefV1(input: unknown, label: string): ArtifactRefV1 {
+export function decodeArtifactRefV1(
+  input: unknown,
+  label: string,
+): ArtifactRefV1 {
   const value = record(input, label);
   exactKeys(value, ARTIFACT_KEYS, [], label);
   hashString(value.contentHash, `${label}.contentHash`);
@@ -313,6 +386,72 @@ function decodeCompositionMemberV1(
   };
 }
 
+function decodeCompositionAppletToolV1(
+  input: unknown,
+  label: string,
+): CompositionAppletToolV1 {
+  const value = record(input, label);
+  exactKeys(value, ["name", "description", "inputSchema"], [], label);
+  const name = boundedString(value.name, `${label}.name`, 64);
+  if (!COMPOSITION_APPLET_TOOL_NAME.test(name)) {
+    throw new Error(`${label}.name is invalid`);
+  }
+  const inputSchema = record(value.inputSchema, `${label}.inputSchema`);
+  return {
+    name,
+    description: boundedString(
+      value.description,
+      `${label}.description`,
+      1_024,
+    ),
+    // The round trip is the normalization: what survives it is JSON, which is
+    // exactly `CompositionJsonValueV1`, and what does not was never a schema.
+    inputSchema: JSON.parse(JSON.stringify(inputSchema)) as {
+      [key: string]: CompositionJsonValueV1;
+    },
+  };
+}
+
+export function decodeCompositionAppletMemberV1(
+  input: unknown,
+  label = "composition applet member",
+): CompositionAppletMemberV1 {
+  const value = record(input, label);
+  exactKeys(
+    value,
+    ["kind", "appletId", "generationId", "tools", "provenance"],
+    [],
+    label,
+  );
+  if (value.kind !== "applet") throw new Error(`${label}.kind is invalid`);
+  if (
+    !Array.isArray(value.tools) ||
+    value.tools.length > MAX_COMPOSITION_APPLET_TOOLS
+  ) {
+    throw new Error(`${label}.tools must be a bounded array`);
+  }
+  const tools = value.tools.map((tool, index) =>
+    decodeCompositionAppletToolV1(tool, `${label}.tools[${index}]`),
+  );
+  if (new Set(tools.map((tool) => tool.name)).size !== tools.length) {
+    throw new Error(`${label}.tools contains duplicate names`);
+  }
+  return {
+    kind: "applet",
+    appletId: boundedString(value.appletId, `${label}.appletId`, 129),
+    generationId: boundedString(
+      value.generationId,
+      `${label}.generationId`,
+      128,
+    ),
+    tools,
+    provenance: decodePackageProvenanceV1(
+      value.provenance,
+      `${label}.provenance`,
+    ),
+  };
+}
+
 function decodeCompositionOriginV1(
   input: unknown,
   label: string,
@@ -415,6 +554,23 @@ export function decodeCompositionGenerationV1(
   if (packageIds.size !== members.length) {
     throw new Error(`${label}.members contains duplicate packages`);
   }
+  let applets: CompositionAppletMemberV1[] | undefined;
+  if (value.applets !== undefined) {
+    if (!Array.isArray(value.applets)) {
+      throw new Error(`${label}.applets must be an array`);
+    }
+    if (value.applets.length > MAX_COMPOSITION_APPLETS) {
+      throw new Error(`${label}.applets exceeds its bound`);
+    }
+    applets = value.applets.map((applet, index) =>
+      decodeCompositionAppletMemberV1(applet, `${label}.applets[${index}]`),
+    );
+    if (
+      new Set(applets.map((applet) => applet.appletId)).size !== applets.length
+    ) {
+      throw new Error(`${label}.applets contains duplicate Applets`);
+    }
+  }
   const status = COMPOSITION_GENERATION_STATUSES.find(
     (candidate) => candidate === value.status,
   );
@@ -446,19 +602,32 @@ export function decodeCompositionGenerationV1(
     ...(value.summary === undefined
       ? {}
       : { summary: value.summary as string }),
+    ...(applets === undefined ? {} : { applets }),
   };
 }
 
-/** The loader identity: sha-256 over the canonical, package-ordered member list. */
+/**
+ * The loader identity: sha-256 over the canonical, package-ordered member list.
+ *
+ * Applet members are covered too, and only when there are any — a generation
+ * with no Applets hashes exactly as it did before Applets existed, so no
+ * already-recorded generation's hash changes meaning.
+ */
 export function compositionArtifactSetHashV1(
   members: readonly CompositionMemberV1[],
+  applets: readonly CompositionAppletMemberV1[] = [],
 ): Promise<string> {
+  const orderedMembers = [...members].sort((left, right) =>
+    left.packageId.localeCompare(right.packageId),
+  );
+  if (applets.length === 0) return sha256(canonicalJson(orderedMembers));
   return sha256(
-    canonicalJson(
-      [...members].sort((left, right) =>
-        left.packageId.localeCompare(right.packageId),
+    canonicalJson({
+      members: orderedMembers,
+      applets: [...applets].sort((left, right) =>
+        left.appletId.localeCompare(right.appletId),
       ),
-    ),
+    }),
   );
 }
 
@@ -466,7 +635,10 @@ export function compositionArtifactSetHashV1(
 export async function assertCompositionArtifactSetHashV1(
   generation: CompositionGenerationV1,
 ): Promise<void> {
-  const expected = await compositionArtifactSetHashV1(generation.members);
+  const expected = await compositionArtifactSetHashV1(
+    generation.members,
+    generation.applets ?? [],
+  );
   if (expected !== generation.artifactSetHash) {
     throw new Error(
       `composition generation "${generation.generationId}" has a mismatched artifact set hash`,
@@ -487,6 +659,19 @@ export interface BootstrapCompositionMemberV1 {
   specifier: string;
   version: string;
   manifest: unknown;
+  /**
+   * The immutable module bytes this first-party member loads from, when the
+   * application declared one.
+   *
+   * ADR 0022 decision 8: a first-party Package that declares only
+   * Bot-authorable Contribution kinds "ships as an artifact-backed member and
+   * loads through the same path as a Bot-authored one". The bootstrap is where
+   * that member enters a Bot's Composition, so it is where the artifact has to
+   * survive — dropping it here would silently turn the member into an
+   * in-process one the application has no table entry for, which is a Bot with
+   * no Applets rather than a mount failure.
+   */
+  artifact?: ArtifactRefV1;
 }
 
 /**
@@ -508,6 +693,7 @@ export async function bootstrapGeneration(
         packageId: member.packageId,
         version: member.version,
       },
+      ...(member.artifact ? { artifact: member.artifact } : {}),
     })),
   );
   const ordered = composed.sort((left, right) =>