//! Generated by `trust-tasks-codegen` — do not edit by hand.
//!
//! Spec slug: `vta/app-state/list`. Version: `1.0`.
#[allow(unused_imports)]
use serde::{Deserialize, Serialize};
/// Error types.
pub mod error {
/// Error from a `TryFrom` or `FromStr` implementation.
pub struct ConversionError(::std::borrow::Cow<'static, str>);
impl ::std::error::Error for ConversionError {}
impl ::std::fmt::Display for ConversionError {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> Result<(), ::std::fmt::Error> {
::std::fmt::Display::fmt(&self.0, f)
}
}
impl ::std::fmt::Debug for ConversionError {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> Result<(), ::std::fmt::Error> {
::std::fmt::Debug::fmt(&self.0, f)
}
}
impl From<&'static str> for ConversionError {
fn from(value: &'static str) -> Self {
Self(value.into())
}
}
impl From<String> for ConversionError {
fn from(value: String) -> Self {
Self(value.into())
}
}
}
///A record as the maintainer holds it. `value` is absent in three distinct situations and a consumer MUST NOT conflate them: the record is a tombstone (`deleted` is true); the caller asked for a metadata-only view (`list` without `includeValues`); or the value genuinely is the JSON literal `null`, in which case `value` is PRESENT and null. This is why `deleted` is required rather than defaulted — a consumer that has to infer deletion from an absent value gets the tombstone case wrong exactly when convergence depends on it.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "AppStateRecord",
/// "description": "A record as the maintainer holds it. `value` is absent in three distinct situations and a consumer MUST NOT conflate them: the record is a tombstone (`deleted` is true); the caller asked for a metadata-only view (`list` without `includeValues`); or the value genuinely is the JSON literal `null`, in which case `value` is PRESENT and null. This is why `deleted` is required rather than defaulted — a consumer that has to infer deletion from an absent value gets the tombstone case wrong exactly when convergence depends on it.",
/// "type": "object",
/// "required": [
/// "contextId",
/// "deleted",
/// "key",
/// "namespace",
/// "updatedAt",
/// "version"
/// ],
/// "properties": {
/// "contextId": {
/// "description": "The VTA context the record is scoped to; the isolation boundary.",
/// "type": "string",
/// "minLength": 1
/// },
/// "createdAt": {
/// "description": "When the record was first created at this address. MAY be absent on a tombstone whose body has been discarded.",
/// "type": "string",
/// "format": "date-time"
/// },
/// "deleted": {
/// "description": "True when this is a tombstone: the record was deleted, and this entry exists so that a consumer syncing incrementally learns of the deletion. Tombstones are reaped after the maintainer's retention window; see `vta/app-state/list`.",
/// "type": "boolean"
/// },
/// "deletedAt": {
/// "description": "When the record was deleted. Present only when `deleted` is true; equal to `updatedAt` for a tombstone the maintainer has not since rewritten.",
/// "type": "string",
/// "format": "date-time"
/// },
/// "key": {
/// "$ref": "#/definitions/Key"
/// },
/// "namespace": {
/// "$ref": "#/definitions/Namespace"
/// },
/// "updatedAt": {
/// "description": "When the write that produced this `version` was applied. For a tombstone, when the delete was applied.",
/// "type": "string",
/// "format": "date-time"
/// },
/// "value": {
/// "description": "The stored JSON, in whatever shape the owning application chose. Any JSON value, including `null`. The maintainer neither validates nor interprets it. Absent when this is a tombstone or a metadata-only view — see this definition's description for why that is not the same as a null value."
/// },
/// "valueBytes": {
/// "description": "Size of the stored value in bytes, measured as the maintainer measures it for the per-record cap (see `vta/app-state/put`). Present in metadata-only views so a consumer can decide what to fetch without fetching it; absent on a tombstone.",
/// "type": "integer",
/// "minimum": 0.0
/// },
/// "version": {
/// "description": "The namespace counter value this record's most recent write took. Supply it as `expectedVersion` on the next write to make that write conditional on nothing having changed in between.",
/// "$ref": "#/definitions/Version"
/// }
/// },
/// "additionalProperties": false
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
pub struct AppStateRecord {
///The VTA context the record is scoped to; the isolation boundary.
#[serde(rename = "contextId")]
pub context_id: AppStateRecordContextId,
///When the record was first created at this address. MAY be absent on a tombstone whose body has been discarded.
#[serde(
rename = "createdAt",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub created_at: ::std::option::Option<::chrono::DateTime<::chrono::offset::Utc>>,
///True when this is a tombstone: the record was deleted, and this entry exists so that a consumer syncing incrementally learns of the deletion. Tombstones are reaped after the maintainer's retention window; see `vta/app-state/list`.
pub deleted: bool,
///When the record was deleted. Present only when `deleted` is true; equal to `updatedAt` for a tombstone the maintainer has not since rewritten.
#[serde(
rename = "deletedAt",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub deleted_at: ::std::option::Option<::chrono::DateTime<::chrono::offset::Utc>>,
pub key: Key,
pub namespace: Namespace,
///When the write that produced this `version` was applied. For a tombstone, when the delete was applied.
#[serde(rename = "updatedAt")]
pub updated_at: ::chrono::DateTime<::chrono::offset::Utc>,
///The stored JSON, in whatever shape the owning application chose. Any JSON value, including `null`. The maintainer neither validates nor interprets it. Absent when this is a tombstone or a metadata-only view — see this definition's description for why that is not the same as a null value.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub value: ::std::option::Option<::serde_json::Value>,
///Size of the stored value in bytes, measured as the maintainer measures it for the per-record cap (see `vta/app-state/put`). Present in metadata-only views so a consumer can decide what to fetch without fetching it; absent on a tombstone.
#[serde(
rename = "valueBytes",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub value_bytes: ::std::option::Option<u64>,
///The namespace counter value this record's most recent write took. Supply it as `expectedVersion` on the next write to make that write conditional on nothing having changed in between.
pub version: Version,
}
///The VTA context the record is scoped to; the isolation boundary.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The VTA context the record is scoped to; the isolation boundary.",
/// "type": "string",
/// "minLength": 1
///}
/// ```
/// </details>
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct AppStateRecordContextId(::std::string::String);
impl ::std::ops::Deref for AppStateRecordContextId {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<AppStateRecordContextId> for ::std::string::String {
fn from(value: AppStateRecordContextId) -> Self {
value.0
}
}
impl ::std::str::FromStr for AppStateRecordContextId {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
if value.chars().count() < 1usize {
return Err("shorter than 1 characters".into());
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for AppStateRecordContextId {
type Error = self::error::ConversionError;
fn try_from(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for AppStateRecordContextId {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for AppStateRecordContextId {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl<'de> ::serde::Deserialize<'de> for AppStateRecordContextId {
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: ::serde::Deserializer<'de>,
{
::std::string::String::deserialize(deserializer)?
.parse()
.map_err(|e: self::error::ConversionError| {
<D::Error as ::serde::de::Error>::custom(e.to_string())
})
}
}
///Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "Ext",
/// "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
/// "type": "object",
/// "minProperties": 1,
/// "additionalProperties": true,
/// "propertyNames": {
/// "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct Ext(pub ::std::collections::HashMap<ExtKey, ::serde_json::Value>);
impl ::std::ops::Deref for Ext {
type Target = ::std::collections::HashMap<ExtKey, ::serde_json::Value>;
fn deref(&self) -> &::std::collections::HashMap<ExtKey, ::serde_json::Value> {
&self.0
}
}
impl ::std::convert::From<Ext> for ::std::collections::HashMap<ExtKey, ::serde_json::Value> {
fn from(value: Ext) -> Self {
value.0
}
}
impl ::std::convert::From<::std::collections::HashMap<ExtKey, ::serde_json::Value>> for Ext {
fn from(value: ::std::collections::HashMap<ExtKey, ::serde_json::Value>) -> Self {
Self(value)
}
}
///`ExtKey`
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "type": "string",
/// "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
///}
/// ```
/// </details>
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct ExtKey(::std::string::String);
impl ::std::ops::Deref for ExtKey {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<ExtKey> for ::std::string::String {
fn from(value: ExtKey) -> Self {
value.0
}
}
impl ::std::str::FromStr for ExtKey {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
static PATTERN: ::std::sync::LazyLock<::regress::Regex> =
::std::sync::LazyLock::new(|| {
::regress::Regex::new("^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$").unwrap()
});
if PATTERN.find(value).is_none() {
return Err("doesn't match pattern \"^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$\"".into());
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for ExtKey {
type Error = self::error::ConversionError;
fn try_from(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for ExtKey {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for ExtKey {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl<'de> ::serde::Deserialize<'de> for ExtKey {
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: ::serde::Deserializer<'de>,
{
::std::string::String::deserialize(deserializer)?
.parse()
.map_err(|e: self::error::ConversionError| {
<D::Error as ::serde::de::Error>::custom(e.to_string())
})
}
}
///Application-chosen identifier for a record within a namespace. Opaque to the maintainer: it MUST NOT be parsed, normalized, or case-folded, and prefix matching in `list` is a byte-prefix comparison over the UTF-8 encoding. Applications SHOULD use `/`-delimited hierarchical keys (`community/acme`, `contact/z6Mk…`) so that `prefix` can address a record family, but the delimiter is a convention between an application and itself — the maintainer attaches no meaning to it.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "Key",
/// "description": "Application-chosen identifier for a record within a namespace. Opaque to the maintainer: it MUST NOT be parsed, normalized, or case-folded, and prefix matching in `list` is a byte-prefix comparison over the UTF-8 encoding. Applications SHOULD use `/`-delimited hierarchical keys (`community/acme`, `contact/z6Mk…`) so that `prefix` can address a record family, but the delimiter is a convention between an application and itself — the maintainer attaches no meaning to it.",
/// "type": "string",
/// "maxLength": 512,
/// "minLength": 1,
/// "pattern": "^[^\\u0000]+$"
///}
/// ```
/// </details>
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct Key(::std::string::String);
impl ::std::ops::Deref for Key {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<Key> for ::std::string::String {
fn from(value: Key) -> Self {
value.0
}
}
impl ::std::str::FromStr for Key {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
if value.chars().count() > 512usize {
return Err("longer than 512 characters".into());
}
if value.chars().count() < 1usize {
return Err("shorter than 1 characters".into());
}
static PATTERN: ::std::sync::LazyLock<::regress::Regex> =
::std::sync::LazyLock::new(|| ::regress::Regex::new("^[^\\u0000]+$").unwrap());
if PATTERN.find(value).is_none() {
return Err("doesn't match pattern \"^[^\\u0000]+$\"".into());
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for Key {
type Error = self::error::ConversionError;
fn try_from(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for Key {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for Key {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl<'de> ::serde::Deserialize<'de> for Key {
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: ::serde::Deserializer<'de>,
{
::std::string::String::deserialize(deserializer)?
.parse()
.map_err(|e: self::error::ConversionError| {
<D::Error as ::serde::de::Error>::custom(e.to_string())
})
}
}
///Scopes one application's records within a context, so several tools can share a context without colliding — `openvtc`, `cnm`, an agent runtime. The maintainer MUST NOT interpret the value; it is an opaque partition name. Namespaces are first-come and unreserved, so an application SHOULD pick a stable, specific one: a future per-namespace ACL would grant on this exact string, which makes renaming a namespace a migration rather than an edit.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "Namespace",
/// "description": "Scopes one application's records within a context, so several tools can share a context without colliding — `openvtc`, `cnm`, an agent runtime. The maintainer MUST NOT interpret the value; it is an opaque partition name. Namespaces are first-come and unreserved, so an application SHOULD pick a stable, specific one: a future per-namespace ACL would grant on this exact string, which makes renaming a namespace a migration rather than an edit.",
/// "type": "string",
/// "maxLength": 64,
/// "minLength": 1,
/// "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
///}
/// ```
/// </details>
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct Namespace(::std::string::String);
impl ::std::ops::Deref for Namespace {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<Namespace> for ::std::string::String {
fn from(value: Namespace) -> Self {
value.0
}
}
impl ::std::str::FromStr for Namespace {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
if value.chars().count() > 64usize {
return Err("longer than 64 characters".into());
}
if value.chars().count() < 1usize {
return Err("shorter than 1 characters".into());
}
static PATTERN: ::std::sync::LazyLock<::regress::Regex> =
::std::sync::LazyLock::new(|| {
::regress::Regex::new("^[a-z][a-z0-9]*(-[a-z0-9]+)*$").unwrap()
});
if PATTERN.find(value).is_none() {
return Err("doesn't match pattern \"^[a-z][a-z0-9]*(-[a-z0-9]+)*$\"".into());
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for Namespace {
type Error = self::error::ConversionError;
fn try_from(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for Namespace {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for Namespace {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl<'de> ::serde::Deserialize<'de> for Namespace {
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: ::serde::Deserializer<'de>,
{
::std::string::String::deserialize(deserializer)?
.parse()
.map_err(|e: self::error::ConversionError| {
<D::Error as ::serde::de::Error>::custom(e.to_string())
})
}
}
///Enumerate application-state records in a context. Two modes, distinguished by whether `sinceVersion` is supplied. Without it this is a SNAPSHOT of live records, optionally narrowed by `prefix`. With it this is a CHANGE FEED: every record in the namespace whose version exceeds the watermark, tombstones included, which is what lets an incremental consumer converge. Pagination is opaque-cursor based.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "$id": "https://trusttasks.org/spec/vta/app-state/list/1.0",
/// "title": "Payload",
/// "description": "Enumerate application-state records in a context. Two modes, distinguished by whether `sinceVersion` is supplied. Without it this is a SNAPSHOT of live records, optionally narrowed by `prefix`. With it this is a CHANGE FEED: every record in the namespace whose version exceeds the watermark, tombstones included, which is what lets an incremental consumer converge. Pagination is opaque-cursor based.",
/// "type": "object",
/// "required": [
/// "contextId"
/// ],
/// "properties": {
/// "contextId": {
/// "description": "The VTA context to enumerate; the isolation boundary.",
/// "type": "string",
/// "minLength": 1
/// },
/// "cursor": {
/// "description": "Opaque continuation token from a previous response. Consumers MUST treat it as opaque: never construct, decode, mutate, or infer meaning from one.",
/// "type": "string"
/// },
/// "ext": {
/// "description": "Ecosystem-defined extension members per SPEC.md §4.5.1.",
/// "$ref": "#/definitions/Ext"
/// },
/// "includeDeleted": {
/// "description": "Snapshot mode only: when true, tombstones still inside the retention window are returned alongside live records. Defaults to false. In change-feed mode tombstones are always returned and this member MUST NOT be set to false — a change feed that omits deletions cannot converge, so asking for one is a contradiction rather than a preference.",
/// "type": "boolean"
/// },
/// "includeValues": {
/// "description": "When true, each returned record carries its `value`. Defaults to false, which returns the metadata view — address, version, timestamps, `valueBytes` — so a prefix scan is cheap. Setting it makes a scan one round trip rather than a scan plus N gets, at the cost of the response carrying every value.",
/// "type": "boolean"
/// },
/// "namespace": {
/// "description": "Restrict to one namespace. Optional in snapshot mode, where omitting it enumerates every namespace the caller can read in the context. REQUIRED in change-feed mode, because the version counter `sinceVersion` is compared against is maintained per (contextId, namespace) and a watermark spanning namespaces would name no single point in time.",
/// "$ref": "#/definitions/Namespace"
/// },
/// "pageSize": {
/// "description": "Caller's upper bound on records per page. The maintainer applies its own ceiling and MAY return fewer — notably when `includeValues` is set and the values are large.",
/// "type": "integer",
/// "maximum": 1000.0,
/// "minimum": 1.0
/// },
/// "prefix": {
/// "description": "Restrict to records whose `key` begins with this byte prefix, compared over the UTF-8 encoding. Lets a consumer read one record family — `community/`, `contact/` — without dragging every record in the namespace through the response.",
/// "type": "string",
/// "maxLength": 512
/// },
/// "sinceVersion": {
/// "description": "Watermark. Selects change-feed mode: only records whose `version` is strictly greater are returned, tombstones included. Supply the `highWatermark` from the previous sync, or 0 for a first full pull in change-feed form. Requires `namespace`.",
/// "type": "integer",
/// "minimum": 0.0
/// }
/// },
/// "additionalProperties": false
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
pub struct Payload {
///The VTA context to enumerate; the isolation boundary.
#[serde(rename = "contextId")]
pub context_id: PayloadContextId,
///Opaque continuation token from a previous response. Consumers MUST treat it as opaque: never construct, decode, mutate, or infer meaning from one.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub cursor: ::std::option::Option<::std::string::String>,
///Ecosystem-defined extension members per SPEC.md §4.5.1.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub ext: ::std::option::Option<Ext>,
///Snapshot mode only: when true, tombstones still inside the retention window are returned alongside live records. Defaults to false. In change-feed mode tombstones are always returned and this member MUST NOT be set to false — a change feed that omits deletions cannot converge, so asking for one is a contradiction rather than a preference.
#[serde(
rename = "includeDeleted",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub include_deleted: ::std::option::Option<bool>,
///When true, each returned record carries its `value`. Defaults to false, which returns the metadata view — address, version, timestamps, `valueBytes` — so a prefix scan is cheap. Setting it makes a scan one round trip rather than a scan plus N gets, at the cost of the response carrying every value.
#[serde(
rename = "includeValues",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub include_values: ::std::option::Option<bool>,
///Restrict to one namespace. Optional in snapshot mode, where omitting it enumerates every namespace the caller can read in the context. REQUIRED in change-feed mode, because the version counter `sinceVersion` is compared against is maintained per (contextId, namespace) and a watermark spanning namespaces would name no single point in time.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub namespace: ::std::option::Option<Namespace>,
///Caller's upper bound on records per page. The maintainer applies its own ceiling and MAY return fewer — notably when `includeValues` is set and the values are large.
#[serde(
rename = "pageSize",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub page_size: ::std::option::Option<::std::num::NonZeroU64>,
///Restrict to records whose `key` begins with this byte prefix, compared over the UTF-8 encoding. Lets a consumer read one record family — `community/`, `contact/` — without dragging every record in the namespace through the response.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub prefix: ::std::option::Option<PayloadPrefix>,
///Watermark. Selects change-feed mode: only records whose `version` is strictly greater are returned, tombstones included. Supply the `highWatermark` from the previous sync, or 0 for a first full pull in change-feed form. Requires `namespace`.
#[serde(
rename = "sinceVersion",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub since_version: ::std::option::Option<u64>,
}
///The VTA context to enumerate; the isolation boundary.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The VTA context to enumerate; the isolation boundary.",
/// "type": "string",
/// "minLength": 1
///}
/// ```
/// </details>
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct PayloadContextId(::std::string::String);
impl ::std::ops::Deref for PayloadContextId {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<PayloadContextId> for ::std::string::String {
fn from(value: PayloadContextId) -> Self {
value.0
}
}
impl ::std::str::FromStr for PayloadContextId {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
if value.chars().count() < 1usize {
return Err("shorter than 1 characters".into());
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for PayloadContextId {
type Error = self::error::ConversionError;
fn try_from(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for PayloadContextId {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for PayloadContextId {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl<'de> ::serde::Deserialize<'de> for PayloadContextId {
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: ::serde::Deserializer<'de>,
{
::std::string::String::deserialize(deserializer)?
.parse()
.map_err(|e: self::error::ConversionError| {
<D::Error as ::serde::de::Error>::custom(e.to_string())
})
}
}
///Restrict to records whose `key` begins with this byte prefix, compared over the UTF-8 encoding. Lets a consumer read one record family — `community/`, `contact/` — without dragging every record in the namespace through the response.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Restrict to records whose `key` begins with this byte prefix, compared over the UTF-8 encoding. Lets a consumer read one record family — `community/`, `contact/` — without dragging every record in the namespace through the response.",
/// "type": "string",
/// "maxLength": 512
///}
/// ```
/// </details>
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct PayloadPrefix(::std::string::String);
impl ::std::ops::Deref for PayloadPrefix {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<PayloadPrefix> for ::std::string::String {
fn from(value: PayloadPrefix) -> Self {
value.0
}
}
impl ::std::str::FromStr for PayloadPrefix {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
if value.chars().count() > 512usize {
return Err("longer than 512 characters".into());
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for PayloadPrefix {
type Error = self::error::ConversionError;
fn try_from(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for PayloadPrefix {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for PayloadPrefix {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl<'de> ::serde::Deserialize<'de> for PayloadPrefix {
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: ::serde::Deserializer<'de>,
{
::std::string::String::deserialize(deserializer)?
.parse()
.map_err(|e: self::error::ConversionError| {
<D::Error as ::serde::de::Error>::custom(e.to_string())
})
}
}
///Success response to vta/app-state/list. Type https://trusttasks.org/spec/vta/app-state/list/1.0#response.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "Response",
/// "description": "Success response to vta/app-state/list. Type https://trusttasks.org/spec/vta/app-state/list/1.0#response.",
/// "type": "object",
/// "required": [
/// "records",
/// "truncated"
/// ],
/// "properties": {
/// "cursor": {
/// "description": "Opaque continuation token for the next page. Present only when `truncated` is true.",
/// "type": "string"
/// },
/// "ext": {
/// "description": "Ecosystem-defined extension members per SPEC.md §4.5.1.",
/// "$ref": "#/definitions/Ext"
/// },
/// "highWatermark": {
/// "description": "The namespace's current counter value. Present whenever `namespace` was supplied. This is what a consumer stores as its next `sinceVersion` — NOT the maximum version among `records`, which is wrong whenever a `prefix` filtered a later change out, and undefined when the page is empty. A paginating consumer MUST NOT advance its stored watermark until it has drained the final page, because the pages of one feed share this value and adopting it early would skip the records still to come.",
/// "$ref": "#/definitions/Version"
/// },
/// "records": {
/// "description": "Matching records in ascending key order in snapshot mode, and ascending version order in change-feed mode — the latter so that a consumer applying them in order reaches the same state as the maintainer. May be empty.",
/// "type": "array",
/// "items": {
/// "$ref": "#/definitions/AppStateRecord"
/// }
/// },
/// "tombstoneRetentionSeconds": {
/// "description": "How long this maintainer retains tombstones before reaping them. Advisory, and present at the maintainer's discretion, so a consumer can schedule its syncs to stay inside the window rather than discovering it has fallen out of it via vta/app-state/list:watermarkTooOld.",
/// "type": "integer",
/// "minimum": 0.0
/// },
/// "truncated": {
/// "description": "True when more matching records exist beyond this page.",
/// "type": "boolean"
/// }
/// },
/// "additionalProperties": false,
/// "$anchor": "response"
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
pub struct Response {
///Opaque continuation token for the next page. Present only when `truncated` is true.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub cursor: ::std::option::Option<::std::string::String>,
///Ecosystem-defined extension members per SPEC.md §4.5.1.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub ext: ::std::option::Option<Ext>,
///The namespace's current counter value. Present whenever `namespace` was supplied. This is what a consumer stores as its next `sinceVersion` — NOT the maximum version among `records`, which is wrong whenever a `prefix` filtered a later change out, and undefined when the page is empty. A paginating consumer MUST NOT advance its stored watermark until it has drained the final page, because the pages of one feed share this value and adopting it early would skip the records still to come.
#[serde(
rename = "highWatermark",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub high_watermark: ::std::option::Option<Version>,
///Matching records in ascending key order in snapshot mode, and ascending version order in change-feed mode — the latter so that a consumer applying them in order reaches the same state as the maintainer. May be empty.
pub records: ::std::vec::Vec<AppStateRecord>,
///How long this maintainer retains tombstones before reaping them. Advisory, and present at the maintainer's discretion, so a consumer can schedule its syncs to stay inside the window rather than discovering it has fallen out of it via vta/app-state/list:watermarkTooOld.
#[serde(
rename = "tombstoneRetentionSeconds",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub tombstone_retention_seconds: ::std::option::Option<u64>,
///True when more matching records exist beyond this page.
pub truncated: bool,
}
///A value of the namespace's monotonic write counter (see this schema's description). Server-assigned; a producer never chooses one.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "Version",
/// "description": "A value of the namespace's monotonic write counter (see this schema's description). Server-assigned; a producer never chooses one.",
/// "type": "integer",
/// "minimum": 1.0
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct Version(pub ::std::num::NonZeroU64);
impl ::std::ops::Deref for Version {
type Target = ::std::num::NonZeroU64;
fn deref(&self) -> &::std::num::NonZeroU64 {
&self.0
}
}
impl ::std::convert::From<Version> for ::std::num::NonZeroU64 {
fn from(value: Version) -> Self {
value.0
}
}
impl ::std::convert::From<::std::num::NonZeroU64> for Version {
fn from(value: ::std::num::NonZeroU64) -> Self {
Self(value)
}
}
impl ::std::str::FromStr for Version {
type Err = <::std::num::NonZeroU64 as ::std::str::FromStr>::Err;
fn from_str(value: &str) -> ::std::result::Result<Self, Self::Err> {
Ok(Self(value.parse()?))
}
}
impl ::std::convert::TryFrom<&str> for Version {
type Error = <::std::num::NonZeroU64 as ::std::str::FromStr>::Err;
fn try_from(value: &str) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::convert::TryFrom<String> for Version {
type Error = <::std::num::NonZeroU64 as ::std::str::FromStr>::Err;
fn try_from(value: String) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::fmt::Display for Version {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
self.0.fmt(f)
}
}
impl crate::Payload for Payload {
const TYPE_URI: &'static str = "https://trusttasks.org/spec/vta/app-state/list/1.0";
const IS_RECIPIENT_REQUIRED: bool = true;
const PAYLOAD_SCHEMA: Option<&'static str> = Some(
"{\n \"$defs\": {\n \"AppStateRecord\": {\n \"additionalProperties\": false,\n \"description\": \"A record as the maintainer holds it. `value` is absent in three distinct situations and a consumer MUST NOT conflate them: the record is a tombstone (`deleted` is true); the caller asked for a metadata-only view (`list` without `includeValues`); or the value genuinely is the JSON literal `null`, in which case `value` is PRESENT and null. This is why `deleted` is required rather than defaulted — a consumer that has to infer deletion from an absent value gets the tombstone case wrong exactly when convergence depends on it.\",\n \"properties\": {\n \"contextId\": {\n \"description\": \"The VTA context the record is scoped to; the isolation boundary.\",\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"description\": \"When the record was first created at this address. MAY be absent on a tombstone whose body has been discarded.\",\n \"format\": \"date-time\",\n \"type\": \"string\"\n },\n \"deleted\": {\n \"description\": \"True when this is a tombstone: the record was deleted, and this entry exists so that a consumer syncing incrementally learns of the deletion. Tombstones are reaped after the maintainer's retention window; see `vta/app-state/list`.\",\n \"type\": \"boolean\"\n },\n \"deletedAt\": {\n \"description\": \"When the record was deleted. Present only when `deleted` is true; equal to `updatedAt` for a tombstone the maintainer has not since rewritten.\",\n \"format\": \"date-time\",\n \"type\": \"string\"\n },\n \"key\": {\n \"$ref\": \"#/$defs/Key\"\n },\n \"namespace\": {\n \"$ref\": \"#/$defs/Namespace\"\n },\n \"updatedAt\": {\n \"description\": \"When the write that produced this `version` was applied. For a tombstone, when the delete was applied.\",\n \"format\": \"date-time\",\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"The stored JSON, in whatever shape the owning application chose. Any JSON value, including `null`. The maintainer neither validates nor interprets it. Absent when this is a tombstone or a metadata-only view — see this definition's description for why that is not the same as a null value.\"\n },\n \"valueBytes\": {\n \"description\": \"Size of the stored value in bytes, measured as the maintainer measures it for the per-record cap (see `vta/app-state/put`). Present in metadata-only views so a consumer can decide what to fetch without fetching it; absent on a tombstone.\",\n \"minimum\": 0,\n \"type\": \"integer\"\n },\n \"version\": {\n \"$ref\": \"#/$defs/Version\",\n \"description\": \"The namespace counter value this record's most recent write took. Supply it as `expectedVersion` on the next write to make that write conditional on nothing having changed in between.\"\n }\n },\n \"required\": [\n \"contextId\",\n \"namespace\",\n \"key\",\n \"version\",\n \"deleted\",\n \"updatedAt\"\n ],\n \"title\": \"AppStateRecord\",\n \"type\": \"object\"\n },\n \"Ext\": {\n \"additionalProperties\": true,\n \"description\": \"Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.\",\n \"minProperties\": 1,\n \"propertyNames\": {\n \"pattern\": \"^[a-z][a-z0-9-]*(\\\\.[a-z0-9-]+)+$\"\n },\n \"title\": \"Ext\",\n \"type\": \"object\"\n },\n \"Key\": {\n \"description\": \"Application-chosen identifier for a record within a namespace. Opaque to the maintainer: it MUST NOT be parsed, normalized, or case-folded, and prefix matching in `list` is a byte-prefix comparison over the UTF-8 encoding. Applications SHOULD use `/`-delimited hierarchical keys (`community/acme`, `contact/z6Mk…`) so that `prefix` can address a record family, but the delimiter is a convention between an application and itself — the maintainer attaches no meaning to it.\",\n \"maxLength\": 512,\n \"minLength\": 1,\n \"pattern\": \"^[^\\\\u0000]+$\",\n \"title\": \"Key\",\n \"type\": \"string\"\n },\n \"Namespace\": {\n \"description\": \"Scopes one application's records within a context, so several tools can share a context without colliding — `openvtc`, `cnm`, an agent runtime. The maintainer MUST NOT interpret the value; it is an opaque partition name. Namespaces are first-come and unreserved, so an application SHOULD pick a stable, specific one: a future per-namespace ACL would grant on this exact string, which makes renaming a namespace a migration rather than an edit.\",\n \"maxLength\": 64,\n \"minLength\": 1,\n \"pattern\": \"^[a-z][a-z0-9]*(-[a-z0-9]+)*$\",\n \"title\": \"Namespace\",\n \"type\": \"string\"\n },\n \"Response\": {\n \"$anchor\": \"response\",\n \"additionalProperties\": false,\n \"description\": \"Success response to vta/app-state/list. Type https://trusttasks.org/spec/vta/app-state/list/1.0#response.\",\n \"properties\": {\n \"cursor\": {\n \"description\": \"Opaque continuation token for the next page. Present only when `truncated` is true.\",\n \"type\": \"string\"\n },\n \"ext\": {\n \"$ref\": \"#/$defs/Ext\",\n \"description\": \"Ecosystem-defined extension members per SPEC.md §4.5.1.\"\n },\n \"highWatermark\": {\n \"$ref\": \"#/$defs/Version\",\n \"description\": \"The namespace's current counter value. Present whenever `namespace` was supplied. This is what a consumer stores as its next `sinceVersion` — NOT the maximum version among `records`, which is wrong whenever a `prefix` filtered a later change out, and undefined when the page is empty. A paginating consumer MUST NOT advance its stored watermark until it has drained the final page, because the pages of one feed share this value and adopting it early would skip the records still to come.\"\n },\n \"records\": {\n \"description\": \"Matching records in ascending key order in snapshot mode, and ascending version order in change-feed mode — the latter so that a consumer applying them in order reaches the same state as the maintainer. May be empty.\",\n \"items\": {\n \"$ref\": \"#/$defs/AppStateRecord\"\n },\n \"type\": \"array\"\n },\n \"tombstoneRetentionSeconds\": {\n \"description\": \"How long this maintainer retains tombstones before reaping them. Advisory, and present at the maintainer's discretion, so a consumer can schedule its syncs to stay inside the window rather than discovering it has fallen out of it via vta/app-state/list:watermarkTooOld.\",\n \"minimum\": 0,\n \"type\": \"integer\"\n },\n \"truncated\": {\n \"description\": \"True when more matching records exist beyond this page.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"records\",\n \"truncated\"\n ],\n \"title\": \"VTA Application State List — response payload\",\n \"type\": \"object\"\n },\n \"Version\": {\n \"description\": \"A value of the namespace's monotonic write counter (see this schema's description). Server-assigned; a producer never chooses one.\",\n \"minimum\": 1,\n \"title\": \"Version\",\n \"type\": \"integer\"\n }\n },\n \"$id\": \"https://trusttasks.org/spec/vta/app-state/list/1.0\",\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"additionalProperties\": false,\n \"description\": \"Enumerate application-state records in a context. Two modes, distinguished by whether `sinceVersion` is supplied. Without it this is a SNAPSHOT of live records, optionally narrowed by `prefix`. With it this is a CHANGE FEED: every record in the namespace whose version exceeds the watermark, tombstones included, which is what lets an incremental consumer converge. Pagination is opaque-cursor based.\",\n \"properties\": {\n \"contextId\": {\n \"description\": \"The VTA context to enumerate; the isolation boundary.\",\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"cursor\": {\n \"description\": \"Opaque continuation token from a previous response. Consumers MUST treat it as opaque: never construct, decode, mutate, or infer meaning from one.\",\n \"type\": \"string\"\n },\n \"ext\": {\n \"$ref\": \"#/$defs/Ext\",\n \"description\": \"Ecosystem-defined extension members per SPEC.md §4.5.1.\"\n },\n \"includeDeleted\": {\n \"description\": \"Snapshot mode only: when true, tombstones still inside the retention window are returned alongside live records. Defaults to false. In change-feed mode tombstones are always returned and this member MUST NOT be set to false — a change feed that omits deletions cannot converge, so asking for one is a contradiction rather than a preference.\",\n \"type\": \"boolean\"\n },\n \"includeValues\": {\n \"description\": \"When true, each returned record carries its `value`. Defaults to false, which returns the metadata view — address, version, timestamps, `valueBytes` — so a prefix scan is cheap. Setting it makes a scan one round trip rather than a scan plus N gets, at the cost of the response carrying every value.\",\n \"type\": \"boolean\"\n },\n \"namespace\": {\n \"$ref\": \"#/$defs/Namespace\",\n \"description\": \"Restrict to one namespace. Optional in snapshot mode, where omitting it enumerates every namespace the caller can read in the context. REQUIRED in change-feed mode, because the version counter `sinceVersion` is compared against is maintained per (contextId, namespace) and a watermark spanning namespaces would name no single point in time.\"\n },\n \"pageSize\": {\n \"description\": \"Caller's upper bound on records per page. The maintainer applies its own ceiling and MAY return fewer — notably when `includeValues` is set and the values are large.\",\n \"maximum\": 1000,\n \"minimum\": 1,\n \"type\": \"integer\"\n },\n \"prefix\": {\n \"description\": \"Restrict to records whose `key` begins with this byte prefix, compared over the UTF-8 encoding. Lets a consumer read one record family — `community/`, `contact/` — without dragging every record in the namespace through the response.\",\n \"maxLength\": 512,\n \"type\": \"string\"\n },\n \"sinceVersion\": {\n \"description\": \"Watermark. Selects change-feed mode: only records whose `version` is strictly greater are returned, tombstones included. Supply the `highWatermark` from the previous sync, or 0 for a first full pull in change-feed form. Requires `namespace`.\",\n \"minimum\": 0,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"contextId\"\n ],\n \"title\": \"VTA Application State List — payload\",\n \"type\": \"object\"\n}\n",
);
}
impl crate::Payload for Response {
const TYPE_URI: &'static str = "https://trusttasks.org/spec/vta/app-state/list/1.0#response";
const IS_RECIPIENT_REQUIRED: bool = true;
const PAYLOAD_SCHEMA: Option<&'static str> = Some(
"{\n \"$defs\": {\n \"AppStateRecord\": {\n \"additionalProperties\": false,\n \"description\": \"A record as the maintainer holds it. `value` is absent in three distinct situations and a consumer MUST NOT conflate them: the record is a tombstone (`deleted` is true); the caller asked for a metadata-only view (`list` without `includeValues`); or the value genuinely is the JSON literal `null`, in which case `value` is PRESENT and null. This is why `deleted` is required rather than defaulted — a consumer that has to infer deletion from an absent value gets the tombstone case wrong exactly when convergence depends on it.\",\n \"properties\": {\n \"contextId\": {\n \"description\": \"The VTA context the record is scoped to; the isolation boundary.\",\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"description\": \"When the record was first created at this address. MAY be absent on a tombstone whose body has been discarded.\",\n \"format\": \"date-time\",\n \"type\": \"string\"\n },\n \"deleted\": {\n \"description\": \"True when this is a tombstone: the record was deleted, and this entry exists so that a consumer syncing incrementally learns of the deletion. Tombstones are reaped after the maintainer's retention window; see `vta/app-state/list`.\",\n \"type\": \"boolean\"\n },\n \"deletedAt\": {\n \"description\": \"When the record was deleted. Present only when `deleted` is true; equal to `updatedAt` for a tombstone the maintainer has not since rewritten.\",\n \"format\": \"date-time\",\n \"type\": \"string\"\n },\n \"key\": {\n \"$ref\": \"#/$defs/Key\"\n },\n \"namespace\": {\n \"$ref\": \"#/$defs/Namespace\"\n },\n \"updatedAt\": {\n \"description\": \"When the write that produced this `version` was applied. For a tombstone, when the delete was applied.\",\n \"format\": \"date-time\",\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"The stored JSON, in whatever shape the owning application chose. Any JSON value, including `null`. The maintainer neither validates nor interprets it. Absent when this is a tombstone or a metadata-only view — see this definition's description for why that is not the same as a null value.\"\n },\n \"valueBytes\": {\n \"description\": \"Size of the stored value in bytes, measured as the maintainer measures it for the per-record cap (see `vta/app-state/put`). Present in metadata-only views so a consumer can decide what to fetch without fetching it; absent on a tombstone.\",\n \"minimum\": 0,\n \"type\": \"integer\"\n },\n \"version\": {\n \"$ref\": \"#/$defs/Version\",\n \"description\": \"The namespace counter value this record's most recent write took. Supply it as `expectedVersion` on the next write to make that write conditional on nothing having changed in between.\"\n }\n },\n \"required\": [\n \"contextId\",\n \"namespace\",\n \"key\",\n \"version\",\n \"deleted\",\n \"updatedAt\"\n ],\n \"title\": \"AppStateRecord\",\n \"type\": \"object\"\n },\n \"Ext\": {\n \"additionalProperties\": true,\n \"description\": \"Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.\",\n \"minProperties\": 1,\n \"propertyNames\": {\n \"pattern\": \"^[a-z][a-z0-9-]*(\\\\.[a-z0-9-]+)+$\"\n },\n \"title\": \"Ext\",\n \"type\": \"object\"\n },\n \"Key\": {\n \"description\": \"Application-chosen identifier for a record within a namespace. Opaque to the maintainer: it MUST NOT be parsed, normalized, or case-folded, and prefix matching in `list` is a byte-prefix comparison over the UTF-8 encoding. Applications SHOULD use `/`-delimited hierarchical keys (`community/acme`, `contact/z6Mk…`) so that `prefix` can address a record family, but the delimiter is a convention between an application and itself — the maintainer attaches no meaning to it.\",\n \"maxLength\": 512,\n \"minLength\": 1,\n \"pattern\": \"^[^\\\\u0000]+$\",\n \"title\": \"Key\",\n \"type\": \"string\"\n },\n \"Namespace\": {\n \"description\": \"Scopes one application's records within a context, so several tools can share a context without colliding — `openvtc`, `cnm`, an agent runtime. The maintainer MUST NOT interpret the value; it is an opaque partition name. Namespaces are first-come and unreserved, so an application SHOULD pick a stable, specific one: a future per-namespace ACL would grant on this exact string, which makes renaming a namespace a migration rather than an edit.\",\n \"maxLength\": 64,\n \"minLength\": 1,\n \"pattern\": \"^[a-z][a-z0-9]*(-[a-z0-9]+)*$\",\n \"title\": \"Namespace\",\n \"type\": \"string\"\n },\n \"Response\": {\n \"$anchor\": \"response\",\n \"additionalProperties\": false,\n \"description\": \"Success response to vta/app-state/list. Type https://trusttasks.org/spec/vta/app-state/list/1.0#response.\",\n \"properties\": {\n \"cursor\": {\n \"description\": \"Opaque continuation token for the next page. Present only when `truncated` is true.\",\n \"type\": \"string\"\n },\n \"ext\": {\n \"$ref\": \"#/$defs/Ext\",\n \"description\": \"Ecosystem-defined extension members per SPEC.md §4.5.1.\"\n },\n \"highWatermark\": {\n \"$ref\": \"#/$defs/Version\",\n \"description\": \"The namespace's current counter value. Present whenever `namespace` was supplied. This is what a consumer stores as its next `sinceVersion` — NOT the maximum version among `records`, which is wrong whenever a `prefix` filtered a later change out, and undefined when the page is empty. A paginating consumer MUST NOT advance its stored watermark until it has drained the final page, because the pages of one feed share this value and adopting it early would skip the records still to come.\"\n },\n \"records\": {\n \"description\": \"Matching records in ascending key order in snapshot mode, and ascending version order in change-feed mode — the latter so that a consumer applying them in order reaches the same state as the maintainer. May be empty.\",\n \"items\": {\n \"$ref\": \"#/$defs/AppStateRecord\"\n },\n \"type\": \"array\"\n },\n \"tombstoneRetentionSeconds\": {\n \"description\": \"How long this maintainer retains tombstones before reaping them. Advisory, and present at the maintainer's discretion, so a consumer can schedule its syncs to stay inside the window rather than discovering it has fallen out of it via vta/app-state/list:watermarkTooOld.\",\n \"minimum\": 0,\n \"type\": \"integer\"\n },\n \"truncated\": {\n \"description\": \"True when more matching records exist beyond this page.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"records\",\n \"truncated\"\n ],\n \"title\": \"VTA Application State List — response payload\",\n \"type\": \"object\"\n },\n \"Version\": {\n \"description\": \"A value of the namespace's monotonic write counter (see this schema's description). Server-assigned; a producer never chooses one.\",\n \"minimum\": 1,\n \"title\": \"Version\",\n \"type\": \"integer\"\n }\n },\n \"$ref\": \"#/$defs/Response\",\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\"\n}\n",
);
}
#[cfg(test)]
mod conformance {
//! Round-trip tests harvested from the spec's `spec.md`,
//! plus a `rejects_invalid_examples` test for any fixtures
//! in `payload.invalid-examples.json` (validate feature).
#[test]
fn request_example_1() {
const JSON: &str = "{\n \"id\": \"1f3a5c70-8b92-4d14-a6e8-0c2d4f6a8b91\",\n \"type\": \"https://trusttasks.org/spec/vta/app-state/list/1.0\",\n \"issuer\": \"did:key:z6MkOpenVtcClient\",\n \"recipient\": \"did:web:vta.example\",\n \"issuedAt\": \"2026-08-22T11:00:00Z\",\n \"payload\": {\n \"contextId\": \"personal\",\n \"namespace\": \"openvtc\",\n \"prefix\": \"community/\",\n \"pageSize\": 100\n }\n}\n";
let doc: crate::TrustTask<super::Payload> =
serde_json::from_str(JSON).expect("deserialize request example");
let rendered = serde_json::to_value(&doc).expect("re-serialize");
let expected: serde_json::Value = serde_json::from_str(JSON).expect("re-parse expected");
assert_eq!(rendered, expected, "request example failed round-trip");
}
#[test]
fn request_example_2() {
const JSON: &str = "{\n \"id\": \"2a4b6d81-9ca3-4e25-b7f9-1d3e5a7b9c02\",\n \"type\": \"https://trusttasks.org/spec/vta/app-state/list/1.0\",\n \"issuer\": \"did:key:z6MkOpenVtcClient\",\n \"recipient\": \"did:web:vta.example\",\n \"issuedAt\": \"2026-08-22T11:00:10Z\",\n \"payload\": {\n \"contextId\": \"personal\",\n \"namespace\": \"openvtc\",\n \"prefix\": \"contact/\",\n \"includeValues\": true,\n \"pageSize\": 50\n }\n}\n";
let doc: crate::TrustTask<super::Payload> =
serde_json::from_str(JSON).expect("deserialize request example");
let rendered = serde_json::to_value(&doc).expect("re-serialize");
let expected: serde_json::Value = serde_json::from_str(JSON).expect("re-parse expected");
assert_eq!(rendered, expected, "request example failed round-trip");
}
#[test]
fn request_example_3() {
const JSON: &str = "{\n \"id\": \"3b5c7e92-0db4-4f36-c80a-2e4f6b8c0d13\",\n \"type\": \"https://trusttasks.org/spec/vta/app-state/list/1.0\",\n \"issuer\": \"did:key:z6MkOpenVtcClient\",\n \"recipient\": \"did:web:vta.example\",\n \"issuedAt\": \"2026-08-22T11:05:00Z\",\n \"payload\": {\n \"contextId\": \"personal\",\n \"namespace\": \"openvtc\",\n \"sinceVersion\": 40,\n \"includeValues\": true\n }\n}\n";
let doc: crate::TrustTask<super::Payload> =
serde_json::from_str(JSON).expect("deserialize request example");
let rendered = serde_json::to_value(&doc).expect("re-serialize");
let expected: serde_json::Value = serde_json::from_str(JSON).expect("re-parse expected");
assert_eq!(rendered, expected, "request example failed round-trip");
}
#[test]
fn response_example_1() {
const JSON: &str = "{\n \"id\": \"4c6d8fa3-1ec5-4047-d91b-3f507c9d1e24\",\n \"type\": \"https://trusttasks.org/spec/vta/app-state/list/1.0#response\",\n \"issuer\": \"did:web:vta.example\",\n \"recipient\": \"did:key:z6MkOpenVtcClient\",\n \"issuedAt\": \"2026-08-22T11:00:01Z\",\n \"threadId\": \"1f3a5c70-8b92-4d14-a6e8-0c2d4f6a8b91\",\n \"payload\": {\n \"records\": [\n {\n \"contextId\": \"personal\",\n \"namespace\": \"openvtc\",\n \"key\": \"community/acme\",\n \"version\": 52,\n \"deleted\": false,\n \"valueBytes\": 95,\n \"createdAt\": \"2026-07-02T14:10:00Z\",\n \"updatedAt\": \"2026-08-22T10:01:01Z\"\n },\n {\n \"contextId\": \"personal\",\n \"namespace\": \"openvtc\",\n \"key\": \"community/borealis\",\n \"version\": 31,\n \"deleted\": false,\n \"valueBytes\": 88,\n \"createdAt\": \"2026-05-19T07:20:00Z\",\n \"updatedAt\": \"2026-08-01T09:14:00Z\"\n }\n ],\n \"truncated\": false,\n \"highWatermark\": 52,\n \"tombstoneRetentionSeconds\": 2592000\n }\n}\n";
let doc: crate::TrustTask<super::Response> =
serde_json::from_str(JSON).expect("deserialize response example");
let rendered = serde_json::to_value(&doc).expect("re-serialize");
let expected: serde_json::Value = serde_json::from_str(JSON).expect("re-parse expected");
assert_eq!(rendered, expected, "response example failed round-trip");
}
#[test]
fn response_example_2() {
const JSON: &str = "{\n \"id\": \"5d7e90b4-2fd6-4158-ea2c-406182ae2f35\",\n \"type\": \"https://trusttasks.org/spec/vta/app-state/list/1.0#response\",\n \"issuer\": \"did:web:vta.example\",\n \"recipient\": \"did:key:z6MkOpenVtcClient\",\n \"issuedAt\": \"2026-08-22T11:05:01Z\",\n \"threadId\": \"3b5c7e92-0db4-4f36-c80a-2e4f6b8c0d13\",\n \"payload\": {\n \"records\": [\n {\n \"contextId\": \"personal\",\n \"namespace\": \"openvtc\",\n \"key\": \"community/defunct\",\n \"version\": 44,\n \"deleted\": true,\n \"createdAt\": \"2026-06-11T08:00:00Z\",\n \"updatedAt\": \"2026-08-18T16:05:00Z\",\n \"deletedAt\": \"2026-08-18T16:05:00Z\"\n },\n {\n \"contextId\": \"personal\",\n \"namespace\": \"openvtc\",\n \"key\": \"community/acme\",\n \"version\": 52,\n \"deleted\": false,\n \"value\": {\n \"label\": \"Acme Engineering\",\n \"joinedAt\": \"2026-07-02T14:10:00Z\",\n \"role\": \"admin\"\n },\n \"valueBytes\": 95,\n \"createdAt\": \"2026-07-02T14:10:00Z\",\n \"updatedAt\": \"2026-08-22T10:01:01Z\"\n }\n ],\n \"truncated\": false,\n \"highWatermark\": 52,\n \"tombstoneRetentionSeconds\": 2592000\n }\n}\n";
let doc: crate::TrustTask<super::Response> =
serde_json::from_str(JSON).expect("deserialize response example");
let rendered = serde_json::to_value(&doc).expect("re-serialize");
let expected: serde_json::Value = serde_json::from_str(JSON).expect("re-parse expected");
assert_eq!(rendered, expected, "response example failed round-trip");
}
}