The versioned instrumented-session SDK an owned game embeds to deliver a Tier B/C study session (proposal §12.2, YSD-12020/12024/12027/12028; shipped under YSD-19082).
It depends on @oshun/contracts and nothing else in the monorepo. A game does
not take a dependency on the study workspace in order to send it a session.
What it does that a hand-rolled uploader does not#
| Concern | What the SDK does |
|---|---|
| Sequences | The recorder owns them, per stream, monotonic. A caller that could set one could fake packet loss. |
| Instants | Stamped on the stream's declared clock basis. A stream on the engine frame or video clock must supply its own. |
| A full buffer | Drops the oldest and counts it, so the retained window stays contiguous and the gap check reads truthfully. |
| Loss | Every drop, rate refusal and backwards clock step is in the capture report — inside the signed hash. |
| Signing | The SDK computes the hash and hands it to the host's key. It never manufactures a signature. |
| Protocol drift | Negotiates against the workspace's advertised window and refuses to send outside it. |
| Partial delivery | Acknowledges only what the receiver counted; the tail stays for a retry. |
| An unclassified field | Fails the build of the ingest plan, naming the paths. Nothing defaults to gameplay. |
Shape of an integration#
ts
import {
buildEnvelope,
buildIngestPlan,
createHttpTransport,
createSessionRecorder,
flush,
} from '@yemaya/instrumented-session-sdk';
const recorder = createSessionRecorder({
sessionId,
producerBuild: '1.4.2+9f21c',
captureClass: 'deterministic-replay',
now: () => performance.now(),
streams: [
{
stream: 'input',
family: 'input',
schemaRef: 'yemaya/study/events/input',
schemaVersion: '1.0.0',
ownerDomain: 'yemaya',
clockBasis: 'session-monotonic',
sequenced: true,
privacyClass: 'pseudonymized',
samplingInterval: 100,
},
],
});
recorder.emit('input', { family: 'input', action: 'attack-light' /* … */ });
recorder.addSyncPoint('engine-frame', currentFrameIndex);
const built = await buildEnvelope(recorder, {
engine: {
engineFamily: 'v2',
engineVersion,
connectorId,
connectorVersion,
},
maxSupportedTier: 'instrumented-session',
supportedCaptureClasses: ['deterministic-replay'],
negotiatedAt: handshakeInstant,
sessionAuthorityGrantId: grantId,
sign: (contentHash) => hostKey.sign(contentHash),
});
await flush(recorder, createHttpTransport({ baseUrl, projectId, editionId, territory, fetch }));
Proving a connector before it ships#
Run the workspace's conformance suite against a real capture — not a hand-written fixture — by adapting the recorder:
ts
import { asConformanceSubject } from '@yemaya/instrumented-session-sdk';
import { runSdkConformance } from '@yemaya/study-workspace';
const report = runSdkConformance(
asConformanceSubject(recorder, { built, ingestPlan, engineFrameRateHz: 60 }),
{ pseudonymize }
);
Six checks, no partial credit. The rules the checks enforce, and what counts as
a breaking registry change, are in
docs/integrations/instrumented-session-sdk/UPGRADE.md.
The first-party reference integration is V2 (decision
YSD-0127):
libs/aphrodite/game-runtime/src/study-connector.