Implement checked workspace integration contracts (WI-01)

This commit is contained in:
Timothy J. Aveni
2026-09-21 11:23:26 -07:00
parent 3c0378358f
commit 884b12f759
22 changed files with 4349 additions and 3089 deletions
+86
View File
@@ -0,0 +1,86 @@
import type { InterfaceRevision, PackageController, WorkspaceRevision } from "./types.js";
import type { CapabilityValidationIssue } from "./validation.js";
import { canonicalJson } from "./evolution.js";
export function validateControllers(
controllers: readonly PackageController[],
interfaces: readonly InterfaceRevision[],
prefix: string,
): CapabilityValidationIssue[] {
const issues: CapabilityValidationIssue[] = [],
ids = new Set<string>();
const fail = (path: string, message: string) => issues.push({ code: "invalid-controller" as const, path, message });
for (const [index, controller] of controllers.entries()) {
const path = `${prefix}[${index}]`;
if (!controller.id.trim() || ids.has(controller.id))
fail(`${path}.id`, "Controller identities must be nonempty and unique within the package");
ids.add(controller.id);
const iface = interfaces.find((i) => i.revisionId === controller.subject && !i.template);
if (!iface) {
fail(`${path}.subject`, "Controller subject must be an imported closed interface");
continue;
}
const operations = iface.members.flatMap((m) => m.operations);
const snapshot = operations.find((o) => o.id === controller.snapshot),
remote = operations.find((o) => o.id === controller.remote);
const unit = (value: unknown) => canonicalJson(value) === canonicalJson({ kind: "builtin", name: "unit" });
if (
!snapshot ||
snapshot.scope === "class" ||
snapshot.mode !== "call" ||
snapshot.execution?.kind !== "snapshot" ||
!snapshot.execution.targets.includes("server") ||
!unit(snapshot.inputType)
)
fail(`${path}.snapshot`, "Controller snapshot must be a server snapshot object call with unit input");
if (
!remote ||
remote.scope === "class" ||
remote.mode !== "call" ||
(remote.execution?.kind ?? "remote") !== "remote"
)
fail(`${path}.remote`, "Controller target must be a remote object call");
if (controller.input !== "unit" && controller.input !== "value")
fail(`${path}.input`, "Controller input must be unit or value");
else if (
remote &&
(controller.input === "unit"
? !unit(remote.inputType)
: snapshot && canonicalJson(snapshot.outputType) !== canonicalJson(remote.inputType))
)
fail(`${path}.input`, "Controller input mapping does not match the remote operation input");
}
return issues;
}
export function validateWorkspaceControllers(workspace: WorkspaceRevision): CapabilityValidationIssue[] {
return workspace.packageImports.flatMap((pkg, index) =>
validateControllers(pkg.controllers ?? [], workspace.interfaceImports, `packageImports[${index}].controllers`),
);
}
/** The file is declarative metadata, not an executable registration callback. */
export function parseControllerCatalog(text: string, interfaces: readonly InterfaceRevision[]): PackageController[] {
if (Buffer.byteLength(text) > 1048576) throw new Error("Controller catalog exceeds 1 MiB");
const value: unknown = JSON.parse(text);
const record = (value: unknown): value is Record<string, unknown> =>
!!value && typeof value === "object" && !Array.isArray(value);
if (
!record(value) ||
value.schemaVersion !== 1 ||
Object.keys(value).some((k) => !["schemaVersion", "controllers"].includes(k)) ||
!Array.isArray(value.controllers) ||
value.controllers.length > 1000
)
throw new Error("Invalid controller catalog: expected schemaVersion 1 and at most 1000 controllers");
const fields = ["id", "subject", "snapshot", "remote", "input"];
for (const entry of value.controllers)
if (
!record(entry) ||
Object.keys(entry).length !== fields.length ||
fields.some((key) => typeof entry[key] !== "string")
)
throw new Error("Invalid controller entry: expected exactly id, subject, snapshot, remote, input strings");
const controllers = value.controllers as PackageController[];
const issues = validateControllers(controllers, interfaces, "controllers");
if (issues.length) throw new Error(issues.map((i) => `${i.path}: ${i.message}`).join("\n"));
return controllers;
}