feat(scum): add live data asset manifest contracts

2026-08-11 18:04:08 +08:00
parent dfd8ca76c9
commit 05ddb3babf
6 changed files with 366 additions and 6 deletions
@@ -312,10 +312,101 @@ export interface SCUMSchemaProbeDeclaration {
  bounds: SCUMSchemaProbeBoundsDeclaration;
 }

+export type SCUMVersionedAssetDigest = `sha256:${string}`;
+export type SCUMLiveDataReadCapability = Extract<SCUMLiveDataCapability, "players.read" | "player-details.read" | "squads.read" | "squad-members.read" | "vehicles.read" | "flags.read" | "positions.read">;
+export type SCUMLiveDataWriteCapability = Extract<SCUMLiveDataCapability, "profile-xml.write" | "economy-command.write" | "gift-command.write">;
+
+export interface SCUMVersionedAssetDeclaration {
+  key: string;
+  adapterVersion: string;
+  assetPath: string;
+  digest: SCUMVersionedAssetDigest;
+}
+
+export interface SCUMLoginLogParserDeclaration extends SCUMVersionedAssetDeclaration {
+  parserVersion: string;
+  sourceKey: string;
+  eventType: string;
+  eventSchemaRef: string;
+  maxLineBytes: number;
+  cursorPolicy: "source-generation-sequence";
+  privacy: { stripNetworkIdentifiers: true; logicalEventIdentity: "native-or-sanitized-fields" };
+}
+
+export interface SCUMSQLiteQueryAssetDeclaration extends SCUMVersionedAssetDeclaration {
+  capability: SCUMLiveDataReadCapability;
+  requiredSchemaFingerprint: string;
+  transportKey: string;
+  targetKey: string;
+  parameterSchemaRef: string;
+  resultSchemaRef: string;
+  maxRows: number;
+  timeoutMs: number;
+  maxResultBytes: number;
+}
+
+export interface SCUMLiveDataSyncCadenceDeclaration {
+  capability: SCUMLiveDataReadCapability;
+  intervalSeconds: number;
+  jitterPercent: number;
+  timeoutMs: number;
+  maxConcurrentPerServer: number;
+}
+
+export interface SCUMTypedRCONTemplateDeclaration extends SCUMVersionedAssetDeclaration {
+  capability: Extract<SCUMLiveDataWriteCapability, "economy-command.write" | "gift-command.write">;
+  requiredSchemaFingerprint?: string;
+  transportKey: string;
+  targetKey: string;
+  permission: Extract<PluginPermission, "server.game-client.command">;
+  payloadSchemaRef: string;
+  resultSchemaRef: string;
+  confirmationSchemaRef?: string;
+  timeoutMs: number;
+  maxPayloadBytes: number;
+}
+
+export interface SCUMGuardedMutationDeclaration extends SCUMVersionedAssetDeclaration {
+  capability: Extract<SCUMLiveDataWriteCapability, "profile-xml.write">;
+  requiredSchemaFingerprint: string;
+  transportKey: string;
+  targetKey: string;
+  permission: Extract<PluginPermission, "server.game-client.maintenance">;
+  payloadSchemaRef: string;
+  resultSchemaRef: string;
+  confirmationSchemaRef: string;
+  timeoutMs: number;
+  maxPayloadBytes: number;
+  maxRowsAffected: 1;
+  safety: { requiresExpectedChecksum: true; requiresBackupEvidence: true; requiresOfflineOrMaintenance: true; requiresReadAfterWrite: true };
+}
+
+export interface SCUMMapAssetDeclaration extends SCUMVersionedAssetDeclaration {
+  requiredSchemaFingerprint: string;
+  metadataSchemaRef: string;
+  transformAssetPath: string;
+  transformDigest: SCUMVersionedAssetDigest;
+  worldBounds: { minX: number; minY: number; maxX: number; maxY: number };
+  image: { width: number; height: number };
+}
+
+export interface SCUMGiftCatalogDeclaration extends SCUMVersionedAssetDeclaration {
+  catalogVersion: string;
+  itemSchemaRef: string;
+  transportTemplateKeys: string[];
+}
+
 export interface SCUMLiveDataManifestDeclaration {
  schemaVersion: "1";
  probe: SCUMSchemaProbeDeclaration;
  capabilityGates: SCUMLiveDataCapabilityGateDeclaration[];
+  logParsers?: SCUMLoginLogParserDeclaration[];
+  sqliteQueries?: SCUMSQLiteQueryAssetDeclaration[];
+  syncCadences?: SCUMLiveDataSyncCadenceDeclaration[];
+  typedRconTemplates?: SCUMTypedRCONTemplateDeclaration[];
+  guardedMutations?: SCUMGuardedMutationDeclaration[];
+  mapAssets?: SCUMMapAssetDeclaration[];
+  giftCatalogs?: SCUMGiftCatalogDeclaration[];
 }

 export interface GameClientBridgeOperationSafety {