@frockbot/catalog-core 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/catalog-core",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -11,7 +11,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-composition": "0.1.3"
+    "@frockbot/kernel-composition": "0.2.0"
   },
   "devDependencies": {
     "@types/bun": "1.3.6",

package/src/index.test.ts

@@ -1,9 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import {
   MAX_CATALOG_SKILL_BODY_BYTES_V1,
+  assertCatalogPackageBundleV1,
   assertCatalogEntryMatchesIndexV1,
   catalogContentHashV1,
   catalogEntryKeyV1,
+  catalogPackageArtifactKeyV1,
+  catalogPackageSourceKeyV1,
+  catalogPackageUiArtifactKeyV1,
   catalogSetupFieldKeyV1,
   catalogIndexKeyV1,
   CATALOG_POINTER_KEY_V1,
@@ -20,6 +24,28 @@ import {
 
 const MANIFEST_HASH = "a".repeat(64);
 
+function isolateManifest() {
+  return {
+    schemaVersion: 3 as const,
+    id: "parcel-tracking",
+    displayName: "Parcel tracking",
+    version: "0.0.1",
+    compatibility: { frockbot: ">=0.0.1" },
+    dependencies: {},
+    contributions: {
+      runtime: { entry: "./package.js", host: "bot-isolate" as const },
+    },
+    tools: [
+      {
+        name: "track_parcel",
+        description: "Tracks a parcel.",
+        inputSchema: { type: "object" },
+      },
+    ],
+    permissions: [],
+  };
+}
+
 function indexEntry(
   overrides: Partial<CatalogIndexEntryV1> = {},
 ): CatalogIndexEntryV1 {
@@ -228,6 +254,112 @@ describe("catalog entry decoding", () => {
       decodeCatalogEntryV1({ ...entryDetail(), installs: 12 }),
     ).toThrow('unknown field "installs"');
   });
+
+  test("decodes an immutable Bot-isolate bundle with the authored manifest shape", async () => {
+    const manifest = isolateManifest();
+    const manifestHash = await catalogContentHashV1(
+      JSON.stringify(manifest, Object.keys(manifest).sort()),
+    );
+    const entry = decodeCatalogEntryV1({
+      ...entryDetail({
+        catalogId: "parcel-tracking",
+        packageId: "parcel-tracking",
+        displayName: "Parcel tracking",
+        description: "Tracks deliveries.",
+        kind: "package",
+        manifestHash,
+      }),
+      tags: ["shipping", "parcels"],
+      bundle: {
+        contentHash: "b".repeat(64),
+        size: 512,
+        mediaType: "application/javascript",
+        bundlerVersion: "catalog-test@1",
+        manifest,
+        sourceHash: "c".repeat(64),
+      },
+    });
+
+    expect(entry.bundle?.manifest.tools?.[0]?.name).toBe("track_parcel");
+    expect(entry.tags).toEqual(["shipping", "parcels"]);
+    // The decoder validates shape synchronously; the reader additionally
+    // verifies the exact manifest bytes against the entry's hash.
+    await expect(assertCatalogPackageBundleV1(entry)).rejects.toThrow(
+      "manifest failed content hash verification",
+    );
+  });
+
+  test("keeps an iframe artifact reference in the bundle's verified manifest", () => {
+    const uiArtifact = {
+      contentHash: "d".repeat(64),
+      size: 42,
+      mediaType: "text/html" as const,
+      bundlerVersion: "frockbot-inline-html@1",
+    };
+    const manifest = isolateManifest();
+    const decoded = decodeCatalogEntryV1({
+      ...entryDetail({
+        catalogId: "parcel-tracking",
+        packageId: "parcel-tracking",
+        displayName: "Parcel tracking",
+        description: "Tracks deliveries.",
+        kind: "package",
+      }),
+      bundle: {
+        contentHash: "b".repeat(64),
+        size: 512,
+        mediaType: "application/javascript",
+        bundlerVersion: "catalog-test@1",
+        manifest: {
+          ...manifest,
+          contributions: {
+            ...manifest.contributions,
+            client: {
+              kind: "iframe",
+              artifact: uiArtifact,
+              mounts: [{ slot: "frockbot.tool-result:track_parcel" }],
+            },
+          },
+        },
+      },
+    });
+
+    expect(decoded.bundle?.manifest.contributions.client).toEqual({
+      kind: "iframe",
+      artifact: uiArtifact,
+      mounts: [{ slot: "frockbot.tool-result:track_parcel" }],
+    });
+  });
+
+  test("refuses code on a connector or a manifest that does not target the Bot isolate", () => {
+    const bundle = {
+      contentHash: "b".repeat(64),
+      size: 512,
+      mediaType: "application/javascript" as const,
+      bundlerVersion: "catalog-test@1",
+      manifest: isolateManifest(),
+    };
+    expect(() => decodeCatalogEntryV1({ ...entryDetail(), bundle })).toThrow(
+      "only a package Catalog entry may carry a bundle",
+    );
+    expect(() =>
+      decodeCatalogEntryV1({
+        ...entryDetail({
+          catalogId: "parcel-tracking",
+          packageId: "parcel-tracking",
+          kind: "package",
+        }),
+        bundle: {
+          ...bundle,
+          manifest: {
+            ...isolateManifest(),
+            contributions: { runtime: { entry: "./runtime.js" } },
+            tools: undefined,
+          },
+        },
+      }),
+    ).toThrow("must declare a Bot isolate runtime");
+  });
 });
 
 describe("content addressing", () => {
@@ -278,6 +410,15 @@ describe("object layout", () => {
       "catalog/gen-0001/entry/mcp-weather.json",
     );
     expect(CATALOG_POINTER_KEY_V1).toBe("catalog/current");
+    expect(catalogPackageArtifactKeyV1("b".repeat(64))).toBe(
+      `packages/${"b".repeat(64)}.mjs`,
+    );
+    expect(catalogPackageSourceKeyV1("c".repeat(64))).toBe(
+      `packages/${"c".repeat(64)}.ts`,
+    );
+    expect(catalogPackageUiArtifactKeyV1("d".repeat(64))).toBe(
+      `packages/${"d".repeat(64)}.html`,
+    );
   });
 
   test("refuses a generation or catalogId that could escape its prefix", () => {

package/src/index.ts

@@ -23,9 +23,12 @@
  * manifest could not declare.
  */
 import {
+  decodeFrockBotManifest,
   decodePackageSettingSchemaV1,
+  type FrockBotManifest,
   type PackageSettingSchema,
 } from "@frockbot/kernel-composition";
+import { canonicalJson } from "@frockbot/kernel-composition/compiler";
 
 export class CatalogDecodeError extends Error {
   constructor(message: string, options?: ErrorOptions) {
@@ -41,6 +44,7 @@ export const MAX_CATALOG_ENTRIES_V1 = 512;
 export const MAX_CATALOG_SERVERS_V1 = 16;
 export const MAX_CATALOG_SETUP_FIELDS_V1 = 32;
 export const MAX_CATALOG_SKILLS_V1 = 64;
+export const MAX_CATALOG_TAGS_V1 = 32;
 /**
  * Longest Skill body one Catalog entry may carry.
  *
@@ -65,6 +69,9 @@ export interface CatalogIndexEntryV1 {
   version: string;
   manifestHash: string;
   kind: CatalogEntryKindV1;
+  /** Present when this row names code loaded in a Bot isolate. */
+  contentHash?: string;
+  tags?: string[];
   logo?: string;
   homepage?: string;
 }
@@ -93,6 +100,25 @@ export interface CatalogSkillV1 {
   body?: string;
 }
 
+/**
+ * One immutable non-first-party bundle named by a Package Catalog entry.
+ *
+ * The manifest is decoded with the same kernel decoder used for a stored
+ * Bot-authored manifest. `sourceHash` is optional because source publication
+ * is optional; when present it addresses the retained `.ts` object in the
+ * shared Package artifact store. A sandboxed page needs no duplicate bundle
+ * field: its canonical artifact descriptor is the decoded manifest's iframe
+ * client Contribution.
+ */
+export interface CatalogPackageBundleV1 {
+  contentHash: string;
+  size: number;
+  mediaType: "application/javascript";
+  bundlerVersion: string;
+  manifest: FrockBotManifest;
+  sourceHash?: string;
+}
+
 export interface CatalogEntryV1 {
   schemaVersion: 1;
   catalogId: string;
@@ -102,11 +128,14 @@ export interface CatalogEntryV1 {
   version: string;
   kind: CatalogEntryKindV1;
   manifestHash: string;
+  tags?: string[];
   logo?: string;
   homepage?: string;
   servers: CatalogServerV1[];
   setupFields: PackageSettingSchema[];
   skills: CatalogSkillV1[];
+  /** Absent means the existing reviewed, compiled-in first-party form. */
+  bundle?: CatalogPackageBundleV1;
 }
 
 /**
@@ -232,6 +261,20 @@ function entryKind(value: unknown, label: string): CatalogEntryKindV1 {
   return value;
 }
 
+function tags(value: unknown, label: string): string[] | undefined {
+  if (value === undefined) return undefined;
+  const decoded = boundedArray(value, label, MAX_CATALOG_TAGS_V1).map(
+    (tag, index) => text(tag, `${label}[${index}]`, 64),
+  );
+  if (
+    new Set(decoded.map((tag) => tag.toLocaleLowerCase())).size !==
+    decoded.length
+  ) {
+    throw new CatalogDecodeError(`${label} repeats a tag`);
+  }
+  return decoded;
+}
+
 /**
  * A Catalog logo and homepage are rendered by the browser, so only an absolute
  * `https:` URL is admitted: a `javascript:` or `data:` value in a document the
@@ -295,9 +338,9 @@ export function decodeCatalogIndexEntryV1(value: unknown): CatalogIndexEntryV1 {
       "manifestHash",
       "kind",
     ],
-    ["logo", "homepage"],
+    ["contentHash", "tags", "logo", "homepage"],
   );
-  return withOptional(
+  const decoded = withOptional(
     {
       catalogId: decodeCatalogIdV1(entry.catalogId),
       packageId: pattern(entry.packageId, "packageId", PACKAGE_ID_PATTERN, 64),
@@ -313,10 +356,18 @@ export function decodeCatalogIndexEntryV1(value: unknown): CatalogIndexEntryV1 {
       kind: entryKind(entry.kind, "kind"),
     },
     {
+      contentHash:
+        entry.contentHash === undefined
+          ? undefined
+          : decodeCatalogContentHashV1(entry.contentHash, "contentHash"),
       logo: optionalHttpsUrl(entry.logo, "logo"),
       homepage: optionalHttpsUrl(entry.homepage, "homepage"),
     },
   );
+  const decodedTags = tags(entry.tags, "catalog tags");
+  return decodedTags === undefined
+    ? decoded
+    : { ...decoded, tags: decodedTags };
 }
 
 export function decodeCatalogIndexV1(input: unknown): CatalogIndexV1 {
@@ -391,6 +442,49 @@ function decodeCatalogSkillV1(value: unknown): CatalogSkillV1 {
   );
 }
 
+function decodeCatalogPackageBundleV1(input: unknown): CatalogPackageBundleV1 {
+  const bundle = exactRecord(
+    input,
+    "catalog package bundle",
+    ["contentHash", "size", "mediaType", "bundlerVersion", "manifest"],
+    ["sourceHash"],
+  );
+  if (!Number.isSafeInteger(bundle.size) || (bundle.size as number) < 0) {
+    throw new CatalogDecodeError("catalog package bundle size is invalid");
+  }
+  if (bundle.mediaType !== "application/javascript") {
+    throw new CatalogDecodeError("catalog package bundle mediaType is invalid");
+  }
+  const manifest = decodeFrockBotManifest(bundle.manifest);
+  if (manifest.contributions.runtime?.host !== "bot-isolate") {
+    throw new CatalogDecodeError(
+      "catalog package bundle manifest must declare a Bot isolate runtime",
+    );
+  }
+  return {
+    contentHash: decodeCatalogContentHashV1(
+      bundle.contentHash,
+      "catalog package bundle contentHash",
+    ),
+    size: bundle.size as number,
+    mediaType: "application/javascript",
+    bundlerVersion: text(
+      bundle.bundlerVersion,
+      "catalog package bundle bundlerVersion",
+      128,
+    ),
+    manifest,
+    ...(bundle.sourceHash === undefined
+      ? {}
+      : {
+          sourceHash: decodeCatalogContentHashV1(
+            bundle.sourceHash,
+            "catalog package bundle sourceHash",
+          ),
+        }),
+  };
+}
+
 export function decodeCatalogEntryV1(input: unknown): CatalogEntryV1 {
   const value = exactRecord(
     input,
@@ -408,10 +502,10 @@ export function decodeCatalogEntryV1(input: unknown): CatalogEntryV1 {
       "setupFields",
       "skills",
     ],
-    ["logo", "homepage"],
+    ["tags", "logo", "homepage", "bundle"],
   );
   schemaVersion(value, "catalog entry detail");
-  return withOptional(
+  const decoded = withOptional(
     {
       schemaVersion: 1 as const,
       catalogId: decodeCatalogIdV1(value.catalogId),
@@ -447,6 +541,45 @@ export function decodeCatalogEntryV1(input: unknown): CatalogEntryV1 {
       homepage: optionalHttpsUrl(value.homepage, "homepage"),
     },
   );
+  const decodedTags = tags(value.tags, "catalog tags");
+  const bundle =
+    value.bundle === undefined
+      ? undefined
+      : decodeCatalogPackageBundleV1(value.bundle);
+  if (bundle && decoded.kind !== "package") {
+    throw new CatalogDecodeError(
+      "only a package Catalog entry may carry a bundle",
+    );
+  }
+  if (
+    bundle &&
+    (bundle.manifest.id !== decoded.packageId ||
+      bundle.manifest.version !== decoded.version)
+  ) {
+    throw new CatalogDecodeError(
+      "catalog package bundle manifest does not match its entry",
+    );
+  }
+  return {
+    ...decoded,
+    ...(decodedTags === undefined ? {} : { tags: decodedTags }),
+    ...(bundle === undefined ? {} : { bundle }),
+  };
+}
+
+/** Verify the nested manifest against the entry's immutable manifest hash. */
+export async function assertCatalogPackageBundleV1(
+  entry: CatalogEntryV1,
+): Promise<void> {
+  if (!entry.bundle) return;
+  const actual = await catalogContentHashV1(
+    canonicalJson(entry.bundle.manifest),
+  );
+  if (actual !== entry.manifestHash) {
+    throw new CatalogDecodeError(
+      `catalog entry "${entry.catalogId}" bundle manifest failed content hash verification`,
+    );
+  }
 }
 
 export function decodeCatalogPointerV1(input: unknown): CatalogPointerV1 {
@@ -474,6 +607,20 @@ export function catalogEntryKeyV1(
   return `catalog/${decodeCatalogGenerationIdV1(generation)}/entry/${decodeCatalogIdV1(catalogId)}.json`;
 }
 
+/** Package artifacts share the same immutable store and layout as authored code. */
+export function catalogPackageArtifactKeyV1(contentHash: string): string {
+  return `packages/${decodeCatalogContentHashV1(contentHash)}.mjs`;
+}
+
+export function catalogPackageSourceKeyV1(sourceHash: string): string {
+  return `packages/${decodeCatalogContentHashV1(sourceHash)}.ts`;
+}
+
+/** Sandboxed UI artifacts share the authored Package artifact layout too. */
+export function catalogPackageUiArtifactKeyV1(contentHash: string): string {
+  return `packages/${decodeCatalogContentHashV1(contentHash)}.html`;
+}
+
 /**
  * The content hash of one Catalog document: SHA-256 over the exact UTF-8 bytes
  * the bucket holds. Hashing the bytes rather than a re-serialization is what
@@ -535,7 +682,9 @@ export async function decodeCatalogEntryDocumentV1(
   expectedHash: string,
 ): Promise<CatalogEntryV1> {
   await assertContentHash(document, expectedHash, "catalog entry");
-  return decodeCatalogEntryV1(parseDocument(document, "catalog entry"));
+  const entry = decodeCatalogEntryV1(parseDocument(document, "catalog entry"));
+  await assertCatalogPackageBundleV1(entry);
+  return entry;
 }
 
 /** Parse an index document whose hash the caller has not pinned yet. */
@@ -561,7 +710,8 @@ export function assertCatalogEntryMatchesIndexV1(
     entry.packageId !== indexEntry.packageId ||
     entry.version !== indexEntry.version ||
     entry.kind !== indexEntry.kind ||
-    entry.manifestHash !== indexEntry.manifestHash
+    entry.manifestHash !== indexEntry.manifestHash ||
+    entry.bundle?.contentHash !== indexEntry.contentHash
   ) {
     throw new CatalogDecodeError(
       `catalog entry "${indexEntry.catalogId}" does not match its index row`,