Eve library

`@yemaya/instrumented-session-sdk`

Other

Revision 1

On this page

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.