@kici-dev/engine 0.1.27 → 0.3.0

package/dist/protocol/messages/browser.js

@@ -1,6 +1,8 @@
 import "../../rolldown-runtime-ClRpJifh.js";
 import { browserJobContextSchema, browserRunEventSchema } from "./run-events.js";
 import { browserEventLogPayloadChunkSchema } from "./dashboard.js";
+import { LogStream } from "./log-stream.js";
+import { OrchLogPhase } from "./platform-orchestrator.js";
 import { z } from "zod";
 //#region src/protocol/messages/browser.ts
 /**
@@ -38,6 +40,24 @@ const browserLogUnsubscribeSchema = z.object({
 	jobId: z.string(),
 	stepIndex: z.number()
 });
+/**
+* Browser subscribes to live orchestration/provisioning logs for a job.
+*
+* Keyed by `(runId, jobId)` — no `stepIndex` (orch logs are job-level, not
+* per-step). On subscribe the Platform backfills persisted history via the
+* `dashboard.orch.logs` RPC, then streams live `orch-log.lines`.
+*/
+const browserOrchLogSubscribeSchema = z.object({
+	type: z.literal("orch-log.subscribe"),
+	runId: z.string(),
+	jobId: z.string()
+});
+/** Browser unsubscribes from live orchestration/provisioning logs for a job. */
+const browserOrchLogUnsubscribeSchema = z.object({
+	type: z.literal("orch-log.unsubscribe"),
+	runId: z.string(),
+	jobId: z.string()
+});
 /** Browser subscribes to org-level status updates (run/job/step status changes). */
 const browserStatusSubscribeSchema = z.object({
 	type: z.literal("status.subscribe"),
@@ -71,6 +91,8 @@ const browserToPlatformMessageSchema = z.discriminatedUnion("type", [
 	browserAuthRefreshSchema,
 	browserLogSubscribeSchema,
 	browserLogUnsubscribeSchema,
+	browserOrchLogSubscribeSchema,
+	browserOrchLogUnsubscribeSchema,
 	browserStatusSubscribeSchema,
 	browserStatusUnsubscribeSchema,
 	browserEventLogPayloadFetchSchema,
@@ -94,7 +116,35 @@ const browserLogLinesSchema = z.object({
 	stepIndex: z.number(),
 	lines: z.array(z.string()),
 	/** Total line count (cumulative offset so browser knows position). */
-	lineCount: z.number()
+	lineCount: z.number(),
+	/**
+	* Which stream these lines came from. Absent when the producing orchestrator
+	* does not report one; read as `stdout`.
+	*/
+	stream: LogStream.optional()
+});
+/**
+* Platform sends orchestration/provisioning log lines for a subscribed job.
+*
+* Delivered in two forms over the same message:
+* - **Backfill** (on subscribe): `lines` are the persisted JSONL strings from
+*   the `dashboard.orch.logs` RPC (each carrying its own `phase`/`ts`), so the
+*   top-level `phase`/`ts` are omitted.
+* - **Live** (streamed after backfill): `lines` are raw message strings for a
+*   single `phase` at timestamp `ts`.
+*
+* The dashboard normalizes both by attempting to JSON-parse each line and
+* falling back to the envelope `phase`/`ts`, and dedups on `(ts, phase,
+* message)` so an overlap between the backfill snapshot and the first live
+* chunk is not double-appended.
+*/
+const browserOrchLogLinesSchema = z.object({
+	type: z.literal("orch-log.lines"),
+	runId: z.string(),
+	jobId: z.string(),
+	phase: OrchLogPhase.optional(),
+	lines: z.array(z.string()),
+	ts: z.number().optional()
 });
 /** Platform notifies browser that lines were dropped due to backpressure. */
 const browserGapSchema = z.object({
@@ -206,6 +256,7 @@ const platformToBrowserMessageSchema = z.discriminatedUnion("type", [
 	browserAuthSuccessSchema,
 	browserAuthFailureSchema,
 	browserLogLinesSchema,
+	browserOrchLogLinesSchema,
 	browserGapSchema,
 	browserLogStreamTerminatedSchema,
 	browserRunStatusSchema,
@@ -220,6 +271,6 @@ const platformToBrowserMessageSchema = z.discriminatedUnion("type", [
 	browserEventLogPayloadChunkSchema
 ]);
 //#endregion
-export { browserAuthFailureSchema, browserAuthRefreshSchema, browserAuthRequestSchema, browserAuthSuccessSchema, browserErrorSchema, browserEventLogPayloadFetchSchema, browserGapSchema, browserJobNewSchema, browserJobStatusSchema, browserLogLinesSchema, browserLogStreamTerminatedReason, browserLogStreamTerminatedSchema, browserLogSubscribeSchema, browserLogUnsubscribeSchema, browserPingSchema, browserPongSchema, browserRunNewSchema, browserRunStatusSchema, browserStatusSubscribeSchema, browserStatusUnsubscribeSchema, browserStepStatusSchema, browserToPlatformMessageSchema, platformToBrowserMessageSchema };
+export { browserAuthFailureSchema, browserAuthRefreshSchema, browserAuthRequestSchema, browserAuthSuccessSchema, browserErrorSchema, browserEventLogPayloadFetchSchema, browserGapSchema, browserJobNewSchema, browserJobStatusSchema, browserLogLinesSchema, browserLogStreamTerminatedReason, browserLogStreamTerminatedSchema, browserLogSubscribeSchema, browserLogUnsubscribeSchema, browserOrchLogLinesSchema, browserOrchLogSubscribeSchema, browserOrchLogUnsubscribeSchema, browserPingSchema, browserPongSchema, browserRunNewSchema, browserRunStatusSchema, browserStatusSubscribeSchema, browserStatusUnsubscribeSchema, browserStepStatusSchema, browserToPlatformMessageSchema, platformToBrowserMessageSchema };
 
 //# sourceMappingURL=browser.js.map

package/dist/protocol/messages/capabilities.d.ts

@@ -1,16 +1,24 @@
 /**
- * Orchestrator capability negotiation schemas.
+ * Capability negotiation schemas — bidirectional.
  *
  * Modeled after peerCapabilitiesSchema in peer.ts.
- * See CONTEXT.md through for design decisions.
  *
- * Direction: orchestrator → Platform only. The Platform is always at the latest version
- * (centrally deployed), so Platform capabilities are unnecessary. The Platform checks
- * orchestrator capabilities before sending feature-gated messages.
+ * Two directions, each advertised as the sending side learns what the other
+ * understands:
+ * - **orchestrator → Platform** (`orchCapabilitiesSchema`, sent in `auth.request`):
+ *   the Platform pre-flight-checks orchestrator capabilities before sending
+ *   feature-gated messages (e.g. the dashboard-request manifest).
+ * - **Platform → orchestrator** (`platformCapabilitiesSchema`, advertised once
+ *   after auth): a self-hosted orchestrator can run *ahead* of the hosted
+ *   Platform, so it pre-flight-checks its own feature-gated sends against what
+ *   the Platform advertises — surfacing a diagnosable capability gap instead of
+ *   firing a frame the Platform would drop.
  *
- * Pattern: Each field indicates support for an optional protocol feature.
- * Missing fields default to unsupported for backward compatibility.
- * Schema uses .passthrough() so newer orchestrators sending unknown flags don't get stripped.
+ * Pattern (both directions): each field indicates support for an optional
+ * protocol feature. Missing fields default to unsupported for backward
+ * compatibility; `.passthrough()` preserves unknown flags from a newer peer.
+ * A peer that never advertises at all is treated as "unknown" (optimistic),
+ * never as "supports nothing".
  */
 import { z } from 'zod';
 /** Orchestrator role in a cluster topology. */
@@ -28,36 +36,48 @@ export declare const orchCapabilitiesSchema: z.ZodObject<{
         coordinator: "coordinator";
         worker: "worker";
     }>>;
-    dashboardWrites: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-        "secrets.set": "secrets.set";
-        "secrets.delete": "secrets.delete";
-        "secrets.scope.create": "secrets.scope.create";
-        "secrets.scope.rename": "secrets.scope.rename";
-        "secrets.scope.delete": "secrets.scope.delete";
-        "variables.set": "variables.set";
-        "variables.delete": "variables.delete";
-        "contexts.create": "contexts.create";
-        "contexts.update": "contexts.update";
-        "contexts.test_access.set": "contexts.test_access.set";
-        "contexts.delete": "contexts.delete";
-        "contexts.bindings.set": "contexts.bindings.set";
-        "contexts.source_overrides.set": "contexts.source_overrides.set";
-        "contexts.source_overrides.delete": "contexts.source_overrides.delete";
-        "held_runs.approve": "held_runs.approve";
-        "held_runs.reject": "held_runs.reject";
-        "event_dlq.retry": "event_dlq.retry";
-        "event_dlq.discard": "event_dlq.discard";
+    dashboardWrites: z.ZodOptional<z.ZodPipe<z.ZodRecord<z.ZodEnum<{
         "attestations.retry": "attestations.retry";
-        "registration.disable": "registration.disable";
-        "registration.delete": "registration.delete";
-        "global_workflows.update": "global_workflows.update";
         "backends.sync": "backends.sync";
         "backends.sync_one": "backends.sync_one";
         "backends.test": "backends.test";
+        "contexts.bindings.set": "contexts.bindings.set";
+        "contexts.create": "contexts.create";
+        "contexts.delete": "contexts.delete";
+        "contexts.source_overrides.delete": "contexts.source_overrides.delete";
+        "contexts.source_overrides.set": "contexts.source_overrides.set";
+        "contexts.test_access.set": "contexts.test_access.set";
+        "contexts.update": "contexts.update";
+        "event_dlq.discard": "event_dlq.discard";
+        "event_dlq.retry": "event_dlq.retry";
         "fleet.host.declare": "fleet.host.declare";
         "fleet.host.remove": "fleet.host.remove";
-    }> & z.core.$partial, z.ZodBoolean>>;
+        "global_workflows.update": "global_workflows.update";
+        "held_runs.approve": "held_runs.approve";
+        "held_runs.reject": "held_runs.reject";
+        "registration.delete": "registration.delete";
+        "registration.disable": "registration.disable";
+        "secrets.delete": "secrets.delete";
+        "secrets.scope.create": "secrets.scope.create";
+        "secrets.scope.delete": "secrets.scope.delete";
+        "secrets.scope.rename": "secrets.scope.rename";
+        "secrets.set": "secrets.set";
+        "variables.delete": "variables.delete";
+        "variables.set": "variables.set";
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+        disabled: "disabled";
+        encrypted: "encrypted";
+        permissive: "permissive";
+    }>]>>, z.ZodTransform<Partial<Record<"attestations.retry" | "backends.sync" | "backends.sync_one" | "backends.test" | "contexts.bindings.set" | "contexts.create" | "contexts.delete" | "contexts.source_overrides.delete" | "contexts.source_overrides.set" | "contexts.test_access.set" | "contexts.update" | "event_dlq.discard" | "event_dlq.retry" | "fleet.host.declare" | "fleet.host.remove" | "global_workflows.update" | "held_runs.approve" | "held_runs.reject" | "registration.delete" | "registration.disable" | "secrets.delete" | "secrets.scope.create" | "secrets.scope.delete" | "secrets.scope.rename" | "secrets.set" | "variables.delete" | "variables.set", "disabled" | "encrypted" | "permissive">>, Partial<Record<"attestations.retry" | "backends.sync" | "backends.sync_one" | "backends.test" | "contexts.bindings.set" | "contexts.create" | "contexts.delete" | "contexts.source_overrides.delete" | "contexts.source_overrides.set" | "contexts.test_access.set" | "contexts.update" | "event_dlq.discard" | "event_dlq.retry" | "fleet.host.declare" | "fleet.host.remove" | "global_workflows.update" | "held_runs.approve" | "held_runs.reject" | "registration.delete" | "registration.disable" | "secrets.delete" | "secrets.scope.create" | "secrets.scope.delete" | "secrets.scope.rename" | "secrets.set" | "variables.delete" | "variables.set", "disabled" | "encrypted" | "permissive" | boolean>>>>>;
     supportedDashboardRequests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dashboardEncryptionKey: z.ZodOptional<z.ZodObject<{
+        kty: z.ZodLiteral<"OKP">;
+        crv: z.ZodLiteral<"X25519">;
+        x: z.ZodString;
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"enc">>;
+    }, z.core.$loose>>;
+    dashboardVerifiedIssuer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
 /** Inferred type for orchestrator capabilities. */
 export type OrchCapabilities = z.infer<typeof orchCapabilitiesSchema>;
@@ -74,4 +94,59 @@ export declare const ORCH_CAPABILITIES: Readonly<{
  * orchestrator) or the flag is missing/false.
  */
 export declare function hasOrchCapability(capabilities: OrchCapabilities | undefined, flag: string): boolean;
+/**
+ * Platform-advertised capabilities sent to the orchestrator after auth.
+ * Uses .passthrough() so a newer Platform's unknown flags are preserved.
+ * Every field is optional and absent = unsupported (same evolution contract as
+ * `orchCapabilitiesSchema`).
+ */
+export declare const platformCapabilitiesSchema: z.ZodObject<{
+    orchMetrics: z.ZodOptional<z.ZodBoolean>;
+    oidcMint: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+/** Inferred type for Platform capabilities. */
+export type PlatformCapabilities = z.infer<typeof platformCapabilitiesSchema>;
+/** Default Platform capabilities advertised to the orchestrator after auth. */
+export declare const PLATFORM_CAPABILITIES: Readonly<{
+    orchMetrics: true;
+    oidcMint: true;
+}>;
+/**
+ * Check whether the Platform advertises a specific capability flag.
+ *
+ * Takes `string` (not `keyof`) because a newer Platform may advertise flags the
+ * current orchestrator build doesn't know about. Returns false if capabilities
+ * is undefined (nothing advertised yet) or the flag is missing/false.
+ *
+ * NOTE: "undefined → false" here is the plain reader semantics. A feature-gated
+ * SEND that must stay backward-safe against a pre-capability Platform (which
+ * never advertises) treats "nothing advertised yet" as optimistic-send — that
+ * layer lives in the orchestrator's `sendIfPlatformSupports`, not here.
+ */
+export declare function hasPlatformCapability(capabilities: PlatformCapabilities | undefined, flag: string): boolean;
+/**
+ * Orchestrator -> Agent capabilities, advertised on `register.ack`. Same
+ * evolution contract as the other two directions: every field optional,
+ * absent = unsupported, `.passthrough()` preserves a newer orchestrator's
+ * unknown flags. Lets the agent learn which optional agent-facing protocol
+ * features this orchestrator build supports.
+ */
+export declare const orchAgentCapabilitiesSchema: z.ZodObject<{
+    artifactCompleteAck: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+/** Inferred type for orchestrator -> agent capabilities. */
+export type OrchAgentCapabilities = z.infer<typeof orchAgentCapabilitiesSchema>;
+/** Default orchestrator -> agent capabilities advertised on register.ack. */
+export declare const ORCH_AGENT_CAPABILITIES: Readonly<{
+    artifactCompleteAck: true;
+}>;
+/**
+ * Check whether an orchestrator advertises a specific agent-facing capability
+ * flag.
+ *
+ * Takes `string` (not `keyof`) because a newer orchestrator may advertise flags
+ * this agent build doesn't know about. Returns false if capabilities is
+ * undefined (pre-capability orchestrator) or the flag is missing/false.
+ */
+export declare function hasOrchAgentCapability(capabilities: OrchAgentCapabilities | undefined, flag: string): boolean;
 //# sourceMappingURL=capabilities.d.ts.map

package/dist/protocol/messages/capabilities.js

@@ -1,21 +1,30 @@
 import "../../rolldown-runtime-ClRpJifh.js";
 import { dashboardWritePolicyMap } from "../dashboard-write-operations.js";
+import { dashboardEncryptionJwkSchema } from "./dashboard-sealed-write.js";
 import { DASHBOARD_REQUEST_TYPES } from "./dashboard.js";
 import { z } from "zod";
 //#region src/protocol/messages/capabilities.ts
 /**
-* Orchestrator capability negotiation schemas.
+* Capability negotiation schemas — bidirectional.
 *
 * Modeled after peerCapabilitiesSchema in peer.ts.
-* See CONTEXT.md through for design decisions.
 *
-* Direction: orchestrator → Platform only. The Platform is always at the latest version
-* (centrally deployed), so Platform capabilities are unnecessary. The Platform checks
-* orchestrator capabilities before sending feature-gated messages.
+* Two directions, each advertised as the sending side learns what the other
+* understands:
+* - **orchestrator → Platform** (`orchCapabilitiesSchema`, sent in `auth.request`):
+*   the Platform pre-flight-checks orchestrator capabilities before sending
+*   feature-gated messages (e.g. the dashboard-request manifest).
+* - **Platform → orchestrator** (`platformCapabilitiesSchema`, advertised once
+*   after auth): a self-hosted orchestrator can run *ahead* of the hosted
+*   Platform, so it pre-flight-checks its own feature-gated sends against what
+*   the Platform advertises — surfacing a diagnosable capability gap instead of
+*   firing a frame the Platform would drop.
 *
-* Pattern: Each field indicates support for an optional protocol feature.
-* Missing fields default to unsupported for backward compatibility.
-* Schema uses .passthrough() so newer orchestrators sending unknown flags don't get stripped.
+* Pattern (both directions): each field indicates support for an optional
+* protocol feature. Missing fields default to unsupported for backward
+* compatibility; `.passthrough()` preserves unknown flags from a newer peer.
+* A peer that never advertises at all is treated as "unknown" (optimistic),
+* never as "supports nothing".
 */
 /** Orchestrator role in a cluster topology. */
 const OrchRole = z.enum(["coordinator", "worker"]);
@@ -43,7 +52,23 @@ const orchCapabilitiesSchema = z.object({
 	* cannot drift. Absent on pre-capability builds → treated as "unknown",
 	* never as "supports nothing".
 	*/
-	supportedDashboardRequests: z.array(z.string()).optional()
+	supportedDashboardRequests: z.array(z.string()).optional(),
+	/**
+	* The orchestrator's active X25519 dashboard-encryption public key. Feeds
+	* the Convenient tier: the key reaches the hosted control plane over the
+	* authenticated orchestrator connection, and the dashboard fetches it from
+	* there when no verified issuer is configured. Absent on builds without the
+	* key (no `KICI_SECRET_KEY`, or not yet provisioned) — the dashboard then
+	* fails closed rather than sending plaintext.
+	*/
+	dashboardEncryptionKey: dashboardEncryptionJwkSchema.optional(),
+	/**
+	* The verified-tier origin the dashboard should fetch the encryption key
+	* from directly (bypassing the control plane), from the orchestrator's
+	* `dashboard_verified_issuer` cluster setting. Null/absent ⇒ the Verified
+	* tier is not offered and the Convenient tier applies.
+	*/
+	dashboardVerifiedIssuer: z.string().nullable().optional()
 }).passthrough();
 /** Default orchestrator capabilities sent in auth.request. */
 const ORCH_CAPABILITIES = Object.freeze({
@@ -60,7 +85,66 @@ const ORCH_CAPABILITIES = Object.freeze({
 function hasOrchCapability(capabilities, flag) {
 	return capabilities?.[flag] === true;
 }
+/**
+* Platform-advertised capabilities sent to the orchestrator after auth.
+* Uses .passthrough() so a newer Platform's unknown flags are preserved.
+* Every field is optional and absent = unsupported (same evolution contract as
+* `orchCapabilitiesSchema`).
+*/
+const platformCapabilitiesSchema = z.object({
+	/** Platform ingests periodic `orch.metrics` telemetry pushes. */
+	orchMetrics: z.boolean().optional(),
+	/** Platform serves the orchestrator-initiated `oidc.mint.request` RPC. */
+	oidcMint: z.boolean().optional()
+}).passthrough();
+/** Default Platform capabilities advertised to the orchestrator after auth. */
+const PLATFORM_CAPABILITIES = Object.freeze({
+	orchMetrics: true,
+	oidcMint: true
+});
+/**
+* Check whether the Platform advertises a specific capability flag.
+*
+* Takes `string` (not `keyof`) because a newer Platform may advertise flags the
+* current orchestrator build doesn't know about. Returns false if capabilities
+* is undefined (nothing advertised yet) or the flag is missing/false.
+*
+* NOTE: "undefined → false" here is the plain reader semantics. A feature-gated
+* SEND that must stay backward-safe against a pre-capability Platform (which
+* never advertises) treats "nothing advertised yet" as optimistic-send — that
+* layer lives in the orchestrator's `sendIfPlatformSupports`, not here.
+*/
+function hasPlatformCapability(capabilities, flag) {
+	return capabilities?.[flag] === true;
+}
+/**
+* Orchestrator -> Agent capabilities, advertised on `register.ack`. Same
+* evolution contract as the other two directions: every field optional,
+* absent = unsupported, `.passthrough()` preserves a newer orchestrator's
+* unknown flags. Lets the agent learn which optional agent-facing protocol
+* features this orchestrator build supports.
+*/
+const orchAgentCapabilitiesSchema = z.object({ 
+/**
+* Orchestrator acks `artifacts.upload.complete` (with committed|failed) so
+* the agent can fail the workflow step on a lost commit instead of losing
+* the artifact silently. Absent -> agent stays fire-and-forget.
+*/
+artifactCompleteAck: z.boolean().optional() }).passthrough();
+/** Default orchestrator -> agent capabilities advertised on register.ack. */
+const ORCH_AGENT_CAPABILITIES = Object.freeze({ artifactCompleteAck: true });
+/**
+* Check whether an orchestrator advertises a specific agent-facing capability
+* flag.
+*
+* Takes `string` (not `keyof`) because a newer orchestrator may advertise flags
+* this agent build doesn't know about. Returns false if capabilities is
+* undefined (pre-capability orchestrator) or the flag is missing/false.
+*/
+function hasOrchAgentCapability(capabilities, flag) {
+	return capabilities?.[flag] === true;
+}
 //#endregion
-export { ORCH_CAPABILITIES, OrchRole, hasOrchCapability, orchCapabilitiesSchema };
+export { ORCH_AGENT_CAPABILITIES, ORCH_CAPABILITIES, OrchRole, PLATFORM_CAPABILITIES, hasOrchAgentCapability, hasOrchCapability, hasPlatformCapability, orchAgentCapabilitiesSchema, orchCapabilitiesSchema, platformCapabilitiesSchema };
 
 //# sourceMappingURL=capabilities.js.map

package/dist/protocol/messages/common.d.ts

@@ -35,12 +35,55 @@ export declare const ackSchema: z.ZodObject<{
     type: z.ZodLiteral<"ack">;
     messageId: z.ZodString;
 }, z.core.$strip>;
-/** Negative acknowledgment - message received but could not be processed. */
+/**
+ * Negative acknowledgment - message received but could not be processed.
+ *
+ * Doubles as the version-skew diagnosability signal: when a peer receives a
+ * protocol message type it does not understand, it replies with a NACK naming
+ * the unsupported `receivedType` instead of silently dropping the frame (which
+ * otherwise surfaces only as a downstream proxy timeout). `messageId` correlates
+ * the NACK to a request/response frame when the offending frame carried one; a
+ * fire-and-forget control frame omits it and `receivedType` is the diagnostic
+ * anchor. Both are optional so an uncorrelatable skew frame still yields a valid
+ * NACK.
+ */
 export declare const nackSchema: z.ZodObject<{
     type: z.ZodLiteral<"nack">;
-    messageId: z.ZodString;
+    messageId: z.ZodOptional<z.ZodString>;
+    receivedType: z.ZodOptional<z.ZodString>;
     reason: z.ZodString;
 }, z.core.$strip>;
+export type Nack = z.infer<typeof nackSchema>;
+/**
+ * Message types that are NEVER answered with an unsupported-message NACK when
+ * they fail a direction's recognition chain:
+ * - `nack` — loop guard: a malformed NACK must not trigger a NACK-of-NACK.
+ * - `log.chunk` / `orch-log.chunk` — pure streaming frames. A NACK cannot be
+ *   correlated to a stream and would only add noise; these stay drop-and-warn.
+ */
+export declare const NACK_EXEMPT_MESSAGE_TYPES: ReadonlySet<string>;
+/**
+ * Build an unsupported-message NACK for a frame that failed every schema in a
+ * direction's recognition chain (version skew: the peer sent a type this build
+ * does not understand).
+ *
+ * Returns `null` — meaning "do not NACK, stay drop-and-warn" — when:
+ * - `raw` is not an object carrying a non-empty string `type` (genuinely
+ *   malformed garbage, not a recognizable-but-unsupported message); OR
+ * - the `type` is in `NACK_EXEMPT_MESSAGE_TYPES` (loop guard + streaming); OR
+ * - the `type` is in `knownTypes` — a KNOWN message type that failed the
+ *   direction's recognition chain is malformed (e.g. an oversized field past
+ *   its length bound), not version skew. The caller must close the connection,
+ *   never keep it alive with a NACK; only a genuinely-unknown type is a skew
+ *   signal.
+ *
+ * `side` names the local peer emitting the NACK (the behind party) for the
+ * operator-facing upgrade hint, matching the lock-window "upgrade the
+ * orchestrator/Platform" wording. `knownTypes` is the set of message types this
+ * build recognizes for the given direction (derived from the schema
+ * discriminators by the caller).
+ */
+export declare function buildUnsupportedMessageNack(raw: unknown, side: 'orchestrator' | 'platform', knownTypes: ReadonlySet<string>): z.infer<typeof nackSchema> | null;
 /** Protocol-level error message. */
 export declare const errorSchema: z.ZodObject<{
     type: z.ZodLiteral<"error">;

package/dist/protocol/messages/common.js

@@ -37,12 +37,73 @@ const ackSchema = z.object({
 	type: z.literal("ack"),
 	messageId: z.string()
 });
-/** Negative acknowledgment - message received but could not be processed. */
+/**
+* Negative acknowledgment - message received but could not be processed.
+*
+* Doubles as the version-skew diagnosability signal: when a peer receives a
+* protocol message type it does not understand, it replies with a NACK naming
+* the unsupported `receivedType` instead of silently dropping the frame (which
+* otherwise surfaces only as a downstream proxy timeout). `messageId` correlates
+* the NACK to a request/response frame when the offending frame carried one; a
+* fire-and-forget control frame omits it and `receivedType` is the diagnostic
+* anchor. Both are optional so an uncorrelatable skew frame still yields a valid
+* NACK.
+*/
 const nackSchema = z.object({
 	type: z.literal("nack"),
-	messageId: z.string(),
+	/** Correlation id echoed from the offending frame, when it carried one. */
+	messageId: z.string().optional(),
+	/** The unsupported/unrecognized message type that triggered this NACK. */
+	receivedType: z.string().optional(),
 	reason: z.string()
 });
+/**
+* Message types that are NEVER answered with an unsupported-message NACK when
+* they fail a direction's recognition chain:
+* - `nack` — loop guard: a malformed NACK must not trigger a NACK-of-NACK.
+* - `log.chunk` / `orch-log.chunk` — pure streaming frames. A NACK cannot be
+*   correlated to a stream and would only add noise; these stay drop-and-warn.
+*/
+const NACK_EXEMPT_MESSAGE_TYPES = /* @__PURE__ */ new Set([
+	"nack",
+	"log.chunk",
+	"orch-log.chunk"
+]);
+/**
+* Build an unsupported-message NACK for a frame that failed every schema in a
+* direction's recognition chain (version skew: the peer sent a type this build
+* does not understand).
+*
+* Returns `null` — meaning "do not NACK, stay drop-and-warn" — when:
+* - `raw` is not an object carrying a non-empty string `type` (genuinely
+*   malformed garbage, not a recognizable-but-unsupported message); OR
+* - the `type` is in `NACK_EXEMPT_MESSAGE_TYPES` (loop guard + streaming); OR
+* - the `type` is in `knownTypes` — a KNOWN message type that failed the
+*   direction's recognition chain is malformed (e.g. an oversized field past
+*   its length bound), not version skew. The caller must close the connection,
+*   never keep it alive with a NACK; only a genuinely-unknown type is a skew
+*   signal.
+*
+* `side` names the local peer emitting the NACK (the behind party) for the
+* operator-facing upgrade hint, matching the lock-window "upgrade the
+* orchestrator/Platform" wording. `knownTypes` is the set of message types this
+* build recognizes for the given direction (derived from the schema
+* discriminators by the caller).
+*/
+function buildUnsupportedMessageNack(raw, side, knownTypes) {
+	if (typeof raw !== "object" || raw === null) return null;
+	const frame = raw;
+	if (typeof frame.type !== "string" || frame.type.length === 0) return null;
+	if (NACK_EXEMPT_MESSAGE_TYPES.has(frame.type)) return null;
+	if (knownTypes.has(frame.type)) return null;
+	const nack = {
+		type: "nack",
+		receivedType: frame.type,
+		reason: `unsupported message type "${frame.type}" — this ${side} does not understand it (protocol version skew); upgrade the ${side}`
+	};
+	if (typeof frame.messageId === "string" && frame.messageId.length > 0) nack.messageId = frame.messageId;
+	return nack;
+}
 /** Protocol-level error message. */
 const errorSchema = z.object({
 	type: z.literal("error"),
@@ -50,6 +111,6 @@ const errorSchema = z.object({
 	message: z.string()
 });
 //#endregion
-export { WS_MAX_PAYLOAD_BYTES, ackSchema, errorSchema, heartbeatSchema, nackSchema };
+export { NACK_EXEMPT_MESSAGE_TYPES, WS_MAX_PAYLOAD_BYTES, ackSchema, buildUnsupportedMessageNack, errorSchema, heartbeatSchema, nackSchema };
 
 //# sourceMappingURL=common.js.map

package/dist/protocol/messages/dashboard-sealed-write.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Wire envelope for a browser-sealed dashboard write.
+ *
+ * Under the `encrypted` dashboard-write posture the browser seals the plaintext
+ * value to the orchestrator's published X25519 encryption key before it leaves
+ * the page, so the hosted Platform relays only opaque ciphertext. The envelope
+ * is the exact shape the orchestrator's `decryptDashboardSealedWrite` consumes:
+ * an ephemeral X25519 public key (base64 DER-SPKI) and the AES-256-GCM output
+ * packed as `IV || authTag || ciphertext` (base64), plus the `keyId` (`kid`)
+ * naming which published encryption key the browser sealed to.
+ *
+ * Browser-safe: pure Zod, no node built-ins, so the dashboard SPA imports it
+ * directly.
+ */
+import { z } from 'zod';
+export declare const dashboardSealedEnvelopeSchema: z.ZodObject<{
+    keyId: z.ZodString;
+    ephemeralPublicKey: z.ZodString;
+    encrypted: z.ZodString;
+}, z.core.$strip>;
+export type DashboardSealedEnvelope = z.infer<typeof dashboardSealedEnvelopeSchema>;
+/**
+ * The orchestrator's published X25519 dashboard-encryption public key, as an
+ * OKP JWK (`kty:'OKP'`, `crv:'X25519'`, `use:'enc'`, `x` = the raw 32-byte
+ * public key base64url-encoded, `kid` = its RFC 7638 thumbprint).
+ *
+ * `.passthrough()` because a JWK may legitimately carry members a given peer
+ * does not know; only the members the seal actually needs are validated.
+ */
+export declare const dashboardEncryptionJwkSchema: z.ZodObject<{
+    kty: z.ZodLiteral<"OKP">;
+    crv: z.ZodLiteral<"X25519">;
+    x: z.ZodString;
+    kid: z.ZodString;
+    use: z.ZodOptional<z.ZodLiteral<"enc">>;
+}, z.core.$loose>;
+export type DashboardEncryptionJwk = z.infer<typeof dashboardEncryptionJwkSchema>;
+/**
+ * Structured error codes the orchestrator returns (in a `.set.response`
+ * `error` field) when a sealed / plaintext write cannot be honored under the
+ * `encrypted` posture. The dashboard renders a fail-closed affordance keyed on
+ * these codes — never a silent fallback to plaintext-through-Platform.
+ */
+export declare const DashboardSealedWriteError: z.ZodEnum<{
+    decryption_failed: "decryption_failed";
+    encryption_unavailable: "encryption_unavailable";
+    missing_value: "missing_value";
+    operation_requires_encryption: "operation_requires_encryption";
+    unknown_encryption_key: "unknown_encryption_key";
+}>;
+export type DashboardSealedWriteError = z.infer<typeof DashboardSealedWriteError>;
+//# sourceMappingURL=dashboard-sealed-write.d.ts.map

package/dist/protocol/messages/dashboard-sealed-write.js

@@ -0,0 +1,57 @@
+import "../../rolldown-runtime-ClRpJifh.js";
+import { z } from "zod";
+//#region src/protocol/messages/dashboard-sealed-write.ts
+/**
+* Wire envelope for a browser-sealed dashboard write.
+*
+* Under the `encrypted` dashboard-write posture the browser seals the plaintext
+* value to the orchestrator's published X25519 encryption key before it leaves
+* the page, so the hosted Platform relays only opaque ciphertext. The envelope
+* is the exact shape the orchestrator's `decryptDashboardSealedWrite` consumes:
+* an ephemeral X25519 public key (base64 DER-SPKI) and the AES-256-GCM output
+* packed as `IV || authTag || ciphertext` (base64), plus the `keyId` (`kid`)
+* naming which published encryption key the browser sealed to.
+*
+* Browser-safe: pure Zod, no node built-ins, so the dashboard SPA imports it
+* directly.
+*/
+const dashboardSealedEnvelopeSchema = z.object({
+	/** The `kid` of the orchestrator encryption key the browser sealed to. */
+	keyId: z.string().min(1),
+	/** Ephemeral X25519 public key, base64-encoded DER-SPKI. */
+	ephemeralPublicKey: z.string().min(1),
+	/** AES-256-GCM output as base64 `IV(12) || authTag(16) || ciphertext`. */
+	encrypted: z.string().min(1)
+});
+/**
+* The orchestrator's published X25519 dashboard-encryption public key, as an
+* OKP JWK (`kty:'OKP'`, `crv:'X25519'`, `use:'enc'`, `x` = the raw 32-byte
+* public key base64url-encoded, `kid` = its RFC 7638 thumbprint).
+*
+* `.passthrough()` because a JWK may legitimately carry members a given peer
+* does not know; only the members the seal actually needs are validated.
+*/
+const dashboardEncryptionJwkSchema = z.object({
+	kty: z.literal("OKP"),
+	crv: z.literal("X25519"),
+	x: z.string().min(1),
+	kid: z.string().min(1),
+	use: z.literal("enc").optional()
+}).passthrough();
+/**
+* Structured error codes the orchestrator returns (in a `.set.response`
+* `error` field) when a sealed / plaintext write cannot be honored under the
+* `encrypted` posture. The dashboard renders a fail-closed affordance keyed on
+* these codes — never a silent fallback to plaintext-through-Platform.
+*/
+const DashboardSealedWriteError = z.enum([
+	"operation_requires_encryption",
+	"unknown_encryption_key",
+	"encryption_unavailable",
+	"decryption_failed",
+	"missing_value"
+]);
+//#endregion
+export { DashboardSealedWriteError, dashboardEncryptionJwkSchema, dashboardSealedEnvelopeSchema };
+
+//# sourceMappingURL=dashboard-sealed-write.js.map