State API, metrics, and watch

Describe the State you want

Each step narrows or reshapes a collection. The chain is a declaration, not a loop: Kam turns it into a plan with explicit limits, keeps the result materialized, and recomputes it only when an input it reads changes.

Naming in the preview follows one concept: source collections are plural nouns (customers, subscriptions); derived views and metrics are camelCase descriptions of what they hold (atRiskCustomers, businessHealth).

// DESIGN PREVIEW · proposed API shape · not available in any SDK
const atRiskCustomers = kam
  .state('customers')
  .where(lt('health', 0.6))
  .pick(['id', 'mrr', 'health', 'renewalDate'])
  .orderBy('mrr', 'desc')
  .take(100)
  .materialize('atRiskCustomers');

// Run your agent only when this view changes.
atRiskCustomers.watch(change => startCustomerSuccessAgent(change));

// Ask how Kam will execute it before it runs.
atRiskCustomers.explain();

A small set of composable operators

1. 1

   Select: where, pick, orderBy, take

   Filter, project, and bound a collection before anything is read in full.

2. 2

   Combine: group, union, diff, expand, hydrate

   Relate collections and resolve references to exact revisions.

3. 3

   Aggregate: count, sum, mean, reduce

   Derive metrics that update incrementally as inputs change.

4. 4

   Operate: materialize, watch, explain

   Keep the result current, react to changes, and inspect the plan.

Metrics recompute on change, not on every read

In the synthetic example, one subscription is upgraded. Kam recomputes mrr, arr, businessHealth because each reads the changed input. churnRate, dailyActiveUsers, p99Latency, supportSla read other inputs, so their existing values are reused.

The executive agent watching businessHealth wakes. Agents watching the other four metrics stay asleep.

Synthetic example of the planned metrics model. Counts are derived nodes in this diagram (3 of 7 recomputed), not a measured benchmark.

Run AI when relevant State changes

watch() is the planned way to start work: subscribe to a materialized view and receive the change, including the exact revisions that caused it. Your code decides what to do, such as invoking an AgentCore agent. A timer that wakes every agent to re-read the world becomes unnecessary for that view.

Customer realtime subscriptions are not implemented. The current internal event path is bounded and maintenance-redrivable, and it is not a public subscription API.

See the work envelope before execution

explain() is planned to return the plan and its bounds: which index is used, how many reads and items it may touch, and what changes trigger recomputation. A plan that would scan or traverse without a bound is rejected instead of being run slowly.

plan atRiskCustomers            (illustrative output)
  source            customers · index on health
  index reads       2
  max items         100
  max bytes         64 KB
  max graph depth   2
  full scans        none · rejected by the work envelope
  recompute when    customers.health or customers.mrr changes

Security and latency share one mechanism

Every planned query carries a work envelope: maxReads, maxItems, maxBytes, maxDepth, maxFanout, maxRetries, deadline. The same limits that stop a runaway query also stop a tenant from reading more than it should and keep tail latency bounded by design.

Boundedness is architectural. A measured production p99 is qualification evidence that has not been published.

1. 1

   Cross-tenant access · Implemented in source

   The server resolves the authorized tenant; a caller-supplied tenant ID is not authorization.

2. 2

   Silent mutation · Implemented in source

   Revisions are immutable. Corrections add a revision and keep the earlier one inspectable.

3. 3

   Model output becoming truth · Implemented in source

   Only your application declares results. No model, reducer, or AgentCore call fills a missing record.

4. 4

   Oversized reads · Implemented in source

   History pages and View membership sets have explicit limits and cursors.

5. 5

   Unbounded traversal · Internal implementation

   View dependency membership is bounded and cycles are rejected at registration.

6. 6

   Stale or duplicate work · Internal implementation

   Commit-time fences reject work whose lifecycle, membership, or source version has moved.

7. 7

   Per-query cost explosions · Planned · not available

   A declared envelope (maxReads, maxItems, maxBytes, maxDepth, maxFanout, deadline) checked before execution.

8. 8

   Acting on stale State · Planned · not available

   Revalidate the exact State a decision read before a consequential external action.

Not another database

Keep Postgres, DynamoDB, Stripe, S3, and your warehouse. Kam holds the smaller set of State your agents reuse across turns and across agents, with the exact versions behind it.

Store the State worth reusing, not every byte worth keeping.

What to use today

Evaluate the implemented History contract with the candidate SDK, and discuss one bounded View with the team. The State API design is shaped by those evaluations.