@semiont/core 0.5.33 → 0.5.34

package/dist/index.d.ts

@@ -1975,6 +1975,11 @@ interface components {
         CommandError: {
             /** @description Optional correlation id echoed from the originating command. When present, the failure event can be matched back to the specific command that failed. */
             correlationId?: string;
+            /**
+             * @description Machine-readable failure class, for consumers that must BRANCH on why a command failed rather than log it. Optional and deliberately sparse: absent means 'no class declared', and every existing failure stays that way. An enum rather than a free string so the vocabulary has an owner — an unconstrained code is a mirror with no gate, and adding one should be a deliberate spec change. `message` remains the human-readable text and is unaffected. Members: `peer-unavailable` — the channel this command was sent on has no subscriber, i.e. the service that answers it has not connected yet. Transient by nature (a peer still starting), which is what distinguishes it from a refusal: retrying is the correct response.
+             * @enum {string}
+             */
+            code?: "peer-unavailable";
             /** @description Human-readable error message */
             message: string;
             /** @description Optional additional context (stack trace, field name, etc.) */
@@ -6266,7 +6271,20 @@ type BridgedChannel = RegistryReply | (typeof BRIDGED_BROADCASTS)[number];
 type BusReply<Op extends BusOperationKey> = EventMap[(typeof BUS_OPERATIONS)[Op]['result'] & EventName] extends {
     response: infer R;
 } ? R : void;
-type BusRequestErrorCode = 'bus.timeout' | 'bus.rejected' | 'bus.closed' | 'bus.bad-payload' | 'bus.unauthorized' | 'bus.forbidden' | 'bus.not-found' | 'bus.unsubscribed';
+type BusRequestErrorCode = 'bus.timeout' | 'bus.rejected' | 'bus.closed' | 'bus.bad-payload' | 'bus.unauthorized' | 'bus.forbidden' | 'bus.not-found'
+/**
+ * THIS transport is not subscribed to the reply channel — a local
+ * misconfiguration, caught before emitting. Not to be confused with
+ * `bus.peer-unavailable`, which is the opposite end: the channel HAS no
+ * subscriber because the service that answers it has not connected yet.
+ */
+ | 'bus.unsubscribed'
+/**
+ * The service that answers this channel is not connected. Transient by
+ * nature — a peer still starting — and therefore the one failure class on
+ * this list worth retrying.
+ */
+ | 'bus.peer-unavailable';
 declare class BusRequestError extends SemiontError {
     code: BusRequestErrorCode;
     constructor(message: string, code: BusRequestErrorCode, details?: Record<string, unknown>);
@@ -7384,6 +7402,24 @@ declare function softwareToAgent(software: {
  *
  * Anything else falls back to a Person with the trailing segment as
  * `name`. This is the read-side inverse of `userToDid`/`agentToDid`.
+ *
+ * **`@id` is emitted only when the input is URI-shaped**, because every Agent
+ * branch declares it `format: "uri"` and `@id` is required by none of them. A
+ * non-URI value fails all three branches of the `oneOf`, and wire validation is
+ * per-PAYLOAD — so one bad Agent rejects an entire `browse:resources-result`,
+ * denying a reply about every resource in it. Measured 2026-09-09: one resource
+ * carrying a raw CUID from pre-DID events (2026-03-26) made an unfiltered listing
+ * of nine permanently unreturnable.
+ *
+ * This is a deliberate TOLERANCE, not a compatibility shim — it carries no
+ * version check, no legacy branch, no second code path. It is one function
+ * declining to assert an identifier it cannot vouch for. It is also a waypoint:
+ * `userId` is declared `{"type":"string"}` with "DID of the user" in a
+ * DESCRIPTION that nothing enforces, and the sequence out of here is (1) clean the
+ * legacy values, (2) constrain `userId` in `StoredEventResponse.json`, (3) delete
+ * this tolerance as unreachable. Do not delete it before step 2: the log is
+ * append-only and the offending records cannot be edited away, so a strict reader
+ * today would convert a partial failure into a total one.
  */
 declare function didToAgent(did: string | undefined | null): Agent;
 
@@ -8080,15 +8116,42 @@ interface GraphViews {
 declare function deriveViews(graph: KnowledgeGraph, mainResourceId: string, focalAnnotationId?: string): GraphViews;
 
 /**
- * Bounded retry with exponential backoff.
- *
- * Exists for startup-critical network calls in long-running peers (worker,
- * smelter, weaver): each authenticates against the KS the moment its
- * container starts, and the gateway may not be reachable for a few seconds
- * (gateway restart, container-network warm-up). Orchestration runs these
- * processes with `--rm` and no restart policy, so a process that dies on
- * the first `TypeError: fetch failed` is dead for good — the retry window
- * here is the only recovery it gets.
+ * Retry: the mechanism, and the classifications core itself owns.
+ *
+ * Originally just `retryWithBackoff`, for startup-critical calls in long-running
+ * peers — each authenticates the moment its container starts, the gateway may not
+ * be reachable for a few seconds, and orchestration runs them with `--rm` and no
+ * restart policy, so a process that dies on the first `TypeError: fetch failed` is
+ * dead for good. That is still the shape; the module has grown a family around it.
+ *
+ * **What lives HERE — the mechanism, because it is one fact each:**
+ *   - `RetryPolicy` / `retryWithBackoff` — the loop, deadline-aware
+ *   - `equalJitter` — the backoff curve, shared with the SSE reconnect
+ *   - `retryBudgetMs` — how long a policy can take, derived rather than restated
+ *   - the predicates that narrow an error type CORE owns (`isTransientFetchError`
+ *     over `fetch`'s `TypeError`, `isRetryableRequestError` over `HttpStatusError`,
+ *     `isPeerUnavailable` over `BusRequestError`)
+ *
+ * **What deliberately does NOT — the judgment, because each is local knowledge:**
+ *   - **policies.** `EMIT_RETRY` (http-transport), `EMBEDDING_PROVIDER_RETRY`
+ *     (vectors). A policy answers *how long does THIS wait*, and centralizing that
+ *     is what caused a bug: the embedding path borrowed `STARTUP_FETCH_RETRY` —
+ *     sized for "until a peer starts listening" — to wait out a model download,
+ *     and its ceiling expired just before the thing it was waiting for arrived.
+ *     Two facts that happen to be measured in seconds are still two facts.
+ *   - **deadlines.** `EMIT_TIMEOUT_MS`, `EMBED_TIMEOUT_MS`,
+ *     `STARTUP_CONNECT_TIMEOUT_MS`, each with the call it bounds.
+ *   - **predicates over another package's errors.** `isColdModelError` is
+ *     `@semiont/vectors`'; core has no business knowing an Ollama 404 means
+ *     "not pulled yet".
+ *
+ * `STARTUP_FETCH_RETRY` is the one policy here, and only because five boot paths
+ * genuinely share the one question it answers.
+ *
+ * **Deadlines beat budgets.** `retryWithBackoff` takes an optional `AbortSignal`
+ * so a caller racing its own timeout can stop the retry, instead of the two
+ * numbers having to be kept compatible by hand across packages. That is the
+ * `context.Context` / gRPC-deadline move, with the platform's own primitive.
  */
 interface RetryPolicy {
     /** Total attempts, including the first one. */
@@ -8098,6 +8161,27 @@ interface RetryPolicy {
     /** Ceiling for the doubled delay. */
     maxDelayMs: number;
 }
+/**
+ * Equal jitter: half the computed ceiling, plus a random share of the other
+ * half — delay ∈ [cap/2, cap).
+ *
+ * **One home, because it is one fact.** `retryWithBackoff` and the SSE reconnect
+ * loop (`actor-state-unit.ts`) both need it and carried byte-identical copies —
+ * two implementations agreeing by coincidence, free to drift the first time
+ * either is tuned. The reconnect computes its own ceiling (`reconnectMs · 2ⁿ`,
+ * capped); only the jitter is shared, which is the part that must not diverge.
+ *
+ * Unconditional in `retryWithBackoff`, not an option. Every caller of
+ * `retryWithBackoff` is a container in a fleet that boots together and retries
+ * against ONE gateway, which is precisely the lockstep this exists to break: N
+ * peers backing off by an identical schedule re-converge on the same instant and
+ * re-deliver the burst that caused the failure. A flag would leave that hazard
+ * reachable by default-choosing, and nobody would ever pass `false`.
+ *
+ * The worst case is unchanged — `delay <= cap` still holds, so the patience
+ * budget a policy advertises stays true; only the expected wait drops, to ~75%.
+ */
+declare function equalJitter(cap: number): number;
 interface RetryAttemptInfo {
     /** 1-based number of the attempt that just failed. */
     attempt: number;
@@ -8107,11 +8191,29 @@ interface RetryAttemptInfo {
     delayMs: number;
     error: unknown;
 }
+/**
+ * The worst-case wall clock a policy can spend.
+ *
+ * Derived, because it was being restated by hand in three places — a docstring
+ * saying "~39s", a test recomputing the sum, and a reader doing arithmetic to
+ * decide whether some other deadline could cut it short. Any of those can drift
+ * from the policy the moment someone edits it, and the drift is silent.
+ *
+ * `perAttemptMs` is the caller's per-attempt deadline. **Pass it, or the answer
+ * is a lower bound rather than a ceiling**: delays are bounded by the policy, but
+ * an unbounded attempt makes the total unbounded too, which is how a budget of
+ * "12 attempts" ends up meaning nothing under packet loss. `0` (the default)
+ * answers the delay sum alone, for a caller whose attempts cannot hang.
+ *
+ * Worst case, not expected: equal jitter puts each wait in [cap/2, cap), so the
+ * true wait averages ~75% of this. A ceiling is what a deadline needs to clear.
+ */
+declare function retryBudgetMs(policy: RetryPolicy, perAttemptMs?: number): number;
 /**
  * Default policy for startup connections to the gateway: 8 attempts with delay
- * ceilings 1s, 2s, 4s, then capped at 8s — up to ~39s of patience before giving
- * up. "Up to", because the backoff is equal-jittered: each wait lands in
- * [cap/2, cap), so the worst case is that sum and the expected case is ~75% of it.
+ * ceilings 1s, 2s, 4s, then capped at 8s. `retryBudgetMs` is the authority on
+ * how long that is; the equal-jittered backoff means the expected wait is ~75%
+ * of the ceiling it reports.
  */
 declare const STARTUP_FETCH_RETRY: RetryPolicy;
 /**
@@ -8153,6 +8255,27 @@ interface HttpStatusError extends Error {
  * will not change its mind. A 429 differs — the gateway is up and *asking* us to
  * wait, so the same "it answered" fact points the other way.
  */
+/**
+ * True when the service that answers a bus channel has not connected yet.
+ *
+ * A startup race, not a refusal: the gateway synthesizes this when a request's
+ * channel has no subscriber, and the peer it is waiting for is usually seconds
+ * away. The weaver's boot passes used to treat it as a data condition and give up
+ * for the life of the process — an empty graph projection behind a healthy
+ * `/health`, with live traffic then advancing the applied mark past events that
+ * were never projected (2026-09-09).
+ *
+ * Narrow on purpose, and note what it EXCLUDES: `bus.unsubscribed` means *this*
+ * transport is not subscribed to the reply channel — a local misconfiguration
+ * caught before emitting, which retrying cannot fix and would only delay. The two
+ * codes sound alike and mean opposite ends of the same wire; the predicate is
+ * where that distinction has to hold.
+ *
+ * Takes a `BusRequestError` rather than any `{ code }` object: the code is a wire
+ * value, and `busRequest` is the one place it is mapped into this vocabulary. An
+ * object that did not come through there has not been classified.
+ */
+declare function isPeerUnavailable(error: unknown): boolean;
 declare function isRetryableRequestError(error: unknown): boolean;
 /**
  * Run `fn`, retrying on errors `isRetryable` accepts, with equal-jitter
@@ -8161,7 +8284,23 @@ declare function isRetryableRequestError(error: unknown): boolean;
  * delay. The final error (retryable budget exhausted, or the first
  * non-retryable one) is rethrown verbatim.
  */
-declare function retryWithBackoff<T>(fn: () => Promise<T>, isRetryable: (error: unknown) => boolean, policy: RetryPolicy, onRetry?: (info: RetryAttemptInfo) => void): Promise<T>;
+/**
+ * Race `work` against a deadline, handing it the deadline as a signal.
+ *
+ * The other half of what this module owns: `retryWithBackoff` consumes an
+ * `AbortSignal`, this produces one. A race alone can only ABANDON slow work —
+ * work that retries never learns the deadline exists, and the two end up kept
+ * compatible by hand.
+ *
+ * ONE timer drives both the abort and the rejection. `AbortSignal.timeout()`
+ * schedules its own, so the signal and the race could fire at different moments,
+ * which is the problem this exists to remove.
+ *
+ * `hint` is the caller's operational context, appended to the message — core
+ * cannot know whether a restart policy is watching.
+ */
+declare function withDeadline<T>(what: string, timeoutMs: number, work: (signal: AbortSignal) => Promise<T>, hint?: string): Promise<T>;
+declare function retryWithBackoff<T>(fn: () => Promise<T>, isRetryable: (error: unknown) => boolean, policy: RetryPolicy, onRetry?: (info: RetryAttemptInfo) => void, signal?: AbortSignal): Promise<T>;
 
 /**
  * Sharding Utilities
@@ -8229,5 +8368,5 @@ declare function getShardPath(key: string, numBuckets?: number): [string, string
  */
 declare const DISCOVERY_URL_PATH = "/discovery/kbs.json";
 
-export { AUTHORABLE_MEDIA_TYPES, BRIDGED_CHANNELS, BUS_OPERATIONS, BusRequestError, CHANNEL_SCHEMAS, CONTEXT_FULL_WEIGHT, CONTEXT_PARTIAL_WEIGHT, ConfigurationError, ConflictError, DEFAULT_CHUNKING_CONFIG, DISCOVERY_URL_PATH, EMBEDDABLE_MEDIA_TYPES, EventBus, GENERATABLE_MEDIA_TYPES, JWTTokenSchema, LOCALES, MEDIA_TYPES, NotFoundError, PERSISTED_EVENT_TYPES, POSITION_WEIGHT_MAX, POSITION_WINDOW, RESOURCE_BROADCAST_TYPES, STARTUP_FETCH_RETRY, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, agentToDid, anchorAnnotation, anchorRuns, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseMediaType, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, busRequest, capabilitiesOf, chunkText, cloneFormat, cloneToken, createCircleSvg, createFragmentSelector, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, deriveStorageUri, deriveViews, didToAgent, email, entityType, errField, estimateTokens, extensionForMediaType, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findClaimSpan, folderOf, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPageFromFragment, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getShardPath, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAnnotatable, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isGatheredContext, isGenerationJobParams, isHighlight, isNull, isNullish, isNumber, isObject, isReference, isResolvedReference, isResourceId, isRetryableRequestError, isStoredEvent, isString, isStubReference, isSupportedMediaType, isTag, isTextRun, isTransientFetchError, isUndefined, isValidEmail, isValidPlatformType, jobId, jumpConsistentHash, kbDid, loadTomlConfig, locate, mcpToken, mediaTypeForExtension, normalizeCoordinates, normalizeText, parseEnvironment, parseFragmentSelector, parseSvgSelector, proposeStoragePath, reconcileSelector, refreshToken, replyChannelsFor, resourceAnnotationUri, resourceId, resourceUri, retryWithBackoff, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, softwareToAgent, storageFileName, textSourceOf, textUnder, userDID, userId, userToAgent, userToDid, uuidV4, validateData, validateEnvironment, validateSvgMarkup, verifyPosition, yieldsGeometryOf };
+export { AUTHORABLE_MEDIA_TYPES, BRIDGED_CHANNELS, BUS_OPERATIONS, BusRequestError, CHANNEL_SCHEMAS, CONTEXT_FULL_WEIGHT, CONTEXT_PARTIAL_WEIGHT, ConfigurationError, ConflictError, DEFAULT_CHUNKING_CONFIG, DISCOVERY_URL_PATH, EMBEDDABLE_MEDIA_TYPES, EventBus, GENERATABLE_MEDIA_TYPES, JWTTokenSchema, LOCALES, MEDIA_TYPES, NotFoundError, PERSISTED_EVENT_TYPES, POSITION_WEIGHT_MAX, POSITION_WINDOW, RESOURCE_BROADCAST_TYPES, STARTUP_FETCH_RETRY, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, agentToDid, anchorAnnotation, anchorRuns, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseMediaType, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, busRequest, capabilitiesOf, chunkText, cloneFormat, cloneToken, createCircleSvg, createFragmentSelector, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, deriveStorageUri, deriveViews, didToAgent, email, entityType, equalJitter, errField, estimateTokens, extensionForMediaType, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findClaimSpan, folderOf, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPageFromFragment, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getShardPath, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAnnotatable, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isGatheredContext, isGenerationJobParams, isHighlight, isNull, isNullish, isNumber, isObject, isPeerUnavailable, isReference, isResolvedReference, isResourceId, isRetryableRequestError, isStoredEvent, isString, isStubReference, isSupportedMediaType, isTag, isTextRun, isTransientFetchError, isUndefined, isValidEmail, isValidPlatformType, jobId, jumpConsistentHash, kbDid, loadTomlConfig, locate, mcpToken, mediaTypeForExtension, normalizeCoordinates, normalizeText, parseEnvironment, parseFragmentSelector, parseSvgSelector, proposeStoragePath, reconcileSelector, refreshToken, replyChannelsFor, resourceAnnotationUri, resourceId, resourceUri, retryBudgetMs, retryWithBackoff, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, softwareToAgent, storageFileName, textSourceOf, textUnder, userDID, userId, userToAgent, userToDid, uuidV4, validateData, validateEnvironment, validateSvgMarkup, verifyPosition, withDeadline, yieldsGeometryOf };
 export type { AccessToken, AnchorConfidence, AnchorMethod, AnchorRect, AnchorSelectors, AnchorStrategy, AnchoredText, AnchoredTextAnswer, AnchoringModel, Annotation, AnnotationCategory, AnnotationId, AnnotationUri, AnthropicProviderConfig, AppConfig, ArchivistServiceConfig, AssembledAnnotation, AuthCode, BaseUrl, BodyItem, BodyItemIdentity, BodyOperation, BoundingBox, Brand, BridgedChannel, BurstBufferOptions, BusOp, BusOperationKey, BusOperationSpec, BusRequestErrorCode, BusRequestPrimitive, ChunkingConfig, CloneToken, CollaboratorEntry, ConnectionState, ContentCache, ContentFormat, CreateAnnotationInternal, DatabaseServiceConfig, DiscoveredKB, DiscoveryDocument, Email, EmbeddingServiceConfig, EmittableChannel, EntityType, EntityTypeStats, Environment, EnvironmentConfig, EventBase, EventInput, EventMap, EventMetadata, EventName, EventOfType, EventQuery, EventSignature, ExtractionOutcome, FragmentSelector, GatewayServiceConfig, GatheredContext, GenerationJobParams, GoogleAuthRequest, GoogleCredential, GraphConnection, GraphDatabaseType, GraphPath, GraphServiceConfig, GraphViews, HealthCheckResponse, HttpStatusError, IContentTransport, IGatewayOperations, ITransport, InferenceProvidersConfig, JobAssessmentAnnotationResult, JobCommentAnnotationResult, JobHighlightAnnotationResult, JobId, JobReferenceAnnotationResult, JobTagAnnotationResult, JobType, ListUsersResponse, LlmSelectorInput, LocaleInfo, Logger, MCPToken, MatchQuality, McpServiceConfig, MediaTypeCapabilities, Motivation, OllamaProviderConfig, PdfCoordinate, PdfTextItem, PdfTextRun, PersistedEvent, PersistedEventType, PlatformType, Point, PutBinaryOptions, PutBinaryProgress, PutBinaryRequest, ReconciledSelector, RefreshToken, RenderMode, RenderedAnchor, ResourceAnnotationUri, ResourceAnnotations, ResourceBroadcastType, ResourceDescriptor, ResourceFilter, ResourceId, ResourceUri, RetryAttemptInfo, RetryPolicy, SearchQuery, SelectionData, Selector, SemiontConfig, ServicePlatformConfig, ServicesConfig, SiteConfig, StateUnit, StatusResponse, StoredEvent, StoredEventLike, StoredResource, SupportedMediaType, SvgSelector, TagCategory, TagSchema, TextPosition, TextPositionSelector, TextQuoteSelector, TextSource, ActorInferenceConfig as TomlActorInferenceConfig, TomlFileReader, InferenceConfig as TomlInferenceConfig, WorkerInferenceConfig as TomlWorkerInferenceConfig, TransportErrorCode, UpdateResourceInput, UpdateUserRequest, UpdateUserResponse, UserDID, UserId, UserResponse, ValidationFailure, ValidationResult, ValidationSuccess, VectorsServiceConfig, components, operations, paths };

package/dist/index.js

@@ -1003,6 +1003,9 @@ var ConflictError = class extends SemiontError {
 };
 
 // src/bus-request.ts
+function classifyFailureCode(code) {
+  return code === "peer-unavailable" ? "bus.peer-unavailable" : "bus.rejected";
+}
 var BusRequestError = class extends SemiontError {
   constructor(message, code, details) {
     super(message, code, details);
@@ -1044,7 +1047,7 @@ async function busRequest(bus, operation, payload, timeoutMs = 3e4) {
       filter((e) => e.correlationId === correlationId),
       map((e) => ({
         ok: false,
-        error: new BusRequestError(e.message ?? "Bus request rejected", "bus.rejected", {
+        error: new BusRequestError(e.message ?? "Bus request rejected", classifyFailureCode(e.code), {
           channel: failureChannel,
           correlationId,
           payload: e
@@ -2036,17 +2039,19 @@ function softwareToAgent(software) {
 }
 function didToAgent(did) {
   if (!did) {
-    return { "@type": "Person", "@id": "unknown", name: "unknown" };
+    return { "@type": "Person", name: "unknown" };
   }
   const parts = did.split(":");
   const agentsIdx = parts.lastIndexOf("agents");
   const usersIdx = parts.lastIndexOf("users");
+  const uriShaped = (value) => /^[A-Za-z][A-Za-z0-9+.-]*:\S/.test(value);
+  const identity = uriShaped(did) ? { "@id": did } : {};
   if (agentsIdx >= 0 && agentsIdx === parts.length - 3) {
     const provider = decodeURIComponent(parts[agentsIdx + 1] ?? "");
     const model = decodeURIComponent(parts[agentsIdx + 2] ?? "");
     return {
       "@type": "Software",
-      "@id": did,
+      ...identity,
       name: `${provider} ${model}`,
       provider,
       model
@@ -2056,14 +2061,14 @@ function didToAgent(did) {
     const name = decodeURIComponent(parts[usersIdx + 1] ?? "");
     return {
       "@type": "Person",
-      "@id": did,
+      ...identity,
       name
     };
   }
   const encoded = parts[parts.length - 1] || "unknown";
   return {
     "@type": "Person",
-    "@id": did,
+    ...identity,
     name: decodeURIComponent(encoded)
   };
 }
@@ -2174,6 +2179,15 @@ function deriveViews(graph, mainResourceId, focalAnnotationId) {
 function equalJitter(cap) {
   return cap / 2 + Math.random() * (cap / 2);
 }
+function retryBudgetMs(policy, perAttemptMs = 0) {
+  let cap = policy.initialDelayMs;
+  let total = perAttemptMs;
+  for (let i = 1; i < policy.attempts; i++) {
+    total += cap + perAttemptMs;
+    cap = Math.min(cap * 2, policy.maxDelayMs);
+  }
+  return total;
+}
 var STARTUP_FETCH_RETRY = {
   attempts: 8,
   initialDelayMs: 1e3,
@@ -2186,6 +2200,9 @@ function isTransientFetchError(error) {
   return typeof code === "string" && code.length > 0;
 }
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 503, 504]);
+function isPeerUnavailable(error) {
+  return error instanceof BusRequestError && error.code === "bus.peer-unavailable";
+}
 function isRetryableRequestError(error) {
   if (isTransientFetchError(error)) return true;
   if (typeof error !== "object" || error === null) return false;
@@ -2193,12 +2210,33 @@ function isRetryableRequestError(error) {
   const status = error.status;
   return typeof status === "number" && RETRYABLE_STATUSES.has(status);
 }
-async function retryWithBackoff(fn, isRetryable, policy, onRetry) {
+async function withDeadline(what, timeoutMs, work, hint) {
+  const controller = new AbortController();
+  let timer;
+  try {
+    return await Promise.race([
+      work(controller.signal),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          const expired = new Error(
+            `${what} did not become available within ${timeoutMs / 1e3}s.${hint ? ` ${hint}` : ""}`
+          );
+          controller.abort(expired);
+          reject(expired);
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+async function retryWithBackoff(fn, isRetryable, policy, onRetry, signal) {
   let cap = policy.initialDelayMs;
   for (let attempt = 1; ; attempt++) {
     try {
       return await fn();
     } catch (error) {
+      if (signal?.aborted) throw error;
       if (attempt >= policy.attempts || !isRetryable(error)) throw error;
       const delayMs = equalJitter(cap);
       onRetry?.({ attempt, attempts: policy.attempts, delayMs, error });
@@ -2238,6 +2276,6 @@ function getShardPath(key, numBuckets = 65536) {
 // src/discovery.ts
 var DISCOVERY_URL_PATH = "/discovery/kbs.json";
 
-export { AUTHORABLE_MEDIA_TYPES, BusRequestError, CHANNEL_SCHEMAS, CONTEXT_FULL_WEIGHT, CONTEXT_PARTIAL_WEIGHT, ConfigurationError, ConflictError, DEFAULT_CHUNKING_CONFIG, DISCOVERY_URL_PATH, EMBEDDABLE_MEDIA_TYPES, GENERATABLE_MEDIA_TYPES, JWTTokenSchema, LOCALES, MEDIA_TYPES, NotFoundError, PERSISTED_EVENT_TYPES, POSITION_WEIGHT_MAX, POSITION_WINDOW, RESOURCE_BROADCAST_TYPES, STARTUP_FETCH_RETRY, ScriptError, SemiontError, UnauthorizedError, ValidationError, agentToDid, anchorAnnotation, anchorRuns, annotationId, applyBodyOperations, assembleAnnotation, baseMediaType, buildContentCache, burstBuffer, busRequest, capabilitiesOf, chunkText, cloneFormat, createCircleSvg, createFragmentSelector, createPolygonSvg, createRectangleSvg, decodeRepresentation, decodeWithCharset, deriveStorageUri, deriveViews, didToAgent, errField, estimateTokens, extensionForMediaType, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findClaimSpan, folderOf, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPageFromFragment, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getShardPath, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, hasTargetSelector, isAnnotatable, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isGatheredContext, isGenerationJobParams, isHighlight, isNull, isNullish, isNumber, isObject, isReference, isResolvedReference, isResourceId, isRetryableRequestError, isStoredEvent, isString, isStubReference, isSupportedMediaType, isTag, isTextRun, isTransientFetchError, isUndefined, isValidEmail, isValidPlatformType, jumpConsistentHash, kbDid, locate, mediaTypeForExtension, normalizeCoordinates, normalizeText, parseEnvironment, parseFragmentSelector, parseSvgSelector, proposeStoragePath, reconcileSelector, replyChannelsFor, resourceId, retryWithBackoff, scaleSvgToNative, serializePerKey, softwareToAgent, storageFileName, textSourceOf, textUnder, userId, userToAgent, userToDid, uuidV4, validateData, validateEnvironment, validateSvgMarkup, verifyPosition, yieldsGeometryOf };
+export { AUTHORABLE_MEDIA_TYPES, BusRequestError, CHANNEL_SCHEMAS, CONTEXT_FULL_WEIGHT, CONTEXT_PARTIAL_WEIGHT, ConfigurationError, ConflictError, DEFAULT_CHUNKING_CONFIG, DISCOVERY_URL_PATH, EMBEDDABLE_MEDIA_TYPES, GENERATABLE_MEDIA_TYPES, JWTTokenSchema, LOCALES, MEDIA_TYPES, NotFoundError, PERSISTED_EVENT_TYPES, POSITION_WEIGHT_MAX, POSITION_WINDOW, RESOURCE_BROADCAST_TYPES, STARTUP_FETCH_RETRY, ScriptError, SemiontError, UnauthorizedError, ValidationError, agentToDid, anchorAnnotation, anchorRuns, annotationId, applyBodyOperations, assembleAnnotation, baseMediaType, buildContentCache, burstBuffer, busRequest, capabilitiesOf, chunkText, cloneFormat, createCircleSvg, createFragmentSelector, createPolygonSvg, createRectangleSvg, decodeRepresentation, decodeWithCharset, deriveStorageUri, deriveViews, didToAgent, equalJitter, errField, estimateTokens, extensionForMediaType, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findClaimSpan, folderOf, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPageFromFragment, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getShardPath, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, hasTargetSelector, isAnnotatable, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isGatheredContext, isGenerationJobParams, isHighlight, isNull, isNullish, isNumber, isObject, isPeerUnavailable, isReference, isResolvedReference, isResourceId, isRetryableRequestError, isStoredEvent, isString, isStubReference, isSupportedMediaType, isTag, isTextRun, isTransientFetchError, isUndefined, isValidEmail, isValidPlatformType, jumpConsistentHash, kbDid, locate, mediaTypeForExtension, normalizeCoordinates, normalizeText, parseEnvironment, parseFragmentSelector, parseSvgSelector, proposeStoragePath, reconcileSelector, replyChannelsFor, resourceId, retryBudgetMs, retryWithBackoff, scaleSvgToNative, serializePerKey, softwareToAgent, storageFileName, textSourceOf, textUnder, userId, userToAgent, userToDid, uuidV4, validateData, validateEnvironment, validateSvgMarkup, verifyPosition, withDeadline, yieldsGeometryOf };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map