Fully parse the exported connection file with a Zod wire-format schema

[kmcginnes]

Description

Slice 2 of retiring the legacy RawConfiguration "god object" (epic #1839). The exported connection-file format (saveConfigurationToFile → import) borrowed the in-memory configuration shape via Pick<ConfigurationContextProps, ...>. That borrowing keeps the unused in-memory RawConfiguration.schema field alive, so it blocks the later slices.

This gives the on-disk format its own honest, self-contained definition, decoupled from the in-memory and persisted shapes so the wire format can evolve independently.

The core move: a single Zod schema in parseConnectionFile.ts is the source of truth. The type is inferred from the schema (ExportedConnectionFile = z.infer<schema>), so the runtime check and the static type can no longer drift apart — replacing the old hand-rolled type + throw-prone imperative validator (isValidConfigurationFile), which asserted a strong type it never fully checked and threw an uncaught TypeError on a malformed schema.vertices/edges instead of rejecting with the "Invalid File" toast.

Key properties of the schema:

• Lenient. Every level is a looseObject, so unknown and legacy fields — per-type styling, __inferred/__matches on prefixes, attribute dataType, optional connection fields — pass through untouched into the parsed output.
• Validating. Every value the type promises is actually checked: id, connection URL and query engine, and the structural shape of vertices/edges/prefixes/edge-connections. Both the connection url and the optional graphDbUrl are constrained to http(s) via Zod's built-in z.url({ protocol: /^https?$/ }) — graphDbUrl is forwarded verbatim as the proxy's request target, so an imported file must not be able to point it at another scheme.
• Produces ready-to-store values. Branded ids and types are applied in the schema via .transform(), and lastUpdate is coerced from its ISO string into a real Date via z.coerce.date(). The importer consumes the parsed output directly and drops its manual new Date(...) revival and field-by-field reconstruction.

The guard becomes a parser: parseConnectionFile(data): ExportedConnectionFile | null. The same ExportedConnectionFile type describes both ends of the round trip: the writer assigns a Date for lastUpdate and JSON.stringify serializes it to the ISO string the parser later coerces back — so one type covers the format without a separate input view.

Vertex and edge attributes are consistently optional and default to [].

Suggested reading order:

1. parseConnectionFile.ts — the Zod schema (source of truth), the inferred ExportedConnectionFile type, and parseConnectionFile (core change).
2. saveConfigurationToFile.ts — now typed against ExportedConnectionFile.
3. useImportConnectionFile.ts — consumes the parsed output directly; manual Date revival and per-field reads removed.
4. Tests + CONTEXT.md glossary entry.

Two small, accepted behavior changes:

• A connection-less export emits connection.url: "" instead of omitting url (forced by the type; aligns the writer with the parser, which requires url). This is a not-actually-reachable state and is pinned by a test noting it should disappear in a later slice.
• The connection URL is now whitespace-trimmed on parse (a property of z.url), where the old hand-rolled check passed the raw string through. The URL only ever originates from a file the app itself wrote, so this affects no real input; pinned by a test.

Validation

• pnpm checks passes (lint, format, types).
• pnpm test passes — full suite.
• Tests pin: the malformed-schema rejection (previously threw); branded/Date-coerced parsed output; unknown/legacy field passthrough; the attribute defaulting; the http(s) refinement of url and graphDbUrl; URL whitespace trimming; the on-disk lastUpdate ISO bytes (so the writer's lastUpdate type can change without altering the file); the save→parse round-trip (values, not just parseability); and the url: "" asymmetry. Backward-compat pins for legacy imports (__matches) and the embedded-schema envelope stay green.

Related Issues

• Closes Give exported connection files an explicit wire-format type #1840
• Part of epic Retire the legacy configuration god-object in favor of explicit connection and schema models #1839

Check List

• I confirm that my contribution is made under the terms of the Apache 2.0 license.
• I have verified pnpm checks passes with no errors.
• I have verified pnpm test passes with no failures.
• I have covered new added functionality with unit tests if necessary.
• I have updated documentation if necessary.