@hydranium/protocol 1.0.0-next.9 → 1.0.0-next.90

package/lib/messages/primitives.d.ts

@@ -0,0 +1,141 @@
+/********************************************************************************
+ * 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 { ResponseError } from 'vscode-jsonrpc';
+/**
+ * The framework externalizes user-facing strings and SELECTS no locale: it
+ * relays the one its client declared and renders with whatever templates the
+ * adopter installed, defaulting to its English. Every such string carries a
+ * stable code beside that English, and exactly one side renders it — the side
+ * that knows the reading user's language.
+ *
+ * Which side that is depends on the message, not on the package. A server
+ * message is rendered by the server, at the one seam every carrier passes
+ * through, in the locale it was handed at init. A message the client tier raises
+ * is rendered there, because those fire when the server is unreachable. Nothing
+ * is rendered twice: two renders of one sentence are two authorities over it,
+ * and they diverge on the first reword.
+ *
+ * Codes are `hydranium/<unscoped-package>/<name>`. The package segment locates
+ * the declaration, so a message is declared in the package that raises it and a
+ * code never names a package it does not live in. `.` and `:` are forbidden in a
+ * segment: they are i18next's default key and namespace separators, where either
+ * silently becomes a nested lookup that misses.
+ */
+export type MessageParams = Readonly<Record<string, string | number>>;
+type Placeholder<S extends string> = S extends `${string}{${infer Name}}${infer Rest}` ? Name | Placeholder<Rest> : never;
+export type ParamsOf<S extends string> = [Placeholder<S>] extends [never] ? Record<never, never> : Readonly<Record<Placeholder<S>, string | number>>;
+/** Required exactly when the text has placeholders, absent when it does not. */
+export type ParamsArg<S extends string> = [Placeholder<S>] extends [never] ? [] : [params: ParamsOf<S>];
+/**
+ * Rejects a text argument already widened to `string`. Load-bearing rather than
+ * defensive: the whole compile-time guarantee is conditional on `S` inferring a
+ * literal, and for a concatenated or pre-widened text the placeholder set
+ * silently becomes empty, `format()` accepts no arguments, and the missing
+ * substitution surfaces only at runtime.
+ */
+export type LiteralText<S extends string> = string extends S ? never : S;
+export interface MessageDefinition<S extends string> {
+    readonly code: string;
+    readonly text: S;
+    format(...args: ParamsArg<S>): string;
+}
+/**
+ * Declare a message. Placeholder names are inferred from `text` rather than
+ * declared again in a type argument: a second spelling of every name is the
+ * repetition that drifts, since adding a placeholder to the sentence and not to
+ * the type compiles.
+ */
+export declare function defineMessage<S extends string>(code: string, text: LiteralText<S>): MessageDefinition<S>;
+/**
+ * Substitute `{name}` tokens, leaving an unfilled token in place.
+ *
+ * It must not throw. This runs over an adopter's translation as well as our own
+ * text, so a typo in a foreign catalogue has to degrade to a slightly wrong
+ * sentence rather than raise inside a toast render. Re-scanning the result to
+ * detect an unfilled token is what an earlier form did, and it cannot work:
+ * `String.replace` does not rescan replacement text, so the check could not tell
+ * an unfilled placeholder from user data shaped like one — an element literally
+ * named `{separator}` crashed at the authoring site.
+ */
+export declare function interpolate(template: string, params: MessageParams): string;
+export interface MessageIdentity {
+    readonly code: string;
+    readonly params: MessageParams;
+}
+/**
+ * Envelope for a protocol `data` field. Namespaced under one key so it co-exists
+ * with a carrier's own `data` conventions rather than occupying `data` itself.
+ */
+export interface HydraniumMessageData {
+    readonly hydranium: MessageIdentity;
+}
+/** An identity plus its resolved English — everything a renderer needs, on any carrier. */
+export interface ResolvedMessage extends MessageIdentity {
+    readonly text: string;
+}
+export declare function messageData<S extends string>(message: MessageDefinition<S>, ...args: ParamsArg<S>): HydraniumMessageData;
+/**
+ * Identity plus resolved English, for a hand-off carrying a value rather than a
+ * protocol field. The result is structured-clone safe, so it survives a process
+ * hop where one intervenes and costs nothing where none does.
+ */
+export declare function resolve<S extends string>(message: MessageDefinition<S>, ...args: ParamsArg<S>): ResolvedMessage;
+/**
+ * Validates every field {@link MessageIdentity} declares, `params` included.
+ * A guard over foreign input that checks only `code` while declaring `params`
+ * non-optional hands `undefined` to the renderer, which fails with the worst
+ * polarity available: invisible in English, crashing only once a translation is
+ * loaded.
+ */
+export declare function hasMessageIdentity(data: unknown): data is HydraniumMessageData;
+/**
+ * A type alias rather than a subclass. Only `code`, `message` and `data` cross
+ * the wire, so a subclass buys nothing there: `instanceof` does not survive
+ * reconstruction, and the subclass costs an `Object.setPrototypeOf` in every
+ * constructor purely to undo what `ResponseError`'s own constructor does.
+ */
+export type HydraniumResponseError = ResponseError<HydraniumMessageData>;
+/**
+ * The numeric `code` and the message's catalogue code are unrelated and both are
+ * needed: `ResponseError.code` is an `integer`, so it cannot hold a
+ * `hydranium/…` key, and it is what a caller switches on after reconstruction.
+ */
+export declare function messageError<S extends string>(code: number, message: MessageDefinition<S>, ...params: ParamsArg<S>): HydraniumResponseError;
+/**
+ * Render on the side that knows the reading user's locale. `translations` is
+ * whatever flat `code → template` map the host exposes; omitting it is how an
+ * adopter without i18n opts out, and yields the English.
+ */
+export declare function renderFrameworkMessage(message: ResolvedMessage, translations?: Record<string, string>): string;
+export declare function resolvedFromResponseError(error: ResponseError<unknown>): ResolvedMessage | undefined;
+/**
+ * The detail half of a `{detail}` placeholder. A technical error string is safe
+ * to pass as a parameter for the same reason a number is: it is not itself
+ * translatable text, so it needs no code of its own. A PROSE fragment is not,
+ * and must become one code per value instead.
+ */
+export declare function describeError(error: unknown): string;
+/**
+ * Recognises a declaration among a barrel's exports. The `format` check is what
+ * discriminates: a `code` + `text` pair alone admits any object that happens to
+ * carry both.
+ */
+export declare function isMessageDeclaration(value: unknown): value is MessageDefinition<string>;
+/**
+ * Every declaration a `./messages` barrel exports.
+ *
+ * A caller cannot get there with `Object.values(barrel).filter(isMessageDeclaration)`:
+ * a barrel's value type is a union of its declarations AND its functions, and
+ * `filter` will not narrow a function type down to a `MessageDefinition`, so the
+ * result stays the union and reading `.code` off it does not compile. Taking the
+ * barrel as an opaque object is what makes the one-liner work.
+ */
+export declare function collectMessages(barrel: object): MessageDefinition<string>[];
+export {};
+//# sourceMappingURL=primitives.d.ts.map

package/lib/messages/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/messages/primitives.ts"],"names":[],"mappings":"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"}

package/lib/messages/primitives.js

@@ -0,0 +1,138 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineMessage = defineMessage;
+exports.interpolate = interpolate;
+exports.messageData = messageData;
+exports.resolve = resolve;
+exports.hasMessageIdentity = hasMessageIdentity;
+exports.messageError = messageError;
+exports.renderFrameworkMessage = renderFrameworkMessage;
+exports.resolvedFromResponseError = resolvedFromResponseError;
+exports.describeError = describeError;
+exports.isMessageDeclaration = isMessageDeclaration;
+exports.collectMessages = collectMessages;
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+/**
+ * Declare a message. Placeholder names are inferred from `text` rather than
+ * declared again in a type argument: a second spelling of every name is the
+ * repetition that drifts, since adding a placeholder to the sentence and not to
+ * the type compiles.
+ */
+function defineMessage(code, text) {
+    const literal = text;
+    return { code, text: literal, format: (...args) => interpolate(literal, args[0] ?? {}) };
+}
+const PLACEHOLDER = /\{([^}]+)\}/g;
+/**
+ * Substitute `{name}` tokens, leaving an unfilled token in place.
+ *
+ * It must not throw. This runs over an adopter's translation as well as our own
+ * text, so a typo in a foreign catalogue has to degrade to a slightly wrong
+ * sentence rather than raise inside a toast render. Re-scanning the result to
+ * detect an unfilled token is what an earlier form did, and it cannot work:
+ * `String.replace` does not rescan replacement text, so the check could not tell
+ * an unfilled placeholder from user data shaped like one — an element literally
+ * named `{separator}` crashed at the authoring site.
+ */
+function interpolate(template, params) {
+    // Indexed rather than `key in params`: a hand-built or version-skewed
+    // identity can arrive with no params at all, and `in` throws on a non-object
+    // where a lookup degrades.
+    const lookup = params;
+    return template.replace(PLACEHOLDER, (match, key) => {
+        const value = lookup?.[key];
+        return value === undefined ? match : String(value);
+    });
+}
+function messageData(message, ...args) {
+    return { hydranium: { code: message.code, params: args[0] ?? {} } };
+}
+/**
+ * Identity plus resolved English, for a hand-off carrying a value rather than a
+ * protocol field. The result is structured-clone safe, so it survives a process
+ * hop where one intervenes and costs nothing where none does.
+ */
+function resolve(message, ...args) {
+    return { code: message.code, text: message.format(...args), params: args[0] ?? {} };
+}
+/**
+ * Validates every field {@link MessageIdentity} declares, `params` included.
+ * A guard over foreign input that checks only `code` while declaring `params`
+ * non-optional hands `undefined` to the renderer, which fails with the worst
+ * polarity available: invisible in English, crashing only once a translation is
+ * loaded.
+ */
+function hasMessageIdentity(data) {
+    if (typeof data !== 'object' || data === null || Array.isArray(data) || !('hydranium' in data)) {
+        return false;
+    }
+    const identity = data.hydranium;
+    if (typeof identity !== 'object' || identity === null || Array.isArray(identity)) {
+        return false;
+    }
+    const candidate = identity;
+    return typeof candidate.code === 'string' && typeof candidate.params === 'object' && candidate.params !== null;
+}
+/**
+ * The numeric `code` and the message's catalogue code are unrelated and both are
+ * needed: `ResponseError.code` is an `integer`, so it cannot hold a
+ * `hydranium/…` key, and it is what a caller switches on after reconstruction.
+ */
+function messageError(code, message, ...params) {
+    return new vscode_jsonrpc_1.ResponseError(code, message.format(...params), messageData(message, ...params));
+}
+/**
+ * Render on the side that knows the reading user's locale. `translations` is
+ * whatever flat `code → template` map the host exposes; omitting it is how an
+ * adopter without i18n opts out, and yields the English.
+ */
+function renderFrameworkMessage(message, translations) {
+    const template = translations?.[message.code];
+    return template ? interpolate(template, message.params) : message.text;
+}
+function resolvedFromResponseError(error) {
+    return hasMessageIdentity(error.data) ? { ...error.data.hydranium, text: error.message } : undefined;
+}
+/**
+ * The detail half of a `{detail}` placeholder. A technical error string is safe
+ * to pass as a parameter for the same reason a number is: it is not itself
+ * translatable text, so it needs no code of its own. A PROSE fragment is not,
+ * and must become one code per value instead.
+ */
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Recognises a declaration among a barrel's exports. The `format` check is what
+ * discriminates: a `code` + `text` pair alone admits any object that happens to
+ * carry both.
+ */
+function isMessageDeclaration(value) {
+    const candidate = value;
+    return (typeof candidate === 'object' &&
+        candidate !== null &&
+        typeof candidate.code === 'string' &&
+        typeof candidate.text === 'string' &&
+        typeof candidate.format === 'function');
+}
+/**
+ * Every declaration a `./messages` barrel exports.
+ *
+ * A caller cannot get there with `Object.values(barrel).filter(isMessageDeclaration)`:
+ * a barrel's value type is a union of its declarations AND its functions, and
+ * `filter` will not narrow a function type down to a `MessageDefinition`, so the
+ * result stays the union and reading `.code` off it does not compile. Taking the
+ * barrel as an opaque object is what makes the one-liner work.
+ */
+function collectMessages(barrel) {
+    return Object.values(barrel).filter(isMessageDeclaration);
+}
+//# sourceMappingURL=primitives.js.map

package/lib/messages/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/messages/primitives.ts"],"names":[],"mappings":"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"}

package/lib/model-server.d.ts

@@ -46,8 +46,8 @@ export interface CloseModelArgs extends TransferClientArgs {
 export interface TransferUpdatedEvent<TDocument> {
     document: TDocument;
     sourceClientId: string;
-    /** See `ModelDocumentUpdateReason` in `./data/events` for the canonical reason set + semantics. */
-    reason: 'changed' | 'deleted' | 'rebuilt' | 'saved';
+    /** See `TransferDocumentUpdateReason` in `./data/events` for the canonical reason set + semantics. */
+    reason: 'changed' | 'rebuilt' | 'saved';
 }
 export interface TransferSavedEvent<TDocument> {
     /** The document as persisted — the state that reached disk, not the state at request time. */
@@ -114,10 +114,10 @@ export declare function isElementSource(object: unknown): object is ElementSourc
 /** An element of a document that does not yet exist on disk — used during element creation flows. */
 export interface SyntheticSource {
     /**
-     * The document the element would belong to. That document must already be
-     * LOADED — the default resolution takes its parse root as the synthetic
-     * node's container and answers `undefined` when it is not, so a URI for a
-     * file that exists on disk but was never opened resolves to nothing.
+     * The document the element would belong to. It need not be loaded, or
+     * exist — an unloaded URI materialises a transient empty document, so a
+     * folder is a valid anchor. A URI that IS loaded contributes that
+     * document's parse root as the container, putting its contents in scope.
      */
     uri: string;
     /**
@@ -126,6 +126,16 @@ export interface SyntheticSource {
      * it is what scoping filters candidates against.
      */
     type: string;
+    /**
+     * The grammar the element will belong to, as a language id.
+     *
+     * Optional because `uri` and `type` each answer on their own when
+     * unambiguous. Set it when neither is: a URI naming no file carries no
+     * extension to route on, and a `type` two grammars can produce identifies
+     * neither. Unset, such a source reaches the server's own policy, which
+     * answers the same way for every caller.
+     */
+    language?: string;
 }
 export declare function isSyntheticSource(object: unknown): object is SyntheticSource;
 /**
@@ -135,7 +145,7 @@ export declare function isSyntheticSource(object: unknown): object is SyntheticS
 export declare namespace ReferenceSource {
     function document(uri: string): DocumentSource;
     function element(name: string, type?: string): ElementSource;
-    function synthetic(uri: string, type: string): SyntheticSource;
+    function synthetic(uri: string, type: string, language?: string): SyntheticSource;
 }
 /**
  * One step in a synthetic navigation path from a {@link ReferenceSource}
@@ -329,9 +339,10 @@ export interface FindNextNameArgs {
      */
     uri: string;
     /**
-     * The AST `$type` of the element being named. Collisions are only looked for
-     * among elements of that same type, so the returned name may still be taken
-     * by an element of another type.
+     * The AST `$type` of the element being named. Collisions are looked for
+     * among elements of that type and of any subtype of it, so a supertype
+     * names a uniqueness scope its concrete types share; the returned name may
+     * still be taken by an element outside that hierarchy.
      */
     type: string;
     /**
@@ -348,5 +359,11 @@ export interface FindNextNameArgs {
      * See {@link NameTier} for what each tier covers.
      */
     tier?: NameTier;
+    /**
+     * The grammar to name under, routed as {@link SyntheticSource.language} —
+     * this call builds one. A caller that sets it there must set it here, or
+     * candidates and the name it proposes come from different grammars.
+     */
+    language?: string;
 }
 //# sourceMappingURL=model-server.d.ts.map

package/lib/model-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-server.d.ts","sourceRoot":"","sources":["../src/model-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model-server.d.ts","sourceRoot":"","sources":["../src/model-server.ts"],"names":[],"mappings":"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"}

package/lib/model-server.js

@@ -47,8 +47,10 @@ var ReferenceSource;
         return { name, type };
     }
     ReferenceSource.element = element;
-    function synthetic(uri, type) {
-        return { uri, type };
+    function synthetic(uri, type, language) {
+        // The key is omitted rather than set to `undefined`, so a source built
+        // without a language stays deep-equal to the two-argument form.
+        return language === undefined ? { uri, type } : { uri, type, language };
     }
     ReferenceSource.synthetic = synthetic;
 })(ReferenceSource || (exports.ReferenceSource = ReferenceSource = {}));

package/lib/model-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-server.js","sourceRoot":"","sources":["../src/model-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model-server.js","sourceRoot":"","sources":["../src/model-server.ts"],"names":[],"mappings":"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"}

package/lib/model-service/args.d.ts

@@ -17,6 +17,7 @@
  * `./model-server.ts` re-exports them, so an import from either path
  * resolves.
  */
+import type { BasedOn } from './based-on';
 /** Identifies a client-document binding. Every facade operation carries these fields. */
 export interface TransferClientArgs {
     /** Document URI. */
@@ -36,15 +37,16 @@ export interface TransferUpdateArgs<T> extends TransferClientArgs {
     /** Structured model root or its serialised textual form. */
     model: T | string;
     /**
-     * Optional based-on version: the text-document version this update
-     * was authored against. When set, the server compares against its
-     * current text-document version for `uri` and throws
-     * `ConflictError` on mismatch. Omit to opt out of the gate — mirrors
-     * LSP's `OptionalVersionedTextDocumentIdentifier` posture, intended
-     * for headless / CLI / batch tooling without a meaningful based-on
-     * version.
+     * What this update was authored against. A `SnapshotVersion` is compared
+     * against the server's current text-document version for `uri` and throws
+     * `ConflictError` on mismatch; `'anything'` writes unconditionally.
+     *
+     * **Required so that an ungated write is a decision rather than an
+     * omission.** An optional gate is indistinguishable from a forgotten one at
+     * the call site, and a file of twenty writes hides the one that lost the
+     * field. Nothing else here can see that, since the defect is an absence.
      */
-    baseVersion?: number;
+    basedOn: BasedOn;
 }
 /**
  * Persist a document to disk via the in-process facade. Same `model`
@@ -54,11 +56,10 @@ export interface TransferSaveArgs<T> extends TransferClientArgs {
     /** Structured model root or its serialised textual form. */
     model: T | string;
     /**
-     * Optional based-on version — same semantics as
-     * {@link TransferUpdateArgs.baseVersion}. `save` delegates the gating
-     * check to its inner `update`, so this field threads through to the
-     * same `ConflictError` site.
+     * Same semantics and same requirement as {@link TransferUpdateArgs.basedOn}.
+     * `save` delegates the gating check to its inner `update`, so this field
+     * threads through to the same `ConflictError` site.
      */
-    baseVersion?: number;
+    basedOn: BasedOn;
 }
 //# sourceMappingURL=args.d.ts.map

package/lib/model-service/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/model-service/args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;GAUG;AAEH,yFAAyF;AACzF,MAAM,WAAW,kBAAkB;IAChC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAC9D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAC5D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/model-service/args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,yFAAyF;AACzF,MAAM,WAAW,kBAAkB;IAChC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAC9D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,OAAO,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAC5D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;CACnB"}

package/lib/model-service/based-on.d.ts

@@ -0,0 +1,55 @@
+/********************************************************************************
+ * Copyright (c) 2026 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
+ ********************************************************************************/
+declare const snapshotMarker: unique symbol;
+/**
+ * A text-document version that came out of a SNAPSHOT read: a document
+ * envelope's `version`, which cannot move once the envelope exists.
+ *
+ * A plain number at runtime, usable anywhere a number is, and it travels the
+ * wire as one. The marker exists only so the compiler can tell it apart from a
+ * version read off a LIVE document, which is the same number type and is the
+ * defect the conflict gate exists to prevent: read at write time it is whatever
+ * the server is at now, which is the number the gate is about to compare it
+ * against, so the gate passes unconditionally and a concurrent edit is
+ * overwritten with nothing logged.
+ */
+export type SnapshotVersion = number & {
+    readonly [snapshotMarker]: true;
+};
+/**
+ * What a write declares it was based on: a version from a snapshot read, or
+ * `'anything'`.
+ *
+ * `'anything'` is a precondition that always holds — the write accepts whatever
+ * the server currently has, and therefore overwrites it. It is the honest
+ * answer wherever the write was authored against no particular server version,
+ * and a lie anywhere a reader handed the writer a document. The field carrying
+ * it is required, so an ungated write is a word someone chose rather than a
+ * field someone forgot.
+ */
+export type BasedOn = SnapshotVersion | 'anything';
+/**
+ * Whether `basedOn` names a version, and so arms the gate.
+ *
+ * Branch on this rather than on `basedOn !== 'anything'`, which reads as "not
+ * based on anything" — the opposite of what the branch tests.
+ */
+export declare function isSnapshotVersion(basedOn: BasedOn): basedOn is SnapshotVersion;
+/**
+ * Mark a version as having come from a snapshot read.
+ *
+ * **For the envelope constructors, not for callers.** Every door that builds a
+ * document envelope applies it on the way in, so anything a read returns
+ * already carries it and a writer never needs this. A caller reaching for it is
+ * asserting a provenance the compiler was about to deny — the read-late defect
+ * written out where a reviewer can see it.
+ */
+export declare function asSnapshotVersion(version: number): SnapshotVersion;
+export {};
+//# sourceMappingURL=based-on.d.ts.map

package/lib/model-service/based-on.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"based-on.d.ts","sourceRoot":"","sources":["../../src/model-service/based-on.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,eAAe,GAAG,UAAU,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,eAAe,CAE9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAElE"}

package/lib/model-service/based-on.js

@@ -0,0 +1,34 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSnapshotVersion = isSnapshotVersion;
+exports.asSnapshotVersion = asSnapshotVersion;
+/**
+ * Whether `basedOn` names a version, and so arms the gate.
+ *
+ * Branch on this rather than on `basedOn !== 'anything'`, which reads as "not
+ * based on anything" — the opposite of what the branch tests.
+ */
+function isSnapshotVersion(basedOn) {
+    return typeof basedOn === 'number';
+}
+/**
+ * Mark a version as having come from a snapshot read.
+ *
+ * **For the envelope constructors, not for callers.** Every door that builds a
+ * document envelope applies it on the way in, so anything a read returns
+ * already carries it and a writer never needs this. A caller reaching for it is
+ * asserting a provenance the compiler was about to deny — the read-late defect
+ * written out where a reviewer can see it.
+ */
+function asSnapshotVersion(version) {
+    return version;
+}
+//# sourceMappingURL=based-on.js.map

package/lib/model-service/based-on.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"based-on.js","sourceRoot":"","sources":["../../src/model-service/based-on.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AAqClF,8CAEC;AAWD,8CAEC;AArBD;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,OAAgB;IAC/C,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC;AACtC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAAC,OAAe;IAC9C,OAAO,OAA0B,CAAC;AACrC,CAAC"}

package/lib/model-service/index.d.ts

@@ -7,5 +7,6 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 export * from './args';
+export * from './based-on';
 export * from './reference-candidate';
 //# sourceMappingURL=index.d.ts.map

package/lib/model-service/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/model-service/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAOlF,cAAc,QAAQ,CAAC;AACvB,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/model-service/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAOlF,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC"}

package/lib/model-service/index.js

@@ -27,5 +27,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // argument types so both the framework facade and the data-server wire
 // protocol can structurally agree on the lifecycle shape.
 __exportStar(require("./args"), exports);
+__exportStar(require("./based-on"), exports);
 __exportStar(require("./reference-candidate"), exports);
 //# sourceMappingURL=index.js.map

package/lib/model-service/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/model-service/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,wEAAwE;AACxE,mEAAmE;AACnE,uEAAuE;AACvE,0DAA0D;AAE1D,yCAAuB;AACvB,wDAAsC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/model-service/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,wEAAwE;AACxE,mEAAmE;AACnE,uEAAuE;AACvE,0DAA0D;AAE1D,yCAAuB;AACvB,6CAA2B;AAC3B,wDAAsC"}