MemQL Attribute Matrix

This page lists every annotation the language accepts, the constructs and fields that accept it, and the form its arguments take there. It is generated from the annotation registry in component/language/annotations, which the construct parsers and the concept loader check every annotation against, and make docs-matrix regenerates it.

#How to read it

Under At a glance, a row is an annotation and a column is a construct or a kind of field: a filled cell says how the annotation is written there, and an empty cell means it is refused there, with one of the codes under Refusals. The words in a cell are argument forms: flag means no arguments, empty empty parentheses, string one string, strings one or more strings, number one number, keywords keyword arguments and expression an expression. Each annotation links to its entry under Annotations, which shows it written on every construct that accepts it, lists its keys and says what it does.

#At a glance

One table per family of constructs, and one for the fields a construct declares.

#Functions

#Data

#Model access

#Capabilities

#Fields

#By construct

Every construct and every kind of field, with each annotation it accepts, how the annotation is written there, and an example.

#query

The fields of its args block take the annotations under args field.

#mutation

The fields of its args block take the annotations under args field.

#logic

The fields of its args block take the annotations under args field.

#automation

The fields of its args block take the annotations under args field.

#concept

The fields in its body take the annotations under concept field.

#shape

#spec and trait

#seed

#prompt

The fields in its body take the annotations under prompt field.

#provider

#policy

#rule

#tool

The fields in its body take the annotations under tool field.

#builtin

The fields in its body take the annotations under builtin field.

#action

The fields of its args block take the annotations under args field.

#capability

The fields of its args block take the annotations under args field.

#concept field

Written after a field's type in the body of a concept.

#args field

Written after a field's type in the args block of a query, mutation, logic, automation, action or capability.

#tool field

Written after a field's type in the body of a tool.

#prompt field

Written after a field's type in the body of a prompt.

#builtin field

Written after a field's type in the body of a builtin.

#Annotations

One entry per annotation, in alphabetical order: where it is accepted and how it is written there, its keys, and what it does. An annotation marked repeatable may be written more than once on one declaration; any other is refused the second time with annotation_repeated.

#@actor

• On a query, a mutation, a logic or an automation: Declares that the body reads the authenticated actor (actor.userId, actor.role, actor.identityId, actor.isClusterOwner, actor.primaryEmail, actor.now). The actor-binding load rule refuses a body that reads actor.* without it (memql#2621).
• On a shape: Shape kind marker: the shape projects the authenticated actor's envelope (actor.userId / actor.role / ...), and carries no signature concept.

#@addToSet

On an update mutation: treat the named array-typed payload fields as SETS and UNION the written elements into the stored array -- deduped, existing order kept, new members appended in the order given. The membership half @appendFields is not: append is not deduped and has no counterpart that removes, so a toggle built on it duplicates on a double click. Pairs with @removeFromSet. Format: @addToSet("disabledDeployables"). See memql#4951.

Both follow the same rules:

• Only an update mutation may carry it; on an insert it is refused at load, because an insert has no stored set to change.
• A field absent from the write is untouched: the stored array survives the read-merge.
• Members compare by their rendered form, so 1 and "1" are one member. A stored number comes back from JSON as a float and its string spelling as a string, and keeping both would be a set that quietly grew.
• A stored value that is not an array reads as empty, and a scalar written where an array is expected is one member, as with @appendFields.
• A field named by two of @appendFields, @addToSet and @removeFromSet is refused at load: each rewrites the same key, so which one won would depend on the executor's order rather than on anything the mutation says.

#@alias

Additional name the builtin is registered under. Repeatable.

#@allowedRoles

DEPRECATED (rule deprecated_allowed_roles, memql#5438): write @requiresAgentRole for an agent kind and @requiresRank for a person's role -- memqlmigrate --rewrite=allowed-roles rewrites it. It compares ONE role string whose meaning depends on who is calling: the acting agent's role (assistant / specialist) in an agent's tool loop, and the person's cluster role over MCP. Two axes in one list is why it is leaving: neither list can be read without knowing which path the call arrives by. Until its window closes it keeps that behaviour, on every path a tool is listed or called by -- read by component/memql/tool_gate.go through Tool.IsAllowedForRole (tool_types.go).

#@appendFields

On an update mutation: append the named array-typed payload fields' elements to the stored array instead of replacing it wholesale, so a single-writer mutation can accumulate list items (e.g. attach one id). Format: @appendFields("attachmentIds").

#@args

@args takes these keys, each written as key=value.

Parse-time argument contract for builtin functions.

#@autoInjected

The field is filled by the runtime rather than the model: it is kept out of the input schema the model sees and stamped server-side (the calling agent's id, for example).

#@base

Mark a vendor-level base provider (auth + type only).

#@cache

@cache takes these keys, each written as key=value.

Override the result-cache TTL for the query. Preferred form (#2618): @cache(300) -- the single ttl arg makes position unambiguous. The keyword form @cache(ttl="300") keeps parsing. Pure reads cache BY DEFAULT (a 60s backstop) without this annotation; @cache sets a different TTL, longer or shorter. @cache(0) is the explicit "never cache" opt-out -- @nocache was retired with it (epic memql#5375), and one annotation for the TTL is the whole reason. The engine keys the cache on the plan signature (query/sort/limit/depth/shape + the keyset cursor) and evicts on any write to the read concept via the cache.invalidate.* broadcast channel -- cross-node eviction needs no per-concept routing rule.

#@composable

@composable takes these keys, each written as key=value.

The Materializer's mark (epic memql#4977, D2): this concept's rows are worth composing a file FROM. Bare, it takes the defaults; as= names the row kind, fields= lists the fields to compose from and list= names the query that lists the rows. Read by clients/os (src/apps/materializer/useCompose.ts) through integration.compose.composableConcepts.

#@createOnly

On an insert (create-or-upsert) mutation: write the named payload fields ONLY when creating the row. If the target id already exists, the fields are dropped from the delta before the engine read-merge, so the stored value is preserved rather than clobbered -- making a deterministic-id re-stage idempotent for lifecycle fields another writer owns after creation (e.g. stageOutboundRequest seeds status but must not reset a row the outbound worker moved to sent). The inverse of @mergeFields/@appendFields: only valid on insert-kind mutations. Format: @createOnly("status", "attempts"). See fylo#63.

#@default

• On a provider: Mark this provider as the default for its modality.
• On a tool field: The default the tool's input schema advertises to the model, written quoted: its text converts to the field's type as a call's default always has -- @default("5") on an integer field, @default("true") on a boolean, one of the values of an enum field -- or the load refuses it (tool_default_type, memql#5430).
• On a prompt field: The default the prompt's input schema declares for the field: its text -- quoted, or an unquoted number as written -- converts to the field's type by the rule a tool field's does, or the load refuses it (prompt_default_type, memql#5430).

#@defaultProvider

Default AI provider for prompt execution: an explicit pin that wins over every routing rule.

#@description

• On a query, a mutation, a logic, an automation, a concept, a shape, a spec or trait, a seed, a prompt, a provider, a policy, a rule, a tool, a builtin, an action or a capability: Human-readable description of this definition. PREFER the /// doc-comment form (#2601): a /// block immediately above the declaration IS the description and wins over this annotation; @description remains the valid compatibility fallback -- the tree gate rejects the redundant long form (including a bare @description shadowed by a /// block). Aim for ~500 characters (editorial target).
• On a concept field: The field's description, emitted into the concept schema.
• On a tool field: The field's description, shown to the model in the tool's input schema.
• On a prompt field: The field's description, carried into the prompt's input schema.
• On a builtin field: The field's description, read into the generated SDKs' docs.

#@destructive

Mark a tool as destructive (mutates/deletes); the tool loop gates it behind a confirmation.

#@disabled

Takes the construct out of service without deleting it. Every construct is enabled by default and @enabled is an accepted no-op, so @disabled is the only off switch. A disabled construct stays in the tree, is still maintained, and must stay valid, because re-enabling it is only removing the annotation. What it does depends on the construct:

• A disabled query, mutation, logic or builtin is hidden from functions() and from the MCP surface, its @mcp tool included, and a direct call is refused with function "name" is disabled; help() still describes it, reporting "enabled": false. A disabled builtin also skips the check that its Go executor exists, so a builtin whose executor is gone can be disabled without refusing boot.
• A disabled automation is neither scheduled nor subscribed to its trigger, is dropped from the MCP surface, and is refused on every manual run path: the MCP dry run and live run, the run relay and the HTTP trigger.
• A disabled tool, seed, prompt, provider, action, spec or trait is skipped at load. A tool is not registered, and its name stays reserved so no ungoverned tool is generated from the function behind it. A seed is never materialised and a prompt never registers. A provider is not registered and no auth is resolved for it, and on a @base provider it skips every provider that @extends it. An action is parsed but not registered. A spec or trait is still validated but never binds, and its name stays reserved, so a call to it says it is disabled rather than not found.
• A disabled rule is loaded but never evaluated.
• A disabled capability is still reconciled against its Go capability and checked for duplicates -- @disabled is not a validation bypass -- but it is left out of the catalog: use capabilities.... imports stop resolving it, and an action that names it is refused at load with capability "name" is @disabled. To park DSL ahead of the Go it needs, put the file under a _disabled/ directory instead, which the loaders skip.

An authored spec or trait keeps the same state through the authoring lifecycle. Staging or promoting a disabled one is refused (construct is @disabled; enable it (remove @disabled from the source) before promoting). A promoted row that is disabled is skipped when the engine re-hydrates authored constructs and counted as skippedDisabled rather than quarantined; it reserves the name only when nothing live or already reserved holds it, and promoting the corrected source or demoting the name releases it. A staged one is skipped without reserving anything. A bundle that authors a disabled capability is refused (capability "name" is @disabled), because a disabled capability compiles to nothing.

#@displayCard

@displayCard takes these keys, each written as key=value.

Rendering hints for concept-agnostic clients (memql#160): the field shown as a row's title (primary=, required) and the fields for the secondary, tertiary and status slots. Each must be a displayable field the concept declares, checked once the property set is known. Read by clients/os (src/apps/concepts/displayCard.ts, consumed by RowsPanel.tsx); test/dslconformance's displaycard_inventory_test.go requires every concept to declare or decline one.

#@enum

The closed set of string values the field accepts: @enum("a", "b"). The enum("a", "b") type is the same constraint in one statement.

#@eventField

On an event-triggered logic: declare the allowed top-level event payload fields (e.g. @eventField("partitionId", "siParticipantId")). Opt-in field-level validation -- every event.payload.<field> reference in the body is checked against this set at load time, rejecting typos / fields the (possibly synthetic, handler-assembled) triggering event cannot carry (memql#1743). Bare names or payload.-prefixed paths both normalize to the head segment.

#@exclude

On a rule: remove one concrete entry from the chain's resolution, e.g. @exclude("fleet:qwen3.5:7b"). Repeatable.

#@executionTime

Expected execution time hint: "fast", "medium", or "slow".

#@executor

Go executor name for builtin functions (integration.X.Y).

#@extends

Inherit configuration from a base provider.

#@fallback

On a policy: an entry tried when the ones before it cannot serve the call. Repeatable (order preserved). Same closed grammar as @primary.

#@filter

Filter for automation triggers: a lambda of one parameter over the triggering row, as in @filter(row => row.status == "open").

#@handler

@handler takes these keys, each written as key=value.

Tool handler configuration. Format: @handler(type="query", query="...") / @handler(type="function", name="...").

#@internal

On a concept field: server-only (memql#2035) -- never projected by a shape's default projection and never accepted from a mutation's caller args; emitted as x-internal. (On a construct, @internal is retired, #2708.)

#@level

• On a prompt: How much intelligence the call needs: fast, strong, reasoning or embeddings. The router's rules branch on it, so a prompt never names a model (epic memql#5127). Required on every prompt: one without it is refused at load (prompt_level_missing), a @disabled prompt included.
• On a rule: The level to resolve the call at: fast, strong, reasoning or embeddings, OVERRIDING what the call declared.

#@locked

On a rule: evaluate before every unlocked rule regardless of precedence. Accepted only in the embedded tree -- the loader refuses it elsewhere.

#@loop

@loop takes these keys, each written as key=value.

On an automation that closes a deliberate cycle: permits the cycle the load would otherwise refuse, bounds it to maxDepth runs of this automation per causal chain, and names the predicate that ends it. The @filter must exclude the rows where until holds.

#@maximum

• On a concept field: The INCLUSIVE upper bound on a numeric value.
• On an args field: The INCLUSIVE upper bound on a numeric argument (memql#4522).

#@maxLength

• On a concept field: The most characters a string value may carry.
• On an args field: The most characters a string argument may carry (a rune count, enforced on strings).

#@mcp

Expose this construct on the MCP connector surface. On a query/mutation/automation it promotes the construct into its own first-class MCP tool (otherwise it stays reachable via the generic run_query / run_mutation / run_automation dispatchers). On a tool it opts the tool into the curated connector allowlist: once ANY tool carries @mcp, tools/list reflects only @mcp tools (otherwise -- zero tagged -- the full tool surface is reflected, so the annotation is inert until the curated set is tagged).

#@mergeFields

On an update mutation: deep-merge the named object-typed payload fields into the stored object instead of replacing them wholesale, so sibling keys survive a single-key write. Format: @mergeFields("preferences").

#@minimum

• On a concept field: The INCLUSIVE lower bound on a numeric value.
• On an args field: The INCLUSIVE lower bound on a numeric argument (memql#4522).

#@minLength

The fewest characters a string value may carry.

#@mirroredTo

Declares WHO ELSE HOLDS A COPY of this MemQL-origin concept: @mirroredTo("shopify"), or several names in one annotation. Every write to the concept appends one v1:platform:outboxEntry per target, in the write's own transaction, which a per-connector drain worker delivers with an idempotency key, backoff, dead-lettering and audit. Only valid on a MemQL-origin concept -- @mirroredTo beside an external @origin is REFUSED at load, because re-mirroring somebody else's data onward is the origin's job and a mirror that also publishes is a second origin wearing the first one's badge. Each named connector must be registered or the engine refuses boot: a mirror target nobody drains is a silent drop. See data-origins.md.

#@modality

Provider modality (e.g., "chat", "audio", "image", "embedding").

#@mode

@mode takes these keys. A key of type flag is written bare, and every other as key=value.

How concurrent fires of this automation behave in one process: single, queued, restart or parallel, with max for queued and parallel. Without it an automation runs every fire in parallel.

#@model

Model identifier (e.g., "gpt-5.4-mini", "claude-sonnet-4-6").

#@noUnset

On any mutation: declare the named payload fields ONE-WAY -- a write may set them or change one non-empty value to another, but may never take a stored non-empty value back to empty. On the read-merge path a named field arriving empty is dropped from the delta when the stored row holds a non-empty value. Closes the gap read-merge cannot (it only inherits fields ABSENT from a delta, so a body writing f: args.f ?? "" blanks the stored value with an explicit empty string). Distinct from @createOnly, which forbids any post-create write; @noUnset forbids only set -> unset, so a legitimately-later stamp still lands. Format: @noUnset("bootstrappedAt"). See memql#3415.

Empty means nil, a blank or whitespace-only string, or an empty array or object. A numeric or boolean zero is a value, not an unset: 0 and false are written like any other value, and treating them as empty would make @noUnset unwritable for those types.

#@onUnavailable

On a rule: what happens when the chain is exhausted at the level -- "degrade" walks down to the next level and records that it did, "park" returns the refusal with the door report. Empty reads as degrade.

#@open

On a nested object block: the block accepts keys it does not declare, suppressing the closed-by-default additionalProperties: false (memql#3641). For a block whose keys are data rather than schema.

#@origin

Declares WHERE CHANGES TO THIS CONCEPT ARE MADE -- the system that owns the data. @origin("memql") (the default when the annotation is absent) means MemQL originates it; @origin("<connector>") names an external system, which makes the concept a MIRROR. A mirror is READ-ONLY BY CONSTRUCTION: component/memql refuses every write to it -- mutation, tool handler, raw insert or staged write -- that does not come from the connector the origin names, so what the badge says is what a reader may assume. The name must be a registered connector or the engine REFUSES BOOT naming the concept: a mirror nobody fills is a lie. Pairs with @mirroredTo to derive dataState (mirror | origin | native), which the registry, both SDKs and client data-origin displays read. See data-origins.md.

#@pattern

• On a concept field: A regular expression a string value must match, in Go's RE2 syntax. It is compiled at load on a concept field and an args field alike, so an expression that does not compile is refused there (pattern_invalid) rather than at the first write or call.
• On an args field: A regular expression a string argument must match, compiled once at load.

#@pii

The field is personally identifying: emitted as x-pii, and the hard-delete scrub (@scrubPii, memql#1711) zeroes every such field generically.

#@policy

Required on a rule: the policy this rule resolves the call through.

#@precedence

On a rule: evaluation order, highest first. A tie between two rules of the same locked-ness is a load error.

#@primary

Required on a policy: the first entry the AI Router resolves. A provider name, a fleet: / app: / federation: selector, or policy:<name>.

#@public

Per-row-authz marker: this query/mutation is intentionally callable without a caller-scope filter (concept catalogs, pre-auth login paths). See per-row-authz-audit.md.

#@relationship

@relationship takes these keys, each written as key=value.

Foreign-key relationship metadata. Format: @relationship(type="parent", field="x", target=concept, direction="outgoing"), plus an optional as="domainVerb" label.

#@removeFromSet

On an update mutation: treat the named array-typed payload fields as SETS and REMOVE the written elements from the stored array, keeping the order of what remains. Removing something absent is a no-op rather than an error, so the mutation is idempotent and two callers removing the same member both succeed. Pairs with @addToSet, and the pair is what lets a set be edited one member at a time instead of read-modify-written whole. Format: @removeFromSet("disabledDeployables"). See memql#4951.

Both follow the same rules:

• Only an update mutation may carry it; on an insert it is refused at load, because an insert has no stored set to change.
• A field absent from the write is untouched: the stored array survives the read-merge.
• Members compare by their rendered form, so 1 and "1" are one member. A stored number comes back from JSON as a float and its string spelling as a string, and keeping both would be a set that quietly grew.
• A stored value that is not an array reads as empty, and a scalar written where an array is expected is one member, as with @appendFields.
• A field named by two of @appendFields, @addToSet and @removeFromSet is refused at load: each rewrites the same key, so which one won would depend on the executor's order rather than on anything the mutation says.

#@required

• On a concept field, a tool field, a prompt field or a builtin field: The field is required: a concept write without it fails the schema, and a caller must pass an args / tool / prompt / builtin field that carries it. The ! sigil after the type is the same thing.
• On an args field: The caller must pass the argument. The ! sigil after the type is the same thing.

#@requiresAgentRole

The AGENT-KIND gate on a tool: only an agent whose role is one of the values may be offered the tool or call it -- @requiresAgentRole("assistant") (memql#5438). The values are the v1:agents:agent concept's own role enum (assistant, specialist), and the load VALIDATES them against that declaration, so a value no agent can hold refuses boot rather than admitting nobody. It is the axis @requiresRank and @requiresCapability cannot express: they judge the PERSON a call is for, this judges WHICH AGENT is calling. A person calling over MCP is not an agent, so a tool carrying it is neither listed nor callable for them. It replaces the agent half of the deprecated @allowedRoles; a tool with neither gate is callable by every agent and by an authenticated person over MCP.

#@requiresCapability

The CAPABILITY a caller must hold to invoke the construct -- @requiresCapability("read", "principal") (epic memql#5166, D11). The sibling of @requiresRank, and the difference is the point: a RANK is a floor on the cluster's ladder, a CAPABILITY is a (verb x resource) grant a role was given, and a cluster can hold one without the other -- developer ranks above admin and holds strictly fewer principal verbs. Declared together, BOTH must pass. VALIDATED AT LOAD against the five verbs and the resource kinds any role in this cluster holds a grant on, so a misspelling refuses boot rather than gating a surface into silence; ENFORCED at execution through the runtime capability catalog, on the direct call and on every plan that expands the construct. It replaces the slug-comparing specs (requiresAdmin, requiresOwnerOrAdmin, requiresDeveloperOrAbove), which could not see a custom role at all: role == "admin" is false for a rank-250 role holding every principal verb. It gates WHO MAY CALL; @rowAuthz still decides WHICH ROWS come back.

#@requiresConfirmation

Require explicit user confirmation before the tool executes.

#@requiresRank

• On a query, a mutation or a logic: The actor-rank FLOOR: only a caller holding this role, or one ranked above it, may invoke the construct -- @requiresRank("developer") (epic memql#4832, D6). ENFORCED at execution and VALIDATED AT LOAD against the role ladder in dsl/rbac, so a typo refuses boot rather than gating on rank 0 and admitting everyone. This is the server-side counterpart to MemQL OS's per-surface role requirement: the shell keeps hiding what a caller cannot reach (hiding an action beats letting them click it and reading a refusal) and this makes the hidden surface a REFUSED one. Declared on the CONSTRUCT because a surface is a set of constructs and an app id from a browser is a claim, not a fact. It gates WHO MAY CALL; @rowAuthz still decides WHICH ROWS come back.
• On a tool: The person-rank FLOOR on a tool: a call is admitted only when the person it is for -- the authenticated user over MCP, or the user an agent acts for in its tool loop -- holds this role or one ranked above it, and a tool above the caller's rank is not listed to them either. VALIDATED AT LOAD against the role ladder in dsl/rbac exactly as on a query, mutation or logic, and resolved at call time through the same ladder, so a custom role is admitted by its rank. It judges the PERSON and never the agent -- @requiresAgentRole is that gate -- and it replaces the person half of the deprecated @allowedRoles.

#@row

Shape kind: projects a concept's payload + row intrinsics (concept bound via the shape <Concept> <name> signature).

#@rowAuthz

@rowAuthz takes these keys. A key of type flag is written bare, and every other as key=value.

Declares WHO MAY SEE this concept's rows, once on the concept, instead of as an actor.* term every filter over it must remember to carry. Four tiers, one spelling each: @rowAuthz(public) (globally readable by intent -- spelled explicitly, because "no annotation" and "declared public" are different states), @rowAuthz(clusterOwner) (administrative), @rowAuthz(owner="<field>") (the field is compared against actor.userId; it must be a field the concept declares, OR the literal "id" for a SELF-OWNED concept whose owner is the row itself -- memql#3029; id and only id, since createdBy means who WROTE the row, not whose row it is), and @rowAuthz(via="<spec>") (a relationship spec grants visibility).

A fifth FORM, not a fifth tier: @rowAuthz(owner="<field>", clusterOwner) is the composite -- the owner, OR a cluster owner (memql#4312), in either order -- and the form an operator console needs over per-user rows, since a plain owner= tier has no cluster-owner bypass. The other keys (account=, rankVisible, rankStrict, unowned=, requiresIdentity, rankFloor=) qualify a tier rather than naming one.

ENFORCED ON THE READ PATH since Phase 3 (memql#3172): declaring a tier CHANGES WHAT READS RETURN. Two mechanisms, and neither consults the filter to decide whether to engage -- the tier's predicate is ANDed into the plan before the read runs (resolved from the construct's declared binding, so the narrowing pushes down into SQL), and every row leaving the engine is separately admitted against the tier ITS OWN concept declares, which is the only mechanism available to a raw client-supplied query string, to graph expansion, or to a TOP-LEVEL BUILTIN CALL whose rows come out of a Go handler (memql#3982) -- none of which has a filter to AND anything into.

SUBSCRIPTIONS are gated by the same row admission (memql#4309): a graph.node.* event reaches a stream only if the tier admits the row for that stream's actor, a granted row arrives id-only with payload_omitted set for the client to re-read, and an UNDECLARED concept is delivered to everyone exactly as its reads already return to everyone -- the live feed mirrors the read path rather than running a second rulebook. The write side is enforced too: update/delete refuse when the target row's declared owner is not the actor (memql#3174).

Implementation: component/memql/rowauthz_enforce.go, called from parser.go. MEASURED BY TestClusterOwnerTierInjectsTheAdminGate, TestFilteredReadPathAppliesTheRowGate, TestGraphExpansionAppliesTheTraversalGateBeforeItEmitsTheRow, TestTopLevelBuiltinAppliesTheRowGate and TestSubscriptionFanOutAppliesTheRowGate -- named so a reader can check whether this is still true rather than trust the sentence. Trusting it would have been wrong before: this doc described the tier as parsed-but-unread for as long as Phase 3 had been live, which is false in the one direction that costs a reader a wrong authorization assumption, and because the doc also feeds editor hover, the error reached every author who hovered the annotation (memql#3727). See per-row-authz-audit.md and memql#2803.

#@scope

Seed scope: "global" seeds once for the cluster, "perUser" once for every user.

#@scrubPii

On an update mutation (the hard-delete / data-deletion path): after the partial payload merges, zero EVERY field the bound concept marks @pii. The field set is derived from the schema, so a newly-annotated PII field is scrubbed automatically with no change to the mutation. Bare flag, no arguments. See memql#1711.

#@sdk

Generator marker (sdk/gen reads from source); no engine effect.

#@secret

The field holds a secret. It is emitted as x-secret, and every validation surface that quotes a rejected value replaces the value with <redacted> while the argument name and the declared constraint (enum members, bounds, pattern) survive, so the diagnostic stays usable.

The covered surfaces come from an exhaustive enumeration of validators -- every jsonschema .Validate( call site and every value-quoting rejection message in the engine -- not from adding one entry at a time. Three incremental passes each shipped a scope statement that walked past a surface the next pass found, so extend the list by re-running the enumeration, never by appending to it.

• The function-args validator (component/memql/function_validator.go): enum, minimum, maximum, pattern and date-time (memql#3036).
• The tool-args validator (MemQLEngine.validateToolArgs, component/memql/tool_execution.go), compiled from the same args schema and running before the function-args validator on the agent path, so it is the surface a rejected secret reaches first. Both of its exits redact (memql#3182): the message returned to the model, and the WARN, which redacts per key from the args schema instead of serializing the whole args map, and falls back to a values-free argKeys list when the tool's arguments cannot be classified.
• The automation args binder (component/automations/args_binding.go), which applies the same rules to event payloads: a graph.node.created event carries the concept row's fields flattened into its payload. The loader stamps the secret flag from the trigger topic's concept, so the enum and pattern refusals, and the WARN log they are written to, all print <redacted>, closing the one path by which a row value could reach a structured log (memql#3183).
• Concept payload validation (Concept.validate, so Create and Delete), where @minimum, @maximum and @format declared on the concept are enforced. The six jsonschema keywords that interpolate the instance value (minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, format) all redact, and every other message stays byte-identical to an unannotated field's (memql#3184).
• The DSL-callable validate and preflight builtins (component/memql/executor_builtin.go), which compile the same concept schema and return every leaf message to the caller in a result payload.

The last two resolve secrecy through the schema at the failing instance location, so they cover @secret at any nesting depth and inherit it onto array elements, unlike Concept.SecretFields(), which is top-level only and is not the accessor those paths use.

On the two args-validator surfaces, matching is by argument NAME, not by write target: an args field is redacted when its name appears among the bound concept's @secret fields. A mutation writing apiKey: args.credential into a @secret apiKey leaves credential unredacted, and renaming between argument and field is common, so do not rely on the write target. The concept-payload and builtin surfaces resolve through the schema and are not subject to this rule.

A @secret value is not redacted from query results: any query that projects it returns it in full. That is an authorization decision, which needs a definition of "elevated" and depends on the per-row authorization model (memql#2803).

Length is never redacted anywhere, deliberately and uniformly: value too long (N runes, max M) and the jsonschema minLength and maxLength messages report a rune count for a secret field too. They quote no value, but a length is a disclosure; redacting it on one surface would make that surface the only one that differs while withholding nothing the others already print.

Prompt input-schema validation (PromptTemplate.ValidateData, component/memql/ai_prompts.go) is unclassified: it runs a jsonschema over caller data and interpolates the instance the same way, but its schema is built from the prompt's own field list rather than from a concept, so there is no x-secret in it to read. Nothing is redacted there; treat it as uncovered, not as safe.

So @secret stops a credential leaking through a validation diagnostic. It is not a general secrecy guarantee, and not a reason to treat a credential in the graph as protected.

#@serverOnly

Bars the construct from client-originated calls while leaving server-side Go free to call it (memql#2800). ENFORCED at execution against auth.CallOrigin -- unlike the retired @internal, which only hid a construct from discovery. Use only when caller-scoping is impossible: the auth path resolving sub -> user before an actor exists, or an automation acting on a user other than the actor. Callers must stamp auth.ContextWithInternalOrigin.

#@serverSet

The field is stamped server-side (createdAt, createdBy, status, ...): never accepted from a mutation's caller args, but projected like any other field. Emitted as x-serverSet (memql#2035).

#@shopperFormExtension

@shopperFormExtension takes these keys, each written as key=value.

On a mutation: this construct is ONE CLIENT DOMAIN'S ADDITION to a shopper form a PACK declares -- the fields that client collects which the pack does not know about, and the concept they are stored on. It ADDS FIELDS TO AN EXISTING PUBLIC ROUTE and never opens one: putting an endpoint on a hosted site's origin stays the privilege of Go compiled into the engine. The field list is this mutation's own args block MINUS the server-stamped names (storeId, siteId, submissionId), which the body declares so it can write them. The bff validates the pack's fields and these together BEFORE anything is written, runs the pack's construct first so the pack's own gate decides, then this mutation with the same stamped submission id. Legal on a MUTATION alone -- a logic may call builtins, and a public form pointed at one would reach them under the site owner's borrowed authority. At most one extension per form. Format: @shopperFormExtension(pack="wholesale", form="application").

#@sideEffect

On a capability: the coarse risk class @sideEffect("read"|"write"|"exec"). It is the authoritative side-effect class: it lives on the capability, not on the action that calls it, and must equal the class of the Go capability the declaration names, so an authored or generated action cannot claim a lower one.

#@template

On an automation: this is a work-spine TEMPLATE, invoked by a v1:work:run that named it rather than fired by the graph (memql#5048). It is the third way an automation can be reachable, alongside an event trigger and a schedule. A @template automation must carry no @trigger -- the load-time gate refuses the combination, so "called" and "triggered" stay distinct.

#@templateFile

• On a seed: A template file whose rendered text is the seeded row's content.
• On a prompt: The prompt's template: a .tmpl file beside the prompt, rendered with the input fields.

#@trigger

@trigger takes these keys, each written as key=value.

Event trigger for automations. Format: @trigger(event="graph.node.created.*.v1:ns:concept") or @trigger(schedule="0 0 * * * *").

#@type

The concept's row kind: "object" (the default), "collection" or "reference".

#@unbounded

On a list-returning query: opt out of the pagination authoring rule and the implicit 50-row runtime cap. Format: @unbounded("reason"). The reason string is REQUIRED -- it documents why this query is a legitimate full-set read (small bounded catalog, sweep job, etc.) and is enumerated by the pagination audit report. A query that paginates/sorts is already bounded and must NOT carry @unbounded; the engine clamps the realized window to MEMQL_MEMORY_ENGINE_MAX_WINDOW regardless. See authoring-rules.md.

#@variant

@variant takes these keys, each written as key=value.

A discriminated union: @variant(discriminator="kind") on an object field, followed by one block per branch; the discriminator field's value picks the branch.

#@vendor

The provider's type, which picks the client that serves it: OpenAI (or OpenAIChat), OpenAITTS or OpenAIEmbedding for OpenAI, and Anthropic (or AnthropicChat) for Anthropic, matched without regard to case. Fleet and SubscriptionApp are accepted on a @base provider only: their models are named from a policy (fleet:<model>, app:<id>) rather than declared as children. Any other type leaves the provider registered but unavailable (unsupported provider type). Streaming is a parameter (streaming true in params), not a type, and a child that @extends a base takes the base's type.

#@version

• On a concept: Version tag for the concept: a semver string, @version("1.0.0"). Metadata only -- canonical ids are not versioned by it (#2613).
• On a seed: Version tag for the seed.

#@when

@when takes these keys, each written as key=value.

On a rule: the condition set, as keyword arguments. Closed keys, every one optional, all present keys ANDed: level, modality, prompt, role, actorRole, tag, touches. @when() with no arguments matches every call.

#Retired

A retired name is refused where the table says, with annotation_retired and a hint that says what to write instead.

#Refusals

Every refusal names the construct and the annotation, says what to write instead, and ends with its code in square brackets, as in [annotation_unknown].