pixivflow 3.1.0 → 3.3.0

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,126 @@
+/**
+ * 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 resolves the target
+ * from configuration instead, optionally narrowed by `account`.
+ */
+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.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: the target is discovered from configuration — every enabled plan's
+     * selected target that actually wires manual candidate-search delivery.
+     */
+    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,310 @@
+"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);
+        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: the target is discovered from configuration — every enabled plan's
+     * selected target that actually wires manual candidate-search delivery.
+     */
+    resolveTarget(config, targetId) {
+        if (targetId !== undefined) {
+            const plans = (config.schedules ?? []).filter((plan) => plan.enabled !== false &&
+                (0, schedules_1.selectScheduleTargets)(config.targets, plan).some((target) => target.id === targetId));
+            if (plans.length === 0) {
+                throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 404, {
+                    message: 'unknown target',
+                    detail: { reason: 'unknown_target', target_id: targetId },
+                });
+            }
+            if (plans.length !== 1) {
+                throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 409, {
+                    message: 'ambiguous target',
+                    detail: { reason: 'ambiguous_target', target_id: targetId },
+                });
+            }
+            const plan = plans[0];
+            const target = (0, schedules_1.selectScheduleTargets)(config.targets, plan).find((item) => item.id === targetId && Boolean(item.id));
+            if (!target || !target.id) {
+                throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 404, {
+                    message: 'unknown target',
+                    detail: { reason: 'unknown_target', target_id: targetId },
+                });
+            }
+            this.assertManualWiring(config, target, target.id, true);
+            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

package/dist/scheduler/ManualJobService.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The generic job surface: `$defs/Task` in, `$defs/Job` out.
+ *
+ * This is an ADAPTER, not a second execution system. Everything it does is a
+ * translation on top of the one durable ledger:
+ *   - admission      -> `ManualJobAdmission` (shared with the legacy refetch path)
+ *   - read model     -> `JobView` (`buildJobProjection` + `buildProtocolJob`)
+ *   - cancellation   -> `cancelConsumerJob` (one transaction)
+ *   - events/ack     -> `JobEventStream` (projection of `delivery_events`)
+ *
+ * Identity is the consumer's idempotency key, which IS the durable
+ * `manual_request_id`; `job_id` IS the slot id. A replay from either entry
+ * point therefore converges on the same job, and no second slot or delivery can
+ * be created for the same key.
+ */
+import type { StandaloneConfig } from '../config';
+import type { Database } from '../storage/Database';
+import { JobEventQuery } from './JobEventStream';
+import { ProtocolAckResult, ProtocolCapabilities, ProtocolEventPage, ProtocolJob } from './JobFacade';
+import { ManualJobAdmission } from './ManualJobAdmission';
+import type { JobHandlers } from './ScheduleTriggerServer';
+export interface ManualJobServiceDeps {
+    database: Database;
+    /** The live config snapshot (the trigger server always reads the newest). */
+    config(): StandaloneConfig;
+    /** The shared admission path — the same instance the legacy shim uses. */
+    admission: ManualJobAdmission;
+    /** Injected clock, for tests. */
+    now?(): number;
+}
+export declare class ManualJobService implements JobHandlers {
+    private readonly deps;
+    private readonly events;
+    constructor(deps: ManualJobServiceDeps);
+    private now;
+    private viewDeps;
+    capabilities(): ProtocolCapabilities;
+    /** Create or replay the one work item this idempotency key owns. */
+    submitJob(body: unknown): {
+        job: ProtocolJob;
+        replayed: boolean;
+    };
+    jobStatus(jobId: string): ProtocolJob | null;
+    jobsByIdempotencyKey(idempotencyKey: string): ProtocolJob[];
+    /** `GET /jobs/:jobId/events` — the durable stream, reconciled from the ledger. */
+    jobEvents(jobId: string, query: JobEventQuery): ProtocolEventPage;
+    /** `POST /jobs/:jobId/events/ack` — O(1) durable cursor write, never a job mutation. */
+    ackJobEvents(jobId: string, body: unknown): ProtocolAckResult;
+    /**
+     * Idempotent: cancelling an already-terminal job reports its current
+     * projection instead of failing. `cancelConsumerJob` owns the one transaction
+     * that terminalises the work and stops further deliveries.
+     */
+    cancelJob(jobId: string): ProtocolJob;
+    private viewBySlotId;
+}
+//# sourceMappingURL=ManualJobService.d.ts.map