@opengeni/contracts 0.39.0 → 0.40.0

package/dist/index.js

@@ -23,6 +23,11 @@ import {
   CODEX_FLEET_POLICY_MAX_OVERLAYS_PER_CANDIDATE,
   CODEX_FLEET_POLICY_SCHEMA_VERSION,
   CODEX_FLEET_POLICY_VERSION,
+  COMPUTER_SCREENSHOT_MAX_BYTES,
+  COMPUTER_SCREENSHOT_MAX_DIMENSION,
+  COMPUTER_SCREENSHOT_MAX_PIXELS,
+  COMPUTER_SCREENSHOT_RETENTION_MS,
+  COMPUTER_SCREENSHOT_WORKSPACE_QUOTA_BYTES,
   CapabilityCatalogAuthKind,
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
@@ -158,6 +163,8 @@ import {
   FsDeleteRequest,
   FsDeleteResponse,
   FsEncoding,
+  FsListBatchRequest,
+  FsListBatchResponse,
   FsListRequest,
   FsListResponse,
   FsMkdirRequest,
@@ -199,6 +206,10 @@ import {
   GitHubRepositoryScope,
   GitLogRequest,
   GitLogResponse,
+  GitReadBatchItemRequest,
+  GitReadBatchItemResponse,
+  GitReadBatchRequest,
+  GitReadBatchResponse,
   GitRepositoryAccess,
   GitShowRequest,
   GitShowResponse,
@@ -257,6 +268,8 @@ import {
   ListEnrollmentsResponse,
   ListWorkspaceMembersResponse,
   MAX_NESTED_AGENT_DEPTH,
+  MCP_MUTATION_RECEIPT_MAX_BYTES,
+  MCP_MUTATION_RECEIPT_VERSION,
   MODEL_ATTACHMENT_REFS_FIELD,
   MachineKind,
   MachineMetricsSeriesResponse,
@@ -266,6 +279,10 @@ import {
   ManagedAccount,
   MarketingDailyAnalysisTaskRequest,
   McpConnectionResourceScope,
+  McpMutationReceipt,
+  McpMutationReceiptIdempotencyStatus,
+  McpMutationReceiptOutcome,
+  McpMutationResource,
   McpPersonalConnectionDelegation,
   McpPersonalConnectionDelegations,
   McpPersonalConnectionSummary,
@@ -359,8 +376,10 @@ import {
   RegisterCapabilityPackRequest,
   RejectPreferenceRegistryProposalRequest,
   RelayTokenPayload,
+  RemoveEnrollmentRequest,
   RenewSessionRealtimeRequest,
   RepositoryResourceRef,
+  RepositoryUriError,
   RequestHumanInputToolInput,
   ResolvedWorkspaceInstructionPolicySnapshot,
   ResolvedWorkspaceInstructionPolicySnapshotEntry,
@@ -574,6 +593,7 @@ import {
   VOICE_INPUT_MAX_DURATION_SECONDS,
   VOICE_INPUT_MAX_SIZE_BYTES,
   VariableSet,
+  VariableSetSecret,
   VariableSetVariableMetadata,
   VariableSetVariableName,
   ViewerHeartbeatRequest,
@@ -717,7 +737,6 @@ import {
   compareCodexFleetCanonicalStringsV1,
   comparePersonalSlackCanonicalConnections,
   createCodexFleetReplayRecordV1,
-  createSecretRedactor,
   decodeNativeSnapshotRef,
   defaultRepositoryMountPath,
   effectiveCodexFleetCacheStateV1,
@@ -725,10 +744,10 @@ import {
   evaluateWorkspaceModelPolicy,
   gitCredentialBindingIdForRepository,
   gitCredentialProviderForRepository,
-  identityRedactor,
+  gitRemoteIdentity,
+  gitRemotePathAliases,
+  gitRemoteUriAliases,
   isClearedRunStateBlob,
-  isCredentialHeaderName,
-  isSensitiveFieldName,
   latencyModeForMetadata,
   measureSessionEventJson,
   mergeResourceRefs,
@@ -736,6 +755,7 @@ import {
   metadataWithTurnExecutionPolicyV1,
   normalizePreferenceRegistryStableKey,
   normalizeRepositorySubpath,
+  normalizeRepositoryTransportUri,
   normalizeResourceMountPath,
   normalizeWorkspaceArtifactSlug,
   normalizeWorkspaceInstructionPolicyRoleKey,
@@ -744,14 +764,11 @@ import {
   readCodexFleetReplayRecordV1,
   readTurnExecutionPolicyV1,
   reasoningEffortForMetadata,
-  redactSensitiveData,
-  redactSensitiveKey,
-  redactSensitiveText,
-  redactSerializedJson,
   renderSessionSystemUpdateBatch,
   replayCodexFleetDecisionV1,
   resolveRetainedOutputRange,
   resolveSessionEventTypeFilters,
+  resolveWorkspaceAgentHumanInputEnabled,
   resolveWorkspaceCodexCompactionDefault,
   resolveWorkspaceMemoryEnabled,
   resolveWorkspaceSlackReactionSummonSettings,
@@ -761,6 +778,7 @@ import {
   resourceMountPathCollisionKey,
   retainedArtifactReferenceFromFile,
   retainedOutputUnavailable,
+  retainedScreenshotReferenceFromFile,
   selectCanonicalPersonalSlackConnection,
   sessionEventJsonBytes,
   sessionEventLatestClassToSemanticClass,
@@ -783,7 +801,7 @@ import {
   verifyStreamToken,
   workspaceControlUtf8Bytes,
   workspaceSlackReactionChannelAllowed
-} from "./chunk-PCTCJEAF.js";
+} from "./chunk-5HR2GPSC.js";
 import {
   ConnectorDocumentDestination,
   ConnectorDocumentDestinationAuthority,
@@ -832,6 +850,11 @@ export {
   CODEX_FLEET_POLICY_MAX_OVERLAYS_PER_CANDIDATE,
   CODEX_FLEET_POLICY_SCHEMA_VERSION,
   CODEX_FLEET_POLICY_VERSION,
+  COMPUTER_SCREENSHOT_MAX_BYTES,
+  COMPUTER_SCREENSHOT_MAX_DIMENSION,
+  COMPUTER_SCREENSHOT_MAX_PIXELS,
+  COMPUTER_SCREENSHOT_RETENTION_MS,
+  COMPUTER_SCREENSHOT_WORKSPACE_QUOTA_BYTES,
   CapabilityCatalogAuthKind,
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
@@ -970,6 +993,8 @@ export {
   FsDeleteRequest,
   FsDeleteResponse,
   FsEncoding,
+  FsListBatchRequest,
+  FsListBatchResponse,
   FsListRequest,
   FsListResponse,
   FsMkdirRequest,
@@ -1011,6 +1036,10 @@ export {
   GitHubRepositoryScope,
   GitLogRequest,
   GitLogResponse,
+  GitReadBatchItemRequest,
+  GitReadBatchItemResponse,
+  GitReadBatchRequest,
+  GitReadBatchResponse,
   GitRepositoryAccess,
   GitShowRequest,
   GitShowResponse,
@@ -1069,6 +1098,8 @@ export {
   ListEnrollmentsResponse,
   ListWorkspaceMembersResponse,
   MAX_NESTED_AGENT_DEPTH,
+  MCP_MUTATION_RECEIPT_MAX_BYTES,
+  MCP_MUTATION_RECEIPT_VERSION,
   MODEL_ATTACHMENT_REFS_FIELD,
   MachineKind,
   MachineMetricsSeriesResponse,
@@ -1078,6 +1109,10 @@ export {
   ManagedAccount,
   MarketingDailyAnalysisTaskRequest,
   McpConnectionResourceScope,
+  McpMutationReceipt,
+  McpMutationReceiptIdempotencyStatus,
+  McpMutationReceiptOutcome,
+  McpMutationResource,
   McpPersonalConnectionDelegation,
   McpPersonalConnectionDelegations,
   McpPersonalConnectionSummary,
@@ -1178,8 +1213,10 @@ export {
   RegisterCapabilityPackRequest,
   RejectPreferenceRegistryProposalRequest,
   RelayTokenPayload,
+  RemoveEnrollmentRequest,
   RenewSessionRealtimeRequest,
   RepositoryResourceRef,
+  RepositoryUriError,
   RequestHumanInputToolInput,
   ResolvedWorkspaceInstructionPolicySnapshot,
   ResolvedWorkspaceInstructionPolicySnapshotEntry,
@@ -1393,6 +1430,7 @@ export {
   VOICE_INPUT_MAX_DURATION_SECONDS,
   VOICE_INPUT_MAX_SIZE_BYTES,
   VariableSet,
+  VariableSetSecret,
   VariableSetVariableMetadata,
   VariableSetVariableName,
   ViewerHeartbeatRequest,
@@ -1541,7 +1579,6 @@ export {
   connectorDestinationDocumentAuthority,
   connectorDocumentDestinationCollectionId,
   createCodexFleetReplayRecordV1,
-  createSecretRedactor,
   decodeNativeSnapshotRef,
   defaultRepositoryMountPath,
   effectiveCodexFleetCacheStateV1,
@@ -1550,11 +1587,11 @@ export {
   evaluateWorkspaceModelPolicy,
   gitCredentialBindingIdForRepository,
   gitCredentialProviderForRepository,
+  gitRemoteIdentity,
+  gitRemotePathAliases,
+  gitRemoteUriAliases,
   hasOpenGeniSlackReactionScope,
-  identityRedactor,
   isClearedRunStateBlob,
-  isCredentialHeaderName,
-  isSensitiveFieldName,
   latencyModeForMetadata,
   legacyWorkspaceConnectorDocumentDestination,
   measureSessionEventJson,
@@ -1563,6 +1600,7 @@ export {
   metadataWithTurnExecutionPolicyV1,
   normalizePreferenceRegistryStableKey,
   normalizeRepositorySubpath,
+  normalizeRepositoryTransportUri,
   normalizeResourceMountPath,
   normalizeWorkspaceArtifactSlug,
   normalizeWorkspaceInstructionPolicyRoleKey,
@@ -1571,15 +1609,12 @@ export {
   readCodexFleetReplayRecordV1,
   readTurnExecutionPolicyV1,
   reasoningEffortForMetadata,
-  redactSensitiveData,
-  redactSensitiveKey,
-  redactSensitiveText,
-  redactSerializedJson,
   renderSessionSystemUpdateBatch,
   replayCodexFleetDecisionV1,
   resolveConnectorDocumentDestination,
   resolveRetainedOutputRange,
   resolveSessionEventTypeFilters,
+  resolveWorkspaceAgentHumanInputEnabled,
   resolveWorkspaceCodexCompactionDefault,
   resolveWorkspaceMemoryEnabled,
   resolveWorkspaceSlackReactionSummonSettings,
@@ -1589,6 +1624,7 @@ export {
   resourceMountPathCollisionKey,
   retainedArtifactReferenceFromFile,
   retainedOutputUnavailable,
+  retainedScreenshotReferenceFromFile,
   selectCanonicalPersonalSlackConnection,
   sessionEventJsonBytes,
   sessionEventLatestClassToSemanticClass,

package/dist/mcp-receipts.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+/**
+ * Versioned, provider-neutral receipt returned by first-party MCP mutation tools.
+ *
+ * A receipt intentionally contains only server-generated identity and outcome
+ * facts. Callers already have mutation inputs in their tool-call history, so
+ * copying names, prompts, instructions, commands, evidence, or other request
+ * fields into the result wastes context and can expose data twice.
+ */
+export declare const MCP_MUTATION_RECEIPT_VERSION: "mcp-mutation-receipt.v1";
+export declare const MCP_MUTATION_RECEIPT_MAX_BYTES: number;
+export declare const McpMutationReceiptOutcome: z.ZodEnum<{
+    accepted: "accepted";
+    created: "created";
+    deleted: "deleted";
+    partial_failure: "partial_failure";
+    repaired: "repaired";
+    replayed: "replayed";
+    triggered: "triggered";
+    unchanged: "unchanged";
+    updated: "updated";
+}>;
+export type McpMutationReceiptOutcome = z.infer<typeof McpMutationReceiptOutcome>;
+export declare const McpMutationReceiptIdempotencyStatus: z.ZodEnum<{
+    applied: "applied";
+    not_requested: "not_requested";
+    not_supported: "not_supported";
+    replayed: "replayed";
+    unknown: "unknown";
+}>;
+export type McpMutationReceiptIdempotencyStatus = z.infer<typeof McpMutationReceiptIdempotencyStatus>;
+export declare const McpMutationResource: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+    version: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    etag: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type McpMutationResource = z.infer<typeof McpMutationResource>;
+export declare const McpMutationReceipt: z.ZodObject<{
+    receiptVersion: z.ZodLiteral<"mcp-mutation-receipt.v1">;
+    operation: z.ZodString;
+    committed: z.ZodLiteral<true>;
+    outcome: z.ZodEnum<{
+        accepted: "accepted";
+        created: "created";
+        deleted: "deleted";
+        partial_failure: "partial_failure";
+        repaired: "repaired";
+        replayed: "replayed";
+        triggered: "triggered";
+        unchanged: "unchanged";
+        updated: "updated";
+    }>;
+    changed: z.ZodBoolean;
+    resource: z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+        version: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        etag: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    relatedResources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+        version: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        etag: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    timestamp: z.ZodString;
+    idempotency: z.ZodObject<{
+        status: z.ZodEnum<{
+            applied: "applied";
+            not_requested: "not_requested";
+            not_supported: "not_supported";
+            replayed: "replayed";
+            unknown: "unknown";
+        }>;
+    }, z.core.$strict>;
+    partialFailure: z.ZodOptional<z.ZodObject<{
+        stage: z.ZodString;
+        retryable: z.ZodBoolean;
+    }, z.core.$strict>>;
+    warnings: z.ZodArray<z.ZodString>;
+    nextAction: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodString;
+        arguments: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strict>>;
+    facts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    id: z.ZodOptional<z.ZodString>;
+    rootSessionId: z.ZodOptional<z.ZodString>;
+    nestedAgentDepth: z.ZodOptional<z.ZodNumber>;
+    effectiveMaxNestedAgentDepth: z.ZodOptional<z.ZodNumber>;
+    updateId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type McpMutationReceipt = z.infer<typeof McpMutationReceipt>;

package/dist/retained-output.d.ts

@@ -5,8 +5,17 @@ export declare const RETAINED_OUTPUT_MAX_PAGE_BYTES: number;
 export declare const RETAINED_OUTPUT_DEFAULT_PAGE_BYTES: number;
 /** Receipts are timeline references, never an extensible metadata bag. */
 export declare const RETAINED_OUTPUT_RECEIPT_MAX_BYTES: number;
+/** Screenshot bytes are accounted separately from the 10k-token text policy. */
+export declare const COMPUTER_SCREENSHOT_MAX_BYTES: number;
+export declare const COMPUTER_SCREENSHOT_MAX_DIMENSION = 16384;
+export declare const COMPUTER_SCREENSHOT_MAX_PIXELS = 67108864;
+/** Canonical ready-object retention window: 30 days from successful settlement. */
+export declare const COMPUTER_SCREENSHOT_RETENTION_MS: number;
+/** Hard workspace reservation across pending + ready screenshot artifacts. */
+export declare const COMPUTER_SCREENSHOT_WORKSPACE_QUOTA_BYTES: number;
 export declare const RetainedOutputKind: z.ZodEnum<{
     assistant_completion: "assistant_completion";
+    computer_screenshot: "computer_screenshot";
     event_media: "event_media";
     file: "file";
     internal_update: "internal_update";
@@ -17,9 +26,12 @@ export declare const RetainedOutputUnavailableReason: z.ZodEnum<{
     deleted: "deleted";
     expired: "expired";
     failed: "failed";
+    invalid_content: "invalid_content";
     missing_storage: "missing_storage";
     not_retained: "not_retained";
+    oversized: "oversized";
     pending: "pending";
+    quota_exceeded: "quota_exceeded";
     storage_write_failed: "storage_write_failed";
     unsupported: "unsupported";
 }>;
@@ -29,6 +41,7 @@ export declare const RetainedArtifactReferenceSchema: z.ZodObject<{
     artifactId: z.ZodString;
     kind: z.ZodEnum<{
         assistant_completion: "assistant_completion";
+        computer_screenshot: "computer_screenshot";
         event_media: "event_media";
         file: "file";
         internal_update: "internal_update";
@@ -38,10 +51,17 @@ export declare const RetainedArtifactReferenceSchema: z.ZodObject<{
     originalBytes: z.ZodNumber;
     sha256: z.ZodString;
     retainedAt: z.ZodString;
-    retention: z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    retention: z.ZodUnion<readonly [z.ZodObject<{
         policy: z.ZodLiteral<"workspace_file">;
         expiresAt: z.ZodNull;
-    }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        policy: z.ZodLiteral<"session_screenshot">;
+        expiresAt: z.ZodString;
+    }, z.core.$strict>]>;
     retrieval: z.ZodObject<{
         method: z.ZodLiteral<"GET">;
         path: z.ZodString;
@@ -62,9 +82,12 @@ export declare const RetainedOutputEvidenceSchema: z.ZodDiscriminatedUnion<[z.Zo
         deleted: "deleted";
         expired: "expired";
         failed: "failed";
+        invalid_content: "invalid_content";
         missing_storage: "missing_storage";
         not_retained: "not_retained";
+        oversized: "oversized";
         pending: "pending";
+        quota_exceeded: "quota_exceeded";
         storage_write_failed: "storage_write_failed";
         unsupported: "unsupported";
     }>;
@@ -73,6 +96,7 @@ export declare const RetainedOutputEvidenceSchema: z.ZodDiscriminatedUnion<[z.Zo
     artifactId: z.ZodString;
     kind: z.ZodEnum<{
         assistant_completion: "assistant_completion";
+        computer_screenshot: "computer_screenshot";
         event_media: "event_media";
         file: "file";
         internal_update: "internal_update";
@@ -82,10 +106,17 @@ export declare const RetainedOutputEvidenceSchema: z.ZodDiscriminatedUnion<[z.Zo
     originalBytes: z.ZodNumber;
     sha256: z.ZodString;
     retainedAt: z.ZodString;
-    retention: z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    retention: z.ZodUnion<readonly [z.ZodObject<{
         policy: z.ZodLiteral<"workspace_file">;
         expiresAt: z.ZodNull;
-    }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        policy: z.ZodLiteral<"session_screenshot">;
+        expiresAt: z.ZodString;
+    }, z.core.$strict>]>;
     retrieval: z.ZodObject<{
         method: z.ZodLiteral<"GET">;
         path: z.ZodString;
@@ -104,9 +135,12 @@ export declare const RetainedArtifactUnavailableSchema: z.ZodObject<{
         deleted: "deleted";
         expired: "expired";
         failed: "failed";
+        invalid_content: "invalid_content";
         missing_storage: "missing_storage";
         not_retained: "not_retained";
+        oversized: "oversized";
         pending: "pending";
+        quota_exceeded: "quota_exceeded";
         storage_write_failed: "storage_write_failed";
         unsupported: "unsupported";
     }>;
@@ -118,6 +152,7 @@ export declare const RetainedArtifactMetadataSchema: z.ZodUnion<readonly [z.ZodO
     artifactId: z.ZodString;
     kind: z.ZodEnum<{
         assistant_completion: "assistant_completion";
+        computer_screenshot: "computer_screenshot";
         event_media: "event_media";
         file: "file";
         internal_update: "internal_update";
@@ -127,10 +162,17 @@ export declare const RetainedArtifactMetadataSchema: z.ZodUnion<readonly [z.ZodO
     originalBytes: z.ZodNumber;
     sha256: z.ZodString;
     retainedAt: z.ZodString;
-    retention: z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    retention: z.ZodUnion<readonly [z.ZodObject<{
         policy: z.ZodLiteral<"workspace_file">;
         expiresAt: z.ZodNull;
-    }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        policy: z.ZodLiteral<"session_screenshot">;
+        expiresAt: z.ZodString;
+    }, z.core.$strict>]>;
     retrieval: z.ZodObject<{
         method: z.ZodLiteral<"GET">;
         path: z.ZodString;
@@ -144,9 +186,12 @@ export declare const RetainedArtifactMetadataSchema: z.ZodUnion<readonly [z.ZodO
         deleted: "deleted";
         expired: "expired";
         failed: "failed";
+        invalid_content: "invalid_content";
         missing_storage: "missing_storage";
         not_retained: "not_retained";
+        oversized: "oversized";
         pending: "pending";
+        quota_exceeded: "quota_exceeded";
         storage_write_failed: "storage_write_failed";
         unsupported: "unsupported";
     }>;
@@ -161,12 +206,20 @@ export type RetainedArtifactFileInput = {
     sha256: string | null;
     updatedAt: string;
 };
+export type RetainedScreenshotArtifactInput = RetainedArtifactFileInput & {
+    sessionId: string;
+    width: number;
+    height: number;
+    expiresAt: string;
+};
 /**
  * Convert a ready, integrity-addressed workspace file into the only available
  * retained-output receipt shape. Invalid, pending, or checksum-less files fail
  * closed instead of implying that full evidence is retrievable.
  */
 export declare function retainedArtifactReferenceFromFile(file: RetainedArtifactFileInput, kind?: RetainedOutputKind): RetainedArtifactReference | null;
+/** Build the closed, session-scoped receipt for one ready screenshot file. */
+export declare function retainedScreenshotReferenceFromFile(file: RetainedScreenshotArtifactInput): RetainedArtifactReference | null;
 /** Parse and clone a trusted server receipt; invalid/untrusted data fails closed. */
 export declare function validateRetainedOutputEvidence(value: unknown): RetainedOutputEvidence | null;
 export declare function retainedOutputUnavailable(reason?: RetainedOutputUnavailableReason): RetainedOutputEvidence;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {

package/src/event-preview.ts

@@ -1,10 +1,10 @@
 /**
- * Canonical bounded representation for `session_events.payload`.
+ * Canonical bounded representation for explicit session-event previews.
  *
- * Session events are the lossy human/audit projection, not model memory and not
- * an evidence blob store. This helper keeps that projection useful while making
- * the loss explicit. It deliberately has no server-only dependency so the DB,
- * realtime transports, SDK/React, and tests can share one wire contract.
+ * Canonical session-event payloads are stored in full. This helper derives a
+ * bounded monitoring/public projection without writing that projection back
+ * over canonical data. It deliberately has no server-only dependency so the
+ * DB, realtime transports, SDK/React, and tests can share one wire contract.
  */
 
 import {
@@ -184,7 +184,7 @@ export function sessionEventPayloadTruncation(
 }
 
 /**
- * Return a byte-bounded audit payload. Unchanged ordinary payloads retain their
+ * Return a byte-bounded preview payload. Unchanged ordinary payloads retain their
  * reference. Oversized strings/containers get deterministic head+tail previews;
  * inline images/binary values become metadata because `session_events` does not
  * durably retain their source bytes as independently retrievable evidence.