@kalada/provider-routing 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,171 @@
+/** Experimental host composition v1; offsets are UTF-16, half-open, in the original text. */
+declare const COMPOSITION_CONTRACT_VERSION = 1;
+interface CompositionSnapshot {
+    readonly uri: string;
+    readonly text: string;
+    readonly version: number;
+    readonly environmentGeneration: string;
+}
+interface CompositionRange {
+    readonly start: number;
+    readonly end: number;
+}
+interface CompositionDiagnostic {
+    readonly owner: string;
+    readonly code: string;
+    readonly range: CompositionRange;
+}
+interface CompositionProfile {
+    readonly version: 1;
+    readonly hostLanguageId: string;
+    readonly position: string;
+    readonly allowedGuests: readonly string[];
+    readonly defaultGuest?: string;
+    /** Host grammar owns the opening and closing text; guest owns only the interior. */
+    readonly open: string;
+    readonly close: string;
+}
+interface CompositionSlot {
+    readonly position: string;
+    readonly start: number;
+    /** Optional independent host-known upper bound for guest stop, including early failures; not inferred by scanning guest text. */
+    readonly maxStop?: number;
+    readonly explicitGuest?: string;
+    /** Host-owned opaque facts; neither router nor guest may derive write authority from them. */
+    readonly context?: Readonly<{
+        expectedType?: unknown;
+        location?: unknown;
+    }>;
+}
+interface CompositionMeter {
+    /** Shared cumulative work: host charges its own text/markers; guest charges its interior and nested work. */
+    readonly exhausted: boolean;
+    readonly work: number;
+    readonly depth: number;
+    readonly diagnostics: number;
+    charge(units: number): boolean;
+    report(count: number): boolean;
+    enter(): boolean;
+    leave(): void;
+}
+interface CompositionGuest {
+    readonly languageId: string;
+    parse(input: Readonly<{
+        snapshot: CompositionSnapshot;
+        start: number;
+        close: string;
+        context?: CompositionSlot["context"];
+        meter: CompositionMeter;
+    }>): GuestCompositionResult;
+}
+interface GuestCompositionResult {
+    readonly owner: string;
+    readonly status: "valid" | "invalid" | "partial" | "unsupported";
+    readonly range: CompositionRange;
+    /** Valid: first applicable host close. Nonvalid: bounded failure stop (possibly start or EOF). Always equals range.end. */
+    readonly stop: number;
+    /** Success requires "host-close"; nonvalid results retain a nonempty guest reason without granting continuation. */
+    readonly reason: string;
+    readonly diagnostics: readonly CompositionDiagnostic[];
+    readonly subtree?: unknown;
+}
+interface CompositionNode {
+    readonly owner: string;
+    readonly range: CompositionRange;
+    readonly children: readonly CompositionNode[];
+    /** Opaque language-owned parsed subtree. Never interpreted by the host router. */
+    readonly subtree?: unknown;
+}
+/** Attempt metadata is diagnostic only; it never authenticates a failed subtree. */
+interface CompositionAttempt {
+    readonly owner: string;
+    readonly range: CompositionRange;
+    readonly reason: string;
+    readonly status: GuestCompositionResult["status"];
+    readonly diagnostics: readonly CompositionDiagnostic[];
+}
+interface HostConnector {
+    readonly owner: string;
+    /** Host-owned original-source range from just after the safe close to the next opening. */
+    readonly range: CompositionRange;
+}
+interface HostContinuation {
+    validate(input: Readonly<{
+        snapshot: CompositionSnapshot;
+        close: CompositionRange;
+        nextSlot: Readonly<CompositionSlot>;
+        meter: CompositionMeter;
+    }>): HostConnector;
+}
+interface CompositionOutcome {
+    readonly status: "valid" | "invalid" | "partial" | "unsupported" | "stale" | "cancelled" | "budget";
+    readonly reason: string;
+    readonly snapshot: CompositionSnapshot;
+    readonly diagnostics: readonly CompositionDiagnostic[];
+    readonly tree?: CompositionNode;
+    /** Only on partial recovery; never equivalent to the authoritative tree. */
+    readonly attempts?: readonly CompositionAttempt[];
+    readonly candidates?: readonly CompositionNode[];
+}
+interface CompositionRequest {
+    readonly snapshot: CompositionSnapshot;
+    /** Must consult the caller's live identity, including environment, on both sides of callbacks. */
+    readonly isCurrent: (snapshot: CompositionSnapshot) => boolean;
+    readonly isCancelled?: () => boolean;
+    readonly hostLanguageId: string;
+    readonly slots: readonly CompositionSlot[];
+    readonly limits: Readonly<{
+        work: number;
+        depth: number;
+        diagnostics: number;
+    }>;
+    /** For a nested request, pass the parent's meter rather than allocating a fresh budget. */
+    readonly meter?: CompositionMeter;
+    /** Trusted host grammar, not a guest scanner; absent means no recovery continuation. */
+    readonly hostContinuation?: HostContinuation;
+}
+
+/** Registered callbacks are trusted/cooperative; this meter cannot preempt CPU or memory use. */
+declare function createCompositionRouter(profiles: readonly CompositionProfile[], providers: readonly CompositionGuest[]): Readonly<{
+    compose(request: CompositionRequest): CompositionOutcome;
+}>;
+
+/** Experimental diagnostic contract v1; not a parser, checker, or runtime API. */
+
+declare const DIAGNOSTIC_CONTRACT_VERSION = 1;
+interface DocumentSnapshot {
+    readonly uri: string;
+    readonly text: string;
+    readonly version: number;
+    readonly environmentGeneration: string;
+}
+interface Diagnostic {
+    readonly code: string;
+    readonly range: Readonly<{
+        readonly start: number;
+        readonly end: number;
+    }>;
+}
+type ProviderOutcome = {
+    readonly status: "supported";
+    readonly diagnostics: readonly Diagnostic[];
+} | {
+    readonly status: "invalid";
+    readonly diagnostics: readonly Diagnostic[];
+} | {
+    readonly status: "unsupported";
+    readonly diagnostics?: never;
+};
+interface DiagnosticProvider {
+    readonly languageId: string;
+    diagnose(document: DocumentSnapshot): ProviderOutcome;
+}
+type RoutedOutcome = ProviderOutcome & {
+    readonly languageId: string;
+    readonly document: DocumentSnapshot;
+};
+declare function createDiagnosticRouter(providers: readonly DiagnosticProvider[]): Readonly<{
+    diagnose(languageId: string, input: DocumentSnapshot): RoutedOutcome;
+}>;
+
+export { COMPOSITION_CONTRACT_VERSION, type CompositionAttempt, type CompositionDiagnostic, type CompositionGuest, type CompositionMeter, type CompositionNode, type CompositionOutcome, type CompositionProfile, type CompositionRange, type CompositionRequest, type CompositionSlot, type CompositionSnapshot, DIAGNOSTIC_CONTRACT_VERSION, type Diagnostic, type DiagnosticProvider, type DocumentSnapshot, type GuestCompositionResult, type HostConnector, type HostContinuation, type ProviderOutcome, type RoutedOutcome, createCompositionRouter, createDiagnosticRouter };

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+/** Experimental host composition v1; offsets are UTF-16, half-open, in the original text. */
+declare const COMPOSITION_CONTRACT_VERSION = 1;
+interface CompositionSnapshot {
+    readonly uri: string;
+    readonly text: string;
+    readonly version: number;
+    readonly environmentGeneration: string;
+}
+interface CompositionRange {
+    readonly start: number;
+    readonly end: number;
+}
+interface CompositionDiagnostic {
+    readonly owner: string;
+    readonly code: string;
+    readonly range: CompositionRange;
+}
+interface CompositionProfile {
+    readonly version: 1;
+    readonly hostLanguageId: string;
+    readonly position: string;
+    readonly allowedGuests: readonly string[];
+    readonly defaultGuest?: string;
+    /** Host grammar owns the opening and closing text; guest owns only the interior. */
+    readonly open: string;
+    readonly close: string;
+}
+interface CompositionSlot {
+    readonly position: string;
+    readonly start: number;
+    /** Optional independent host-known upper bound for guest stop, including early failures; not inferred by scanning guest text. */
+    readonly maxStop?: number;
+    readonly explicitGuest?: string;
+    /** Host-owned opaque facts; neither router nor guest may derive write authority from them. */
+    readonly context?: Readonly<{
+        expectedType?: unknown;
+        location?: unknown;
+    }>;
+}
+interface CompositionMeter {
+    /** Shared cumulative work: host charges its own text/markers; guest charges its interior and nested work. */
+    readonly exhausted: boolean;
+    readonly work: number;
+    readonly depth: number;
+    readonly diagnostics: number;
+    charge(units: number): boolean;
+    report(count: number): boolean;
+    enter(): boolean;
+    leave(): void;
+}
+interface CompositionGuest {
+    readonly languageId: string;
+    parse(input: Readonly<{
+        snapshot: CompositionSnapshot;
+        start: number;
+        close: string;
+        context?: CompositionSlot["context"];
+        meter: CompositionMeter;
+    }>): GuestCompositionResult;
+}
+interface GuestCompositionResult {
+    readonly owner: string;
+    readonly status: "valid" | "invalid" | "partial" | "unsupported";
+    readonly range: CompositionRange;
+    /** Valid: first applicable host close. Nonvalid: bounded failure stop (possibly start or EOF). Always equals range.end. */
+    readonly stop: number;
+    /** Success requires "host-close"; nonvalid results retain a nonempty guest reason without granting continuation. */
+    readonly reason: string;
+    readonly diagnostics: readonly CompositionDiagnostic[];
+    readonly subtree?: unknown;
+}
+interface CompositionNode {
+    readonly owner: string;
+    readonly range: CompositionRange;
+    readonly children: readonly CompositionNode[];
+    /** Opaque language-owned parsed subtree. Never interpreted by the host router. */
+    readonly subtree?: unknown;
+}
+/** Attempt metadata is diagnostic only; it never authenticates a failed subtree. */
+interface CompositionAttempt {
+    readonly owner: string;
+    readonly range: CompositionRange;
+    readonly reason: string;
+    readonly status: GuestCompositionResult["status"];
+    readonly diagnostics: readonly CompositionDiagnostic[];
+}
+interface HostConnector {
+    readonly owner: string;
+    /** Host-owned original-source range from just after the safe close to the next opening. */
+    readonly range: CompositionRange;
+}
+interface HostContinuation {
+    validate(input: Readonly<{
+        snapshot: CompositionSnapshot;
+        close: CompositionRange;
+        nextSlot: Readonly<CompositionSlot>;
+        meter: CompositionMeter;
+    }>): HostConnector;
+}
+interface CompositionOutcome {
+    readonly status: "valid" | "invalid" | "partial" | "unsupported" | "stale" | "cancelled" | "budget";
+    readonly reason: string;
+    readonly snapshot: CompositionSnapshot;
+    readonly diagnostics: readonly CompositionDiagnostic[];
+    readonly tree?: CompositionNode;
+    /** Only on partial recovery; never equivalent to the authoritative tree. */
+    readonly attempts?: readonly CompositionAttempt[];
+    readonly candidates?: readonly CompositionNode[];
+}
+interface CompositionRequest {
+    readonly snapshot: CompositionSnapshot;
+    /** Must consult the caller's live identity, including environment, on both sides of callbacks. */
+    readonly isCurrent: (snapshot: CompositionSnapshot) => boolean;
+    readonly isCancelled?: () => boolean;
+    readonly hostLanguageId: string;
+    readonly slots: readonly CompositionSlot[];
+    readonly limits: Readonly<{
+        work: number;
+        depth: number;
+        diagnostics: number;
+    }>;
+    /** For a nested request, pass the parent's meter rather than allocating a fresh budget. */
+    readonly meter?: CompositionMeter;
+    /** Trusted host grammar, not a guest scanner; absent means no recovery continuation. */
+    readonly hostContinuation?: HostContinuation;
+}
+
+/** Registered callbacks are trusted/cooperative; this meter cannot preempt CPU or memory use. */
+declare function createCompositionRouter(profiles: readonly CompositionProfile[], providers: readonly CompositionGuest[]): Readonly<{
+    compose(request: CompositionRequest): CompositionOutcome;
+}>;
+
+/** Experimental diagnostic contract v1; not a parser, checker, or runtime API. */
+
+declare const DIAGNOSTIC_CONTRACT_VERSION = 1;
+interface DocumentSnapshot {
+    readonly uri: string;
+    readonly text: string;
+    readonly version: number;
+    readonly environmentGeneration: string;
+}
+interface Diagnostic {
+    readonly code: string;
+    readonly range: Readonly<{
+        readonly start: number;
+        readonly end: number;
+    }>;
+}
+type ProviderOutcome = {
+    readonly status: "supported";
+    readonly diagnostics: readonly Diagnostic[];
+} | {
+    readonly status: "invalid";
+    readonly diagnostics: readonly Diagnostic[];
+} | {
+    readonly status: "unsupported";
+    readonly diagnostics?: never;
+};
+interface DiagnosticProvider {
+    readonly languageId: string;
+    diagnose(document: DocumentSnapshot): ProviderOutcome;
+}
+type RoutedOutcome = ProviderOutcome & {
+    readonly languageId: string;
+    readonly document: DocumentSnapshot;
+};
+declare function createDiagnosticRouter(providers: readonly DiagnosticProvider[]): Readonly<{
+    diagnose(languageId: string, input: DocumentSnapshot): RoutedOutcome;
+}>;
+
+export { COMPOSITION_CONTRACT_VERSION, type CompositionAttempt, type CompositionDiagnostic, type CompositionGuest, type CompositionMeter, type CompositionNode, type CompositionOutcome, type CompositionProfile, type CompositionRange, type CompositionRequest, type CompositionSlot, type CompositionSnapshot, DIAGNOSTIC_CONTRACT_VERSION, type Diagnostic, type DiagnosticProvider, type DocumentSnapshot, type GuestCompositionResult, type HostConnector, type HostContinuation, type ProviderOutcome, type RoutedOutcome, createCompositionRouter, createDiagnosticRouter };