@loutrejs/loutre 0.9.2 → 0.10.0

package/dist/core/model/modules.js

@@ -1,7 +1,9 @@
+import { moduleName } from '../identity.js';
 import { collectInjectedDependencies } from '../injection.js';
 import { diagnostic } from '../diagnostic.js';
 import { normalizeProvider } from '../provider.js';
 import { tokenName } from '../token.js';
+import { findProviderNode } from './context.js';
 import { appendLifecycleNodes } from './lifecycle.js';
 import { snapshotProvider } from './snapshot.js';
 import { getSourceLocation } from '../source-location.js';
@@ -12,10 +14,10 @@ export function collectModuleDeclarations(context) {
     for (const module of modules) {
         const moduleId = moduleIds.get(module);
         if (module.definition.name) {
-            if (moduleNames.has(module.definition.name)) {
+            if (moduleNames.has(moduleName(module.definition.name))) {
                 diagnostics.push(diagnostic('LUTRE_MODULE_NAME_COLLISION', `Module name ${module.definition.name} is already registered.`, moduleId));
             }
-            moduleNames.add(module.definition.name);
+            moduleNames.add(moduleName(module.definition.name));
         }
         const moduleSource = getSourceLocation(module) ?? getSourceLocation(module.template);
         nodes.push({
@@ -41,7 +43,7 @@ export function collectModuleDeclarations(context) {
                 ? getSourceLocation(normalized.useClass)
                 : getSourceLocation(declaration);
             const providerId = context.nextProviderId();
-            const existingProvider = providerNodes.get(provider.provide);
+            const existingProvider = findProviderNode(context, provider.provide);
             if (existingProvider?.provider.kind === 'environment' &&
                 provider.kind === 'environment') {
                 edges.push({ from: moduleId, to: existingProvider.id, kind: 'owns' });
@@ -78,7 +80,7 @@ export function collectModuleDeclarations(context) {
         appendLifecycleNodes(module, moduleId, nodes, edges);
     }
 }
-function collectProviderDependencies(provider) {
+export function collectProviderDependencies(provider) {
     return match(provider)
         .with({ kind: 'class' }, (candidate) => Object.freeze(collectInjectedDependencies(candidate.provide, () => Reflect.construct(candidate.useClass, []))))
         .with({ kind: 'factory' }, (candidate) => Object.freeze([...candidate.inject]))

package/dist/core/model/providers.d.ts

@@ -1,4 +1,4 @@
-import type { ModelBuildContext } from './context.js';
+import { type ModelBuildContext } from './context.js';
 export declare function resolveModuleExports(context: ModelBuildContext): void;
 export declare function compileArgumentsProvider(context: ModelBuildContext): void;
 export declare function resolveProviderDependencies(context: ModelBuildContext): void;

package/dist/core/model/providers.js

@@ -1,17 +1,19 @@
+import { isLoggerToken } from '../logger-internal.js';
 import { diagnostic } from '../diagnostic.js';
 import { argumentsProvider } from '../provider.js';
 import { isFrameworkProvidedToken } from '../token-internal.js';
 import { tokenName } from '../token.js';
+import { findProviderNode } from './context.js';
 import { snapshotProvider } from './snapshot.js';
 import { isTokenVisible, moduleDeclaresToken } from './visibility.js';
 export function resolveModuleExports(context) {
-    const { modules, moduleIds, providerNodes, edges, diagnostics } = context;
+    const { modules, moduleIds, edges, diagnostics } = context;
     for (const module of modules) {
         const moduleId = moduleIds.get(module);
         for (const exported of module.definition.exports ?? []) {
             if (moduleDeclaresToken(module, exported))
                 continue;
-            const provider = providerNodes.get(exported);
+            const provider = findProviderNode(context, exported);
             const providerModule = provider
                 ? modules.find((candidate) => moduleIds.get(candidate) === provider.moduleId)
                 : undefined;
@@ -49,17 +51,15 @@ export function compileArgumentsProvider(context) {
 export function resolveProviderDependencies(context) {
     const { providerNodes, modules, moduleIds, edges, diagnostics } = context;
     for (const provider of providerNodes.values()) {
-        if (provider.moduleId === 'application')
-            continue;
         const sourceModule = modules.find((candidate) => moduleIds.get(candidate) === provider.moduleId);
-        if (!sourceModule)
-            continue;
         for (const dependency of provider.dependencies) {
-            const target = providerNodes.get(dependency);
+            const target = findProviderNode(context, dependency);
             if (target) {
                 edges.push({ from: provider.id, to: target.id, kind: 'injects' });
                 const targetModule = modules.find((candidate) => moduleIds.get(candidate) === target.moduleId);
-                if (targetModule &&
+                if (sourceModule &&
+                    !isLoggerToken(dependency) &&
+                    targetModule &&
                     target.moduleId !== provider.moduleId &&
                     !moduleDeclaresToken(sourceModule, dependency) &&
                     !isTokenVisible(context, sourceModule, targetModule, dependency)) {

package/dist/core/model/types.d.ts

@@ -1,32 +1,33 @@
+import type { ModuleId, ProviderNodeId, ExecutionNodeId, LifecycleNodeId, CapabilityNodeId, ExtensionNodeId } from './identity.js';
 import type { ArgsClass } from '../args.js';
 import type { AnyExecutionExtension, ExecutionExtension, RuntimeCapability } from '../extension.js';
 import type { LifecycleHook } from '../lifecycle.js';
-import type { ModuleInstance, ModuleTemplate } from '../module.js';
+import type { ModuleInstance } from '../module.js';
 import type { ProviderDescriptor } from '../provider.js';
 import type { Diagnostic } from '../diagnostic.js';
 import type { TokenLike } from '../token.js';
 import type { SourceLocation } from '../source-location.js';
 export interface ModuleModelNode {
     readonly kind: 'module';
-    readonly id: string;
+    readonly id: ModuleId;
     readonly name?: string;
     readonly description?: string;
     readonly source?: SourceLocation;
 }
 export interface ProviderModelNode {
     readonly kind: 'provider';
-    readonly id: string;
+    readonly id: ProviderNodeId;
     readonly token: TokenLike;
     readonly provider: ProviderDescriptor;
-    readonly moduleId: string;
+    readonly moduleId: ModuleId | 'application';
     readonly dependencies: readonly TokenLike[];
     readonly source?: SourceLocation;
 }
 export interface ExecutionModelNode<TCompiled = unknown> {
     readonly kind: 'execution';
-    readonly id: string;
+    readonly id: ExecutionNodeId;
     readonly executionKind: string;
-    readonly moduleId: string;
+    readonly moduleId: ModuleId;
     readonly dependencies: readonly TokenLike[];
     readonly capabilities: readonly RuntimeCapability[];
     readonly compiled: TCompiled;
@@ -34,25 +35,30 @@ export interface ExecutionModelNode<TCompiled = unknown> {
 }
 export interface LifecycleModelNode {
     readonly kind: 'lifecycle';
-    readonly id: string;
-    readonly moduleId: string;
+    readonly id: LifecycleNodeId;
+    readonly moduleId: ModuleId;
     readonly phase: string;
     readonly hook: LifecycleHook<any>;
     readonly source?: SourceLocation;
 }
-export interface FrameworkModelNode {
+export type FrameworkModelNode = {
     readonly kind: 'framework';
-    readonly id: string;
-    readonly frameworkKind: 'runtime-capability' | 'execution-extension';
     readonly name: string;
     readonly source?: SourceLocation;
-}
+} & ({
+    readonly frameworkKind: 'runtime-capability';
+    readonly id: CapabilityNodeId;
+} | {
+    readonly frameworkKind: 'execution-extension';
+    readonly id: ExtensionNodeId;
+});
 export type ApplicationModelNode = ModuleModelNode | ProviderModelNode | ExecutionModelNode | LifecycleModelNode | FrameworkModelNode;
-export interface ApplicationModelEdge {
-    readonly from: string;
-    readonly to: string;
-    readonly kind: 'owns' | 'imports' | 'exports' | 'injects' | 'references' | 'requires' | 'starts' | 'wraps';
-}
+type Edge<Kind, From, To> = {
+    readonly kind: Kind;
+    readonly from: From;
+    readonly to: To;
+};
+export type ApplicationModelEdge = Edge<'owns', ModuleId, ProviderNodeId | ExecutionNodeId | LifecycleNodeId> | Edge<'imports', ModuleId, ModuleId> | Edge<'exports', ModuleId, ProviderNodeId> | Edge<'injects', ProviderNodeId | ExecutionNodeId | LifecycleNodeId, ProviderNodeId> | Edge<'references', ExecutionNodeId, ExecutionNodeId> | Edge<'requires', ExecutionNodeId, CapabilityNodeId> | Edge<'starts', ExtensionNodeId, ExecutionNodeId> | Edge<'wraps', ApplicationModelNode['id'], ApplicationModelNode['id']>;
 export type CompiledOf<TExtension extends AnyExecutionExtension> = TExtension extends ExecutionExtension<any, infer TCompiled, any, any, any> ? TCompiled : never;
 export interface ApplicationModelExtension<TExtension extends AnyExecutionExtension = AnyExecutionExtension> {
     readonly extension: TExtension;
@@ -73,6 +79,7 @@ export interface ApplicationModel {
     readonly diagnostics: readonly Diagnostic[];
 }
 export interface ApplicationModelBuildOptions {
-    readonly modules: readonly (ModuleInstance | ModuleTemplate<void>)[];
+    readonly modules: readonly ModuleInstance[];
     readonly arguments?: ArgsClass;
 }
+export {};

package/dist/core/model/validation.js

@@ -1,3 +1,4 @@
+import { hostNamespace } from '../identity.js';
 import { diagnostic } from '../diagnostic.js';
 export function validateHostNamespaces(extensions, diagnostics) {
     const reserved = new Set([
@@ -20,12 +21,12 @@ export function validateHostNamespaces(extensions, diagnostics) {
             diagnostics.push(diagnostic('LUTRE_HOST_NAMESPACE_RESERVED', `Host namespace ${namespace} is reserved by the Application or runtime adapter API.`, `host.${namespace}`));
             continue;
         }
-        const owner = owners.get(namespace);
+        const owner = owners.get(hostNamespace(namespace));
         if (owner && owner.identity !== extension.identity) {
             diagnostics.push(diagnostic('LUTRE_HOST_NAMESPACE_COLLISION', `Host namespace ${namespace} is contributed by both ${owner.name} and ${extension.name}.`, `host.${namespace}`));
             continue;
         }
-        owners.set(namespace, extension);
+        owners.set(hostNamespace(namespace), extension);
     }
 }
 export function validateNodeIds(nodes, diagnostics) {

package/dist/core/model/visibility.js

@@ -1,13 +1,18 @@
+import { isLoggerToken } from '../logger-internal.js';
 import { normalizeProvider } from '../provider.js';
 export function moduleDeclaresToken(module, token) {
-    return (module.definition.providers ?? []).some((declaration) => normalizeProvider(declaration).provide === token);
+    return (module.definition.providers ?? []).some((declaration) => {
+        const provided = normalizeProvider(declaration).provide;
+        return (provided === token || (isLoggerToken(provided) && isLoggerToken(token)));
+    });
 }
 export function isTokenVisible(context, source, target, token, visited = new Set()) {
     if (visited.has(source))
         return false;
     visited.add(source);
     for (const imported of context.imports.get(source) ?? []) {
-        if (!imported.definition.exports?.includes(token))
+        if (!imported.definition.exports?.some((exported) => exported === token ||
+            (isLoggerToken(exported) && isLoggerToken(token))))
             continue;
         if (imported === target)
             return true;

package/dist/core/model.js

@@ -1,3 +1,4 @@
+import { executionNodeId, capabilityNodeId, extensionNodeId, } from './model/identity.js';
 import { diagnostic, isErrorDiagnostic } from './diagnostic.js';
 import { isExecutionDefinition, flattenExecutions, } from './extension.js';
 import { isFrameworkProvidedToken } from './token-internal.js';
@@ -8,6 +9,9 @@ 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 { compileApplicationLogger, validateApplicationLogger, } from './model/logger.js';
+import { findProviderNode } from './model/context.js';
+import { isLoggerToken } from './logger-internal.js';
 import { getSourceLocation } from './source-location.js';
 import { isTokenVisible, moduleDeclaresToken } from './model/visibility.js';
 class ApplicationModelExtensionRegistry {
@@ -47,11 +51,12 @@ export function assertValidApplicationModel(model) {
 export function buildApplicationModel(options) {
     const context = createModelBuildContext(options);
     collectModuleDeclarations(context);
-    resolveModuleExports(context);
     compileArgumentsProvider(context);
+    compileApplicationLogger(context);
+    resolveModuleExports(context);
     resolveProviderDependencies(context);
     resolveLifecycleDependencies(context);
-    const { modules, moduleIds, nodes, edges, diagnostics, providers, executions, providerNodes, } = context;
+    const { modules, moduleIds, nodes, edges, diagnostics, providers, executions, } = context;
     const extensionExecutions = new Map();
     const extensionNames = new Map();
     const extensionIdentities = new Map();
@@ -216,14 +221,15 @@ export function buildApplicationModel(options) {
                 diagnostics.push(diagnostic('LUTRE_EXTENSION_COMPILE', describeError(error), path));
                 continue;
             }
-            if (executionIds.has(contribution.id)) {
+            if (executionIds.has(executionNodeId(contribution.id))) {
                 diagnostics.push(diagnostic('LUTRE_EXECUTION_ID_COLLISION', `Execution id ${contribution.id} is already registered.`, path));
                 continue;
             }
-            executionIds.add(contribution.id);
+            executionIds.add(executionNodeId(contribution.id));
             const executionSource = getSourceLocation(value);
             const execution = Object.freeze({
                 ...contribution,
+                id: executionNodeId(contribution.id),
                 dependencies: Object.freeze([...contribution.dependencies]),
                 capabilities: Object.freeze([...contribution.capabilities]),
                 moduleId,
@@ -240,11 +246,12 @@ export function buildApplicationModel(options) {
             grouped.executions.push(execution);
             extensionExecutions.set(extension.identity, grouped);
             for (const dependency of execution.dependencies) {
-                const provider = providerNodes.get(dependency);
+                const provider = findProviderNode(context, 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 &&
+                        !isLoggerToken(dependency) &&
                         provider.moduleId !== moduleId &&
                         !moduleDeclaresToken(module, dependency) &&
                         !isTokenVisible(context, module, providerModule, dependency)) {
@@ -256,7 +263,7 @@ export function buildApplicationModel(options) {
                 }
             }
             for (const capability of execution.capabilities) {
-                const capabilityId = `capability:${capability.id}`;
+                const capabilityId = capabilityNodeId(capability.id);
                 if (!capabilityNodeIds.has(capabilityId)) {
                     capabilityNodeIds.add(capabilityId);
                     nodes.push({
@@ -312,7 +319,7 @@ export function buildApplicationModel(options) {
         edges.push({ from: from.id, to: to.id, kind: 'references' });
     }
     const extensionGroups = [...extensionExecutions.values()].map(({ extension, executions: ownedExecutions }) => {
-        const extensionId = `extension:${extension.name}`;
+        const extensionId = extensionNodeId(extension.name);
         nodes.push({
             kind: 'framework',
             id: extensionId,
@@ -336,6 +343,7 @@ export function buildApplicationModel(options) {
         });
     });
     const extensions = new ApplicationModelExtensionRegistry(extensionGroups);
+    validateApplicationLogger(context);
     validateHostNamespaces(extensionGroups, diagnostics);
     validateNodeIds(nodes, diagnostics);
     return Object.freeze({

package/dist/core/module.d.ts

@@ -1,3 +1,4 @@
+import type { Descriptor } from '../internal/brand.js';
 import type { EnvClass } from './env.js';
 import type { ExecutionDeclaration, ExtensionOfDefinition, HostApiOfExtension } from './extension.js';
 import type { ModuleLifecycle } from './lifecycle.js';
@@ -5,7 +6,7 @@ import { type ProviderDeclaration } from './provider.js';
 export interface ModuleDefinition {
     readonly name?: string;
     readonly description?: string;
-    readonly imports?: readonly ModuleInput[];
+    readonly imports?: readonly ModuleInstance[];
     readonly environment?: readonly EnvClass[];
     readonly providers?: readonly ProviderDeclaration[];
     readonly executions?: readonly ExecutionDeclaration[];
@@ -17,18 +18,18 @@ export interface ModuleTypeInfo<TDefinition extends ModuleDefinition = ModuleDef
     readonly extensions: ExtensionsOfModuleDefinition<TDefinition>;
 }
 type DirectExtensions<TDefinition extends ModuleDefinition> = TDefinition['executions'] extends readonly ExecutionDeclaration[] ? ExtensionOfDefinition<TDefinition['executions'][number]> : never;
-type ImportedExtensions<TDefinition extends ModuleDefinition> = TDefinition['imports'] extends readonly ModuleInput[] ? ModuleExtensions<TDefinition['imports'][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> : TModule extends ModuleTemplate<void, infer TDefinition> ? ExtensionsOfModuleDefinition<TDefinition> : never;
+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> {
+export interface ModuleInstance<TDefinition extends ModuleDefinition = ModuleDefinition> extends Descriptor<'module-instance'> {
     readonly kind: 'module-instance';
     readonly template: AnyModuleTemplate;
     readonly args: unknown;
     readonly definition: TDefinition;
     readonly [moduleTypeInfo]?: ModuleTypeInfo<TDefinition>;
 }
-export interface AnyModuleTemplate {
+export interface AnyModuleTemplate extends Descriptor<'module-template'> {
     (args?: any): ModuleInstance<any>;
     readonly kind: 'module-template';
     readonly instantiate: (args: any) => ModuleInstance<any>;
@@ -40,11 +41,10 @@ export type ModuleTemplate<Args, TDefinition extends ModuleDefinition = ModuleDe
     (args: Args): ModuleInstance<TDefinition>;
 }) & {
     readonly kind: 'module-template';
+    readonly '~loutre.descriptor': 'module-template';
     readonly instantiate: (args: Args) => ModuleInstance<TDefinition>;
     readonly [moduleTypeInfo]?: ModuleTypeInfo<TDefinition>;
 };
-export type ModuleInput = ModuleInstance | ModuleTemplate<void>;
 export declare function defineModule<const TDefinition extends ModuleDefinition>(definition: TDefinition): ModuleInstance<TDefinition>;
 export declare function defineModule<Args = void, const TDefinition extends ModuleDefinition = ModuleDefinition>(factory: (args: Args) => TDefinition): ModuleTemplate<Args, TDefinition>;
-export declare function asModuleInstance(module: ModuleInput): ModuleInstance;
 export {};

package/dist/core/module.js

@@ -31,6 +31,3 @@ function createModuleTemplate(factory) {
     });
     return template;
 }
-export function asModuleInstance(module) {
-    return module.kind === 'module-instance' ? module : module();
-}

package/dist/core/runtime-input.d.ts

@@ -1,8 +1,9 @@
+import type { Descriptor } from '../internal/brand.js';
 import type { TokenLike } from './token.js';
 export type RuntimeInputContract = TokenLike<object> & {
     readonly name: string;
 };
-export interface RuntimeInputKey<TValue = unknown> {
+export interface RuntimeInputKey<TValue = unknown> extends Descriptor<'runtime-input-key'> {
     readonly kind: 'runtime-input-key';
     readonly source: 'environment' | 'arguments';
     readonly contract: RuntimeInputContract;

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

@@ -1,8 +1,20 @@
-export interface SourceLocation {
+import type { Brand } from '../internal/brand.js';
+export type SourceFileReference = Brand<string, 'source.file-reference'>;
+export type SourceLine = Brand<number, 'source.line'>;
+export type SourceColumn = Brand<number, 'source.column'>;
+export declare const sourceFileReference: (value: string) => SourceFileReference;
+export declare const sourceLine: (value: number) => SourceLine;
+export declare const sourceColumn: (value: number) => SourceColumn;
+export interface SourceLocationInput {
     readonly file: string;
     readonly line?: number;
     readonly column?: number;
 }
-export declare function registerSourceLocation<T>(value: T, source: SourceLocation): T;
+export interface SourceLocation {
+    readonly file: SourceFileReference;
+    readonly line?: SourceLine;
+    readonly column?: SourceColumn;
+}
+export declare function registerSourceLocation<T>(value: T, source: SourceLocationInput): 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

@@ -1,3 +1,6 @@
+export const sourceFileReference = (value) => value;
+export const sourceLine = (value) => value;
+export const sourceColumn = (value) => value;
 const sourceMetadata = new WeakMap();
 function asObject(value) {
     return (typeof value === 'object' && value !== null) ||
@@ -7,9 +10,11 @@ function asObject(value) {
 }
 function snapshotSourceLocation(source) {
     return Object.freeze({
-        file: source.file,
-        ...(source.line === undefined ? {} : { line: source.line }),
-        ...(source.column === undefined ? {} : { column: source.column }),
+        file: sourceFileReference(source.file),
+        ...(source.line === undefined ? {} : { line: sourceLine(source.line) }),
+        ...(source.column === undefined
+            ? {}
+            : { column: sourceColumn(source.column) }),
     });
 }
 export function registerSourceLocation(value, source) {

package/dist/core/token-internal.js

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

package/dist/core/token.d.ts

@@ -1,11 +1,13 @@
+import type { Descriptor } from '../internal/brand.js';
+import type { TokenKey } from './identity.js';
 export interface TokenOptions {
     readonly description?: string;
 }
-export interface Token<T> {
+export interface Token<T> extends Descriptor<'token'> {
     readonly kind: 'token';
     readonly id: string;
     readonly description?: string;
-    readonly key: symbol;
+    readonly key: TokenKey;
     readonly '~type'?: T;
 }
 export type Class<T = unknown> = new (...args: any[]) => T;

package/dist/core/token.js

@@ -1,3 +1,4 @@
+import { isLoggerTokenIdentity } from './logger-identity.js';
 export function token(id, options = {}) {
     return Object.freeze({
         kind: 'token',
@@ -9,5 +10,7 @@ export function token(id, options = {}) {
     });
 }
 export function tokenName(value) {
+    if (isLoggerTokenIdentity(value))
+        return 'LoggerToken';
     return typeof value === 'function' ? value.name : value.id;
 }

package/dist/core/units.d.ts

@@ -0,0 +1,22 @@
+import type { Brand } from '../internal/brand.js';
+export type DurationMs = Brand<number, 'duration.ms'>;
+export type DurationSeconds = Brand<number, 'duration.seconds'>;
+export type EpochMs = Brand<number, 'time.epoch-ms'>;
+export type MonotonicMs = Brand<number, 'time.monotonic-ms'>;
+export type ByteLength = Brand<number, 'bytes.length'>;
+export type ByteLimit = Brand<number, 'bytes.limit'>;
+export type CaptureDepthLimit = Brand<number, 'capture.depth-limit'>;
+export declare const milliseconds: (value: number) => DurationMs;
+export declare const seconds: (value: number) => DurationSeconds;
+export declare const epochMilliseconds: (value: number) => EpochMs;
+export declare const monotonicMilliseconds: (value: number) => MonotonicMs;
+export declare const byteLimit: (value: number) => ByteLimit;
+export declare const captureDepthLimit: (value: number) => CaptureDepthLimit;
+export declare const utf8ByteLength: (value: string) => ByteLength;
+export declare const epochNow: () => EpochMs;
+export declare const monotonicNow: () => MonotonicMs;
+export declare const elapsed: (start: MonotonicMs, end: MonotonicMs) => DurationMs;
+export declare const expiresAt: (now: EpochMs, ttl: DurationMs) => EpochMs;
+export declare const epochFromMonotonic: (value: MonotonicMs) => EpochMs;
+export declare const secondsToMilliseconds: (value: DurationSeconds) => DurationMs;
+export declare const epochDifference: (start: EpochMs, end: EpochMs) => DurationMs;

package/dist/core/units.js

@@ -0,0 +1,14 @@
+export const milliseconds = (value) => value;
+export const seconds = (value) => value;
+export const epochMilliseconds = (value) => value;
+export const monotonicMilliseconds = (value) => value;
+export const byteLimit = (value) => value;
+export const captureDepthLimit = (value) => value;
+export const utf8ByteLength = (value) => new TextEncoder().encode(value).byteLength;
+export const epochNow = () => epochMilliseconds(Date.now());
+export const monotonicNow = () => monotonicMilliseconds(performance.now());
+export const elapsed = (start, end) => milliseconds(end - start);
+export const expiresAt = (now, ttl) => epochMilliseconds(now + ttl);
+export const epochFromMonotonic = (value) => epochMilliseconds(performance.timeOrigin + value);
+export const secondsToMilliseconds = (value) => milliseconds(value * 1_000);
+export const epochDifference = (start, end) => milliseconds(end - start);

package/dist/devtools/capsule.d.ts

@@ -1,3 +1,7 @@
+import type { RunId, TraceId, SpanId, CapsuleId, CaptureHandleId } from './identity.js';
+import type { ModelNodeId } from '../core/model/identity.js';
+import type { RuntimeExecutionId } from '../core/identity.js';
+import type { EpochMs } from '../core/units.js';
 import type { RuntimeExecutionMetadata } from '../core/instrumentation.js';
 import type { DevtoolsModuleOptions } from './module.js';
 import type { ReplayCapsuleRequest, ReplayExecutionContext, RuntimeInvocationResult } from './inspector.js';
@@ -11,23 +15,23 @@ export type CapturedValue = {
     readonly value: unknown;
 } | {
     readonly mode: 'reference';
-    readonly handleId: string;
+    readonly handleId: CaptureHandleId;
 } | {
     readonly mode: 'unavailable';
     readonly reason: string;
 };
 export interface ExecutionReplayCapsulePreview {
-    readonly id: string;
+    readonly id: CapsuleId;
     readonly kind: 'execution';
-    readonly runId: string;
-    readonly traceId: string;
-    readonly spanId: string;
-    readonly createdAt: number;
-    readonly expiresAt: number;
+    readonly runId: RunId;
+    readonly traceId: TraceId;
+    readonly spanId: SpanId;
+    readonly createdAt: EpochMs;
+    readonly expiresAt: EpochMs;
     readonly execution: {
-        readonly executionId: string;
+        readonly executionId: RuntimeExecutionId;
         readonly executionKind: string;
-        readonly graphNodeId?: string;
+        readonly graphNodeId?: ModelNodeId;
         readonly name: string;
     };
     readonly input: DevtoolsValuePreview;
@@ -42,10 +46,10 @@ export interface ReplayCapsuleStoreOptions {
 }
 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;
+    constructor(runId: RunId, options?: ReplayCapsuleStoreOptions);
+    createExecution(traceId: TraceId, spanId: SpanId, observation: RuntimeExecutionMetadata, registration: ReplayRegistration): ExecutionReplayCapsulePreview;
+    preview(capsuleId: CapsuleId): ExecutionReplayCapsulePreview | undefined;
     replay(request: ReplayCapsuleRequest): Promise<RuntimeInvocationResult>;
-    discard(capsuleId: string): void;
+    discard(capsuleId: CapsuleId): void;
     clear(): void;
 }

package/dist/devtools/capsule.js

@@ -1,3 +1,10 @@
+function capsuleLimit(value) {
+    if (!Number.isInteger(value) || value < 1)
+        throw new TypeError('maxCapsules must be a positive integer.');
+    return value;
+}
+import { createCapsuleId, createCaptureHandleId } from './identity-internal.js';
+import { milliseconds, epochNow, expiresAt } from '../core/units.js';
 import { serializeDevtoolsError } from './observer.js';
 import { previewDevtoolsValue } from './values.js';
 import { match } from 'ts-pattern';
@@ -13,21 +20,18 @@ export class ReplayCapsuleStore {
     #references = new Map();
     constructor(runId, options = {}) {
         this.#runId = runId;
-        this.#ttlMs = options.ttlMs ?? defaultCapsuleTtlMs;
-        this.#maxCapsules = options.maxCapsules ?? defaultMaxCapsules;
+        this.#ttlMs = milliseconds(options.ttlMs ?? defaultCapsuleTtlMs);
+        this.#maxCapsules = capsuleLimit(options.maxCapsules ?? defaultMaxCapsules);
         this.#capture = options.capture;
         this.#redact = options.redact ?? [];
         if (!Number.isFinite(this.#ttlMs) || this.#ttlMs <= 0) {
             throw new TypeError('capsuleTtlMs must be a positive finite number.');
         }
-        if (!Number.isInteger(this.#maxCapsules) || this.#maxCapsules < 1) {
-            throw new TypeError('maxCapsules must be a positive integer.');
-        }
     }
     createExecution(traceId, spanId, observation, registration) {
         this.#purgeExpired();
-        const id = `capsule_${crypto.randomUUID()}`;
-        const createdAt = Date.now();
+        const id = createCapsuleId();
+        const createdAt = epochNow();
         const captured = this.#captureValue(registration.input);
         const preview = {
             id,
@@ -36,7 +40,7 @@ export class ReplayCapsuleStore {
             traceId,
             spanId,
             createdAt,
-            expiresAt: createdAt + this.#ttlMs,
+            expiresAt: expiresAt(createdAt, this.#ttlMs),
             execution: {
                 executionId: observation.executionId,
                 executionKind: observation.executionKind,
@@ -145,7 +149,7 @@ export class ReplayCapsuleStore {
             // cloneできない値を失うより、同一process内だけで有効な参照として保持する。
         }
         if (value !== undefined) {
-            const handleId = `ref_${crypto.randomUUID()}`;
+            const handleId = createCaptureHandleId();
             this.#references.set(handleId, value);
             return { mode: 'reference', handleId };
         }
@@ -166,7 +170,7 @@ export class ReplayCapsuleStore {
             .exhaustive();
     }
     #purgeExpired() {
-        const now = Date.now();
+        const now = epochNow();
         for (const [id, capsule] of this.#capsules) {
             if (capsule.preview.expiresAt > now)
                 continue;

package/dist/devtools/decoder.d.ts

@@ -0,0 +1,15 @@
+import type { RuntimeEvent } from './observer.js';
+import type { ReplayCapsuleRequest, ProviderPlaygroundRequest, ProviderMethodInvocationRequest } from './inspector.js';
+export declare const isDevtoolsRecord: (value: unknown) => value is Record<string, unknown>;
+export declare function decodeRuntimeEvent(value: unknown): RuntimeEvent | undefined;
+export type InspectorCommand = {
+    readonly type: 'command.replay-capsule';
+    readonly request: ReplayCapsuleRequest;
+} | {
+    readonly type: 'command.provider-playground';
+    readonly request: ProviderPlaygroundRequest;
+} | {
+    readonly type: 'command.invoke-provider-method';
+    readonly request: ProviderMethodInvocationRequest;
+};
+export declare function decodeInspectorCommand(value: unknown): InspectorCommand | undefined;