@hydranium/protocol 1.0.0-next.10

package/src/observable-value.ts

@@ -0,0 +1,92 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type Disposable, type Event } from 'vscode-jsonrpc';
+
+/**
+ * A value that may change over the connection lifetime. `value` is the
+ * current snapshot; `onChange` fires when the snapshot is replaced.
+ *
+ * The dynamic source in practice is always a user-configurable setting (see
+ * the `Settings` producers, which bind one to a Langium configuration
+ * section), but the type is source-agnostic — a constant wrapped via
+ * {@link ObservableValue.of} is still an `ObservableValue`; its `onChange`
+ * simply never fires. Recognised structurally by {@link isObservableValue}.
+ */
+export interface ObservableValue<T> {
+   /**
+    * `readonly` means the holder cannot assign it, NOT that it is stable —
+    * a live cell backs this with a getter, so it must be read at the point of
+    * use. Copying it into a field at construction pins the snapshot and
+    * silently defeats the whole type. A setting-bound cell answers its declared
+    * default until the client's configuration fetch resolves, so an early read
+    * is a legitimate value rather than an error.
+    */
+   readonly value: T;
+   /**
+    * Fires when {@link value} is replaced, deduplicated by `Object.is`, so an
+    * unchanged push is not re-announced. Subscribing is OPTIONAL and usually
+    * unnecessary — reading `.value` per use already sees every change; the
+    * event is for consumers that must re-arm something a later read cannot fix
+    * (a timer already scheduled, a listener already registered).
+    *
+    * It never fires at all for a constant cell, so logic that lives only in an
+    * `onChange` handler does nothing when an adopter passes a plain value.
+    * Dispose what subscribing returns.
+    */
+   readonly onChange: Event<T>;
+}
+
+/**
+ * What a service option accepts: either a plain constant (one-shot, never
+ * changes) or an {@link ObservableValue}. Consumers normalise to a cell once
+ * via {@link ObservableValue.from} and read `.value` at the point of use.
+ */
+export type MaybeObservableValue<T> = T | ObservableValue<T>;
+
+const NOOP_DISPOSABLE: Disposable = Object.freeze({ dispose: () => undefined });
+
+/** An {@link Event} that never fires — the `onChange` of a constant cell. */
+const NEVER_EVENT: Event<never> = () => NOOP_DISPOSABLE;
+
+/**
+ * Type-guard discriminating a {@link MaybeObservableValue} into its {@link ObservableValue}
+ * arm. Returns `false` for primitives, `null`, and any non-object payload; for
+ * objects, requires both a `value` property and a callable `onChange` accessor
+ * (vscode-jsonrpc events are exposed as callable subscribers).
+ */
+export function isObservableValue<T>(input: MaybeObservableValue<T>): input is ObservableValue<T> {
+   if (input === null || typeof input !== 'object') {
+      return false;
+   }
+   const candidate = input as Partial<ObservableValue<T>>;
+   return 'value' in candidate && typeof candidate.onChange === 'function';
+}
+
+export namespace ObservableValue {
+   /**
+    * Wrap a constant as an {@link ObservableValue} whose `onChange` never
+    * fires. Adopters rarely need this — the constant arm of {@link MaybeObservableValue}
+    * already accepts a bare value; it exists for {@link from} and for tests
+    * that want an explicit cell.
+    */
+   export function of<T>(value: T): ObservableValue<T> {
+      return { value, onChange: NEVER_EVENT as Event<T> };
+   }
+
+   /**
+    * Normalise a {@link MaybeObservableValue} to an {@link ObservableValue}. Identity for a
+    * cell (preserving its live `value` getter + `onChange`); wraps a constant
+    * via {@link of}. The combinator a consumer calls once in its constructor
+    * so the rest of the class reads `.value` uniformly.
+    */
+   export function from<T>(input: MaybeObservableValue<T>): ObservableValue<T> {
+      return isObservableValue(input) ? input : of(input);
+   }
+}

package/src/patch-merge.ts

@@ -0,0 +1,165 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { applyPatch, compare, deepClone, getValueByPointer, type Operation as JsonPatchOperation } from 'fast-json-patch';
+
+/**
+ * Augment a user-intent JSON patch (computed `baseline → attempted`) with
+ * `test` ops so a strict `applyPatch` against freshly-fetched server state
+ * fails loudly when a foreign writer changed a path the user also changed.
+ *
+ * `fast-json-patch`'s `validateOperation: true` validates op structure and
+ * path resolvability but NOT the pre-existing value — a plain `replace` /
+ * `remove` silently overwrites whatever the foreign writer put there. For each
+ * `replace` / `remove` op we prepend a `test` op carrying the baseline value at
+ * that path, so a same-path divergence becomes a `TEST_OPERATION_FAILED` throw.
+ * The caller treats that as a real field-level conflict (drop + refetch) rather
+ * than silently clobbering the foreign edit.
+ *
+ * `add` ops are left unguarded: the path is new, so there is no baseline value
+ * to test against, and add-vs-add overlaps are out of scope for this floor.
+ *
+ * Used behind the framework's `ConflictError` contract by every reconcile
+ * path — the GLSP recording command's undo/redo and forward-write, via
+ * {@link ReconcilingConflictResolver}, and an adopter's form-widget save — so
+ * they share one collision-detection rule.
+ */
+export function augmentWithTestOps(baseline: object, userPatch: ReadonlyArray<JsonPatchOperation>): JsonPatchOperation[] {
+   const augmented: JsonPatchOperation[] = [];
+   for (const op of userPatch) {
+      if (op.op === 'replace' || op.op === 'remove') {
+         augmented.push({ op: 'test', path: op.path, value: getValueByPointer(baseline, op.path) });
+      }
+      augmented.push(op);
+   }
+   return augmented;
+}
+
+/**
+ * Outcome of {@link reconcileByPatchReplay}. The caller persists / re-baselines
+ * on `merged`, drops + surfaces the `fresh` root on `conflict`, and decides its
+ * own fallback (e.g. force-retry) on `no-op` / `unavailable`.
+ */
+export type ReconcileOutcome<T> =
+   | {
+        /** The replay succeeded: the foreign writer touched no path the user did. */
+        status: 'merged';
+        /**
+         * A fresh root built on the refetched server state, carrying both
+         * intents. It is NOT the caller's `attempted` root — re-baseline on
+         * this value, or the next write diffs against state the server never
+         * had.
+         */
+        merged: T;
+     }
+   | {
+        /**
+         * The user's root already equalled the baseline, so the version gate
+         * fired on drift that changed nothing. No refetch was performed and
+         * there is nothing to persist — retrying the same write reproduces it.
+         */
+        status: 'no-op';
+     }
+   | {
+        /** A guarded `test` op tripped: user and foreign writer touched one path. */
+        status: 'conflict';
+        /**
+         * The server's current root, refetched and unmodified — the user's
+         * intent was NOT applied to it. Surface it and drop the write; treating
+         * it as a merge result silently discards what the user typed.
+         */
+        fresh: T;
+     }
+   | {
+        /**
+         * The refetch produced nothing, so reconciliation could not be
+         * attempted at all. This says nothing about whether a conflict exists;
+         * the caller picks its own fallback (force-write, retry, surface).
+         */
+        status: 'unavailable';
+     };
+
+/**
+ * Shared three-way reconcile for a `ConflictError`: diff the user's intent
+ * (`baseline → attempted`), refetch the server's current root, and replay the
+ * intent on top under strict, {@link augmentWithTestOps}-guarded `applyPatch`.
+ *
+ * - `no-op` — the user's root equals the baseline, so the gate fired on a
+ *   benign version drift; nothing to replay (refetch is skipped).
+ * - `unavailable` — the refetch produced nothing; caller falls back.
+ * - `merged` — the foreign writer touched only paths the user did not; the
+ *   merged root carries both intents.
+ * - `conflict` — a same-path divergence tripped a `test` op; caller drops the
+ *   write and surfaces `fresh`.
+ *
+ * I/O is the caller's: `refetch` supplies the current root, and applying the
+ * `merged` result (update vs save, re-baseline, UI refresh) stays at the call
+ * site so form and GLSP paths keep their own persistence semantics.
+ */
+export async function reconcileByPatchReplay<T extends object>(
+   baseline: T,
+   attempted: T,
+   refetch: () => Promise<T | undefined>
+): Promise<ReconcileOutcome<T>> {
+   const userPatch = compare(baseline, attempted);
+   if (userPatch.length === 0) {
+      return { status: 'no-op' };
+   }
+   const fresh = await refetch();
+   if (!fresh) {
+      return { status: 'unavailable' };
+   }
+   try {
+      const merged = applyPatch(deepClone(fresh), augmentWithTestOps(baseline, userPatch), true).newDocument;
+      return { status: 'merged', merged };
+   } catch {
+      return { status: 'conflict', fresh };
+   }
+}
+
+/**
+ * Strategy for resolving a write that raced a foreign edit. One declarative
+ * choice covers every conflict site — `execute` forward-write `(before,
+ * after)`, `undo` `(after, before)`, `redo` `(before, after)`, and form / GLSP
+ * save `(lastSynced, newRoot)` — so adopters pick reconcile-vs-force once
+ * (by binding a resolver) rather than per call site.
+ */
+export interface ConflictResolver {
+   /**
+    * Reconcile the user's `baseline → attempted` intent against the current
+    * server state (`refetch`), returning a {@link ReconcileOutcome} the caller
+    * acts on (persist `merged`, drop on `conflict`, fall back on `no-op` /
+    * `unavailable`).
+    */
+   resolve<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
+}
+
+/**
+ * Default {@link ConflictResolver}: field-level three-way merge via
+ * {@link reconcileByPatchReplay}. A foreign edit to a different field is
+ * merged; a same-field collision is reported as a conflict rather than
+ * clobbered.
+ */
+export class ReconcilingConflictResolver implements ConflictResolver {
+   resolve<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
+      return reconcileByPatchReplay(baseline, attempted, refetch);
+   }
+}
+
+/**
+ * Last-writer-wins {@link ConflictResolver}: always reports the `attempted`
+ * state as merged, without refetching or guarding. Suitable for single-client
+ * tools or always-regenerated artifacts where a concurrent foreign edit may be
+ * overwritten. A foreign edit to any field is clobbered.
+ */
+export class ForceConflictResolver implements ConflictResolver {
+   async resolve<T extends object>(_baseline: T, attempted: T, _refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
+      return { status: 'merged', merged: attempted };
+   }
+}

package/src/profile-session.ts

@@ -0,0 +1,164 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type Clock, type Stopwatch } from './clock';
+import { Format, Logger, type LogThreshold } from './logger';
+
+/** One aggregated row of a {@link ProfileSession}: a scope id and its totals. */
+export interface ProfileRecord {
+   /** The scope id passed to {@link ProfileSession.scope}. */
+   id: string;
+   /** How many times a scope with this id ran. */
+   count: number;
+   /** Summed self-time across those runs (wall-clock minus nested scopes). */
+   selfMs: number;
+   /** Self-time as a percentage of the session's total wall-clock. */
+   selfPct: number;
+}
+
+/**
+ * An aggregating, parent-exclusive self-time profiler scoped to one operation.
+ *
+ * Unlike `Tracer.time`, which emits one log line per
+ * call and keeps the timeline, a {@link ProfileSession} collapses many
+ * {@link scope} calls into a compact per-id aggregate (count + self-time +
+ * self-%), then dumps it as line-based output through a {@link Logger}. It is
+ * the in-house analogue of Langium's `ProfilingTask` (per-rule / per-node-type
+ * self-time) but for the framework's own passes — integrity rules, GModel
+ * construction, the save/reconcile chain — that Langium's profiler does not
+ * cover.
+ *
+ * Spawned per operation via `tracer.profile(id)`, used, reported, discarded —
+ * it is stateful and op-scoped, which is why it is not a method on the
+ * long-lived {@link Logger}/`Tracer`.
+ */
+export interface ProfileSession {
+   /**
+    * Run `fn` as a measured task `id`, accumulating its self-time = wall-clock
+    * minus any nested {@link scope} calls. Re-entrant: an inner scope nests and
+    * its full duration is excluded from the enclosing id's self-time
+    * (parent-exclusive). Async `fn` is awaited so timing covers the full
+    * settle. Returns `fn`'s result unchanged; rethrows after recording the
+    * elapsed time of a throwing scope.
+    */
+   scope<T>(id: string, fn: () => Promise<T>): Promise<T>;
+   scope<T>(id: string, fn: () => T): T;
+
+   /**
+    * Emit the aggregate through the bound {@link Logger}: one line per id,
+    * sorted by self-time descending, plus an "unaccounted" remainder (the
+    * session wall-clock not attributed to any top-level scope). No-op when
+    * `logLevel` is suppressed by the global threshold (incl. `'off'`).
+    */
+   report(logLevel?: LogThreshold): void;
+
+   /** The same aggregate as structured records, for tests / programmatic use. */
+   records(): readonly ProfileRecord[];
+}
+
+interface ScopeFrame {
+   readonly id: string;
+   /** Session-stopwatch reading when this scope began. */
+   readonly start: number;
+   /** Wall-time consumed by nested scopes, excluded from this scope's self-time. */
+   childMs: number;
+}
+
+/**
+ * Default {@link ProfileSession}. Times against an injected {@link Clock} (so
+ * it is fake-clock deterministic in tests, unlike a raw `performance.now`) and
+ * dumps through an injected {@link Logger}.
+ */
+export class DefaultProfileSession implements ProfileSession {
+   /** Single monotonic timeline for the whole session; per-scope readings are deltas off it. */
+   protected readonly sessionStopwatch: Stopwatch;
+   protected readonly stack: ScopeFrame[] = [];
+   protected readonly entries = new Map<string, number[]>();
+
+   constructor(
+      protected readonly logger: Logger,
+      clock: Clock,
+      protected readonly identifier: string
+   ) {
+      this.sessionStopwatch = clock.stopwatch();
+   }
+
+   scope<T>(id: string, fn: () => Promise<T>): Promise<T>;
+   scope<T>(id: string, fn: () => T): T;
+   scope<T>(id: string, fn: () => T | Promise<T>): T | Promise<T> {
+      const frame: ScopeFrame = { id, start: this.sessionStopwatch.elapsedMs, childMs: 0 };
+      this.stack.push(frame);
+      let result: T | Promise<T>;
+      try {
+         result = fn();
+      } catch (error) {
+         this.closeFrame(frame);
+         throw error;
+      }
+      if (result instanceof Promise) {
+         return result.then(
+            value => {
+               this.closeFrame(frame);
+               return value;
+            },
+            error => {
+               this.closeFrame(frame);
+               throw error;
+            }
+         );
+      }
+      this.closeFrame(frame);
+      return result;
+   }
+
+   /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
+   protected closeFrame(frame: ScopeFrame): void {
+      this.stack.pop();
+      const duration = this.sessionStopwatch.elapsedMs - frame.start;
+      const parent = this.stack[this.stack.length - 1];
+      if (parent) {
+         parent.childMs += duration;
+      }
+      const selfMs = duration - frame.childMs;
+      const samples = this.entries.get(frame.id);
+      if (samples) {
+         samples.push(selfMs);
+      } else {
+         this.entries.set(frame.id, [selfMs]);
+      }
+   }
+
+   records(): readonly ProfileRecord[] {
+      const totalMs = this.sessionStopwatch.elapsedMs;
+      const records: ProfileRecord[] = [];
+      for (const [id, samples] of this.entries) {
+         const selfMs = samples.reduce((sum, value) => sum + value, 0);
+         records.push({ id, count: samples.length, selfMs, selfPct: totalMs > 0 ? (100 * selfMs) / totalMs : 0 });
+      }
+      return records.sort((left, right) => right.selfMs - left.selfMs);
+   }
+
+   report(logLevel: LogThreshold = 'debug'): void {
+      if (logLevel === 'off' || !Logger.isLevelEnabled(logLevel)) {
+         return;
+      }
+      const totalMs = this.sessionStopwatch.elapsedMs;
+      const records = this.records();
+      const emit = this.logger[logLevel].bind(this.logger);
+      for (const record of records) {
+         emit(`[profile ${this.identifier}] ${record.id} ×${record.count} ${Math.round(record.selfPct)}% ${Format.elapsed(record.selfMs)}`);
+      }
+      const accountedMs = records.reduce((sum, record) => sum + record.selfMs, 0);
+      const unaccountedMs = totalMs - accountedMs;
+      if (unaccountedMs >= 0.5) {
+         const pct = totalMs > 0 ? Math.round((100 * unaccountedMs) / totalMs) : 0;
+         emit(`[profile ${this.identifier}] (unaccounted) ${pct}% ${Format.elapsed(unaccountedMs)}`);
+      }
+   }
+}

package/src/profiling.ts

@@ -0,0 +1,113 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Neutral shape of a sampled-profile capture request. It lives in `protocol`
+ * (not the Node-only `@hydranium/core/node` capture implementation) because it
+ * crosses the wire — the data-server diagnostics `startProfiling` args extend it,
+ * and a frontend/CLI names the dimensions to capture. The implementation
+ * (`ProfileCapture`, the `node:inspector` session) stays in `@hydranium/core/node`.
+ */
+
+/** Which dimensions to capture, and the two sampling knobs. All off by default. */
+export interface ProfileCaptureOptions {
+   cpu?: boolean;
+   allocation?: boolean;
+   gc?: boolean;
+   eventLoopDelay?: boolean;
+   /** Also drop a retained `.heapsnapshot` at stop (for the memory analyzer). */
+   heapSnapshot?: boolean;
+   /** CPU sampling interval in µs (implementation default 1000). */
+   cpuIntervalMicros?: number;
+   /** Allocation sampling interval in bytes (implementation default 32768). */
+   allocationIntervalBytes?: number;
+}
+
+/*
+ * The manifest schema — the self-describing index over one profiling run's
+ * artefacts. It lives in `protocol` (not the Node-only `ProfilingRun` that writes
+ * it) so both the server-side assembler AND a Playwright-side assembler can share
+ * the shape without a `node`-only dependency chain. `ProfilingRun` re-exports
+ * these from `@hydranium/core/node`.
+ */
+
+export const PROFILING_SCHEMA_VERSION = 1;
+
+/**
+ * The locked, origin-first artefact kinds (the kind equals the artefact's filename stem).
+ * A closed union so a producer cannot emit a stale or typo'd kind and still
+ * compile — the drift the naming scheme forbids.
+ */
+export type ProfilingArtifactKind =
+   | 'server-cpu'
+   | 'server-alloc'
+   | 'server-heap'
+   | 'server-summary'
+   | 'server-latency'
+   | 'server-ast'
+   | 'server-memory-report'
+   | 'server-log'
+   | 'browser-runtime'
+   | 'browser-timeline'
+   | 'browser-heap'
+   | 'browser-console';
+
+/** One entry in the manifest — a captured file plus enough context for a skill to know what it is. */
+export interface ProfilingArtifact {
+   /** The artefact's origin-first kind; equals its filename stem. */
+   kind: ProfilingArtifactKind;
+   /** Path relative to the manifest (the artefact lives beside it in the session directory). */
+   path: string;
+   /** The window the artefact was captured in, when it is window-scoped. */
+   window?: string;
+   /** Pointer to a compact digest file for a heavy artefact (added by the digest emitters). */
+   digest?: string;
+}
+
+/** What a skill reads to know what to expect from a run (browser entries only in `app` mode, etc.). */
+export interface ProfilingEnvironment {
+   mode: 'harness' | 'app';
+   /** Whether a cgroup memory controller is present (running in a pod) vs local. */
+   container: boolean;
+   commit?: string;
+   workspace?: string;
+   node: string;
+   windows: { label: string; ms: number }[];
+}
+
+/** The `manifest.json` contents — the index over one run's artefacts. */
+export interface ProfilingManifest {
+   /**
+    * Always {@link PROFILING_SCHEMA_VERSION} as written; declared as `number`
+    * because a READER may be newer than the run it is opening. Check it before
+    * trusting any field — an older manifest can be missing fields this
+    * declaration says are required.
+    */
+   schemaVersion: number;
+   /**
+    * Names the session directory the manifest sits in, so it identifies a run
+    * without carrying an absolute path. Unique per run by construction (a
+    * timestamp when the caller supplies none), but nothing enforces that a
+    * caller-supplied id is not reused.
+    */
+   sessionId: string;
+   /**
+    * What the run was captured against — needed to know which artefacts to
+    * expect at all, since the browser kinds only occur in `app` mode, and to
+    * know whether two runs are comparable.
+    */
+   environment: ProfilingEnvironment;
+   /**
+    * Every file written beside the manifest. Presence is the only signal that a
+    * dimension was captured: an artefact for a dimension that was not requested
+    * is absent rather than empty, and a kind may occur more than once when the
+    * run has several windows.
+    */
+   artifacts: ProfilingArtifact[];
+}

package/src/project.ts

@@ -0,0 +1,125 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/**
+ * Cross-cutting domain type for the project tier — a descriptor-discovered,
+ * optionally versioned and dependency-aware sub-grouping of model files
+ * inside an LSP workspace folder.
+ *
+ * Owned by `@hydranium/protocol` (rather than `@hydranium/core`) so
+ * protocol consumers — including browser-bundle frontend code that
+ * imports the typed data-server proxy — pull this type without
+ * transitively depending on Langium. The `Project` shape is the structural
+ * baseline both the framework's runtime project tier (`ProjectManager` in
+ * `@hydranium/core`) and its wire-level surface (`DataServerProtocol`
+ * methods returning projects) agree on; collapsing them into one
+ * type eliminates a duplicate definition that would otherwise drift.
+ *
+ * **Project tier rationale.** Sits at a tier Langium itself deliberately
+ * does not provide. Langium's `WorkspaceManager` indexes all files in all
+ * workspace folders into one flat global scope; the maintainers have
+ * on-record stated they intend to keep it that way — see
+ * [Discussion #1375 — *Multiple Languages from different Projects*](https://github.com/eclipse-langium/langium/discussions/1375).
+ * This framework fills that gap so consumers don't have to reinvent it.
+ * Consumers that don't need projects bind `SingleProjectManager` and pay
+ * no cost — one synthetic project at runtime, no descriptor tracking,
+ * no events.
+ *
+ * **Extension model.** Adopters with richer per-project metadata declare a
+ * subtype `interface MyProject extends Project { ... }` and parameterise
+ * `ProjectManager<MyProject>` / `DataServer<TRoot, TDiagnostic, MyProject>`.
+ * The framework's structural read from a project is `id` (registry key,
+ * dependency-graph identity) plus optionally `dependencies` (visibility-
+ * closure walk); every other field is either wire metadata (`version`) or
+ * adopter-specific extension carried transparently through the typed
+ * surface. The framework imposes no format on extension fields — they
+ * ride on the JSON-RPC envelope as additional properties when crossing
+ * the wire.
+ */
+export interface Project {
+   /**
+    * Stable, unique identifier. Used as the lookup key in
+    * `ProjectManager.getProjectById` and as the value in
+    * {@link dependencies} entries that point at this project.
+    * Conventionally a name-plus-version string (e.g.
+    * `"example-dwh@1.0.0"`), but the framework imposes no format — any
+    * non-empty string works.
+    *
+    * The framework's internal identifier — map keys, visibility-set
+    * membership, dependency-declaration matching. Distinct from the
+    * user-facing {@link referenceName}; see there for why they are separate.
+    */
+   readonly id: string;
+
+   /**
+    * User-facing prefix used in qualified-name references that cross
+    * project boundaries. Composed by `NameProvider.getProjectQualifiedName`
+    * to produce the workspace-unique form that the linker resolves
+    * cross-project references against; emitted as the name of the
+    * `TieredAstNodeDescription` produced by
+    * `HydraniumScopeComputation.addExportedSymbol` when the project-
+    * qualified form differs from the document-qualified form.
+    *
+    * Set to {@link UNQUALIFIED_PROJECT_REFERENCE} (`''`) to contribute no
+    * prefix at all — see that constant for the semantics.
+    *
+    * **Why this is a separate field from {@link id}.** Two reasons:
+    *  1. Versioned ids (e.g. `"example-dwh@1.0.0"`) need un-versioned
+    *     names in reference syntax (`example-dwh.User.email`) — the
+    *     version pinning only matters for dependency declarations.
+    *  2. Names with grammar-illegal characters (dots, spaces) need
+    *     sanitisation. The framework cannot safely sanitise {@link id}
+    *     (it would break dependency matching); a separate field lets
+    *     adopters sanitise once at parse time.
+    */
+   readonly referenceName: string;
+
+   /**
+    * Optional semantic version of the project. Distinct from {@link id}
+    * because two versions of the same logical project are different
+    * projects (different {@link id}s) — `version` is metadata for tooling /
+    * display / version-matched dependency declarations, not part of
+    * identity. The framework does not read this field internally; it
+    * passes through to clients as-is.
+    */
+   readonly version?: string;
+
+   /**
+    * Ids of other projects this project explicitly depends on. Concrete
+    * `ProjectManager` implementations decide what "depends on" means
+    * and combine these into the visibility closure via
+    * `ProjectManager.getVisibleProjects` — the framework default in
+    * `AbstractProjectManager` walks them transitively; adopters can
+    * override.
+    */
+   readonly dependencies?: readonly string[];
+}
+
+/**
+ * Sentinel value for {@link Project.referenceName} indicating the
+ * project does not prefix its names with a reference segment. Names
+ * from such projects contribute to the workspace-wide namespace as-is —
+ * `NameProvider.getProjectQualifiedName` collapses to
+ * `getDocumentQualifiedName`, and `HydraniumScopeComputation` emits a
+ * single description per node (no separate `tier: 'public'` entry,
+ * since it would carry the same name).
+ *
+ * Typical use:
+ * - `SingleProjectManager` workspaces (no inter-project disambiguation
+ *   needed — there is only one project, the synthetic workspace project).
+ * - Adopters whose grammar has no qualified-name reference syntax (e.g.
+ *   class references written as bare `[Class:ID]` tokens at the framework
+ *   boundary; per-package projects all bind this sentinel).
+ *
+ * The empty string is chosen so that `referenceName + nameSeparator + name`
+ * compositions detect the unqualified case without an explicit null
+ * check on the consumer side — but for predicate readability prefer
+ * `ProjectManager.isUnqualifiedProjectReference(uri)`.
+ */
+export const UNQUALIFIED_PROJECT_REFERENCE = '';