# V9-004 offline sync integrity

Date: 2026-07-27

## Repository result

Metis's authenticated durable xAPI endpoint is the repository's existing
learner-activity ingestion boundary and a suitable future sink for mobile
offline events. Its former idempotency behavior was unsafe for that role: any
request reusing a stored statement UUID was returned as a duplicate, even when
the learner, verb, object, result, context, registration, or timestamp differed.
That could silently acknowledge a colliding offline event without retaining its
content.

The service now binds each statement UUID to canonical immutable semantic
material:

- authenticated learner and authority;
- verb and activity object;
- result;
- context and cmi5 registration;
- client timestamp; and
- every nested field in those records.

An exact retry returns the original durable statement with `duplicate: true`.
Changed content returns HTTP 409 and does not append a second statement.
Requests that omit a retry timestamp are compared against the original stored
timestamp, preserving compatibility for server-timestamped exact retries without
allowing other fields to change.

## Concurrent-worker behavior

The SQLAlchemy store now inserts inside a savepoint. If another worker wins the
unique-statement-ID race, the losing worker reads the committed statement and
returns it as a duplicate. The service then repeats the complete semantic
comparison before acknowledging it. A same-content race succeeds idempotently; a
changed-content race fails as a conflict.

This closes both lookup-time and insert-time collision paths. It does not claim
global exactly-once delivery: a client still retries with a stable statement
UUID, and downstream consumers must retain that identity.

## Attachment boundary

The request schema previously accepted xAPI attachments even though the model
and durable store did not retain their metadata or bytes. Attachments now fail
validation with `maxItems: 0` until a hash- and byte-retaining implementation
exists. The canonical OpenAPI document exposes that bound instead of silently
dropping evidence.

## Verification

- Focused xAPI service, API, OpenAPI, and exporter suites: 29 tests passed.
- Ruff lint and format checks: passed.
- Strict MyPy over the three changed production modules: passed.
- `pnpm metis:contracts:check`: canonical OpenAPI and generated TypeScript
  client freshness passed.
- `pnpm exec tsc --noEmit -p tsconfig.json` in `libs/openapi`: passed.

## Honest boundary

This is server-side admission integrity, not completed mobile synchronization.
The mobile app still lacks an authenticated session/token provider and therefore
keeps its transport deliberately unconfigured. No live device delivery,
production database race, mastery mutation, merge/conflict policy, or deployed
learner event is claimed. Those remain part of the open composite V9-004
mobile/offline launch task.
