@semiont/core 0.5.31 → 0.5.33

package/dist/index.d.ts

@@ -2309,6 +2309,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 +2588,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 +2607,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 +2640,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 +2671,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 +2731,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 +2743,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 +2882,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 +3049,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 +4741,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
@@ -8200,4 +8230,4 @@ 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 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/openapi.d.ts

@@ -92,6 +92,7 @@ declare const DirEntry: ValidateFunction<components['schemas']['DirEntry']>;
 declare const DirectoryEntry: ValidateFunction<components['schemas']['DirectoryEntry']>;
 declare const DiscoveredKB: ValidateFunction<components['schemas']['DiscoveredKB']>;
 declare const DiscoveryDocument: ValidateFunction<components['schemas']['DiscoveryDocument']>;
+declare const DurabilityEvidence: ValidateFunction<components['schemas']['DurabilityEvidence']>;
 declare const EnrichedResourceEvent: ValidateFunction<components['schemas']['EnrichedResourceEvent']>;
 declare const EntityTagChangedPayload: ValidateFunction<components['schemas']['EntityTagChangedPayload']>;
 declare const EntityTypeAddedPayload: ValidateFunction<components['schemas']['EntityTypeAddedPayload']>;
@@ -101,6 +102,7 @@ declare const EventStreamResponse: ValidateFunction<components['schemas']['Event
 declare const ExtractedText: ValidateFunction<components['schemas']['ExtractedText']>;
 declare const ExtractionDeclined: ValidateFunction<components['schemas']['ExtractionDeclined']>;
 declare const ExtractionOutcome: ValidateFunction<components['schemas']['ExtractionOutcome']>;
+declare const FailureClass: ValidateFunction<components['schemas']['FailureClass']>;
 declare const FileEntry: ValidateFunction<components['schemas']['FileEntry']>;
 declare const FragmentSelector: ValidateFunction<components['schemas']['FragmentSelector']>;
 declare const FrameAddEntityTypeCommand: ValidateFunction<components['schemas']['FrameAddEntityTypeCommand']>;
@@ -326,6 +328,7 @@ declare const generated_DirEntry: typeof DirEntry;
 declare const generated_DirectoryEntry: typeof DirectoryEntry;
 declare const generated_DiscoveredKB: typeof DiscoveredKB;
 declare const generated_DiscoveryDocument: typeof DiscoveryDocument;
+declare const generated_DurabilityEvidence: typeof DurabilityEvidence;
 declare const generated_EnrichedResourceEvent: typeof EnrichedResourceEvent;
 declare const generated_EntityTagChangedPayload: typeof EntityTagChangedPayload;
 declare const generated_EntityTypeAddedPayload: typeof EntityTypeAddedPayload;
@@ -335,6 +338,7 @@ declare const generated_EventStreamResponse: typeof EventStreamResponse;
 declare const generated_ExtractedText: typeof ExtractedText;
 declare const generated_ExtractionDeclined: typeof ExtractionDeclined;
 declare const generated_ExtractionOutcome: typeof ExtractionOutcome;
+declare const generated_FailureClass: typeof FailureClass;
 declare const generated_FileEntry: typeof FileEntry;
 declare const generated_FragmentSelector: typeof FragmentSelector;
 declare const generated_FrameAddEntityTypeCommand: typeof FrameAddEntityTypeCommand;
@@ -561,6 +565,7 @@ declare namespace generated {
     generated_DirectoryEntry as DirectoryEntry,
     generated_DiscoveredKB as DiscoveredKB,
     generated_DiscoveryDocument as DiscoveryDocument,
+    generated_DurabilityEvidence as DurabilityEvidence,
     generated_EnrichedResourceEvent as EnrichedResourceEvent,
     generated_EntityTagChangedPayload as EntityTagChangedPayload,
     generated_EntityTypeAddedPayload as EntityTypeAddedPayload,
@@ -570,6 +575,7 @@ declare namespace generated {
     generated_ExtractedText as ExtractedText,
     generated_ExtractionDeclined as ExtractionDeclined,
     generated_ExtractionOutcome as ExtractionOutcome,
+    generated_FailureClass as FailureClass,
     generated_FileEntry as FileEntry,
     generated_FragmentSelector as FragmentSelector,
     generated_FrameAddEntityTypeCommand as FrameAddEntityTypeCommand,