Files
quixos-protocol/src/capability-model/types.ts
T
Timothy J. Aveni 5634d3ee78 Add checked workspace-interface query roots
Implement scoped interface extents across QX, generated bindings, SDK,
Orch, Camino and browser queries. Preserve native projection, aggregation,
pagination and watch invalidation without synthetic persisted objects.
Validate exact query grants and scope freshness on execution and replay.
Add local PostgreSQL, transport, browser and code-generation coverage.

C1 implementation slice only: full-text indexes and Studio search adoption
(C2/C3) remain tracked in the implementation handoff. No publication or deployment.
2026-09-19 10:18:47 -07:00

409 lines
13 KiB
TypeScript

declare const opaqueIdBrand: unique symbol;
type OpaqueId<Kind extends string> = string & {
readonly [opaqueIdBrand]: Kind;
};
export type WorkspaceId = OpaqueId<"WorkspaceId">;
export type WorkspaceRevisionId = OpaqueId<"WorkspaceRevisionId">;
export type AtomId = OpaqueId<"AtomId">;
export type ConformanceId = OpaqueId<"ConformanceId">;
export type InterfaceId = OpaqueId<"InterfaceId">;
export type InterfaceRevisionId = OpaqueId<"InterfaceRevisionId">;
export type MemberId = OpaqueId<"MemberId">;
export type OperationId = OpaqueId<"OperationId">;
export type SlotId = OpaqueId<"SlotId">;
export type EdgeTypeId = OpaqueId<"EdgeTypeId">;
export type EdgeProjectionId = OpaqueId<"EdgeProjectionId">;
export type PackageId = OpaqueId<"PackageId">;
export type PackageRevisionId = OpaqueId<"PackageRevisionId">;
export type PackageExportId = OpaqueId<"PackageExportId">;
export type DependencyPortId = OpaqueId<"DependencyPortId">;
export type ObjectId = OpaqueId<"ObjectId">;
const opaque = <Kind extends string>(value: string) => value as OpaqueId<Kind>;
/**
* Textual IDs remain opaque to the semantic model. Authoring tools may mint
* UUID-backed values later without changing the checked IR.
*/
export const capabilityId = {
workspace: (value: string) => opaque<"WorkspaceId">(value),
workspaceRevision: (value: string) => opaque<"WorkspaceRevisionId">(value),
atom: (value: string) => opaque<"AtomId">(value),
conformance: (value: string) => opaque<"ConformanceId">(value),
interface: (value: string) => opaque<"InterfaceId">(value),
interfaceRevision: (value: string) => opaque<"InterfaceRevisionId">(value),
member: (value: string) => opaque<"MemberId">(value),
operation: (value: string) => opaque<"OperationId">(value),
slot: (value: string) => opaque<"SlotId">(value),
edgeType: (value: string) => opaque<"EdgeTypeId">(value),
edgeProjection: (value: string) => opaque<"EdgeProjectionId">(value),
package: (value: string) => opaque<"PackageId">(value),
packageRevision: (value: string) => opaque<"PackageRevisionId">(value),
packageExport: (value: string) => opaque<"PackageExportId">(value),
dependencyPort: (value: string) => opaque<"DependencyPortId">(value),
object: (value: string) => opaque<"ObjectId">(value),
} as const;
export interface SourceRevision {
repository: string;
commit: string;
}
export type ScalarValueTypeName = "bool" | "bytes" | "double" | "int32" | "int64" | "string" | "uint32" | "uint64";
export type ObjectExpectation =
| { kind: "atom"; atomId: AtomId }
| {
kind: "interface";
interfaceRevisionId: InterfaceRevisionId;
};
export type ValueType =
| { kind: "builtin"; name: "unit" | "watch-handle" }
| { kind: "scalar"; name: ScalarValueTypeName }
| { kind: "message"; descriptorId: string }
| { kind: "record"; fields: Record<string, ValueType> }
| { kind: "object-ref"; expectation: ObjectExpectation }
| { kind: "optional"; value: ValueType }
| { kind: "list"; value: ValueType };
export const valueType = {
unit: { kind: "builtin", name: "unit" } as const,
watchHandle: { kind: "builtin", name: "watch-handle" } as const,
bool: { kind: "scalar", name: "bool" } as const,
bytes: { kind: "scalar", name: "bytes" } as const,
double: { kind: "scalar", name: "double" } as const,
int32: { kind: "scalar", name: "int32" } as const,
int64: { kind: "scalar", name: "int64" } as const,
string: { kind: "scalar", name: "string" } as const,
uint32: { kind: "scalar", name: "uint32" } as const,
uint64: { kind: "scalar", name: "uint64" } as const,
message: (descriptorId: string): ValueType => ({
kind: "message",
descriptorId,
}),
atomRef: (atomId: AtomId): ValueType => ({
kind: "object-ref",
expectation: { kind: "atom", atomId },
}),
interfaceRef: (interfaceRevisionId: InterfaceRevisionId): ValueType => ({
kind: "object-ref",
expectation: { kind: "interface", interfaceRevisionId },
}),
optional: (value: ValueType): ValueType => ({ kind: "optional", value }),
list: (value: ValueType): ValueType => ({ kind: "list", value }),
} as const;
export interface AtomDefinition {
id: AtomId;
displayName: string;
documentation?: string;
}
export type InterfaceOperationMode = "call" | "watch-start" | "watch-stop" | "subscribe" | "unsubscribe";
export interface InterfaceOperation<Type = ValueType> {
id: OperationId;
displayName: string;
inputType: Type;
outputType: Type;
mode: InterfaceOperationMode;
/** Class capabilities have no object receiver and bind free functions. */
scope?: "class";
/** Required for watch-start/subscribe and absent for other modes. */
eventType?: Type;
}
export type QueryReadContract = { execution: "native" | "rpc-permitted" };
interface InterfaceMemberBase<Type = ValueType> {
id: MemberId;
displayName: string;
operations: InterfaceOperation<Type>[];
}
export interface ValueInterfaceMember<Type = ValueType> extends InterfaceMemberBase<Type> {
kind: "value";
queryRead?: QueryReadContract;
valueType: Type;
}
export type EdgeCardinality = "optional-one" | "exactly-one" | "many" | "many-unique";
export type EdgeEndpointConstraint =
| { kind: "atom"; atomId: AtomId }
| {
kind: "interface";
interfaceRevisionId: InterfaceRevisionId;
};
export interface RelationshipInterfaceMember<
Type = ValueType,
Target = EdgeEndpointConstraint,
> extends InterfaceMemberBase<Type> {
kind: "relationship";
queryRead?: QueryReadContract;
target: Target;
cardinality: EdgeCardinality;
ordered: boolean;
keyType?: "string" | "boolean" | "int64";
}
/** A named callable capability that is not value or relationship sugar. */
export interface OperationInterfaceMember<Type = ValueType> extends InterfaceMemberBase<Type> {
kind: "operation";
inputType: Type;
outputType: Type;
}
export type InterfaceMember<Type = ValueType, Target = EdgeEndpointConstraint> =
| ValueInterfaceMember<Type>
| RelationshipInterfaceMember<Type, Target>
| OperationInterfaceMember<Type>;
export interface InterfaceRevision {
interfaceId: InterfaceId;
revisionId: InterfaceRevisionId;
displayName: string;
source: SourceRevision;
members: InterfaceMember[];
/** Authored generic definition; never an executable contract by itself. */
template?: import("./generics.js").GenericInterfaceTemplate;
/** Immutable provenance of a closed generic application. */
application?: import("./generics.js").AppliedInterfaceIdentity;
requiredInterfaces?: InterfaceRevisionId[];
argumentRequirements?: { target: ObjectExpectation; required: InterfaceRevisionId }[];
}
export type StoragePolicy = { kind: "optimistic-register" } | { kind: "crdt-document"; updateType: ValueType };
export interface StateSlotDefinition {
kind: "state";
id: SlotId;
attachedTo: AtomId;
displayName: string;
valueType: ValueType;
storagePolicy: StoragePolicy;
defaultValue?: unknown;
}
export interface EdgeEndpoint {
keyType?: "string" | "boolean" | "int64";
publicTraversal?: boolean;
projectionId: EdgeProjectionId;
displayName: string;
constraint: EdgeEndpointConstraint;
cardinality: EdgeCardinality;
ordered: boolean;
onDelete?: "restrict" | "detach" | "cascade-other";
retainOther?: boolean;
}
export interface EdgeDefinition {
kind: "edge";
id: EdgeTypeId;
displayName: string;
endpoints: [EdgeEndpoint, EdgeEndpoint];
}
export type PersistentAttachment = StateSlotDefinition | EdgeDefinition;
export type StatePrimitive = "read" | "write" | "watch-start" | "watch-stop";
export type EdgePrimitive = "resolve" | "connect" | "disconnect" | "watch-start" | "watch-stop";
export type PackageReceiverRequirement =
| { kind: "any-object" }
| { kind: "exact-atom"; atomId: AtomId }
| {
kind: "all-interfaces";
interfaceRevisionIds: InterfaceRevisionId[];
};
export type DependencyPortRequirement =
| { kind: "query"; packageRevisionId: PackageRevisionId; queryId: string }
| {
kind: "state";
valueType: ValueType;
primitives: StatePrimitive[];
}
| {
kind: "edge";
target: EdgeEndpointConstraint;
cardinality: EdgeCardinality;
primitives: EdgePrimitive[];
}
| {
kind: "interface";
interfaceRevisionId: InterfaceRevisionId;
}
| { kind: "constructor"; atomId: AtomId; inputType?: ValueType };
export interface DependencyPort {
id: DependencyPortId;
displayName: string;
requirement: DependencyPortRequirement;
}
interface PackageExportBase {
id: PackageExportId;
displayName: string;
inputType: ValueType;
outputType: ValueType;
dependencyPorts: DependencyPort[];
/** Closed adapter served by the same immutable package build. */
application?: { exportId: PackageExportId; arguments: import("./generics.js").ClosedTypeArgument[]; self?: AtomId };
}
export interface PackageOperationExport extends PackageExportBase {
kind: "operation";
mode: InterfaceOperationMode;
eventType?: ValueType;
receiverRequirement: PackageReceiverRequirement;
}
export interface PackageFunctionExport extends PackageExportBase {
kind: "function";
}
export interface PackageConstructorExport extends PackageExportBase {
kind: "constructor";
constructsAtom: AtomId;
}
export type PackageExport = PackageOperationExport | PackageFunctionExport | PackageConstructorExport;
export interface PackageRevision {
queries?: import("../query/types.js").QueryDeclaration[];
checkedQueries?: import("../query/types.js").CheckedQuery[];
queryTemplates?: import("../query/types.js").QueryTemplate[];
genericExports?: import("./generic-packages.js").GenericPackageExport[];
argumentRequirements?: { target: ObjectExpectation; required: InterfaceRevisionId }[];
migrationCatalog?: import("./migrations.js").MigrationCatalog;
packageId: PackageId;
revisionId: PackageRevisionId;
displayName: string;
source: SourceRevision;
exports: PackageExport[];
/** Author-declared implementation semantics; omitted legacy values mean 1. */
semanticMajor?: number;
}
export type DependencyBinding =
| {
kind: "query";
packageRevisionId: PackageRevisionId;
queryId: string;
scope: "object" | "workspace";
via?: EdgeTraversal;
}
| { kind: "state"; slotId: SlotId; via?: EdgeTraversal }
| {
kind: "edge";
edgeTypeId: EdgeTypeId;
projectionId: EdgeProjectionId;
via?: EdgeTraversal;
}
| {
kind: "interface";
interfaceRevisionId: InterfaceRevisionId;
via?: EdgeTraversal;
}
| { kind: "constructor"; atomId: AtomId };
export interface BoundDependency {
portId: DependencyPortId;
binding: DependencyBinding;
}
/** Selects the object at the other end of an exactly-one relationship. */
export interface EdgeTraversal {
edgeTypeId: EdgeTypeId;
projectionId: EdgeProjectionId;
}
/**
* Provisional get-or-create recipe for a relationship implementation. The
* host projection is supplied by the relationship's resolve binding; this
* projection originates at the object constructed for the relationship.
*/
export interface RelationshipMaterialization {
memberId: MemberId;
constructorAtomId: AtomId;
edgeTypeId: EdgeTypeId;
constructedProjectionId: EdgeProjectionId;
}
export type Binding =
| {
kind: "state";
slotId: SlotId;
primitive: StatePrimitive;
}
| {
kind: "edge";
edgeTypeId: EdgeTypeId;
projectionId: EdgeProjectionId;
primitive: EdgePrimitive;
}
| {
kind: "package";
packageRevisionId: PackageRevisionId;
exportId: PackageExportId;
dependencies: BoundDependency[];
};
export interface OperationBinding {
operationId: OperationId;
binding: Binding;
/** Required for package-backed reads of an RPC-permitted queryable field. */
queryReason?: string;
}
export interface Conformance {
/** Absent only for legacy assemblies awaiting explicit ownership enrollment. */
id?: ConformanceId;
semanticMajor?: number;
atomId: AtomId;
interfaceRevisionId: InterfaceRevisionId;
privateAttachments: PersistentAttachment[];
operationBindings: OperationBinding[];
relationshipMaterializations: RelationshipMaterialization[];
}
export interface AtomConstructorBinding {
atomId: AtomId;
packageRevisionId: PackageRevisionId;
exportId: PackageExportId;
dependencies: BoundDependency[];
}
export interface WorkspaceRevision {
linkedQueries?: import("../query/link.js").LinkedQuery[];
id: WorkspaceRevisionId;
workspaceId: WorkspaceId;
parentRevisionIds: WorkspaceRevisionId[];
sourceRootCommit: string;
atoms: AtomDefinition[];
sharedAttachments: PersistentAttachment[];
interfaceImports: InterfaceRevision[];
packageImports: PackageRevision[];
conformances: Conformance[];
constructors: AtomConstructorBinding[];
}
export type AttachmentOwner =
| { kind: "workspace" }
| {
kind: "conformance";
atomId: AtomId;
interfaceRevisionId: InterfaceRevisionId;
};
export interface OwnedAttachment {
attachment: PersistentAttachment;
owner: AttachmentOwner;
}