Timothy J. Aveni
1e72713ae2
Add checked native journal/subscription bindings, managed-reference retention, bounded history and backpressure, atomic delivery receipts, and fenced hosting. Preserve source publication prediction and replica reconciliation; subscription attachment, controls, and delivery remain authoritative in this initial version. Connect independent manual/Gutenberg document producers to Reader bookshelves through typed adapters. Add connection inspection, shared provider selection, authoring documentation, and restart/rejection/fan-out integration coverage. Verified compiler suite (287 passed, two existing skips), Nix runtime and PostgreSQL qualification, five example assemblies, headless Reader integration, Chromium Reader integration, resource pins, formatting, and lint. No pinned workspace runtime was deployed.
520 lines
17 KiB
TypeScript
520 lines
17 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: "variant"; id: string; cases: Record<string, { id: string; value: 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";
|
|
/** Every operation resolves directly to the same native state slot. */
|
|
nativeField?: true;
|
|
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;
|
|
}
|
|
|
|
/** A typed code artifact. Module bindings are neither calls nor storage fields. */
|
|
export interface ModuleInterfaceMember<
|
|
Type = ValueType,
|
|
Target = EdgeEndpointConstraint,
|
|
> extends InterfaceMemberBase<Type> {
|
|
kind: "module";
|
|
contract: string;
|
|
subject?: Target;
|
|
}
|
|
|
|
export type InterfaceMember<Type = ValueType, Target = EdgeEndpointConstraint> =
|
|
| ValueInterfaceMember<Type>
|
|
| RelationshipInterfaceMember<Type, Target>
|
|
| OperationInterfaceMember<Type>
|
|
| ModuleInterfaceMember<Type, Target>;
|
|
|
|
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 interface JournalStorageLimits {
|
|
maxEntries: number;
|
|
maxBytes: number;
|
|
maxPublicationBytes: number;
|
|
maxProtectedSubscriptions: number;
|
|
}
|
|
export type StoragePolicy =
|
|
| { kind: "register" }
|
|
| { kind: "crdt-document"; updateType: ValueType }
|
|
| { kind: "journal"; limits: JournalStorageLimits }
|
|
| { kind: "subscription"; payload: ValueType };
|
|
export type JournalPrimitive = "publish" | "readPage" | "head";
|
|
export type SubscriptionPrimitive = "attach" | "status" | "pause" | "resume" | "retire";
|
|
|
|
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;
|
|
keyType?: "string" | "boolean" | "int64";
|
|
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 {
|
|
/** Returns this declared birth, with unchanged operation input as its initializer. */
|
|
preparation?: { port: DependencyPortId; key: string };
|
|
/** 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 PackageModule {
|
|
id: string;
|
|
displayName: string;
|
|
interfaceRevisionId: InterfaceRevisionId;
|
|
memberId: MemberId;
|
|
}
|
|
|
|
export interface ModuleBinding {
|
|
memberId: MemberId;
|
|
packageRevisionId: PackageRevisionId;
|
|
moduleId: string;
|
|
}
|
|
|
|
export interface WorkspacePresentation {
|
|
id: string;
|
|
displayName: string;
|
|
subject: InterfaceRevisionId;
|
|
packageRevisionId: PackageRevisionId;
|
|
componentId: string;
|
|
}
|
|
|
|
export interface PackageRevision {
|
|
/** Explicit build consumers own these artifacts. Generic checking and query
|
|
* execution attach no semantics to their keys or contents. */
|
|
buildArtifacts?: Record<string, unknown>;
|
|
modules?: PackageModule[];
|
|
/** Closed interface imports exposed to this package's checked component bindings. */
|
|
clientInterfaces?: Record<string, InterfaceRevisionId>;
|
|
/** Explicit package imports supplying module selections, never the whole workspace. */
|
|
clientPackages?: Record<string, PackageRevisionId>;
|
|
controllers?: PackageController[];
|
|
queries?: import("../query/types.js").QueryDeclaration[];
|
|
checkedQueries?: import("../query/types.js").CheckedQuery[];
|
|
queryCompositions?: import("../query/composition.js").CheckedQueryComposition[];
|
|
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;
|
|
}
|
|
|
|
/** 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;
|
|
remote: OperationId;
|
|
input: "unit" | "value";
|
|
}
|
|
|
|
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: "journal"; slotId: SlotId; primitive: JournalPrimitive }
|
|
| { kind: "subscription"; slotId: SlotId; primitive: SubscriptionPrimitive }
|
|
| { 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 {
|
|
/** Source provenance of a compiler-expanded rule, never runtime dispatch input. */
|
|
ruleOrigin?: { ruleId: string; sourceInterfaceRevisionId: InterfaceRevisionId; line: number; column: number };
|
|
moduleBindings?: ModuleBinding[];
|
|
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 {
|
|
presentations?: WorkspacePresentation[];
|
|
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;
|
|
}
|