pixivflow 3.2.0 → 3.4.0

package/dist/scheduler/JobProjection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The generic Job projection (§liveness).
+ *
+ * One durable Slot cell, described in terms a consumer can act on WITHOUT
+ * knowing this service's internal column names, table layout or scheduler
+ * topology. This is the body a job-status endpoint returns; the manual-refetch
+ * GET endpoint is the first such consumer (and declares the legacy
+ * `requestId`/`slotId`/`state`/`slotStatus` aliases on top of it).
+ *
+ * Why the extra fields exist: a caller that receives only a coarse state cannot
+ * tell "queued two seconds ago" from "pending for three days behind a stopped
+ * scheduler", so it cannot implement a heartbeat-based watchdog — it can only
+ * poll forever. Timestamps + lease liveness + attempt count make the difference
+ * decidable, and `terminalReasonCode`/`terminalReasonMessage` give the
+ * first-level cause once the job is terminal.
+ *
+ * Timestamp normalisation (the columns do NOT share one shape):
+ *  - `schedule_slots.created_at` / `started_at` and
+ *    `schedule_slot_items.updated_at` are SQLite `CURRENT_TIMESTAMP` UTC
+ *    datetimes without a zone marker -> parsed as UTC (see `ledger-time`).
+ *  - `schedule_slots.heartbeat_at` / `lease_until` are already epoch ms.
+ *  - Every timestamp in this projection is epoch milliseconds UTC, or null when
+ *    the ledger has no such instant.
+ */
+import type { SlotItemRecord, SlotRecord } from '../storage/repositories/SlotRepository';
+export interface JobStatusProjection {
+    /** The caller's own request id, echoed back. */
+    requestId: string;
+    slotId: string;
+    /** Cell state from the Slot FSM (pending|selected|artifact_ready|delivery_pending|submitted|no_candidate|duplicate|failed). */
+    state: string;
+    /** Rolled-up Slot status (pending|running|success|partial|failed|expired). */
+    slotStatus: string;
+    createdAt: number | null;
+    /** When a worker first marked the slot running. */
+    startedAt: number | null;
+    /** Last cell update: the freshest durable progress signal for this target. */
+    updatedAt: number | null;
+    /** Last lease heartbeat written by the owning run. */
+    heartbeatAt: number | null;
+    /** When the current lease expires (null when nobody holds one). */
+    leaseExpiresAt: number | null;
+    /** A lease is held AND unexpired: some run owns this slot right now. */
+    leaseActive: boolean;
+    /** The slot left `pending` (claimed by a run or already terminal). */
+    claimed: boolean;
+    /** Delivery/execution attempts recorded on this cell. */
+    attemptCount: number;
+    terminalReasonCode: string | null;
+    terminalReasonMessage: string | null;
+    /** Internal name of the request that opened this job. */
+    manualRequestId: string | null;
+    /**
+     * Consumer-facing opaque key for the same request. A consumer groups work by
+     * this value and never needs to learn the column it came from.
+     */
+    idempotencyKey: string | null;
+    /** Opaque caller correlation (review chain / review id). */
+    correlationId: string | null;
+}
+/**
+ * Project one (slot, cell) pair. Pure: no clock reads beyond the injectable
+ * `now`, so the same ledger row always projects the same way for a given
+ * instant.
+ */
+export declare function buildJobProjection(requestId: string, slot: SlotRecord, cell: SlotItemRecord, now?: number): JobStatusProjection;
+//# sourceMappingURL=JobProjection.d.ts.map

package/dist/scheduler/JobProjection.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildJobProjection = buildJobProjection;
+const ledger_time_1 = require("./ledger-time");
+/**
+ * Project one (slot, cell) pair. Pure: no clock reads beyond the injectable
+ * `now`, so the same ledger row always projects the same way for a given
+ * instant.
+ */
+function buildJobProjection(requestId, slot, cell, now = Date.now()) {
+    const leaseActive = slot.leaseOwner !== null && slot.leaseUntil !== null && slot.leaseUntil > now;
+    return {
+        requestId,
+        slotId: slot.id,
+        state: cell.status,
+        slotStatus: slot.status,
+        createdAt: (0, ledger_time_1.sqliteUtcMs)(slot.createdAt) ?? null,
+        startedAt: (0, ledger_time_1.sqliteUtcMs)(slot.startedAt) ?? null,
+        updatedAt: (0, ledger_time_1.sqliteUtcMs)(cell.updatedAt) ?? null,
+        heartbeatAt: slot.heartbeatAt ?? null,
+        leaseExpiresAt: slot.leaseUntil ?? null,
+        leaseActive,
+        claimed: slot.status !== 'pending' || leaseActive,
+        attemptCount: cell.attemptCount,
+        terminalReasonCode: cell.terminalReasonCode ?? null,
+        terminalReasonMessage: cell.terminalReasonMessage ?? null,
+        manualRequestId: slot.manualRequestId ?? null,
+        idempotencyKey: slot.manualRequestId ?? null,
+        correlationId: slot.correlationId ?? null,
+    };
+}
+//# sourceMappingURL=JobProjection.js.map

package/dist/scheduler/JobView.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The one read model for a generic job: durable slot + cell -> `$defs/Job`.
+ *
+ * Extracted from `ManualJobService` so the HTTP job surface and the event stream
+ * (`JobEventStream`) project a slot through EXACTLY the same code. Two views of
+ * the same ledger that could disagree would be a second status machine in
+ * disguise.
+ */
+import type { StandaloneConfig } from '../config';
+import type { Database } from '../storage/Database';
+import type { SlotItemRecord, SlotRecord } from '../storage/repositories/SlotRepository';
+import { ProtocolJob } from './JobFacade';
+export interface JobViewDeps {
+    database: Database;
+    /** The live config snapshot (the trigger server always reads the newest). */
+    config(): StandaloneConfig;
+    /** Injected clock, for tests. */
+    now(): number;
+}
+/** Project one durable slot. Throws when the ledger row is not materialized. */
+export declare function protocolJobForSlot(deps: JobViewDeps, slot: SlotRecord): ProtocolJob;
+/** Project one slot by id; null when this job is not in the ledger. */
+export declare function protocolJobBySlotId(deps: JobViewDeps, slotId: string): ProtocolJob | null;
+/** Project an admitted slot that MUST exist. */
+export declare function requireProtocolJobForSlotId(deps: JobViewDeps, slotId: string): ProtocolJob;
+/**
+ * What this job actually delivered, read from the durable delivery intents.
+ * Only a confirmed delivery counts; an intent that never left is not an outcome.
+ */
+export declare function deliveredWork(deps: JobViewDeps, slot: SlotRecord, targetId: string, cell: SlotItemRecord): {
+    workId: string | null;
+    workType: string | null;
+} | null;
+//# sourceMappingURL=JobView.d.ts.map

package/dist/scheduler/JobView.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * The one read model for a generic job: durable slot + cell -> `$defs/Job`.
+ *
+ * Extracted from `ManualJobService` so the HTTP job surface and the event stream
+ * (`JobEventStream`) project a slot through EXACTLY the same code. Two views of
+ * the same ledger that could disagree would be a second status machine in
+ * disguise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.protocolJobForSlot = protocolJobForSlot;
+exports.protocolJobBySlotId = protocolJobBySlotId;
+exports.requireProtocolJobForSlotId = requireProtocolJobForSlotId;
+exports.deliveredWork = deliveredWork;
+const JobFacade_1 = require("./JobFacade");
+const JobProjection_1 = require("./JobProjection");
+const ProtocolErrors_1 = require("./ProtocolErrors");
+/** Project one durable slot. Throws when the ledger row is not materialized. */
+function protocolJobForSlot(deps, slot) {
+    const targetId = slot.targetIds[0];
+    const cell = targetId ? deps.database.slots.getCell(slot.id, targetId) : null;
+    if (!targetId || !cell) {
+        throw new ProtocolErrors_1.ProtocolRequestError('internal_error', 500, {
+            message: 'job has no materialized work item',
+            detail: { reason: 'job_cell_missing', job_id: slot.id },
+        });
+    }
+    const requestId = slot.manualRequestId ?? slot.id;
+    const projection = (0, JobProjection_1.buildJobProjection)(requestId, slot, cell, deps.now());
+    return (0, JobFacade_1.buildProtocolJob)({
+        jobType: JobFacade_1.JOB_TYPE_CANDIDATE_SEARCH,
+        projection,
+        deadlineAt: deadlineAt(slot, deps.config()),
+        delivered: deliveredWork(deps, slot, targetId, cell),
+        supply: cell.candidateReport,
+        now: deps.now(),
+    });
+}
+/** Project one slot by id; null when this job is not in the ledger. */
+function protocolJobBySlotId(deps, slotId) {
+    const slot = deps.database.slots.getSlot(slotId);
+    return slot ? protocolJobForSlot(deps, slot) : null;
+}
+/** Project an admitted slot that MUST exist. */
+function requireProtocolJobForSlotId(deps, slotId) {
+    const job = protocolJobBySlotId(deps, slotId);
+    if (!job) {
+        throw new ProtocolErrors_1.ProtocolRequestError('internal_error', 500, {
+            message: 'admitted job is missing from the ledger',
+            detail: { reason: 'job_not_persisted', job_id: slotId },
+        });
+    }
+    return job;
+}
+/**
+ * What this job actually delivered, read from the durable delivery intents.
+ * Only a confirmed delivery counts; an intent that never left is not an outcome.
+ */
+function deliveredWork(deps, slot, targetId, cell) {
+    const delivered = deps.database.deliveries
+        .listForSlotCell(slot.id, targetId)
+        .filter((row) => row.status === 'delivered');
+    const last = delivered[delivered.length - 1];
+    if (last)
+        return { workId: last.pixivId, workType: last.workType };
+    if (cell.status === 'submitted' && cell.workId) {
+        return { workId: cell.workId, workType: cell.workType };
+    }
+    return null;
+}
+/**
+ * The ceiling this deployment enforces for the job: the plan's execution
+ * timeout, measured from the occurrence. A consumer-supplied `deadline_ms`
+ * that is shorter is NOT honoured yet (no durable column enforces it), so the
+ * facade must not report it here.
+ */
+function deadlineAt(slot, config) {
+    if (slot.occurrenceAt === null)
+        return null;
+    return slot.occurrenceAt + (0, JobFacade_1.resolveDeadlineMs)(config, slot.scheduleId);
+}
+//# sourceMappingURL=JobView.js.map

package/dist/scheduler/ManualJobAdmission.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The ONE admission path for consumer-initiated candidate search work.
+ *
+ * Two HTTP entry points exist for the same durable work item:
+ *   - the legacy TelePost manual refetch (`POST /internal/targets/:id/refetch`)
+ *   - the generic Workflow Protocol v1 job surface (`POST /jobs`)
+ *
+ * They differ only in how the request is shaped, never in what happens: both
+ * adapters translate their input into one `CandidateSearchJobRequest` and call
+ * `admit()`, which owns target resolution, idempotent identity resolution and
+ * the durable slot admission. Identity is the consumer's own key
+ * (`manual_request_id`), so a replay from either entry point converges on the
+ * same `job_id`/`slotId` and never creates a second slot or delivery.
+ *
+ * Nothing here inspects the business meaning of a target, a plan or a slot
+ * name; a slot label is durable display data and is written, never branched on.
+ */
+import { StandaloneConfig, TargetConfig } from '../config';
+import type { Database } from '../storage/Database';
+import { CandidateSearchParams } from './CandidateSearchParams';
+import type { SlotContext, SlotCoordinator } from './SlotCoordinator';
+/**
+ * Durable slot label for consumer-initiated candidate search.
+ *
+ * FROZEN: production ledgers already carry this value on historical rows, and
+ * the legacy compatibility contract forbids changing it. It is a display label
+ * only — no code may branch on a slot name.
+ */
+export declare const MANUAL_CANDIDATE_SEARCH_SLOT_NAME = "\u5BA1\u6838\u7FA4\u91CD\u6293";
+/**
+ * A consumer-initiated candidate search, normalized from whichever adapter
+ * received it. `targetId` exists only for the legacy path (the old endpoint
+ * carries the target in its URL); the generic job surface instead names the
+ * target explicitly with `targetSelector` (`params.target_id`) or, when it names
+ * none, resolves the unique manual-eligible target from configuration. Both are
+ * SELECTORS over the configured targets — neither can override delivery wiring or
+ * plan identity.
+ */
+export interface CandidateSearchJobRequest {
+    /** Consumer idempotency key; becomes the durable `manual_request_id`. */
+    idempotencyKey: string;
+    /** Opaque caller correlation: stored, echoed back, never interpreted. */
+    correlationId?: string;
+    /** Legacy adapter only: target id taken from the request path. */
+    targetId?: string;
+    /** Generic adapter only: `params.target_id`, an explicit target selector. */
+    targetSelector?: string;
+    /** Generic adapter only: `params.source.account` resource identity. */
+    account?: string;
+    /**
+     * Generic adapter only: the requested retrieval view (§6). Persisted with the
+     * occurrence-scoped slot so a resumed worker re-applies it; the legacy adapter
+     * never sets it, so a refetch keeps running the plan exactly as configured.
+     */
+    params?: CandidateSearchParams;
+}
+/** What happened to the request, independent of which adapter asked. */
+export type ManualJobDisposition = 'accepted' | 'queued' | 'already_completed';
+export interface CandidateSearchJobResult {
+    /** The durable identity of the work item (`job_id`). */
+    slotId: string;
+    planId: string;
+    targetId: string;
+    disposition: ManualJobDisposition;
+    /** True when an existing slot owned this key (an idempotent replay). */
+    reused: boolean;
+}
+export interface ManualJobAdmissionDeps {
+    database: Database;
+    coordinator: SlotCoordinator;
+    /** The live config snapshot (the trigger server always reads the newest). */
+    config(): StandaloneConfig;
+    /** Hand the prepared occurrence to execution; returns false when queued. */
+    admit(planId: string, context: SlotContext, targetId: string): boolean;
+}
+export declare class ManualJobAdmission {
+    private readonly deps;
+    constructor(deps: ManualJobAdmissionDeps);
+    /**
+     * Resolve, admit and report one consumer-initiated candidate search.
+     *
+     * Idempotent by `idempotencyKey`: the first call creates the durable slot,
+     * every later call (from either entry point) returns the same `slotId`.
+     * Throws `ProtocolRequestError` so every adapter answers in the protocol's
+     * error shape while the legacy adapter keeps its historic message strings.
+     */
+    admit(request: CandidateSearchJobRequest): CandidateSearchJobResult;
+    /**
+     * `params.source.account` names the Pixiv resource identity. One process owns
+     * exactly one credential profile, so the only satisfiable value is the
+     * configured one; anything else is refused rather than silently downgraded to
+     * a different account.
+     */
+    private assertAccount;
+    /**
+     * Legacy: the target comes from the URL and must resolve to exactly one
+     * enabled plan (the historic `unknown target` / `ambiguous target` rules).
+     * Generic with `params.target_id`: the same rules, applied to the selector the
+     * caller named — a selector picks an existing target, it never rewrites one.
+     * Generic without any selector: the target is discovered from configuration —
+     * every enabled plan's selected target that actually wires manual
+     * candidate-search delivery, which must be exactly one.
+     */
+    private resolveTarget;
+    /**
+     * Idempotent identity resolution. The key is the durable identity; the
+     * plan-derived slot id is only the legacy naming convention. A key that
+     * already belongs to different work is a conflict, never a second slot.
+     */
+    private resolveExisting;
+    /**
+     * §3: reusing an idempotency key with DIFFERENT params is a conflict, never a
+     * silent second meaning for the same job. The comparison is skipped when
+     * either side carries no retrieval view (the legacy adapter never sets one),
+     * so a legacy replay of a generic job stays idempotent instead of conflicting.
+     */
+    private assertSameParams;
+    /** A key may not be reused for a different plan/target than it first created. */
+    private assertSameWork;
+    private conflict;
+    /** Legacy messages are preserved verbatim: deployed clients match on them. */
+    private assertManualWiring;
+    /**
+     * `constraints.work_types` restricts the work type this job accepts. The
+     * producer knows the resolved target's own type, so a request that asks for a
+     * type the target does not produce is refused instead of silently widened.
+     */
+    private assertParamsApplyToTarget;
+    /** Build the occurrence this work item occupies — the same shape as before. */
+    private buildContext;
+}
+/** Exported for tests/diagnostics: does this target serve manual candidate search? */
+export declare function targetServesManualCandidateSearch(config: StandaloneConfig, target: TargetConfig): boolean;
+//# sourceMappingURL=ManualJobAdmission.d.ts.map

package/dist/scheduler/ManualJobAdmission.js

@@ -0,0 +1,316 @@
+"use strict";
+/**
+ * The ONE admission path for consumer-initiated candidate search work.
+ *
+ * Two HTTP entry points exist for the same durable work item:
+ *   - the legacy TelePost manual refetch (`POST /internal/targets/:id/refetch`)
+ *   - the generic Workflow Protocol v1 job surface (`POST /jobs`)
+ *
+ * They differ only in how the request is shaped, never in what happens: both
+ * adapters translate their input into one `CandidateSearchJobRequest` and call
+ * `admit()`, which owns target resolution, idempotent identity resolution and
+ * the durable slot admission. Identity is the consumer's own key
+ * (`manual_request_id`), so a replay from either entry point converges on the
+ * same `job_id`/`slotId` and never creates a second slot or delivery.
+ *
+ * Nothing here inspects the business meaning of a target, a plan or a slot
+ * name; a slot label is durable display data and is written, never branched on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManualJobAdmission = exports.MANUAL_CANDIDATE_SEARCH_SLOT_NAME = void 0;
+exports.targetServesManualCandidateSearch = targetServesManualCandidateSearch;
+const targetRoutes_1 = require("../delivery/targetRoutes");
+const ProtocolErrors_1 = require("./ProtocolErrors");
+const schedules_1 = require("./schedules");
+/**
+ * Durable slot label for consumer-initiated candidate search.
+ *
+ * FROZEN: production ledgers already carry this value on historical rows, and
+ * the legacy compatibility contract forbids changing it. It is a display label
+ * only — no code may branch on a slot name.
+ */
+exports.MANUAL_CANDIDATE_SEARCH_SLOT_NAME = '审核群重抓';
+/**
+ * The delivery-template wiring a target must declare for manual work. The
+ * field name and placeholder VALUE are the frozen production config contract
+ * (deployed delivery templates declare them); this module only reads them.
+ */
+const DELIVERY_CORRELATION_FIELD = 'refetch_request_id';
+const DELIVERY_CORRELATION_PLACEHOLDER = '{{refetchRequestId}}';
+class ManualJobAdmission {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Resolve, admit and report one consumer-initiated candidate search.
+     *
+     * Idempotent by `idempotencyKey`: the first call creates the durable slot,
+     * every later call (from either entry point) returns the same `slotId`.
+     * Throws `ProtocolRequestError` so every adapter answers in the protocol's
+     * error shape while the legacy adapter keeps its historic message strings.
+     */
+    admit(request) {
+        const key = (request.idempotencyKey ?? '').trim();
+        if (!key) {
+            throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 400, {
+                message: 'idempotency_key must be a non-empty string',
+            });
+        }
+        const legacy = request.targetId !== undefined;
+        const config = this.deps.config();
+        this.assertAccount(config, request.account);
+        const admission = this.resolveTarget(config, request.targetId, request.targetSelector);
+        const { plan, target } = admission;
+        this.assertParamsApplyToTarget(target, request.params);
+        const derivedSlotId = `${plan.id}@manual-${key.toLowerCase()}`;
+        const existing = this.resolveExisting(plan, admission.targetId, key, derivedSlotId, legacy);
+        const slotId = existing ? existing.id : derivedSlotId;
+        if (existing)
+            this.assertSameParams(existing, request.params, legacy);
+        const context = this.buildContext(plan, slotId, key, request.correlationId, request.params);
+        const prepared = this.deps.coordinator.prepare(context, plan, [target]);
+        if (prepared.alreadyCompleted) {
+            return {
+                slotId: prepared.slotRec.id,
+                planId: plan.id,
+                targetId: admission.targetId,
+                disposition: 'already_completed',
+                reused: true,
+            };
+        }
+        const started = this.deps.admit(plan.id, context, admission.targetId);
+        return {
+            slotId: context.slotId,
+            planId: plan.id,
+            targetId: admission.targetId,
+            disposition: started ? 'accepted' : 'queued',
+            reused: existing !== null,
+        };
+    }
+    /**
+     * `params.source.account` names the Pixiv resource identity. One process owns
+     * exactly one credential profile, so the only satisfiable value is the
+     * configured one; anything else is refused rather than silently downgraded to
+     * a different account.
+     */
+    assertAccount(config, requested) {
+        if (requested === undefined)
+            return;
+        const configured = (config.pixiv?.accountId ?? '').trim() || 'default';
+        const wanted = requested.trim() || 'default';
+        if (wanted !== configured) {
+            throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 400, {
+                message: `account '${wanted}' is not available in this deployment`,
+                detail: { reason: 'account_unavailable', requested: wanted, configured },
+            });
+        }
+    }
+    /**
+     * Legacy: the target comes from the URL and must resolve to exactly one
+     * enabled plan (the historic `unknown target` / `ambiguous target` rules).
+     * Generic with `params.target_id`: the same rules, applied to the selector the
+     * caller named — a selector picks an existing target, it never rewrites one.
+     * Generic without any selector: the target is discovered from configuration —
+     * every enabled plan's selected target that actually wires manual
+     * candidate-search delivery, which must be exactly one.
+     */
+    resolveTarget(config, targetId, targetSelector) {
+        const explicit = targetId ?? targetSelector;
+        if (explicit !== undefined) {
+            const plans = (config.schedules ?? []).filter((plan) => plan.enabled !== false &&
+                (0, schedules_1.selectScheduleTargets)(config.targets, plan).some((target) => target.id === explicit));
+            if (plans.length === 0) {
+                throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 404, {
+                    message: 'unknown target',
+                    detail: { reason: 'unknown_target', target_id: explicit },
+                });
+            }
+            if (plans.length !== 1) {
+                throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 409, {
+                    message: 'ambiguous target',
+                    detail: { reason: 'ambiguous_target', target_id: explicit },
+                });
+            }
+            const plan = plans[0];
+            const target = (0, schedules_1.selectScheduleTargets)(config.targets, plan).find((item) => item.id === explicit && Boolean(item.id));
+            if (!target || !target.id) {
+                throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 404, {
+                    message: 'unknown target',
+                    detail: { reason: 'unknown_target', target_id: explicit },
+                });
+            }
+            // `legacy` only selects the historic diagnostic vocabulary: the URL-borne
+            // target is the old path, `params.target_id` is the generic one.
+            this.assertManualWiring(config, target, target.id, targetId !== undefined);
+            return { plan, target, targetId: target.id };
+        }
+        const candidates = [];
+        for (const plan of config.schedules ?? []) {
+            if (plan.enabled === false)
+                continue;
+            for (const target of (0, schedules_1.selectScheduleTargets)(config.targets, plan)) {
+                if (!target.id)
+                    continue;
+                if (targetServesManualCandidateSearch(config, target)) {
+                    candidates.push({ plan, target, targetId: target.id });
+                }
+            }
+        }
+        if (candidates.length === 0) {
+            throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 400, {
+                message: 'no candidate search target is configured',
+                detail: { reason: 'no_eligible_target' },
+            });
+        }
+        if (candidates.length > 1) {
+            throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 409, {
+                message: 'more than one candidate search target is configured',
+                detail: {
+                    reason: 'ambiguous_target',
+                    targets: candidates.map((candidate) => candidate.targetId),
+                },
+            });
+        }
+        return candidates[0];
+    }
+    /**
+     * Idempotent identity resolution. The key is the durable identity; the
+     * plan-derived slot id is only the legacy naming convention. A key that
+     * already belongs to different work is a conflict, never a second slot.
+     */
+    resolveExisting(plan, targetId, key, derivedSlotId, legacy) {
+        const byKey = this.deps.database.slots.findManualSlotByKey(key);
+        if (byKey) {
+            this.assertSameWork(byKey, plan, targetId, legacy);
+            return byKey;
+        }
+        const byId = this.deps.database.slots.getSlot(derivedSlotId);
+        if (!byId)
+            return null;
+        if (byId.manualRequestId && byId.manualRequestId !== key) {
+            throw this.conflict(legacy, `idempotency key '${key}' collides with an existing work item`, { reason: 'idempotency_conflict', slot_id: byId.id });
+        }
+        this.assertSameWork(byId, plan, targetId, legacy);
+        return byId;
+    }
+    /**
+     * §3: reusing an idempotency key with DIFFERENT params is a conflict, never a
+     * silent second meaning for the same job. The comparison is skipped when
+     * either side carries no retrieval view (the legacy adapter never sets one),
+     * so a legacy replay of a generic job stays idempotent instead of conflicting.
+     */
+    assertSameParams(slot, params, legacy) {
+        if (!params || !slot.paramsJson)
+            return;
+        if (slot.paramsJson === JSON.stringify(params))
+            return;
+        throw this.conflict(legacy, 'idempotency key was first used with different params', {
+            reason: 'idempotency_conflict',
+            slot_id: slot.id,
+        });
+    }
+    /** A key may not be reused for a different plan/target than it first created. */
+    assertSameWork(slot, plan, targetId, legacy) {
+        const sameTarget = slot.targetIds.length === 1 && slot.targetIds[0] === targetId && slot.scheduleId === plan.id;
+        if (sameTarget)
+            return;
+        if (!legacy) {
+            throw this.conflict(legacy, 'idempotency key already belongs to another work item', {
+                reason: 'idempotency_conflict',
+                slot_id: slot.id,
+            });
+        }
+        throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 409, {
+            message: 'ambiguous target',
+            detail: { reason: 'ambiguous_target', slot_id: slot.id },
+        });
+    }
+    conflict(legacy, message, detail) {
+        if (legacy) {
+            return new ProtocolErrors_1.ProtocolRequestError('invalid_params', 409, {
+                message: 'ambiguous target',
+                detail: { ...detail, reason: 'ambiguous_target' },
+            });
+        }
+        return new ProtocolErrors_1.ProtocolRequestError('idempotency_conflict', 409, { message, detail });
+    }
+    /** Legacy messages are preserved verbatim: deployed clients match on them. */
+    assertManualWiring(config, target, targetId, legacy) {
+        const deliveryName = (0, targetRoutes_1.primaryDeliveryName)(target);
+        const delivery = deliveryName ? config.delivery?.targets?.[deliveryName] : undefined;
+        if (delivery?.type !== 'httpMultipart' || !delivery.refetchOutcomeUrl?.trim()) {
+            throw new ProtocolErrors_1.ProtocolRequestError('internal_error', 500, {
+                message: legacy
+                    ? 'refetch outcome endpoint not configured'
+                    : 'candidate search delivery outcome is not configured',
+                detail: { reason: 'delivery_outcome_not_configured', target_id: targetId },
+            });
+        }
+        const field = target.delivery?.fields?.[DELIVERY_CORRELATION_FIELD] ??
+            delivery.fields?.[DELIVERY_CORRELATION_FIELD];
+        if (field !== DELIVERY_CORRELATION_PLACEHOLDER) {
+            throw new ProtocolErrors_1.ProtocolRequestError('internal_error', 500, {
+                message: legacy
+                    ? 'refetch_request_id delivery field not configured'
+                    : 'candidate search delivery correlation field is not configured',
+                detail: { reason: 'delivery_correlation_field_not_configured', target_id: targetId },
+            });
+        }
+    }
+    /**
+     * `constraints.work_types` restricts the work type this job accepts. The
+     * producer knows the resolved target's own type, so a request that asks for a
+     * type the target does not produce is refused instead of silently widened.
+     */
+    assertParamsApplyToTarget(target, params) {
+        const workTypes = params?.constraints?.work_types;
+        if (!workTypes || workTypes.length === 0)
+            return;
+        if (!workTypes.includes(target.type)) {
+            throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 400, {
+                message: `work_types ${JSON.stringify(workTypes)} does not include the configured target work type`,
+                detail: { reason: 'work_type_not_available', target_type: target.type },
+            });
+        }
+    }
+    /** Build the occurrence this work item occupies — the same shape as before. */
+    buildContext(plan, slotId, key, correlationId, params) {
+        const now = new Date();
+        const timezone = plan.timezone ?? 'UTC';
+        const date = new Intl.DateTimeFormat('en-CA', {
+            timeZone: timezone,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+        }).format(now);
+        return {
+            slotId,
+            scheduleId: plan.id,
+            occurrenceAt: now.getTime(),
+            occurrenceDate: date,
+            occurrenceLabel: 'manual',
+            timezone,
+            triggerSource: 'manual',
+            slotName: exports.MANUAL_CANDIDATE_SEARCH_SLOT_NAME,
+            slotDate: date,
+            manualRequestId: key,
+            correlationId: correlationId || undefined,
+            paramsJson: params ? JSON.stringify(params) : undefined,
+        };
+    }
+}
+exports.ManualJobAdmission = ManualJobAdmission;
+/** Exported for tests/diagnostics: does this target serve manual candidate search? */
+function targetServesManualCandidateSearch(config, target) {
+    const deliveryName = (0, targetRoutes_1.primaryDeliveryName)(target);
+    const delivery = deliveryName ? config.delivery?.targets?.[deliveryName] : undefined;
+    if (!deliveryName || !delivery)
+        return false;
+    if (delivery.type !== 'httpMultipart' || !delivery.refetchOutcomeUrl?.trim())
+        return false;
+    const field = target.delivery?.fields?.[DELIVERY_CORRELATION_FIELD] ??
+        delivery.fields?.[DELIVERY_CORRELATION_FIELD];
+    return field === DELIVERY_CORRELATION_PLACEHOLDER;
+}
+//# sourceMappingURL=ManualJobAdmission.js.map