Timothy J. Aveni
e8d19d2bb7
Project source-free capability contracts and keep exact source provenance in package assembly. Reuse compiled groups across unrelated graph and dependency implementation edits. Keep React public inputs separate from workspace query lowering and retain explicit type-companion dependencies. Allow independent execution-package checks, scope resource compilation to declared dependencies, and memoize source closure traversal. Document generic-specialization limits and measured Reader rebuild behavior. Verified protocol, artifact, package, React, and managed activation checks; retained-Git independent/workspace artifact equality and incompatible type dependency rejection; nix fmt -- --check and lint. One-off Reader measurements recompiled 1 of 13 groups for a child edit and 0 for a workspace QX default edit.
449 lines
21 KiB
TypeScript
449 lines
21 KiB
TypeScript
import type {
|
|
InterfaceRevision,
|
|
PackageRevision,
|
|
ValueType,
|
|
DependencyPort,
|
|
WorkspaceRevision,
|
|
} from "../capability-model/types.js";
|
|
import type { CompiledCapabilityResourceRepository } from "../capability-language/assembly.js";
|
|
import { genericImplementationType } from "./generics.js";
|
|
import { capabilityId } from "../capability-model/types.js";
|
|
|
|
/** Source-free package compilation inputs. Nominal references do not import
|
|
* implementations or concrete workspace conformances. */
|
|
export type BindingContractSchema = {
|
|
format: "quixos-bindings";
|
|
version: 1;
|
|
interfaces: Omit<InterfaceRevision, "source">[];
|
|
packages: Pick<PackageRevision, "revisionId" | "exports" | "genericExports">[];
|
|
};
|
|
/** Portable generator input. New backends consume this instead of the parser or TS runtime. */
|
|
export type BindingSchema = {
|
|
format: "quixos-bindings";
|
|
version: 1;
|
|
interfaces: InterfaceRevision[];
|
|
interfaceTemplates?: InterfaceRevision[];
|
|
packages: PackageRevision[];
|
|
};
|
|
export const bindingSchema = (
|
|
compiled: Pick<CompiledCapabilityResourceRepository, "resources"> &
|
|
Partial<Pick<CompiledCapabilityResourceRepository, "capabilityResources">>,
|
|
): BindingSchema => ({
|
|
format: "quixos-bindings",
|
|
version: 1,
|
|
interfaceTemplates: (compiled.capabilityResources ?? compiled.resources).flatMap((node) =>
|
|
node.resource.kind === "interface" && node.resource.revision.template ? [node.resource.revision] : [],
|
|
),
|
|
interfaces: [
|
|
...new Map(
|
|
(compiled.capabilityResources ?? compiled.resources)
|
|
.flatMap((node) => [
|
|
...(node.resource.kind === "interface" ? [node.resource.revision] : []),
|
|
...(node.resource.kind === "build" ? [] : (node.resource.specializations ?? [])),
|
|
])
|
|
.filter((entry) => !entry.template)
|
|
.map((entry) => [entry.revisionId, entry]),
|
|
).values(),
|
|
],
|
|
packages: (compiled.capabilityResources ?? compiled.resources).flatMap((node) =>
|
|
node.resource.kind === "package" ? [node.resource.revision] : [],
|
|
),
|
|
});
|
|
|
|
export const specializeBindingSchema = (
|
|
base: BindingSchema,
|
|
workspace: WorkspaceRevision,
|
|
revisionId: string,
|
|
): BindingSchema => {
|
|
const pkg = workspace.packageImports.find((entry) => entry.revisionId === revisionId);
|
|
if (!pkg) throw new Error(`Missing candidate package ${revisionId}`);
|
|
const needed = new Set<string>();
|
|
const visit = (value: unknown): void => {
|
|
if (!value || typeof value !== "object") return;
|
|
if ("interfaceRevisionId" in value && typeof value.interfaceRevisionId === "string")
|
|
needed.add(value.interfaceRevisionId);
|
|
Object.values(value).forEach(visit);
|
|
};
|
|
visit(pkg.exports);
|
|
const interfaces = new Map<string, InterfaceRevision>(base.interfaces.map((entry) => [entry.revisionId, entry]));
|
|
for (const id of needed) {
|
|
const iface = workspace.interfaceImports.find((entry) => entry.revisionId === id);
|
|
if (iface) {
|
|
interfaces.set(id, iface);
|
|
visit(iface.members);
|
|
}
|
|
}
|
|
return {
|
|
...base,
|
|
interfaces: [...interfaces.values()],
|
|
packages: base.packages.map((entry) => {
|
|
const candidate = workspace.packageImports.find((value) => value.revisionId === entry.revisionId);
|
|
if (!candidate) throw new Error(`Missing dependency package ${entry.revisionId}`);
|
|
return candidate;
|
|
}),
|
|
};
|
|
};
|
|
export type TypeScriptBindingOptions = {
|
|
runtimeModule?: string;
|
|
/** Each export must implement MessageBinding<T>, providing both TS type and wire codec. */
|
|
messages?: Record<string, { module: string; export: string }>;
|
|
};
|
|
export function generatePackageDescriptor(schema: BindingSchema, revisionId: string): string {
|
|
const pkg = schema.packages.find((entry) => entry.revisionId === revisionId);
|
|
if (!pkg) throw new Error(`Unknown package revision ${revisionId}`);
|
|
return (
|
|
`# Generated from the checked package contract\npackage_id: ${JSON.stringify(pkg.packageId)}\npackage_revision_id: ${JSON.stringify(pkg.revisionId)}\nruntime_protocol_version: "quixos-capabilities-v1"\n` +
|
|
pkg.exports
|
|
.map(
|
|
(entry) =>
|
|
`exports: { export_id: ${JSON.stringify(entry.id)} runtime_symbol: ${JSON.stringify(entry.displayName)} }\n`,
|
|
)
|
|
.join("")
|
|
);
|
|
}
|
|
const q = JSON.stringify;
|
|
const object = (entries: [string, string][]) =>
|
|
`{ ${entries.map(([key, value]) => `${q(key)}: ${value}`).join("; ")} }`;
|
|
const unit = (type: ValueType) => type.kind === "builtin" && type.name === "unit";
|
|
|
|
export const generateTypeScriptBindings = (
|
|
schema: BindingSchema,
|
|
packageRevisionId: string,
|
|
options: TypeScriptBindingOptions = {},
|
|
) => {
|
|
if (schema.format !== "quixos-bindings" || schema.version !== 1)
|
|
throw new Error("Unsupported binding schema version");
|
|
if (schema.interfaces.some((entry) => entry.template))
|
|
throw new Error("Package bindings require closed interface applications, not generic definitions");
|
|
const pkg = schema.packages.find((entry) => entry.revisionId === packageRevisionId);
|
|
if (!pkg) throw new Error(`Unknown package revision ${packageRevisionId}`);
|
|
const messages = new Map<string, string>();
|
|
const type = (value: ValueType): string => {
|
|
switch (value.kind) {
|
|
case "variant":
|
|
throw new Error("Variants require the Camino portable value runtime; legacy RPC bindings are unsupported");
|
|
case "builtin":
|
|
return value.name === "unit" ? "null" : "QxWatchHandle";
|
|
case "scalar":
|
|
return {
|
|
bool: "boolean",
|
|
bytes: "Uint8Array",
|
|
string: "string",
|
|
int64: "bigint",
|
|
uint64: "bigint",
|
|
double: "number",
|
|
int32: "number",
|
|
uint32: "number",
|
|
}[value.name];
|
|
case "object-ref":
|
|
return `QxObjectRef<${q(value.expectation.kind === "atom" ? `atom:${value.expectation.atomId}` : `interface:${value.expectation.interfaceRevisionId}`)}>`;
|
|
case "change":
|
|
throw new Error("CRDT change values require the prepared-change codec and runtime (LF-19)");
|
|
case "optional":
|
|
return `(${type(value.value)} | null)`;
|
|
case "list":
|
|
return `Array<${type(value.value)}>`;
|
|
case "record":
|
|
return `{ ${Object.entries(value.fields)
|
|
.map(([name, field]) => `${q(name)}: ${type(field)}`)
|
|
.join("; ")} }`;
|
|
case "message": {
|
|
if (!options.messages?.[value.descriptorId])
|
|
throw new Error(`Missing TypeScript message binding for ${value.descriptorId}`);
|
|
if (!messages.has(value.descriptorId)) messages.set(value.descriptorId, `message${messages.size}`);
|
|
return `BindingValue<typeof ${messages.get(value.descriptorId)}>`;
|
|
}
|
|
}
|
|
};
|
|
const ref = (target: { kind: "atom"; atomId: string } | { kind: "interface"; interfaceRevisionId: string }) =>
|
|
`QxObjectRef<${q(target.kind === "atom" ? `atom:${target.atomId}` : `interface:${target.interfaceRevisionId}`)}>`;
|
|
const params = (input: ValueType) => (unit(input) ? "" : `input: ${type(input)}`);
|
|
const port = (entry: DependencyPort): { type: string; spec: unknown } => {
|
|
const requirement = entry.requirement;
|
|
switch (requirement.kind) {
|
|
case "reflection":
|
|
return {
|
|
type: `QxReflectionPort<${requirement.selectors.map((value) => q(value)).join(" | ")}>`,
|
|
spec: { kind: "reflection", id: entry.id, selectors: requirement.selectors },
|
|
};
|
|
case "query": {
|
|
const query = schema.packages
|
|
.find((candidate) => candidate.revisionId === requirement.packageRevisionId)
|
|
?.checkedQueries?.find((query) => query.declaration.id === requirement.queryId);
|
|
if (!query) throw new Error(`Missing checked query ${requirement.packageRevisionId}:${requirement.queryId}`);
|
|
return {
|
|
type: object([
|
|
["execute", `(variables: ${type(query.variables)}) => Promise<${type(query.output)}>`],
|
|
...(query.declaration.watch
|
|
? ([
|
|
[
|
|
"watch",
|
|
`(variables: ${type(query.variables)}, signal: AbortSignal) => AsyncIterable<QxQuerySnapshot<${type(query.output)}>>`,
|
|
],
|
|
] as [string, string][])
|
|
: []),
|
|
]),
|
|
spec: {
|
|
kind: "query",
|
|
id: entry.id,
|
|
definitionDigest: query.definitionDigest,
|
|
variables: query.variables,
|
|
output: query.output,
|
|
watch: query.declaration.watch,
|
|
},
|
|
};
|
|
}
|
|
case "state": {
|
|
const methods = requirement.primitives.map((primitive): [string, string] => {
|
|
if (primitive === "read") return ["get", `() => Promise<${type(requirement.valueType)}>`];
|
|
if (primitive === "write") return ["set", `(value: ${type(requirement.valueType)}) => Promise<void>`];
|
|
throw new Error(`State primitive ${primitive} is not supported by the TypeScript runtime binding yet`);
|
|
});
|
|
if (requirement.primitives.includes("read")) methods.push(["live", "() => Promise<QxLiveValue>"]);
|
|
return { type: object(methods), spec: { ...requirement, id: entry.id } };
|
|
}
|
|
case "edge": {
|
|
const methods = requirement.primitives.map((primitive): [string, string] => {
|
|
if (primitive === "resolve") return [primitive, `() => Promise<Array<${ref(requirement.target)}>>`];
|
|
if (primitive === "connect" || primitive === "disconnect")
|
|
return [primitive, `(target: ${ref(requirement.target)}) => Promise<void>`];
|
|
throw new Error(`Edge primitive ${primitive} is not supported by the TypeScript runtime binding yet`);
|
|
});
|
|
if (requirement.primitives.includes("resolve"))
|
|
methods.push(["collection", `() => Promise<RelationshipCollection<${ref(requirement.target)}>>`]);
|
|
if (
|
|
["resolve", "connect", "disconnect"].every((primitive) =>
|
|
requirement.primitives.includes(primitive as "resolve"),
|
|
)
|
|
)
|
|
methods.push([
|
|
"replace",
|
|
`(entries: RelationshipEntry<${ref(requirement.target)}>[], expectedRevision: bigint) => Promise<RelationshipCollection<${ref(requirement.target)}>>`,
|
|
]);
|
|
return { type: object(methods), spec: { kind: "edge", id: entry.id, primitives: requirement.primitives } };
|
|
}
|
|
case "interface": {
|
|
const contract = schema.interfaces.find(
|
|
(candidate) => candidate.revisionId === requirement.interfaceRevisionId,
|
|
);
|
|
if (!contract) throw new Error(`Missing imported interface contract ${requirement.interfaceRevisionId}`);
|
|
// Streaming ports need a future streaming ABI; ordinary calls are fully typed today.
|
|
const operations = contract.members.flatMap((member) =>
|
|
member.operations
|
|
.filter(
|
|
(operation) =>
|
|
operation.mode === "call" &&
|
|
operation.scope !== "class" &&
|
|
(!requirement.operations || requirement.operations.includes(operation.id)),
|
|
)
|
|
.map((operation) => ({ ...operation, name: `${member.displayName}.${operation.displayName}` })),
|
|
);
|
|
const methods: [string, string][] = [
|
|
["objectId", ref({ kind: "interface", interfaceRevisionId: requirement.interfaceRevisionId })],
|
|
[
|
|
"live",
|
|
object(
|
|
operations.map((operation) => [
|
|
operation.name,
|
|
`(${params(operation.inputType)}) => Promise<QxLiveValue>`,
|
|
]),
|
|
),
|
|
],
|
|
...operations.map((operation): [string, string] => [
|
|
operation.name,
|
|
`(${params(operation.inputType)}) => Promise<${type(operation.outputType)}>`,
|
|
]),
|
|
];
|
|
return {
|
|
type: object([...methods, ["contract", `QxInterfaceContract<${object(methods)}>`]]),
|
|
spec: {
|
|
kind: "interface",
|
|
id: entry.id,
|
|
interfaceRevisionId: requirement.interfaceRevisionId,
|
|
operations: Object.fromEntries(
|
|
operations.map(({ name, id, inputType, outputType }) => [name, { id, inputType, outputType }]),
|
|
),
|
|
},
|
|
};
|
|
}
|
|
case "creation":
|
|
throw new Error("Creation ports require the portable transaction context generator (LF-09)");
|
|
case "constructor": {
|
|
const input = requirement.inputType;
|
|
if (!input)
|
|
throw new Error(
|
|
`Constructor port ${entry.id} needs an explicit input contract: add 'input TYPE' after ${requirement.atomId} in QX`,
|
|
);
|
|
return {
|
|
type: object([
|
|
["construct", `(${params(input)}) => Promise<${ref({ kind: "atom", atomId: requirement.atomId })}>`],
|
|
]),
|
|
spec: { kind: "constructor", id: entry.id, inputType: input },
|
|
};
|
|
}
|
|
}
|
|
};
|
|
const exports = [...pkg.exports].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
|
|
const names = new Set<string>();
|
|
const specs: Record<string, unknown> = {};
|
|
const contexts: [string, string][] = [];
|
|
const handlers: [string, string][] = [];
|
|
const results: [string, string][] = [];
|
|
for (const entry of exports) {
|
|
if (names.has(entry.displayName)) throw new Error(`Duplicate export name ${entry.displayName}`);
|
|
names.add(entry.displayName);
|
|
const ports = entry.dependencyPorts.map((dependency) => ({ name: dependency.displayName, ...port(dependency) }));
|
|
if (new Set(ports.map((p) => p.name)).size !== ports.length)
|
|
throw new Error(`Duplicate dependency name in ${entry.displayName}`);
|
|
const receiver =
|
|
entry.kind === "constructor"
|
|
? ref({ kind: "atom", atomId: entry.constructsAtom })
|
|
: entry.kind === "operation" && entry.receiverRequirement.kind === "exact-atom"
|
|
? ref({ kind: "atom", atomId: entry.receiverRequirement.atomId })
|
|
: entry.kind === "operation" && entry.receiverRequirement.kind === "all-interfaces"
|
|
? `QxObjectRef<${entry.receiverRequirement.interfaceRevisionIds.map((id) => q(`interface:${id}`)).join(" | ") || "never"}>`
|
|
: "QxObjectRef<string>";
|
|
const contextShape = object([
|
|
["conform", "QxConformer"],
|
|
...(entry.kind === "function" ? [] : [["objectId", receiver] as [string, string]]),
|
|
["input", type(entry.inputType)],
|
|
["ports", object(ports.map((port) => [port.name, port.type]))],
|
|
]);
|
|
contexts.push([
|
|
entry.displayName,
|
|
entry.kind === "function"
|
|
? `${contextShape} & {signal?: AbortSignal}`
|
|
: `${contextShape} & QxContextLifecycle<${contextShape} & {signal?: AbortSignal}>`,
|
|
]);
|
|
const event = entry.kind === "operation" ? entry.eventType : undefined;
|
|
const contextType = `Contexts[${q(entry.displayName)}]`;
|
|
const outputType = type(event ?? entry.outputType);
|
|
results.push([entry.displayName, outputType]);
|
|
// Watch-start handlers produce events through the runtime's derived stream protocol.
|
|
if (!entry.application)
|
|
handlers.push([
|
|
entry.displayName,
|
|
event
|
|
? `QxDerived<${contextType}, ${outputType}>`
|
|
: `QxHandler<${contextType}, ${outputType}>${entry.kind === "operation" && entry.mode === "call" ? ` | QxDerived<${contextType}, ${outputType}>` : ""}`,
|
|
]);
|
|
specs[entry.displayName] = {
|
|
...(entry.kind === "function" ? { receiver: "none" } : {}),
|
|
inputType: entry.inputType,
|
|
outputType: entry.outputType,
|
|
...(event ? { eventType: event } : {}),
|
|
ports: Object.fromEntries(ports.map((port) => [port.name, port.spec])),
|
|
};
|
|
}
|
|
for (const definition of pkg.genericExports ?? []) {
|
|
handlers.push([
|
|
definition.displayName,
|
|
genericImplementationType(
|
|
definition,
|
|
[...schema.interfaces, ...(schema.interfaceTemplates ?? [])],
|
|
type,
|
|
(requirement) => port({ id: capabilityId.dependencyPort("query"), displayName: "query", requirement }).type,
|
|
),
|
|
]);
|
|
}
|
|
// Unused imported interfaces must not introduce new message-codec obligations.
|
|
// A used port still fails above if its own required codec is missing.
|
|
const hasCodec = (value: ValueType): boolean => {
|
|
if (value.kind === "message") return !!options.messages?.[value.descriptorId];
|
|
if (value.kind === "variant") return false;
|
|
if (value.kind === "record") return Object.values(value.fields).every(hasCodec);
|
|
if (value.kind === "list" || value.kind === "optional") return hasCodec(value.value);
|
|
return true;
|
|
};
|
|
const contracts = schema.interfaces
|
|
.filter((iface) =>
|
|
iface.members.every((member) =>
|
|
member.operations
|
|
.filter((operation) => operation.mode === "call" && operation.scope !== "class")
|
|
.every((operation) => hasCodec(operation.inputType) && hasCodec(operation.outputType)),
|
|
),
|
|
)
|
|
.map((iface) => {
|
|
const generated = port({
|
|
id: capabilityId.dependencyPort("contract"),
|
|
displayName: iface.displayName,
|
|
requirement: { kind: "interface", interfaceRevisionId: iface.revisionId },
|
|
});
|
|
const spec = generated.spec as { operations: unknown };
|
|
return {
|
|
iface,
|
|
type: generated.type,
|
|
code: `defineQxInterfaceContract<${generated.type}>(${q(iface.revisionId)}, ${JSON.stringify(spec.operations)})`,
|
|
};
|
|
});
|
|
const imports = [...messages].map(([id, alias]) => {
|
|
const binding = options.messages![id]!;
|
|
if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(binding.export))
|
|
throw new Error(`Invalid message binding export ${binding.export}`);
|
|
return `import { ${binding.export} as ${alias} } from ${q(binding.module)};`;
|
|
});
|
|
const queryVariables = object(
|
|
(pkg.checkedQueries ?? []).map((query) => [query.declaration.displayName, type(query.variables)]),
|
|
);
|
|
const queryResults = object(
|
|
(pkg.checkedQueries ?? []).map((query) => [query.declaration.displayName, type(query.output)]),
|
|
);
|
|
const queryDescriptors = object(
|
|
(pkg.checkedQueries ?? []).map((query) => [
|
|
query.declaration.displayName,
|
|
`QxQueryDescriptor<QueryVariables[${q(query.declaration.displayName)}], QueryResults[${q(query.declaration.displayName)}], ${q(query.declaration.root)}>`,
|
|
]),
|
|
);
|
|
const signatures = `${object(contexts)} ${object(handlers)} ${object(results)} ${queryVariables} ${queryResults} ${queryDescriptors} ${contracts.map((entry) => entry.type).join(" ")}`;
|
|
const typeImports = [
|
|
"BindingValue",
|
|
"QxObjectRef",
|
|
"QxWatchHandle",
|
|
"QxHandler",
|
|
"QxDerived",
|
|
"QxContextLifecycle",
|
|
"QxConformer",
|
|
"QxInterfaceContract",
|
|
"QxLiveValue",
|
|
"RelationshipCollection",
|
|
"RelationshipEntry",
|
|
"QxQuerySnapshot",
|
|
"QxReflectionPort",
|
|
"QxQueryDescriptor",
|
|
].filter((name) => new RegExp(`\\b${name}\\b`).test(signatures));
|
|
return (
|
|
`// Generated by quixos-codegen-ts. Do not edit. Binding ABI version 1.\n` +
|
|
`import { ${contracts.length ? "defineQxInterfaceContract, " : ""}${exports.length ? "bindQxHandler, " : ""}${[...typeImports, "QxHandlerSpec", "QxMessages"].map((name) => `type ${name}`).join(", ")} } from ${q(options.runtimeModule ?? "@quixos/camino-package-runtime")};\n` +
|
|
imports.join("\n") +
|
|
`\nexport const packageRevisionId = ${q(pkg.revisionId)};\n` +
|
|
`declare const appliedType: unique symbol;\ntype QxApplied<Definition extends string, Arguments extends readonly unknown[]> = string & {readonly [appliedType]: (value: [Definition, Arguments]) => [Definition, Arguments]};\n` +
|
|
`export type Contexts = ${object(contexts)};\nexport type Results = ${object(results)};\nexport type Implementation = ${object(handlers)};\n` +
|
|
`export type QueryVariables = ${queryVariables};\nexport type QueryResults = ${queryResults};\n` +
|
|
`export const queries: ${queryDescriptors} = ${JSON.stringify(Object.fromEntries((pkg.checkedQueries ?? []).map((query) => [query.declaration.displayName, { id: `${pkg.revisionId}:${query.declaration.id}`, definitionDigest: query.definitionDigest, root: query.declaration.root, variables: query.variables, output: query.output, watch: query.declaration.watch }])), null, 2)} as const;\n` +
|
|
`export const contracts = {${contracts.map((entry) => `${q(entry.iface.revisionId)}: ${entry.code}`).join(",\n")}};\n` +
|
|
`export const interfaces = {${contracts
|
|
.filter((entry) => contracts.filter((other) => other.iface.displayName === entry.iface.displayName).length === 1)
|
|
.map((entry) => `${q(entry.iface.displayName)}: contracts[${q(entry.iface.revisionId)}]`)
|
|
.join(",\n")}};\n` +
|
|
`const messages = { ${[...messages].map(([id, alias]) => `${q(id)}: ${alias}`).join(", ")} } satisfies QxMessages;\n` +
|
|
`const specs = ${JSON.stringify(specs, null, 2)} satisfies Record<string, QxHandlerSpec>;\n` +
|
|
`export const createRuntime = (implementation: Implementation) => ({\n packageRevisionId,\n exports: {\n` +
|
|
exports
|
|
.map(
|
|
(entry) =>
|
|
` ${q(entry.id)}: bindQxHandler(specs[${q(entry.displayName)}], implementation[${q(entry.application ? pkg.genericExports!.find((definition) => definition.id === entry.application!.exportId)!.displayName : entry.displayName)}], messages),`,
|
|
)
|
|
.join("\n") +
|
|
`\n },\n});\n`
|
|
);
|
|
};
|
|
|
|
export {
|
|
generatePortableTypeScriptBindings,
|
|
generateRemoteTypeScriptBindings,
|
|
portableValueSchema,
|
|
PortableBindingError,
|
|
type PortableBindingOptions,
|
|
} from "./portable.js";
|
|
export * from "./portable-client.js";
|