Expose workspace data to the agent and curate its authoring guides

Check named public GraphQL documents against the serving installation using the existing compiler, linker and authorized snapshot interpreter. Keep listObjects as a convenience over workspace-root queries, with no separate filter language. Bound compilation/results, cache by content and serving plan, and fence cutovers. Share graph discovery and reads between qx-workspace graph and the gardener's workspace_graph tool. Local authoring shells discover the live endpoint through the private control socket; configured public mounts also support direct clients. Fix pending paginated inspections to wait for their confirmed window, and retain semantic integration assertions instead of locking a server ticket's shape. Replace the long prompt with a 384-word entry point and five focused guides. Build immutable bundles with profiles, deep links, source hashes and word/link checks. Keep the docs-maintenance process and feedback outside agent guidance. Running agents use current guides while authored source and checker pins remain. Validation: nix fmt; nix fmt -- --check; nix run .#lint; existing CLI checks; protocol/client/coordinator build tests; complete Studio integration; 13 agent unit tests. A real GPT-6.1 Sol medium/priority turn summarized two synthetic saved comments and a document draft in 27.7s without source changes or cutover. Live reads also succeeded after an ordinary check/activation in the retained fixture.
2026-10-01 13:15:24 -07:00
parent bd42306059
commit ef9a4e067a
6 changed files with 142 additions and 44 deletions
@@ -0,0 +1,77 @@
+import { compileQuery } from "../query/compile.js";
+import { linkQueries } from "../query/link.js";
+import { capabilityId } from "../capability-model/types.js";
+import { portableValueSchema } from "../bindings/portable.js";
+import { hexDigest, type ExecutionPlan, type PlannedQuery } from "./plan.js";
+import { compileKernelProgram } from "./kernel.js";
+import { queryProgramEntry } from "./queries.js";
+import { unsupportedQueryOperator } from "./query-operators.js";
+
+export interface QueryDocument {
+  readonly interface: string;
+  readonly document: string;
+  readonly operation: string;
+  readonly objectRoot: boolean;
+}
+/** Runtime query documents use the same language, nominal contracts, linking
+ * and interpreter as packaged queries. They introduce no resources or code. */
+export async function compilePublicQuery(plan: ExecutionPlan, request: QueryDocument) {
+  if (hexDigest(plan.definition) !== plan.digest) throw Error("INVALID_PLAN");
+  if (
+    typeof request.document !== "string" ||
+    Buffer.byteLength(request.document) > 32768 ||
+    typeof request.operation !== "string" ||
+    !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(request.operation) ||
+    typeof request.interface !== "string" ||
+    request.interface.length > 2048
+  )
+    throw Error("QUERY_DOCUMENT_LIMIT");
+  const id = "public-query:" + hexDigest(request);
+  const checked = await compileQuery(
+    {
+      id,
+      displayName: request.operation,
+      root: {
+        kind: request.objectRoot ? "object" : "workspace-interface",
+        interface: capabilityId.interfaceRevision(request.interface),
+      },
+      document: "request.graphql",
+      operation: request.operation,
+      fragments: [],
+      views: [],
+      allowances: [],
+      watch: false,
+      budgets: {
+        rows: 512,
+        depth: 8,
+        resultBytes: 256 * 1024,
+        candidates: 10000,
+        rpcCalls: 128,
+        concurrency: 8,
+        deadlineMs: 10000,
+      },
+    },
+    plan.definition.workspace.interfaceImports,
+    async () => request.document,
+  );
+  const unsupported = unsupportedQueryOperator(checked);
+  if (unsupported) throw Error(`QUERY_OPERATOR_UNSUPPORTED: ${unsupported}`);
+  const linked = linkQueries(plan.definition.workspace, [
+    { packageRevisionId: "org.quixos.public-query/1", checked },
+  ]).find((q) => q.checked === checked)!;
+  const kernel = compileKernelProgram(plan) as {
+    operations: { key: string; effect: string; unsupported: string | null; binding: { kind: string } }[];
+  };
+  for (const field of linked.fields) {
+    const key = JSON.stringify([field.atomId, field.interfaceRevisionId, field.getter]);
+    const operation = kernel.operations.find((op) => op.key === key);
+    const member = plan.definition.workspace.interfaceImports
+      .find((i) => i.revisionId === field.interfaceRevisionId)!
+      .members.find((m) => m.id === field.memberId)!;
+    if (!operation || operation.unsupported || operation.effect !== "snapshot")
+      throw Error("QUERY_DOCUMENT_REQUIRES_SNAPSHOT: use an installed query for remote-effect enrichment");
+    if (member.kind === "relationship" && operation.binding.kind !== "edge") throw Error("QUERY_NON_NATIVE_RELATION");
+  }
+  const entry: PlannedQuery = { id, query: linked, operations: [], admittedOperations: [] };
+  return { id, program: queryProgramEntry(plan, entry), output: portableValueSchema(checked.output) };
+}