quixos-protocol/src/capability-model/types.ts

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 }
  | { kind: "change"; 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";

/** Omission has remote semantics; availability never strengthens an imported contract. */
export type ExecutionContract = { kind: "remote" } | { kind: "snapshot" | "transaction"; targets: string[] };

export interface InterfaceOperation<Type = ValueType> {
  execution?: ExecutionContract;
  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" | "portable" };

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: "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" | "edit" | "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: "reflection"; selectors: string[] }
  | { kind: "query"; packageRevisionId: PackageRevisionId; queryId: string }
  | {
      kind: "state";
      valueType: ValueType;
      primitives: StatePrimitive[];
    }
  | {
      kind: "edge";
      target: EdgeEndpointConstraint;
      cardinality: EdgeCardinality;
      primitives: EdgePrimitive[];
    }
  | {
      kind: "interface";
      interfaceRevisionId: InterfaceRevisionId;
      /** Exact public operation identities, not implementation export names. */
      operations?: OperationId[];
      receiver?: "input";
    }
  | { kind: "creation"; atomId: AtomId; inputType: ValueType }
  | { kind: "constructor"; atomId: AtomId; inputType?: ValueType };

export interface DependencyPort {
  id: DependencyPortId;
  displayName: string;
  requirement: DependencyPortRequirement;
}

interface PackageExportBase {
  /** Required authoritative snapshot export in this package. */
  acceptanceExportId?: PackageExportId;
  execution?: ExecutionContract;
  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: "reflection"; selectors: string[]; via?: never }
  | {
      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;
      receiver?: "input";
    }
  | {
      kind: "creation";
      atomId: AtomId;
      owners: { interfaceRevisionId: InterfaceRevisionId; inputPath: string[] }[];
      via?: never;
    }
  | { 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: "lifecycle"; primitive: "delete" }
  | {
      kind: "interface";
      interfaceRevisionId: InterfaceRevisionId;
      operationId: OperationId;
    }
  | {
      kind: "state";
      slotId: SlotId;
      primitive: StatePrimitive;
    }
  | {
      kind: "edge";
      edgeTypeId: EdgeTypeId;
      projectionId: EdgeProjectionId;
      primitive: EdgePrimitive;
    }
  | {
      kind: "package";
      packageRevisionId: PackageRevisionId;
      exportId: PackageExportId;
      dependencies: BoundDependency[];
      acceptanceDependencies?: BoundDependency[];
    };

export interface OperationBinding {
  operationId: OperationId;
  binding: Binding;
  /** Required for package-backed reads of an RPC-permitted queryable field. */
  queryReason?: string;
}

export interface InitializationField {
  input: string;
  binding: { kind: "state"; slotId: SlotId } | { kind: "edge"; edgeTypeId: EdgeTypeId; projectionId: EdgeProjectionId };
}

export interface Conformance {
  initialization?: InitializationField[];
  /** 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;
}