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.jsoninlibs/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.