@kalada/provider-routing 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @kalada/provider-routing (experimental)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Two separate opt-in, dependency-free experimental capabilities: whole-document diagnostic
+routing and host-owned parser composition. Contract version
+`DIAGNOSTIC_CONTRACT_VERSION === 1` identifies this provisional diagnostic shape;
+the package is not a stable language kernel API. Changes to the experimental contract
+may require consumer updates. There is no implicit Expressions provider: install
+`@kalada/language-service` separately to opt into its Expressions adapter.
+
+```ts
+import { createDiagnosticRouter } from "@kalada/provider-routing";
+
+const router = createDiagnosticRouter([{
+  languageId: "my-language",
+  diagnose(document) {
+    return { status: "supported", diagnostics: [] };
+  },
+}]);
+const outcome = router.diagnose("my-language", {
+  uri: "file:///example.txt",
+  text: "hello",
+  version: 1,
+  environmentGeneration: "schema-1",
+});
+```
+
+The caller supplies an explicit language ID and whole-document snapshot for each request.
+`version` is a nonnegative safe integer document revision; `environmentGeneration` is a
+nonempty opaque identity for the caller's environment. The router copies and freezes
+the snapshot before invoking a provider. Callers must compare returned document identity
+with their *current* document and environment before displaying diagnostics; the router
+cannot discover a changed external environment. Duplicate or empty registrations,
+unknown language IDs, and malformed document identity throw. Registration reads the
+language ID once; providers should be trusted code, not downloaded plugins.
+
+`supported` carries an empty diagnostic list; `invalid` carries one or more diagnostics;
+`unsupported` has no diagnostics. Each diagnostic has an uppercase code and a half-open
+`[start, end)` UTF-16 offset range within the snapshot (including zero-width ranges).
+Malformed provider results become `invalid` with `PROVIDER_INVALID_RESULT`; thrown
+provider/accessor errors become `PROVIDER_FAILURE`. Input over 100,000 UTF-16 code units
+becomes `PROVIDER_SOURCE_LIMIT` without invoking the provider. At most 100 diagnostics
+are accepted; code length is at most 128, and URI/environment identity length at most
+2,048 code units. These limits are provisional, not calibrated platform budgets.
+Returned diagnostics and snapshots are frozen copies, not live provider values.
+
+`COMPOSITION_CONTRACT_VERSION === 1` identifies the separate provisional host-composition
+contract. A trusted host parser supplies **declared** slot offsets (not discovered by the
+router), a versioned host-language/grammar-position profile, allowlisted guest IDs and
+host-owned opening/closing markers. An explicit guest choice overrides the static profile
+default; neither may bypass the allowlist, and no selection means unsupported (no fallback).
+For reverse embedding, register a *separate* reverse host profile. The host keeps delimiters;
+the selected guest lexes its interior and returns its own opaque subtree, UTF-16 range,
+consumed stop, reason and diagnostics. Success requires `status: "valid"`,
+  `reason: "host-close"`, a progressing claimed interior, an actual host close at stop, no diagnostics and a subtree;
+`reason: "eof"` cannot authorize a tree. The router validates progress, local bounds, closing marker,
+ownership (including diagnostic codes/ranges), selection, currentness and cancellation before returning a navigable host/guest
+tree. It does not parse the host or know how to skip guest strings/comments: guests must
+implement their language's supported lexical boundary themselves and report the **first**
+applicable close in their grammar. A host may supply an independently known slot `maxStop`
+  to reject a later return; this optional safe UTF-16 offset may equal the interior start
+  for an early failure. The router does not scan guest text for earlier `}` (which
+might be quoted), nor can it detect a dishonest trusted provider's earlier neutral close
+  without such a bound. Bounded `unsupported`, `partial`, and `invalid` returns may stop at
+  the opening offset or EOF, even without a closing marker. They retain the guest reason
+  and copied owner-tagged diagnostics within `[start, stop]` (including zero-width at stop),
+  but do not consume a host close or authorize a sibling. Invalid bounds, owner, status or
+  diagnostics fail closed without guest diagnostics. Unsupported, partial, invalid, stale,
+  cancelled and budget outcomes have no tree and confer no emission/edit authority.
+
+```ts
+import { createCompositionRouter } from "@kalada/provider-routing";
+const router = createCompositionRouter([{
+  version: 1, hostLanguageId: "host", position: "expression",
+  open: "{", close: "}", allowedGuests: ["tiny"], defaultGuest: "tiny",
+}], [{ languageId: "tiny", parse({ start, meter }) {
+  meter.charge(3); // cooperative guest work, including nested calls
+  return { owner: "tiny", status: "valid", range: { start, end: start + 3 },
+    stop: start + 3, reason: "host-close", diagnostics: [], subtree: { kind: "tiny" } };
+} }]);
+const input = { uri: "file:///a", text: "{abc}", version: 1, environmentGeneration: "env" };
+const result = router.compose({ snapshot: input, hostLanguageId: "host",
+  slots: [{ position: "expression", start: 0 }], isCurrent: () => true,
+  limits: { work: 100, depth: 4, diagnostics: 10 } });
+```
+
+The router copies/freezes source identity and profile declarations; `isCurrent` must check
+the caller's live document **and environment** both before and after callbacks, and consumers
+must recheck before publishing. Optional `context` carries host-owned opaque expected-type
+and location facts, not type checking or permission to write. Nested compositions must pass
+the same meter. Host charges its own text and opening/closing markers once; guests charge
+  actual interior work (at least one unit for nonempty successful interior), including nested
+  calls, via that meter. Work/depth/diagnostic bounds are cooperative and qualitative, not a CPU or
+memory sandbox: never register untrusted executable providers. Guest subtrees and opaque
+context values are language/host-owned references, not deep-frozen or admitted artifacts.
+
+This package does **not** implement a host parser, generic AST/CST, type composition,
+expression evaluator, editor/LSP services, or CF01 completion (#108). The real Kalada
+adapter and independent packed two-guest proof belong to #145.
+Packed independent domain and Expressions opt-in cross-consumer proof is tracked by #137.
+
+### Experimental partial recovery (#151)
+
+Optionally pass `hostContinuation: { validate(input) { ... } }` to `compose` for a trusted
+host grammar to certify a connector to the **next predeclared slot**. The frozen input
+contains the copied snapshot, the guest-reported host `close` range, a frozen copy of the
+next slot and the same cooperative meter. After independently validating its own grammar
+between `close.end` and `nextSlot.start`, the host charges at least the connector's UTF-16
+length and returns `{ owner: hostLanguageId, range: { start: close.end,
+end: nextSlot.start } }`. A Boolean, a guessed slot, or scanning a guest interior is not
+proof. The router checks the original source's closing/opening markers, profile selection,
+bounded offsets, ordering, meter and live snapshot identity before invoking the next guest.
+
+Only a bounded, progressing `status: "partial", reason: "safe-host-close"` guest exit
+whose lexed stop points at the actual close can initiate recovery. The guest must account
+for its interior work on the shared meter; `invalid`, `unsupported`, EOF or ambiguous
+exits cannot resume. On a recovered `partial` outcome, `attempts` contain only failed
+guest exits as frozen owner-tagged bounded ranges/reasons/copied diagnostics;
+`candidates` contain only opaque language-owned nodes from independently valid siblings.
+A fully valid document has a `tree` instead of `attempts` or `candidates`. The failed
+subtree is never read. Neither `attempts` nor `candidates` is an authenticated host CST
+or the authoritative `tree`;
+they grant no lowering, emission, editing or publication authority. Consumers must recheck
+source/version/environment identity before displaying even diagnostic recovery data.
+No Formbar runtime or CF01 pass is implied; this is trusted cooperative code, not a sandbox.

package/dist/index.cjs

@@ -0,0 +1,539 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  COMPOSITION_CONTRACT_VERSION: () => COMPOSITION_CONTRACT_VERSION,
+  DIAGNOSTIC_CONTRACT_VERSION: () => DIAGNOSTIC_CONTRACT_VERSION,
+  createCompositionRouter: () => createCompositionRouter,
+  createDiagnosticRouter: () => createDiagnosticRouter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/composition-meter.ts
+var Meter = class {
+  work = 0;
+  depth = 0;
+  diagnostics = 0;
+  exhausted = false;
+  active = 0;
+  limits;
+  constructor(limits) {
+    this.limits = limits;
+  }
+  debit(key, amount, limit) {
+    if (this.exhausted || !Number.isSafeInteger(amount) || amount < 0 || this[key] + amount > limit) {
+      this.exhausted = true;
+      return false;
+    }
+    this[key] += amount;
+    return true;
+  }
+  charge(units) {
+    return this.debit("work", units, this.limits.work);
+  }
+  report(count) {
+    return this.debit("diagnostics", count, this.limits.diagnostics);
+  }
+  enter() {
+    if (this.exhausted || this.active >= this.limits.depth) {
+      this.exhausted = true;
+      return false;
+    }
+    this.active++;
+    this.depth = Math.max(this.depth, this.active);
+    return true;
+  }
+  leave() {
+    this.active--;
+  }
+};
+
+// src/composition-validation.ts
+var MAX_ID = 2048;
+var MAX_DIAGNOSTICS = 100;
+var id = (s) => typeof s === "string" && !!s.trim() && s.length <= MAX_ID;
+var offset = (n, length) => Number.isSafeInteger(n) && n >= 0 && n <= length;
+var range = (start, end) => Object.freeze({ start, end });
+function outcome(status, reason, document, diagnostics = []) {
+  return Object.freeze({
+    status,
+    reason,
+    snapshot: document,
+    diagnostics: Object.freeze([...diagnostics])
+  });
+}
+function checkpoint(request, document) {
+  if (request.isCancelled?.()) return "cancelled";
+  const original = request.snapshot;
+  if (original.uri !== document.uri || original.text !== document.text || original.version !== document.version || original.environmentGeneration !== document.environmentGeneration)
+    return "stale";
+  if (!request.isCurrent(document)) return "stale";
+}
+function declaredSlotsClear(slots, index, boundary, length) {
+  let previous = slots[index]?.start;
+  if (previous === void 0 || !offset(previous, length)) return false;
+  for (let i = index + 1; i < slots.length; i++) {
+    const start = slots[i]?.start;
+    if (start === void 0 || !offset(start, length)) return false;
+    if (start <= previous || start < boundary) return false;
+    previous = start;
+  }
+  return true;
+}
+function boundedExit(result, owner, start, length, maxStop) {
+  const stop = result?.stop;
+  return result?.owner === owner && offset(stop, length) && stop >= start && (maxStop === void 0 || stop <= maxStop) && result.range?.start === start && result.range?.end === stop && typeof result.reason === "string" && !!result.reason && (result.status === "valid" || result.status === "invalid" || result.status === "partial" || result.status === "unsupported");
+}
+function snapshot(input) {
+  const copy = Object.freeze({
+    uri: input?.uri,
+    text: input?.text,
+    version: input?.version,
+    environmentGeneration: input?.environmentGeneration
+  });
+  if (!id(copy.uri) || typeof copy.text !== "string" || !Number.isSafeInteger(copy.version) || copy.version < 0 || !id(copy.environmentGeneration))
+    throw new Error("Invalid snapshot");
+  return copy;
+}
+function profileCopy(p) {
+  const allowedGuests = [...p.allowedGuests];
+  if (p.version !== 1 || !id(p.hostLanguageId) || !id(p.position) || !id(p.open) || !id(p.close) || !allowedGuests.length || allowedGuests.some((guest) => !id(guest)) || new Set(allowedGuests).size !== allowedGuests.length || p.defaultGuest !== void 0 && !allowedGuests.includes(p.defaultGuest))
+    throw new Error("Invalid or ambiguous composition profile");
+  return Object.freeze({
+    version: 1,
+    hostLanguageId: p.hostLanguageId,
+    position: p.position,
+    open: p.open,
+    close: p.close,
+    defaultGuest: p.defaultGuest,
+    allowedGuests: Object.freeze(allowedGuests)
+  });
+}
+function diagnosticCopy(items, regionStart, stop, owner) {
+  if (!Array.isArray(items) || items.length > MAX_DIAGNOSTICS) return;
+  const result = [];
+  for (const item of items) {
+    const code = item?.code, start = item?.range?.start, end = item?.range?.end;
+    if (typeof code !== "string" || code.length > 128 || !/^[A-Z][A-Z0-9_]*$/u.test(code) || item?.owner !== owner || !offset(start, stop) || !offset(end, stop) || start < regionStart || end < start)
+      return;
+    result.push(Object.freeze({ owner, code, range: range(start, end) }));
+  }
+  return Object.freeze(result);
+}
+
+// src/composition-recovery.ts
+function clearBoundary(request, document, index, end) {
+  return declaredSlotsClear(request.slots, index, end, document.text.length);
+}
+function clearFailure(request, document, index, failed) {
+  if (!failed.attempt) return true;
+  const end = failed.safe ? failed.safe.stop + failed.safe.profile.close.length : failed.attempt.range.end;
+  return clearBoundary(request, document, index, end);
+}
+function recoveryFailure(request, document, index, failed, attempts, candidates, reason) {
+  if (["budget", "stale", "cancelled"].includes(failed.outcome.status))
+    return { outcome: failed.outcome };
+  if (!clearFailure(request, document, index, failed))
+    return { outcome: outcome("invalid", "OVERLAPPING_SLOT", document) };
+  if (failed.attempt) attempts.push(failed.attempt);
+  if (failed.safe && index + 1 < request.slots.length) return { safe: failed.safe };
+  return { outcome: partial(document, reason, attempts, candidates) };
+}
+function attempt(result, diagnostics) {
+  return Object.freeze({
+    owner: result.owner,
+    range: Object.freeze({ start: result.range.start, end: result.stop }),
+    status: result.status,
+    reason: result.reason,
+    diagnostics
+  });
+}
+function partial(document, reason, attempts, candidates) {
+  return Object.freeze({
+    status: "partial",
+    reason,
+    snapshot: document,
+    diagnostics: Object.freeze(attempts.flatMap((item) => item.diagnostics)),
+    attempts: Object.freeze([...attempts]),
+    candidates: Object.freeze([...candidates])
+  });
+}
+function connectorInput(document, meter, stop, start, next) {
+  return Object.freeze({
+    snapshot: document,
+    close: Object.freeze({ start: stop, end: start }),
+    nextSlot: Object.freeze({
+      position: next.position,
+      start: next.start,
+      maxStop: next.maxStop,
+      explicitGuest: next.explicitGuest
+    }),
+    meter
+  });
+}
+function connector(request, document, meter, stop, profile, next) {
+  const continuation = request.hostContinuation;
+  const start = stop + profile.close.length;
+  if (!continuation || typeof continuation.validate !== "function" || !Number.isSafeInteger(next?.start) || next.start < start || next.start > document.text.length)
+    return false;
+  if (!meter.enter()) return false;
+  let value;
+  const before = meter.work;
+  try {
+    value = continuation.validate(connectorInput(document, meter, stop, start, next));
+  } finally {
+    meter.leave();
+  }
+  const owner = value?.owner;
+  const range2 = value?.range;
+  const from = range2?.start;
+  const to = range2?.end;
+  return !meter.exhausted && owner === request.hostLanguageId && from === start && to === next.start && meter.work - before >= to - from;
+}
+
+// src/composition.ts
+var MAX_TEXT = 1e5;
+var MAX_WORK = 1e6;
+var MAX_DEPTH = 32;
+var MAX_DIAGNOSTICS2 = 100;
+function select(slot, host, profiles, guests) {
+  const profile = profiles.find((p) => p.hostLanguageId === host && p.position === slot.position);
+  if (!profile) return;
+  const chosen = slot.explicitGuest ?? profile.defaultGuest;
+  if (!chosen || !profile.allowedGuests.includes(chosen)) return;
+  const guest = guests.get(chosen);
+  return guest ? { profile, guest } : void 0;
+}
+function node(owner, start, end, children = [], subtree) {
+  return Object.freeze({
+    owner,
+    range: range(start, end),
+    children: Object.freeze([...children]),
+    subtree
+  });
+}
+function createCompositionRouter(profiles, providers) {
+  const registered = profiles.map(profileCopy);
+  const keys = registered.map((p) => `${p.hostLanguageId}\0${p.position}`);
+  if (new Set(keys).size !== keys.length) throw new Error("Overlapping host positions");
+  const guests = /* @__PURE__ */ new Map();
+  for (const provider of providers) {
+    const languageId = provider?.languageId, parse = provider?.parse;
+    if (!id(languageId) || typeof parse !== "function" || guests.has(languageId))
+      throw new Error("Invalid or duplicate guest");
+    guests.set(languageId, Object.freeze({ languageId, parse: parse.bind(provider) }));
+  }
+  return Object.freeze({
+    compose(request) {
+      const document = snapshot(request.snapshot);
+      const limits = Object.freeze({ ...request.limits });
+      if (!Number.isSafeInteger(limits.work) || limits.work < 1 || limits.work > MAX_WORK || !Number.isSafeInteger(limits.depth) || limits.depth < 1 || limits.depth > MAX_DEPTH || !Number.isSafeInteger(limits.diagnostics) || limits.diagnostics < 0 || limits.diagnostics > MAX_DIAGNOSTICS2)
+        throw new Error("Invalid budget");
+      const meter = request.meter ?? new Meter(limits);
+      try {
+        return compose(request, document, meter, registered, guests);
+      } catch {
+        return outcome("invalid", "COMPOSITION_FAILURE", document);
+      }
+    }
+  });
+}
+function compose(request, document, meter, profiles, guests) {
+  const state = checkpoint(request, document);
+  if (state) return outcome(state, state, document);
+  if (document.text.length > MAX_TEXT) return outcome("budget", "SOURCE_LIMIT", document);
+  if (!id(request.hostLanguageId) || !Array.isArray(request.slots) || request.slots.length > MAX_DIAGNOSTICS2)
+    return outcome("invalid", "INVALID_HOST", document);
+  if (!meter.enter()) return outcome("budget", "DEPTH_LIMIT", document);
+  try {
+    return walk(request, document, meter, profiles, guests);
+  } finally {
+    meter.leave();
+  }
+}
+function walk(request, document, meter, profiles, guests) {
+  const children = [];
+  let cursor = 0;
+  for (const [index, slot] of request.slots.entries()) {
+    const state = checkpoint(request, document);
+    if (state) return outcome(state, state, document);
+    if (!offset(slot?.start, document.text.length) || slot.start < cursor)
+      return outcome("invalid", "OVERLAPPING_SLOT", document);
+    const processed = processSlot(request, document, meter, profiles, guests, slot, cursor);
+    if ("outcome" in processed)
+      return walkFailure(request, document, meter, profiles, guests, index, processed);
+    const { start, stop, close, guest, subtree } = processed;
+    if (!clearBoundary(request, document, index, stop + close.length))
+      return outcome("invalid", "OVERLAPPING_SLOT", document);
+    if (slot.start > cursor) children.push(node(request.hostLanguageId, cursor, slot.start));
+    children.push(node(request.hostLanguageId, slot.start, start));
+    children.push(node(guest, start, stop, [], subtree));
+    cursor = stop + close.length;
+    children.push(node(request.hostLanguageId, stop, cursor));
+  }
+  return finishWalk(request, document, meter, children, cursor);
+}
+function walkFailure(request, document, meter, profiles, guests, index, failed) {
+  if (!clearFailure(request, document, index, failed))
+    return outcome("invalid", "OVERLAPPING_SLOT", document);
+  return failed.safe && request.hostContinuation && index + 1 < request.slots.length ? recover(request, document, meter, profiles, guests, index, failed) : failed.outcome;
+}
+function finishWalk(request, document, meter, children, cursor) {
+  if (!meter.charge(document.text.length - cursor) || meter.exhausted)
+    return outcome("budget", "WORK_LIMIT", document);
+  const state = checkpoint(request, document);
+  if (state) return outcome(state, state, document);
+  if (cursor < document.text.length)
+    children.push(node(request.hostLanguageId, cursor, document.text.length));
+  return Object.freeze({
+    status: "valid",
+    reason: "complete",
+    snapshot: document,
+    diagnostics: Object.freeze([]),
+    tree: node(request.hostLanguageId, 0, document.text.length, children)
+  });
+}
+function resumeSlot(request, document, meter, profiles, guests, slot, previous) {
+  const state = checkpoint(request, document);
+  if (state) return { outcome: outcome(state, state, document) };
+  if (!slot) return { outcome: outcome("invalid", "MISSING_SLOT", document) };
+  const entry = select(slot, request.hostLanguageId, profiles, guests);
+  if (!entry || !document.text.startsWith(entry.profile.open, slot.start))
+    return { outcome: outcome("invalid", "MISSING_NEXT_OPEN", document) };
+  if (!previous.closeCharged && !meter.charge(previous.profile.close.length))
+    return { outcome: outcome("budget", "WORK_OR_DIAGNOSTIC_LIMIT", document) };
+  if (!connector(request, document, meter, previous.stop, previous.profile, slot))
+    return {
+      outcome: outcome(meter.exhausted ? "budget" : "invalid", "CONNECTOR_REJECTED", document)
+    };
+  const after = checkpoint(request, document);
+  if (after) return { outcome: outcome(after, after, document) };
+  return processSlot(request, document, meter, profiles, guests, slot, slot.start);
+}
+function recover(request, document, meter, profiles, guests, index, failed) {
+  const attempts = [failed.attempt];
+  const candidates = [];
+  let previous = {
+    ...failed.safe,
+    closeCharged: false
+  };
+  for (let i = index + 1; i < request.slots.length; i++) {
+    const slot = request.slots[i];
+    const processed = resumeSlot(request, document, meter, profiles, guests, slot, previous);
+    if ("outcome" in processed) {
+      const decision = recoveryFailure(
+        request,
+        document,
+        i,
+        processed,
+        attempts,
+        candidates,
+        failed.outcome.reason
+      );
+      if (decision.outcome) return decision.outcome;
+      previous = { ...decision.safe, closeCharged: false };
+      continue;
+    }
+    if (!clearBoundary(request, document, i, processed.stop + processed.close.length))
+      return outcome("invalid", "OVERLAPPING_SLOT", document);
+    candidates.push(node(processed.guest, processed.start, processed.stop, [], processed.subtree));
+    previous = { stop: processed.stop, profile: processed.profile, closeCharged: true };
+  }
+  if (meter.exhausted) return outcome("budget", "WORK_LIMIT", document);
+  const state = checkpoint(request, document);
+  return state ? outcome(state, state, document) : partial(document, failed.outcome.reason, attempts, candidates);
+}
+function admit(result, entry, start, document, meter, maxStop, guestWork) {
+  const guestRange = result.range;
+  const value = {
+    owner: result.owner,
+    stop: result.stop,
+    range: { start: guestRange.start, end: guestRange.end },
+    reason: result.reason,
+    status: result.status,
+    diagnostics: result.diagnostics
+  };
+  if (!boundedExit(value, entry.guest.languageId, start, document.text.length, maxStop))
+    return { outcome: outcome("invalid", "INVALID_GUEST_EXIT", document) };
+  const copied = diagnosticCopy(value.diagnostics, start, value.stop, entry.guest.languageId);
+  if (!copied) return { outcome: outcome("invalid", "INVALID_GUEST_DIAGNOSTIC", document) };
+  if (!meter.report(copied.length) || meter.exhausted)
+    return { outcome: outcome("budget", "WORK_OR_DIAGNOSTIC_LIMIT", document) };
+  if (value.status !== "valid")
+    return {
+      outcome: outcome(value.status, value.reason, document, copied),
+      attempt: attempt(value, copied),
+      safe: value.status === "partial" && value.reason === "safe-host-close" && value.stop > start && guestWork >= value.stop - start && document.text.startsWith(entry.profile.close, value.stop) ? { stop: value.stop, profile: entry.profile } : void 0
+    };
+  return admitValid(result, value, copied, entry, start, document, meter, guestWork);
+}
+function admitValid(result, value, copied, entry, start, document, meter, guestWork) {
+  if (value.stop <= start || !document.text.startsWith(entry.profile.close, value.stop) || copied.length || value.reason !== "host-close" || !Number.isSafeInteger(guestWork) || guestWork < 1)
+    return { outcome: outcome("invalid", "INVALID_GUEST_EXIT", document) };
+  const subtree = result.subtree;
+  if (subtree === void 0)
+    return { outcome: outcome("invalid", "MISSING_GUEST_SUBTREE", document) };
+  if (!meter.charge(entry.profile.close.length))
+    return { outcome: outcome("budget", "WORK_OR_DIAGNOSTIC_LIMIT", document) };
+  return {
+    start,
+    stop: value.stop,
+    close: entry.profile.close,
+    profile: entry.profile,
+    guest: entry.guest.languageId,
+    subtree
+  };
+}
+function processSlot(request, document, meter, profiles, guests, slot, cursor) {
+  const entry = select(slot, request.hostLanguageId, profiles, guests);
+  if (!entry) return { outcome: outcome("unsupported", "UNDECLARED_GUEST_OR_POSITION", document) };
+  if (!document.text.startsWith(entry.profile.open, slot.start))
+    return { outcome: outcome("invalid", "MISSING_OPEN", document) };
+  const start = slot.start + entry.profile.open.length;
+  if (slot.maxStop !== void 0 && (!offset(slot.maxStop, document.text.length) || slot.maxStop < start))
+    return { outcome: outcome("invalid", "INVALID_MAX_STOP", document) };
+  if (!meter.charge(start - cursor) || !meter.enter())
+    return { outcome: outcome("budget", "WORK_OR_DEPTH_LIMIT", document) };
+  const workBefore = meter.work;
+  let result;
+  try {
+    result = entry.guest.parse(
+      Object.freeze({
+        snapshot: document,
+        start,
+        close: entry.profile.close,
+        context: slot.context && Object.freeze({
+          expectedType: slot.context.expectedType,
+          location: slot.context.location
+        }),
+        meter
+      })
+    );
+  } finally {
+    meter.leave();
+  }
+  const state = checkpoint(request, document);
+  if (state) return { outcome: outcome(state, state, document) };
+  if (meter.exhausted) return { outcome: outcome("budget", "GUEST_BUDGET", document) };
+  const work = meter.work - workBefore;
+  const admitted = admit(result, entry, start, document, meter, slot.maxStop, work);
+  const afterAdmission = checkpoint(request, document);
+  return afterAdmission ? { outcome: outcome(afterAdmission, afterAdmission, document) } : admitted;
+}
+
+// src/contracts.ts
+var COMPOSITION_CONTRACT_VERSION = 1;
+
+// src/index.ts
+var DIAGNOSTIC_CONTRACT_VERSION = 1;
+var MAX_TEXT2 = 1e5;
+var MAX_IDENTITY = 2048;
+var MAX_DIAGNOSTICS3 = 100;
+var MAX_CODE = 128;
+function invalid(code) {
+  return Object.freeze({
+    status: "invalid",
+    diagnostics: Object.freeze([
+      Object.freeze({ code, range: Object.freeze({ start: 0, end: 0 }) })
+    ])
+  });
+}
+function validDocument(value) {
+  return typeof value?.uri === "string" && value.uri.length > 0 && value.uri.length <= MAX_IDENTITY && typeof value.text === "string" && Number.isSafeInteger(value.version) && value.version >= 0 && typeof value.environmentGeneration === "string" && value.environmentGeneration.length > 0 && value.environmentGeneration.length <= MAX_IDENTITY;
+}
+function validDiagnostic(code, start, end, length) {
+  return /^[A-Z][A-Z0-9_]*$/u.test(code) && code.length <= MAX_CODE && Number.isSafeInteger(start) && Number.isSafeInteger(end) && start >= 0 && end >= start && end <= length;
+}
+function copyDiagnostic(item, length) {
+  const code = item?.code;
+  const range2 = item?.range;
+  const start = range2?.start;
+  const end = range2?.end;
+  if (typeof code !== "string" || typeof start !== "number" || typeof end !== "number" || !validDiagnostic(code, start, end, length))
+    return void 0;
+  return Object.freeze({ code, range: Object.freeze({ start, end }) });
+}
+function safeOutcome(value, length) {
+  const status = value?.status;
+  if (status === "unsupported") {
+    if ("diagnostics" in value) return invalid("PROVIDER_INVALID_RESULT");
+    return Object.freeze({ status: "unsupported" });
+  }
+  if (status !== "supported" && status !== "invalid") return invalid("PROVIDER_INVALID_RESULT");
+  const source = value.diagnostics;
+  if (!Array.isArray(source)) return invalid("PROVIDER_INVALID_RESULT");
+  const count = source.length;
+  if (!Number.isSafeInteger(count) || count < 0 || count > MAX_DIAGNOSTICS3)
+    return invalid("PROVIDER_INVALID_RESULT");
+  const diagnostics = [];
+  for (let index = 0; index < count; index++) {
+    const item = source[index];
+    const copied = copyDiagnostic(item, length);
+    if (!copied) return invalid("PROVIDER_INVALID_RESULT");
+    diagnostics.push(copied);
+  }
+  if (status === "supported" !== (diagnostics.length === 0))
+    return invalid("PROVIDER_INVALID_RESULT");
+  if (status === "supported")
+    return Object.freeze({ status: "supported", diagnostics: Object.freeze(diagnostics) });
+  return Object.freeze({ status: "invalid", diagnostics: Object.freeze(diagnostics) });
+}
+function createDiagnosticRouter(providers) {
+  const registered = /* @__PURE__ */ new Map();
+  for (const provider of providers) {
+    const languageId = provider?.languageId;
+    if (typeof languageId !== "string" || !languageId.trim())
+      throw new Error("Invalid language ID");
+    if (registered.has(languageId)) throw new Error("Duplicate language ID");
+    if (typeof provider.diagnose !== "function") throw new Error("Invalid provider");
+    registered.set(languageId, provider);
+  }
+  return Object.freeze({
+    diagnose(languageId, input) {
+      const provider = registered.get(languageId);
+      if (!provider) throw new Error("Unknown language ID");
+      const document = Object.freeze({
+        uri: input?.uri,
+        text: input?.text,
+        version: input?.version,
+        environmentGeneration: input?.environmentGeneration
+      });
+      if (!validDocument(document)) throw new Error("Invalid document identity");
+      let outcome2;
+      if (document.text.length > MAX_TEXT2) outcome2 = invalid("PROVIDER_SOURCE_LIMIT");
+      else {
+        try {
+          outcome2 = safeOutcome(provider.diagnose(document), document.text.length);
+        } catch {
+          outcome2 = invalid("PROVIDER_FAILURE");
+        }
+      }
+      return Object.freeze({ ...outcome2, languageId, document });
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  COMPOSITION_CONTRACT_VERSION,
+  DIAGNOSTIC_CONTRACT_VERSION,
+  createCompositionRouter,
+  createDiagnosticRouter
+});