Eve library

V9-004 offline sync integrity

Evidence

Revision 1

On this page

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.