@canonmsg/backend-contracts 1.8.0 → 1.9.0

package/dist/bridgeLocal.d.ts

@@ -175,6 +175,111 @@ export interface BridgeLocalMethodContract {
     params: z.ZodType;
     result: z.ZodType;
 }
+/** A single tool-trail item forwarded raw; the bridge folds it into `blocks`. */
+export declare const BridgeStreamToolEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"tool">;
+    id: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        completed: "completed";
+        running: "running";
+        failed: "failed";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * A visible-text segment. `mode:'append'` concatenates onto the segment's
+ * running text; `mode:'replace'` overwrites it (the adapter already holds the
+ * full segment). The bridge rebuilds the bubble text from its text segments in
+ * sequence order, exactly as the core turn-output-controller does today.
+ */
+export declare const BridgeStreamTextEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    id: z.ZodString;
+    mode: z.ZodEnum<{
+        replace: "replace";
+        append: "append";
+    }>;
+    text: z.ZodString;
+}, z.core.$strip>;
+/** A thinking tick (onset or keepalive) — no content; keeps the bubble warm. */
+export declare const BridgeStreamThinkingEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"thinking">;
+}, z.core.$strip>;
+/**
+ * Final compose: the assembled reply text is written one last time (status
+ * settles to `streaming`) and the node is LEFT in place for the final-message
+ * handoff. Clearing is a separate `clear` event / `clearStreaming`.
+ */
+export declare const BridgeStreamFinalEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"final">;
+    text: z.ZodString;
+}, z.core.$strip>;
+/** Clear the streaming node (turn ended / interrupted). */
+export declare const BridgeStreamClearEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"clear">;
+}, z.core.$strip>;
+export declare const BridgeStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    id: z.ZodString;
+    mode: z.ZodEnum<{
+        replace: "replace";
+        append: "append";
+    }>;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool">;
+    id: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        completed: "completed";
+        running: "running";
+        failed: "failed";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"thinking">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"final">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"clear">;
+}, z.core.$strip>], "kind">;
+export type BridgeStreamEvent = z.infer<typeof BridgeStreamEventSchema>;
+export declare const BridgePublishStreamingEventParamsSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    turnId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    messageId: z.ZodOptional<z.ZodString>;
+    event: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        id: z.ZodString;
+        mode: z.ZodEnum<{
+            replace: "replace";
+            append: "append";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"tool">;
+        id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            completed: "completed";
+            running: "running";
+            failed: "failed";
+        }>>;
+        title: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"thinking">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"final">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"clear">;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
 export declare const BRIDGE_LOCAL_METHODS: {
     readonly hello: {
         readonly params: z.ZodObject<{
@@ -519,24 +624,24 @@ export declare const BRIDGE_LOCAL_METHODS: {
                 behavior: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 hasUnread: z.ZodOptional<z.ZodBoolean>;
                 lastMessage: z.ZodNullable<z.ZodObject<{
-                    text: z.ZodString;
+                    text: z.ZodNullable<z.ZodString>;
                     messageId: z.ZodOptional<z.ZodString>;
-                    senderId: z.ZodString;
-                    senderType: z.ZodEnum<{
+                    senderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    senderType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                         human: "human";
                         ai_agent: "ai_agent";
-                    }>;
-                    contentType: z.ZodOptional<z.ZodEnum<{
+                    }>>>;
+                    contentType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                         file: "file";
                         image: "image";
                         audio: "audio";
                         video: "video";
                         text: "text";
                         contact_card: "contact_card";
-                    }>>;
-                    timestamp: z.ZodString;
+                    }>>>;
+                    timestamp: z.ZodNullable<z.ZodString>;
                 }, z.core.$loose>>;
-                createdAt: z.ZodOptional<z.ZodString>;
+                createdAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             }, z.core.$loose>>;
         }, z.core.$strip>;
     };
@@ -867,6 +972,43 @@ export declare const BRIDGE_LOCAL_METHODS: {
             ok: z.ZodLiteral<true>;
         }, z.core.$strip>;
     };
+    readonly publishStreamingEvent: {
+        readonly params: z.ZodObject<{
+            conversationId: z.ZodString;
+            turnId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            messageId: z.ZodOptional<z.ZodString>;
+            event: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"text">;
+                id: z.ZodString;
+                mode: z.ZodEnum<{
+                    replace: "replace";
+                    append: "append";
+                }>;
+                text: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"tool">;
+                id: z.ZodString;
+                status: z.ZodOptional<z.ZodEnum<{
+                    completed: "completed";
+                    running: "running";
+                    failed: "failed";
+                }>>;
+                title: z.ZodOptional<z.ZodString>;
+                summary: z.ZodOptional<z.ZodString>;
+                detail: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"thinking">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"final">;
+                text: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"clear">;
+            }, z.core.$strip>], "kind">;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
     readonly publishRuntimeDescriptor: {
         readonly params: z.ZodObject<{
             descriptor: z.ZodRecord<z.ZodString, z.ZodUnknown>;

package/dist/bridgeLocal.js

@@ -153,6 +153,71 @@ const messageScoped = z.object({ conversationId: z.string(), messageId: z.string
  */
 const ServerTimestampSentinelSchema = z.object({ '.sv': z.literal('timestamp') });
 const EpochOrServerTimestampSchema = z.union([z.number(), ServerTimestampSentinelSchema]);
+// ─────────────────────────────────────────────────────────────────────────
+// W2-A4 REGION START — bridge-owned streaming assembly (raw event surface).
+// ADDITIVE: `publishStreamingEvent` lets a channel adapter forward RAW turn
+// events (a text segment begin/append/replace, a tool-trail item, a thinking
+// tick, a final compose, or a clear). The BRIDGE owns snapshot assembly, the
+// single write cadence, thinking keepalive, final compose, and node clear —
+// so adapters stop reimplementing turn-output-controller + a keepalive loop
+// (T1: they also stop swallowing the write failure). The pre-existing
+// snapshot `publishStreaming` (below) is UNTOUCHED — coding hosts still call
+// it via agent-host/runtime-writers.
+// ─────────────────────────────────────────────────────────────────────────
+/** A single tool-trail item forwarded raw; the bridge folds it into `blocks`. */
+export const BridgeStreamToolEventSchema = z.object({
+    kind: z.literal('tool'),
+    /** Stable block id (adapter-scoped, e.g. `tool:{turnId}`). */
+    id: z.string(),
+    status: z.enum(['running', 'completed', 'failed']).optional(),
+    title: z.string().optional(),
+    summary: z.string().optional(),
+    detail: z.string().optional(),
+});
+/**
+ * A visible-text segment. `mode:'append'` concatenates onto the segment's
+ * running text; `mode:'replace'` overwrites it (the adapter already holds the
+ * full segment). The bridge rebuilds the bubble text from its text segments in
+ * sequence order, exactly as the core turn-output-controller does today.
+ */
+export const BridgeStreamTextEventSchema = z.object({
+    kind: z.literal('text'),
+    /** Segment id (adapter-scoped, e.g. `text:{turnId}:{n}`). */
+    id: z.string(),
+    mode: z.enum(['append', 'replace']),
+    text: z.string(),
+});
+/** A thinking tick (onset or keepalive) — no content; keeps the bubble warm. */
+export const BridgeStreamThinkingEventSchema = z.object({
+    kind: z.literal('thinking'),
+});
+/**
+ * Final compose: the assembled reply text is written one last time (status
+ * settles to `streaming`) and the node is LEFT in place for the final-message
+ * handoff. Clearing is a separate `clear` event / `clearStreaming`.
+ */
+export const BridgeStreamFinalEventSchema = z.object({
+    kind: z.literal('final'),
+    text: z.string(),
+});
+/** Clear the streaming node (turn ended / interrupted). */
+export const BridgeStreamClearEventSchema = z.object({
+    kind: z.literal('clear'),
+});
+export const BridgeStreamEventSchema = z.discriminatedUnion('kind', [
+    BridgeStreamTextEventSchema,
+    BridgeStreamToolEventSchema,
+    BridgeStreamThinkingEventSchema,
+    BridgeStreamFinalEventSchema,
+    BridgeStreamClearEventSchema,
+]);
+export const BridgePublishStreamingEventParamsSchema = conversationScoped.extend({
+    /** New turnId resets the bridge's accumulation for this conversation. */
+    turnId: z.string().nullable().optional(),
+    messageId: z.string().optional(),
+    event: BridgeStreamEventSchema,
+});
+// W2-A4 REGION END — bridge-owned streaming assembly.
 export const BRIDGE_LOCAL_METHODS = {
     // §A lifecycle
     hello: { params: BridgeHelloParamsSchema, result: BridgeHelloResultSchema },
@@ -305,6 +370,12 @@ export const BRIDGE_LOCAL_METHODS = {
         result: OkResultSchema,
     },
     clearStreaming: { params: conversationScoped, result: OkResultSchema },
+    // W2-A4 additive: raw streaming events (bridge owns assembly/cadence/
+    // keepalive/final/clear). Coexists with the snapshot publishStreaming above.
+    publishStreamingEvent: {
+        params: BridgePublishStreamingEventParamsSchema,
+        result: OkResultSchema,
+    },
     // §B6 runtime presentation (adapter owns content, bridge publishes)
     publishRuntimeDescriptor: {
         params: z.object({

package/dist/cjs/bridgeLocal.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BridgeRpcResponseSchema = exports.BridgeRpcErrorSchema = exports.BridgeRpcNotificationSchema = exports.BridgeRpcRequestSchema = exports.BridgeRpcIdSchema = exports.BRIDGE_LOCAL_NOTIFICATION_FAMILIES = exports.BRIDGE_LOCAL_NOTIFICATION_NAMES = exports.BRIDGE_LOCAL_NOTIFICATIONS = exports.BRIDGE_LOCAL_METHOD_NAMES = exports.BRIDGE_LOCAL_METHODS = exports.BridgeGetAttachmentResultSchema = exports.BridgeGetAttachmentParamsSchema = exports.BridgeUploadMediaParamsSchema = exports.BridgeHitlStateSchema = exports.BridgeStatusResultSchema = exports.BridgeConnectionStateNotificationSchema = exports.BridgeReadyNotificationSchema = exports.BridgeUpstreamStateSchema = exports.BridgeHelloResultSchema = exports.BRIDGE_EVENT_CURSOR_SHAPE = exports.BridgeResyncSchema = exports.BridgeResyncReasonSchema = exports.BridgeHelloParamsSchema = exports.BridgeOkResultSchema = exports.BRIDGE_LOCAL_PROTOCOL_VERSION = void 0;
+exports.BridgeRpcResponseSchema = exports.BridgeRpcErrorSchema = exports.BridgeRpcNotificationSchema = exports.BridgeRpcRequestSchema = exports.BridgeRpcIdSchema = exports.BRIDGE_LOCAL_NOTIFICATION_FAMILIES = exports.BRIDGE_LOCAL_NOTIFICATION_NAMES = exports.BRIDGE_LOCAL_NOTIFICATIONS = exports.BRIDGE_LOCAL_METHOD_NAMES = exports.BRIDGE_LOCAL_METHODS = exports.BridgePublishStreamingEventParamsSchema = exports.BridgeStreamEventSchema = exports.BridgeStreamClearEventSchema = exports.BridgeStreamFinalEventSchema = exports.BridgeStreamThinkingEventSchema = exports.BridgeStreamTextEventSchema = exports.BridgeStreamToolEventSchema = exports.BridgeGetAttachmentResultSchema = exports.BridgeGetAttachmentParamsSchema = exports.BridgeUploadMediaParamsSchema = exports.BridgeHitlStateSchema = exports.BridgeStatusResultSchema = exports.BridgeConnectionStateNotificationSchema = exports.BridgeReadyNotificationSchema = exports.BridgeUpstreamStateSchema = exports.BridgeHelloResultSchema = exports.BRIDGE_EVENT_CURSOR_SHAPE = exports.BridgeResyncSchema = exports.BridgeResyncReasonSchema = exports.BridgeHelloParamsSchema = exports.BridgeOkResultSchema = exports.BRIDGE_LOCAL_PROTOCOL_VERSION = void 0;
 // Bridge ⇄ runtime-adapter LOCAL JSON-RPC contract v1 (types + schemas ONLY —
 // no runtime, no transport; Phase 4 builds the bridge against these).
 //
@@ -156,6 +156,71 @@ const messageScoped = zod_1.z.object({ conversationId: zod_1.z.string(), message
  */
 const ServerTimestampSentinelSchema = zod_1.z.object({ '.sv': zod_1.z.literal('timestamp') });
 const EpochOrServerTimestampSchema = zod_1.z.union([zod_1.z.number(), ServerTimestampSentinelSchema]);
+// ─────────────────────────────────────────────────────────────────────────
+// W2-A4 REGION START — bridge-owned streaming assembly (raw event surface).
+// ADDITIVE: `publishStreamingEvent` lets a channel adapter forward RAW turn
+// events (a text segment begin/append/replace, a tool-trail item, a thinking
+// tick, a final compose, or a clear). The BRIDGE owns snapshot assembly, the
+// single write cadence, thinking keepalive, final compose, and node clear —
+// so adapters stop reimplementing turn-output-controller + a keepalive loop
+// (T1: they also stop swallowing the write failure). The pre-existing
+// snapshot `publishStreaming` (below) is UNTOUCHED — coding hosts still call
+// it via agent-host/runtime-writers.
+// ─────────────────────────────────────────────────────────────────────────
+/** A single tool-trail item forwarded raw; the bridge folds it into `blocks`. */
+exports.BridgeStreamToolEventSchema = zod_1.z.object({
+    kind: zod_1.z.literal('tool'),
+    /** Stable block id (adapter-scoped, e.g. `tool:{turnId}`). */
+    id: zod_1.z.string(),
+    status: zod_1.z.enum(['running', 'completed', 'failed']).optional(),
+    title: zod_1.z.string().optional(),
+    summary: zod_1.z.string().optional(),
+    detail: zod_1.z.string().optional(),
+});
+/**
+ * A visible-text segment. `mode:'append'` concatenates onto the segment's
+ * running text; `mode:'replace'` overwrites it (the adapter already holds the
+ * full segment). The bridge rebuilds the bubble text from its text segments in
+ * sequence order, exactly as the core turn-output-controller does today.
+ */
+exports.BridgeStreamTextEventSchema = zod_1.z.object({
+    kind: zod_1.z.literal('text'),
+    /** Segment id (adapter-scoped, e.g. `text:{turnId}:{n}`). */
+    id: zod_1.z.string(),
+    mode: zod_1.z.enum(['append', 'replace']),
+    text: zod_1.z.string(),
+});
+/** A thinking tick (onset or keepalive) — no content; keeps the bubble warm. */
+exports.BridgeStreamThinkingEventSchema = zod_1.z.object({
+    kind: zod_1.z.literal('thinking'),
+});
+/**
+ * Final compose: the assembled reply text is written one last time (status
+ * settles to `streaming`) and the node is LEFT in place for the final-message
+ * handoff. Clearing is a separate `clear` event / `clearStreaming`.
+ */
+exports.BridgeStreamFinalEventSchema = zod_1.z.object({
+    kind: zod_1.z.literal('final'),
+    text: zod_1.z.string(),
+});
+/** Clear the streaming node (turn ended / interrupted). */
+exports.BridgeStreamClearEventSchema = zod_1.z.object({
+    kind: zod_1.z.literal('clear'),
+});
+exports.BridgeStreamEventSchema = zod_1.z.discriminatedUnion('kind', [
+    exports.BridgeStreamTextEventSchema,
+    exports.BridgeStreamToolEventSchema,
+    exports.BridgeStreamThinkingEventSchema,
+    exports.BridgeStreamFinalEventSchema,
+    exports.BridgeStreamClearEventSchema,
+]);
+exports.BridgePublishStreamingEventParamsSchema = conversationScoped.extend({
+    /** New turnId resets the bridge's accumulation for this conversation. */
+    turnId: zod_1.z.string().nullable().optional(),
+    messageId: zod_1.z.string().optional(),
+    event: exports.BridgeStreamEventSchema,
+});
+// W2-A4 REGION END — bridge-owned streaming assembly.
 exports.BRIDGE_LOCAL_METHODS = {
     // §A lifecycle
     hello: { params: exports.BridgeHelloParamsSchema, result: exports.BridgeHelloResultSchema },
@@ -308,6 +373,12 @@ exports.BRIDGE_LOCAL_METHODS = {
         result: OkResultSchema,
     },
     clearStreaming: { params: conversationScoped, result: OkResultSchema },
+    // W2-A4 additive: raw streaming events (bridge owns assembly/cadence/
+    // keepalive/final/clear). Coexists with the snapshot publishStreaming above.
+    publishStreamingEvent: {
+        params: exports.BridgePublishStreamingEventParamsSchema,
+        result: OkResultSchema,
+    },
     // §B6 runtime presentation (adapter owns content, bridge publishes)
     publishRuntimeDescriptor: {
         params: zod_1.z.object({

package/dist/cjs/restEndpoints.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UploadMediaResponseSchema = exports.UploadMediaRequestSchema = exports.SetStreamingRequestSchema = exports.SetTypingRequestSchema = exports.ResolveAdmissionResponseSchema = exports.ResolveAdmissionRequestSchema = exports.ContactsResponseSchema = exports.CreateContactRequestResponseSchema = exports.CreateContactRequestRequestSchema = exports.CreateConversationResponseSchema = exports.CreateConversationRequestSchema = exports.MessagesPageResponseSchema = exports.GetMessagesQuerySchema = exports.ConversationsResponseSchema = exports.UpdateDispositionRequestSchema = exports.MarkReadResponseSchema = exports.DeleteMessageResponseSchema = exports.ForwardMessageResponseSchema = exports.ForwardMessageRequestSchema = exports.ReactResponseSchema = exports.ReactRequestSchema = exports.SendMessageResponseSchema = exports.SendMessageRequestSchema = exports.RestSessionSelectionSchema = exports.RestContactSchema = exports.RestConversationSchema = exports.RestMessageSchema = exports.RestOkResponseSchema = void 0;
+exports.UploadMediaResponseSchema = exports.UploadMediaRequestSchema = exports.SetStreamingRequestSchema = exports.SetTypingRequestSchema = exports.ResolveAdmissionResponseSchema = exports.ResolveAdmissionRequestSchema = exports.ContactsResponseSchema = exports.CreateContactRequestResponseSchema = exports.CreateContactRequestRequestSchema = exports.CreateConversationResponseSchema = exports.CreateConversationRequestSchema = exports.MessagesPageResponseSchema = exports.GetMessagesQuerySchema = exports.ConversationsResponseSchema = exports.UpdateDispositionRequestSchema = exports.MarkReadResponseSchema = exports.DeleteMessageResponseSchema = exports.ForwardMessageResponseSchema = exports.ForwardMessageRequestSchema = exports.ReactResponseSchema = exports.ReactRequestSchema = exports.SendMessageResponseSchema = exports.SendMessageRequestSchema = exports.RestSessionSelectionSchema = exports.RestContactSchema = exports.RestConversationSchema = exports.RestConversationLastMessageSchema = exports.RestMessageSchema = exports.RestOkResponseSchema = void 0;
 // Wire contract v1 — request/response schemas for the agent-facing "Canon op"
 // REST surface the bridge proxies (bridge-local-api.md §B).
 //
@@ -20,6 +20,30 @@ exports.RestOkResponseSchema = zod_1.z.looseObject({
 exports.RestMessageSchema = message_js_1.SerializedMessageSchema.extend({
     deleted: zod_1.z.boolean().optional(),
 });
+/**
+ * STRICT WRITES, TOLERANT READS: this is a READ schema over live production
+ * data, so it must describe what Firestore actually holds — not what today's
+ * writers produce. The GET /conversations serializer
+ * (functions/src/api/getConversations.ts) passes `lastMessage` fields through
+ * from the conversation doc, and legacy rows (pre-refactor writes,
+ * deleted-message repair) hold explicit nulls:
+ * - `text` is serialized `?? null` and `timestamp` as
+ *   `?.toDate?.()?.toISOString() ?? null` — both emit null by construction.
+ * - `senderId` / `senderType` / `contentType` are raw pass-throughs; live
+ *   rows exist with all three null (the getConversations "ghost fix" comment
+ *   acknowledges null senderId).
+ * - conversation `createdAt` is also serialized `?? null`.
+ * Writers (onMessageCreated / deletedMessageRepair) stay strict — they always
+ * produce the full shape; only the read contract admits the legacy nulls.
+ */
+exports.RestConversationLastMessageSchema = zod_1.z.looseObject({
+    text: zod_1.z.string().nullable(),
+    messageId: zod_1.z.string().optional(),
+    senderId: zod_1.z.string().nullable().optional(),
+    senderType: zod_1.z.enum(['human', 'ai_agent']).nullable().optional(),
+    contentType: message_js_1.SerializedContentTypeSchema.nullable().optional(),
+    timestamp: zod_1.z.string().nullable(),
+});
 exports.RestConversationSchema = zod_1.z.looseObject({
     id: zod_1.z.string(),
     type: zod_1.z.enum(['direct', 'group']),
@@ -30,15 +54,8 @@ exports.RestConversationSchema = zod_1.z.looseObject({
     /** Resolved agent behavior policy — opaque pass-through. */
     behavior: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
     hasUnread: zod_1.z.boolean().optional(),
-    lastMessage: zod_1.z.looseObject({
-        text: zod_1.z.string(),
-        messageId: zod_1.z.string().optional(),
-        senderId: zod_1.z.string(),
-        senderType: zod_1.z.enum(['human', 'ai_agent']),
-        contentType: message_js_1.SerializedContentTypeSchema.optional(),
-        timestamp: zod_1.z.string(),
-    }).nullable(),
-    createdAt: zod_1.z.string().optional(),
+    lastMessage: exports.RestConversationLastMessageSchema.nullable(),
+    createdAt: zod_1.z.string().nullable().optional(),
 });
 exports.RestContactSchema = zod_1.z.object({
     id: zod_1.z.string(),

package/dist/cjs/sseEvents.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SseEventEnvelopeSchema = exports.SSE_EVENT_FAMILY_BY_TYPE = exports.SseEventFamilySchema = exports.SSE_EVENT_FAMILIES = exports.SSE_EVENT_PAYLOAD_SCHEMAS = exports.SseEventTypeSchema = exports.SSE_EVENT_TYPES = exports.SseVoiceSessionEventPayloadSchema = exports.SseVoiceSessionSchema = exports.SseRuntimeControlPayloadSchema = exports.SseRuntimeControlKindSchema = exports.SseTurnUpdatedPayloadSchema = exports.SseRuntimeUpdatedPayloadSchema = exports.SsePresencePayloadSchema = exports.SseTypingPayloadSchema = exports.SseContactRemovedPayloadSchema = exports.SseContactPayloadSchema = exports.SseContactRequestPayloadSchema = exports.SseConversationUpdatedPayloadSchema = exports.SseMembershipChangeSchema = exports.SseMessageDeletedPayloadSchema = exports.SseMessageUpdatedPayloadSchema = exports.SseMessageCreatedPayloadSchema = exports.SseProvenanceSchema = exports.SseTurnDispatchSchema = exports.SseSelfContextSchema = exports.SseErrorPayloadSchema = exports.SseReplayExpiredPayloadSchema = exports.SseHeartbeatPayloadSchema = exports.SseAgentContextPayloadSchema = exports.SseConnectedPayloadSchema = exports.SseAccessPolicySchema = void 0;
+exports.SseEventEnvelopeSchema = exports.SSE_EVENT_FAMILY_BY_TYPE = exports.SseEventFamilySchema = exports.SSE_EVENT_FAMILIES = exports.SSE_EVENT_PAYLOAD_SCHEMAS = exports.SseEventTypeSchema = exports.SSE_EVENT_TYPES = exports.SseVoiceSessionEventPayloadSchema = exports.SseVoiceSessionSchema = exports.SseRuntimeControlPayloadSchema = exports.SseRuntimeControlKindSchema = exports.SsePresencePayloadSchema = exports.SseTypingPayloadSchema = exports.SseContactRemovedPayloadSchema = exports.SseContactPayloadSchema = exports.SseContactRequestPayloadSchema = exports.SseConversationUpdatedPayloadSchema = exports.SseMembershipChangeSchema = exports.SseMessageDeletedPayloadSchema = exports.SseMessageUpdatedPayloadSchema = exports.SseMessageCreatedPayloadSchema = exports.SseProvenanceSchema = exports.SseTurnDispatchSchema = exports.SseSelfContextSchema = exports.SseErrorPayloadSchema = exports.SseReplayExpiredPayloadSchema = exports.SseHeartbeatPayloadSchema = exports.SseAgentContextPayloadSchema = exports.SseConnectedPayloadSchema = exports.SseAccessPolicySchema = void 0;
 // Wire contract v1 — SSE event envelope + per-family payload schemas.
 //
 // Grounded in what stream-service ACTUALLY emits (stream-service/src/stream.ts
@@ -142,20 +142,9 @@ exports.SsePresencePayloadSchema = zod_1.z.object({
     lastSeen: zod_1.z.string().optional(),
 });
 // ── Runtime / turn family ──────────────────────────────────────────────
-/** Aggregated RTDB runtime snapshot — nodes are passed through opaquely. */
-exports.SseRuntimeUpdatedPayloadSchema = zod_1.z.object({
-    conversationId: zod_1.z.string(),
-    agentId: zod_1.z.string(),
-    runtime: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
-    runtimeInfo: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
-    sessionState: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
-    sessionConfig: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
-});
-exports.SseTurnUpdatedPayloadSchema = zod_1.z.object({
-    conversationId: zod_1.z.string(),
-    agentId: zod_1.z.string(),
-    turn: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
-});
+// `runtime.updated` / `turn.updated` were retired 2026-07 (zero consumers;
+// the bridge reads RTDB directly). `runtime.control` remains — it is the
+// planned event-push control transport (housecleaning plan §6 W2-A2).
 exports.SseRuntimeControlKindSchema = zod_1.z.enum([
     'session',
     'signal',
@@ -219,8 +208,6 @@ exports.SSE_EVENT_TYPES = [
     'contact.removed',
     'typing',
     'presence',
-    'runtime.updated',
-    'turn.updated',
     'runtime.control',
     'voice.session.started',
     'voice.session.ended',
@@ -244,8 +231,6 @@ exports.SSE_EVENT_PAYLOAD_SCHEMAS = {
     'contact.removed': exports.SseContactRemovedPayloadSchema,
     'typing': exports.SseTypingPayloadSchema,
     'presence': exports.SsePresencePayloadSchema,
-    'runtime.updated': exports.SseRuntimeUpdatedPayloadSchema,
-    'turn.updated': exports.SseTurnUpdatedPayloadSchema,
     'runtime.control': exports.SseRuntimeControlPayloadSchema,
     'voice.session.started': exports.SseVoiceSessionEventPayloadSchema,
     'voice.session.ended': exports.SseVoiceSessionEventPayloadSchema,
@@ -279,8 +264,6 @@ exports.SSE_EVENT_FAMILY_BY_TYPE = {
     'contact.removed': 'contacts',
     'typing': 'typing_presence',
     'presence': 'typing_presence',
-    'runtime.updated': 'runtime_turn',
-    'turn.updated': 'runtime_turn',
     'runtime.control': 'runtime_turn',
     'voice.session.started': 'voice',
     'voice.session.ended': 'voice',

package/dist/restEndpoints.d.ts

@@ -78,6 +78,41 @@ export declare const RestMessageSchema: z.ZodObject<{
     deleted: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type RestMessage = z.infer<typeof RestMessageSchema>;
+/**
+ * STRICT WRITES, TOLERANT READS: this is a READ schema over live production
+ * data, so it must describe what Firestore actually holds — not what today's
+ * writers produce. The GET /conversations serializer
+ * (functions/src/api/getConversations.ts) passes `lastMessage` fields through
+ * from the conversation doc, and legacy rows (pre-refactor writes,
+ * deleted-message repair) hold explicit nulls:
+ * - `text` is serialized `?? null` and `timestamp` as
+ *   `?.toDate?.()?.toISOString() ?? null` — both emit null by construction.
+ * - `senderId` / `senderType` / `contentType` are raw pass-throughs; live
+ *   rows exist with all three null (the getConversations "ghost fix" comment
+ *   acknowledges null senderId).
+ * - conversation `createdAt` is also serialized `?? null`.
+ * Writers (onMessageCreated / deletedMessageRepair) stay strict — they always
+ * produce the full shape; only the read contract admits the legacy nulls.
+ */
+export declare const RestConversationLastMessageSchema: z.ZodObject<{
+    text: z.ZodNullable<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    senderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    senderType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        human: "human";
+        ai_agent: "ai_agent";
+    }>>>;
+    contentType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        file: "file";
+        image: "image";
+        audio: "audio";
+        video: "video";
+        text: "text";
+        contact_card: "contact_card";
+    }>>>;
+    timestamp: z.ZodNullable<z.ZodString>;
+}, z.core.$loose>;
+export type RestConversationLastMessage = z.infer<typeof RestConversationLastMessageSchema>;
 export declare const RestConversationSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
@@ -91,24 +126,24 @@ export declare const RestConversationSchema: z.ZodObject<{
     behavior: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     hasUnread: z.ZodOptional<z.ZodBoolean>;
     lastMessage: z.ZodNullable<z.ZodObject<{
-        text: z.ZodString;
+        text: z.ZodNullable<z.ZodString>;
         messageId: z.ZodOptional<z.ZodString>;
-        senderId: z.ZodString;
-        senderType: z.ZodEnum<{
+        senderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        senderType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             human: "human";
             ai_agent: "ai_agent";
-        }>;
-        contentType: z.ZodOptional<z.ZodEnum<{
+        }>>>;
+        contentType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             file: "file";
             image: "image";
             audio: "audio";
             video: "video";
             text: "text";
             contact_card: "contact_card";
-        }>>;
-        timestamp: z.ZodString;
+        }>>>;
+        timestamp: z.ZodNullable<z.ZodString>;
     }, z.core.$loose>>;
-    createdAt: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
 export type RestConversation = z.infer<typeof RestConversationSchema>;
 export declare const RestContactSchema: z.ZodObject<{
@@ -230,24 +265,24 @@ export declare const ConversationsResponseSchema: z.ZodObject<{
         behavior: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         hasUnread: z.ZodOptional<z.ZodBoolean>;
         lastMessage: z.ZodNullable<z.ZodObject<{
-            text: z.ZodString;
+            text: z.ZodNullable<z.ZodString>;
             messageId: z.ZodOptional<z.ZodString>;
-            senderId: z.ZodString;
-            senderType: z.ZodEnum<{
+            senderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            senderType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 human: "human";
                 ai_agent: "ai_agent";
-            }>;
-            contentType: z.ZodOptional<z.ZodEnum<{
+            }>>>;
+            contentType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 file: "file";
                 image: "image";
                 audio: "audio";
                 video: "video";
                 text: "text";
                 contact_card: "contact_card";
-            }>>;
-            timestamp: z.ZodString;
+            }>>>;
+            timestamp: z.ZodNullable<z.ZodString>;
         }, z.core.$loose>>;
-        createdAt: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$loose>>;
 }, z.core.$strip>;
 export type ConversationsResponse = z.infer<typeof ConversationsResponseSchema>;

package/dist/restEndpoints.js

@@ -17,6 +17,30 @@ export const RestOkResponseSchema = z.looseObject({
 export const RestMessageSchema = SerializedMessageSchema.extend({
     deleted: z.boolean().optional(),
 });
+/**
+ * STRICT WRITES, TOLERANT READS: this is a READ schema over live production
+ * data, so it must describe what Firestore actually holds — not what today's
+ * writers produce. The GET /conversations serializer
+ * (functions/src/api/getConversations.ts) passes `lastMessage` fields through
+ * from the conversation doc, and legacy rows (pre-refactor writes,
+ * deleted-message repair) hold explicit nulls:
+ * - `text` is serialized `?? null` and `timestamp` as
+ *   `?.toDate?.()?.toISOString() ?? null` — both emit null by construction.
+ * - `senderId` / `senderType` / `contentType` are raw pass-throughs; live
+ *   rows exist with all three null (the getConversations "ghost fix" comment
+ *   acknowledges null senderId).
+ * - conversation `createdAt` is also serialized `?? null`.
+ * Writers (onMessageCreated / deletedMessageRepair) stay strict — they always
+ * produce the full shape; only the read contract admits the legacy nulls.
+ */
+export const RestConversationLastMessageSchema = z.looseObject({
+    text: z.string().nullable(),
+    messageId: z.string().optional(),
+    senderId: z.string().nullable().optional(),
+    senderType: z.enum(['human', 'ai_agent']).nullable().optional(),
+    contentType: SerializedContentTypeSchema.nullable().optional(),
+    timestamp: z.string().nullable(),
+});
 export const RestConversationSchema = z.looseObject({
     id: z.string(),
     type: z.enum(['direct', 'group']),
@@ -27,15 +51,8 @@ export const RestConversationSchema = z.looseObject({
     /** Resolved agent behavior policy — opaque pass-through. */
     behavior: z.record(z.string(), z.unknown()).optional(),
     hasUnread: z.boolean().optional(),
-    lastMessage: z.looseObject({
-        text: z.string(),
-        messageId: z.string().optional(),
-        senderId: z.string(),
-        senderType: z.enum(['human', 'ai_agent']),
-        contentType: SerializedContentTypeSchema.optional(),
-        timestamp: z.string(),
-    }).nullable(),
-    createdAt: z.string().optional(),
+    lastMessage: RestConversationLastMessageSchema.nullable(),
+    createdAt: z.string().nullable().optional(),
 });
 export const RestContactSchema = z.object({
     id: z.string(),