@theruntime/protocol 0.0.0 → 0.0.1

package/src/operations/declaration.ts

@@ -0,0 +1,115 @@
+/** What an agent states about an app's setup. Three closed fields, each parsed against its own
+ * set, so a value outside one never reaches the daemon. */
+import { asRecord } from "./parse-helpers";
+
+export const HOST_DECLARATIONS = ["connected", "none"] as const;
+export const REACT_DECLARATIONS = ["runtime", "host"] as const;
+export const COMPONENT_DECLARATIONS = ["runtime", "host", "both"] as const;
+
+export type HostDeclaration = (typeof HOST_DECLARATIONS)[number];
+export type ReactDeclaration = (typeof REACT_DECLARATIONS)[number];
+export type ComponentDeclaration = (typeof COMPONENT_DECLARATIONS)[number];
+
+export interface Declaration {
+  readonly host?: HostDeclaration;
+  readonly react?: ReactDeclaration;
+  readonly components?: ComponentDeclaration;
+}
+
+/** The field names a declaration carries, in the order every message about one lists them. */
+export const DECLARATION_FIELDS = ["host", "react", "components"] as const;
+
+export type DeclarationField = (typeof DECLARATION_FIELDS)[number];
+
+function isMember<Value extends string>(set: readonly Value[], value: unknown): value is Value {
+  if (typeof value !== "string") return false;
+  const members: readonly string[] = set;
+  return members.includes(value);
+}
+
+export function isHostDeclaration(value: unknown): value is HostDeclaration {
+  return isMember(HOST_DECLARATIONS, value);
+}
+
+export function isReactDeclaration(value: unknown): value is ReactDeclaration {
+  return isMember(REACT_DECLARATIONS, value);
+}
+
+export function isComponentDeclaration(value: unknown): value is ComponentDeclaration {
+  return isMember(COMPONENT_DECLARATIONS, value);
+}
+
+/**
+ * A sparse patch. Each field has three states, so a re-register never blanks one by omission:
+ * omitted keeps the stored value, "" clears it, a member of the set sets it.
+ */
+export interface DeclarationPatch {
+  readonly host?: HostDeclaration | "";
+  readonly react?: ReactDeclaration | "";
+  readonly components?: ComponentDeclaration | "";
+}
+
+function parseField<Value extends string>(
+  record: Record<string, unknown>,
+  field: DeclarationField,
+  set: readonly Value[],
+  guard: (value: unknown) => value is Value,
+  noun: string,
+): Value | "" | undefined {
+  if (!(field in record) || record[field] === undefined) return undefined;
+  const value = record[field];
+  if (value === "") return "";
+  if (!guard(value)) {
+    throw new Error(`${noun}'s ${field} is one of ${set.join(", ")}, or "" to clear it`);
+  }
+  return value;
+}
+
+/** A patch read off a record's own keys. Every field is optional; an empty patch is a patch
+ * that writes nothing, and a caller that needs one refused says so itself. */
+export function parseDeclarationPatch(
+  record: Record<string, unknown>,
+  noun: string,
+): DeclarationPatch {
+  const host = parseField(record, "host", HOST_DECLARATIONS, isHostDeclaration, noun);
+  const react = parseField(record, "react", REACT_DECLARATIONS, isReactDeclaration, noun);
+  const components = parseField(
+    record,
+    "components",
+    COMPONENT_DECLARATIONS,
+    isComponentDeclaration,
+    noun,
+  );
+  return {
+    ...(host !== undefined ? { host } : {}),
+    ...(react !== undefined ? { react } : {}),
+    ...(components !== undefined ? { components } : {}),
+  };
+}
+
+export function isEmptyDeclarationPatch(patch: DeclarationPatch): boolean {
+  return DECLARATION_FIELDS.every((field) => patch[field] === undefined);
+}
+
+/** A patch carried as one nested field, and undefined when the field is absent. */
+export function optionalDeclarationPatch(
+  record: Record<string, unknown>,
+  field: string,
+  noun: string,
+): DeclarationPatch | undefined {
+  if (!(field in record) || record[field] === undefined) return undefined;
+  return parseDeclarationPatch(asRecord(record[field], `${noun}'s ${field}`), `${noun}'s ${field}`);
+}
+
+/** A stored declaration as it is read back. No clearing state here: a cleared field is absent. */
+export function parseDeclaration(value: unknown, noun: string): Declaration {
+  const patch = parseDeclarationPatch(asRecord(value, noun), noun);
+  const host = patch.host === "" ? undefined : patch.host;
+  const react = patch.react === "" ? undefined : patch.react;
+  const components = patch.components === "" ? undefined : patch.components;
+  return {
+    ...(host !== undefined ? { host } : {}),
+    ...(react !== undefined ? { react } : {}),
+    ...(components !== undefined ? { components } : {}),
+  };
+}

package/src/operations/declare-route.ts

@@ -0,0 +1,66 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  DECLARATION_FIELDS,
+  isEmptyDeclarationPatch,
+  parseDeclaration,
+  parseDeclarationPatch,
+  type Declaration,
+  type DeclarationPatch,
+} from "./declaration";
+import {
+  asRecord,
+  optionalStringArray,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a declareRoute input";
+
+export interface DeclareRouteInput extends DeclarationPatch {
+  readonly operation: "declareRoute";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+}
+
+export function parseDeclareRouteInput(value: unknown): DeclareRouteInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "declareRoute", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const patch = parseDeclarationPatch(record, NOUN);
+  if (isEmptyDeclarationPatch(patch)) {
+    throw new Error(`${NOUN} changes at least one of ${DECLARATION_FIELDS.join(", ")}`);
+  }
+  return { operation: "declareRoute", protocol: PROTOCOL_VERSION, name, ...patch };
+}
+
+export function serializeDeclareRouteInput(input: DeclareRouteInput): string {
+  return JSON.stringify(input);
+}
+
+export interface DeclareRouteResult {
+  readonly name: string;
+  /** The fields this call wrote, which is every field the patch named. */
+  readonly wrote: readonly string[];
+  /** What the route declares after this call. A cleared field is absent. */
+  readonly declaration: Declaration;
+}
+
+export function parseDeclareRouteResult(value: unknown): DeclareRouteResult {
+  const record = asRecord(value, "a declareRoute result");
+  const name = requireString(record, "name", "a declareRoute result");
+  const wrote = optionalStringArray(
+    record,
+    "wrote",
+    "a declareRoute result",
+    DECLARATION_FIELDS.length,
+  );
+  if (wrote === undefined) throw new Error("a declareRoute result names the fields it wrote");
+  const declaration = parseDeclaration(record.declaration, "a declareRoute result's declaration");
+  return { name, wrote, declaration };
+}
+
+export function serializeDeclareRouteResult(result: DeclareRouteResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/delete-app.ts

@@ -0,0 +1,47 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { asRecord, requireOperation, requireProtocol, requireString } from "./parse-helpers";
+
+const NOUN = "a deleteApp input";
+
+export interface DeleteAppInput {
+  readonly operation: "deleteApp";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+}
+
+export function parseDeleteAppInput(value: unknown): DeleteAppInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "deleteApp", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  return { operation: "deleteApp", protocol: PROTOCOL_VERSION, name };
+}
+
+export function serializeDeleteAppInput(input: DeleteAppInput): string {
+  return JSON.stringify(input);
+}
+
+export interface DeleteAppResult {
+  readonly name: string;
+  readonly filesTrashed: boolean;
+  readonly recordsDropped: number;
+}
+
+export function parseDeleteAppResult(value: unknown): DeleteAppResult {
+  const record = asRecord(value, "a deleteApp result");
+  const name = requireString(record, "name", "a deleteApp result");
+  if (typeof record.filesTrashed !== "boolean")
+    throw new Error("a deleteApp result states whether its files were trashed");
+  if (
+    typeof record.recordsDropped !== "number" ||
+    !Number.isInteger(record.recordsDropped) ||
+    record.recordsDropped < 0
+  ) {
+    throw new Error("a deleteApp result counts the records it dropped");
+  }
+  return { name, filesTrashed: record.filesTrashed, recordsDropped: record.recordsDropped };
+}
+
+export function serializeDeleteAppResult(result: DeleteAppResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/delete-record.ts

@@ -0,0 +1,46 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  requireOperation,
+  requirePositiveInteger,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a deleteRecord input";
+
+export interface DeleteRecordInput {
+  readonly operation: "deleteRecord";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly id: number;
+}
+
+export function parseDeleteRecordInput(value: unknown): DeleteRecordInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "deleteRecord", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const id = requirePositiveInteger(record, "id", NOUN);
+  return { operation: "deleteRecord", protocol: PROTOCOL_VERSION, name, id };
+}
+
+export function serializeDeleteRecordInput(input: DeleteRecordInput): string {
+  return JSON.stringify(input);
+}
+
+export interface DeleteRecordResult {
+  readonly name: string;
+  readonly id: number;
+}
+
+export function parseDeleteRecordResult(value: unknown): DeleteRecordResult {
+  const record = asRecord(value, "a deleteRecord result");
+  const name = requireString(record, "name", "a deleteRecord result");
+  const id = requirePositiveInteger(record, "id", "a deleteRecord result");
+  return { name, id };
+}
+
+export function serializeDeleteRecordResult(result: DeleteRecordResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/describe-route.ts

@@ -0,0 +1,122 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  optionalBoolean,
+  optionalString,
+  optionalStringArray,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a describeRoute input";
+
+// Field caps, as characterized against the previous engine's storage.ts (SUMMARY_MAX, ABOUT_MAX,
+// DISPLAY_NAME_MAX, TAGS_MAX, and the icon column's 8-character trim).
+const DISPLAY_NAME_MAX = 60;
+const SUMMARY_MAX = 140;
+const ABOUT_MAX = 8000;
+const ICON_MAX = 8;
+const TAGS_MAX = 12;
+
+export interface DescribeRouteInput {
+  readonly operation: "describeRoute";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly displayName?: string;
+  readonly summary?: string;
+  readonly about?: string;
+  readonly icon?: string;
+  readonly tags?: readonly string[];
+  readonly pinned?: boolean;
+  /** The per-route gate on agent-initiated deletion (deleteApp). Carried here rather than as
+   * its own operation because it rides the same sparse-patch wire shape; the dispatch seam is
+   * what refuses to honor it from an agent session, not this parse. */
+  readonly allowAgentDelete?: boolean;
+}
+
+export function parseDescribeRouteInput(value: unknown): DescribeRouteInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "describeRoute", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const displayName = optionalString(record, "displayName", NOUN, DISPLAY_NAME_MAX);
+  const summary = optionalString(record, "summary", NOUN, SUMMARY_MAX);
+  const about = optionalString(record, "about", NOUN, ABOUT_MAX);
+  const icon = optionalString(record, "icon", NOUN, ICON_MAX);
+  const tags = optionalStringArray(record, "tags", NOUN, TAGS_MAX);
+  const pinned = optionalBoolean(record, "pinned", NOUN);
+  const allowAgentDelete = optionalBoolean(record, "allowAgentDelete", NOUN);
+  if (
+    [displayName, summary, about, icon, tags, pinned, allowAgentDelete].every(
+      (field) => field === undefined,
+    )
+  ) {
+    throw new Error(
+      `${NOUN} changes at least one of displayName, summary, about, icon, tags, pinned, allowAgentDelete`,
+    );
+  }
+  return {
+    operation: "describeRoute",
+    protocol: PROTOCOL_VERSION,
+    name,
+    ...(displayName !== undefined ? { displayName } : {}),
+    ...(summary !== undefined ? { summary } : {}),
+    ...(about !== undefined ? { about } : {}),
+    ...(icon !== undefined ? { icon } : {}),
+    ...(tags !== undefined ? { tags } : {}),
+    ...(pinned !== undefined ? { pinned } : {}),
+    ...(allowAgentDelete !== undefined ? { allowAgentDelete } : {}),
+  };
+}
+
+export function serializeDescribeRouteInput(input: DescribeRouteInput): string {
+  return JSON.stringify(input);
+}
+
+export interface RouteCard {
+  readonly displayName: string;
+  readonly summary?: string;
+  readonly about?: string;
+  readonly icon?: string;
+  readonly tags: readonly string[];
+  readonly pinned: boolean;
+}
+
+function parseRouteCard(value: unknown): RouteCard {
+  const record = asRecord(value, "a route card");
+  const displayName = requireString(record, "displayName", "a route card");
+  const summary = optionalString(record, "summary", "a route card");
+  const about = optionalString(record, "about", "a route card");
+  const icon = optionalString(record, "icon", "a route card");
+  const tags = optionalStringArray(record, "tags", "a route card", TAGS_MAX) ?? [];
+  const pinned = optionalBoolean(record, "pinned", "a route card");
+  if (pinned === undefined) throw new Error("a route card states whether the route is pinned");
+  return {
+    displayName,
+    ...(summary !== undefined ? { summary } : {}),
+    ...(about !== undefined ? { about } : {}),
+    ...(icon !== undefined ? { icon } : {}),
+    tags,
+    pinned,
+  };
+}
+
+export interface DescribeRouteResult {
+  readonly name: string;
+  readonly wrote: readonly string[];
+  readonly card: RouteCard;
+}
+
+export function parseDescribeRouteResult(value: unknown): DescribeRouteResult {
+  const record = asRecord(value, "a describeRoute result");
+  const name = requireString(record, "name", "a describeRoute result");
+  const wrote = optionalStringArray(record, "wrote", "a describeRoute result", 7);
+  if (wrote === undefined) throw new Error("a describeRoute result names the fields it wrote");
+  const card = parseRouteCard(record.card);
+  return { name, wrote, card };
+}
+
+export function serializeDescribeRouteResult(result: DescribeRouteResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/emit-event.ts

@@ -0,0 +1,66 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  optionalPositiveInteger,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "an emitEvent input";
+
+export interface EmitEventInput {
+  readonly operation: "emitEvent";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly action: string;
+  // Payload is JSON, validated at the boundary.
+  readonly payload: unknown;
+}
+
+export function parseEmitEventInput(value: unknown): EmitEventInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "emitEvent", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const action = requireString(record, "action", NOUN);
+  if (!("payload" in record)) throw new Error(`${NOUN} carries a payload`);
+  return {
+    operation: "emitEvent",
+    protocol: PROTOCOL_VERSION,
+    name,
+    action,
+    payload: record.payload,
+  };
+}
+
+export function serializeEmitEventInput(input: EmitEventInput): string {
+  return JSON.stringify(input);
+}
+
+export interface EmitEventResult {
+  readonly name: string;
+  readonly action: string;
+  /** Absent for an action the daemon takes as a report, which it answers without logging. */
+  readonly id?: number;
+  readonly delivered: number;
+}
+
+export function parseEmitEventResult(value: unknown): EmitEventResult {
+  const record = asRecord(value, "an emitEvent result");
+  const name = requireString(record, "name", "an emitEvent result");
+  const action = requireString(record, "action", "an emitEvent result");
+  const id = optionalPositiveInteger(record, "id", "an emitEvent result");
+  if (
+    typeof record.delivered !== "number" ||
+    !Number.isInteger(record.delivered) ||
+    record.delivered < 0
+  ) {
+    throw new Error("an emitEvent result counts how many subscribers it delivered to");
+  }
+  return { name, action, ...(id !== undefined ? { id } : {}), delivered: record.delivered };
+}
+
+export function serializeEmitEventResult(result: EmitEventResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/get-record.ts

@@ -0,0 +1,44 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { parseAppRecord, type AppRecord } from "./app-record";
+import {
+  asRecord,
+  requireOperation,
+  requirePositiveInteger,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a getRecord input";
+
+export interface GetRecordInput {
+  readonly operation: "getRecord";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly id: number;
+}
+
+export function parseGetRecordInput(value: unknown): GetRecordInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "getRecord", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const id = requirePositiveInteger(record, "id", NOUN);
+  return { operation: "getRecord", protocol: PROTOCOL_VERSION, name, id };
+}
+
+export function serializeGetRecordInput(input: GetRecordInput): string {
+  return JSON.stringify(input);
+}
+
+export interface GetRecordResult {
+  readonly record: AppRecord;
+}
+
+export function parseGetRecordResult(value: unknown): GetRecordResult {
+  const record = asRecord(value, "a getRecord result");
+  return { record: parseAppRecord(record.record) };
+}
+
+export function serializeGetRecordResult(result: GetRecordResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/get-snapshot.ts

@@ -0,0 +1,64 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  requireNonNegativeInteger,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+import { isVisibility, type Visibility } from "./visibility";
+
+const NOUN = "a getSnapshot input";
+
+export interface GetSnapshotInput {
+  readonly operation: "getSnapshot";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+}
+
+export function parseGetSnapshotInput(value: unknown): GetSnapshotInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "getSnapshot", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  return { operation: "getSnapshot", protocol: PROTOCOL_VERSION, name };
+}
+
+export function serializeGetSnapshotInput(input: GetSnapshotInput): string {
+  return JSON.stringify(input);
+}
+
+export interface SnapshotState {
+  readonly generatedAt: string;
+  readonly files: number;
+  readonly bytes: number;
+}
+
+export interface GetSnapshotResult {
+  readonly name: string;
+  readonly visibility: Visibility;
+  readonly snapshot: SnapshotState | null;
+}
+
+function parseSnapshotState(value: unknown, noun: string): SnapshotState | null {
+  if (value === null) return null;
+  const record = asRecord(value, `${noun}'s snapshot`);
+  const generatedAt = requireString(record, "generatedAt", `${noun}'s snapshot`);
+  const files = requireNonNegativeInteger(record, "files", `${noun}'s snapshot`);
+  const bytes = requireNonNegativeInteger(record, "bytes", `${noun}'s snapshot`);
+  return { generatedAt, files, bytes };
+}
+
+export function parseGetSnapshotResult(value: unknown): GetSnapshotResult {
+  const record = asRecord(value, "a getSnapshot result");
+  const name = requireString(record, "name", "a getSnapshot result");
+  if (!isVisibility(record.visibility))
+    throw new Error("a getSnapshot result names a known visibility");
+  if (!("snapshot" in record)) throw new Error("a getSnapshot result states its snapshot");
+  const snapshot = parseSnapshotState(record.snapshot, "a getSnapshot result");
+  return { name, visibility: record.visibility, snapshot };
+}
+
+export function serializeGetSnapshotResult(result: GetSnapshotResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/guidance.ts

@@ -0,0 +1,91 @@
+import {
+  asRecord,
+  optionalString,
+  optionalStringArray,
+  requireNonNegativeInteger,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a guidance block";
+const REGISTER_NOUN = "a guidance register";
+const LIBRARY_NOUN = "a guidance register library";
+const SECTION_MAX = 500;
+
+/** The design register the daemon found above an app: where the bundle is, and which of its
+ * artifacts exist. Absent fields are artifacts the bundle does not carry. */
+export interface Register {
+  /** The bundle directory, or the directory holding a single-file pin. */
+  readonly dir: string;
+  /** The document that states the register. */
+  readonly anchor: string;
+  /** A stylesheet carrying the register's token values. Copied into an app as its tokens.css. */
+  readonly theme?: string;
+  /** A stylesheet carrying the register's faces. Copied into an app as its fonts.css. */
+  readonly fonts?: string;
+  /** The canonical reference image. */
+  readonly reference?: string;
+  /** The exemplar ids, each pairing a document, an image, and the source it names. */
+  readonly exemplars?: readonly string[];
+  /** The signed-off component library and how many components it holds. */
+  readonly library?: { readonly dir: string; readonly count: number };
+}
+
+/** What an operation result teaches the calling session: short text plus sections the daemon
+ * computes from what is installed at call time. */
+export interface Guidance {
+  readonly text: string;
+  /** Every bare id an app may import, the same union listPackages reports. */
+  readonly packages?: readonly string[];
+  /** The subpath ids the components package's own exports map names. */
+  readonly components?: readonly string[];
+  /** The entry files this call wrote. Present iff the call scaffolded at least one. */
+  readonly scaffolded?: readonly string[];
+  /** The design register above the app. Present iff a walk up from the app found one. */
+  readonly register?: Register;
+}
+
+function parseLibrary(value: unknown): NonNullable<Register["library"]> {
+  const record = asRecord(value, LIBRARY_NOUN);
+  return {
+    dir: requireString(record, "dir", LIBRARY_NOUN),
+    count: requireNonNegativeInteger(record, "count", LIBRARY_NOUN),
+  };
+}
+
+export function parseRegister(value: unknown): Register {
+  const record = asRecord(value, REGISTER_NOUN);
+  const theme = optionalString(record, "theme", REGISTER_NOUN, SECTION_MAX);
+  const fonts = optionalString(record, "fonts", REGISTER_NOUN, SECTION_MAX);
+  const reference = optionalString(record, "reference", REGISTER_NOUN, SECTION_MAX);
+  const exemplars = optionalStringArray(record, "exemplars", REGISTER_NOUN, SECTION_MAX);
+  const library = record.library === undefined ? undefined : parseLibrary(record.library);
+  return {
+    dir: requireString(record, "dir", REGISTER_NOUN),
+    anchor: requireString(record, "anchor", REGISTER_NOUN),
+    ...(theme !== undefined ? { theme } : {}),
+    ...(fonts !== undefined ? { fonts } : {}),
+    ...(reference !== undefined ? { reference } : {}),
+    ...(exemplars !== undefined ? { exemplars } : {}),
+    ...(library !== undefined ? { library } : {}),
+  };
+}
+
+export function parseGuidance(value: unknown): Guidance {
+  const record = asRecord(value, NOUN);
+  const text = requireString(record, "text", NOUN);
+  const packages = optionalStringArray(record, "packages", NOUN, SECTION_MAX);
+  const components = optionalStringArray(record, "components", NOUN, SECTION_MAX);
+  const scaffolded = optionalStringArray(record, "scaffolded", NOUN, SECTION_MAX);
+  const register = record.register === undefined ? undefined : parseRegister(record.register);
+  return {
+    text,
+    ...(packages !== undefined ? { packages } : {}),
+    ...(components !== undefined ? { components } : {}),
+    ...(scaffolded !== undefined ? { scaffolded } : {}),
+    ...(register !== undefined ? { register } : {}),
+  };
+}
+
+export function serializeGuidance(guidance: Guidance): string {
+  return JSON.stringify(guidance);
+}