@fnndsc/menu 0.3.1

package/dist/pacs.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @file The PACS query vocabulary: search results as typed envelope payloads.
+ *
+ * A `pacs query` answers with studies containing series; the terminal renders
+ * them as text while a graphical surface reads this model — the same
+ * one-command-two-projections pattern as the DAG models. Series carry their
+ * instance UIDs so a surface can lower a selection straight to
+ * `pacs pull SeriesInstanceUID:<uid>`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** One series within a found study. */
+export declare const pacsSeriesSchema: z.ZodObject<{
+    seriesUID: z.ZodString;
+    description: z.ZodString;
+    modality: z.ZodString;
+    fileCount: z.ZodOptional<z.ZodNumber>;
+    /** The series' own VFS path under the query — the pull's argument. */
+    vfsPath: z.ZodOptional<z.ZodString>;
+    /** True when CUBE already holds this series (a pull would just confirm). */
+    pulled: z.ZodOptional<z.ZodBoolean>;
+    /** How many files CUBE holds, when known. */
+    pulledFiles: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    seriesUID: string;
+    description: string;
+    modality: string;
+    vfsPath?: string | undefined;
+    fileCount?: number | undefined;
+    pulled?: boolean | undefined;
+    pulledFiles?: number | undefined;
+}, {
+    seriesUID: string;
+    description: string;
+    modality: string;
+    vfsPath?: string | undefined;
+    fileCount?: number | undefined;
+    pulled?: boolean | undefined;
+    pulledFiles?: number | undefined;
+}>;
+/** One found study and its series. */
+export declare const pacsStudySchema: z.ZodObject<{
+    studyUID: z.ZodOptional<z.ZodString>;
+    /** The study's VFS path under the query — a study-level pull's argument. */
+    vfsPath: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    patientName: z.ZodString;
+    patientId: z.ZodString;
+    date: z.ZodString;
+    modalities: z.ZodString;
+    accession: z.ZodString;
+    series: z.ZodArray<z.ZodObject<{
+        seriesUID: z.ZodString;
+        description: z.ZodString;
+        modality: z.ZodString;
+        fileCount: z.ZodOptional<z.ZodNumber>;
+        /** The series' own VFS path under the query — the pull's argument. */
+        vfsPath: z.ZodOptional<z.ZodString>;
+        /** True when CUBE already holds this series (a pull would just confirm). */
+        pulled: z.ZodOptional<z.ZodBoolean>;
+        /** How many files CUBE holds, when known. */
+        pulledFiles: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        seriesUID: string;
+        description: string;
+        modality: string;
+        vfsPath?: string | undefined;
+        fileCount?: number | undefined;
+        pulled?: boolean | undefined;
+        pulledFiles?: number | undefined;
+    }, {
+        seriesUID: string;
+        description: string;
+        modality: string;
+        vfsPath?: string | undefined;
+        fileCount?: number | undefined;
+        pulled?: boolean | undefined;
+        pulledFiles?: number | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    date: string;
+    series: {
+        seriesUID: string;
+        description: string;
+        modality: string;
+        vfsPath?: string | undefined;
+        fileCount?: number | undefined;
+        pulled?: boolean | undefined;
+        pulledFiles?: number | undefined;
+    }[];
+    description: string;
+    patientName: string;
+    patientId: string;
+    modalities: string;
+    accession: string;
+    vfsPath?: string | undefined;
+    studyUID?: string | undefined;
+}, {
+    date: string;
+    series: {
+        seriesUID: string;
+        description: string;
+        modality: string;
+        vfsPath?: string | undefined;
+        fileCount?: number | undefined;
+        pulled?: boolean | undefined;
+        pulledFiles?: number | undefined;
+    }[];
+    description: string;
+    patientName: string;
+    patientId: string;
+    modalities: string;
+    accession: string;
+    vfsPath?: string | undefined;
+    studyUID?: string | undefined;
+}>;
+/**
+ * The `pacs.query` model: one query's decoded result. `vfsPath` is where the
+ * query lives under `/net/pacs/queries` — a query is a persistent CUBE
+ * object, re-checkable later.
+ */
+export declare const pacsQueryModelSchema: z.ZodObject<{
+    queryId: z.ZodNumber;
+    vfsPath: z.ZodString;
+    pacsName: z.ZodString;
+    expression: z.ZodString;
+    studies: z.ZodArray<z.ZodObject<{
+        studyUID: z.ZodOptional<z.ZodString>;
+        /** The study's VFS path under the query — a study-level pull's argument. */
+        vfsPath: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        patientName: z.ZodString;
+        patientId: z.ZodString;
+        date: z.ZodString;
+        modalities: z.ZodString;
+        accession: z.ZodString;
+        series: z.ZodArray<z.ZodObject<{
+            seriesUID: z.ZodString;
+            description: z.ZodString;
+            modality: z.ZodString;
+            fileCount: z.ZodOptional<z.ZodNumber>;
+            /** The series' own VFS path under the query — the pull's argument. */
+            vfsPath: z.ZodOptional<z.ZodString>;
+            /** True when CUBE already holds this series (a pull would just confirm). */
+            pulled: z.ZodOptional<z.ZodBoolean>;
+            /** How many files CUBE holds, when known. */
+            pulledFiles: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            seriesUID: string;
+            description: string;
+            modality: string;
+            vfsPath?: string | undefined;
+            fileCount?: number | undefined;
+            pulled?: boolean | undefined;
+            pulledFiles?: number | undefined;
+        }, {
+            seriesUID: string;
+            description: string;
+            modality: string;
+            vfsPath?: string | undefined;
+            fileCount?: number | undefined;
+            pulled?: boolean | undefined;
+            pulledFiles?: number | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        date: string;
+        series: {
+            seriesUID: string;
+            description: string;
+            modality: string;
+            vfsPath?: string | undefined;
+            fileCount?: number | undefined;
+            pulled?: boolean | undefined;
+            pulledFiles?: number | undefined;
+        }[];
+        description: string;
+        patientName: string;
+        patientId: string;
+        modalities: string;
+        accession: string;
+        vfsPath?: string | undefined;
+        studyUID?: string | undefined;
+    }, {
+        date: string;
+        series: {
+            seriesUID: string;
+            description: string;
+            modality: string;
+            vfsPath?: string | undefined;
+            fileCount?: number | undefined;
+            pulled?: boolean | undefined;
+            pulledFiles?: number | undefined;
+        }[];
+        description: string;
+        patientName: string;
+        patientId: string;
+        modalities: string;
+        accession: string;
+        vfsPath?: string | undefined;
+        studyUID?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    vfsPath: string;
+    queryId: number;
+    pacsName: string;
+    expression: string;
+    studies: {
+        date: string;
+        series: {
+            seriesUID: string;
+            description: string;
+            modality: string;
+            vfsPath?: string | undefined;
+            fileCount?: number | undefined;
+            pulled?: boolean | undefined;
+            pulledFiles?: number | undefined;
+        }[];
+        description: string;
+        patientName: string;
+        patientId: string;
+        modalities: string;
+        accession: string;
+        vfsPath?: string | undefined;
+        studyUID?: string | undefined;
+    }[];
+}, {
+    vfsPath: string;
+    queryId: number;
+    pacsName: string;
+    expression: string;
+    studies: {
+        date: string;
+        series: {
+            seriesUID: string;
+            description: string;
+            modality: string;
+            vfsPath?: string | undefined;
+            fileCount?: number | undefined;
+            pulled?: boolean | undefined;
+            pulledFiles?: number | undefined;
+        }[];
+        description: string;
+        patientName: string;
+        patientId: string;
+        modalities: string;
+        accession: string;
+        vfsPath?: string | undefined;
+        studyUID?: string | undefined;
+    }[];
+}>;
+export type PacsSeries = z.infer<typeof pacsSeriesSchema>;
+export type PacsStudy = z.infer<typeof pacsStudySchema>;
+export type PacsQueryModel = z.infer<typeof pacsQueryModelSchema>;
+/** The model's envelope kind. */
+export declare const PACS_QUERY_MODEL_KIND: "pacs.query";

package/dist/pacs.js

@@ -0,0 +1,53 @@
+/**
+ * @file The PACS query vocabulary: search results as typed envelope payloads.
+ *
+ * A `pacs query` answers with studies containing series; the terminal renders
+ * them as text while a graphical surface reads this model — the same
+ * one-command-two-projections pattern as the DAG models. Series carry their
+ * instance UIDs so a surface can lower a selection straight to
+ * `pacs pull SeriesInstanceUID:<uid>`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** One series within a found study. */
+export const pacsSeriesSchema = z.object({
+    seriesUID: z.string(),
+    description: z.string(),
+    modality: z.string(),
+    fileCount: z.number().optional(),
+    /** The series' own VFS path under the query — the pull's argument. */
+    vfsPath: z.string().optional(),
+    /** True when CUBE already holds this series (a pull would just confirm). */
+    pulled: z.boolean().optional(),
+    /** How many files CUBE holds, when known. */
+    pulledFiles: z.number().optional(),
+});
+/** One found study and its series. */
+export const pacsStudySchema = z.object({
+    studyUID: z.string().optional(),
+    /** The study's VFS path under the query — a study-level pull's argument. */
+    vfsPath: z.string().optional(),
+    description: z.string(),
+    patientName: z.string(),
+    patientId: z.string(),
+    date: z.string(),
+    modalities: z.string(),
+    accession: z.string(),
+    series: z.array(pacsSeriesSchema),
+});
+/**
+ * The `pacs.query` model: one query's decoded result. `vfsPath` is where the
+ * query lives under `/net/pacs/queries` — a query is a persistent CUBE
+ * object, re-checkable later.
+ */
+export const pacsQueryModelSchema = z.object({
+    queryId: z.number(),
+    vfsPath: z.string(),
+    pacsName: z.string(),
+    expression: z.string(),
+    studies: z.array(pacsStudySchema),
+});
+/** The model's envelope kind. */
+export const PACS_QUERY_MODEL_KIND = 'pacs.query';
+//# sourceMappingURL=pacs.js.map

package/dist/pacs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pacs.js","sourceRoot":"","sources":["../src/pacs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,uCAAuC;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,sEAAsE;IACtE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,4EAA4E;IAC5E,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC9B,6CAA6C;IAC7C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAEH,sCAAsC;AACtC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,4EAA4E;IAC5E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;CAClC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;CAClC,CAAC,CAAC;AAMH,iCAAiC;AACjC,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAqB,CAAC"}

package/dist/proc.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file Prompt-facing process-index lifecycle state.
+ *
+ * This is contract vocabulary: it is narrowed by the prompt-context schema and
+ * read by every surface that draws a prompt, so it lives with the contract
+ * rather than with the cache that happens to produce it.
+ *
+ * @module
+ */
+/** User-visible process-index states carried to prompt renderers. */
+export declare const PROC_PROMPT_STATES: readonly ["cold", "cached", "failed"];
+/** User-visible process-index state carried to prompt renderers. */
+export type ProcPromptState = typeof PROC_PROMPT_STATES[number];
+/**
+ * Prompt-facing progress for cache restoration and reconciliation.
+ *
+ * @property loaded - Plugin instances currently available.
+ * @property total - Authoritative total when CUBE has reported one.
+ * @property restored - Whether the available instances came from a checkpoint.
+ * @property state - Cold indexing, cached reconciliation, or failed refresh.
+ */
+export interface ProcPromptProgress {
+    loaded: number;
+    total?: number;
+    restored?: boolean;
+    state?: ProcPromptState;
+    /** Whether the global index sweep is what `loaded`/`total` describe; absent means yes (older daemons). */
+    sweeping?: boolean;
+    /** One feed's first-visit topology load in flight, when there is one. */
+    feed?: ProcFeedPromptProgress;
+    /** Feeds the roster gained (created or shared) in the last half minute. */
+    arrived?: number[];
+}
+/**
+ * A warm-up step that failed behind the prompt and has not since succeeded.
+ *
+ * @property label - The boot-step label, as the readout named it.
+ * @property message - What the failure said.
+ */
+export interface WarmupFailureReport {
+    label: string;
+    message: string;
+}
+/**
+ * Prompt-facing progress of one feed's topology load.
+ *
+ * @property id - The feed being loaded.
+ * @property loaded - Plugin instances fetched so far.
+ * @property total - The server's count for the feed, zero while unknown.
+ */
+export interface ProcFeedPromptProgress {
+    id: number;
+    loaded: number;
+    total: number;
+}
+/**
+ * Resolves the prompt state, including compatibility with contexts that only
+ * carry the legacy `restored` flag.
+ *
+ * @param progress - Prompt-facing process-index progress.
+ * @returns Explicit state, or one derived from checkpoint restoration.
+ */
+export declare function procPromptState_get(progress: ProcPromptProgress): ProcPromptState;

package/dist/proc.js

@@ -0,0 +1,22 @@
+/**
+ * @file Prompt-facing process-index lifecycle state.
+ *
+ * This is contract vocabulary: it is narrowed by the prompt-context schema and
+ * read by every surface that draws a prompt, so it lives with the contract
+ * rather than with the cache that happens to produce it.
+ *
+ * @module
+ */
+/** User-visible process-index states carried to prompt renderers. */
+export const PROC_PROMPT_STATES = ['cold', 'cached', 'failed'];
+/**
+ * Resolves the prompt state, including compatibility with contexts that only
+ * carry the legacy `restored` flag.
+ *
+ * @param progress - Prompt-facing process-index progress.
+ * @returns Explicit state, or one derived from checkpoint restoration.
+ */
+export function procPromptState_get(progress) {
+    return progress.state ?? (progress.restored === true ? 'cached' : 'cold');
+}
+//# sourceMappingURL=proc.js.map

package/dist/proc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proc.js","sourceRoot":"","sources":["../src/proc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,qEAAqE;AACrE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAkDxE;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA4B;IAC9D,OAAO,QAAQ,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5E,CAAC"}

package/dist/progress.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file The structured-progress vocabulary.
+ *
+ * Progress is semantic live telemetry: not command output, never captured into
+ * envelopes, never consumed by pipes or redirects. These are the values it may
+ * carry. They live with the contract because the wire narrows to them and every
+ * surface reads them, while the engine merely produces them.
+ *
+ * @module
+ */
+/**
+ * Operations that may produce structured progress.
+ *
+ * `task` is the deliberate none-of-the-above value: work whose activity has no
+ * useful name, such as a cache warm-up or a directory scan. It is also the
+ * value an unknown operation from a newer peer degrades to, so a surface built
+ * against an older enum renders such work generically instead of dropping it.
+ */
+export declare const PROGRESS_OPERATIONS: readonly ["upload", "download", "pull", "workflow", "pipeline", "group", "task"];
+/** Broad structured-progress producer classes. */
+export declare const PROGRESS_KINDS: readonly ["transfer", "retrieve", "workflow", "inspection"];
+/**
+ * Lifecycle phases shared by structured-progress operations.
+ *
+ * `working` is indeterminate: work is under way and neither its extent nor its
+ * remaining time is known. The named phases all imply a specific activity,
+ * which is precisely what indeterminate work cannot claim.
+ */
+export declare const PROGRESS_PHASES: readonly ["scanning", "transferring", "watching", "retrying", "reading", "working", "complete", "failed"];
+/** Units supported by counted progress. */
+export declare const PROGRESS_UNITS: readonly ["files", "bytes", "series", "jobs", "nodes"];
+/** Operation and item states supported by structured progress. */
+export declare const PROGRESS_STATUSES: readonly ["running", "done", "unconfirmed", "stalled", "timeout", "error", "unknown"];
+export type ProgressOperation = typeof PROGRESS_OPERATIONS[number];
+export type ProgressKind = typeof PROGRESS_KINDS[number];
+export type ProgressPhase = typeof PROGRESS_PHASES[number];
+export type ProgressUnit = typeof PROGRESS_UNITS[number];
+export type ProgressStatus = typeof PROGRESS_STATUSES[number];

package/dist/progress.js

@@ -0,0 +1,43 @@
+/**
+ * @file The structured-progress vocabulary.
+ *
+ * Progress is semantic live telemetry: not command output, never captured into
+ * envelopes, never consumed by pipes or redirects. These are the values it may
+ * carry. They live with the contract because the wire narrows to them and every
+ * surface reads them, while the engine merely produces them.
+ *
+ * @module
+ */
+/**
+ * Operations that may produce structured progress.
+ *
+ * `task` is the deliberate none-of-the-above value: work whose activity has no
+ * useful name, such as a cache warm-up or a directory scan. It is also the
+ * value an unknown operation from a newer peer degrades to, so a surface built
+ * against an older enum renders such work generically instead of dropping it.
+ */
+export const PROGRESS_OPERATIONS = [
+    'upload', 'download', 'pull', 'workflow', 'pipeline', 'group', 'task',
+];
+/** Broad structured-progress producer classes. */
+export const PROGRESS_KINDS = ['transfer', 'retrieve', 'workflow', 'inspection'];
+/**
+ * Lifecycle phases shared by structured-progress operations.
+ *
+ * `working` is indeterminate: work is under way and neither its extent nor its
+ * remaining time is known. The named phases all imply a specific activity,
+ * which is precisely what indeterminate work cannot claim.
+ */
+export const PROGRESS_PHASES = [
+    'scanning', 'transferring', 'watching', 'retrying', 'reading', 'working', 'complete', 'failed',
+];
+/** Units supported by counted progress. */
+export const PROGRESS_UNITS = ['files', 'bytes', 'series', 'jobs', 'nodes'];
+/** Operation and item states supported by structured progress. */
+export const PROGRESS_STATUSES = [
+    'running', 'done', 'unconfirmed', 'stalled', 'timeout', 'error', 'unknown',
+];
+// `ProgressEvent` is not declared here. It is inferred from the wire schema in
+// `messages.ts`, so the shape the engine emits and the shape the wire carries
+// cannot be two things.
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM;CAC7D,CAAC;AACX,kDAAkD;AAClD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,CAAU,CAAC;AAC1F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ;CACtF,CAAC;AACX,2CAA2C;AAC3C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AACrF,kEAAkE;AAClE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS;CAClE,CAAC;AAQX,+EAA+E;AAC/E,8EAA8E;AAC9E,wBAAwB"}

package/dist/validate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file Boundary validation.
+ *
+ * Every message is validated on the way in and out. Structural violations
+ * (missing required fields, wrong types, an unknown `type`) are rejected;
+ * unknown *additional* fields are tolerated (stripped), so a daemon accepts
+ * additive extensions from a newer minor without understanding them. Parsing
+ * never throws — it returns a {@link ParseResult} so the caller can answer a
+ * malformed message with an `error` message rather than dropping the socket.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { attachMessageSchema, type ClientMessage, type ServerMessage } from './messages.js';
+/**
+ * The outcome of validating a message at the boundary.
+ *
+ * @property ok - Whether the input was a valid message.
+ * @property value - The parsed message, when `ok`.
+ * @property error - A human-readable reason, when not `ok`.
+ */
+export interface ParseResult<T> {
+    ok: boolean;
+    value?: T;
+    error?: string;
+}
+/**
+ * Validates a message a surface sent to the daemon.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result.
+ */
+export declare function clientMessage_parse(raw: unknown): ParseResult<ClientMessage>;
+/**
+ * Validates a message the daemon sent to a surface.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result.
+ */
+export declare function serverMessage_parse(raw: unknown): ParseResult<ServerMessage>;
+/**
+ * Parses a JSON string into a client message, rejecting both malformed JSON
+ * and structurally invalid messages with a clear reason.
+ *
+ * @param json - The raw JSON text received on the socket.
+ * @returns The parse result.
+ */
+export declare function clientMessage_fromJson(json: string): ParseResult<ClientMessage>;
+/**
+ * Validates an attach message and checks its declared contract version
+ * against this build. A structurally valid attach on an incompatible major
+ * is rejected with a clear reason.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result; an incompatible version is a validation failure.
+ */
+export declare function attach_parse(raw: unknown): ParseResult<z.infer<typeof attachMessageSchema>>;

package/dist/validate.js

@@ -0,0 +1,93 @@
+import { clientMessageSchema, serverMessageSchema, attachMessageSchema, } from './messages.js';
+import { version_isCompatible } from './version.js';
+/**
+ * Formats a Zod error into a compact, single-line boundary reason.
+ *
+ * @param error - The Zod validation error.
+ * @returns A human-readable reason string.
+ */
+function zodError_format(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.join('.');
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join('; ');
+}
+/**
+ * Validates a raw value against a schema, never throwing.
+ *
+ * Generic over the schema rather than over a value type, because a schema that
+ * degrades unknown values (see `progressOperationSchema`) reads a wider input
+ * than it produces, and only the schema's own output type states what a caller
+ * receives.
+ *
+ * @param schema - The schema to validate against.
+ * @param raw - The untrusted input.
+ * @returns The parse result.
+ */
+function schema_parse(schema, raw) {
+    const result = schema.safeParse(raw);
+    if (result.success) {
+        return { ok: true, value: result.data };
+    }
+    return { ok: false, error: zodError_format(result.error) };
+}
+/**
+ * Validates a message a surface sent to the daemon.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result.
+ */
+export function clientMessage_parse(raw) {
+    return schema_parse(clientMessageSchema, raw);
+}
+/**
+ * Validates a message the daemon sent to a surface.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result.
+ */
+export function serverMessage_parse(raw) {
+    return schema_parse(serverMessageSchema, raw);
+}
+/**
+ * Parses a JSON string into a client message, rejecting both malformed JSON
+ * and structurally invalid messages with a clear reason.
+ *
+ * @param json - The raw JSON text received on the socket.
+ * @returns The parse result.
+ */
+export function clientMessage_fromJson(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `malformed JSON: ${message}` };
+    }
+    return clientMessage_parse(parsed);
+}
+/**
+ * Validates an attach message and checks its declared contract version
+ * against this build. A structurally valid attach on an incompatible major
+ * is rejected with a clear reason.
+ *
+ * @param raw - The untrusted input (already JSON-parsed).
+ * @returns The parse result; an incompatible version is a validation failure.
+ */
+export function attach_parse(raw) {
+    const parsed = schema_parse(attachMessageSchema, raw);
+    if (!parsed.ok || parsed.value === undefined) {
+        return parsed;
+    }
+    if (!version_isCompatible(parsed.value.protocolVersion)) {
+        return {
+            ok: false,
+            error: `incompatible contract version ${parsed.value.protocolVersion}`,
+        };
+    }
+    return parsed;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GAGpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAepD;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAiB;IACxC,OAAO,KAAK,CAAC,MAAM;SAChB,GAAG,CAAC,CAAC,KAAiB,EAAU,EAAE;QACjC,MAAM,IAAI,GAAW,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5D,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,YAAY,CAAyB,MAAS,EAAE,GAAY;IACnE,MAAM,MAAM,GAAgD,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAClF,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,YAAY,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,YAAY,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAW,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,OAAO,EAAE,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,MAAM,GAAqD,YAAY,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;IACxG,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7C,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC;QACxD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,iCAAiC,MAAM,CAAC,KAAK,CAAC,eAAe,EAAE;SACvE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file The wire-contract version and its compatibility rule.
+ *
+ * The contract version is carried by a client in the attach handshake and
+ * refused by the daemon on mismatch, with no silent degradation. Per
+ * `docs/calypso.adoc`, it tracks the calypso package's major version at
+ * release; within a major, changes are additive only (new message types,
+ * new optional fields, new model kinds), so a daemon tolerates unknown
+ * additions from a newer minor but rejects a different major outright.
+ *
+ * @module
+ */
+/**
+ * The wire-contract major version this build speaks.
+ */
+export declare const CONTRACT_VERSION: number;
+/**
+ * Decides whether a client's declared contract version is compatible with
+ * this build. Compatibility is exact-major: a client on a different major is
+ * refused, because a major bump removes or re-types something.
+ *
+ * @param clientVersion - The contract major the client declared at attach.
+ * @returns True when the client may attach.
+ */
+export declare function version_isCompatible(clientVersion: number): boolean;