# Normalized objects and versioned collections The proposed collection architecture for AgentCore workloads: exact identities, ordered membership and bounded Views, with the existing History contract kept intact. Status: Planned · not available. Prelaunch; not a live service guarantee. Architecture direction, not a public generalized collection SDK. Existing allIds()/byIds() remain UTC-day History operations; the unpublished State Selection candidate is restricted to one Active State evidence-reference collection. No managed/customer-owned S3 snapshot service is qualified. Reviewed: 2026-10-14. Backend source: e16b81b4a637acec91f3aed8a71cf5b0f42f0c19. Native toolkit: merged in PR #176, reviewed at e16b81b4a637acec91f3aed8a71cf5b0f42f0c19. HTML: /docs/normalized-state ## In short Plan how an AgentCore workload could share exact objects through scoped, versioned collections. The proposed generalization builds on History's identities and pinned membership. It does not turn today's History methods into a public general collection API. **Available today:** General collections remain proposed. allIds() and byIds() keep their UTC-day History contract; scoped State and Components have their own bounded source APIs. > Plan shared State for AgentCore tasks using exact identities and fixed, versioned collections. General collections remain proposed. ## Existing contract and proposed direction - **Start with History** — Use exact revisions and fixed UTC-day membership for an AgentCore workload. - **Add scoped State** — State and Components use declared, bounded evidence references. - **Keep the proposal separate** — General collection adapters and managed integration remain future work. ## One Rust State engine; many typed collections The foundational distinction is identity versus membership. Exact identity answers which retained object revision is requested. Collection membership answers which exact references belong to a particular ordered, pinned generation. A consumer can enumerate references and hydrate only selected records. The existing History adapter scopes records by tenant, subject, and type, and pins UTC-day collection membership to a generation. This date-based History contract does not require every proposed collection to be date-based. General collection adapters, including project builds, documents, and tasks, are architectural direction only. Knowledge is information represented as typed State, with provenance and review status where applicable. Context is a consumer-specific View selecting authorized references. Neither needs a second State engine. 1. **Exact object** — Stable identity plus exact revision and declared availability. A stored build record is not proof that the artifact is safe to reuse. 2. **Versioned membership** — An ordered collection of exact references with a pinned generation. Membership can change without duplicating objects. 3. **Materialized View** — A derived result with exact source/definition references, applicability, and its own publication boundary. 4. **Consumer Context View** — A task-scoped selection of eligible State/evidence references; permission is rechecked when serving. ## What the current History API actually guarantees allIds() pages one bounded UTC-day generation. Generation-bound byIds() verifies exact membership; direct byIds() resolves known exact revisions without a membership claim. Missing, unresolved and expired evidence stays explicit; neither API silently follows the latest revision. The existing Rust State engine already supports versioned Views, dependency membership, change detection and bounded reconciliation. The generalized collection contract described here must reuse those mechanisms rather than create parallel reducers or dirty-propagation loops. [Existing History API and exact references](/docs/history) [State queries and supported operators](/docs/state-api) [Engineering contract](/docs/engineering-review) ## Adapter boundaries, not a different engine per vertical 1. **History adapter — implemented scope** — UTC-day ordered outcomes, specific revisions, retention and correction rules. 2. **Project collection — proposed** — Enumerate exact build, test, and task references by project instead of date; no build-specific inference or compiler required. 3. **Temporal collection — proposed** — Use explicit time and versioned rules as View inputs, so durable source facts may drive new bounded projections without being rewritten each year. 4. **Context collection — proposed** — Select exact evidence references for one consumer and budget; representation is separate from the original payload. > **Dependency injection boundary** > Adapters supply scoped access, membership policies, storage ports, and lifecycle configuration. Rust remains the semantic authority for supported deterministic validation and publication. ## Keep the existing dependency DAG A changed source makes its affected dependent Views dirty. The existing reconciliation lifecycle evaluates bounded affected work and conditionally publishes. Within one traversal, a visited set avoids duplicate work. For supported Views, unchanged results can be reused when the required version, freshness, and authority checks still hold. General calculation caching remains planned. A future nested collection may reference exact child generations, but the parent must pin each child version; old parents must not silently retrieve newer children. Traversal requires total depth, node, edge, byte, and read limits. A trie or Merkle DAG is an optional measured indexing optimization, not a prerequisite. ## Hot State and durable snapshots have different jobs The target storage architecture uses DynamoDB for operational pointers, indexed membership and durable work. Immutable evidence and snapshots may live in an approved S3 store. Kam-managed and customer-owned S3 are proposed storage-ownership modes, not existing product offerings. Retention, snapshot interval, application validity and hot working-set policy are distinct. Customers might select multi-year retention while only occasionally changing State. The current 365-UTC-date working History window is a real existing contract; generalizing future lifecycles must preserve it until separately migrated and qualified. Snapshot publication must verify the exact durable object before advancing a conditional hot-State pointer. DynamoDB and S3 do not share a transaction. An absent or inaccessible archived object must not silently resolve to latest. [Existing retention guarantees](/docs/retention) [Qualification status](/reliability) ## Illustrative: three agents share one build record Agent A submits a build result under a stable application-supplied ID. Agents B and C can retrieve the same authorized record or see it in different project collections without copying its payload. A new build gets a distinct exact identity or revision according to the declared producer contract. Reusing the compiled artifact still depends on an external build cache and its compatibility checks. Kam does not compile Rust, certify arbitrary toolchains, infer build equivalence, or grant access because an agent knows an ID. ## Implementation boundary and next experiment This document describes the intended generalization of existing primitives, not a shipped universal byIds/allIds service. Start by preserving the existing History adapter and qualifying one non-date, bounded collection through the real Rust engine, authorized reads, conditional publication, and recovery. Only after that source-backed happy path should the website describe generic collections, customer-owned S3, generalized durable Context collections or managed multiagent artifact reuse as available.