@semiont/jobs 0.5.32 → 0.5.34

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { JobId, UserId, ResourceId, EntityType, GenerationJobParams, TagSchema, Logger, EventBus, components, Annotation, SupportedMediaType, GatheredContext } from '@semiont/core';
+import { JobId, UserId, ResourceId, EntityType, JobReferenceAnnotationResult, GenerationJobParams, JobHighlightAnnotationResult, JobAssessmentAnnotationResult, JobCommentAnnotationResult, TagSchema, JobTagAnnotationResult, Logger, EventBus, components, Annotation, SupportedMediaType, GatheredContext } from '@semiont/core';
 import { SemiontState } from '@semiont/core/node';
 import { InferenceClient } from '@semiont/inference';
 
@@ -142,15 +142,6 @@ interface DetectionProgress {
     entitiesFound: number;
     entitiesEmitted: number;
 }
-/**
- * Detection job result
- */
-interface DetectionResult {
-    kind: 'reference-annotation';
-    totalFound: number;
-    totalEmitted: number;
-    errors: number;
-}
 /**
  * Generation job progress
  */
@@ -178,14 +169,6 @@ interface HighlightDetectionProgress {
     percentage: number;
     message?: string;
 }
-/**
- * Highlight detection job result
- */
-interface HighlightDetectionResult {
-    kind: 'highlight-annotation';
-    highlightsFound: number;
-    highlightsCreated: number;
-}
 /**
  * Assessment detection job progress
  */
@@ -194,14 +177,6 @@ interface AssessmentDetectionProgress {
     percentage: number;
     message?: string;
 }
-/**
- * Assessment detection job result
- */
-interface AssessmentDetectionResult {
-    kind: 'assessment-annotation';
-    assessmentsFound: number;
-    assessmentsCreated: number;
-}
 /**
  * Comment detection job progress
  */
@@ -210,14 +185,6 @@ interface CommentDetectionProgress {
     percentage: number;
     message?: string;
 }
-/**
- * Comment detection job result
- */
-interface CommentDetectionResult {
-    kind: 'comment-annotation';
-    commentsFound: number;
-    commentsCreated: number;
-}
 /**
  * Tag detection job progress
  */
@@ -229,15 +196,6 @@ interface TagDetectionProgress {
     totalCategories: number;
     message?: string;
 }
-/**
- * Tag detection job result
- */
-interface TagDetectionResult {
-    kind: 'tag-annotation';
-    tagsFound: number;
-    tagsCreated: number;
-    byCategory: Record<string, number>;
-}
 /**
  * Pending job - just created, waiting to be picked up
  */
@@ -292,12 +250,12 @@ interface CancelledJob<P> {
  * Generic job - discriminated union of all states
  */
 type Job<P, PG, R> = PendingJob<P> | RunningJob<P, PG> | CompleteJob<P, R> | FailedJob<P> | CancelledJob<P>;
-type DetectionJob = Job<DetectionParams, DetectionProgress, DetectionResult>;
+type DetectionJob = Job<DetectionParams, DetectionProgress, JobReferenceAnnotationResult>;
 type GenerationJob = Job<GenerationJobParams, YieldProgress, GenerationResult>;
-type HighlightDetectionJob = Job<HighlightDetectionParams, HighlightDetectionProgress, HighlightDetectionResult>;
-type AssessmentDetectionJob = Job<AssessmentDetectionParams, AssessmentDetectionProgress, AssessmentDetectionResult>;
-type CommentDetectionJob = Job<CommentDetectionParams, CommentDetectionProgress, CommentDetectionResult>;
-type TagDetectionJob = Job<TagDetectionParams, TagDetectionProgress, TagDetectionResult>;
+type HighlightDetectionJob = Job<HighlightDetectionParams, HighlightDetectionProgress, JobHighlightAnnotationResult>;
+type AssessmentDetectionJob = Job<AssessmentDetectionParams, AssessmentDetectionProgress, JobAssessmentAnnotationResult>;
+type CommentDetectionJob = Job<CommentDetectionParams, CommentDetectionProgress, JobCommentAnnotationResult>;
+type TagDetectionJob = Job<TagDetectionParams, TagDetectionProgress, JobTagAnnotationResult>;
 /**
  * Discriminated union of all job types
  */
@@ -555,13 +513,23 @@ type JobProgressMessage = components['schemas']['JobProgressMessage'];
 /** The five W3C motivations this system mints — a closed vocabulary, so it is
  *  typed as one rather than as `string`. */
 type Motivation = Annotation['motivation'];
+/**
+ * A detection processor returns only its result. Annotations leave through
+ * `onChunkComplete`, per chunk — a return that also carried them would be a
+ * second path to the same write.
+ */
 interface ProcessorResult<R> {
-    annotations: Annotation[];
     result: R;
 }
-declare function processHighlightJob(content: string, inferenceClient: InferenceClient, params: HighlightDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress): Promise<ProcessorResult<HighlightDetectionResult>>;
-declare function processCommentJob(content: string, inferenceClient: InferenceClient, params: CommentDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress): Promise<ProcessorResult<CommentDetectionResult>>;
-declare function processAssessmentJob(content: string, inferenceClient: InferenceClient, params: AssessmentDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress): Promise<ProcessorResult<AssessmentDetectionResult>>;
+declare function processHighlightJob(content: string, inferenceClient: InferenceClient, params: HighlightDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, 
+/** This chunk's novel annotations, awaited: the durability write. */
+onChunkComplete: (annotations: Annotation[]) => Promise<void>): Promise<ProcessorResult<JobHighlightAnnotationResult>>;
+declare function processCommentJob(content: string, inferenceClient: InferenceClient, params: CommentDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, 
+/** This chunk's novel annotations, awaited: the durability write. */
+onChunkComplete: (annotations: Annotation[]) => Promise<void>): Promise<ProcessorResult<JobCommentAnnotationResult>>;
+declare function processAssessmentJob(content: string, inferenceClient: InferenceClient, params: AssessmentDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, 
+/** This chunk's novel annotations, awaited: the durability write. */
+onChunkComplete: (annotations: Annotation[]) => Promise<void>): Promise<ProcessorResult<JobAssessmentAnnotationResult>>;
 /**
  * Reference detection commits per UNIT — one entity type — through
  * `onUnitComplete` (ABANDONED-INFERENCE P2, checkpointed resume): the
@@ -571,10 +539,21 @@ declare function processAssessmentJob(content: string, inferenceClient: Inferenc
  * annotations as well would recreate the post-run batch that N2 showed
  * discards completed work wholesale.
  */
-declare function processReferenceJob(content: string, inferenceClient: InferenceClient, params: DetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, logger: Logger, onUnitComplete: (entityType: string, annotations: Annotation[]) => Promise<void>, signal?: AbortSignal): Promise<{
-    result: DetectionResult;
+declare function processReferenceJob(content: string, inferenceClient: InferenceClient, params: DetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, logger: Logger, 
+/**
+ * The CHECKPOINT, fired once per unit after every one of its chunks has
+ * committed. It carries no annotations — the effect already happened per
+ * chunk through `onChunkComplete`, and a unit callback that also carried
+ * them would be a second commit path.
+ */
+onUnitComplete: (entityType: string) => Promise<void>, signal?: AbortSignal, 
+/** This chunk's novel annotations, awaited: the durability write. */
+onChunkComplete?: (annotations: Annotation[]) => Promise<void>): Promise<{
+    result: JobReferenceAnnotationResult;
 }>;
-declare function processTagJob(content: string, inferenceClient: InferenceClient, params: TagDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress): Promise<ProcessorResult<TagDetectionResult>>;
+declare function processTagJob(content: string, inferenceClient: InferenceClient, params: TagDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, 
+/** This chunk's novel annotations, awaited: the durability write. */
+onChunkComplete: (annotations: Annotation[]) => Promise<void>): Promise<ProcessorResult<JobTagAnnotationResult>>;
 declare function processGenerationJob(inferenceClient: InferenceClient, params: GenerationJobParams, onProgress: OnProgress, logger: Logger): Promise<{
     content: Uint8Array;
     title: string;
@@ -659,7 +638,9 @@ declare class AnnotationDetection {
      * (source-resource locale). See `types.ts` "Locale conventions" for the
      * full discussion.
      */
-    static detectComments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void): Promise<CommentMatch[]>;
+    static detectComments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void, 
+    /** This chunk's matches, as the chunk completes. */
+    onChunkResults?: (matches: CommentMatch[]) => Promise<void>): Promise<CommentMatch[]>;
     /**
      * Detect highlights in content.
      *
@@ -667,7 +648,9 @@ declare class AnnotationDetection {
      * applies, used in the prompt so the LLM analyzes non-English source
      * correctly.
      */
-    static detectHighlights(content: string, client: InferenceClient, instructions?: string, density?: number, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void): Promise<HighlightMatch[]>;
+    static detectHighlights(content: string, client: InferenceClient, instructions?: string, density?: number, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void, 
+    /** This chunk's matches, as the chunk completes. */
+    onChunkResults?: (matches: HighlightMatch[]) => Promise<void>): Promise<HighlightMatch[]>;
     /**
      * Detect assessments in content.
      *
@@ -675,7 +658,9 @@ declare class AnnotationDetection {
      * (annotation body locale). `sourceLanguage` is the locale of the content
      * being analyzed (source-resource locale).
      */
-    static detectAssessments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void): Promise<AssessmentMatch[]>;
+    static detectAssessments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void, 
+    /** This chunk's matches, as the chunk completes. */
+    onChunkResults?: (matches: AssessmentMatch[]) => Promise<void>): Promise<AssessmentMatch[]>;
     /**
      * Detect tags in content for a specific category.
      *
@@ -688,7 +673,13 @@ declare class AnnotationDetection {
      * identifiers, not LLM-generated text — so it's consumed at the body-stamp
      * site, not here.
      */
-    static detectTags(content: string, client: InferenceClient, schema: TagSchema, category: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void): Promise<TagMatch[]>;
+    static detectTags(content: string, client: InferenceClient, schema: TagSchema, category: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void, 
+    /**
+     * This chunk's matches, ANCHORED before they leave: `parse` here yields
+     * raw tags, so this path runs `validateTagOffsets` per chunk — a per-item
+     * anchor against the full document, so partitioning changes nothing.
+     */
+    onChunkResults?: (matches: TagMatch[]) => Promise<void>): Promise<TagMatch[]>;
 }
 
 /**
@@ -763,4 +754,4 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
 declare const STALL_THRESHOLD_MS: number;
 
 export { AnnotationDetection, FsJobQueue, STALL_THRESHOLD_MS, generateResourceFromTopic, isCancelledJob, isCompleteJob, isFailedJob, isPendingJob, isRunningJob, processAssessmentJob, processCommentJob, processGenerationJob, processHighlightJob, processReferenceJob, processTagJob };
-export type { AnyJob, AssessmentDetectionJob, AssessmentDetectionParams, AssessmentDetectionProgress, AssessmentDetectionResult, CancelledJob, CommentDetectionJob, CommentDetectionParams, CommentDetectionProgress, CommentDetectionResult, CompleteJob, DetectionJob, DetectionParams, DetectionProgress, DetectionResult, FailedJob, GenerationJob, GenerationResult, HighlightDetectionJob, HighlightDetectionParams, HighlightDetectionProgress, HighlightDetectionResult, JobMetadata, JobQueryFilters, JobQueue, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningJob, TagDetectionJob, TagDetectionParams, TagDetectionProgress, TagDetectionResult, YieldProgress };
+export type { AnyJob, AssessmentDetectionJob, AssessmentDetectionParams, AssessmentDetectionProgress, CancelledJob, CommentDetectionJob, CommentDetectionParams, CommentDetectionProgress, CompleteJob, DetectionJob, DetectionParams, DetectionProgress, FailedJob, GenerationJob, GenerationResult, HighlightDetectionJob, HighlightDetectionParams, HighlightDetectionProgress, JobMetadata, JobQueryFilters, JobQueue, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningJob, TagDetectionJob, TagDetectionParams, TagDetectionProgress, YieldProgress };