@graphorin/core 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -2,9 +2,9 @@ import { AnyValue, Barrier, Channel, ChannelKind, Ephemeral, LatestValue, ListAg
 import { Directive, DirectiveOptions } from "./channels/directive.js";
 import { Dispatch, dispatch } from "./channels/dispatch.js";
 import { APPROVAL_PAUSE_KIND, AWAKEABLE_PAUSE_KIND, ApprovalPauseValue, AwakeablePauseValue, TIMER_PAUSE_KIND, TimerPauseValue, awaitExternal, isApprovalPauseValue, isAwakeablePauseValue, isTimerPauseValue, requestApproval, sleepFor, sleepUntil } from "./channels/durable.js";
-import { PAUSE_SIGNAL_BRAND, PauseResumeScope, PauseSignal, isPauseSignal, pause, runWithPauseResume } from "./channels/pause.js";
+import { PAUSE_SIGNAL_BRAND, PauseIdentity, PauseResumeScope, PauseSignal, REPLAY_DIVERGENCE_BRAND, ReplayDivergenceSignal, isPauseSignal, isReplayDivergenceSignal, pause, runWithPauseResume } from "./channels/pause.js";
 import { AuthTokenRecord, AuthTokenStore } from "./contracts/auth-token-store.js";
-import { Checkpoint, CheckpointConflictError, CheckpointId, CheckpointMetadata, CheckpointPutOptions, CheckpointStore, CheckpointTuple, ListOptions, PendingWrite } from "./contracts/checkpoint-store.js";
+import { Checkpoint, CheckpointConflictError, CheckpointId, CheckpointMetadata, CheckpointPutOptions, CheckpointStore, CheckpointStoreExt, CheckpointTuple, ListOptions, PendingWrite, PruneThreadsOptions } from "./contracts/checkpoint-store.js";
 import { EmbedOptions, EmbedderProvider } from "./contracts/embedder.js";
 import { EvalSample, EvalScore, EvalScorer } from "./contracts/eval-scorer.js";
 import { LocalProviderTrust, OllamaTrust } from "./contracts/local-provider-trust.js";
@@ -14,10 +14,10 @@ import { Block, EntityRole, Episode, Fact, GraphEntity, Insight, MemoryHit, Memo
 import { ToolCall } from "./types/tool-call.js";
 import { AssistantMessage, AudioContent, FileContent, ImageContent, Message, MessageContent, MessageRole, ReasoningContent, ReasoningContentMeta, SystemMessage, TextContent, ToolMessage, UserMessage } from "./types/message.js";
 import { SessionScope } from "./types/session-scope.js";
-import { EpisodicMemoryStore, MemoryStore, MessageRef, ProceduralMemoryStore, SemanticMemoryStore, SessionListOptions, SessionMemoryStore, SessionMessageWithMetadata, SharedMemoryStore, WorkingMemoryStore } from "./contracts/memory-store.js";
+import { EpisodicMemoryStore, MemoryStore, MemoryStoreExt, MessageRef, ProceduralMemoryStore, SemanticMemoryStore, SessionListOptions, SessionMemoryStore, SessionMessageWithMetadata, SharedMemoryStore, WorkingMemoryStore } from "./contracts/memory-store.js";
 import { OAuthServerRecord, OAuthServerStore } from "./contracts/oauth-server-store.js";
 import { MODEL_HINTS, ModelHint, ModelSpec, ProviderLike } from "./contracts/preferred-model.js";
-import { AISpan, NOOP_TRACER, SpanAttributeValue, SpanAttributes, SpanStatus, SpanType, StartSpanOptions, Tracer } from "./contracts/tracer.js";
+import { AISpan, AddEventOptions, CustomSpanType, KnownSpanType, NOOP_TRACER, SpanAttributeValue, SpanAttributes, SpanStatus, SpanType, StartSpanOptions, Tracer } from "./contracts/tracer.js";
 import { Cost, ModelUsage, Usage, UsageAccumulator, UsageSnapshot, zeroUsage } from "./types/usage.js";
 import { ReasoningContract, ReasoningRetention } from "./contracts/reasoning-retention.js";
 import { ComposeProviderMiddleware, FinishReason, OutputSpec, Provider, ProviderCachePolicy, ProviderCapabilities, ProviderError, ProviderErrorKind, ProviderEvent, ProviderMiddleware, ProviderRequest, ProviderRequestMetadata, ProviderResponse, ResponseMetadata, ToolChoice, ToolDefinition, ToolDefinitionExample } from "./contracts/provider.js";
@@ -30,11 +30,13 @@ import { Handoff, HandoffFilter, HandoffInputFilterDescriptor, HandoffRecord, Ha
 import { AgentRegistryEntry, SessionAuditEntry, SessionMetadata, SessionStore, SessionStoreExt, SessionWorkflowRun } from "./contracts/session-store.js";
 import { TokenCounter } from "./contracts/token-counter.js";
 import { CompletedToolCall, ContentChunk, InboundSanitizationPolicy, MemoryGuardTier, RecoveryHint, ResultHandle, SandboxPolicy, SideEffectClass, ToolApproval, ToolError, ToolErrorKind, ToolOutcome, ToolResult, ToolSource, ToolTrustClass, TruncationStrategy } from "./types/tool.js";
-import { RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, TodoItem, flattenUsageByModel } from "./types/run.js";
+import { ReadonlyRunState, RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, TodoItem, flattenUsageByModel } from "./types/run.js";
 import { ValidationResult, ZodLikeError, ZodLikeSafeParseResult, ZodLikeSchema, validate, validateOrThrow } from "./utils/validation.js";
-import { ResolvedTool, Tool, ToolExample, ToolExecutionContext, ToolReturn, ToolSecretsAccessor } from "./contracts/tool.js";
+import { AnyTool, ResolvedTool, TOOL_RETURN_BRAND, Tool, ToolExample, ToolExecutionContext, ToolReturn, ToolSecretsAccessor, isToolReturnEnvelope, isUnbrandedToolReturn, toolReturn } from "./contracts/tool.js";
 import { TriggerState, TriggerStore } from "./contracts/trigger-store.js";
 import { AgentCancellingEvent, AgentEndEvent, AgentErrorEvent, AgentEvaluatorConvergedEvent, AgentEvaluatorIterationEvent, AgentEvent, AgentFanOutMergedEvent, AgentFanOutSpawnedEvent, AgentFollowUpQueuedEvent, AgentLateralLeakDetectedEvent, AgentModelFellbackEvent, AgentProgressReadEvent, AgentProgressWrittenEvent, AgentResult, AgentStartEvent, AgentSteeredEvent, ContextCompactedEvent, FanOutChildMetadata, GuardrailTrippedEvent, HandoffEvent, LateralLeakVector, ProgressArtifactRef, ReasoningDeltaEvent, StepEndEvent, StepStartEvent, TextCompleteEvent, TextDeltaEvent, ToolApprovalDeniedEvent, ToolApprovalGrantedEvent, ToolApprovalRequestedEvent, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolExecuteEndEvent, ToolExecuteErrorEvent, ToolExecutePartialEvent, ToolExecuteProgressEvent, ToolExecuteStartEvent, VerifierResultEvent } from "./types/agent-event.js";
+import { EncodedBinary, EncodedBytes, EncodedUrl, WireAssistantMessage, WireAudioContent, WireCompletedToolCall, WireFileContent, WireImageContent, WireMessage, WireMessageContent, WireRunState, WireRunStep, WireToolMessage, WireToolOutcome, WireToolResult, WireUserMessage, base64ToBytes, bytesToBase64, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState } from "./utils/binary-json.js";
+import { WireAgentEndEvent, WireAgentEvent, WireContentChunk, WireFileGeneratedEvent, WireToolExecutePartialEvent, fromWireAgentEvent, toWireAgentEvent } from "./types/agent-event-wire.js";
 import { StopCondition, and, hasToolCall, isStepCount, isTerminal, not, or } from "./types/stop-condition.js";
 import { WorkflowChannelUpdateEvent, WorkflowCheckpointWrittenEvent, WorkflowCustomEvent, WorkflowEndEvent, WorkflowErrorEvent, WorkflowEvent, WorkflowResumedEvent, WorkflowStartEvent, WorkflowStepEndEvent, WorkflowStepStartEvent, WorkflowSuspendedEvent, WorkflowTaskEndEvent, WorkflowTaskStartEvent } from "./types/workflow-event.js";
 import { assertNever } from "./utils/assert-never.js";
@@ -53,8 +55,11 @@ import { collect, filter, mapStream, merge, take, takeWhile, withSignal } from "
  *
  * @packageDocumentation
  */
-/** Canonical version constant. Mirrors the `package.json` version. */
-declare const VERSION = "0.6.0";
+/**
+ * Canonical version constant, derived from `package.json` at build
+ * time so a release bump never has to edit source.
+ */
+declare const VERSION: string;
 //#endregion
-export { AISpan, APPROVAL_PAUSE_KIND, AWAKEABLE_PAUSE_KIND, AgentCancellingEvent, AgentEndEvent, AgentErrorEvent, AgentEvaluatorConvergedEvent, AgentEvaluatorIterationEvent, AgentEvent, AgentFanOutMergedEvent, AgentFanOutSpawnedEvent, AgentFollowUpQueuedEvent, AgentLateralLeakDetectedEvent, AgentModelFellbackEvent, AgentProgressReadEvent, AgentProgressWrittenEvent, AgentRegistryEntry, AgentResult, AgentStartEvent, AgentSteeredEvent, AnyValue, ApprovalPauseValue, AssistantMessage, AsyncContext, AudioContent, AuthTokenRecord, AuthTokenStore, AwakeablePauseValue, Barrier, Block, Channel, ChannelKind, Checkpoint, CheckpointConflictError, CheckpointId, CheckpointMetadata, CheckpointPutOptions, CheckpointStore, CheckpointTuple, CompletedToolCall, ComposeProviderMiddleware, ContentChunk, ContextCompactedEvent, Cost, Directive, DirectiveOptions, Dispatch, EmbedOptions, EmbedderProvider, EntityRole, Ephemeral, Episode, EpisodicMemoryStore, EvalSample, EvalScore, EvalScorer, Fact, FanOutChildMetadata, FileContent, FinishReason, GraphEntity, GuardrailTrippedEvent, Handoff, HandoffEvent, HandoffFilter, HandoffInputFilterDescriptor, HandoffRecord, HandoffSecretsInheritance, ImageContent, InboundSanitizationPolicy, Insight, LateralLeakVector, LatestValue, ListAggregate, ListOptions, LocalProviderTrust, LogFields, LogLevel, Logger, MODEL_HINTS, MemoryGuardTier, MemoryHit, MemoryKind, MemoryMetadata, MemoryOwner, MemoryProvenance, MemoryRecord, MemorySearchOptions, MemoryStatus, MemoryStore, Message, MessageContent, MessageRef, MessageRole, ModelHint, ModelSpec, ModelUsage, NODEJS_INSPECT_CUSTOM, NOOP_LOGGER, NOOP_TRACER, OAuthServerRecord, OAuthServerStore, OllamaTrust, OutputSpec, PAUSE_SIGNAL_BRAND, PauseResumeScope, PauseSignal, PendingWrite, ProceduralMemoryStore, ProgressArtifactRef, Provider, ProviderCachePolicy, ProviderCapabilities, ProviderError, ProviderErrorKind, ProviderEvent, ProviderLike, ProviderMiddleware, ProviderRequest, ProviderRequestMetadata, ProviderResponse, ReasoningContent, ReasoningContentMeta, ReasoningContract, ReasoningDeltaEvent, ReasoningRetention, RecoveryHint, RedactionInput, RedactionOutput, RedactionValidator, Reducer, ResolvedTool, ResponseMetadata, ResultHandle, Rule, RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, SECRET_VALUE_BRAND, SENSITIVITY_ORDER, Sandbox, SandboxCode, SandboxPolicy, SandboxResult, SandboxRunOptions, SecretMetadata, SecretRef, SecretResolver, SecretResolverContext, SecretValue, SecretValueOptions, SecretValueStatic, SecretsSetOptions, SecretsStore, SemanticMemoryStore, Sensitivity, SessionAuditEntry, SessionListOptions, SessionMemoryStore, SessionMessageWithMetadata, SessionMetadata, SessionScope, SessionStore, SessionStoreExt, SessionWorkflowRun, SharedMemoryStore, SideEffectClass, SpanAttributeValue, SpanAttributes, SpanStatus, SpanType, StartSpanOptions, StepEndEvent, StepStartEvent, StopCondition, Stream, SystemMessage, TIMER_PAUSE_KIND, TextCompleteEvent, TextContent, TextDeltaEvent, TimerPauseValue, TodoItem, TokenCounter, Tool, ToolApproval, ToolApprovalDeniedEvent, ToolApprovalGrantedEvent, ToolApprovalRequestedEvent, ToolCall, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolChoice, ToolDefinition, ToolDefinitionExample, ToolError, ToolErrorKind, ToolExample, ToolExecuteEndEvent, ToolExecuteErrorEvent, ToolExecutePartialEvent, ToolExecuteProgressEvent, ToolExecuteStartEvent, ToolExecutionContext, ToolMessage, ToolOutcome, ToolResult, ToolReturn, ToolSecretsAccessor, ToolSource, ToolTrustClass, Tracer, TriggerState, TriggerStore, TruncationStrategy, Usage, UsageAccumulator, UsageSnapshot, UserMessage, VERSION, ValidationResult, VerifierResultEvent, WorkflowChannelUpdateEvent, WorkflowCheckpointWrittenEvent, WorkflowCustomEvent, WorkflowEndEvent, WorkflowErrorEvent, WorkflowEvent, WorkflowResumedEvent, WorkflowStartEvent, WorkflowStepEndEvent, WorkflowStepStartEvent, WorkflowSuspendedEvent, WorkflowTaskEndEvent, WorkflowTaskStartEvent, WorkingMemoryStore, ZodLikeError, ZodLikeSafeParseResult, ZodLikeSchema, acceptsSensitivity, and, anyValue, assertNever, awaitExternal, barrier, collect, createAsyncContext, dispatch, ephemeral, filter, flattenUsageByModel, hasToolCall, isApprovalPauseValue, isAwakeablePauseValue, isPauseSignal, isStepCount, isTerminal, isTimerPauseValue, latestValue, listAggregate, mapStream, md5, merge, not, or, pause, reducer, requestApproval, runWithPauseResume, sleepFor, sleepUntil, stream, take, takeWhile, validate, validateOrThrow, withSignal, xxhash, zeroUsage };
+export { AISpan, APPROVAL_PAUSE_KIND, AWAKEABLE_PAUSE_KIND, AddEventOptions, AgentCancellingEvent, AgentEndEvent, AgentErrorEvent, AgentEvaluatorConvergedEvent, AgentEvaluatorIterationEvent, AgentEvent, AgentFanOutMergedEvent, AgentFanOutSpawnedEvent, AgentFollowUpQueuedEvent, AgentLateralLeakDetectedEvent, AgentModelFellbackEvent, AgentProgressReadEvent, AgentProgressWrittenEvent, AgentRegistryEntry, AgentResult, AgentStartEvent, AgentSteeredEvent, AnyTool, AnyValue, ApprovalPauseValue, AssistantMessage, AsyncContext, AudioContent, AuthTokenRecord, AuthTokenStore, AwakeablePauseValue, Barrier, Block, Channel, ChannelKind, Checkpoint, CheckpointConflictError, CheckpointId, CheckpointMetadata, CheckpointPutOptions, CheckpointStore, CheckpointStoreExt, CheckpointTuple, CompletedToolCall, ComposeProviderMiddleware, ContentChunk, ContextCompactedEvent, Cost, CustomSpanType, Directive, DirectiveOptions, Dispatch, EmbedOptions, EmbedderProvider, EncodedBinary, EncodedBytes, EncodedUrl, EntityRole, Ephemeral, Episode, EpisodicMemoryStore, EvalSample, EvalScore, EvalScorer, Fact, FanOutChildMetadata, FileContent, FinishReason, GraphEntity, GuardrailTrippedEvent, Handoff, HandoffEvent, HandoffFilter, HandoffInputFilterDescriptor, HandoffRecord, HandoffSecretsInheritance, ImageContent, InboundSanitizationPolicy, Insight, KnownSpanType, LateralLeakVector, LatestValue, ListAggregate, ListOptions, LocalProviderTrust, LogFields, LogLevel, Logger, MODEL_HINTS, MemoryGuardTier, MemoryHit, MemoryKind, MemoryMetadata, MemoryOwner, MemoryProvenance, MemoryRecord, MemorySearchOptions, MemoryStatus, MemoryStore, MemoryStoreExt, Message, MessageContent, MessageRef, MessageRole, ModelHint, ModelSpec, ModelUsage, NODEJS_INSPECT_CUSTOM, NOOP_LOGGER, NOOP_TRACER, OAuthServerRecord, OAuthServerStore, OllamaTrust, OutputSpec, PAUSE_SIGNAL_BRAND, PauseIdentity, PauseResumeScope, PauseSignal, PendingWrite, ProceduralMemoryStore, ProgressArtifactRef, Provider, ProviderCachePolicy, ProviderCapabilities, ProviderError, ProviderErrorKind, ProviderEvent, ProviderLike, ProviderMiddleware, ProviderRequest, ProviderRequestMetadata, ProviderResponse, PruneThreadsOptions, REPLAY_DIVERGENCE_BRAND, ReadonlyRunState, ReasoningContent, ReasoningContentMeta, ReasoningContract, ReasoningDeltaEvent, ReasoningRetention, RecoveryHint, RedactionInput, RedactionOutput, RedactionValidator, Reducer, ReplayDivergenceSignal, ResolvedTool, ResponseMetadata, ResultHandle, Rule, RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, SECRET_VALUE_BRAND, SENSITIVITY_ORDER, Sandbox, SandboxCode, SandboxPolicy, SandboxResult, SandboxRunOptions, SecretMetadata, SecretRef, SecretResolver, SecretResolverContext, SecretValue, SecretValueOptions, SecretValueStatic, SecretsSetOptions, SecretsStore, SemanticMemoryStore, Sensitivity, SessionAuditEntry, SessionListOptions, SessionMemoryStore, SessionMessageWithMetadata, SessionMetadata, SessionScope, SessionStore, SessionStoreExt, SessionWorkflowRun, SharedMemoryStore, SideEffectClass, SpanAttributeValue, SpanAttributes, SpanStatus, SpanType, StartSpanOptions, StepEndEvent, StepStartEvent, StopCondition, Stream, SystemMessage, TIMER_PAUSE_KIND, TOOL_RETURN_BRAND, TextCompleteEvent, TextContent, TextDeltaEvent, TimerPauseValue, TodoItem, TokenCounter, Tool, ToolApproval, ToolApprovalDeniedEvent, ToolApprovalGrantedEvent, ToolApprovalRequestedEvent, ToolCall, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolChoice, ToolDefinition, ToolDefinitionExample, ToolError, ToolErrorKind, ToolExample, ToolExecuteEndEvent, ToolExecuteErrorEvent, ToolExecutePartialEvent, ToolExecuteProgressEvent, ToolExecuteStartEvent, ToolExecutionContext, ToolMessage, ToolOutcome, ToolResult, ToolReturn, ToolSecretsAccessor, ToolSource, ToolTrustClass, Tracer, TriggerState, TriggerStore, TruncationStrategy, Usage, UsageAccumulator, UsageSnapshot, UserMessage, VERSION, ValidationResult, VerifierResultEvent, WireAgentEndEvent, WireAgentEvent, WireAssistantMessage, WireAudioContent, WireCompletedToolCall, WireContentChunk, WireFileContent, WireFileGeneratedEvent, WireImageContent, WireMessage, WireMessageContent, WireRunState, WireRunStep, WireToolExecutePartialEvent, WireToolMessage, WireToolOutcome, WireToolResult, WireUserMessage, WorkflowChannelUpdateEvent, WorkflowCheckpointWrittenEvent, WorkflowCustomEvent, WorkflowEndEvent, WorkflowErrorEvent, WorkflowEvent, WorkflowResumedEvent, WorkflowStartEvent, WorkflowStepEndEvent, WorkflowStepStartEvent, WorkflowSuspendedEvent, WorkflowTaskEndEvent, WorkflowTaskStartEvent, WorkingMemoryStore, ZodLikeError, ZodLikeSafeParseResult, ZodLikeSchema, acceptsSensitivity, and, anyValue, assertNever, awaitExternal, barrier, base64ToBytes, bytesToBase64, collect, createAsyncContext, dispatch, ephemeral, filter, flattenUsageByModel, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, fromWireAgentEvent, hasToolCall, isApprovalPauseValue, isAwakeablePauseValue, isPauseSignal, isReplayDivergenceSignal, isStepCount, isTerminal, isTimerPauseValue, isToolReturnEnvelope, isUnbrandedToolReturn, latestValue, listAggregate, mapStream, md5, merge, not, or, pause, reducer, requestApproval, runWithPauseResume, sleepFor, sleepUntil, stream, take, takeWhile, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState, toWireAgentEvent, toolReturn, validate, validateOrThrow, withSignal, xxhash, zeroUsage };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAYa,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiBa"}

package/dist/index.js

@@ -1,15 +1,17 @@
+import { version } from "./package.js";
 import { anyValue, barrier, ephemeral, latestValue, listAggregate, reducer, stream } from "./channels/channels.js";
 import { Directive } from "./channels/directive.js";
 import { Dispatch, dispatch } from "./channels/dispatch.js";
-import { PAUSE_SIGNAL_BRAND, PauseSignal, isPauseSignal, pause, runWithPauseResume } from "./channels/pause.js";
+import { PAUSE_SIGNAL_BRAND, PauseSignal, REPLAY_DIVERGENCE_BRAND, ReplayDivergenceSignal, isPauseSignal, isReplayDivergenceSignal, pause, runWithPauseResume } from "./channels/pause.js";
 import { APPROVAL_PAUSE_KIND, AWAKEABLE_PAUSE_KIND, TIMER_PAUSE_KIND, awaitExternal, isApprovalPauseValue, isAwakeablePauseValue, isTimerPauseValue, requestApproval, sleepFor, sleepUntil } from "./channels/durable.js";
-import "./channels/index.js";
 import { CheckpointConflictError } from "./contracts/checkpoint-store.js";
 import { NOOP_LOGGER } from "./contracts/logger.js";
 import { MODEL_HINTS } from "./contracts/preferred-model.js";
 import { NODEJS_INSPECT_CUSTOM, SECRET_VALUE_BRAND } from "./contracts/secret-value.js";
+import { TOOL_RETURN_BRAND, isToolReturnEnvelope, isUnbrandedToolReturn, toolReturn } from "./contracts/tool.js";
 import { NOOP_TRACER } from "./contracts/tracer.js";
-import "./contracts/index.js";
+import { base64ToBytes, bytesToBase64, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState } from "./utils/binary-json.js";
+import { fromWireAgentEvent, toWireAgentEvent } from "./types/agent-event-wire.js";
 import { flattenUsageByModel } from "./types/run.js";
 import { SENSITIVITY_ORDER, acceptsSensitivity } from "./types/sensitivity.js";
 import { and, hasToolCall, isStepCount, isTerminal, not, or } from "./types/stop-condition.js";
@@ -19,7 +21,6 @@ import { createAsyncContext } from "./utils/async-context.js";
 import { md5, xxhash } from "./utils/hash.js";
 import { collect, filter, mapStream, merge, take, takeWhile, withSignal } from "./utils/streams.js";
 import { validate, validateOrThrow } from "./utils/validation.js";
-import "./utils/index.js";
 
 //#region src/index.ts
 /**
@@ -32,9 +33,12 @@ import "./utils/index.js";
 *
 * @packageDocumentation
 */
-/** Canonical version constant. Mirrors the `package.json` version. */
-const VERSION = "0.6.0";
+/**
+* Canonical version constant, derived from `package.json` at build
+* time so a release bump never has to edit source.
+*/
+const VERSION = version;
 
 //#endregion
-export { APPROVAL_PAUSE_KIND, AWAKEABLE_PAUSE_KIND, CheckpointConflictError, Directive, Dispatch, MODEL_HINTS, NODEJS_INSPECT_CUSTOM, NOOP_LOGGER, NOOP_TRACER, PAUSE_SIGNAL_BRAND, PauseSignal, SECRET_VALUE_BRAND, SENSITIVITY_ORDER, TIMER_PAUSE_KIND, VERSION, acceptsSensitivity, and, anyValue, assertNever, awaitExternal, barrier, collect, createAsyncContext, dispatch, ephemeral, filter, flattenUsageByModel, hasToolCall, isApprovalPauseValue, isAwakeablePauseValue, isPauseSignal, isStepCount, isTerminal, isTimerPauseValue, latestValue, listAggregate, mapStream, md5, merge, not, or, pause, reducer, requestApproval, runWithPauseResume, sleepFor, sleepUntil, stream, take, takeWhile, validate, validateOrThrow, withSignal, xxhash, zeroUsage };
+export { APPROVAL_PAUSE_KIND, AWAKEABLE_PAUSE_KIND, CheckpointConflictError, Directive, Dispatch, MODEL_HINTS, NODEJS_INSPECT_CUSTOM, NOOP_LOGGER, NOOP_TRACER, PAUSE_SIGNAL_BRAND, PauseSignal, REPLAY_DIVERGENCE_BRAND, ReplayDivergenceSignal, SECRET_VALUE_BRAND, SENSITIVITY_ORDER, TIMER_PAUSE_KIND, TOOL_RETURN_BRAND, VERSION, acceptsSensitivity, and, anyValue, assertNever, awaitExternal, barrier, base64ToBytes, bytesToBase64, collect, createAsyncContext, dispatch, ephemeral, filter, flattenUsageByModel, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, fromWireAgentEvent, hasToolCall, isApprovalPauseValue, isAwakeablePauseValue, isPauseSignal, isReplayDivergenceSignal, isStepCount, isTerminal, isTimerPauseValue, isToolReturnEnvelope, isUnbrandedToolReturn, latestValue, listAggregate, mapStream, md5, merge, not, or, pause, reducer, requestApproval, runWithPauseResume, sleepFor, sleepUntil, stream, take, takeWhile, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState, toWireAgentEvent, toolReturn, validate, validateOrThrow, withSignal, xxhash, zeroUsage };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/core - types, contracts, and utilities for the Graphorin\n * framework. Dependency-free root package every other `@graphorin/*`\n * package depends on.\n *\n * The full documentation lives in the package `README.md` and the\n * sub-module barrels (`./types`, `./contracts`, `./utils`, `./channels`).\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.6.0';\n\nexport * from './channels/index.js';\nexport * from './contracts/index.js';\nexport * from './types/index.js';\nexport * from './utils/index.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAYA,MAAa,UAAU"}
+{"version":3,"file":"index.js","names":["VERSION: string","pkg.version"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/core - types, contracts, and utilities for the Graphorin\n * framework. Dependency-free root package every other `@graphorin/*`\n * package depends on.\n *\n * The full documentation lives in the package `README.md` and the\n * sub-module barrels (`./types`, `./contracts`, `./utils`, `./channels`).\n *\n * @packageDocumentation\n */\n\nimport pkg from '../package.json' with { type: 'json' };\n\n/**\n * Canonical version constant, derived from `package.json` at build\n * time so a release bump never has to edit source.\n */\nexport const VERSION: string = pkg.version;\n\nexport * from './channels/index.js';\nexport * from './contracts/index.js';\nexport * from './types/index.js';\nexport * from './utils/index.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBA,MAAaA,UAAkBC"}

package/dist/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.7.0";
+
+//#endregion
+export { version };
+//# sourceMappingURL=package.js.map

package/dist/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/core\",\n  \"version\": \"0.7.0\",\n  \"description\": \"Core types, contracts, and utilities for the Graphorin framework. Dependency-free root package every other @graphorin/* package depends on.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/core\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/core\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"types\",\n    \"contracts\"\n  ],\n  \"type\": \"module\",\n  \"sideEffects\": false,\n  \"engines\": {\n    \"node\": \">=22.12.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./types\": {\n      \"types\": \"./dist/types/index.d.ts\",\n      \"default\": \"./dist/types/index.js\"\n    },\n    \"./contracts\": {\n      \"types\": \"./dist/contracts/index.d.ts\",\n      \"default\": \"./dist/contracts/index.js\"\n    },\n    \"./utils\": {\n      \"types\": \"./dist/utils/index.d.ts\",\n      \"default\": \"./dist/utils/index.js\"\n    },\n    \"./channels\": {\n      \"types\": \"./dist/channels/index.d.ts\",\n      \"default\": \"./dist/channels/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"src\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"peerDependencies\": {\n    \"zod\": \"^3.23.0 || ^4.0.0\"\n  },\n  \"peerDependenciesMeta\": {\n    \"zod\": {\n      \"optional\": false\n    }\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  },\n  \"devDependencies\": {\n    \"zod\": \"^3.25.0\"\n  }\n}\n"],"mappings":";cAEa"}

package/dist/types/agent-event-wire.d.ts

@@ -0,0 +1,74 @@
+import { ContentChunk } from "./tool.js";
+import { AgentEndEvent, AgentEvent, AgentResult, FileGeneratedEvent, SubagentEvent, ToolExecutePartialEvent } from "./agent-event.js";
+import { EncodedBytes, WireRunState } from "../utils/binary-json.js";
+
+//#region src/types/agent-event-wire.d.ts
+
+/** Wire twin of the binary {@link ContentChunk} variant. @stable */
+type WireContentChunk = Exclude<ContentChunk, {
+  readonly kind: 'image';
+}> | {
+  readonly kind: 'image';
+  readonly data: EncodedBytes;
+  readonly mediaType: string;
+};
+/** Wire twin of `FileGeneratedEvent`. @stable */
+interface WireFileGeneratedEvent extends Omit<FileGeneratedEvent, 'data'> {
+  readonly data: EncodedBytes;
+}
+/** Wire twin of {@link ToolExecutePartialEvent}. @stable */
+interface WireToolExecutePartialEvent extends Omit<ToolExecutePartialEvent, 'chunk'> {
+  readonly chunk: WireContentChunk;
+}
+/**
+ * Wire twin of {@link AgentEndEvent}: `result.state` is the JSON-safe
+ * {@link WireRunState} projection.
+ *
+ * @stable
+ */
+interface WireAgentEndEvent<TOutput = string> extends Omit<AgentEndEvent<TOutput>, 'result'> {
+  readonly result: Omit<AgentResult<TOutput>, 'state'> & {
+    readonly state: WireRunState;
+  };
+}
+/**
+ * JSON-safe twin of {@link AgentEvent}: the three binary-bearing
+ * variants are replaced by their wire twins, every other variant
+ * passes through structurally unchanged.
+ *
+ * This is the actual payload shape a server puts on the wire (inside
+ * the `{ eventId, subject, type, payload }` envelope) - see
+ * {@link toWireAgentEvent}.
+ *
+ * @stable
+ */
+/**
+ * Wire twin of {@link SubagentEvent} (W-036): the wrapped child event
+ * projects recursively - a forwarded child `agent.end` carries a full
+ * `RunState` of its own.
+ *
+ * @stable
+ */
+interface WireSubagentEvent extends Omit<SubagentEvent, 'event'> {
+  readonly event: WireAgentEvent<unknown>;
+}
+type WireAgentEvent<TOutput = string> = Exclude<AgentEvent<TOutput>, FileGeneratedEvent | ToolExecutePartialEvent | AgentEndEvent<TOutput> | SubagentEvent> | WireFileGeneratedEvent | WireToolExecutePartialEvent | WireSubagentEvent | WireAgentEndEvent<TOutput>;
+/**
+ * Project an {@link AgentEvent} into its JSON-safe {@link WireAgentEvent}
+ * twin. Idempotent: projecting an already-wire event returns an
+ * equivalent value. Events of unknown `type` pass through untouched.
+ *
+ * @stable
+ */
+declare function toWireAgentEvent<TOutput = string>(ev: AgentEvent<TOutput> | WireAgentEvent<TOutput>): WireAgentEvent<TOutput>;
+/**
+ * Inverse of {@link toWireAgentEvent}: decode base64 envelopes back
+ * into `Uint8Array` / `URL` instances. Exposed for `@graphorin/client`
+ * consumers that want runtime types back after `JSON.parse`.
+ *
+ * @stable
+ */
+declare function fromWireAgentEvent<TOutput = string>(ev: WireAgentEvent<TOutput> | AgentEvent<TOutput>): AgentEvent<TOutput>;
+//#endregion
+export { WireAgentEndEvent, WireAgentEvent, WireContentChunk, WireFileGeneratedEvent, WireToolExecutePartialEvent, fromWireAgentEvent, toWireAgentEvent };
+//# sourceMappingURL=agent-event-wire.d.ts.map

package/dist/types/agent-event-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-event-wire.d.ts","names":[],"sources":["../../src/types/agent-event-wire.ts"],"sourcesContent":[],"mappings":";;;;;;AAyDA;AAC6B,KArBjB,gBAAA,GACR,OAoByB,CApBjB,YAoBiB,EAAA;EAAd,SAAA,IAAA,EAAA,OAAA;CACqB,CAAA,GAAA;EAAZ,SAAA,IAAA,EAAA,OAAA;EAAL,SAAA,IAAA,EApB0B,YAoB1B;EAAwD,SAAA,SAAA,EAAA,MAAA;CADjE;;AAsBO,UAtCA,sBAAA,SAA+B,IAsCb,CAtCkB,kBAsClB,EAAA,MAAA,CAAA,CAAA;EAAa,SAAA,IAAA,EArC/B,YAqC+B;;;AAAD,UAjC9B,2BAAA,SAAoC,IAiCN,CAjCW,uBAiCX,EAAA,OAAA,CAAA,CAAA;EAInC,SAAA,KAAA,EApCM,gBAoCQ;;;;;;;;AACtB,UA5Ba,iBA4Bb,CAAA,UAAA,MAAA,CAAA,SA3BM,IA2BN,CA3BW,aA2BX,CA3ByB,OA2BzB,CAAA,EAAA,QAAA,CAAA,CAAA;EAIA,SAAA,MAAA,EA9Be,IA8Bf,CA9BoB,WA8BpB,CA9BgC,OA8BhC,CAAA,EAAA,OAAA,CAAA,GAAA;IACA,SAAA,KAAA,EA/BuE,YA+BvE;EACA,CAAA;;;;AAwCJ;;;;;;;;AAkCA;;;;;;;;UArFiB,iBAAA,SAA0B,KAAK;kBAC9B;;KAGN,mCACR,QACE,WAAW,UACX,qBAAqB,0BAA0B,cAAc,WAAW,iBAE1E,yBACA,8BACA,oBACA,kBAAkB;;;;;;;;iBAuCN,uCACV,WAAW,WAAW,eAAe,WACxC,eAAe;;;;;;;;iBAgCF,yCACV,eAAe,WAAW,WAAW,WACxC,WAAW"}

package/dist/types/agent-event-wire.js

@@ -0,0 +1,130 @@
+import { base64ToBytes, bytesToBase64, fromJsonSafeRunState, toJsonSafeRunState } from "../utils/binary-json.js";
+
+//#region src/types/agent-event-wire.ts
+/**
+* JSON-safe wire projection of {@link AgentEvent} (W-046).
+*
+* Three `AgentEvent` variants carry payloads that `JSON.stringify`
+* corrupts: `file.generated` (`data: Uint8Array`),
+* `tool.execute.partial` (binary `ContentChunk`) and - the bulk -
+* `agent.end`, whose `result.state: RunState` embeds multimodal
+* messages and tool-outcome `contentParts`. The wire twins below
+* project those payloads through the binary codec so a server can
+* `JSON.stringify` any event without silently mangling it.
+*
+* `AgentResult.output` (`TOutput`) is assumed JSON-safe already
+* (a string, or a value parsed from JSON structured output) - the
+* projection does not touch it.
+*
+* @packageDocumentation
+*/
+function isRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+* Registry-hosted agents are structurally typed and may emit an
+* `agent.end` without a full `result.state` (e.g. plain `{ status,
+* output }`). Only a state that actually carries the walked arrays is
+* projected; anything else passes through untouched.
+*/
+function hasProjectableState(result) {
+	if (!isRecord(result)) return false;
+	const state = result.state;
+	return isRecord(state) && Array.isArray(state.messages) && Array.isArray(state.steps);
+}
+function encodeBytesField(data) {
+	if (data instanceof Uint8Array) return {
+		enc: "base64",
+		data: bytesToBase64(data)
+	};
+	return data;
+}
+function decodeBytesField(data) {
+	if (data instanceof Uint8Array) return data;
+	if (isRecord(data) && data.enc === "base64" && typeof data.data === "string") return base64ToBytes(data.data);
+	return new Uint8Array(0);
+}
+/**
+* Project an {@link AgentEvent} into its JSON-safe {@link WireAgentEvent}
+* twin. Idempotent: projecting an already-wire event returns an
+* equivalent value. Events of unknown `type` pass through untouched.
+*
+* @stable
+*/
+function toWireAgentEvent(ev) {
+	switch (ev.type) {
+		case "file.generated": return {
+			...ev,
+			data: encodeBytesField(ev.data)
+		};
+		case "tool.execute.partial": {
+			const chunk = ev.chunk;
+			if (chunk.kind === "image") return {
+				...ev,
+				chunk: {
+					...chunk,
+					data: encodeBytesField(chunk.data)
+				}
+			};
+			return ev;
+		}
+		case "agent.end":
+			if (!hasProjectableState(ev.result)) return ev;
+			return {
+				...ev,
+				result: {
+					...ev.result,
+					state: toJsonSafeRunState(ev.result.state)
+				}
+			};
+		case "subagent.event": return {
+			...ev,
+			event: toWireAgentEvent(ev.event)
+		};
+		default: return ev;
+	}
+}
+/**
+* Inverse of {@link toWireAgentEvent}: decode base64 envelopes back
+* into `Uint8Array` / `URL` instances. Exposed for `@graphorin/client`
+* consumers that want runtime types back after `JSON.parse`.
+*
+* @stable
+*/
+function fromWireAgentEvent(ev) {
+	switch (ev.type) {
+		case "file.generated": return {
+			...ev,
+			data: decodeBytesField(ev.data)
+		};
+		case "tool.execute.partial": {
+			const chunk = ev.chunk;
+			if (chunk.kind === "image") return {
+				...ev,
+				chunk: {
+					...chunk,
+					data: decodeBytesField(chunk.data)
+				}
+			};
+			return ev;
+		}
+		case "agent.end":
+			if (!hasProjectableState(ev.result)) return ev;
+			return {
+				...ev,
+				result: {
+					...ev.result,
+					state: fromJsonSafeRunState(ev.result.state)
+				}
+			};
+		case "subagent.event": return {
+			...ev,
+			event: fromWireAgentEvent(ev.event)
+		};
+		default: return ev;
+	}
+}
+
+//#endregion
+export { fromWireAgentEvent, toWireAgentEvent };
+//# sourceMappingURL=agent-event-wire.js.map

package/dist/types/agent-event-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-event-wire.js","names":[],"sources":["../../src/types/agent-event-wire.ts"],"sourcesContent":["/**\n * JSON-safe wire projection of {@link AgentEvent} (W-046).\n *\n * Three `AgentEvent` variants carry payloads that `JSON.stringify`\n * corrupts: `file.generated` (`data: Uint8Array`),\n * `tool.execute.partial` (binary `ContentChunk`) and - the bulk -\n * `agent.end`, whose `result.state: RunState` embeds multimodal\n * messages and tool-outcome `contentParts`. The wire twins below\n * project those payloads through the binary codec so a server can\n * `JSON.stringify` any event without silently mangling it.\n *\n * `AgentResult.output` (`TOutput`) is assumed JSON-safe already\n * (a string, or a value parsed from JSON structured output) - the\n * projection does not touch it.\n *\n * @packageDocumentation\n */\n\nimport {\n  base64ToBytes,\n  bytesToBase64,\n  type EncodedBytes,\n  fromJsonSafeRunState,\n  toJsonSafeRunState,\n  type WireRunState,\n} from '../utils/binary-json.js';\nimport type {\n  AgentEndEvent,\n  AgentEvent,\n  AgentResult,\n  FileGeneratedEvent,\n  SubagentEvent,\n  ToolExecutePartialEvent,\n} from './agent-event.js';\nimport type { ContentChunk } from './tool.js';\n\n/** Wire twin of the binary {@link ContentChunk} variant. @stable */\nexport type WireContentChunk =\n  | Exclude<ContentChunk, { readonly kind: 'image' }>\n  | { readonly kind: 'image'; readonly data: EncodedBytes; readonly mediaType: string };\n\n/** Wire twin of `FileGeneratedEvent`. @stable */\nexport interface WireFileGeneratedEvent extends Omit<FileGeneratedEvent, 'data'> {\n  readonly data: EncodedBytes;\n}\n\n/** Wire twin of {@link ToolExecutePartialEvent}. @stable */\nexport interface WireToolExecutePartialEvent extends Omit<ToolExecutePartialEvent, 'chunk'> {\n  readonly chunk: WireContentChunk;\n}\n\n/**\n * Wire twin of {@link AgentEndEvent}: `result.state` is the JSON-safe\n * {@link WireRunState} projection.\n *\n * @stable\n */\nexport interface WireAgentEndEvent<TOutput = string>\n  extends Omit<AgentEndEvent<TOutput>, 'result'> {\n  readonly result: Omit<AgentResult<TOutput>, 'state'> & { readonly state: WireRunState };\n}\n\n/**\n * JSON-safe twin of {@link AgentEvent}: the three binary-bearing\n * variants are replaced by their wire twins, every other variant\n * passes through structurally unchanged.\n *\n * This is the actual payload shape a server puts on the wire (inside\n * the `{ eventId, subject, type, payload }` envelope) - see\n * {@link toWireAgentEvent}.\n *\n * @stable\n */\n/**\n * Wire twin of {@link SubagentEvent} (W-036): the wrapped child event\n * projects recursively - a forwarded child `agent.end` carries a full\n * `RunState` of its own.\n *\n * @stable\n */\nexport interface WireSubagentEvent extends Omit<SubagentEvent, 'event'> {\n  readonly event: WireAgentEvent<unknown>;\n}\n\nexport type WireAgentEvent<TOutput = string> =\n  | Exclude<\n      AgentEvent<TOutput>,\n      FileGeneratedEvent | ToolExecutePartialEvent | AgentEndEvent<TOutput> | SubagentEvent\n    >\n  | WireFileGeneratedEvent\n  | WireToolExecutePartialEvent\n  | WireSubagentEvent\n  | WireAgentEndEvent<TOutput>;\n\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n\n/**\n * Registry-hosted agents are structurally typed and may emit an\n * `agent.end` without a full `result.state` (e.g. plain `{ status,\n * output }`). Only a state that actually carries the walked arrays is\n * projected; anything else passes through untouched.\n */\nfunction hasProjectableState(result: unknown): result is { state: { messages: unknown[] } } {\n  if (!isRecord(result)) return false;\n  const state = result.state;\n  return isRecord(state) && Array.isArray(state.messages) && Array.isArray(state.steps);\n}\n\nfunction encodeBytesField(data: Uint8Array | EncodedBytes): EncodedBytes {\n  if (data instanceof Uint8Array) return { enc: 'base64', data: bytesToBase64(data) };\n  return data;\n}\n\nfunction decodeBytesField(data: EncodedBytes | Uint8Array | unknown): Uint8Array {\n  if (data instanceof Uint8Array) return data;\n  if (isRecord(data) && data.enc === 'base64' && typeof data.data === 'string') {\n    return base64ToBytes(data.data);\n  }\n  // Unrecoverable legacy shape - degrade to empty bytes rather than throw.\n  return new Uint8Array(0);\n}\n\n/**\n * Project an {@link AgentEvent} into its JSON-safe {@link WireAgentEvent}\n * twin. Idempotent: projecting an already-wire event returns an\n * equivalent value. Events of unknown `type` pass through untouched.\n *\n * @stable\n */\nexport function toWireAgentEvent<TOutput = string>(\n  ev: AgentEvent<TOutput> | WireAgentEvent<TOutput>,\n): WireAgentEvent<TOutput> {\n  switch (ev.type) {\n    case 'file.generated':\n      return { ...ev, data: encodeBytesField(ev.data) };\n    case 'tool.execute.partial': {\n      const chunk = ev.chunk;\n      if (chunk.kind === 'image') {\n        return { ...ev, chunk: { ...chunk, data: encodeBytesField(chunk.data) } };\n      }\n      return ev as WireAgentEvent<TOutput>;\n    }\n    case 'agent.end':\n      if (!hasProjectableState(ev.result)) return ev as WireAgentEvent<TOutput>;\n      return {\n        ...ev,\n        result: { ...ev.result, state: toJsonSafeRunState(ev.result.state) },\n      };\n    case 'subagent.event':\n      // W-036: the wrapped child event projects recursively.\n      return { ...ev, event: toWireAgentEvent(ev.event) };\n    default:\n      return ev as WireAgentEvent<TOutput>;\n  }\n}\n\n/**\n * Inverse of {@link toWireAgentEvent}: decode base64 envelopes back\n * into `Uint8Array` / `URL` instances. Exposed for `@graphorin/client`\n * consumers that want runtime types back after `JSON.parse`.\n *\n * @stable\n */\nexport function fromWireAgentEvent<TOutput = string>(\n  ev: WireAgentEvent<TOutput> | AgentEvent<TOutput>,\n): AgentEvent<TOutput> {\n  switch (ev.type) {\n    case 'file.generated':\n      return { ...ev, data: decodeBytesField(ev.data) };\n    case 'tool.execute.partial': {\n      const chunk = ev.chunk;\n      if (chunk.kind === 'image') {\n        return { ...ev, chunk: { ...chunk, data: decodeBytesField(chunk.data) } };\n      }\n      return ev as AgentEvent<TOutput>;\n    }\n    case 'agent.end':\n      if (!hasProjectableState(ev.result)) return ev as AgentEvent<TOutput>;\n      return {\n        ...ev,\n        result: {\n          ...ev.result,\n          state: fromJsonSafeRunState(ev.result.state as unknown as WireRunState),\n        },\n      } as AgentEvent<TOutput>;\n    case 'subagent.event':\n      return { ...ev, event: fromWireAgentEvent(ev.event) } as AgentEvent<TOutput>;\n    default:\n      return ev as AgentEvent<TOutput>;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA8FA,SAAS,SAAS,GAA0C;AAC1D,QAAO,OAAO,MAAM,YAAY,MAAM,QAAQ,CAAC,MAAM,QAAQ,EAAE;;;;;;;;AASjE,SAAS,oBAAoB,QAA+D;AAC1F,KAAI,CAAC,SAAS,OAAO,CAAE,QAAO;CAC9B,MAAM,QAAQ,OAAO;AACrB,QAAO,SAAS,MAAM,IAAI,MAAM,QAAQ,MAAM,SAAS,IAAI,MAAM,QAAQ,MAAM,MAAM;;AAGvF,SAAS,iBAAiB,MAA+C;AACvE,KAAI,gBAAgB,WAAY,QAAO;EAAE,KAAK;EAAU,MAAM,cAAc,KAAK;EAAE;AACnF,QAAO;;AAGT,SAAS,iBAAiB,MAAuD;AAC/E,KAAI,gBAAgB,WAAY,QAAO;AACvC,KAAI,SAAS,KAAK,IAAI,KAAK,QAAQ,YAAY,OAAO,KAAK,SAAS,SAClE,QAAO,cAAc,KAAK,KAAK;AAGjC,QAAO,IAAI,WAAW,EAAE;;;;;;;;;AAU1B,SAAgB,iBACd,IACyB;AACzB,SAAQ,GAAG,MAAX;EACE,KAAK,iBACH,QAAO;GAAE,GAAG;GAAI,MAAM,iBAAiB,GAAG,KAAK;GAAE;EACnD,KAAK,wBAAwB;GAC3B,MAAM,QAAQ,GAAG;AACjB,OAAI,MAAM,SAAS,QACjB,QAAO;IAAE,GAAG;IAAI,OAAO;KAAE,GAAG;KAAO,MAAM,iBAAiB,MAAM,KAAK;KAAE;IAAE;AAE3E,UAAO;;EAET,KAAK;AACH,OAAI,CAAC,oBAAoB,GAAG,OAAO,CAAE,QAAO;AAC5C,UAAO;IACL,GAAG;IACH,QAAQ;KAAE,GAAG,GAAG;KAAQ,OAAO,mBAAmB,GAAG,OAAO,MAAM;KAAE;IACrE;EACH,KAAK,iBAEH,QAAO;GAAE,GAAG;GAAI,OAAO,iBAAiB,GAAG,MAAM;GAAE;EACrD,QACE,QAAO;;;;;;;;;;AAWb,SAAgB,mBACd,IACqB;AACrB,SAAQ,GAAG,MAAX;EACE,KAAK,iBACH,QAAO;GAAE,GAAG;GAAI,MAAM,iBAAiB,GAAG,KAAK;GAAE;EACnD,KAAK,wBAAwB;GAC3B,MAAM,QAAQ,GAAG;AACjB,OAAI,MAAM,SAAS,QACjB,QAAO;IAAE,GAAG;IAAI,OAAO;KAAE,GAAG;KAAO,MAAM,iBAAiB,MAAM,KAAK;KAAE;IAAE;AAE3E,UAAO;;EAET,KAAK;AACH,OAAI,CAAC,oBAAoB,GAAG,OAAO,CAAE,QAAO;AAC5C,UAAO;IACL,GAAG;IACH,QAAQ;KACN,GAAG,GAAG;KACN,OAAO,qBAAqB,GAAG,OAAO,MAAiC;KACxE;IACF;EACH,KAAK,iBACH,QAAO;GAAE,GAAG;GAAI,OAAO,mBAAmB,GAAG,MAAM;GAAE;EACvD,QACE,QAAO"}

package/dist/types/agent-event.d.ts

@@ -11,14 +11,44 @@ import { RunError, RunState, RunStatus } from "./run.js";
  * union is exhaustive: `assertNever(...)` catches missed variants at
  * compile time.
  *
- * The shape is wire-stable: the protocol package (`@graphorin/protocol`,
- * created in a later phase) re-exports this union as its server-to-client
- * payload schema. Adding a variant here therefore counts as a wire-format
- * change; track it through changesets.
+ * Wire contract (two layers): the server delivers events inside an
+ * envelope `{ eventId, subject, type, payload }` where `payload` is the
+ * JSON-safe `WireAgentEvent` projection (`toWireAgentEvent`), NOT this
+ * raw union - three variants (`file.generated`, `tool.execute.partial`,
+ * `agent.end`) carry `Uint8Array`/`URL` payloads that plain
+ * `JSON.stringify` would corrupt. `@graphorin/protocol` validates the
+ * envelope and leaves `payload` opaque (`z.unknown()`); clients decode
+ * with `fromWireAgentEvent`. Adding a variant here counts as a
+ * wire-format change; track it through changesets.
+ *
+ * Correlation policy (W-049): events are consumed from a per-run
+ * stream, so cross-run attribution is the ENVELOPE's job (`subject`
+ * carries `agentId`/`runId`); an in-payload `runId` exists only on the
+ * variants that historically carry one and is deliberately NOT
+ * retrofitted onto the rest. Within one tool lifecycle the correlation
+ * key is `toolCallId`; `toolName` is duplicated onto the
+ * `tool.execute.*` variants purely for subscriber convenience.
+ *
+ * @stable
+ */
+type AgentEvent<TOutput = string> = AgentStartEvent | StepStartEvent | TextDeltaEvent | TextCompleteEvent | ReasoningDeltaEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | ToolExecuteStartEvent | ToolExecuteProgressEvent | ToolExecutePartialEvent | ToolExecuteEndEvent | ToolExecuteErrorEvent | ToolApprovalRequestedEvent | ToolApprovalGrantedEvent | ToolApprovalDeniedEvent | ContextCompactedEvent | HandoffEvent | AgentSteeredEvent | AgentFollowUpQueuedEvent | AgentCancellingEvent | AgentModelFellbackEvent | AgentFanOutSpawnedEvent | AgentFanOutMergedEvent | AgentEvaluatorIterationEvent | AgentEvaluatorConvergedEvent | AgentProgressWrittenEvent | AgentProgressReadEvent | AgentLateralLeakDetectedEvent | FileGeneratedEvent | SourceCitedEvent | StepEndEvent | GuardrailTrippedEvent | VerifierResultEvent | SubagentEvent | AgentEndEvent<TOutput> | AgentErrorEvent;
+/**
+ * W-036: a CHILD sub-agent's event forwarded into the parent stream,
+ * wrapped so it never aliases the parent's own step/run events. Which
+ * child events forward is governed by the `forwardEvents` policy on
+ * the handoff entry / `AgentToToolOptions` (default `'lifecycle'`).
  *
  * @stable
  */
-type AgentEvent<TOutput = string> = AgentStartEvent | StepStartEvent | TextDeltaEvent | TextCompleteEvent | ReasoningDeltaEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | ToolExecuteStartEvent | ToolExecuteProgressEvent | ToolExecutePartialEvent | ToolExecuteEndEvent | ToolExecuteErrorEvent | ToolApprovalRequestedEvent | ToolApprovalGrantedEvent | ToolApprovalDeniedEvent | ContextCompactedEvent | HandoffEvent | AgentSteeredEvent | AgentFollowUpQueuedEvent | AgentCancellingEvent | AgentModelFellbackEvent | AgentFanOutSpawnedEvent | AgentFanOutMergedEvent | AgentEvaluatorIterationEvent | AgentEvaluatorConvergedEvent | AgentProgressWrittenEvent | AgentProgressReadEvent | AgentLateralLeakDetectedEvent | FileGeneratedEvent | SourceCitedEvent | StepEndEvent | GuardrailTrippedEvent | VerifierResultEvent | AgentEndEvent<TOutput> | AgentErrorEvent;
+interface SubagentEvent {
+  readonly type: 'subagent.event';
+  /** The PARENT-side toolCallId of the handoff / sub-agent call. */
+  readonly toolCallId: string;
+  /** The child agent's configured name. */
+  readonly agentName: string;
+  /** The child's event, verbatim. */
+  readonly event: AgentEvent<unknown>;
+}
 /** @stable */
 interface AgentStartEvent {
   readonly type: 'agent.start';
@@ -68,6 +98,14 @@ interface ToolCallEndEvent {
 interface ToolExecuteStartEvent {
   readonly type: 'tool.execute.start';
   readonly toolCallId: string;
+  /**
+   * Convenience duplicate of the executing tool's name (W-049).
+   * Correlation within a tool lifecycle is by `toolCallId`; this field
+   * spares direct subscribers a stateful join back to the
+   * `tool.call.start` that carried the name. Optional for wire
+   * compatibility; the agent runtime always fills it.
+   */
+  readonly toolName?: string;
 }
 /**
  * Emitted by streaming-hint tools via `ctx.reportProgress(...)`. Counter
@@ -107,6 +145,8 @@ interface ToolExecutePartialEvent {
 interface ToolExecuteEndEvent {
   readonly type: 'tool.execute.end';
   readonly toolCallId: string;
+  /** See {@link ToolExecuteStartEvent.toolName} (W-049). */
+  readonly toolName?: string;
   readonly result: unknown;
   readonly durationMs: number;
 }
@@ -114,6 +154,8 @@ interface ToolExecuteEndEvent {
 interface ToolExecuteErrorEvent {
   readonly type: 'tool.execute.error';
   readonly toolCallId: string;
+  /** See {@link ToolExecuteStartEvent.toolName} (W-049). */
+  readonly toolName?: string;
   readonly error: ToolError;
 }
 /** @stable */
@@ -459,5 +501,5 @@ interface AgentResult<TOutput = string> {
   readonly state: RunState;
 }
 //#endregion
-export { AgentCancellingEvent, AgentEndEvent, AgentErrorEvent, AgentEvaluatorConvergedEvent, AgentEvaluatorIterationEvent, AgentEvent, AgentFanOutMergedEvent, AgentFanOutSpawnedEvent, AgentFollowUpQueuedEvent, AgentLateralLeakDetectedEvent, AgentModelFellbackEvent, AgentProgressReadEvent, AgentProgressWrittenEvent, AgentResult, AgentStartEvent, AgentSteeredEvent, ContextCompactedEvent, FanOutChildMetadata, GuardrailTrippedEvent, HandoffEvent, LateralLeakVector, ProgressArtifactRef, ReasoningDeltaEvent, StepEndEvent, StepStartEvent, TextCompleteEvent, TextDeltaEvent, ToolApprovalDeniedEvent, ToolApprovalGrantedEvent, ToolApprovalRequestedEvent, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolExecuteEndEvent, ToolExecuteErrorEvent, ToolExecutePartialEvent, ToolExecuteProgressEvent, ToolExecuteStartEvent, VerifierResultEvent };
+export { AgentCancellingEvent, AgentEndEvent, AgentErrorEvent, AgentEvaluatorConvergedEvent, AgentEvaluatorIterationEvent, AgentEvent, AgentFanOutMergedEvent, AgentFanOutSpawnedEvent, AgentFollowUpQueuedEvent, AgentLateralLeakDetectedEvent, AgentModelFellbackEvent, AgentProgressReadEvent, AgentProgressWrittenEvent, AgentResult, AgentStartEvent, AgentSteeredEvent, ContextCompactedEvent, FanOutChildMetadata, FileGeneratedEvent, GuardrailTrippedEvent, HandoffEvent, LateralLeakVector, ProgressArtifactRef, ReasoningDeltaEvent, StepEndEvent, StepStartEvent, SubagentEvent, TextCompleteEvent, TextDeltaEvent, ToolApprovalDeniedEvent, ToolApprovalGrantedEvent, ToolApprovalRequestedEvent, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolExecuteEndEvent, ToolExecuteErrorEvent, ToolExecutePartialEvent, ToolExecuteProgressEvent, ToolExecuteStartEvent, VerifierResultEvent };
 //# sourceMappingURL=agent-event.d.ts.map

package/dist/types/agent-event.d.ts.map

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

package/dist/types/index.d.ts

@@ -6,8 +6,9 @@ import { SessionScope } from "./session-scope.js";
 import { Cost, ModelUsage, Usage, UsageAccumulator, UsageSnapshot, zeroUsage } from "./usage.js";
 import { Handoff, HandoffFilter, HandoffInputFilterDescriptor, HandoffRecord, HandoffSecretsInheritance } from "./handoff.js";
 import { CompletedToolCall, ContentChunk, InboundSanitizationPolicy, MemoryGuardTier, RecoveryHint, ResultHandle, SandboxPolicy, SideEffectClass, ToolApproval, ToolError, ToolErrorKind, ToolOutcome, ToolResult, ToolSource, ToolTrustClass, TruncationStrategy } from "./tool.js";
-import { RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, TodoItem, flattenUsageByModel } from "./run.js";
+import { ReadonlyRunState, RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, TodoItem, flattenUsageByModel } from "./run.js";
 import { AgentCancellingEvent, AgentEndEvent, AgentErrorEvent, AgentEvaluatorConvergedEvent, AgentEvaluatorIterationEvent, AgentEvent, AgentFanOutMergedEvent, AgentFanOutSpawnedEvent, AgentFollowUpQueuedEvent, AgentLateralLeakDetectedEvent, AgentModelFellbackEvent, AgentProgressReadEvent, AgentProgressWrittenEvent, AgentResult, AgentStartEvent, AgentSteeredEvent, ContextCompactedEvent, FanOutChildMetadata, GuardrailTrippedEvent, HandoffEvent, LateralLeakVector, ProgressArtifactRef, ReasoningDeltaEvent, StepEndEvent, StepStartEvent, TextCompleteEvent, TextDeltaEvent, ToolApprovalDeniedEvent, ToolApprovalGrantedEvent, ToolApprovalRequestedEvent, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolExecuteEndEvent, ToolExecuteErrorEvent, ToolExecutePartialEvent, ToolExecuteProgressEvent, ToolExecuteStartEvent, VerifierResultEvent } from "./agent-event.js";
+import { WireAgentEndEvent, WireAgentEvent, WireContentChunk, WireFileGeneratedEvent, WireToolExecutePartialEvent, fromWireAgentEvent, toWireAgentEvent } from "./agent-event-wire.js";
 import { StopCondition, and, hasToolCall, isStepCount, isTerminal, not, or } from "./stop-condition.js";
 import { WorkflowChannelUpdateEvent, WorkflowCheckpointWrittenEvent, WorkflowCustomEvent, WorkflowEndEvent, WorkflowErrorEvent, WorkflowEvent, WorkflowResumedEvent, WorkflowStartEvent, WorkflowStepEndEvent, WorkflowStepStartEvent, WorkflowSuspendedEvent, WorkflowTaskEndEvent, WorkflowTaskStartEvent } from "./workflow-event.js";
-export { type AgentCancellingEvent, type AgentEndEvent, type AgentErrorEvent, type AgentEvaluatorConvergedEvent, type AgentEvaluatorIterationEvent, type AgentEvent, type AgentFanOutMergedEvent, type AgentFanOutSpawnedEvent, type AgentFollowUpQueuedEvent, type AgentLateralLeakDetectedEvent, type AgentModelFellbackEvent, type AgentProgressReadEvent, type AgentProgressWrittenEvent, type AgentResult, type AgentStartEvent, type AgentSteeredEvent, type AssistantMessage, type AudioContent, type Block, type CompletedToolCall, type ContentChunk, type ContextCompactedEvent, type Cost, type EntityRole, type Episode, type Fact, type FanOutChildMetadata, type FileContent, type GraphEntity, type GuardrailTrippedEvent, type Handoff, type HandoffEvent, type HandoffFilter, type HandoffInputFilterDescriptor, type HandoffRecord, type HandoffSecretsInheritance, type ImageContent, type InboundSanitizationPolicy, type Insight, type LateralLeakVector, type MemoryGuardTier, type MemoryHit, type MemoryKind, type MemoryMetadata, type MemoryOwner, type MemoryProvenance, type MemoryRecord, type MemorySearchOptions, type MemoryStatus, type Message, type MessageContent, type MessageRole, type ModelUsage, type ProgressArtifactRef, type ReasoningContent, type ReasoningContentMeta, type ReasoningDeltaEvent, type RecoveryHint, type ResultHandle, type Rule, type RunContext, type RunError, type RunState, type RunStateUsageByModel, type RunStatus, type RunStep, type RunStepProviderResponse, type RunTaintSummary, SENSITIVITY_ORDER, type SandboxPolicy, type Sensitivity, type SessionScope, type SideEffectClass, type StepEndEvent, type StepStartEvent, type StopCondition, type SystemMessage, type TextCompleteEvent, type TextContent, type TextDeltaEvent, type TodoItem, type ToolApproval, type ToolApprovalDeniedEvent, type ToolApprovalGrantedEvent, type ToolApprovalRequestedEvent, type ToolCall, type ToolCallDeltaEvent, type ToolCallEndEvent, type ToolCallStartEvent, type ToolError, type ToolErrorKind, type ToolExecuteEndEvent, type ToolExecuteErrorEvent, type ToolExecutePartialEvent, type ToolExecuteProgressEvent, type ToolExecuteStartEvent, type ToolMessage, type ToolOutcome, type ToolResult, type ToolSource, type ToolTrustClass, type TruncationStrategy, type Usage, type UsageAccumulator, type UsageSnapshot, type UserMessage, type VerifierResultEvent, type WorkflowChannelUpdateEvent, type WorkflowCheckpointWrittenEvent, type WorkflowCustomEvent, type WorkflowEndEvent, type WorkflowErrorEvent, type WorkflowEvent, type WorkflowResumedEvent, type WorkflowStartEvent, type WorkflowStepEndEvent, type WorkflowStepStartEvent, type WorkflowSuspendedEvent, type WorkflowTaskEndEvent, type WorkflowTaskStartEvent, acceptsSensitivity, and, flattenUsageByModel, hasToolCall, isStepCount, isTerminal, not, or, zeroUsage };
+export { type AgentCancellingEvent, type AgentEndEvent, type AgentErrorEvent, type AgentEvaluatorConvergedEvent, type AgentEvaluatorIterationEvent, type AgentEvent, type AgentFanOutMergedEvent, type AgentFanOutSpawnedEvent, type AgentFollowUpQueuedEvent, type AgentLateralLeakDetectedEvent, type AgentModelFellbackEvent, type AgentProgressReadEvent, type AgentProgressWrittenEvent, type AgentResult, type AgentStartEvent, type AgentSteeredEvent, type AssistantMessage, type AudioContent, type Block, type CompletedToolCall, type ContentChunk, type ContextCompactedEvent, type Cost, type EntityRole, type Episode, type Fact, type FanOutChildMetadata, type FileContent, type GraphEntity, type GuardrailTrippedEvent, type Handoff, type HandoffEvent, type HandoffFilter, type HandoffInputFilterDescriptor, type HandoffRecord, type HandoffSecretsInheritance, type ImageContent, type InboundSanitizationPolicy, type Insight, type LateralLeakVector, type MemoryGuardTier, type MemoryHit, type MemoryKind, type MemoryMetadata, type MemoryOwner, type MemoryProvenance, type MemoryRecord, type MemorySearchOptions, type MemoryStatus, type Message, type MessageContent, type MessageRole, type ModelUsage, type ProgressArtifactRef, type ReadonlyRunState, type ReasoningContent, type ReasoningContentMeta, type ReasoningDeltaEvent, type RecoveryHint, type ResultHandle, type Rule, type RunContext, type RunError, type RunState, type RunStateUsageByModel, type RunStatus, type RunStep, type RunStepProviderResponse, type RunTaintSummary, SENSITIVITY_ORDER, type SandboxPolicy, type Sensitivity, type SessionScope, type SideEffectClass, type StepEndEvent, type StepStartEvent, type StopCondition, type SystemMessage, type TextCompleteEvent, type TextContent, type TextDeltaEvent, type TodoItem, type ToolApproval, type ToolApprovalDeniedEvent, type ToolApprovalGrantedEvent, type ToolApprovalRequestedEvent, type ToolCall, type ToolCallDeltaEvent, type ToolCallEndEvent, type ToolCallStartEvent, type ToolError, type ToolErrorKind, type ToolExecuteEndEvent, type ToolExecuteErrorEvent, type ToolExecutePartialEvent, type ToolExecuteProgressEvent, type ToolExecuteStartEvent, type ToolMessage, type ToolOutcome, type ToolResult, type ToolSource, type ToolTrustClass, type TruncationStrategy, type Usage, type UsageAccumulator, type UsageSnapshot, type UserMessage, type VerifierResultEvent, type WireAgentEndEvent, type WireAgentEvent, type WireContentChunk, type WireFileGeneratedEvent, type WireToolExecutePartialEvent, type WorkflowChannelUpdateEvent, type WorkflowCheckpointWrittenEvent, type WorkflowCustomEvent, type WorkflowEndEvent, type WorkflowErrorEvent, type WorkflowEvent, type WorkflowResumedEvent, type WorkflowStartEvent, type WorkflowStepEndEvent, type WorkflowStepStartEvent, type WorkflowSuspendedEvent, type WorkflowTaskEndEvent, type WorkflowTaskStartEvent, acceptsSensitivity, and, flattenUsageByModel, fromWireAgentEvent, hasToolCall, isStepCount, isTerminal, not, or, toWireAgentEvent, zeroUsage };

package/dist/types/index.js

@@ -1,6 +1,7 @@
+import { fromWireAgentEvent, toWireAgentEvent } from "./agent-event-wire.js";
 import { flattenUsageByModel } from "./run.js";
 import { SENSITIVITY_ORDER, acceptsSensitivity } from "./sensitivity.js";
 import { and, hasToolCall, isStepCount, isTerminal, not, or } from "./stop-condition.js";
 import { zeroUsage } from "./usage.js";
 
-export { SENSITIVITY_ORDER, acceptsSensitivity, and, flattenUsageByModel, hasToolCall, isStepCount, isTerminal, not, or, zeroUsage };
+export { SENSITIVITY_ORDER, acceptsSensitivity, and, flattenUsageByModel, fromWireAgentEvent, hasToolCall, isStepCount, isTerminal, not, or, toWireAgentEvent, zeroUsage };

package/dist/types/memory.d.ts

@@ -261,6 +261,11 @@ interface Rule extends MemoryRecord {
  * an ExpeL-style salience counter (new insights start at `2`, pruned at
  * `≤ 0`) and are retrieval-ranked **below** the primary facts they cite.
  *
+ * Core defines only the record shape; the storage surface for insights
+ * is NOT part of the baseline {@link MemoryStore} contract - it lives in
+ * the optional `InsightMemoryStoreExt` exported from `@graphorin/memory`
+ * (W-048). Adapters without it simply have no insight tier.
+ *
  * @stable
  */
 interface Insight extends MemoryRecord {
@@ -314,6 +319,12 @@ type EntityRole = 'subject' | 'object';
  * ledger, and `mergedInto` is single-level (it always points directly at
  * a root), so `mergedInto ?? id` is the canonical id.
  *
+ * Core defines only the record shape; the storage surface for the graph
+ * (upsert / link / merge / one-hop expansion) is NOT part of the
+ * baseline {@link MemoryStore} contract - it lives in the optional
+ * `GraphMemoryStoreExt` exported from `@graphorin/memory` (W-048).
+ * Adapters without it simply have no relation graph.
+ *
  * @stable
  */
 interface GraphEntity {

package/dist/types/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","names":[],"sources":["../../src/types/memory.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;AAwBA;AAgBA;AAeA;AAUA;AAuBA;;;AAckB,KAtGN,UAAA,GAsGM,SAAA,GAAA,SAAA,GAAA,UAAA,GAAA,UAAA,GAAA,YAAA,GAAA,QAAA,GAAA,SAAA;;AASlB;AAcA;;;;;;AA4DA;;;;;;AAsBA;AAWmB,KAlMP,gBAAA,GAkMO,MAAA,GAAA,MAAA,GAAA,YAAA,GAAA,YAAA,GAAA,WAAA,GAAA,UAAA;;;;;;;;AAwDnB;AASkB,KAnPN,YAAA,GAmPM,QAAA,GAAA,aAAA;;;;;;AA4BlB;AAkBA;AAuBA;;;;;;AAsC8C,KA/UlC,WAAA,GA+UkC,MAAA,GAAA,OAAA,GAAA,QAAA;AAQ9C;;;;;;;;UA7UiB,cAAA;;;;;;;;;;;;;;kBAcC;;;;;;;;UASD,YAAA;;iBAEA;;;;wBAIO;;;;;;;;kBAQN;;;;;;;;UASD,KAAA,SAAc;;;;;;;;;;;;;UAcd,IAAA,SAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwCN;;;;;;oBAMJ;;;;;;mBAMD;;;;;;;UAQF,OAAA,SAAgB;;;;;;;;;;wBAUT;;oBAEJ;;mBAED;;;;;;;UAQF,IAAA,SAAa;;;;;;;;;;;mBAWX;;;;;;;uBAOI;;;;;;6BAMM;;;;;;wBAML;;;;;;;oBAOJ;;;;;;;;;;mBAUD;;;;;;;;;;;;;;;;;;;UAoBF,OAAA,SAAgB;;;;;;;;;kBASf;;;;;;;;;;;wBAWM;;;;;oBAKJ;;mBAED;;;;;;;;;KAUP,UAAA;;;;;;;;;;;;;;;;;UAkBK,WAAA;;;;;;;;;;;;;;;;;;;;;;UAuBA,mBAAA;;;kBAGC;;;;;;;;;;;;;oBAUE;;;;;;;;;;;;;;;;;;;;;;;;;mBAyBD,cAAc,cAAc;;;;;;;UAQ9B,0BAA0B,eAAe;mBACvC;;;qBAGE,SAAS"}
+{"version":3,"file":"memory.d.ts","names":[],"sources":["../../src/types/memory.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;AAwBA;AAgBA;AAeA;AAUA;AAuBA;;;AAckB,KAtGN,UAAA,GAsGM,SAAA,GAAA,SAAA,GAAA,UAAA,GAAA,UAAA,GAAA,YAAA,GAAA,QAAA,GAAA,SAAA;;AASlB;AAcA;;;;;;AA4DA;;;;;;AAsBA;AAWmB,KAlMP,gBAAA,GAkMO,MAAA,GAAA,MAAA,GAAA,YAAA,GAAA,YAAA,GAAA,WAAA,GAAA,UAAA;;;;;;;;AA6DnB;AASkB,KAxPN,YAAA,GAwPM,QAAA,GAAA,aAAA;;;;;;AA4BlB;AAwBA;AAuBA;;;;;;AAsC8C,KA1VlC,WAAA,GA0VkC,MAAA,GAAA,OAAA,GAAA,QAAA;AAQ9C;;;;;;;;UAxViB,cAAA;;;;;;;;;;;;;;kBAcC;;;;;;;;UASD,YAAA;;iBAEA;;;;wBAIO;;;;;;;;kBAQN;;;;;;;;UASD,KAAA,SAAc;;;;;;;;;;;;;UAcd,IAAA,SAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwCN;;;;;;oBAMJ;;;;;;mBAMD;;;;;;;UAQF,OAAA,SAAgB;;;;;;;;;;wBAUT;;oBAEJ;;mBAED;;;;;;;UAQF,IAAA,SAAa;;;;;;;;;;;mBAWX;;;;;;;uBAOI;;;;;;6BAMM;;;;;;wBAML;;;;;;;oBAOJ;;;;;;;;;;mBAUD;;;;;;;;;;;;;;;;;;;;;;;;UAyBF,OAAA,SAAgB;;;;;;;;;kBASf;;;;;;;;;;;wBAWM;;;;;oBAKJ;;mBAED;;;;;;;;;KAUP,UAAA;;;;;;;;;;;;;;;;;;;;;;;UAwBK,WAAA;;;;;;;;;;;;;;;;;;;;;;UAuBA,mBAAA;;;kBAGC;;;;;;;;;;;;;oBAUE;;;;;;;;;;;;;;;;;;;;;;;;;mBAyBD,cAAc,cAAc;;;;;;;UAQ9B,0BAA0B,eAAe;mBACvC;;;qBAGE,SAAS"}