Field options¶
Set in brackets after a field:
spec.assert_required¶
Set on field · Type bool · Number 60001
Validates that a field has a value
For scalar/string fields: must not be empty/zero value
For repeated fields: must have at least one element
spec.assert_ipaddr_type¶
Set on field · Type IpAddrTypes · Number 60002
No description in spec.proto.
spec.assert_enc_type¶
Set on field · Type EncType · Number 60003
No description in spec.proto.
spec.assert_net_port¶
Set on field · Type bool · Number 60004
No description in spec.proto.
spec.assert_url¶
Set on field · Type UrlScheme · Number 60005
URL/URI validation
spec.assert_email¶
Set on field · Type bool · Number 60006
Email validation
spec.assert_fqdn¶
Set on field · Type bool · Number 60007
FQDN validation
spec.assert_duration¶
Set on field · Type DurationType · Number 60008
Duration/Timeout validation
spec.assert_duration_min¶
Set on field · Type int64 · Number 60009
No description in spec.proto.
spec.assert_duration_max¶
Set on field · Type int64 · Number 60010
No description in spec.proto.
spec.assert_listen_addr¶
Set on field · Type bool · Number 60015
Listen address validation (host:port format)
spec.assert_base64¶
Set on field · Type bool · Number 60016
Base64 validation
spec.assert_enum_defined¶
Set on field · Type bool · Number 60019
Enum non-zero validation (ensures enum is not 0/_UNDEFINED value)
spec.assert_file_path¶
Set on field · Type PathType · Number 60020
File path validation
spec.assert_gt¶
Set on field · Type int64 · Number 60021
Simple numeric comparisons (for most common cases)
These work with int32, int64, uint32, uint64 fields
greater than
spec.assert_ge¶
Set on field · Type int64 · Number 60022
greater than or equal
spec.assert_lt¶
Set on field · Type int64 · Number 60023
less than
spec.assert_le¶
Set on field · Type int64 · Number 60024
less than or equal
spec.assert_numeric¶
Set on field · Type NumericConstraint · Number 60025
Complex numeric constraints (for advanced validation scenarios)
spec.assert_float¶
Set on field · Type FloatConstraint · Number 60026
Floating-point constraints (for float and double fields)
spec.assert_semver¶
Set on field · Type bool · Number 60028
Semantic version validation
Validates that a string follows semantic versioning format (e.g., "1.0.0", "v2.3.1")
Supports optional 'v' prefix and follows semver.org specification
spec.param_key¶
Set on field · Type string · Number 60029
Parameter key mapping for FromMap generation
Explicitly maps this field to a specific enum value for parameter parsing
Example: [(consts.param_key) = "TOKEN_PARAM_KEY_CLIENT_ID"]
spec.required_if_false¶
Set on field · Type string · Number 60030
Conditional requirement: this field is required when another field equals false
Specifies the name of a boolean field that, when false, makes this field required
Example: [(consts.required_if_false) = "disable_tls"] means this field is required when disable_tls is false
spec.required_if_true¶
Set on field · Type string · Number 60031
Conditional requirement: this field is required when another field equals true
Specifies the name of a boolean field that, when true, makes this field required
Example: [(consts.required_if_true) = "enable_cors"] means this field is required when enable_cors is true
spec.assert_host¶
Set on field · Type bool · Number 60032
Host validation (IP address OR FQDN)
Validates that a string is either a valid IP address (IPv4/IPv6) or a valid FQDN.
This is an OR check — the value must satisfy at least one of the two formats.
Use this for fields that accept a network host identifier.
spec.default_string¶
Set on field · Type string · Number 60033
Field-level default value annotations.
Attaches a default constant directly to a field. The code generators will
emit a constant named DEFAULT_{FIELD_NAME_UPPER_SNAKE} in the constants output.
Example: int32 partition_count = 5 [(spec.default_int) = 271];
spec.default_int¶
Set on field · Type int64 · Number 60034
No description in spec.proto.
spec.default_float¶
Set on field · Type double · Number 60035
No description in spec.proto.
spec.default_bool¶
Set on field · Type bool · Number 60036
was default_double — do not reuse 60049 (removed; use default_float for
all floating-point defaults, the parser always mapped it to default_float).
spec.key¶
Set on field · Type string · Number 60037
key provides a string identifier for mapping on Config fields.
Links a grpcserver.Config or statedb.Config field to its target service/state.
Example: statedb.Config state = 2 [(spec.key) = "BaseballState"];
spec.required_if_eq¶
Set on field · Type ConditionalRequirement · Number 60038
Conditional requirement: this field is required when another field equals a specific value.
Works with enum or string sibling fields.
Example: [(spec.required_if_eq) = {field: "action", value: "ACTION_PERMIT"}]
spec.assert_max_size¶
Set on field · Type uint32 · Number 60039
assert_max_size enforces a maximum length/count on string, bytes, repeated, and map fields.
For string/bytes: maximum byte length. Default 32,768 bytes (32 KB) when not set.
For repeated/map: maximum element count. Runtime default 1,024 elements when not set;
user protos are still linted to require explicit bounds unless exempt.
Use this to override the default for fields that need more or less capacity.
spec.assert_min_size¶
Set on field · Type uint32 · Number 60052
assert_min_size enforces a minimum length/count on string, bytes, repeated, and map fields.
For string/bytes: minimum byte length. For repeated/map: minimum element count.
spec.assert_element_max_size¶
Set on field · Type uint32 · Number 60090
assert_element_max_size enforces a maximum BYTE LENGTH on each individual
element of a repeated or map field whose element type is string or bytes.
This is distinct from assert_max_size on the same field, which bounds the
element COUNT: a field may carry both.
bounds the field to 32 domains of at most 253 bytes each.
For a map field the bound applies to each VALUE; map keys keep the 32,768
byte default. Only valid on a repeated field of type string/bytes or on a
map with a string/bytes value type — applying it anywhere else is a
generation error. When unset, each element falls back to the 32,768 byte
(32 KB) default the generated validators already enforce.
spec.assert_sql¶
Set on field · Type SqlPermit · Number 60046
SQL statement validation: a syntactic sanity check, NOT an injection defense.
Checks that a string looks like a single statement of the permitted type: it rejects a
few obvious tokens (semicolons, -- and /* comments, backslash escapes) and verifies the
leading keyword. It does NOT make an interpolated string injection-safe -- a permitted
SELECT can still carry a UNION/subquery payload, and other comment syntaxes (e.g. a
'#' line comment) are not rejected. Callers MUST use parameterized queries.
Example: string query = 1 [(spec.assert_sql) = SQL_PERMIT_SELECT];
spec.default_const¶
Set on field · Type string · Number 60047
References a file-level constant (int_const, string_const, float_const, bool_const)
as the default value for this field. The Defaults function will use the named constant
directly, so multiple fields can share the same default without duplicating values.
Example: int32 tcp_port = 5 [(spec.default_const) = "DEFAULT_PORT"];
spec.default_host¶
Set on field · Type DefaultHost · Number 60048
Default value for host.Host fields. Generates a Defaults() initialization
and a DEFAULT_{FIELD}_PORT constant.
Mirrors host.Host structure to avoid circular import with host.proto.
spec.indexed¶
Set on field · Type bool · Number 50010
Statedb field indexing: marks a field for state-store index creation
spec.index_type¶
Set on field · Type string · Number 50011
Statedb index type hint for indexed fields
"HASH", "SORTED", "BITMAP"
spec.private¶
Set on field · Type bool · Number 50013
Statedb private: field can never be accessed by other services (owner RW only)
spec.state_import¶
Set on field · Type string · Number 50014
state_import declares that this field's value comes from another service's
exported state. This is the canonical source for read-only cross-service
state imports; the imported root is derived from "package.StateName.field".
The projection currently supports singular message fields.
Example: [(spec.state_import) = "football.FootballState.roster"];
spec.queue¶
Set on field · Type bool · Number 50015
queue marks a state root field as a FIFO queue.
One consumer receives each item. Operations: offer, poll, peek, size.
Example: TaskItem task_queue = 3 [(spec.queue) = true];
spec.priority_queue¶
Set on field · Type string · Number 50016
priority_queue marks a state root field as a priority queue.
Value is the name of the field used for priority ordering (e.g., "severity").
Items consumed in priority order (highest first).
Example: AlertItem alert_queue = 4 [(spec.priority_queue) = "severity"];
spec.topic¶
Set on field · Type bool · Number 50017
topic marks a state root field as a pub/sub topic.
Every subscriber receives every message. Operations: publish, subscribe.
Example: EventData event_stream = 5 [(spec.topic) = true];
spec.leader¶
Set on field · Type bool · Number 50018
leader marks a queue, topic, or priority_queue field as requiring leader election.
When set, the generated code automatically manages election, lease renewal, and
watch streams. Write operations (Offer/Publish) are gated on leader status.
The hand-written code must implement a leader handler callback.
Example: TaskItem task_queue = 3 [(spec.queue) = true, (spec.leader) = true];
spec.sync_backup_count¶
Set on field · Type int32 · Number 50020
NOT IMPLEMENTED. Statedb storage: number of synchronous backups for this
boundary. No generator reads this; generation REJECTS it rather than accept a
durability intent tacplus does not honour (GEN-ANN-1).
spec.async_backup_count¶
Set on field · Type int32 · Number 50021
NOT IMPLEMENTED. Statedb storage: number of asynchronous backups for this
boundary. No generator reads this; generation REJECTS it (GEN-ANN-1).
spec.eviction_policy¶
Set on field · Type EvictionPolicy · Number 50022
NOT IMPLEMENTED. Statedb eviction: which entries to evict when max_size is
reached. No generator reads this; generation REJECTS it (GEN-ANN-1).
spec.eviction_max_size¶
Set on field · Type int32 · Number 50023
Statedb eviction: maximum number of entries (or heap metric) before eviction begins.
Default: 0 (no limit).
spec.eviction_max_size_policy¶
Set on field · Type MaxSizePolicy · Number 50024
NOT IMPLEMENTED. Statedb eviction: what the eviction_max_size limit refers
to. No generator reads this; generation REJECTS it (GEN-ANN-1).
spec.eviction_ttl_seconds¶
Set on field · Type int64 · Number 50025
NOT IMPLEMENTED. Statedb eviction: time-to-live for entries in seconds. No
generator reads this; generation REJECTS it, because a boundary that silently
never expires anything is the failure it was meant to prevent (GEN-ANN-1).
For per-entry expiry use (spec.epoch_expiration) on the collection item.
spec.eviction_max_idle_seconds¶
Set on field · Type int64 · Number 50026
NOT IMPLEMENTED. Statedb eviction: maximum idle time for entries in seconds.
No generator reads this; generation REJECTS it (GEN-ANN-1).
spec.epoch_expiration¶
Set on field · Type bool · Number 50027
epoch_expiration marks an int64 field as a Unix epoch expiration timestamp (seconds).
Collections only: 0 = no expiration; > 0 must be future and within 1 year.
TTL = epoch - now at write time; the state store auto-removes the entry on expiry.
The check runs on write and on the wire, not on a disk load: stored data ages.
Placement validation: a scalar state-root field carrying this annotation is
REJECTED at generation time. CARVE-OUT (accepted-and-ignored, not validated):
an int64 inside a message used only as a SINGLETON boundary — detecting that
needs whole-graph collection-usage analysis and would false-reject item types
shared between collection and singleton uses (e.g. jwk.proto JWK.exp).
spec.persistence¶
Set on field · Type bool · Number 50028
persistence requests that a graph boundary (singleton, collection, map) be
durable. NO STATE STORE IMPLEMENTS IT TODAY. Kernel does not: kernel is
in-memory coordination plus its own identity snapshot, and it holds no durable
user data (decision 2026-09-25, reversing 2026-09-23). No generated state
client in any language writes the boundary to local disk either. tacplus
implements nothing here: it carries the flag to registry.json
(BoundaryInfo.persistence), descriptively, for a future store that does.
Placement validation: setting this on a state root whose
(spec.service_state).label includes "kernel" is a generation ERROR —
durable data belongs in stored records ((spec.record) + (spec.record_store)),
not in a kernel boundary — UNLESS that state root also sets
(spec.service_state).identity_snapshot = true, the carve-out for kernel's
own identity snapshot the decision itself names. Unrelated to typed disk
persistence, which is keyed off (spec.service_store) and
grpcconfig.disk_persistence.
Can only be set on message-typed boundary fields.
Cannot be set on queues, topics, or priority queues.
spec.refresh_on_miss¶
Set on field · Type string · Number 50031
refresh_on_miss names the message type used as the lookup request
for cache-miss-triggered refresh. When set, tacplus generates a
Lookup{FieldName} RPC on the state service.
The implementation checks the boundary for a match, refreshes from
the external source on miss, and returns the updated boundary value.
Only valid on message-typed boundary fields.
Cannot combine with queue/topic/priority_queue.
spec.command¶
Set on field · Type bool · Number 50032
command marks this field as a command RPC on the state service.
The field type is the request message; the response is always google.protobuf.Empty.
Commands are mutations. Use boundary_callers to restrict which services can
invoke the command cross-namespace.
spec.view_sources¶
Set on field · Type repeated string · Number 50033
view_sources marks a field as a read-only view over multiple collection boundaries.
Each entry is the field name of a source collection within the same service_state.
The view unions all source collections into a single read-only boundary.
Generated RPCs: Get, GetAll, Watch, KeySet, Size, ContainsKey (read-only subset).
No mutator RPCs (Put, Set, Delete, Remove, Clear) are generated.
The indexed field (kid, node_id, etc.) must be unique across all source collections.
Writes to a source collection that would violate cross-source uniqueness are rejected.
Requirements:
- The field must be repeated.
- All source fields must be collections of the same message type.
- At least two source fields must be specified.
- The field is a view (not stored): it aggregates the source collections.
Example:
repeated ManagedJwk config_keys = 1;
repeated ManagedJwk dynamic_keys = 2;
repeated ManagedJwk all_keys = 3 [
(spec.view_sources) = "config_keys",
(spec.view_sources) = "dynamic_keys"
];
spec.boundary_callers¶
Set on field · Type repeated string · Number 50036
boundary_callers lists services allowed to call this boundary cross-namespace.
Applies to queue (offer), topic (publish), and command (exec) boundaries.
Example: TaskItem task_queue = 3 [(spec.queue) = true, (spec.boundary_callers) = "woodstock"];
spec.view_member¶
Set on field · Type repeated string · Number 50035
view_member registers this collection as a contributing source to one or
more named cross-boundary views. All collections sharing a view_member
value are aggregated by the cluster into that read-only view service. A
collection may belong to multiple views (e.g. an internal-signing-key
collection that feeds both "JwkVerifyingKeysView" for internal verifiers
and "PublicJwksView" for the gateway's public JWKS).
Each value must match a view service defined in the embedded protos
(e.g., "JwkVerifyingKeysView" from sys/jwkview.proto).
Requirements:
- The field must be a repeated (collection) boundary.
- All members of the same view must have the same message type.
- The message type must have an (spec.indexed) field for entry keying.
spec.instance_keyed¶
Set on field · Type bool · Number 50034
instance_keyed: server extracts instance_id from the caller's token
and uses "service_id@instance_id" as the entry key. The publisher
sees a singleton Set API (no key param). Consumers see a collection.
spec.store_key¶
Set on field · Type bool · Number 50037
store_key marks a field as the entry key for a service_store message.
Exactly one field per service_store message must have this annotation.
The field type must be string. The key is used as the entry key.
spec.quorum_write¶
Set on field · Type bool · Number 50038
quorum_write marks a state field as requiring write quorum: the write is
acked only after the value is durable on (spec.min_durable_copies) distinct
nodes. Only valid on fields within a service_state or service_store message.
BELOW THAT THRESHOLD THE WRITE IS REJECTED, NOT ACKED. This comment used to
read "on a single-node cluster, writes succeed immediately (no quorum
possible)" — an implicit auto-degrade on cluster size. That was retired
(ruling, 2026-08-29) because a production cluster that has lost two members
is indistinguishable from a laptop, so the degrade silently converts the
durability guarantee into its absence exactly when it matters. The threshold
is now an explicit knob: see (spec.min_durable_copies) below, which a local
dev tree sets to 1 DELIBERATELY.
spec.min_durable_copies¶
Set on field · Type int32 · Number 50040
min_durable_copies is how many distinct nodes must hold a value durably
before a (spec.quorum_write) field's write is acked. Default 2 when unset;
\1 is the deliberate single-node development setting.
A write that cannot reach this many durable copies is REJECTED with
FAILED_PRECONDITION before any local effect — it never acks-then-hopes. That
is the whole point of the knob: the alternative (degrade to whatever the
cluster can manage) is the failure the threshold exists to catch.
Only valid on a field that also carries (spec.quorum_write): a durability
threshold on a field with no quorum requirement is a knob nothing reads, and
generation REJECTS it rather than accept an intent tacplus does not honour
(ValidateMinDurableCopiesAnnotations).
Values below 1 are a generation error. A value of 1 disables the
multi-node requirement and is legal, loudly, for local development.
spec.collected_health¶
Set on field · Type bool · Number 50039
collected_health marks a state boundary for Sentinel health collection.
Sentinel discovers instances via ServiceHealthState, calls a generated
GetXxx RPC on the source service, and writes results to state.
Singular fields → query ONE node. Repeated fields → query ALL nodes.
Per-node (repeated) entries are keyed by instance_id and auto-evicted
when Sentinel stops updating them (use eviction_ttl_seconds).
spec.projection_source¶
Set on field · Type string · Number 60063
projection_source maps a projection field to its source path on the event message.
Used on fields within messages annotated with (spec.timeseries_type)
that have a source set. Uses dot notation for
nested/oneof field access.
Examples:
"agent_id" — top-level field on the source event
"tool_use.tool_name" — field inside a oneof/nested payload
"tool_use.duration_ms" — nested int64 field
spec.projection_record_key¶
Set on field · Type bool · Number 60081
projection_record_key marks the projection field that carries the SOURCE
RECORD's key. tacplus auto-injects this field (or marks the existing one) on
every timeseries projection so the projection query can return record
keys — the record store federates into a projection, gets record keys, and hydrates the
full records from the record_store. Exactly one field per projection carries it.
spec.assert_invariant¶
Set on field · Type string · Number 60053
assert_invariant declares a formal invariant for this field.
The expression is a boolean predicate in the target language's syntax.
For Rust: used as kani::assume() in proof harnesses and debug_assert! in validate().
For Java: emitted as //@ invariant ... (JML).
Use for cross-field relationships that can't be expressed as single-field constraints.
Example: string token = 1 [(spec.assert_invariant) = "self.ttl > 0 && self.ttl <= 86400"];
spec.cache¶
Set on field · Type bool · Number 60054
cache marks this field for projection into the hot cache.
When true, this field is included in the cache entry.
Example: string display_name = 3 [(spec.cache) = true];
spec.timeseries¶
Set on field · Type bool · Number 60055
timeseries marks this field for projection into the timeseries store.
When true, this field is included in the timeseries materialized view.
Example: int64 first_seen_ms = 5 [(spec.timeseries) = true];
spec.json_key¶
Set on field · Type string · Number 60061
JSON key override: specifies the output key used in JSON serialization.
The generated JSON helpers use this instead of the proto field name.
Use when the proto field was renamed to avoid language keyword conflicts
but the JSON wire format must remain unchanged.
Example: int64 reset_at = 4 [(spec.json_key) = "reset"];
spec.json_aliases¶
Set on field · Type repeated string · Number 60062
JSON aliases: additional keys accepted during JSON deserialization.
Used alongside json_key and the proto field name for flexible input parsing.
Example: string callback_url = 5 [(spec.json_aliases) = "callbackUrl"];
spec.timeseries_column¶
Set on field · Type TimeseriesFieldOption · Number 60066
── Timeseries Projection Annotations ────────────────────────────────────────
Controls how individual fields map to timeseries columns. Fields without
this annotation are omitted — timeseries projection is opt-in.
See TimeseriesFieldOption for detailed documentation.
Example:
string session_id = 1 [(spec.timeseries_column) = {order_key: 1}];
int64 timestamp_ms = 2 [(spec.timeseries_column) = {order_key: 2, partition_key: true}];
string event_type = 3 [(spec.timeseries_column) = {cardinality_hint: CARDINALITY_LOW}];
spec.identity_namespace¶
Set on field · Type bool · Number 60075
identity_namespace: this string field holds an authorization-tree namespace
path; generated code normalizes it via normalize_namespace before use.
spec.identity_subject¶
Set on field · Type bool · Number 60076
identity_subject: this string field holds a stable principal subject id
(the sub), not a full SPIFFE URI.
spec.identity_spiffe_subject¶
Set on field · Type bool · Number 60077
identity_spiffe_subject: this string field holds a full SUBJECT SPIFFE ID,
constructed/validated via sys/spiffe (durable subject key, e.g. workload).
spec.identity_spiffe_resource¶
Set on field · Type IdentitySpiffeResource · Number 60078
identity_spiffe_resource: this string field holds a RESOURCE SPIFFE ID that
tacplus constructs from sibling fields; see IdentitySpiffeResource.
spec.query_field¶
Set on field · Type QueryFieldOption · Number 60080
query_field: marks this record field as a typed filter criterion for the
generated RecordMap query plane (Open<T>Query / Refine<T>). tacplus emits a typed
<T>Filter message from the queryable fields. EQ → optional <type> <name>;
RANGE → optional <type> <name>_from + optional <type> <name>_to (ordered
fields, e.g. int64 timestamp_ms). The store transforms the filter into its
query; tacplus knows only the shape, never the query→SQL transform.
spec.redact¶
Set on field · Type RedactOption · Number 60082
redact: marks this record field as REDACTABLE AT EGRESS. Records are stored
raw; the record store applies the field's mode when the caller's entitlements
do not reveal it (at Sample/Pull only — never baked into stored state). tacplus
generates a typed Sanitize<T>(record, <T>Entitlement, hmacKey) transform; the
store computes the entitlement (mechanism in tacplus, policy in service).
spec.principal¶
Set on field · Type bool · Number 60083
principal: this REQUEST string field carries the caller's principal. The
generated wrapper resolves the authenticated caller's subject and then:
- empty -> stamps the subject into the field before the handler runs;
- equal -> accepts unchanged;
- differs-> refuses with INVALID_ARGUMENT (never silently overwritten).
An unauthenticated caller on a principal-bearing RPC is UNAUTHENTICATED.
Example: string created_by = 2 [(spec.principal) = true];
spec.store_principal¶
Set on field · Type bool · Number 60084
store_principal: this RECORD string field holds the row's owning principal.
The generated wrapper filters every repeated field of that record type in a
response down to rows the caller owns, so a read plane cannot return one
principal's rows to another. Egress-side only, exactly like (spec.redact):
rows are stored raw and the filter is applied on the way out.
Example: string created_by = 4 [(spec.store_principal) = true];
spec.identity_spiffe_actor¶
Set on field · Type bool · Number 60085
identity_spiffe_actor: this OPTIONAL string field holds the delegated-
mint actor's identity, stamped by EventBus from the token's act claim
(JWT_PAYLOAD_TYPE_ACT) at publish time — the delegate/agent that made
the call on the user's behalf, distinct from (spec.identity_spiffe_subject)
which is always the authenticated caller (the user, when delegated).
Unset when the token carries no act claim (the ordinary, non-delegated
case). This field is provenance metadata on the event envelope ONLY —
it is never a (spec.principal)/(spec.store_principal) field and must
never be wired into either.
spec.store_epoch¶
Set on field · Type bool · Number 60086
store_epoch: this RECORD int64 field holds the row's STORE EPOCH — Unix
milliseconds of the row's LAST WRITE, stamped by the generated wrapper.
Same doctrine as (spec.principal)/(spec.store_principal) above: the
annotation says WHERE the value lives, once, on the type; the generated
wrapper owns the stamp so no handler hand-writes it.
WHERE THE STAMP HAPPENS. A record has no write RPC — it reaches the store
on the store's EventBus subscription (spec.record implies spec.event), so
the stamping seam is the generated service manager's subscription dispatch,
not a request wrapper. There is therefore no caller to refuse: the store's
clock is stamped over whatever arrived, UNCONDITIONALLY, which is a
stronger guarantee than a refusal (the value cannot be caller-influenced at
all) and does not drop the record. A producer that sets the field is not
erroring, it is writing into a slot the store owns.
The store epoch is the row's last WRITE, durable, and it is what
(spec.record).residency.deleted_max_age_seconds measures a delete from, plus
the predicate a sweep or a restore orders on. It is therefore also a RANGE
query criterion in the generated filter, so the field carries
(spec.query_field) = {op: QUERY_OP_RANGE}.
It is NOT the residency clock. residency.idle_seconds runs on reads AND
writes and lives only in memory: a read never restamps this field, never
writes the event log, never touches disk.
NOT (spec.epoch_expiration) either (above, statedb per-entry TTL). Different
clocks; only this one is store-owned and durable.
spec.namespace¶
Set on field · Type bool · Number 60087
namespace: this REQUEST string field carries the caller's namespace. The
generated wrapper resolves the authenticated caller's namespace claim and
then, exactly as (spec.principal) does for the subject:
- empty -> stamps the namespace into the field before the handler runs;
- equal -> accepts unchanged;
- differs-> refuses with INVALID_ARGUMENT (never silently overwritten).
An unauthenticated caller on a namespace-bearing RPC is UNAUTHENTICATED.
Example: string namespace = 2 [(spec.namespace) = true];
spec.store_namespace¶
Set on field · Type bool · Number 60088
store_namespace: this RECORD string field holds the row's owning namespace.
MANDATORY: every (spec.record)-annotated message must declare exactly one,
and generation FAILS for one that does not — the same posture the record
query plane's non-empty auth_services requirement already takes. An opt-in
isolation backstop is not a backstop; the annotation an author forgets is
exactly the record that leaks.
The generated wrapper filters every repeated field of that record type in a
response down to rows whose stamped namespace EXACTLY equals the caller's.
Egress-side only, exactly like (spec.store_principal): rows are stored raw
and the filter is applied on the way out.
A row that has to be filtered CRASHES THE PROCESS rather than failing the
one call. Reaching that line means the store handed the wrapper another
tenant's row, which multi-tenant tests are supposed to catch before release
and a canary is built to absorb; a crash-rate spike halts a rollout, where
a per-call error would be swallowed. Against a silent cross-tenant leak an
availability blip is the cheaper failure.
Example: string namespace = 5 [(spec.store_namespace) = true];
spec.deleted_flag¶
Set on field · Type bool · Number 60091
deleted_flag: this RECORD bool field records the row's SOFT-DELETE state.
A marker, like (spec.store_epoch) and (spec.store_namespace) above: the
annotation owns the LOCATION and nothing else. Deletion is an ordinary
republish that sets the flag — the row's last write. The row is still in
memory for its idle window, still on disk, still fetchable by key.
The generated query plane EXCLUDES flagged-true rows from List / Watch /
Count / Sample by default; the query message gains include_deleted for audit
and citation cases, and Get by key always returns the row, deleted or not,
until it is purged. A flagged row older than
(spec.record).residency.deleted_max_age_seconds is purged at the next sweep.
EXACTLY ONE such field per record message, or none: a record with no
soft-delete marker (an append-only type, say) is valid and nothing is
excluded from its queries. ValidateDeletedFlagAnnotations refuses anything
else — a non-record message, a non-bool field, or two marked fields.
Example:
spec.visibility¶
Set on field · Type Visibility · Number 60092
visibility: on a field of a (spec.public_view) message, whether the field
may be rendered outside the company (VISIBILITY_SHOW) or never leaves it
(VISIBILITY_BACKGROUND). Required on every field of a public_view message
and refused on any other message. Only SHOW fields appear in the generated
<T>Public; a BACKGROUND field is absent from it by construction.
Example: