Projection Queries

Projection queries read current runtime state. They should be narrow, predictable, and tied to the projection’s published schema.

Legacy Design MCP v1 query_projection_data can target a Design Workspace with workspaceId. That read lazily activates the exact Workspace runtime scope and uses the same fenced projection namespace as Custom Page preview, including both inherited published projections and projections added in the Workspace. Activation failures return structured reason, workspaceId, and recoveryAction fields; follow the returned action before retrying.

Common controls

Exact query parameters come from the generated OpenAPI contract for the app. For REST list endpoints, pass projection predicates as a URL-encoded JSON object in filter, for example ?filter=%7B%22status%22%3A%22scheduled%22%7D. Direct field parameters such as ?status=scheduled return 400; they are never silently ignored.

Filter shape

Use structured filters instead of string-built query fragments. Supported operators depend on the projection query contract and can include equality, containment, prefix matching, and case-insensitive matching.

Scalar equality also matches array-valued fields containing that scalar. For example, { "tags": "urgent" } matches tags: ["urgent", "customer"].

Avoid unbounded text search unless the projection is designed for it.

Policy polling

Each awaited ctx.getProjection(...) call in a custom-code policy bypasses response caches and executes a new live read against the policy’s exact Production or Workspace runtime source. A Workspace callback never falls back to Production.

Every callback is capped at 30 seconds and below the policy handler’s remaining absolute deadline, with a terminal guard. Deadline expiry aborts cooperative work and returns a structured retryable response without waiting for an uncooperative storage call. The projection_callback slot remains occupied until every underlying physical read settles, so timed-out work cannot escape the process-wide bound. If no lease is available in budget, runtime returns a retryable 503 in phase admission before resolving the runtime or reading the projection. Queue and server timing remain charged to the one handler deadline.

Policy execution evidence retains up to 32 bounded, value-free projectionCallbackDiagnostics entries for successful and failed reads. They record outcome, phase, exact source, elapsed time, timeout, remaining budget, response reach/status, and query shape. Document IDs, filters, response bodies, and error messages are excluded.

HTTP policy workers bind each callback to the runtime-config revision that produced their projection manifest. Unknown projections and invalid app ownership are distinct non-retryable failures. A stale worker/runtime revision or a transient app/runtime-registry lookup is marked retryable and remains under the durable invocation’s bounded retry or reconciliation contract; it never falls back to another runtime source. Operator diagnostics state whether to correct ownership/configuration or reconcile the current invocation.

Poll with a finite attempt or deadline limit and add delay or backoff between attempts. List reads remain capped at 1,000 documents per call. Separate calls, especially calls to different projections, are not one atomic snapshot. When a completion decision depends on several projections, require two consecutive stable exact reads before returning the completion command. An intentional settle or retry path may return no command.

Output shaping

Projection tools and APIs can support output controls to reduce payload size. Use them for agent workflows so the model receives only the fields needed for the task.

Copying fixtures to a Workspace

On legacy Design MCP v1, copy_projection_document_to_workspace can copy Production read-model documents into a Workspace without replaying events. Use the singular id from a query or page diagnostic copyAction for one document. Existing singular calls remain compatible.

For an exact set, pass ids (1 to 500, at most 1,024 UTF-16 code units per ID) and an idempotencyKey. Optional expectedSourceHashes and expectedSourceAggregateHash pin the copy-safe Production snapshot. Optional expectedTargetHashes provides per-ID target CAS: null requires absence, while a hash permits replacement only with overwrite: true. Hashes are lowercase 64-character SHA-256 hex values, and per-ID maps may only name selected IDs. Existing identical documents are deterministic no-ops.

Exactness is scoped to the requested manifest. Counts and aggregate hashes do not include unrelated destination documents, and the operation never deletes those documents.

Hashes use projection-copy canonical JSON v1: SHA-256 over UTF-8, with object keys sorted by UTF-16 code units at every depth. Arrays preserve order, undefined object properties are omitted, and undefined array entries become null. A document hash covers the default-redacted document. The aggregate input is the UTF-16-code-unit-ID-sorted array of { "id": <id>, "hash": <document-hash> } objects, canonicalized the same way. For a fixed check, { "é": 1, "z": 2, "😀": 3 } becomes {"z":2,"é":1,"😀":3} and hashes to 4177f29d85d48c133fea6e4531c5817e8ad4a86eca582296fe34d6322db0799c.

Cessy de-duplicates and sorts the manifest and processes document work through a process-wide shared FIFO scheduler with two permits. The first source hashes are persisted and rechecked before write and during final verification. The durable result contains counts, per-ID statuses and source/target hashes, plus aggregate hashes when complete; it contains no document bodies. After a timeout, call the same tool with operation: "status" or "resume" and the original app, Workspace, projection, and key. Omit the IDs, hashes, and overwrite flag for those operations. A completed receipt is immutable point-in-time evidence; use a new key to verify the target after later Workspace mutations.

Hashes cover the default-redacted document payload that is actually copied, not raw secret-bearing Production storage. The fixture is Workspace-only and non-event-backed: Production is not mutated, and no commands, events, policies, triggers, subscriptions, or external HTTP run.

This capability is not on the current Design MCP vNext surface. vNext remains the five-tool Begin/Inspect/Apply/Evaluate/Finalize lifecycle, and its evaluation-only projection snapshot flow is tracked separately.

Builder guidance

Design projections around real read questions. If every client has to fetch a large projection and filter locally, the projection shape is probably wrong.