@syncular/core 0.7.0 → 0.9.0

package/dist/frames.d.ts

@@ -13,6 +13,7 @@ export declare const FrameType: {
     readonly SEGMENT_INLINE: 21;
     readonly SUB_END: 22;
     readonly LEASE: 25;
+    readonly PUSH_RESULT_DETAILS: 27;
     readonly ERROR: 31;
 };
 export type FrameTypeName = keyof typeof FrameType;

package/dist/frames.js

@@ -13,6 +13,7 @@ export const FrameType = {
     SEGMENT_INLINE: 0x15,
     SUB_END: 0x16,
     LEASE: 0x19,
+    PUSH_RESULT_DETAILS: 0x1b,
     ERROR: 0x1f,
 };
 /** Known request frame types (excluding END). */
@@ -32,6 +33,7 @@ export const RESPONSE_FRAME_TYPES = new Set([
     FrameType.SEGMENT_INLINE,
     FrameType.SUB_END,
     FrameType.LEASE,
+    FrameType.PUSH_RESULT_DETAILS,
     FrameType.ERROR,
 ]);
 /** Every frame type with a defined layout in wire version 1. */

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from './errors.js';
 export * from './frames.js';
 export * from './message.js';
 export * from './realtime.js';
+export * from './rejection-details.js';
 export * from './render.js';
 export * from './row-codec.js';
 export * from './segment.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export * from './errors.js';
 export * from './frames.js';
 export * from './message.js';
 export * from './realtime.js';
+export * from './rejection-details.js';
 export * from './render.js';
 export * from './row-codec.js';
 export * from './segment.js';

package/dist/message.d.ts

@@ -1,3 +1,4 @@
+import { type RejectionDetails } from './rejection-details.js';
 export type ScopeMap = Record<string, string[]>;
 export interface ReqHeaderFrame {
     type: 'REQ_HEADER';
@@ -70,6 +71,11 @@ export type PushOperationResult = {
     code: string;
     message: string;
     retryable: boolean;
+    /**
+     * Host-safe structured metadata. It is emitted on the wire through the
+     * additive PUSH_RESULT_DETAILS companion frame, not the legacy record.
+     */
+    details?: RejectionDetails;
 };
 export interface PushResultFrame {
     type: 'PUSH_RESULT';
@@ -79,6 +85,18 @@ export interface PushResultFrame {
     commitSeq?: number;
     results: PushOperationResult[];
 }
+/**
+ * Additive companion metadata for host validation errors. Older clients see
+ * this as an unknown frame and continue processing the normative PUSH_RESULT.
+ */
+export interface PushResultDetailsFrame {
+    type: 'PUSH_RESULT_DETAILS';
+    clientCommitId: string;
+    entries: Array<{
+        opIndex: number;
+        details: RejectionDetails;
+    }>;
+}
 export interface SubStartFrame {
     type: 'SUB_START';
     id: string;
@@ -140,7 +158,7 @@ export interface ErrorFrame {
     recommendedAction: string;
     details?: string;
 }
-export type ResponseFrame = RespHeaderFrame | LeaseFrame | PushResultFrame | SubStartFrame | CommitFrame | SegmentRefFrame | SegmentInlineFrame | SubEndFrame | ErrorFrame | UnknownFrame;
+export type ResponseFrame = RespHeaderFrame | LeaseFrame | PushResultFrame | PushResultDetailsFrame | SubStartFrame | CommitFrame | SegmentRefFrame | SegmentInlineFrame | SubEndFrame | ErrorFrame | UnknownFrame;
 export interface RequestMessage {
     wireVersion: number;
     msgKind: 'request';

package/dist/message.js

@@ -15,6 +15,7 @@ import { ByteReader, ByteWriter, readStringListMap, readStringMap, utf8Encode, w
 import { PROTOCOL_WIRE_VERSION, SYNC_PACK_MAGIC } from './constants.js';
 import { DecodeError } from './errors.js';
 import { FrameType, KNOWN_FRAME_TYPES, REQUEST_FRAME_TYPES, RESPONSE_FRAME_TYPES, } from './frames.js';
+import { normalizeRejectionDetails, } from './rejection-details.js';
 import { decodeRowsSegment } from './segment.js';
 const MAGIC_BYTES = utf8Encode(SYNC_PACK_MAGIC);
 function invalid(message) {
@@ -187,6 +188,33 @@ function decodePushResult(r) {
         results,
     };
 }
+function decodePushResultDetails(r) {
+    const clientCommitId = r.str();
+    if (clientCommitId.length === 0) {
+        invalid('PUSH_RESULT_DETAILS.clientCommitId must be non-empty');
+    }
+    const count = r.u32();
+    if (count === 0)
+        invalid('PUSH_RESULT_DETAILS must carry at least one entry');
+    const entries = [];
+    const seen = new Set();
+    for (let index = 0; index < count; index++) {
+        const opIndex = r.i32();
+        if (opIndex < 0 || seen.has(opIndex)) {
+            invalid('PUSH_RESULT_DETAILS opIndex values must be unique and non-negative');
+        }
+        seen.add(opIndex);
+        let details;
+        try {
+            details = normalizeRejectionDetails(JSON.parse(r.str()));
+        }
+        catch (error) {
+            invalid(`invalid PUSH_RESULT_DETAILS.details: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        entries.push({ opIndex, details });
+    }
+    return { type: 'PUSH_RESULT_DETAILS', clientCommitId, entries };
+}
 function decodeSubStart(r) {
     const id = r.str();
     const statusByte = r.u8();
@@ -363,6 +391,9 @@ function decodeResponseFrame(frameType, payload) {
         case FrameType.PUSH_RESULT:
             frame = decodePushResult(r);
             break;
+        case FrameType.PUSH_RESULT_DETAILS:
+            frame = decodePushResultDetails(r);
+            break;
         case FrameType.SUB_START:
             frame = decodeSubStart(r);
             break;
@@ -439,6 +470,8 @@ function validateResponseSequence(frames) {
     let subscriptionHasCommits = false;
     let subscriptionHasSegments = false;
     let errorSeen = false;
+    let lastPushResult;
+    let lastPushResultHasDetails = false;
     for (const frame of frames.slice(1)) {
         if (errorSeen)
             invalid('frames after ERROR (the next frame must be END)');
@@ -458,8 +491,32 @@ function validateResponseSequence(frames) {
             case 'PUSH_RESULT':
                 if (sawSubscription)
                     invalid('PUSH_RESULT frame after SUB_START');
+                lastPushResult = frame;
+                lastPushResultHasDetails = false;
+                sawBody = true;
+                break;
+            case 'PUSH_RESULT_DETAILS': {
+                if (sawSubscription) {
+                    invalid('PUSH_RESULT_DETAILS frame after SUB_START');
+                }
+                if (lastPushResult === undefined) {
+                    invalid('PUSH_RESULT_DETAILS without a preceding PUSH_RESULT');
+                }
+                if (lastPushResultHasDetails) {
+                    invalid('duplicate PUSH_RESULT_DETAILS companion');
+                }
+                if (lastPushResult.clientCommitId !== frame.clientCommitId ||
+                    lastPushResult.status !== 'rejected') {
+                    invalid('PUSH_RESULT_DETAILS does not match its rejected PUSH_RESULT');
+                }
+                const errorIndexes = new Set(lastPushResult.results.flatMap((result) => result.status === 'error' ? [result.opIndex] : []));
+                if (frame.entries.some((entry) => !errorIndexes.has(entry.opIndex))) {
+                    invalid('PUSH_RESULT_DETAILS entry does not match an error result');
+                }
+                lastPushResultHasDetails = true;
                 sawBody = true;
                 break;
+            }
             case 'SUB_START':
                 if (inSubscription)
                     invalid('nested SUB_START frame');
@@ -619,6 +676,32 @@ function encodeFrame(frame) {
             }
             return { frameType: FrameType.PUSH_RESULT, payload: w.finish() };
         }
+        case 'PUSH_RESULT_DETAILS': {
+            if (frame.clientCommitId.length === 0) {
+                throw new Error('PUSH_RESULT_DETAILS.clientCommitId must be non-empty');
+            }
+            if (frame.entries.length === 0) {
+                throw new Error('PUSH_RESULT_DETAILS must carry at least one entry');
+            }
+            const seen = new Set();
+            w.str(frame.clientCommitId);
+            w.u32(frame.entries.length);
+            for (const entry of frame.entries) {
+                if (!Number.isInteger(entry.opIndex) || entry.opIndex < 0) {
+                    throw new Error('PUSH_RESULT_DETAILS.opIndex must be non-negative');
+                }
+                if (seen.has(entry.opIndex)) {
+                    throw new Error('PUSH_RESULT_DETAILS.opIndex must be unique');
+                }
+                seen.add(entry.opIndex);
+                w.i32(entry.opIndex);
+                w.str(JSON.stringify(normalizeRejectionDetails(entry.details)));
+            }
+            return {
+                frameType: FrameType.PUSH_RESULT_DETAILS,
+                payload: w.finish(),
+            };
+        }
         case 'SUB_START': {
             w.str(frame.id);
             w.u8(SUB_STATUS_BYTES[frame.status]);

package/dist/rejection-details.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Bounded host rejection metadata carried by the additive
+ * `PUSH_RESULT_DETAILS` companion frame.
+ *
+ * Every member is deliberately code-like rather than free-form display text.
+ * A host opts values into replication by placing them here, so references MUST
+ * be non-sensitive identifiers that are safe for the authorized client to
+ * persist and render. Diagnostic prose stays in the ordinary `message` field.
+ */
+export interface RejectionDetails {
+    /** Schema/domain paths affected by the rejection. */
+    readonly fieldPaths?: readonly string[];
+    /** Stable machine reason, for example `outside_schedule_day`. */
+    readonly reason?: string;
+    /** Stable recovery action, for example `edit_fields`. */
+    readonly requiredAction?: string;
+    /** Explicitly safe, non-sensitive identifiers needed by recovery UI. */
+    readonly references?: Readonly<Record<string, string>>;
+}
+export declare const REJECTION_DETAILS_LIMITS: {
+    readonly maxEncodedBytes: 4096;
+    readonly maxFieldPaths: 32;
+    readonly maxFieldPathLength: 160;
+    readonly maxTokenLength: 96;
+    readonly maxReferences: 16;
+    readonly maxReferenceKeyLength: 64;
+    readonly maxReferenceValueBytes: 256;
+};
+/** Validate, clone, and normalize a host-supplied details object. */
+export declare function normalizeRejectionDetails(value: unknown): RejectionDetails;

package/dist/rejection-details.js

@@ -0,0 +1,109 @@
+export const REJECTION_DETAILS_LIMITS = {
+    maxEncodedBytes: 4_096,
+    maxFieldPaths: 32,
+    maxFieldPathLength: 160,
+    maxTokenLength: 96,
+    maxReferences: 16,
+    maxReferenceKeyLength: 64,
+    maxReferenceValueBytes: 256,
+};
+const FIELD_PATH = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const TOKEN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function recordOf(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('rejection details must be an object');
+    }
+    return value;
+}
+function stableToken(value, label, maxLength) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > maxLength ||
+        !TOKEN.test(value)) {
+        throw new Error(`${label} must be a lowercase stable token of at most ${maxLength} characters`);
+    }
+    return value;
+}
+/** Validate, clone, and normalize a host-supplied details object. */
+export function normalizeRejectionDetails(value) {
+    const source = recordOf(value);
+    const allowed = new Set([
+        'fieldPaths',
+        'reason',
+        'requiredAction',
+        'references',
+    ]);
+    for (const key of Object.keys(source)) {
+        if (!allowed.has(key)) {
+            throw new Error(`unknown rejection details member ${JSON.stringify(key)}`);
+        }
+    }
+    const normalized = {};
+    if (source.fieldPaths !== undefined) {
+        if (!Array.isArray(source.fieldPaths) ||
+            source.fieldPaths.length === 0 ||
+            source.fieldPaths.length > REJECTION_DETAILS_LIMITS.maxFieldPaths) {
+            throw new Error(`fieldPaths must contain 1-${REJECTION_DETAILS_LIMITS.maxFieldPaths} paths`);
+        }
+        const paths = [];
+        const seen = new Set();
+        for (const path of source.fieldPaths) {
+            if (typeof path !== 'string' ||
+                path.length === 0 ||
+                path.length > REJECTION_DETAILS_LIMITS.maxFieldPathLength ||
+                !FIELD_PATH.test(path)) {
+                throw new Error(`fieldPaths entries must be schema paths of at most ${REJECTION_DETAILS_LIMITS.maxFieldPathLength} characters`);
+            }
+            if (seen.has(path))
+                throw new Error(`duplicate field path ${JSON.stringify(path)}`);
+            seen.add(path);
+            paths.push(path);
+        }
+        normalized.fieldPaths = paths;
+    }
+    if (source.reason !== undefined) {
+        normalized.reason = stableToken(source.reason, 'reason', REJECTION_DETAILS_LIMITS.maxTokenLength);
+    }
+    if (source.requiredAction !== undefined) {
+        normalized.requiredAction = stableToken(source.requiredAction, 'requiredAction', REJECTION_DETAILS_LIMITS.maxTokenLength);
+    }
+    if (source.references !== undefined) {
+        const references = recordOf(source.references);
+        const keys = Object.keys(references).sort();
+        if (keys.length === 0 ||
+            keys.length > REJECTION_DETAILS_LIMITS.maxReferences) {
+            throw new Error(`references must contain 1-${REJECTION_DETAILS_LIMITS.maxReferences} entries`);
+        }
+        const safe = {};
+        for (const key of keys) {
+            stableToken(key, 'reference key', REJECTION_DETAILS_LIMITS.maxReferenceKeyLength);
+            const member = references[key];
+            if (typeof member !== 'string' ||
+                member.length === 0 ||
+                new TextEncoder().encode(member).length >
+                    REJECTION_DETAILS_LIMITS.maxReferenceValueBytes ||
+                member.trim() !== member ||
+                hasControlCharacter(member)) {
+                throw new Error(`reference values must be non-empty safe strings of at most ${REJECTION_DETAILS_LIMITS.maxReferenceValueBytes} encoded bytes`);
+            }
+            safe[key] = member;
+        }
+        normalized.references = safe;
+    }
+    if (Object.keys(normalized).length === 0) {
+        throw new Error('rejection details must contain at least one supported member');
+    }
+    const encodedBytes = new TextEncoder().encode(JSON.stringify(normalized)).length;
+    if (encodedBytes > REJECTION_DETAILS_LIMITS.maxEncodedBytes) {
+        throw new Error(`rejection details exceed ${REJECTION_DETAILS_LIMITS.maxEncodedBytes} encoded bytes`);
+    }
+    return normalized;
+}

package/dist/render.js

@@ -151,6 +151,28 @@ function renderFrame(frame) {
                     : {}),
                 results: frame.results.map(renderResult),
             };
+        case 'PUSH_RESULT_DETAILS':
+            return {
+                type: 'PUSH_RESULT_DETAILS',
+                clientCommitId: frame.clientCommitId,
+                entries: frame.entries.map((entry) => ({
+                    opIndex: entry.opIndex,
+                    details: {
+                        ...(entry.details.fieldPaths !== undefined
+                            ? { fieldPaths: [...entry.details.fieldPaths] }
+                            : {}),
+                        ...(entry.details.reason !== undefined
+                            ? { reason: entry.details.reason }
+                            : {}),
+                        ...(entry.details.requiredAction !== undefined
+                            ? { requiredAction: entry.details.requiredAction }
+                            : {}),
+                        ...(entry.details.references !== undefined
+                            ? { references: { ...entry.details.references } }
+                            : {}),
+                    },
+                })),
+            };
         case 'SUB_START':
             return {
                 type: 'SUB_START',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Core protocol types and shared utilities for the Syncular sync framework",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",

package/src/frames.ts

@@ -13,6 +13,7 @@ export const FrameType = {
   SEGMENT_INLINE: 0x15,
   SUB_END: 0x16,
   LEASE: 0x19,
+  PUSH_RESULT_DETAILS: 0x1b,
   ERROR: 0x1f,
 } as const;
 
@@ -36,6 +37,7 @@ export const RESPONSE_FRAME_TYPES: ReadonlySet<number> = new Set([
   FrameType.SEGMENT_INLINE,
   FrameType.SUB_END,
   FrameType.LEASE,
+  FrameType.PUSH_RESULT_DETAILS,
   FrameType.ERROR,
 ]);
 

package/src/index.ts

@@ -15,6 +15,7 @@ export * from './errors';
 export * from './frames';
 export * from './message';
 export * from './realtime';
+export * from './rejection-details';
 export * from './render';
 export * from './row-codec';
 export * from './segment';

package/src/message.ts

@@ -28,6 +28,10 @@ import {
   REQUEST_FRAME_TYPES,
   RESPONSE_FRAME_TYPES,
 } from './frames';
+import {
+  normalizeRejectionDetails,
+  type RejectionDetails,
+} from './rejection-details';
 import { decodeRowsSegment } from './segment';
 
 const MAGIC_BYTES = utf8Encode(SYNC_PACK_MAGIC);
@@ -119,6 +123,11 @@ export type PushOperationResult =
       code: string;
       message: string;
       retryable: boolean;
+      /**
+       * Host-safe structured metadata. It is emitted on the wire through the
+       * additive PUSH_RESULT_DETAILS companion frame, not the legacy record.
+       */
+      details?: RejectionDetails;
     };
 
 export interface PushResultFrame {
@@ -130,6 +139,16 @@ export interface PushResultFrame {
   results: PushOperationResult[];
 }
 
+/**
+ * Additive companion metadata for host validation errors. Older clients see
+ * this as an unknown frame and continue processing the normative PUSH_RESULT.
+ */
+export interface PushResultDetailsFrame {
+  type: 'PUSH_RESULT_DETAILS';
+  clientCommitId: string;
+  entries: Array<{ opIndex: number; details: RejectionDetails }>;
+}
+
 export interface SubStartFrame {
   type: 'SUB_START';
   id: string;
@@ -202,6 +221,7 @@ export type ResponseFrame =
   | RespHeaderFrame
   | LeaseFrame
   | PushResultFrame
+  | PushResultDetailsFrame
   | SubStartFrame
   | CommitFrame
   | SegmentRefFrame
@@ -397,6 +417,36 @@ function decodePushResult(r: ByteReader): PushResultFrame {
   };
 }
 
+function decodePushResultDetails(r: ByteReader): PushResultDetailsFrame {
+  const clientCommitId = r.str();
+  if (clientCommitId.length === 0) {
+    invalid('PUSH_RESULT_DETAILS.clientCommitId must be non-empty');
+  }
+  const count = r.u32();
+  if (count === 0) invalid('PUSH_RESULT_DETAILS must carry at least one entry');
+  const entries: PushResultDetailsFrame['entries'] = [];
+  const seen = new Set<number>();
+  for (let index = 0; index < count; index++) {
+    const opIndex = r.i32();
+    if (opIndex < 0 || seen.has(opIndex)) {
+      invalid(
+        'PUSH_RESULT_DETAILS opIndex values must be unique and non-negative',
+      );
+    }
+    seen.add(opIndex);
+    let details: RejectionDetails;
+    try {
+      details = normalizeRejectionDetails(JSON.parse(r.str()) as unknown);
+    } catch (error) {
+      invalid(
+        `invalid PUSH_RESULT_DETAILS.details: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    entries.push({ opIndex, details });
+  }
+  return { type: 'PUSH_RESULT_DETAILS', clientCommitId, entries };
+}
+
 function decodeSubStart(r: ByteReader): SubStartFrame {
   const id = r.str();
   const statusByte = r.u8();
@@ -581,6 +631,9 @@ function decodeResponseFrame(
     case FrameType.PUSH_RESULT:
       frame = decodePushResult(r);
       break;
+    case FrameType.PUSH_RESULT_DETAILS:
+      frame = decodePushResultDetails(r);
+      break;
     case FrameType.SUB_START:
       frame = decodeSubStart(r);
       break;
@@ -659,6 +712,8 @@ function validateResponseSequence(frames: readonly ResponseFrame[]): void {
   let subscriptionHasCommits = false;
   let subscriptionHasSegments = false;
   let errorSeen = false;
+  let lastPushResult: PushResultFrame | undefined;
+  let lastPushResultHasDetails = false;
   for (const frame of frames.slice(1)) {
     if (errorSeen) invalid('frames after ERROR (the next frame must be END)');
     switch (frame.type) {
@@ -674,8 +729,40 @@ function validateResponseSequence(frames: readonly ResponseFrame[]): void {
         break;
       case 'PUSH_RESULT':
         if (sawSubscription) invalid('PUSH_RESULT frame after SUB_START');
+        lastPushResult = frame;
+        lastPushResultHasDetails = false;
         sawBody = true;
         break;
+      case 'PUSH_RESULT_DETAILS': {
+        if (sawSubscription) {
+          invalid('PUSH_RESULT_DETAILS frame after SUB_START');
+        }
+        if (lastPushResult === undefined) {
+          invalid('PUSH_RESULT_DETAILS without a preceding PUSH_RESULT');
+        }
+        if (lastPushResultHasDetails) {
+          invalid('duplicate PUSH_RESULT_DETAILS companion');
+        }
+        if (
+          lastPushResult.clientCommitId !== frame.clientCommitId ||
+          lastPushResult.status !== 'rejected'
+        ) {
+          invalid(
+            'PUSH_RESULT_DETAILS does not match its rejected PUSH_RESULT',
+          );
+        }
+        const errorIndexes = new Set(
+          lastPushResult.results.flatMap((result) =>
+            result.status === 'error' ? [result.opIndex] : [],
+          ),
+        );
+        if (frame.entries.some((entry) => !errorIndexes.has(entry.opIndex))) {
+          invalid('PUSH_RESULT_DETAILS entry does not match an error result');
+        }
+        lastPushResultHasDetails = true;
+        sawBody = true;
+        break;
+      }
       case 'SUB_START':
         if (inSubscription) invalid('nested SUB_START frame');
         inSubscription = true;
@@ -838,6 +925,32 @@ function encodeFrame(frame: RequestFrame | ResponseFrame): {
       }
       return { frameType: FrameType.PUSH_RESULT, payload: w.finish() };
     }
+    case 'PUSH_RESULT_DETAILS': {
+      if (frame.clientCommitId.length === 0) {
+        throw new Error('PUSH_RESULT_DETAILS.clientCommitId must be non-empty');
+      }
+      if (frame.entries.length === 0) {
+        throw new Error('PUSH_RESULT_DETAILS must carry at least one entry');
+      }
+      const seen = new Set<number>();
+      w.str(frame.clientCommitId);
+      w.u32(frame.entries.length);
+      for (const entry of frame.entries) {
+        if (!Number.isInteger(entry.opIndex) || entry.opIndex < 0) {
+          throw new Error('PUSH_RESULT_DETAILS.opIndex must be non-negative');
+        }
+        if (seen.has(entry.opIndex)) {
+          throw new Error('PUSH_RESULT_DETAILS.opIndex must be unique');
+        }
+        seen.add(entry.opIndex);
+        w.i32(entry.opIndex);
+        w.str(JSON.stringify(normalizeRejectionDetails(entry.details)));
+      }
+      return {
+        frameType: FrameType.PUSH_RESULT_DETAILS,
+        payload: w.finish(),
+      };
+    }
     case 'SUB_START': {
       w.str(frame.id);
       w.u8(SUB_STATUS_BYTES[frame.status]);

package/src/rejection-details.ts

@@ -0,0 +1,183 @@
+/**
+ * Bounded host rejection metadata carried by the additive
+ * `PUSH_RESULT_DETAILS` companion frame.
+ *
+ * Every member is deliberately code-like rather than free-form display text.
+ * A host opts values into replication by placing them here, so references MUST
+ * be non-sensitive identifiers that are safe for the authorized client to
+ * persist and render. Diagnostic prose stays in the ordinary `message` field.
+ */
+export interface RejectionDetails {
+  /** Schema/domain paths affected by the rejection. */
+  readonly fieldPaths?: readonly string[];
+  /** Stable machine reason, for example `outside_schedule_day`. */
+  readonly reason?: string;
+  /** Stable recovery action, for example `edit_fields`. */
+  readonly requiredAction?: string;
+  /** Explicitly safe, non-sensitive identifiers needed by recovery UI. */
+  readonly references?: Readonly<Record<string, string>>;
+}
+
+export const REJECTION_DETAILS_LIMITS = {
+  maxEncodedBytes: 4_096,
+  maxFieldPaths: 32,
+  maxFieldPathLength: 160,
+  maxTokenLength: 96,
+  maxReferences: 16,
+  maxReferenceKeyLength: 64,
+  maxReferenceValueBytes: 256,
+} as const;
+
+const FIELD_PATH = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const TOKEN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) return true;
+  }
+  return false;
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('rejection details must be an object');
+  }
+  return value as Record<string, unknown>;
+}
+
+function stableToken(value: unknown, label: string, maxLength: number): string {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.length > maxLength ||
+    !TOKEN.test(value)
+  ) {
+    throw new Error(
+      `${label} must be a lowercase stable token of at most ${maxLength} characters`,
+    );
+  }
+  return value;
+}
+
+/** Validate, clone, and normalize a host-supplied details object. */
+export function normalizeRejectionDetails(value: unknown): RejectionDetails {
+  const source = recordOf(value);
+  const allowed = new Set([
+    'fieldPaths',
+    'reason',
+    'requiredAction',
+    'references',
+  ]);
+  for (const key of Object.keys(source)) {
+    if (!allowed.has(key)) {
+      throw new Error(
+        `unknown rejection details member ${JSON.stringify(key)}`,
+      );
+    }
+  }
+
+  const normalized: {
+    fieldPaths?: string[];
+    reason?: string;
+    requiredAction?: string;
+    references?: Record<string, string>;
+  } = {};
+
+  if (source.fieldPaths !== undefined) {
+    if (
+      !Array.isArray(source.fieldPaths) ||
+      source.fieldPaths.length === 0 ||
+      source.fieldPaths.length > REJECTION_DETAILS_LIMITS.maxFieldPaths
+    ) {
+      throw new Error(
+        `fieldPaths must contain 1-${REJECTION_DETAILS_LIMITS.maxFieldPaths} paths`,
+      );
+    }
+    const paths: string[] = [];
+    const seen = new Set<string>();
+    for (const path of source.fieldPaths) {
+      if (
+        typeof path !== 'string' ||
+        path.length === 0 ||
+        path.length > REJECTION_DETAILS_LIMITS.maxFieldPathLength ||
+        !FIELD_PATH.test(path)
+      ) {
+        throw new Error(
+          `fieldPaths entries must be schema paths of at most ${REJECTION_DETAILS_LIMITS.maxFieldPathLength} characters`,
+        );
+      }
+      if (seen.has(path))
+        throw new Error(`duplicate field path ${JSON.stringify(path)}`);
+      seen.add(path);
+      paths.push(path);
+    }
+    normalized.fieldPaths = paths;
+  }
+
+  if (source.reason !== undefined) {
+    normalized.reason = stableToken(
+      source.reason,
+      'reason',
+      REJECTION_DETAILS_LIMITS.maxTokenLength,
+    );
+  }
+  if (source.requiredAction !== undefined) {
+    normalized.requiredAction = stableToken(
+      source.requiredAction,
+      'requiredAction',
+      REJECTION_DETAILS_LIMITS.maxTokenLength,
+    );
+  }
+
+  if (source.references !== undefined) {
+    const references = recordOf(source.references);
+    const keys = Object.keys(references).sort();
+    if (
+      keys.length === 0 ||
+      keys.length > REJECTION_DETAILS_LIMITS.maxReferences
+    ) {
+      throw new Error(
+        `references must contain 1-${REJECTION_DETAILS_LIMITS.maxReferences} entries`,
+      );
+    }
+    const safe: Record<string, string> = {};
+    for (const key of keys) {
+      stableToken(
+        key,
+        'reference key',
+        REJECTION_DETAILS_LIMITS.maxReferenceKeyLength,
+      );
+      const member = references[key];
+      if (
+        typeof member !== 'string' ||
+        member.length === 0 ||
+        new TextEncoder().encode(member).length >
+          REJECTION_DETAILS_LIMITS.maxReferenceValueBytes ||
+        member.trim() !== member ||
+        hasControlCharacter(member)
+      ) {
+        throw new Error(
+          `reference values must be non-empty safe strings of at most ${REJECTION_DETAILS_LIMITS.maxReferenceValueBytes} encoded bytes`,
+        );
+      }
+      safe[key] = member;
+    }
+    normalized.references = safe;
+  }
+
+  if (Object.keys(normalized).length === 0) {
+    throw new Error(
+      'rejection details must contain at least one supported member',
+    );
+  }
+  const encodedBytes = new TextEncoder().encode(
+    JSON.stringify(normalized),
+  ).length;
+  if (encodedBytes > REJECTION_DETAILS_LIMITS.maxEncodedBytes) {
+    throw new Error(
+      `rejection details exceed ${REJECTION_DETAILS_LIMITS.maxEncodedBytes} encoded bytes`,
+    );
+  }
+  return normalized;
+}

package/src/render.ts

@@ -192,6 +192,28 @@ function renderFrame(frame: RequestFrame | ResponseFrame): JsonValue {
           : {}),
         results: frame.results.map(renderResult),
       };
+    case 'PUSH_RESULT_DETAILS':
+      return {
+        type: 'PUSH_RESULT_DETAILS',
+        clientCommitId: frame.clientCommitId,
+        entries: frame.entries.map((entry) => ({
+          opIndex: entry.opIndex,
+          details: {
+            ...(entry.details.fieldPaths !== undefined
+              ? { fieldPaths: [...entry.details.fieldPaths] }
+              : {}),
+            ...(entry.details.reason !== undefined
+              ? { reason: entry.details.reason }
+              : {}),
+            ...(entry.details.requiredAction !== undefined
+              ? { requiredAction: entry.details.requiredAction }
+              : {}),
+            ...(entry.details.references !== undefined
+              ? { references: { ...entry.details.references } }
+              : {}),
+          },
+        })),
+      };
     case 'SUB_START':
       return {
         type: 'SUB_START',