feat(scanner): complete localized artifact quality checkpoint
This commit is contained in:
AzuTear
@@ -2,23 +2,30 @@ import fs from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { pngBufferToBitmap } from "./pngBitmap.js";
|
||||
import { createNativeScannerResultWorkflowService } from "./nativeScannerResultWorkflowService.js";
|
||||
import { loadNativeScannerDeletedResultIds } from "./nativeScannerResultTombstones.js";
|
||||
import { parseArtifactCandidate } from "../../src/lib/artifactOcrParser.js";
|
||||
import { evaluateStoredScanResult } from "../../src/lib/artifactEvaluation.js";
|
||||
import { toStoredArtifact } from "../../src/lib/artifactStore.js";
|
||||
import { matchParsedArtifactToIk, type IkArtifactCatalog } from "../../src/lib/ikArtifactMatcher.js";
|
||||
import { createStoredScanResultEntry } from "../../src/lib/scanResultEntry.js";
|
||||
import { shouldFlagArtifactForReview } from "../../src/lib/scannerLearning.js";
|
||||
import type {
|
||||
ArtifactStoreLoadResult,
|
||||
ArtifactStoreSaveResult,
|
||||
CaptureResult,
|
||||
NativeScannerImageLoadStatus,
|
||||
NativeScannerDeleteResultStatus,
|
||||
NativeScannerProcessStatus,
|
||||
NativeScannerProcessingProgressStatus,
|
||||
NativeScannerPromotionStatus,
|
||||
NativeScannerReviewArtifactInput,
|
||||
NativeScannerReviewStatus,
|
||||
NativeScannerResultsLoadStatus,
|
||||
NativeScannerRunTiming,
|
||||
NativeScannerRunTimingPatch,
|
||||
ReviewSamplePayload,
|
||||
} from "../../src/types/global.js";
|
||||
import type { ScanResultCategory, StoredArtifactRecord, StoredScanResultEntry } from "../../src/types/storage.js";
|
||||
import type { ArtifactRarity, ScanResultCategory, StoredArtifactRecord, StoredScanResultEntry } from "../../src/types/storage.js";
|
||||
|
||||
export type NativeCaptureJobPayload = {
|
||||
sequence: number;
|
||||
@@ -29,11 +36,21 @@ export type NativeCaptureJobPayload = {
|
||||
capturedAt?: string;
|
||||
relativePath?: string;
|
||||
absolutePath?: string;
|
||||
/** Direct visual evidence from the native card crop; absent on legacy jobs. */
|
||||
starCount?: number | null;
|
||||
starConfidence?: number;
|
||||
starSource?: string | null;
|
||||
};
|
||||
|
||||
export interface NativeScannerProcessingService {
|
||||
processRun(options?: { runDir?: string; persist?: boolean; limit?: number }): Promise<NativeScannerProcessStatus>;
|
||||
loadResults(options?: { runDir?: string; limit?: number }): Promise<NativeScannerResultsLoadStatus>;
|
||||
processRun(options?: {
|
||||
runDir?: string;
|
||||
persist?: boolean;
|
||||
limit?: number;
|
||||
stream?: boolean;
|
||||
expectedTotal?: number;
|
||||
}): Promise<NativeScannerProcessStatus>;
|
||||
loadResults(options?: { runDir?: string; limit?: number; afterSequence?: number }): Promise<NativeScannerResultsLoadStatus>;
|
||||
promoteResults(options: { runDir?: string; resultIds: string[] }): Promise<NativeScannerPromotionStatus>;
|
||||
reviewResult(options: {
|
||||
runDir?: string;
|
||||
@@ -42,6 +59,11 @@ export interface NativeScannerProcessingService {
|
||||
artifact?: NativeScannerReviewArtifactInput;
|
||||
note?: string;
|
||||
}): Promise<NativeScannerReviewStatus>;
|
||||
deleteResult(options: {
|
||||
runDir?: string;
|
||||
resultId: string;
|
||||
removeLinkedStoreRecord?: boolean;
|
||||
}): Promise<NativeScannerDeleteResultStatus>;
|
||||
loadImage(options: { runDir?: string; imagePath: string }): Promise<NativeScannerImageLoadStatus>;
|
||||
}
|
||||
|
||||
@@ -50,8 +72,14 @@ interface NativeScannerProcessingServiceDependencies {
|
||||
buildCaptureResult(imagePath: string, job: NativeCaptureJobPayload): Promise<CaptureResult>;
|
||||
loadArtifacts?: () => Promise<ArtifactStoreLoadResult>;
|
||||
saveArtifacts(records: StoredArtifactRecord[]): Promise<Pick<ArtifactStoreSaveResult, "added" | "updated"> & Partial<ArtifactStoreSaveResult>>;
|
||||
removeArtifacts?: (ids: string[]) => Promise<{ ok: boolean; removed: number }>;
|
||||
saveReviewSample?: (sample: ReviewSamplePayload) => Promise<{ ok: boolean }>;
|
||||
loadIkArtifactCatalog?: () => Promise<IkArtifactCatalog | null>;
|
||||
/** Durable timing is observational only and must never block OCR/parse work. */
|
||||
recordRunTiming?: (runDir: string, patch: NativeScannerRunTimingPatch) => Promise<NativeScannerRunTiming>;
|
||||
loadRunTiming?: (runDir: string) => Promise<NativeScannerRunTiming | null>;
|
||||
onProgress?: (progress: NativeScannerProcessingProgressStatus) => void;
|
||||
onResult?: (result: StoredScanResultEntry) => void;
|
||||
}
|
||||
|
||||
type ProcessedNativeJob = {
|
||||
@@ -61,70 +89,55 @@ type ProcessedNativeJob = {
|
||||
};
|
||||
|
||||
const POST_CAPTURE_QUEUE_CONCURRENCY = 4;
|
||||
const STREAM_QUEUE_HIGH_WATERMARK = 8;
|
||||
const STREAM_READ_CHUNK_BYTES = 64 * 1024;
|
||||
const STREAM_POLL_INTERVAL_MS = 40;
|
||||
const STREAM_TERMINAL_DRAIN_GRACE_MS = 2_000;
|
||||
const MAX_CACHED_LIVE_RUNS = 8;
|
||||
|
||||
type ProcessRunOptions = {
|
||||
runDir?: string;
|
||||
persist?: boolean;
|
||||
limit?: number;
|
||||
stream?: boolean;
|
||||
expectedTotal?: number;
|
||||
};
|
||||
|
||||
type NativeCaptureProducerStatus = {
|
||||
running: boolean;
|
||||
status: string;
|
||||
target: number;
|
||||
captured: number;
|
||||
};
|
||||
|
||||
const activeProcessingRuns = new Map<string, Promise<NativeScannerProcessStatus>>();
|
||||
const liveResultsByRunDir = new Map<string, StoredScanResultEntry[]>();
|
||||
|
||||
export function createNativeScannerProcessingService(
|
||||
deps: NativeScannerProcessingServiceDependencies,
|
||||
): NativeScannerProcessingService {
|
||||
const resultWorkflows = createNativeScannerResultWorkflowService(deps);
|
||||
const resultWorkflows = createNativeScannerResultWorkflowService({
|
||||
...deps,
|
||||
isProcessingRunActive: (runDir) => activeProcessingRuns.has(runDir),
|
||||
});
|
||||
return {
|
||||
async processRun(options = {}) {
|
||||
const started = Date.now();
|
||||
processRun(options: ProcessRunOptions = {}) {
|
||||
const runDir = deps.resolveRunDir(options.runDir);
|
||||
if (!runDir) {
|
||||
return emptyProcessStatus("No native scanner runDir available.");
|
||||
return Promise.resolve(emptyProcessStatus("No native scanner runDir available."));
|
||||
}
|
||||
const active = activeProcessingRuns.get(runDir);
|
||||
if (active) return active;
|
||||
|
||||
const { jobsPath, jobs } = await readNativeCaptureJobs(runDir);
|
||||
const limit = Math.max(1, Math.min(jobs.length, Math.round(options.limit ?? jobs.length)));
|
||||
const selectedJobs = jobs.slice(0, limit);
|
||||
const runId = path.basename(runDir);
|
||||
const ikCatalog = deps.loadIkArtifactCatalog
|
||||
? await deps.loadIkArtifactCatalog().catch(() => null)
|
||||
: null;
|
||||
|
||||
const processedJobs = await mapWithConcurrency(
|
||||
selectedJobs,
|
||||
POST_CAPTURE_QUEUE_CONCURRENCY,
|
||||
(job) => processNativeCaptureJob({
|
||||
deps,
|
||||
ikCatalog,
|
||||
job,
|
||||
persist: Boolean(options.persist),
|
||||
runDir,
|
||||
runId,
|
||||
}),
|
||||
);
|
||||
const results = processedJobs.map((entry) => entry.result);
|
||||
const scanResults = processedJobs.map((entry) => entry.scanResult);
|
||||
const recordsToPersist = processedJobs
|
||||
.map((entry) => entry.storedRecord)
|
||||
.filter((record): record is StoredArtifactRecord => Boolean(record));
|
||||
|
||||
let stored = 0;
|
||||
if (options.persist && recordsToPersist.length > 0) {
|
||||
const saved = await deps.saveArtifacts(recordsToPersist);
|
||||
stored = saved.added + saved.updated;
|
||||
}
|
||||
|
||||
const status: NativeScannerProcessStatus = {
|
||||
ok: true,
|
||||
runDir,
|
||||
jobsPath,
|
||||
reportPath: path.join(runDir, "processing-report.json"),
|
||||
scanResultsPath: path.join(runDir, "scan-results.json"),
|
||||
processed: results.length,
|
||||
parsed: results.filter((result) => result.parsed).length,
|
||||
review: results.filter((result) => result.needsReview).length,
|
||||
stored,
|
||||
errors: results.filter((result) => result.error).length,
|
||||
elapsedMs: Date.now() - started,
|
||||
queueConcurrency: Math.min(POST_CAPTURE_QUEUE_CONCURRENCY, selectedJobs.length),
|
||||
persisted: Boolean(options.persist),
|
||||
results,
|
||||
};
|
||||
await fs.writeFile(status.scanResultsPath, JSON.stringify(scanResults, null, 2), "utf8");
|
||||
await fs.writeFile(status.reportPath, JSON.stringify(status, null, 2), "utf8");
|
||||
return status;
|
||||
replaceCachedLiveResults(runDir, []);
|
||||
const runPromise = processNativeScannerRun({ deps, options, runDir })
|
||||
.finally(() => {
|
||||
if (activeProcessingRuns.get(runDir) === runPromise) {
|
||||
activeProcessingRuns.delete(runDir);
|
||||
}
|
||||
});
|
||||
activeProcessingRuns.set(runDir, runPromise);
|
||||
return runPromise;
|
||||
},
|
||||
|
||||
async loadResults(options = {}) {
|
||||
@@ -135,20 +148,32 @@ export function createNativeScannerProcessingService(
|
||||
|
||||
const resultsPath = path.join(runDir, "scan-results.json");
|
||||
try {
|
||||
const raw = await fs.readFile(resultsPath, "utf8");
|
||||
const parsed = JSON.parse(raw);
|
||||
const results = Array.isArray(parsed)
|
||||
? parsed.filter(isStoredScanResultEntry)
|
||||
: [];
|
||||
const cached = liveResultsByRunDir.get(runDir);
|
||||
const rawResults = cached
|
||||
? [...cached]
|
||||
: await readStoredScanResults(resultsPath);
|
||||
const deletedIds = await loadNativeScannerDeletedResultIds(runDir);
|
||||
const results = rawResults.filter((entry) => !deletedIds.has(entry.id));
|
||||
const afterSequence = Number.isFinite(options.afterSequence)
|
||||
? Math.max(0, Math.round(options.afterSequence ?? 0))
|
||||
: null;
|
||||
const candidates = afterSequence === null
|
||||
? results
|
||||
: results.filter((entry) => entry.sequence > afterSequence);
|
||||
const limit = Number.isFinite(options.limit)
|
||||
? Math.max(1, Math.min(results.length, Math.round(options.limit ?? results.length)))
|
||||
: results.length;
|
||||
? Math.max(1, Math.min(candidates.length, Math.round(options.limit ?? candidates.length)))
|
||||
: candidates.length;
|
||||
const selectedResults = afterSequence === null
|
||||
? candidates.slice(-limit)
|
||||
: candidates.slice(0, limit);
|
||||
const timing = await recordResultReconciliationIfComplete(deps, runDir, results);
|
||||
return {
|
||||
ok: true,
|
||||
runDir,
|
||||
path: resultsPath,
|
||||
total: results.length,
|
||||
results: results.slice(-limit),
|
||||
results: selectedResults,
|
||||
...(timing ? { timing } : {}),
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
@@ -159,8 +184,21 @@ export function createNativeScannerProcessingService(
|
||||
}
|
||||
},
|
||||
|
||||
promoteResults: resultWorkflows.promoteResults,
|
||||
reviewResult: resultWorkflows.reviewResult,
|
||||
async promoteResults(options) {
|
||||
const status = await resultWorkflows.promoteResults(options);
|
||||
await refreshCachedResultsAfterMutation(deps, options.runDir);
|
||||
return status;
|
||||
},
|
||||
async reviewResult(options) {
|
||||
const status = await resultWorkflows.reviewResult(options);
|
||||
await refreshCachedResultsAfterMutation(deps, options.runDir);
|
||||
return status;
|
||||
},
|
||||
async deleteResult(options) {
|
||||
const status = await resultWorkflows.deleteResult(options);
|
||||
await refreshCachedResultsAfterMutation(deps, options.runDir);
|
||||
return status;
|
||||
},
|
||||
|
||||
async loadImage(options) {
|
||||
const runDir = deps.resolveRunDir(options.runDir);
|
||||
@@ -205,6 +243,617 @@ export function createNativeScannerProcessingService(
|
||||
};
|
||||
}
|
||||
|
||||
async function processNativeScannerRun({
|
||||
deps,
|
||||
options,
|
||||
runDir,
|
||||
}: {
|
||||
deps: NativeScannerProcessingServiceDependencies;
|
||||
options: ProcessRunOptions;
|
||||
runDir: string;
|
||||
}) {
|
||||
await updateRunTiming(deps, runDir, { processingStartedAt: new Date().toISOString() });
|
||||
return options.stream
|
||||
? processStreamingNativeScannerRun({ deps, options, runDir })
|
||||
: processBatchNativeScannerRun({ deps, options, runDir });
|
||||
}
|
||||
|
||||
async function processBatchNativeScannerRun({
|
||||
deps,
|
||||
options,
|
||||
runDir,
|
||||
}: {
|
||||
deps: NativeScannerProcessingServiceDependencies;
|
||||
options: ProcessRunOptions;
|
||||
runDir: string;
|
||||
}): Promise<NativeScannerProcessStatus> {
|
||||
const started = Date.now();
|
||||
const { jobsPath, jobs } = await readNativeCaptureJobs(runDir);
|
||||
const requestedLimit = Number.isFinite(options.limit)
|
||||
? Math.max(1, Math.round(options.limit ?? jobs.length))
|
||||
: jobs.length;
|
||||
const selectedJobs = jobs.slice(0, Math.min(jobs.length, requestedLimit));
|
||||
const runId = path.basename(runDir);
|
||||
const ikCatalog = deps.loadIkArtifactCatalog
|
||||
? await deps.loadIkArtifactCatalog().catch(() => null)
|
||||
: null;
|
||||
|
||||
let processedCount = 0;
|
||||
let parsedCount = 0;
|
||||
let reviewCount = 0;
|
||||
let errorCount = 0;
|
||||
const publishProgress = (running: boolean, stored = 0) => safePublishProgress(deps, {
|
||||
running,
|
||||
runDir,
|
||||
total: selectedJobs.length,
|
||||
processed: processedCount,
|
||||
parsed: parsedCount,
|
||||
review: reviewCount,
|
||||
stored,
|
||||
errors: errorCount,
|
||||
elapsedMs: Date.now() - started,
|
||||
});
|
||||
publishProgress(true);
|
||||
|
||||
const processedJobs = await mapWithConcurrency(
|
||||
selectedJobs,
|
||||
POST_CAPTURE_QUEUE_CONCURRENCY,
|
||||
async (job) => {
|
||||
const processedJob = await processNativeCaptureJob({
|
||||
deps,
|
||||
ikCatalog,
|
||||
job,
|
||||
persist: Boolean(options.persist),
|
||||
runDir,
|
||||
runId,
|
||||
});
|
||||
processedCount += 1;
|
||||
if (processedJob.result.parsed) parsedCount += 1;
|
||||
if (processedJob.result.needsReview) reviewCount += 1;
|
||||
if (processedJob.result.error) errorCount += 1;
|
||||
publishProgress(true);
|
||||
return processedJob;
|
||||
},
|
||||
);
|
||||
const scanResults = processedJobs.map((entry) => entry.scanResult);
|
||||
replaceCachedLiveResults(runDir, scanResults);
|
||||
for (const result of scanResults) safePublishResult(deps, result);
|
||||
return finalizeProcessedRun({
|
||||
deps,
|
||||
jobsPath,
|
||||
ok: true,
|
||||
options,
|
||||
processedJobs,
|
||||
runDir,
|
||||
started,
|
||||
});
|
||||
}
|
||||
|
||||
async function processStreamingNativeScannerRun({
|
||||
deps,
|
||||
options,
|
||||
runDir,
|
||||
}: {
|
||||
deps: NativeScannerProcessingServiceDependencies;
|
||||
options: ProcessRunOptions;
|
||||
runDir: string;
|
||||
}): Promise<NativeScannerProcessStatus> {
|
||||
const started = Date.now();
|
||||
const runId = path.basename(runDir);
|
||||
const jobsPath = path.join(runDir, "capture-jobs.jsonl");
|
||||
const reportPath = path.join(runDir, "processing-report.json");
|
||||
const scanResultsPath = path.join(runDir, "scan-results.json");
|
||||
const streamLimit = Number.isFinite(options.limit)
|
||||
? Math.max(1, Math.round(options.limit ?? 1))
|
||||
: Number.POSITIVE_INFINITY;
|
||||
const configuredTotal = Number.isFinite(options.expectedTotal)
|
||||
? Math.max(0, Math.round(options.expectedTotal ?? 0))
|
||||
: Number.isFinite(options.limit)
|
||||
? streamLimit
|
||||
: 0;
|
||||
const ikCatalog = deps.loadIkArtifactCatalog
|
||||
? await deps.loadIkArtifactCatalog().catch(() => null)
|
||||
: null;
|
||||
const tailState: NativeCaptureJobTailState = { offset: 0 };
|
||||
const pendingJobs: NativeCaptureJobPayload[] = [];
|
||||
const orderedSequences: number[] = [];
|
||||
const seenJobsBySequence = new Map<number, string>();
|
||||
const activeJobs = new Map<number, Promise<void>>();
|
||||
const completedBySequence = new Map<number, ProcessedNativeJob>();
|
||||
const publishedJobs: ProcessedNativeJob[] = [];
|
||||
let nextPublishIndex = 0;
|
||||
let processedCount = 0;
|
||||
let parsedCount = 0;
|
||||
let reviewCount = 0;
|
||||
let errorCount = 0;
|
||||
let producerStatus: NativeCaptureProducerStatus | null = null;
|
||||
let terminalObservedAt = 0;
|
||||
let integrityError = "";
|
||||
let snapshotWriteQueue = Promise.resolve();
|
||||
|
||||
const progressTotal = () => {
|
||||
if (producerStatus && !producerStatus.running) {
|
||||
return Math.min(producerStatus.captured, streamLimit);
|
||||
}
|
||||
return configuredTotal
|
||||
|| producerStatus?.target
|
||||
|| Math.min(orderedSequences.length, streamLimit);
|
||||
};
|
||||
const publishProgress = (running: boolean, stored = 0) => safePublishProgress(deps, {
|
||||
running,
|
||||
runDir,
|
||||
total: progressTotal(),
|
||||
processed: processedCount,
|
||||
parsed: parsedCount,
|
||||
review: reviewCount,
|
||||
stored,
|
||||
errors: errorCount + (integrityError ? 1 : 0),
|
||||
elapsedMs: Date.now() - started,
|
||||
...(integrityError ? { error: integrityError } : {}),
|
||||
});
|
||||
const queueDurableSnapshot = () => {
|
||||
const snapshot = [...publishedJobs];
|
||||
const status = buildProcessStatus({
|
||||
jobsPath,
|
||||
ok: true,
|
||||
options,
|
||||
processedJobs: snapshot,
|
||||
runDir,
|
||||
started,
|
||||
stored: 0,
|
||||
});
|
||||
snapshotWriteQueue = snapshotWriteQueue
|
||||
.catch(() => undefined)
|
||||
.then(() => writeProcessingOutputs({ reportPath, scanResultsPath, status, processedJobs: snapshot }));
|
||||
};
|
||||
const flushOrderedResults = () => {
|
||||
let published = false;
|
||||
while (nextPublishIndex < orderedSequences.length) {
|
||||
const sequence = orderedSequences[nextPublishIndex];
|
||||
const completed = completedBySequence.get(sequence);
|
||||
if (!completed) break;
|
||||
completedBySequence.delete(sequence);
|
||||
nextPublishIndex += 1;
|
||||
publishedJobs.push(completed);
|
||||
appendCachedLiveResult(runDir, completed.scanResult);
|
||||
safePublishResult(deps, completed.scanResult);
|
||||
published = true;
|
||||
}
|
||||
if (published && (publishedJobs.length === 1 || publishedJobs.length % 8 === 0)) {
|
||||
queueDurableSnapshot();
|
||||
}
|
||||
};
|
||||
const scheduleAvailableJobs = () => {
|
||||
while (activeJobs.size < POST_CAPTURE_QUEUE_CONCURRENCY && pendingJobs.length > 0) {
|
||||
const job = pendingJobs.shift();
|
||||
if (!job) break;
|
||||
const task = processNativeCaptureJob({
|
||||
deps,
|
||||
ikCatalog,
|
||||
job,
|
||||
persist: Boolean(options.persist),
|
||||
runDir,
|
||||
runId,
|
||||
}).then((processedJob) => {
|
||||
processedCount += 1;
|
||||
if (processedJob.result.parsed) parsedCount += 1;
|
||||
if (processedJob.result.needsReview) reviewCount += 1;
|
||||
if (processedJob.result.error) errorCount += 1;
|
||||
completedBySequence.set(job.sequence, processedJob);
|
||||
flushOrderedResults();
|
||||
publishProgress(true);
|
||||
}).finally(() => {
|
||||
activeJobs.delete(job.sequence);
|
||||
});
|
||||
activeJobs.set(job.sequence, task);
|
||||
}
|
||||
};
|
||||
|
||||
publishProgress(true);
|
||||
while (true) {
|
||||
const queueCapacity = Math.max(
|
||||
0,
|
||||
STREAM_QUEUE_HIGH_WATERMARK - pendingJobs.length - activeJobs.size,
|
||||
);
|
||||
const appendedJobs = queueCapacity > 0
|
||||
? await readAppendedNativeCaptureJobs(jobsPath, tailState, queueCapacity)
|
||||
: [];
|
||||
for (const job of appendedJobs) {
|
||||
const identity = nativeCaptureJobIdentity(job);
|
||||
const existingIdentity = seenJobsBySequence.get(job.sequence);
|
||||
if (existingIdentity) {
|
||||
if (existingIdentity !== identity && !integrityError) {
|
||||
integrityError = `Conflicting capture jobs use sequence ${job.sequence}.`;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (orderedSequences.length >= streamLimit) continue;
|
||||
seenJobsBySequence.set(job.sequence, identity);
|
||||
orderedSequences.push(job.sequence);
|
||||
pendingJobs.push(job);
|
||||
}
|
||||
scheduleAvailableJobs();
|
||||
|
||||
const nextProducerStatus = await readNativeCaptureProducerStatus(runDir);
|
||||
if (nextProducerStatus) producerStatus = nextProducerStatus;
|
||||
if (producerStatus && !producerStatus.running && terminalObservedAt === 0) {
|
||||
terminalObservedAt = Date.now();
|
||||
}
|
||||
|
||||
const expectedCapturedJobs = producerStatus && !producerStatus.running
|
||||
? Math.min(producerStatus.captured, streamLimit)
|
||||
: null;
|
||||
const producerDrained = expectedCapturedJobs !== null
|
||||
&& orderedSequences.length >= expectedCapturedJobs;
|
||||
if (producerDrained && pendingJobs.length === 0 && activeJobs.size === 0) break;
|
||||
if (
|
||||
expectedCapturedJobs !== null
|
||||
&& terminalObservedAt > 0
|
||||
&& Date.now() - terminalObservedAt >= STREAM_TERMINAL_DRAIN_GRACE_MS
|
||||
&& pendingJobs.length === 0
|
||||
&& activeJobs.size === 0
|
||||
) {
|
||||
integrityError = `Capture job stream ended with ${orderedSequences.length}/${expectedCapturedJobs} jobs.`;
|
||||
break;
|
||||
}
|
||||
|
||||
if (activeJobs.size > 0) {
|
||||
await Promise.race([
|
||||
Promise.race(activeJobs.values()),
|
||||
delay(STREAM_POLL_INTERVAL_MS),
|
||||
]);
|
||||
} else {
|
||||
await delay(STREAM_POLL_INTERVAL_MS);
|
||||
}
|
||||
}
|
||||
|
||||
if (activeJobs.size > 0) await Promise.all(activeJobs.values());
|
||||
flushOrderedResults();
|
||||
await snapshotWriteQueue.catch(() => undefined);
|
||||
const status = await finalizeProcessedRun({
|
||||
deps,
|
||||
jobsPath,
|
||||
ok: !integrityError,
|
||||
options,
|
||||
processedJobs: publishedJobs,
|
||||
runDir,
|
||||
started,
|
||||
error: integrityError || undefined,
|
||||
});
|
||||
return status;
|
||||
}
|
||||
|
||||
async function finalizeProcessedRun({
|
||||
deps,
|
||||
error,
|
||||
jobsPath,
|
||||
ok,
|
||||
options,
|
||||
processedJobs,
|
||||
runDir,
|
||||
started,
|
||||
}: {
|
||||
deps: NativeScannerProcessingServiceDependencies;
|
||||
error?: string;
|
||||
jobsPath: string;
|
||||
ok: boolean;
|
||||
options: ProcessRunOptions;
|
||||
processedJobs: ProcessedNativeJob[];
|
||||
runDir: string;
|
||||
started: number;
|
||||
}) {
|
||||
const recordsToPersist = processedJobs
|
||||
.map((entry) => entry.storedRecord)
|
||||
.filter((record): record is StoredArtifactRecord => Boolean(record));
|
||||
let stored = 0;
|
||||
if (options.persist && recordsToPersist.length > 0) {
|
||||
const saved = await deps.saveArtifacts(recordsToPersist);
|
||||
stored = saved.added + saved.updated;
|
||||
}
|
||||
const processingTiming = await updateRunTiming(deps, runDir, {
|
||||
processingCompletedAt: new Date().toISOString(),
|
||||
});
|
||||
let status = buildProcessStatus({
|
||||
error,
|
||||
jobsPath,
|
||||
ok,
|
||||
options,
|
||||
processedJobs,
|
||||
runDir,
|
||||
started,
|
||||
stored,
|
||||
timing: processingTiming,
|
||||
});
|
||||
// The complete results file is the durable hand-off boundary. Keep its
|
||||
// timestamp distinct from a later renderer/service reconciliation read.
|
||||
await writeJsonAtomic(status.scanResultsPath, processedJobs.map((entry) => entry.scanResult));
|
||||
const durableTiming = await updateRunTiming(deps, runDir, {
|
||||
resultsDurableAt: new Date().toISOString(),
|
||||
});
|
||||
status = buildProcessStatus({
|
||||
error,
|
||||
jobsPath,
|
||||
ok,
|
||||
options,
|
||||
processedJobs,
|
||||
runDir,
|
||||
started,
|
||||
stored,
|
||||
timing: durableTiming ?? processingTiming,
|
||||
});
|
||||
await writeJsonAtomic(status.reportPath, status);
|
||||
replaceCachedLiveResults(runDir, processedJobs.map((entry) => entry.scanResult));
|
||||
safePublishProgress(deps, {
|
||||
running: false,
|
||||
runDir,
|
||||
total: processedJobs.length,
|
||||
processed: status.processed,
|
||||
parsed: status.parsed,
|
||||
review: status.review,
|
||||
stored: status.stored,
|
||||
errors: status.errors,
|
||||
elapsedMs: status.elapsedMs,
|
||||
...(status.error ? { error: status.error } : {}),
|
||||
});
|
||||
return status;
|
||||
}
|
||||
|
||||
function buildProcessStatus({
|
||||
error,
|
||||
jobsPath,
|
||||
ok,
|
||||
options,
|
||||
processedJobs,
|
||||
runDir,
|
||||
started,
|
||||
stored,
|
||||
timing,
|
||||
}: {
|
||||
error?: string;
|
||||
jobsPath: string;
|
||||
ok: boolean;
|
||||
options: ProcessRunOptions;
|
||||
processedJobs: ProcessedNativeJob[];
|
||||
runDir: string;
|
||||
started: number;
|
||||
stored: number;
|
||||
timing?: NativeScannerRunTiming;
|
||||
}): NativeScannerProcessStatus {
|
||||
const results = processedJobs.map((entry) => entry.result);
|
||||
return {
|
||||
ok,
|
||||
runDir,
|
||||
jobsPath,
|
||||
reportPath: path.join(runDir, "processing-report.json"),
|
||||
scanResultsPath: path.join(runDir, "scan-results.json"),
|
||||
processed: results.length,
|
||||
parsed: results.filter((result) => result.parsed).length,
|
||||
review: results.filter((result) => result.needsReview).length,
|
||||
stored,
|
||||
errors: results.filter((result) => result.error).length + (error ? 1 : 0),
|
||||
elapsedMs: Date.now() - started,
|
||||
queueConcurrency: Math.min(POST_CAPTURE_QUEUE_CONCURRENCY, processedJobs.length),
|
||||
persisted: Boolean(options.persist),
|
||||
results,
|
||||
...(timing ? { timing } : {}),
|
||||
...(error ? { error } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
async function writeProcessingOutputs({
|
||||
processedJobs,
|
||||
reportPath,
|
||||
scanResultsPath,
|
||||
status,
|
||||
}: {
|
||||
processedJobs: ProcessedNativeJob[];
|
||||
reportPath: string;
|
||||
scanResultsPath: string;
|
||||
status: NativeScannerProcessStatus;
|
||||
}) {
|
||||
await writeJsonAtomic(scanResultsPath, processedJobs.map((entry) => entry.scanResult));
|
||||
await writeJsonAtomic(reportPath, status);
|
||||
}
|
||||
|
||||
async function writeJsonAtomic(filePath: string, payload: unknown) {
|
||||
const temporaryPath = `${filePath}.tmp-${process.pid}`;
|
||||
await fs.writeFile(temporaryPath, JSON.stringify(payload, null, 2), "utf8");
|
||||
await fs.rename(temporaryPath, filePath);
|
||||
}
|
||||
|
||||
type NativeCaptureJobTailState = {
|
||||
offset: number;
|
||||
};
|
||||
|
||||
async function readAppendedNativeCaptureJobs(
|
||||
jobsPath: string,
|
||||
state: NativeCaptureJobTailState,
|
||||
maxJobs: number,
|
||||
): Promise<NativeCaptureJobPayload[]> {
|
||||
let handle: Awaited<ReturnType<typeof fs.open>> | null = null;
|
||||
try {
|
||||
handle = await fs.open(jobsPath, "r");
|
||||
const stat = await handle.stat();
|
||||
if (stat.size < state.offset) {
|
||||
state.offset = 0;
|
||||
}
|
||||
const length = Math.min(stat.size - state.offset, STREAM_READ_CHUNK_BYTES);
|
||||
if (length <= 0) return [];
|
||||
const chunk = Buffer.alloc(length);
|
||||
const { bytesRead } = await handle.read(chunk, 0, length, state.offset);
|
||||
const jobs: NativeCaptureJobPayload[] = [];
|
||||
let lineStart = 0;
|
||||
let consumedBytes = 0;
|
||||
for (let index = 0; index < bytesRead; index += 1) {
|
||||
if (chunk[index] !== 0x0a) continue;
|
||||
const line = chunk.subarray(lineStart, index).toString("utf8").trim();
|
||||
lineStart = index + 1;
|
||||
consumedBytes = lineStart;
|
||||
if (!line) continue;
|
||||
const job = JSON.parse(line) as NativeCaptureJobPayload;
|
||||
if (Number.isFinite(job.sequence)) jobs.push(job);
|
||||
if (jobs.length >= maxJobs) break;
|
||||
}
|
||||
state.offset += consumedBytes;
|
||||
return jobs;
|
||||
} catch (error) {
|
||||
if (isMissingFileError(error)) return [];
|
||||
throw error;
|
||||
} finally {
|
||||
await handle?.close().catch(() => undefined);
|
||||
}
|
||||
}
|
||||
|
||||
async function readNativeCaptureProducerStatus(runDir: string): Promise<NativeCaptureProducerStatus | null> {
|
||||
try {
|
||||
const raw = JSON.parse(await fs.readFile(path.join(runDir, "status.json"), "utf8"));
|
||||
const scanner = raw?.scanner ?? raw;
|
||||
if (!scanner || typeof scanner !== "object") return null;
|
||||
return {
|
||||
running: Boolean(scanner.running),
|
||||
status: typeof scanner.status === "string" ? scanner.status : "unknown",
|
||||
target: Math.max(0, Math.round(Number(scanner.target) || 0)),
|
||||
captured: Math.max(0, Math.round(Number(scanner.captured) || 0)),
|
||||
};
|
||||
} catch (error) {
|
||||
if (isMissingFileError(error) || error instanceof SyntaxError) return null;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
async function readStoredScanResults(resultsPath: string) {
|
||||
const raw = await fs.readFile(resultsPath, "utf8");
|
||||
const parsed = JSON.parse(raw);
|
||||
return Array.isArray(parsed)
|
||||
? parsed.filter(isStoredScanResultEntry).map(evaluateStoredScanResult)
|
||||
: [];
|
||||
}
|
||||
|
||||
async function refreshCachedResultsAfterMutation(
|
||||
deps: NativeScannerProcessingServiceDependencies,
|
||||
requestedRunDir?: string,
|
||||
) {
|
||||
const runDir = deps.resolveRunDir(requestedRunDir);
|
||||
if (!runDir) return;
|
||||
try {
|
||||
const [results, deletedIds] = await Promise.all([
|
||||
readStoredScanResults(path.join(runDir, "scan-results.json")),
|
||||
loadNativeScannerDeletedResultIds(runDir),
|
||||
]);
|
||||
replaceCachedLiveResults(runDir, results.filter((entry) => !deletedIds.has(entry.id)));
|
||||
} catch {
|
||||
// Mutation status remains authoritative; a later disk load can retry.
|
||||
liveResultsByRunDir.delete(runDir);
|
||||
}
|
||||
}
|
||||
|
||||
async function recordResultReconciliationIfComplete(
|
||||
deps: NativeScannerProcessingServiceDependencies,
|
||||
runDir: string,
|
||||
results: StoredScanResultEntry[],
|
||||
) {
|
||||
const currentTiming = await loadRunTiming(deps, runDir);
|
||||
// Legacy runs intentionally stay untouched. A reconciliation timestamp is
|
||||
// meaningful only for a run that already owns the new capture/processing
|
||||
// timeline and whose complete result file was durably written by this path.
|
||||
if (!currentTiming?.resultsDurableAt || currentTiming.resultsReconciledAt) return currentTiming ?? undefined;
|
||||
|
||||
const producer = await readNativeCaptureProducerStatus(runDir).catch(() => null);
|
||||
const terminal = producer
|
||||
&& !producer.running
|
||||
&& (producer.status === "done" || producer.status === "completed")
|
||||
&& producer.captured > 0
|
||||
&& results.length === producer.captured;
|
||||
if (!terminal) return currentTiming;
|
||||
return updateRunTiming(deps, runDir, { resultsReconciledAt: new Date().toISOString() }) ?? currentTiming;
|
||||
}
|
||||
|
||||
async function updateRunTiming(
|
||||
deps: NativeScannerProcessingServiceDependencies,
|
||||
runDir: string,
|
||||
patch: NativeScannerRunTimingPatch,
|
||||
) {
|
||||
if (!deps.recordRunTiming || !runDir) return undefined;
|
||||
try {
|
||||
return await deps.recordRunTiming(runDir, patch);
|
||||
} catch {
|
||||
// Timing is evidence, never a dependency of scanner correctness. A later
|
||||
// caller can still load the durable results and report the missing marker.
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
async function loadRunTiming(
|
||||
deps: NativeScannerProcessingServiceDependencies,
|
||||
runDir: string,
|
||||
) {
|
||||
if (!deps.loadRunTiming || !runDir) return null;
|
||||
try {
|
||||
return await deps.loadRunTiming(runDir);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function replaceCachedLiveResults(runDir: string, results: StoredScanResultEntry[]) {
|
||||
liveResultsByRunDir.delete(runDir);
|
||||
liveResultsByRunDir.set(runDir, [...results]);
|
||||
while (liveResultsByRunDir.size > MAX_CACHED_LIVE_RUNS) {
|
||||
const oldest = liveResultsByRunDir.keys().next().value;
|
||||
if (typeof oldest !== "string") break;
|
||||
liveResultsByRunDir.delete(oldest);
|
||||
}
|
||||
}
|
||||
|
||||
function appendCachedLiveResult(runDir: string, result: StoredScanResultEntry) {
|
||||
const current = liveResultsByRunDir.get(runDir) ?? [];
|
||||
if (current.some((entry) => entry.id === result.id)) return;
|
||||
current.push(result);
|
||||
liveResultsByRunDir.set(runDir, current);
|
||||
}
|
||||
|
||||
function safePublishProgress(
|
||||
deps: NativeScannerProcessingServiceDependencies,
|
||||
progress: NativeScannerProcessingProgressStatus,
|
||||
) {
|
||||
try {
|
||||
deps.onProgress?.(progress);
|
||||
} catch {
|
||||
// UI progress must never abort durable OCR/parse processing.
|
||||
}
|
||||
}
|
||||
|
||||
function safePublishResult(deps: NativeScannerProcessingServiceDependencies, result: StoredScanResultEntry) {
|
||||
try {
|
||||
deps.onResult?.(result);
|
||||
} catch {
|
||||
// UI delivery is best effort; loadResults can reconcile from memory or disk.
|
||||
}
|
||||
}
|
||||
|
||||
function nativeCaptureJobIdentity(job: NativeCaptureJobPayload) {
|
||||
return JSON.stringify({
|
||||
sequence: job.sequence,
|
||||
category: job.category ?? "",
|
||||
page: job.page ?? null,
|
||||
row: job.row ?? null,
|
||||
col: job.col ?? null,
|
||||
relativePath: job.relativePath ?? "",
|
||||
absolutePath: job.absolutePath ?? "",
|
||||
starCount: job.starCount ?? null,
|
||||
starConfidence: job.starConfidence ?? null,
|
||||
starSource: job.starSource ?? "",
|
||||
});
|
||||
}
|
||||
|
||||
function isMissingFileError(error: unknown) {
|
||||
return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
|
||||
}
|
||||
|
||||
function delay(ms: number) {
|
||||
return new Promise((resolve) => setTimeout(resolve, ms));
|
||||
}
|
||||
|
||||
export function nativeScannerProcessStats(status: NativeScannerProcessStatus): Record<string, number> {
|
||||
return {
|
||||
processed: status.processed,
|
||||
@@ -252,13 +901,53 @@ async function processNativeCaptureJob({
|
||||
const capture = await deps.buildCaptureResult(imagePath, job);
|
||||
const parsed = parseArtifactCandidate(capture);
|
||||
const ikMatch = parsed && ikCatalog ? matchParsedArtifactToIk(parsed, ikCatalog) : null;
|
||||
const notes = [...new Set([...(parsed?.notes ?? []), ...(ikMatch?.notes ?? [])])];
|
||||
const needsReview = parsedArtifactNeedsReview(parsed) || Boolean(ikMatch && !ikMatch.matched);
|
||||
const rarityEvidence = nativeJobRarityEvidence(job);
|
||||
const notes = [...new Set([
|
||||
...(parsed?.notes ?? []),
|
||||
...(ikMatch?.notes ?? []),
|
||||
...(rarityEvidence.uncertain ? ["Artifact star row could not be confirmed; keep this result in Review."] : []),
|
||||
])];
|
||||
const needsReview = shouldFlagArtifactForReview(parsed)
|
||||
|| Boolean(ikMatch && !ikMatch.matched)
|
||||
|| rarityEvidence.uncertain;
|
||||
const canPersist = parsedArtifactCanPersist(parsed, needsReview);
|
||||
const shouldPersist = Boolean(persist && parsed && canPersist && !needsReview);
|
||||
const baseScanResult = createStoredScanResultEntry({
|
||||
runId,
|
||||
sequence: job.sequence,
|
||||
page: job.page,
|
||||
row: job.row,
|
||||
col: job.col,
|
||||
category: category.scanResultCategory,
|
||||
source: "native-ik-scan",
|
||||
imagePath,
|
||||
parsed,
|
||||
needsReview,
|
||||
confidence: parsed?.confidence ?? 0,
|
||||
capturedAt: job.capturedAt,
|
||||
persistedArtifact: false,
|
||||
notes,
|
||||
locked: capture.locked,
|
||||
ikMatch: ikMatch ?? undefined,
|
||||
rarity: rarityEvidence.rarity,
|
||||
rarityConfidence: rarityEvidence.confidence,
|
||||
raritySource: rarityEvidence.rarity ? "native" : undefined,
|
||||
});
|
||||
const shouldPersist = Boolean(
|
||||
persist
|
||||
&& parsed
|
||||
&& canPersist
|
||||
&& !needsReview
|
||||
&& baseScanResult.valueStatus === "evaluated"
|
||||
&& baseScanResult.valueEvaluation?.status === "evaluated"
|
||||
&& baseScanResult.valueEvaluation.score !== null
|
||||
&& Number.isFinite(baseScanResult.valueEvaluation.score),
|
||||
);
|
||||
const storedRecord = parsed && shouldPersist
|
||||
? toStoredArtifact(parsed, "native-ik-scan", needsReview, capture.locked)
|
||||
: null;
|
||||
const scanResult = storedRecord
|
||||
? { ...baseScanResult, artifactRecordId: storedRecord.id, persistedArtifact: true }
|
||||
: baseScanResult;
|
||||
return {
|
||||
result: {
|
||||
sequence: job.sequence,
|
||||
@@ -273,30 +962,14 @@ async function processNativeCaptureJob({
|
||||
slot: parsed?.slot,
|
||||
confidence: parsed?.confidence ?? 0,
|
||||
needsReview,
|
||||
rarity: rarityEvidence.rarity,
|
||||
rarityConfidence: rarityEvidence.confidence,
|
||||
persisted: shouldPersist,
|
||||
ikMatch: ikMatch ?? undefined,
|
||||
notes,
|
||||
ocr: capture.ocr ?? [],
|
||||
},
|
||||
scanResult: createStoredScanResultEntry({
|
||||
runId,
|
||||
sequence: job.sequence,
|
||||
page: job.page,
|
||||
row: job.row,
|
||||
col: job.col,
|
||||
category: category.scanResultCategory,
|
||||
source: "native-ik-scan",
|
||||
imagePath,
|
||||
parsed,
|
||||
needsReview,
|
||||
confidence: parsed?.confidence ?? 0,
|
||||
capturedAt: job.capturedAt,
|
||||
artifactRecordId: storedRecord?.id,
|
||||
persistedArtifact: shouldPersist,
|
||||
notes,
|
||||
locked: capture.locked,
|
||||
ikMatch: ikMatch ?? undefined,
|
||||
}),
|
||||
scanResult,
|
||||
storedRecord,
|
||||
};
|
||||
} catch (error) {
|
||||
@@ -305,6 +978,26 @@ async function processNativeCaptureJob({
|
||||
}
|
||||
}
|
||||
|
||||
function nativeJobRarityEvidence(job: NativeCaptureJobPayload): {
|
||||
rarity?: ArtifactRarity;
|
||||
confidence?: number;
|
||||
/** The newer helper attempted direct visual detection but could not prove a count. */
|
||||
uncertain: boolean;
|
||||
} {
|
||||
const hasDetectionPayload = Object.prototype.hasOwnProperty.call(job, "starCount")
|
||||
|| Object.prototype.hasOwnProperty.call(job, "starConfidence")
|
||||
|| Object.prototype.hasOwnProperty.call(job, "starSource");
|
||||
if (!hasDetectionPayload) return { uncertain: false };
|
||||
|
||||
const starCount = Number(job.starCount);
|
||||
const confidence = Number(job.starConfidence);
|
||||
const validRarity = Number.isInteger(starCount) && starCount >= 1 && starCount <= 5;
|
||||
const confident = Number.isFinite(confidence) && confidence >= 0.8 && confidence <= 1;
|
||||
const hasSource = typeof job.starSource === "string" && job.starSource.trim().length > 0;
|
||||
if (!validRarity || !confident || !hasSource) return { uncertain: true };
|
||||
return { rarity: starCount as ArtifactRarity, confidence, uncertain: false };
|
||||
}
|
||||
|
||||
function reviewJobResult({
|
||||
category,
|
||||
error,
|
||||
@@ -473,15 +1166,6 @@ function isStoredScanResultEntry(value: unknown): value is StoredScanResultEntry
|
||||
&& Array.isArray(entry.notes);
|
||||
}
|
||||
|
||||
function parsedArtifactNeedsReview(parsed: ReturnType<typeof parseArtifactCandidate>) {
|
||||
if (!parsed) return true;
|
||||
if (parsed.confidence < 78) return true;
|
||||
const criticalFields: Array<"name" | "slot" | "mainStat" | "mainValue" | "setName"> = ["name", "slot", "mainStat", "mainValue", "setName"];
|
||||
if (criticalFields.some((field) => (parsed.fields[field]?.confidence ?? 0) < 70)) return true;
|
||||
if (parsed.substats.length === 0) return true;
|
||||
return parsed.notes.some((note) => /not confidently parsed|substats look incomplete|likely OCR misread/i.test(note));
|
||||
}
|
||||
|
||||
function parsedArtifactCanPersist(parsed: ReturnType<typeof parseArtifactCandidate>, needsReview: boolean) {
|
||||
if (!parsed) return false;
|
||||
if (parsed.name === "Unknown artifact") return false;
|
||||
|
||||
Reference in New Issue
Block a user