@loutrejs/loutre 0.5.0 → 0.7.0

package/dist/core/model.js

@@ -0,0 +1,346 @@
+import { diagnostic, isErrorDiagnostic } from './diagnostic.js';
+import { isExecutionDefinition, } from './extension.js';
+import { isFrameworkProvidedToken } from './token-internal.js';
+import { tokenName } from './token.js';
+import { createModelBuildContext } from './model/context.js';
+import { resolveLifecycleDependencies } from './model/lifecycle.js';
+import { collectModuleDeclarations } from './model/modules.js';
+import { compileArgumentsProvider, resolveModuleExports, resolveProviderDependencies, } from './model/providers.js';
+import { snapshotExecutionExtension } from './model/snapshot.js';
+import { validateHostNamespaces, validateNodeIds } from './model/validation.js';
+import { getSourceLocation } from './source-location.js';
+import { isTokenVisible, moduleDeclaresToken } from './model/visibility.js';
+class ApplicationModelExtensionRegistry {
+    #ordered;
+    #groups;
+    constructor(groups) {
+        this.#ordered = Object.freeze([...groups]);
+        this.#groups = new Map(groups.map((group) => [group.extension.identity, group]));
+    }
+    get(extension) {
+        return this.#groups.get(extension.identity);
+    }
+    values() {
+        return this.#ordered;
+    }
+    [Symbol.iterator]() {
+        return this.#ordered[Symbol.iterator]();
+    }
+}
+export class ApplicationModelError extends Error {
+    diagnostics;
+    code = 'LUTRE_APPLICATION_MODEL_INVALID';
+    constructor(diagnostics) {
+        super(`Application Model is invalid:\n${diagnostics
+            .map((item) => `${item.code} at ${item.path}: ${item.message}`)
+            .join('\n')}`);
+        this.diagnostics = diagnostics;
+        this.name = 'ApplicationModelError';
+    }
+}
+export function assertValidApplicationModel(model) {
+    const errors = model.diagnostics.filter(isErrorDiagnostic);
+    if (errors.length > 0)
+        throw new ApplicationModelError(errors);
+    return model;
+}
+export function buildApplicationModel(options) {
+    const context = createModelBuildContext(options);
+    collectModuleDeclarations(context);
+    resolveModuleExports(context);
+    compileArgumentsProvider(context);
+    resolveProviderDependencies(context);
+    resolveLifecycleDependencies(context);
+    const { modules, moduleIds, nodes, edges, diagnostics, providers, executions, providerNodes, } = context;
+    const extensionExecutions = new Map();
+    const extensionNames = new Map();
+    const extensionIdentities = new Map();
+    const executionIds = new Set();
+    const capabilityNodeIds = new Set();
+    const visitedDefinitions = new Set();
+    const compiledDefinitions = new Map();
+    const executionReferences = [];
+    const executionReferenceResults = new Map();
+    const getExecutionReferences = (definition) => {
+        const cached = executionReferenceResults.get(definition);
+        if (cached)
+            return cached;
+        const references = definition.extension.references;
+        if (!references) {
+            const result = { references: Object.freeze([]) };
+            executionReferenceResults.set(definition, result);
+            return result;
+        }
+        try {
+            const result = {
+                references: references(definition),
+            };
+            executionReferenceResults.set(definition, result);
+            return result;
+        }
+        catch (error) {
+            const result = { error };
+            executionReferenceResults.set(definition, result);
+            return result;
+        }
+    };
+    const rootDefinitionOwners = new Map();
+    for (const module of modules) {
+        for (const value of module.definition.executions ?? []) {
+            if (!isExecutionDefinition(value))
+                continue;
+            const owners = rootDefinitionOwners.get(value) ?? new Set();
+            owners.add(module);
+            rootDefinitionOwners.set(value, owners);
+        }
+    }
+    const reachableDefinitionModules = new Map();
+    for (const module of modules) {
+        const queue = (module.definition.executions ?? []).filter(isExecutionDefinition);
+        const seen = new Set();
+        let queueIndex = 0;
+        while (queueIndex < queue.length) {
+            const value = queue[queueIndex++];
+            if (seen.has(value))
+                continue;
+            seen.add(value);
+            const explicitOwners = rootDefinitionOwners.get(value);
+            if (explicitOwners && !explicitOwners.has(module))
+                continue;
+            const reachableModules = reachableDefinitionModules.get(value) ?? new Set();
+            reachableModules.add(module);
+            reachableDefinitionModules.set(value, reachableModules);
+            const referenceResult = getExecutionReferences(value);
+            if ('error' in referenceResult)
+                continue;
+            for (const reference of referenceResult.references) {
+                if (!isExecutionDefinition(reference))
+                    continue;
+                if (reference.extension.identity !== value.extension.identity)
+                    continue;
+                queue.push(reference);
+            }
+        }
+    }
+    const definitionOwners = new Map();
+    const ambiguousDefinitions = new Set();
+    for (const [definition, explicitOwners] of rootDefinitionOwners) {
+        if (explicitOwners.size === 1) {
+            definitionOwners.set(definition, [...explicitOwners][0]);
+        }
+        else {
+            ambiguousDefinitions.add(definition);
+        }
+    }
+    for (const [definition, reachableModules] of reachableDefinitionModules) {
+        if (rootDefinitionOwners.has(definition))
+            continue;
+        if (reachableModules.size === 1) {
+            definitionOwners.set(definition, [...reachableModules][0]);
+        }
+        else {
+            ambiguousDefinitions.add(definition);
+        }
+    }
+    if (ambiguousDefinitions.size > 0) {
+        diagnostics.push(diagnostic('LUTRE_EXECUTION_OWNER_AMBIGUOUS', 'Execution Definition ownership is ambiguous across multiple Modules. Register each shared Definition in exactly one Module.executions; other Modules may reference it.', 'application.executions'));
+    }
+    for (const module of modules) {
+        const moduleId = moduleIds.get(module);
+        const rootDefinitions = module.definition.executions ?? [];
+        const rootDefinitionIndexes = new Map();
+        for (const [definitionIndex, value] of rootDefinitions.entries()) {
+            if (isExecutionDefinition(value) && !rootDefinitionIndexes.has(value)) {
+                rootDefinitionIndexes.set(value, definitionIndex);
+            }
+        }
+        const discoveredDefinitionIndexes = new Map();
+        const queue = rootDefinitions.map((value, definitionIndex) => ({
+            value,
+            definitionIndex,
+            path: `${moduleId}.executions.${definitionIndex}`,
+        }));
+        let nextDiscoveredDefinitionIndex = rootDefinitions.length;
+        let queueIndex = 0;
+        while (queueIndex < queue.length) {
+            const { value, definitionIndex, path } = queue[queueIndex++];
+            if (!isExecutionDefinition(value)) {
+                diagnostics.push(diagnostic('LUTRE_EXECUTION_DEFINITION_INVALID', 'Module executions and referenced executions accept only branded Execution Definitions.', path));
+                continue;
+            }
+            if (ambiguousDefinitions.has(value))
+                continue;
+            if (definitionOwners.get(value) !== module)
+                continue;
+            if (visitedDefinitions.has(value))
+                continue;
+            visitedDefinitions.add(value);
+            const extension = value.extension;
+            const namedIdentity = extensionNames.get(extension.name);
+            if (namedIdentity && namedIdentity.identity !== extension.identity) {
+                diagnostics.push(diagnostic('LUTRE_EXTENSION_ABI_MISMATCH', `Extension ${extension.name} mixes incompatible ABI versions ${namedIdentity.abiVersion} and ${extension.abiVersion}.`, path));
+                continue;
+            }
+            const identityOwner = extensionIdentities.get(extension.identity);
+            if (identityOwner && identityOwner.name !== extension.name) {
+                diagnostics.push(diagnostic('LUTRE_EXTENSION_IDENTITY_COLLISION', `Extension identity is shared by ${identityOwner.name} and ${extension.name}.`, path));
+                continue;
+            }
+            const canonicalExtension = identityOwner?.extension ?? snapshotExecutionExtension(extension);
+            extensionNames.set(extension.name, {
+                identity: extension.identity,
+                abiVersion: extension.abiVersion,
+            });
+            extensionIdentities.set(extension.identity, {
+                name: extension.name,
+                extension: canonicalExtension,
+            });
+            let contribution;
+            try {
+                contribution = extension.compile(value, {
+                    moduleId,
+                    definitionIndex,
+                });
+            }
+            catch (error) {
+                diagnostics.push(diagnostic('LUTRE_EXTENSION_COMPILE', describeError(error), path));
+                continue;
+            }
+            if (executionIds.has(contribution.id)) {
+                diagnostics.push(diagnostic('LUTRE_EXECUTION_ID_COLLISION', `Execution id ${contribution.id} is already registered.`, path));
+                continue;
+            }
+            executionIds.add(contribution.id);
+            const executionSource = getSourceLocation(value);
+            const execution = Object.freeze({
+                ...contribution,
+                dependencies: Object.freeze([...contribution.dependencies]),
+                capabilities: Object.freeze([...contribution.capabilities]),
+                moduleId,
+                ...(executionSource === undefined ? {} : { source: executionSource }),
+            });
+            compiledDefinitions.set(value, execution);
+            executions.push(execution);
+            nodes.push(execution);
+            edges.push({ from: moduleId, to: execution.id, kind: 'owns' });
+            const grouped = extensionExecutions.get(extension.identity) ?? {
+                extension: canonicalExtension,
+                executions: [],
+            };
+            grouped.executions.push(execution);
+            extensionExecutions.set(extension.identity, grouped);
+            for (const dependency of execution.dependencies) {
+                const provider = providerNodes.get(dependency);
+                if (provider) {
+                    edges.push({ from: execution.id, to: provider.id, kind: 'injects' });
+                    const providerModule = modules.find((candidate) => moduleIds.get(candidate) === provider.moduleId);
+                    if (providerModule &&
+                        provider.moduleId !== moduleId &&
+                        !moduleDeclaresToken(module, dependency) &&
+                        !isTokenVisible(module, providerModule, dependency)) {
+                        diagnostics.push(diagnostic('LUTRE_MODULE_VISIBILITY', `Execution ${execution.id} depends on private ${tokenName(dependency)} from another Module.`, execution.id));
+                    }
+                }
+                else if (!isFrameworkProvidedToken(dependency)) {
+                    diagnostics.push(diagnostic('LUTRE_EXECUTION_DEPENDENCY_MISSING', `Execution ${execution.id} requires ${tokenName(dependency)}, but no provider is declared.`, execution.id));
+                }
+            }
+            for (const capability of execution.capabilities) {
+                const capabilityId = `capability:${capability.id}`;
+                if (!capabilityNodeIds.has(capabilityId)) {
+                    capabilityNodeIds.add(capabilityId);
+                    nodes.push({
+                        kind: 'framework',
+                        id: capabilityId,
+                        frameworkKind: 'runtime-capability',
+                        name: capability.id,
+                    });
+                }
+                edges.push({
+                    from: execution.id,
+                    to: capabilityId,
+                    kind: 'requires',
+                });
+            }
+            const referenceResult = getExecutionReferences(value);
+            if ('error' in referenceResult) {
+                diagnostics.push(diagnostic('LUTRE_EXTENSION_REFERENCES', describeError(referenceResult.error), path));
+                continue;
+            }
+            for (const [referenceIndex, reference,] of referenceResult.references.entries()) {
+                const referencePath = `${path}.references.${referenceIndex}`;
+                if (!isExecutionDefinition(reference)) {
+                    diagnostics.push(diagnostic('LUTRE_EXECUTION_REFERENCE_INVALID', 'Execution references accept only branded Execution Definitions.', referencePath));
+                    continue;
+                }
+                if (reference.extension.identity !== extension.identity) {
+                    diagnostics.push(diagnostic('LUTRE_EXECUTION_REFERENCE_EXTENSION', `Execution ${execution.id} cannot reference an execution owned by ${reference.extension.name}.`, referencePath));
+                    continue;
+                }
+                executionReferences.push({ from: value, to: reference });
+                let referencedDefinitionIndex = rootDefinitionIndexes.get(reference);
+                if (referencedDefinitionIndex === undefined) {
+                    referencedDefinitionIndex = discoveredDefinitionIndexes.get(reference);
+                    if (referencedDefinitionIndex === undefined) {
+                        referencedDefinitionIndex = nextDiscoveredDefinitionIndex++;
+                        discoveredDefinitionIndexes.set(reference, referencedDefinitionIndex);
+                    }
+                }
+                queue.push({
+                    value: reference,
+                    definitionIndex: referencedDefinitionIndex,
+                    path: referencePath,
+                });
+            }
+        }
+    }
+    for (const reference of executionReferences) {
+        const from = compiledDefinitions.get(reference.from);
+        const to = compiledDefinitions.get(reference.to);
+        if (!from || !to)
+            continue;
+        edges.push({ from: from.id, to: to.id, kind: 'references' });
+    }
+    const extensionGroups = [...extensionExecutions.values()].map(({ extension, executions: ownedExecutions }) => {
+        const extensionId = `extension:${extension.name}`;
+        nodes.push({
+            kind: 'framework',
+            id: extensionId,
+            frameworkKind: 'execution-extension',
+            name: extension.name,
+        });
+        for (const execution of ownedExecutions) {
+            edges.push({ from: extensionId, to: execution.id, kind: 'starts' });
+        }
+        if (extension.validate) {
+            try {
+                diagnostics.push(...extension.validate({ executions: ownedExecutions }));
+            }
+            catch (error) {
+                diagnostics.push(diagnostic('LUTRE_EXTENSION_VALIDATE', describeError(error), extensionId));
+            }
+        }
+        return Object.freeze({
+            extension,
+            executions: Object.freeze([...ownedExecutions]),
+        });
+    });
+    const extensions = new ApplicationModelExtensionRegistry(extensionGroups);
+    validateHostNamespaces(extensionGroups, diagnostics);
+    validateNodeIds(nodes, diagnostics);
+    return Object.freeze({
+        kind: 'application-model',
+        ...(options.arguments === undefined
+            ? {}
+            : { arguments: options.arguments }),
+        providers: Object.freeze(providers),
+        nodes: Object.freeze(nodes.map((node) => Object.freeze(node))),
+        edges: Object.freeze(edges.map((edge) => Object.freeze(edge))),
+        executions: Object.freeze(executions),
+        extensions,
+        diagnostics: Object.freeze(diagnostics.map((item) => Object.freeze({ ...item }))),
+    });
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/module.d.ts

@@ -1,5 +1,5 @@
 import type { EnvClass } from './env.js';
-import type { ImplementationDescriptor } from './implementation.js';
+import type { ExecutionDefinition, ExtensionOfDefinition, HostApiOfExtension } from './extension.js';
 import type { ModuleLifecycle } from './lifecycle.js';
 import { type ProviderDeclaration } from './provider.js';
 export interface ModuleDefinition {
@@ -8,24 +8,19 @@ export interface ModuleDefinition {
     readonly imports?: readonly ModuleInstance[];
     readonly environment?: readonly EnvClass[];
     readonly providers?: readonly ProviderDeclaration[];
-    readonly implementations?: readonly ImplementationDescriptor[];
+    readonly executions?: readonly ExecutionDefinition[];
     readonly exports?: readonly unknown[];
     readonly lifecycle?: ModuleLifecycle;
-    readonly requires?: readonly string[];
 }
 export declare const moduleTypeInfo: unique symbol;
 export interface ModuleTypeInfo<TDefinition extends ModuleDefinition = ModuleDefinition> {
-    readonly protocols: ProtocolsOfModuleDefinition<TDefinition>;
-    readonly capabilities: CapabilitiesOfModuleDefinition<TDefinition>;
+    readonly extensions: ExtensionsOfModuleDefinition<TDefinition>;
 }
-type DirectProtocols<TDefinition extends ModuleDefinition> = TDefinition['implementations'] extends readonly ImplementationDescriptor[] ? TDefinition['implementations'][number]['protocol'] : never;
-type ImportedProtocols<TDefinition extends ModuleDefinition> = TDefinition['imports'] extends readonly ModuleInstance[] ? ModuleProtocols<TDefinition['imports'][number]> : never;
-export type ProtocolsOfModuleDefinition<TDefinition extends ModuleDefinition> = DirectProtocols<TDefinition> | ImportedProtocols<TDefinition>;
-type DirectCapabilities<TDefinition extends ModuleDefinition> = TDefinition['implementations'] extends readonly ImplementationDescriptor[] ? TDefinition['implementations'][number]['capabilities'][number] : never;
-type ImportedCapabilities<TDefinition extends ModuleDefinition> = TDefinition['imports'] extends readonly ModuleInstance[] ? ModuleCapabilities<TDefinition['imports'][number]> : never;
-export type CapabilitiesOfModuleDefinition<TDefinition extends ModuleDefinition> = DirectCapabilities<TDefinition> | ImportedCapabilities<TDefinition>;
-export type ModuleProtocols<TModule> = TModule extends ModuleInstance<infer TDefinition> ? ProtocolsOfModuleDefinition<TDefinition> : never;
-export type ModuleCapabilities<TModule> = TModule extends ModuleInstance<infer TDefinition> ? CapabilitiesOfModuleDefinition<TDefinition> : never;
+type DirectExtensions<TDefinition extends ModuleDefinition> = TDefinition['executions'] extends readonly ExecutionDefinition[] ? ExtensionOfDefinition<TDefinition['executions'][number]> : never;
+type ImportedExtensions<TDefinition extends ModuleDefinition> = TDefinition['imports'] extends readonly ModuleInstance[] ? ModuleExtensions<TDefinition['imports'][number]> : never;
+export type ExtensionsOfModuleDefinition<TDefinition extends ModuleDefinition> = DirectExtensions<TDefinition> | ImportedExtensions<TDefinition>;
+export type ModuleExtensions<TModule> = TModule extends ModuleInstance<infer TDefinition> ? ExtensionsOfModuleDefinition<TDefinition> : never;
+export type ModuleHostApis<TModule> = HostApiOfExtension<ModuleExtensions<TModule>>;
 export interface ModuleInstance<TDefinition extends ModuleDefinition = ModuleDefinition> {
     readonly kind: 'module-instance';
     readonly template: AnyModuleTemplate;

package/dist/core/source-location.d.ts

@@ -0,0 +1,8 @@
+export interface SourceLocation {
+    readonly file: string;
+    readonly line?: number;
+    readonly column?: number;
+}
+export declare function registerSourceLocation<T>(value: T, source: SourceLocation): T;
+export declare function getSourceLocation(value: unknown): SourceLocation | undefined;
+export declare function inheritSourceLocation<T>(target: T, source: unknown): T;

package/dist/core/source-location.js

@@ -0,0 +1,31 @@
+const sourceMetadata = new WeakMap();
+function asObject(value) {
+    return (typeof value === 'object' && value !== null) ||
+        typeof value === 'function'
+        ? value
+        : undefined;
+}
+function snapshotSourceLocation(source) {
+    return Object.freeze({
+        file: source.file,
+        ...(source.line === undefined ? {} : { line: source.line }),
+        ...(source.column === undefined ? {} : { column: source.column }),
+    });
+}
+export function registerSourceLocation(value, source) {
+    const target = asObject(value);
+    if (!target || sourceMetadata.has(target))
+        return value;
+    sourceMetadata.set(target, snapshotSourceLocation(source));
+    return value;
+}
+export function getSourceLocation(value) {
+    const target = asObject(value);
+    return target ? sourceMetadata.get(target) : undefined;
+}
+export function inheritSourceLocation(target, source) {
+    const location = getSourceLocation(source);
+    return location === undefined
+        ? target
+        : registerSourceLocation(target, location);
+}

package/dist/core/token-internal.d.ts

@@ -0,0 +1,3 @@
+import type { TokenLike } from './token.js';
+export declare const frameworkProvidedTokenBrand: unique symbol;
+export declare function isFrameworkProvidedToken(token: TokenLike): boolean;

package/dist/core/token-internal.js

@@ -0,0 +1,4 @@
+export const frameworkProvidedTokenBrand = Symbol.for('loutre.framework-provided-token');
+export function isFrameworkProvidedToken(token) {
+    return (token[frameworkProvidedTokenBrand] === true);
+}

package/dist/core/type.d.ts

@@ -0,0 +1,7 @@
+declare const typeValue: unique symbol;
+export interface Type<T> {
+    readonly [typeValue]: T;
+}
+export type TypeOf<TType> = TType extends Type<infer TValue> ? TValue : never;
+export declare function type<T>(): Type<T>;
+export {};

package/dist/core/type.js

@@ -0,0 +1,4 @@
+const typeCarrier = Object.freeze({});
+export function type() {
+    return typeCarrier;
+}

package/dist/devtools/capsule.d.ts

@@ -0,0 +1,51 @@
+import type { RuntimeExecutionMetadata } from '../core/instrumentation.js';
+import type { DevtoolsModuleOptions } from './module.js';
+import type { ReplayCapsuleRequest, ReplayExecutionContext, RuntimeInvocationResult } from './inspector.js';
+import { type DevtoolsValuePreview } from './values.js';
+export interface ReplayRegistration {
+    readonly input: unknown;
+    replay(input: unknown, context: ReplayExecutionContext): unknown | Promise<unknown>;
+}
+export type CapturedValue = {
+    readonly mode: 'snapshot';
+    readonly value: unknown;
+} | {
+    readonly mode: 'reference';
+    readonly handleId: string;
+} | {
+    readonly mode: 'unavailable';
+    readonly reason: string;
+};
+export interface ExecutionReplayCapsulePreview {
+    readonly id: string;
+    readonly kind: 'execution';
+    readonly runId: string;
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+    readonly execution: {
+        readonly executionId: string;
+        readonly executionKind: string;
+        readonly graphNodeId?: string;
+        readonly name: string;
+    };
+    readonly input: DevtoolsValuePreview;
+    readonly fidelity: 'snapshot' | 'reference' | 'unavailable';
+    readonly replayModes: readonly ['direct'];
+}
+export interface ReplayCapsuleStoreOptions {
+    readonly ttlMs?: number;
+    readonly maxCapsules?: number;
+    readonly capture?: DevtoolsModuleOptions['capture'];
+    readonly redact?: readonly string[];
+}
+export declare class ReplayCapsuleStore {
+    #private;
+    constructor(runId: string, options?: ReplayCapsuleStoreOptions);
+    createExecution(traceId: string, spanId: string, observation: RuntimeExecutionMetadata, registration: ReplayRegistration): ExecutionReplayCapsulePreview;
+    preview(capsuleId: string): ExecutionReplayCapsulePreview | undefined;
+    replay(request: ReplayCapsuleRequest): Promise<RuntimeInvocationResult>;
+    discard(capsuleId: string): void;
+    clear(): void;
+}