@frockbot/kernel-contracts 0.0.0 → 0.1.0

package/package.json

@@ -1,14 +1,29 @@
 {
   "name": "@frockbot/kernel-contracts",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "@types/node": "26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/kernel-contracts"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/authoring.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodePackageBundleArtifactV1,
+  decodePackageBundleResultV1,
+  PACKAGE_BUNDLE_MAX_SOURCE_BYTES,
+} from "./authoring.js";
+import { decodeSessionEvent } from "./types.js";
+
+const ARTIFACT = {
+  contentHash: "a".repeat(64),
+  size: 128,
+  mediaType: "application/javascript",
+  bundlerVersion: "@cloudflare/worker-bundler@0.2.3",
+};
+
+describe("the kernel-declared bundler seam", () => {
+  test("bounds Package source at the D7 quota", () => {
+    expect(PACKAGE_BUNDLE_MAX_SOURCE_BYTES).toBe(256 * 1024);
+  });
+
+  test("decodes a bundled result exactly", () => {
+    const result = decodePackageBundleResultV1({
+      schemaVersion: 1,
+      effectId: "author-1",
+      status: "bundled",
+      artifact: ARTIFACT,
+      module: "export const tools = [];",
+      diagnostics: [],
+    });
+    expect(result.status).toBe("bundled");
+    expect(decodePackageBundleArtifactV1(ARTIFACT)).toEqual(ARTIFACT as never);
+  });
+
+  test("decodes a failed result exactly", () => {
+    expect(
+      decodePackageBundleResultV1({
+        schemaVersion: 1,
+        effectId: "author-1",
+        status: "failed",
+        failure: "unresolved-import",
+        diagnostics: ['still imports "zod"'],
+      }).status,
+    ).toBe("failed");
+  });
+
+  test.each([
+    [
+      "an unsupported schema version",
+      { schemaVersion: 2, effectId: "a", status: "bundled" },
+    ],
+    [
+      "an unknown status",
+      { schemaVersion: 1, effectId: "a", status: "queued" },
+    ],
+    [
+      "a non-hex content hash",
+      {
+        schemaVersion: 1,
+        effectId: "a",
+        status: "bundled",
+        artifact: { ...ARTIFACT, contentHash: "not-a-hash" },
+        module: "x",
+        diagnostics: [],
+      },
+    ],
+    [
+      "an unexpected media type",
+      {
+        schemaVersion: 1,
+        effectId: "a",
+        status: "bundled",
+        artifact: { ...ARTIFACT, mediaType: "text/html" },
+        module: "x",
+        diagnostics: [],
+      },
+    ],
+    [
+      "an empty module",
+      {
+        schemaVersion: 1,
+        effectId: "a",
+        status: "bundled",
+        artifact: ARTIFACT,
+        module: "",
+        diagnostics: [],
+      },
+    ],
+    [
+      "an extra field",
+      {
+        schemaVersion: 1,
+        effectId: "a",
+        status: "bundled",
+        artifact: ARTIFACT,
+        module: "x",
+        diagnostics: [],
+        r2Key: "packages/a.mjs",
+      },
+    ],
+  ])("rejects %s", (_label, input) => {
+    expect(() => decodePackageBundleResultV1(input)).toThrow();
+  });
+});
+
+describe("the authoring session events", () => {
+  const intent = {
+    type: "package/author-intent",
+    seq: 0,
+    timestamp: "2026-08-31T00:00:00.000Z",
+    turn: 1,
+    step: 1,
+    effectId: "author-1",
+    packageId: "weather-lookup",
+    sourceHash: "a".repeat(64),
+  };
+  const authored = {
+    type: "package/authored",
+    seq: 1,
+    timestamp: "2026-08-31T00:00:00.000Z",
+    turn: 1,
+    step: 1,
+    effectId: "author-1",
+    packageId: "weather-lookup",
+    version: "0.0.1",
+    contentHash: "b".repeat(64),
+    generationId: "2026-08-31T00:00:00.000Z:0123456789abcdef",
+  };
+
+  test("decode exactly", () => {
+    expect(decodeSessionEvent(intent)).toEqual(intent as never);
+    expect(decodeSessionEvent(authored)).toEqual(authored as never);
+  });
+
+  test.each([
+    ["an intent with no step", { ...intent, step: undefined }],
+    ["an intent with an extra field", { ...intent, source: "x" }],
+    ["an authored event with no generation", { ...authored, generationId: "" }],
+    ["an authored event with no version", { ...authored, version: undefined }],
+    ["a turn of zero", { ...intent, turn: 0 }],
+  ])("reject %s", (_label, input) => {
+    expect(() => decodeSessionEvent(input)).toThrow();
+  });
+});

package/src/authoring.ts

@@ -0,0 +1,189 @@
+// The kernel-declared Package bundler seam.
+//
+// "Compilation and bundling happen outside Durable Objects. Composition
+// consumes immutable, content-addressed artifacts and never builds them."
+// The kernel therefore declares *what* a bundler is — a narrow, versioned
+// binding that turns Package source text into a content-addressed artifact —
+// and owns no implementation of one. `apps/cloudflare-bundler` is the
+// production implementation behind the `PACKAGE_BUNDLER` service binding.
+//
+// A Package that authors code receives this binding from the Durable Object
+// host that owns it; it never reaches a Worker `env` itself.
+import type {} from "cordis";
+
+/** D7: 256 KB of source per Package. */
+export const PACKAGE_BUNDLE_MAX_SOURCE_BYTES = 256 * 1024;
+/** The only entry a Bot-authored Package may declare in this slice. */
+export const PACKAGE_BUNDLE_ENTRY = "package.ts";
+
+export interface PackageBundleSourceV1 {
+  path: string;
+  text: string;
+}
+
+export interface PackageBundleRequestV1 {
+  schemaVersion: 1;
+  /** Idempotency key: the Durable-Object-recorded authorship intent id. */
+  effectId: string;
+  target: "bot-isolate";
+  compatibilityDate: string;
+  entry: "package.ts";
+  sources: PackageBundleSourceV1[];
+}
+
+export interface PackageBundleArtifactV1 {
+  /** sha-256 hex of the bundled module bytes. */
+  contentHash: string;
+  size: number;
+  mediaType: "application/javascript";
+  bundlerVersion: string;
+}
+
+export type PackageBundleResultV1 =
+  | {
+      schemaVersion: 1;
+      effectId: string;
+      status: "bundled";
+      artifact: PackageBundleArtifactV1;
+      /** The module bytes as text; the Durable Object owns the artifact write. */
+      module: string;
+      diagnostics: string[];
+    }
+  | {
+      schemaVersion: 1;
+      effectId: string;
+      status: "failed";
+      failure: string;
+      diagnostics: string[];
+    };
+
+/** The `PACKAGE_BUNDLER` binding, declared structurally so the kernel stays platform-free. */
+export interface PackageBundlerBinding {
+  bundle(request: PackageBundleRequestV1): Promise<PackageBundleResultV1>;
+}
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  label: string,
+): void {
+  if (
+    Object.keys(value).length !== keys.length ||
+    !keys.every((key) => Object.hasOwn(value, key))
+  ) {
+    throw new Error(`${label} has invalid fields`);
+  }
+}
+
+function boundedString(value: unknown, label: string, maximum: number): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > maximum)
+    throw new Error(`${label} must be a bounded string`);
+  return value;
+}
+
+function diagnostics(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.length > 64) {
+    throw new Error(`${label} must be a bounded array`);
+  }
+  return value.map((entry, index) => {
+    if (typeof entry !== "string" || entry.length > 8_192) {
+      throw new Error(`${label}[${index}] must be a bounded string`);
+    }
+    return entry;
+  });
+}
+
+export function decodePackageBundleArtifactV1(
+  input: unknown,
+  label = "package bundle artifact",
+): PackageBundleArtifactV1 {
+  const value = record(input, label);
+  exactKeys(
+    value,
+    ["contentHash", "size", "mediaType", "bundlerVersion"],
+    label,
+  );
+  if (
+    typeof value.contentHash !== "string" ||
+    !SHA256_HEX.test(value.contentHash)
+  )
+    throw new Error(`${label}.contentHash must be a sha-256 hex digest`);
+  if (!Number.isSafeInteger(value.size) || (value.size as number) < 0)
+    throw new Error(`${label}.size must be a non-negative integer`);
+  if (value.mediaType !== "application/javascript")
+    throw new Error(`${label}.mediaType is invalid`);
+  boundedString(value.bundlerVersion, `${label}.bundlerVersion`, 128);
+  return {
+    contentHash: value.contentHash,
+    size: value.size as number,
+    mediaType: "application/javascript",
+    bundlerVersion: value.bundlerVersion as string,
+  };
+}
+
+/**
+ * The exact v1 decoder for what comes back across the bundler binding. The
+ * bundler is a separate Worker, so its answer is an inbound value at a
+ * cross-runtime seam and is decoded before a byte of it becomes an artifact.
+ */
+export function decodePackageBundleResultV1(
+  input: unknown,
+  label = "package bundle result",
+): PackageBundleResultV1 {
+  const value = record(input, label);
+  if (value.schemaVersion !== 1)
+    throw new Error(`${label}.schemaVersion is unsupported`);
+  const effectId = boundedString(value.effectId, `${label}.effectId`, 200);
+  if (value.status === "bundled") {
+    exactKeys(
+      value,
+      [
+        "schemaVersion",
+        "effectId",
+        "status",
+        "artifact",
+        "module",
+        "diagnostics",
+      ],
+      label,
+    );
+    const artifact = decodePackageBundleArtifactV1(
+      value.artifact,
+      `${label}.artifact`,
+    );
+    if (typeof value.module !== "string" || value.module.length === 0)
+      throw new Error(`${label}.module must be a non-empty string`);
+    return {
+      schemaVersion: 1,
+      effectId,
+      status: "bundled",
+      artifact,
+      module: value.module,
+      diagnostics: diagnostics(value.diagnostics, `${label}.diagnostics`),
+    };
+  }
+  if (value.status === "failed") {
+    exactKeys(
+      value,
+      ["schemaVersion", "effectId", "status", "failure", "diagnostics"],
+      label,
+    );
+    return {
+      schemaVersion: 1,
+      effectId,
+      status: "failed",
+      failure: boundedString(value.failure, `${label}.failure`, 256),
+      diagnostics: diagnostics(value.diagnostics, `${label}.diagnostics`),
+    };
+  }
+  throw new Error(`${label}.status is invalid`);
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./authoring.js";
+export * from "./isolate.js";
+export * from "./model-invocation.js";
+export * from "./prompt-assembly.js";
+export * from "./send-to-user.js";
+export * from "./session.js";
+export * from "./skills.js";
+export * from "./tool-execution.js";
+export * from "./turn-history.js";
+export * from "./types.js";
+export * from "./workspace.js";