@semiont/core 0.5.32 → 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.) */
@@ -2309,6 +2314,16 @@ interface components {
             annotationId: string;
             resourceId: string;
         };
+        /**
+         * @description How a job's annotations were established as durable — the OBSERVATION, never a conclusion drawn from it. 'acknowledged': the event log confirmed the batch (mark:commit-ok). 'probe-confirmed': the acknowledgement was lost and a later read found the batch's last annotation present — true, but a weaker claim than an ack, since it rests on the log appending a batch in order and stopping at the first failure. 'probe-refused': the read returned a failure reply; note this does NOT assert the annotations are absent, because a read that failed for its own reasons answers on the same channel. 'probe-unreachable': no answer came at all, so nothing was established either way. ABSENT means the question never arose — a job that committed no annotations. Never defaulted: a manufactured value here is a claim nobody made, in a log nobody can rewrite.
+         * @enum {string}
+         */
+        DurabilityEvidence: "acknowledged" | "probe-confirmed" | "probe-refused" | "probe-unreachable";
+        /**
+         * @description Worker-side classification of a job failure, made where the error is still typed (at the gateway it is already a flattened string, and message-regex classification is the drift this exists to avoid). 'deterministic' — the same request cannot succeed on a second attempt — skips the retry budget. ABSENT means unrecognised, which is deliberately not the same claim as 'transient': only KNOWN-deterministic failures carry the class, because mis-reading a transient failure as deterministic halves reliability while the reverse costs one wasted attempt.
+         * @enum {string}
+         */
+        FailureClass: "transient" | "deterministic";
         /** @description Context gathered for a gather.* call — consumed by yield.* (generation) and the matcher. A shared base (graph, semanticContext, metadata, inferredRelationshipSummary) plus a discriminated `focus` that names the anchor: an annotation or a whole resource. */
         GatheredContext: {
             /** @description The gather anchor. Discriminated on `kind`. */
@@ -2578,6 +2593,7 @@ interface components {
             /** @description Annotation this job is attached to, when applicable. Lets the UI route completion feedback (toast, resolve state) to a specific annotation. */
             annotationId?: string;
             result?: components["schemas"]["JobResult"];
+            durability?: components["schemas"]["DurabilityEvidence"];
         };
         /** @description Payload for job:completed domain event */
         JobCompletedPayload: {
@@ -2596,6 +2612,7 @@ interface components {
             result?: {
                 [key: string]: unknown;
             };
+            durability?: components["schemas"]["DurabilityEvidence"];
         };
         /** @description Command to create a new job via the event bus */
         JobCreateCommand: {
@@ -2628,13 +2645,10 @@ interface components {
             error: string;
             /** @description Entity-type units whose annotations were fully emitted before this failure (checkpointed resume). The queue records them on the retried job's metadata; a retried claim skips them so completed work is neither redone nor duplicated. */
             completedUnits?: string[];
-            /**
-             * @description Worker-side classification of the failure, made where the error is still typed. 'deterministic' — the same request cannot succeed on a second attempt — skips the retry budget; absent or 'transient' retries as before. Only KNOWN-deterministic failures carry the class.
-             * @enum {string}
-             */
-            failureClass?: "transient" | "deterministic";
+            failureClass?: components["schemas"]["FailureClass"];
             /** @description Whether the queue will re-queue this job for another attempt. Computed by the worker from the SAME predicate the queue applies at failJob (one decision site, `willRetryAfter` in @semiont/jobs) using the retry budget carried on the claimed record. FALSE (or absent) means this failure is TERMINAL: a client's job-watch stream ends here. TRUE means the work continues on a fresh attempt — the failure is an event, not the end, and a stream that terminated on it would report a recovering run as a failed one (JOB-RESTART-SAFETY P5). */
             willRetry?: boolean;
+            durability?: components["schemas"]["DurabilityEvidence"];
         };
         /** @description Command to persist a running job's completed-unit checkpoint AT unit completion (JOB-RESTART-SAFETY P2). Distinct from JobFailCommand's checkpoint, which lands only on a clean failure: a worker that dies (crash/OOM/kill) never emits job:fail, so this durable, unthrottled write is what lets the janitor's stale-running recovery resume a dead worker's job rather than redo its finished units. */
         JobCheckpointCommand: {
@@ -2662,14 +2676,17 @@ interface components {
              */
             reason: "no-text-layer" | "encrypted" | "corrupt" | "too-large" | "empty";
         };
-        /** @description Payload for job:failed domain event */
+        /** @description Payload for the job:failed domain event — a permanent fact of the resource, not operational state. It carries the judgments the worker COMPUTED, not just its message: at the log they are otherwise unrecoverable, the only remaining witness being a flattened English string. */
         JobFailedPayload: {
             jobId: string;
             jobType: components["schemas"]["JobType"];
             /** @description Annotation this job was attached to, when applicable */
             annotationId?: string;
             error: string;
-            details?: string;
+            failureClass?: components["schemas"]["FailureClass"];
+            /** @description Whether the worker computed that the queue would re-queue this job (same predicate the queue applies, `willRetryAfter`). Absent means the worker stated nothing. Without it a reader of the log cannot tell a run recovering across several job:failed events from that many dead jobs. */
+            willRetry?: boolean;
+            durability?: components["schemas"]["DurabilityEvidence"];
         };
         /** @description Result of a completed generation job. The worker creates the resource first (the yield:create round-trip returns the id), then emits job:complete carrying it — so resourceId is always present on the wire. */
         JobGenerationResult: {
@@ -2719,6 +2736,8 @@ interface components {
             total?: number;
             /** @description Entities found so far (reference-annotation) */
             entitiesFound?: number;
+            /** @description Cumulative mentions the count-verifier priced across the pieces accepted so far — the denominator for a real progress bar (found of ~expected). Approximate by nature (the count saturates on very large pieces) and monotonically growing within a run. ABSENT when the provider does not verify detection yield, or before any piece has been priced: no claim, never zero. */
+            entitiesExpected?: number;
             /** @description Annotations emitted so far (reference-annotation) */
             entitiesEmitted?: number;
             /** @description Per-item results for the items already finished, for the UI's completed log. Generic across flows for the same reason `current` is. */
@@ -2729,6 +2748,15 @@ interface components {
                 foundCount: number;
                 /** @description Annotations actually persisted for it — post-dedupe and post-durability-acknowledgement, so it counts what the event log holds, not what the model proposed. Beside foundCount this is the per-unit yield the sizing work is judged by. Present on flows whose units persist as they complete (reference-annotation); the tagging flow reports the same fact as byCategory on its result, because its annotations are built after the per-category loop. */
                 persistedCount?: number;
+                /** @description Present only when pieces of this unit were accepted at the subdivision floor while a count call said more was present. The unit completed, but incompletely — this carries the EVIDENCE (found vs counted, over how many pieces), never a judgment against any expected yield. Absent means complete: genuinely absent, not defaulted. */
+                underReported?: {
+                    /** @description Floor-accepted pieces in this unit. */
+                    pieces: number;
+                    /** @description Annotations extraction did find on those pieces — every span write-time-verified. */
+                    found: number;
+                    /** @description Mentions the count calls reported across those pieces (approximate by nature). */
+                    counted: number;
+                };
             }[];
             /** @description Echoed job parameters for display in the progress UI. `label` is a CODE, not a sentence — the client owns the wording, same rule as the progress message. `value` is the user's own input (an entity-type list, their instructions) and is deliberately NOT translated: it is their words, not ours. */
             requestParams?: {
@@ -2859,6 +2887,8 @@ interface components {
             totalEmitted: number;
             /** @description Number of errors encountered */
             errors: number;
+            /** @description Total floor-accepted under-reported pieces across the job's units. Absent means none — the per-unit evidence rides the terminal progress frame's completedItems; this keeps the result self-describing without the progress stream. */
+            underReportedPieces?: number;
         };
         /** @description Command to report progress on a job */
         JobReportProgressCommand: {
@@ -3024,7 +3054,7 @@ interface components {
             correlationId: string;
             /** @description What the commit persisted. */
             response: {
-                /** @description Annotations this commit appended to the event log. Equals the batch size on success — a retry re-appends what already landed rather than counting it out, because the annotation fold is idempotent by id and the log is append-only. Not a dedupe count. */
+                /** @description Annotations the command named that are durable in the event log. Equals the batch size on success, on a first commit and on a retry alike — the commit appends only what the resource does not already hold, so a wholly-redundant retry has still succeeded and says so. Not an append tally: a caller must never have to read a 0 as 'all good'. */
                 persisted: number;
                 /** @description Ids the batch covers, whether appended now or already present. */
                 annotationIds: string[];
@@ -4716,6 +4746,11 @@ type EmittableChannel = {
 
 type Selector = components['schemas']['TextPositionSelector'] | components['schemas']['TextQuoteSelector'] | components['schemas']['SvgSelector'] | components['schemas']['FragmentSelector'];
 type GatheredContext = components['schemas']['GatheredContext'];
+type JobReferenceAnnotationResult = components['schemas']['JobReferenceAnnotationResult'];
+type JobHighlightAnnotationResult = components['schemas']['JobHighlightAnnotationResult'];
+type JobCommentAnnotationResult = components['schemas']['JobCommentAnnotationResult'];
+type JobAssessmentAnnotationResult = components['schemas']['JobAssessmentAnnotationResult'];
+type JobTagAnnotationResult = components['schemas']['JobTagAnnotationResult'];
 /**
  * The `job:create` params shape for `jobType: 'generation'` — one type shared
  * by the write side (sdk `yield.fromContext` → `runGeneration`) and the read
@@ -6236,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>);
@@ -7354,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;
 
@@ -8050,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. */
@@ -8068,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;
@@ -8077,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;
 /**
@@ -8123,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
@@ -8131,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
@@ -8199,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 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, JobId, 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 };
+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