# What Kam stores, writes, reads, and proves

For engineers evaluating Kam: the storage model, write and read paths, consistency and concurrency boundaries, recovery, retention, responsibility split, and what remains unqualified.

Status: Implemented in source. Prelaunch; not a live service guarantee.
Describes the History contract implemented in source. Nothing here is live-qualified, and no deployment is offered from this page.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/engineering-review

## In short

The questions an architecture review asks, answered with the guarantee and its limit together: what Kam stores, how a write commits, what each read proves, where consistency stops, how recovery and retention work, and what is still unqualified.

**Available today:** Describes the History contract implemented in source. Nothing is live-qualified.

> Answer the design-review questions with the guarantee and its limit side by side.

## What is stored

1. **Outcome revisions** — Immutable (id, revision) records your application declares: subject, type, occurrence time, success or failure, category, and source references. Kam does not store your system of record, model prompts, or agent transcripts.

2. **Day membership** — Ordered references naming which exact revisions belong to one scope and UTC day, published as generations.

3. **Durable work records** — Work owed to the projection worker, committed with each accepted revision (a transactional outbox).

4. **Checkpoints and projections** — Saved fold state and applied sequence, plus the trajectory comparisons derived from them.

5. **Delivery obligations and receipts** — Only when optional AgentCore delivery is enabled (default off): one obligation per eligible generation, with separate publication and verification receipts.

[Glossary: outcome revision](/docs/concepts#outcome-revision)

## The write path

1. **1. Authenticate and authorize** — API Gateway verifies the Cognito access token; the handler re-checks issuer, client and scope, takes the principal from sub, and authorizes the requested tenant. A tenant ID in the request is not permission.

2. **2. Admit** — Rust validates identity, revision, occurrence time against the working window, and budgets. A correction must be exactly the next revision and cannot move the occurrence time.

3. **3. Commit atomically** — One DynamoDB TransactWriteItems call commits the revision, its day membership, and the work record, guarded by version conditions. Identical resubmission returns duplicate with the original acceptedSequence; a different payload for the same revision is rejected.

4. **4. Wake and fold** — A best-effort wakeup starts the worker. If it fails, the committed work record is redriven. The worker folds accepted revisions in sequence order.

5. **5. Publish** — A separate transaction commits the checkpoint, the new generation, and any eligible delivery obligation. Acceptance and publication are two transactions, not one.

[Glossary: acceptance transaction](/docs/concepts#acceptance-transaction)

[Glossary: transactional outbox](/docs/concepts#outbox)

## The read path, and what each read proves

1. **trajectory()** — Proves the projection as of appliedSequence, alongside acceptedSequence. If they differ, accepted work is not yet folded.

2. **allIds()** — Proves membership: these exact revision references belong to this generation, through acceptedThroughSequence. It does not assert that every real-world event was reported (externalCompleteness: not_asserted).

3. **byIds() in generation mode** — Proves each named revision is retained and matches its content hash, in caller order, and that it belongs to the generation. Missing, expired and unresolved positions stay explicit.

4. **byIds() in direct mode** — Proves a known (id, revision) is retained. It makes no membership claim and never falls back to the latest revision.

5. **What no read proves** — That an agent consumed the record, that the external fact is true, or who authored it. A content hash is integrity, not a signature.

## Where consistency and concurrency apply

Ordering is per scope: each tenant, subject and type has its own contiguous acceptedSequence and no global commit counter. Concurrent writers use optimistic concurrency; a stale version is rejected, not merged.

Each storage read is strongly consistent. A read that spans pages is made consistent by pinning a generation and passing its cursor back with it; if the service would have to switch generations, the read fails instead.

Kam makes no linearizability, serializability, or cross-scope isolation claim, and projections are asynchronous relative to acceptance.

[Glossary: conditional write](/docs/concepts#conditional-write)

[Glossary: generation](/docs/concepts#generation)

[Glossary: strongly consistent read](/docs/concepts#consistent-read)

## How recovery works

Work is persisted before anything relies on a wakeup, so a lost message delays processing instead of losing it. Processing is at-least-once and idempotent; Kam does not claim exactly-once execution.

Ambiguous external responses stay UNKNOWN until reconciled, and lifecycle epochs stop old jobs from acting with new authority. Owner export, export-bound deletion and a restore fence are implemented in source; live restore and erasure drills are not qualified. There is no arbitrary point-in-time recovery.

[Recovery and authority](/docs/reliability)

## Retention and deletion

New outcomes are admitted for today plus the previous 364 UTC dates. Retained evidence carries its own deadline of up to 730 days. Reads report a revision past its deadline as expired immediately; DynamoDB TTL removes the item later, typically within a few days, so expiry is not proof of physical deletion.

[Glossary: logical expiry](/docs/concepts#logical-expiry)

[Retention guide](/docs/retention)

## Who is responsible for what

1. **Your application** — Business meaning of success and failure, stable IDs, idempotency of external effects, and the agent runtime.

2. **Kam** — Admission rules, per-scope ordering, immutable revisions, generations, projections, and receipts, with the limits stated above.

3. **Identity and access** — Cognito authenticates the principal. The History API decides which workspaces that principal can read. Neither the browser nor this website grants access.

4. **Deployment** — Kam runs in AWS. No live deployment or Marketplace listing is offered today; an evaluation needs an isolated deployment and an explicit review of identity, permissions, retries, corrections and exit.

## What remains unqualified

Every capability below is shown at the highest level its recorded evidence supports. No capability is live-qualified, pilot-only, or production-authorized.

1. **History — Locally qualified** — Package qualification is not a live deployment.

2. **Identity & membership — Locally qualified** — Covered by the same package qualification as History.

3. **Views & current State — Source-implemented** — Not deployed. Package coverage of View reconciliation is not confirmed for the website.

4. **State queries & Components — Source-implemented** — SDK 0.36.0 candidate; whether the SDK artifact round trip exercises queries is not confirmed for the website.

5. **Metrics, materialize & watch — Planned · not available** — Design preview only.

6. **Turn Lifecycle — Locally qualified** — Merged native toolkit; reference-only local frames.

7. **Context compiler — Planned · not available** — Design direction only.

8. **Operational durability — Source-implemented** — History and reconciliation progress are durable in source; no named checkpoint API.

9. **Profiler & developer toolkit — Locally qualified** — Merged; Linux x64 only; no public distribution.

10. **Optional AgentCore delivery — Locally qualified** — Default off; simulated AWS transports only.

11. **Export, deletion & restore fence — Source-implemented** — Live erasure and restore drills are qualification gates.

[What has been tested](/docs/qualification)

## Quickstart: record, correct, read both revisions

Every call below exists in the pinned SDK 0.36.0 typings. It needs an authorized endpoint, tenant and token, which are never embedded in these pages. The SDK is not published to npm.

### Record a correction and read both exact revisions

```javascript
// SDK 0.36.0 (the qualified CI artifact for backend 1db8cf00). Not published to npm.
// Run in Node 22 with an authorized endpoint, tenant and short-lived access token.
import { createKamClient } from '@kam-ai/agentcore-history-sdk';
const kam = createKamClient({
  baseUrl: process.env.KAM_API_URL,
  tenantId: process.env.KAM_TENANT_ID,
  accessToken: () => process.env.KAM_ACCESS_TOKEN,
});
const checks = kam.scope({ subjectId: 'checkout', type: 'deployment' });

// 1. Accept revision 1. Sending the identical payload again returns status 'duplicate'.
const first = await checks.outcome({ id: 'deploy-0412', occurredAt: '2026-10-06T17:00:00.000Z', status: 'success' });

// 2. Correct it: the next revision, same id and occurredAt. Revision 1 is kept.
const second = await checks.outcome({ id: 'deploy-0412', revision: 2, occurredAt: '2026-10-06T17:00:00.000Z', status: 'failure' });
console.log(first.acceptedSequence, second.acceptedSequence); // per-scope order

// 3. Read both exact revisions. Direct mode makes no day-membership claim.
const exact = await checks.byIds({ refs: [{ id: 'deploy-0412', revision: 1 }, { id: 'deploy-0412', revision: 2 }] });
for (const record of exact.records) console.log(record.ref.revision, record.status);
```