Add activated workspace reflection and Studio definition watches

Expose bounded snapshot-bound definition reads and latest-only watches from the serving checked bundle. Add checked reflection dependency ports, generated SDK bindings and selector-scoped invocation authority.

Move Studio factory, contract and query discovery to public reflection inventories. Share an active-definition watch across canvas and standalone routes and invalidate/reload on epoch changes instead of polling GetWorkspace.

Document the API and deferred scope; cover compiler/codegen, SDK injection, transport authorization, activation publication, pagination and reconnect behavior. Keep all work local; no deployment or publication.

src/bindings.ts

@@ -51,6 +51,7 @@ export type QxValueType =
   | { kind: "optional" | "list"; value: QxValueType };
 export type QxOperationSpec = { id: string; inputType: QxValueType; outputType: QxValueType };
 export type QxPortSpec =
+  | { kind: "reflection"; id: string; selectors: string[] }
   | { kind: "query"; id: string; definitionDigest: string; variables: QxValueType; output: QxValueType; watch: boolean }
   | { kind: "state"; id: string; valueType: QxValueType; primitives: string[] }
   | { kind: "edge"; id: string; primitives: string[] }
@@ -246,6 +247,8 @@ export const bindQxHandler = <C, O>(
               bindInterfaceView(target, defineQxInterfaceContract(port.interfaceRevisionId, port.operations), messages),
             ];
           }
+          case "reflection":
+            return [name, raw.reflection(port.id)];
           case "query": {
             const query = raw.query(port.id);
             const variablesToWire = (variables: unknown) => {

src/index.ts

@@ -10,6 +10,8 @@ import {
 } from "./references.js";
 export * from "./bindings.js";
 export * from "./queries.js";
+export * from "./reflection.js";
+import type { QxReflectionPort, ReflectionRequest } from "./reflection.js";
 export { relationshipMap, relationshipList, relationshipSet } from "./relationships.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
@@ -208,7 +210,8 @@ export type QueryPort = {
     expectedDefinitionDigest?: string,
   ): AsyncIterable<import("./quixos/orch_pb.js").QueryEvent>;
 };
-export type RuntimePort = StatePort | EdgePort | InterfacePort | ConstructorPort | QueryPort;
+export type ReflectionPort = QxReflectionPort & { reflection: true };
+export type RuntimePort = StatePort | EdgePort | InterfacePort | ConstructorPort | QueryPort | ReflectionPort;
 
 export type RuntimeContext = {
   tryConform(object: QxObjectRef, interfaceRevisionId: string): Promise<InterfacePort | undefined>;
@@ -224,6 +227,7 @@ export type RuntimeContext = {
   interface(portId: string): InterfacePort;
   constructor(portId: string): ConstructorPort;
   query(portId: string): QueryPort;
+  reflection(portId: string): ReflectionPort;
 };
 
 export type RuntimeSession = {
@@ -285,6 +289,19 @@ export const createRuntimeContext = (
   const ports = new Map<string, RuntimePort>();
   for (const dependency of request.dependencies) {
     switch (dependency.binding.case) {
+      case "reflection": {
+        const scope = dependency.binding.value;
+        const scoped = (input: ReflectionRequest) => {
+          if (!scope.selectors.includes(input.selector.kind)) throw new Error("Undeclared reflection selector");
+          return { ...input, workspaceId: scope.workspaceId, workspaceEpoch: scope.workspaceEpoch };
+        };
+        ports.set(dependency.portId, {
+          reflection: true,
+          read: (input: ReflectionRequest) => orch.readDefinitions(scoped(input)),
+          watch: (input: ReflectionRequest, signal: AbortSignal) => orch.watchDefinitions(scoped(input), { signal }),
+        });
+        break;
+      }
       case "queryId":
       case "workspaceQuery": {
         if (dependency.binding.case === "workspaceQuery" && !dependency.binding.value.scope)
@@ -453,6 +470,7 @@ export const createRuntimeContext = (
     interface: (portId: string) => requirePort<InterfacePort>(portId, "interfaceRevisionId"),
     constructor: (portId: string) => requirePort<ConstructorPort>(portId, "atomId"),
     query: (portId: string) => requirePort<QueryPort>(portId, "queryId"),
+    reflection: (portId: string) => requirePort<ReflectionPort>(portId, "reflection"),
   };
 };
 

src/quixos/refs_pb.ts

@@ -10,7 +10,7 @@ import type { Message } from "@bufbuild/protobuf";
  * Describes the file quixos/refs.proto.
  */
 export const file_quixos_refs: GenFile = /*@__PURE__*/
-  fileDesc("ChFxdWl4b3MvcmVmcy5wcm90bxIGcXVpeG9zInUKDUNhcGFiaWxpdHlSZWYSHQoVaW50ZXJmYWNlX3JldmlzaW9uX2lkGAEgASgJEhQKDG9wZXJhdGlvbl9pZBgCIAEoCRIvCgtjb25mb3JtYW5jZRgDIAEoCzIaLnF1aXhvcy5Db25mb3JtYW5jZVdpdG5lc3Mi0QEKDEZpZWxkRWRpdGluZxIbChNnZXR0ZXJfb3BlcmF0aW9uX2lkGAEgASgJEhsKE3NldHRlcl9vcGVyYXRpb25faWQYAiABKAkSFQoNZG9jdW1lbnRfdHlwZRgDIAEoCRIWCg5iaW5kaW5nX2RpZ2VzdBgEIAEoCRInCgRtb2RlGAUgASgOMhkucXVpeG9zLkZpZWxkRWRpdGluZy5Nb2RlIi8KBE1vZGUSDwoLVU5TUEVDSUZJRUQQABIMCghSRUdJU1RFUhABEggKBENSRFQQAiKWAQoSQ29uZm9ybWFuY2VXaXRuZXNzEhEKCW9iamVjdF9pZBgBIAEoCRIdChVpbnRlcmZhY2VfcmV2aXNpb25faWQYAiABKAkSFgoOY29uZm9ybWFuY2VfaWQYAyABKAkSHQoVd29ya3NwYWNlX3JldmlzaW9uX2lkGAQgASgJEhcKD3dvcmtzcGFjZV9lcG9jaBgFIAEoCSJCChBQYWNrYWdlRXhwb3J0UmVmEhsKE3BhY2thZ2VfcmV2aXNpb25faWQYASABKAkSEQoJZXhwb3J0X2lkGAIgASgJIpUCChJJbmplY3RlZERlcGVuZGVuY3kSDwoHcG9ydF9pZBgBIAEoCRIXCg1zdGF0ZV9zbG90X2lkGAIgASgJSAASJgoEZWRnZRgDIAEoCzIWLnF1aXhvcy5FZGdlRGVwZW5kZW5jeUgAEh8KFWludGVyZmFjZV9yZXZpc2lvbl9pZBgEIAEoCUgAEh0KE2NvbnN0cnVjdG9yX2F0b21faWQYBSABKAlIABISCghxdWVyeV9pZBgHIAEoCUgAEjsKD3dvcmtzcGFjZV9xdWVyeRgIIAEoCzIgLnF1aXhvcy5Xb3Jrc3BhY2VRdWVyeURlcGVuZGVuY3lIABIRCglvYmplY3RfaWQYBiABKAlCCQoHYmluZGluZyKaAQoTV29ya3NwYWNlUXVlcnlTY29wZRIUCgx3b3Jrc3BhY2VfaWQYASABKAkSHQoVd29ya3NwYWNlX3JldmlzaW9uX2lkGAIgASgJEhcKD3dvcmtzcGFjZV9lcG9jaBgDIAEoCRIdChVpbnRlcmZhY2VfcmV2aXNpb25faWQYBCABKAkSFgoOYmluZGluZ19kaWdlc3QYBSABKAkiWAoYV29ya3NwYWNlUXVlcnlEZXBlbmRlbmN5EhAKCHF1ZXJ5X2lkGAEgASgJEioKBXNjb3BlGAIgASgLMhsucXVpeG9zLldvcmtzcGFjZVF1ZXJ5U2NvcGUiPQoORWRnZURlcGVuZGVuY3kSFAoMZWRnZV90eXBlX2lkGAEgASgJEhUKDXByb2plY3Rpb25faWQYAiABKAliBnByb3RvMw");
+  fileDesc("ChFxdWl4b3MvcmVmcy5wcm90bxIGcXVpeG9zInUKDUNhcGFiaWxpdHlSZWYSHQoVaW50ZXJmYWNlX3JldmlzaW9uX2lkGAEgASgJEhQKDG9wZXJhdGlvbl9pZBgCIAEoCRIvCgtjb25mb3JtYW5jZRgDIAEoCzIaLnF1aXhvcy5Db25mb3JtYW5jZVdpdG5lc3Mi0QEKDEZpZWxkRWRpdGluZxIbChNnZXR0ZXJfb3BlcmF0aW9uX2lkGAEgASgJEhsKE3NldHRlcl9vcGVyYXRpb25faWQYAiABKAkSFQoNZG9jdW1lbnRfdHlwZRgDIAEoCRIWCg5iaW5kaW5nX2RpZ2VzdBgEIAEoCRInCgRtb2RlGAUgASgOMhkucXVpeG9zLkZpZWxkRWRpdGluZy5Nb2RlIi8KBE1vZGUSDwoLVU5TUEVDSUZJRUQQABIMCghSRUdJU1RFUhABEggKBENSRFQQAiKWAQoSQ29uZm9ybWFuY2VXaXRuZXNzEhEKCW9iamVjdF9pZBgBIAEoCRIdChVpbnRlcmZhY2VfcmV2aXNpb25faWQYAiABKAkSFgoOY29uZm9ybWFuY2VfaWQYAyABKAkSHQoVd29ya3NwYWNlX3JldmlzaW9uX2lkGAQgASgJEhcKD3dvcmtzcGFjZV9lcG9jaBgFIAEoCSJCChBQYWNrYWdlRXhwb3J0UmVmEhsKE3BhY2thZ2VfcmV2aXNpb25faWQYASABKAkSEQoJZXhwb3J0X2lkGAIgASgJIskCChJJbmplY3RlZERlcGVuZGVuY3kSDwoHcG9ydF9pZBgBIAEoCRIXCg1zdGF0ZV9zbG90X2lkGAIgASgJSAASJgoEZWRnZRgDIAEoCzIWLnF1aXhvcy5FZGdlRGVwZW5kZW5jeUgAEh8KFWludGVyZmFjZV9yZXZpc2lvbl9pZBgEIAEoCUgAEh0KE2NvbnN0cnVjdG9yX2F0b21faWQYBSABKAlIABISCghxdWVyeV9pZBgHIAEoCUgAEjsKD3dvcmtzcGFjZV9xdWVyeRgIIAEoCzIgLnF1aXhvcy5Xb3Jrc3BhY2VRdWVyeURlcGVuZGVuY3lIABIyCgpyZWZsZWN0aW9uGAkgASgLMhwucXVpeG9zLlJlZmxlY3Rpb25EZXBlbmRlbmN5SAASEQoJb2JqZWN0X2lkGAYgASgJQgkKB2JpbmRpbmciWAoUUmVmbGVjdGlvbkRlcGVuZGVuY3kSFAoMd29ya3NwYWNlX2lkGAEgASgJEhcKD3dvcmtzcGFjZV9lcG9jaBgCIAEoCRIRCglzZWxlY3RvcnMYAyADKAkimgEKE1dvcmtzcGFjZVF1ZXJ5U2NvcGUSFAoMd29ya3NwYWNlX2lkGAEgASgJEh0KFXdvcmtzcGFjZV9yZXZpc2lvbl9pZBgCIAEoCRIXCg93b3Jrc3BhY2VfZXBvY2gYAyABKAkSHQoVaW50ZXJmYWNlX3JldmlzaW9uX2lkGAQgASgJEhYKDmJpbmRpbmdfZGlnZXN0GAUgASgJIlgKGFdvcmtzcGFjZVF1ZXJ5RGVwZW5kZW5jeRIQCghxdWVyeV9pZBgBIAEoCRIqCgVzY29wZRgCIAEoCzIbLnF1aXhvcy5Xb3Jrc3BhY2VRdWVyeVNjb3BlIj0KDkVkZ2VEZXBlbmRlbmN5EhQKDGVkZ2VfdHlwZV9pZBgBIAEoCRIVCg1wcm9qZWN0aW9uX2lkGAIgASgJYgZwcm90bzM");
 
 /**
  * @generated from message quixos.CapabilityRef
@@ -213,6 +213,12 @@ export type InjectedDependency = Message<"quixos.InjectedDependency"> & {
      */
     value: WorkspaceQueryDependency;
     case: "workspaceQuery";
+  } | {
+    /**
+     * @generated from field: quixos.ReflectionDependency reflection = 9;
+     */
+    value: ReflectionDependency;
+    case: "reflection";
   } | { case: undefined; value?: undefined };
 
   /**
@@ -231,6 +237,33 @@ export type InjectedDependency = Message<"quixos.InjectedDependency"> & {
 export const InjectedDependencySchema: GenMessage<InjectedDependency> = /*@__PURE__*/
   messageDesc(file_quixos_refs, 4);
 
+/**
+ * @generated from message quixos.ReflectionDependency
+ */
+export type ReflectionDependency = Message<"quixos.ReflectionDependency"> & {
+  /**
+   * @generated from field: string workspace_id = 1;
+   */
+  workspaceId: string;
+
+  /**
+   * @generated from field: string workspace_epoch = 2;
+   */
+  workspaceEpoch: string;
+
+  /**
+   * @generated from field: repeated string selectors = 3;
+   */
+  selectors: string[];
+};
+
+/**
+ * Describes the message quixos.ReflectionDependency.
+ * Use `create(ReflectionDependencySchema)` to create a new message.
+ */
+export const ReflectionDependencySchema: GenMessage<ReflectionDependency> = /*@__PURE__*/
+  messageDesc(file_quixos_refs, 5);
+
 /**
  * Scope evidence is not authority by itself. The caller must also hold the
  * matching workspace-query grant (or the authenticated workspace user grant).
@@ -269,7 +302,7 @@ export type WorkspaceQueryScope = Message<"quixos.WorkspaceQueryScope"> & {
  * Use `create(WorkspaceQueryScopeSchema)` to create a new message.
  */
 export const WorkspaceQueryScopeSchema: GenMessage<WorkspaceQueryScope> = /*@__PURE__*/
-  messageDesc(file_quixos_refs, 5);
+  messageDesc(file_quixos_refs, 6);
 
 /**
  * @generated from message quixos.WorkspaceQueryDependency
@@ -291,7 +324,7 @@ export type WorkspaceQueryDependency = Message<"quixos.WorkspaceQueryDependency"
  * Use `create(WorkspaceQueryDependencySchema)` to create a new message.
  */
 export const WorkspaceQueryDependencySchema: GenMessage<WorkspaceQueryDependency> = /*@__PURE__*/
-  messageDesc(file_quixos_refs, 6);
+  messageDesc(file_quixos_refs, 7);
 
 /**
  * @generated from message quixos.EdgeDependency
@@ -313,5 +346,5 @@ export type EdgeDependency = Message<"quixos.EdgeDependency"> & {
  * Use `create(EdgeDependencySchema)` to create a new message.
  */
 export const EdgeDependencySchema: GenMessage<EdgeDependency> = /*@__PURE__*/
-  messageDesc(file_quixos_refs, 7);
+  messageDesc(file_quixos_refs, 8);
 

src/reflection.ts

@@ -0,0 +1,32 @@
+import type { DefinitionPage } from "./quixos/orch_pb.js";
+export type {
+  DefinitionPage,
+  DefinitionIdentity,
+  DefinitionRecord,
+  ReflectedAtom,
+  ReflectedInterface,
+  ReflectedConformance,
+  ReflectedQuery,
+  ReflectedIndex,
+} from "./quixos/orch_pb.js";
+export type ReflectionKind = "active" | "atoms" | "interfaces" | "conformances" | "queries" | "indexes";
+export type ReflectionSelector<K extends string = ReflectionKind> = K extends "active"
+  ? { kind: K }
+  : K extends "atoms"
+    ? { kind: K; ids?: string[]; interfaceRevisionId?: string }
+    : K extends "conformances"
+      ? { kind: K; ids?: string[]; atomId?: string; interfaceRevisionId?: string }
+      : K extends "queries"
+        ? { kind: K; ids?: string[]; packageRevisionId?: string; interfaceRevisionId?: string }
+        : { kind: K; ids?: string[] };
+export type ReflectionRequest<K extends string = ReflectionKind> = {
+  selector: ReflectionSelector<K>;
+  first?: number;
+  after?: string;
+  snapshot?: string;
+};
+/** Read-only metadata. Returned capability IDs confer no invocation authority. */
+export type QxReflectionPort<K extends string = ReflectionKind> = {
+  read(request: ReflectionRequest<K>): Promise<DefinitionPage>;
+  watch(request: Omit<ReflectionRequest<K>, "after" | "snapshot">, signal: AbortSignal): AsyncIterable<DefinitionPage>;
+};