quixos-toolchain/quixos-protocol
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Host checked adapter-object controllers through bounded registries (WI-13)

Browse Source
This commit is contained in:
Timothy J. Aveni
2026-09-21 18:00:27 -07:00
parent 1e08ccd937
commit d824634859
14 changed files with 235 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/capability-language/assembly.ts
+5 -1
View File
@@ -257,7 +257,11 @@ const createResourceGraphResolver = (quixosCommit: string, resolveResource: Capa
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
}
if (controllerText !== undefined)
compiled.resource.revision.controllers = parseControllerCatalog(controllerText, queryInterfaces);
compiled.resource.revision.controllers = parseControllerCatalog(
controllerText,
queryInterfaces,
compiled.resource.revision.checkedQueries,
);
let catalogText: string | undefined;
try {
catalogText = await readFile(path.join(snapshot.directory, "quixos.migrations.json"), "utf8");
src/capability-language/controller-scaffold.ts
+2 -1
View File
@@ -10,7 +10,8 @@ export async function scaffoldController(
const entry = { id: spec.id, ...spec.controller };
const fields = ["id", "subject", "snapshot", "remote", "input"];
if (
Object.keys(entry).length !== fields.length ||
Object.keys(entry).some((key) => ![...fields, "registry"].includes(key)) ||
(entry.registry !== undefined && typeof entry.registry !== "string") ||
fields.some((key) => typeof (entry as Record<string, unknown>)[key] !== "string") ||
!["unit", "value"].includes(entry.input ?? "")
)
src/capability-language/scaffold-recipes.ts
+1 -1
View File
@@ -15,7 +15,7 @@ export type ScaffoldRecipe = {
declaration?: string;
queryDocument?: string;
initialFiles?: Record<string, string>;
controller?: { subject: string; snapshot: string; remote: string; input: "unit" | "value" };
controller?: { registry?: string; subject: string; snapshot: string; remote: string; input: "unit" | "value" };
tools?: { quixos: Source; protocol: Source; helpers: Source; sdk?: Source };
};
const source = (value: Source): GitSource => {
src/capability-model/controllers.ts
+46 -4
View File
@@ -6,6 +6,7 @@ export function validateControllers(
controllers: readonly PackageController[],
interfaces: readonly InterfaceRevision[],
prefix: string,
queries: readonly import("../query/types.js").CheckedQuery[] = [],
): CapabilityValidationIssue[] {
const issues: CapabilityValidationIssue[] = [],
ids = new Set<string>();
@@ -15,6 +16,37 @@ export function validateControllers(
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);
if (controller.registry !== undefined) {
const query = queries.find((query) => query.declaration.id === controller.registry);
const selected = (entries: import("../query/types.js").QuerySelection[] | undefined, name: string) =>
entries?.find((entry) => entry.name === name && entry.key === name && !entry.conditions.length);
const root = selected(query?.selection, "root"),
objects = selected(root?.selection, "objects"),
entries = selected(objects?.selection, "entries"),
node = selected(entries?.selection, "node"),
qx = selected(node?.selection, "_qx"),
ref = selected(qx?.selection, "ref");
const all = objects?.arguments.all;
if (
!query ||
query.declaration.root.kind !== "workspace-interface" ||
query.declaration.root.interface !== controller.subject ||
query.declaration.placement?.kind === "local" ||
query.effects.some((effect) => effect.execution === "rpc-permitted") ||
query.variables.kind !== "record" ||
Object.keys(query.variables.fields).length ||
!ref ||
all?.kind !== "literal" ||
!/^\d+$/.test(String(all.value)) ||
!Number.isSafeInteger(Number(all.value)) ||
Number(all.value) < 1 ||
Number(all.value) > 64
)
fail(
`${path}.registry`,
"Controller registry requires a native/portable workspace query over its subject, no variables, and root.objects(all: 1..64).entries.node._qx.ref without aliases or conditional selections",
);
}
const iface = interfaces.find((i) => i.revisionId === controller.subject && !i.template);
if (!iface) {
fail(`${path}.subject`, "Controller subject must be an imported closed interface");
@@ -54,11 +86,20 @@ export function validateControllers(
}
export function validateWorkspaceControllers(workspace: WorkspaceRevision): CapabilityValidationIssue[] {
return workspace.packageImports.flatMap((pkg, index) =>
validateControllers(pkg.controllers ?? [], workspace.interfaceImports, `packageImports[${index}].controllers`),
validateControllers(
pkg.controllers ?? [],
workspace.interfaceImports,
`packageImports[${index}].controllers`,
pkg.checkedQueries,
),
);
}
/** The file is declarative metadata, not an executable registration callback. */
export function parseControllerCatalog(text: string, interfaces: readonly InterfaceRevision[]): PackageController[] {
export function parseControllerCatalog(
text: string,
interfaces: readonly InterfaceRevision[],
queries: readonly import("../query/types.js").CheckedQuery[] = [],
): 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> =>
@@ -75,12 +116,13 @@ export function parseControllerCatalog(text: string, interfaces: readonly Interf
for (const entry of value.controllers)
if (
!record(entry) ||
Object.keys(entry).length !== fields.length ||
Object.keys(entry).some((key) => ![...fields, "registry"].includes(key)) ||
(entry.registry !== undefined && typeof entry.registry !== "string") ||
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");
const issues = validateControllers(controllers, interfaces, "controllers", queries);
if (issues.length) throw new Error(issues.map((i) => `${i.path}: ${i.message}`).join("\n"));
return controllers;
}
src/capability-model/types.ts
+2
View File
@@ -326,6 +326,8 @@ export interface PackageRevision {
/** Checked adapter registration. Implementations remain ordinary object capabilities. */
export interface PackageController {
/** Optional opt-in discovery: a bounded checked workspace query in this package. */
registry?: string;
id: string;
subject: InterfaceRevisionId;
snapshot: OperationId;
test/controller-registry.test.ts
+50
View File
@@ -0,0 +1,50 @@
import test from "node:test";
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import { compileCapabilityResourceSource } from "../src/capability-language/index.js";
import { compileQuery } from "../src/query/compile.js";
import { parseControllerCatalog } from "../src/capability-model/controllers.js";
const source = { repository: "https://example.test/device.git", commit: "a".repeat(40) };
test("controller discovery requires complete bounded accepted-state membership", async () => {
const result = compileCapabilityResourceSource(
await readFile("test/fixtures/controller-device/DeviceController.qx", "utf8"),
{ source },
);
assert.ok(result.ok && result.resource.kind === "interface", JSON.stringify(result.diagnostics));
const iface = result.resource.revision;
const pkg = compileCapabilityResourceSource(
'import interface DeviceController;package Driver id "driver" revision "driver@1" {query Enabled id "enabled" root workspace DeviceController document "enabled.graphql" operation "Enabled" {max rows 100;}}',
{ source, environment: { interfaces: new Map([["DeviceController", iface]]), interfaceClosure: [iface] } },
);
assert.ok(pkg.ok && pkg.resource.kind === "package", JSON.stringify(pkg.diagnostics));
const declaration = pkg.resource.revision.queries![0]!;
const metadata = JSON.stringify({
schemaVersion: 1,
controllers: [
{
id: "driver",
registry: "enabled",
subject: "device-controller@1",
snapshot: "device:snapshot:call",
remote: "device:apply:call",
input: "value",
},
],
});
const check = async (document: string) =>
parseControllerCatalog(metadata, [iface], [await compileQuery(declaration, [iface], async () => document)]);
assert.equal(
(await check("query Enabled {root {objects(all:64,where:{enabled:{eq:true}}) {entries {node {_qx {ref}}}}}}"))
.length,
1,
);
for (const document of [
"query Enabled {root {objects(first:64) {entries {node {_qx {ref}}}}}}",
"query Enabled {root {objects(all:65) {entries {node {_qx {ref}}}}}}",
"query Enabled {root {devices:objects(all:64) {entries {node {_qx {ref}}}}}}",
"query Enabled {root {objects(all:64) {entries {node {enabled}}}}}",
"query Enabled($enabled:Boolean!) {root {objects(all:64,where:{enabled:{eq:$enabled}}) {entries {node {_qx {ref}}}}}}",
])
await assert.rejects(check(document), /registry|Controller/);
assert.throws(() => parseControllerCatalog(metadata, [iface], []), /registry/);
});
test/emit-controllers.ts
+68
View File
@@ -0,0 +1,68 @@
import assert from "node:assert/strict";
import { readFile, mkdir, writeFile } from "node:fs/promises";
import { compileCapabilityResourceSource, compileCapabilitySource } from "../src/capability-language/index.js";
import { compileQuery } from "../src/query/compile.js";
import { parseControllerCatalog } from "../src/capability-model/controllers.js";
import {
compileExecutionPlan,
generateInterfaceClientBindings,
generatePackageQueryClientBindings,
} from "../src/execution-world/index.js";
const read = (file: string) => readFile("test/fixtures/controller-device/" + file, "utf8");
const source = { repository: "https://example.test/device.git", commit: "a".repeat(40) };
const device = compileCapabilityResourceSource(await read("Device.qx"), { source });
assert.ok(device.ok && device.resource.kind === "interface", JSON.stringify(device.diagnostics));
const control = compileCapabilityResourceSource(await read("DeviceController.qx"), { source });
assert.ok(control.ok && control.resource.kind === "interface", JSON.stringify(control.diagnostics));
const iface = device.resource.revision,
controllerInterface = control.resource.revision,
environment = {
interfaces: new Map([
["Device", iface],
["DeviceController", controllerInterface],
]),
interfaceClosure: [iface, controllerInterface],
};
const driver = compileCapabilityResourceSource(await read("Driver.qx"), { source, environment });
assert.ok(driver.ok && driver.resource.kind === "package", JSON.stringify(driver.diagnostics));
const pkg = driver.resource.revision;
pkg.checkedQueries = await Promise.all(
pkg.queries!.map((query) => compileQuery(query, [iface, controllerInterface], read)),
);
pkg.controllers = parseControllerCatalog(
JSON.stringify({
schemaVersion: 1,
controllers: [
{
id: "device-driver",
registry: "enabled",
subject: "device-controller@1",
snapshot: "device:snapshot:call",
remote: "device:apply:call",
input: "value",
},
],
}),
[iface, controllerInterface],
pkg.checkedQueries,
);
for (const variant of ["controller", "controller-next"]) {
const extra = variant.endsWith("next") ? 'atom Dashboard id "dashboard";' : "";
const result = compileCapabilitySource((await read("workspace.qx")).replace(/}\s*$/, extra + "\n}"), "workspace.qx", {
...environment,
packages: new Map([["Driver", pkg]]),
});
assert.ok(result.ok, JSON.stringify(result.diagnostics));
const plan = compileExecutionPlan(result.workspace),
root = "dist/managed/" + variant;
await mkdir(root, { recursive: true });
await writeFile(root + "/client.ts", generateInterfaceClientBindings({ Device: iface }));
await writeFile(root + "/queries.ts", generatePackageQueryClientBindings(pkg));
for (const [file, value] of Object.entries({
"candidate.json": result.workspace,
"execution-plan.json": plan,
"entry.json": null,
"source.json": { kind: "workspace", ...source },
}))
await writeFile(root + "/" + file, JSON.stringify(value));
}
test/emit-managed.ts
+2
View File
@@ -169,3 +169,5 @@ package Owner id "package:owner" revision "package:owner@1" {
}))
await writeFile(`${root}/${file}`, JSON.stringify(value));
}
await import("./emit-controllers.js");
test/fixtures/controller-device/Device.qx
Vendored
+11
View File
@@ -0,0 +1,11 @@
external atom Display id "device:display";
type Request=record {url:string;text:string;version:int32;};
interface Device id "device" revision "device@1" {
static operation create id "device:create" : string -> atom-ref<Display> {call id "device:create:call" execution transaction targets [browser,server];}
queryable value enabled id "device:enabled" : bool {get id "device:enabled:get" execution snapshot targets [browser,server];set id "device:enabled:set" execution transaction targets [browser,server];}
queryable value requested id "device:requested" : Request {get id "device:requested:get" execution snapshot targets [browser,server];}
queryable value observed id "device:observed" : optional<Request> {get id "device:observed:get" execution snapshot targets [browser,server];}
operation requestText id "device:request" : string -> unit {call id "device:request:call" execution transaction targets [browser,server];}
operation recordObservation id "device:record" : Request -> unit {call id "device:record:call" execution transaction targets [server];}
operation remove id "device:remove" : unit -> unit {call id "device:remove:call" execution transaction targets [server];}
}
test/fixtures/controller-device/DeviceController.qx
Vendored
+6
View File
@@ -0,0 +1,6 @@
type Request=record {url:string;text:string;version:int32;};
interface DeviceController id "device-controller" revision "device-controller@1" {
queryable portable value enabled id "controller:enabled" : bool {get id "controller:enabled:get" execution snapshot targets [server];}
operation snapshot id "device:snapshot" : unit -> optional<Request> {call id "device:snapshot:call" execution snapshot targets [server];}
operation apply id "device:apply" : optional<Request> -> unit {call id "device:apply:call" execution remote;}
}
test/fixtures/controller-device/Driver.qx
Vendored
+15
View File
@@ -0,0 +1,15 @@
import interface Device;
import interface DeviceController;
external atom Display id "device:display";
type Request=record {url:string;text:string;version:int32;};
package Driver id "driver" revision "driver@1" {
function create id "driver:create" : string -> atom-ref<Display> execution transaction targets [browser,server] requires {creation device id "device" : Display input record {enabled:bool;requested:Request;observed:optional<Request>;};};
operation request id "driver:request" : string -> unit mode call execution transaction targets [browser,server] receiver any requires {state requested id "requested" : Request [read,write];};
operation snapshot id "driver:snapshot" : unit -> optional<Request> mode call execution snapshot targets [server] receiver any requires {interface data id "data" : Device using [enabled.get,requested.get,observed.get];};
operation recordObservation id "driver:record" : Request -> unit mode call execution transaction targets [server] receiver any requires {state requested id "requested" : Request [read];state observed id "observed" : optional<Request> [write];};
operation apply id "driver:apply" : optional<Request> -> unit mode call execution remote receiver any requires {interface device id "device" : Device using [recordObservation.call];};
operation enabled id "driver:enabled" : unit -> bool mode call execution snapshot targets [server] receiver any requires {interface data id "data" : Device using [enabled.get];};
query Enabled id "enabled" root workspace DeviceController document "enabled.graphql" operation "Enabled" {max rows 64;}
query Inputs id "inputs" root Device document "inputs.graphql" operation "Inputs" {replica;}
query View id "view" root Device document "inputs.graphql" operation "Inputs" {local from Inputs;watch;}
}
test/fixtures/controller-device/enabled.graphql
Vendored
+1
View File
@@ -0,0 +1 @@
query Enabled {root {objects(all:64, where:{enabled:{eq:true}}) {entries {node {_qx {ref}}}}}}
test/fixtures/controller-device/inputs.graphql
Vendored
+1
View File
@@ -0,0 +1 @@
query Inputs {root {enabled requested {url text version} observed {url text version}}}
test/fixtures/controller-device/workspace.qx
Vendored
+25
View File
@@ -0,0 +1,25 @@
workspace Controllers id "workspace:controllers" revision "workspace:controllers@1" commit "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" {
import interface Device;
import interface DeviceController;
import package Driver;
atom Display id "device:display";
conform Display as Device id "display:device" {
private state Enabled id "display:enabled" on Display : bool policy register;
private state Requested id "display:requested" on Display : record {url:string;text:string;version:int32;} policy register;
private state Observed id "display:observed" on Display : optional<record {url:string;text:string;version:int32;}> policy register;
initialize {enabled to state Enabled;requested to state Requested;observed to state Observed;};
bind create.call to package Driver.create with {device to creation Display with {Device from input;};};
bind enabled.get to state Enabled.read;
bind enabled.set to state Enabled.write;
bind requested.get to state Requested.read;
bind observed.get to state Observed.read;
bind requestText.call to package Driver.request with {requested to state Requested;};
bind recordObservation.call to package Driver.recordObservation with {requested to state Requested;observed to state Observed;};
bind remove.call to lifecycle.delete;
}
conform Display as DeviceController id "display:controller" {
bind enabled.get to package Driver.enabled with {data to interface Device;};
bind snapshot.call to package Driver.snapshot with {data to interface Device;};
bind apply.call to package Driver.apply with {device to interface Device;};
}
}