Entities and access patterns

See schema for exact keys. The public JSON contract is in Monitoring API.

Token

Two transactional rows store token identity, scopes, creation/revocation time and SHA-256 hash. The KEY# lookup authenticates requests. The owner metadata row also holds the encrypted recovery envelope (version, key ID, nonce, ciphertext and tag); the lookup only records its recovery key ID. Plaintext is generated randomly and never persisted. Public metadata explicitly excludes hash, owner ID and encryption fields; canReveal indicates whether an active token has a saved copy.

Authenticated use upgrades older hash-only records, or records from another encryption key, through a conditional two-row transaction. Authentication itself does not require decryption. Revocation removes the encrypted copy and invalidates access. Deletion physically removes both rows in one transaction; concurrent recovery cannot resurrect them. Token deletion does not modify source or history rows.

Latest source

One row per owner/source contains the validated observation plus createdAt and receivedAt. observedAt belongs to the sender; receivedAt belongs to the server. Agent kind and provider/account identity remain fixed. A configured resource can change its collector preset without becoming an agent.

Custom resources also store resourceType, metricDefinitions, metricOrder, and optional statusMessage. Owner edits live in a separate configuration object on the same row, with an independent configuration revision. Conditional writes preserve observations during edits and preserve configuration during ingestion. Editing does not change receipt time or create a minute sample. Read-time projection applies the configured order and hides measurements whose key/unit does not match.

A primary-key lookup reads one source. An owner partition query with prefix SOURCE# lists sources; selected-ID and account filters restrict the result. stale is derived from age and is not persisted.

Minute summary

One row per source/minute records sample count, metric-specific valid counts, means, maxima, and expiration. Null measurements do not increase a metric's count. Accepted non-heartbeat observations update the summary and latest source in the same transaction. Duplicates, reversed observations, and heartbeats do not add samples.

Custom-resource minutes also retain their resource type and definitions. Read-time projection returns only metrics compatible with the current definition. Deleting a latest source leaves minute rows until expiry; reusing its ID cannot reinterpret incompatible retained data.

A sort-key range query loads retained minutes. Account trends and legacy hour/day/week activity are computed from these rows at read time; they do not create extra stored series.

Agent memory

The legacy memory API stores string values under owner, normalized project, and key. PUT preserves createdAt and replaces updatedAt. Values are limited to 10,000 characters and the JSON request to 16 KiB. Memory has no TTL and is separate from agent context utilization.

The legacy adapter's internal token field carries a non-secret owner ID, not a Bearer credential. Responses include only project, key, value, and timestamps.

Request budget

Atomic conditional increments enforce owner-wide read, write, and token-creation limits across server instances. Rows include the request count and a two-minute TTL; an old budget is never reused for a later minute.

Owner statistics

The statistics endpoint counts the owner's stored token metadata and agent-source rows at read time. Counts include revoked entries but exclude deleted ones. Statistics require a read token and do not expose other owners' totals. No global counter row participates in source or token writes.