diff --git a/app/api/0pt/internal/er/candidates/route.ts b/app/api/0pt/internal/er/candidates/route.ts index 20ddf64..e22689c 100644 --- a/app/api/0pt/internal/er/candidates/route.ts +++ b/app/api/0pt/internal/er/candidates/route.ts @@ -3,22 +3,40 @@ import { NextRequest, NextResponse } from "next/server"; import { verifyInternalServiceToken } from "@/src/auth/internal-token"; import { EntityResolutionService, - type ErCandidateRequest, type ErCandidateResult, type ErRecord, } from "@/src/er/entity-resolution-service"; +import { parseErCandidateRequest } from "@/src/er/request-validation"; import { siaxErrorResponse } from "@/src/http/siax-error-response"; -import { SiaxError } from "@/src/platform/errors"; const er = new EntityResolutionService(); +function rawStringField(record: ErRecord, field: string): string | undefined { + const value = record.fields[field]; + if (value === null || value === undefined) return undefined; + const normalized = String(value).trim(); + return normalized || undefined; +} + +function stableIdentifier(record: ErRecord, field: string): string | undefined { + const value = rawStringField(record, field); + if (!value) return undefined; + const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, ""); + return normalized || undefined; +} + +function countryIdentifier(record: ErRecord): string | undefined { + const value = rawStringField(record, "registration_country") ?? rawStringField(record, "country"); + if (!value) return undefined; + const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, ""); + return normalized || undefined; +} + /** - * Company identity hard rule. - * - * LEI is globally scoped. National registration numbers are not: they may only - * force a decision when both records also carry the same registration country. - * Negative identity evidence dominates positive evidence within the same - * identifier scope. Formatting punctuation is ignored for stable identifiers. + * Company identity hard rule v3. + * - LEI is globally scoped. + * - National registration numbers are comparable only within the same country. + * - Any comparable stable-ID conflict dominates every positive match. */ er.registerHardRule({ rule_id: "0pt.company.stable-identifiers.v3", @@ -45,27 +63,6 @@ er.registerHardRule({ }, }); -function rawStringField(record: ErRecord, field: string): string | undefined { - const value = record.fields[field]; - if (value === null || value === undefined) return undefined; - const normalized = String(value).trim(); - return normalized || undefined; -} - -function stableIdentifier(record: ErRecord, field: string): string | undefined { - const value = rawStringField(record, field); - if (!value) return undefined; - const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, ""); - return normalized || undefined; -} - -function countryIdentifier(record: ErRecord): string | undefined { - const value = rawStringField(record, "registration_country") ?? rawStringField(record, "country"); - if (!value) return undefined; - const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, ""); - return normalized || undefined; -} - function assertInternal(request: NextRequest): NextResponse | undefined { if (verifyInternalServiceToken(request.headers)) return undefined; return NextResponse.json( @@ -74,101 +71,9 @@ function assertInternal(request: NextRequest): NextResponse | undefined { ); } -function finiteThreshold(value: unknown, field: string, fallback: number): number { - if (value === undefined) return fallback; - const parsed = Number(value); - if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", `${field} must be a finite number between 0 and 1`); - } - return parsed; -} - -function parseRequest(raw: unknown): ErCandidateRequest { - if (!raw || typeof raw !== "object" || Array.isArray(raw)) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", "JSON object body is required"); - } - const body = raw as Record; - const tenantId = typeof body.tenant_id === "string" ? body.tenant_id.trim() : ""; - const projectId = typeof body.project_id === "string" ? body.project_id.trim() : ""; - if (!tenantId) throw new SiaxError("INVALID_REQUEST", "0pt.er", "tenant_id is required"); - if (!projectId) throw new SiaxError("INVALID_REQUEST", "0pt.er", "project_id is required"); - - if (!Array.isArray(body.records) || body.records.length < 2 || body.records.length > 5_000) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", "records must contain between 2 and 5000 items"); - } - if ( - !Array.isArray(body.blocking_fields) || - body.blocking_fields.length === 0 || - !body.blocking_fields.every((v) => typeof v === "string" && v.trim().length > 0) - ) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", "blocking_fields must be a non-empty string array"); - } - if (!Array.isArray(body.compare_fields) || body.compare_fields.length === 0) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", "compare_fields must be a non-empty array"); - } - - const records: ErRecord[] = body.records.map((value, index) => { - if (!value || typeof value !== "object" || Array.isArray(value)) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", `records[${index}] must be an object`); - } - const record = value as Record; - if (typeof record.record_id !== "string" || !record.record_id.trim()) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", `records[${index}].record_id is required`); - } - if (!record.fields || typeof record.fields !== "object" || Array.isArray(record.fields)) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", `records[${index}].fields must be an object`); - } - return { record_id: record.record_id.trim(), fields: record.fields as ErRecord["fields"] }; - }); - - if (new Set(records.map((record) => record.record_id)).size !== records.length) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", "record_id values must be unique within the request"); - } - - const compareFields = body.compare_fields.map((value, index) => { - if (!value || typeof value !== "object" || Array.isArray(value)) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", `compare_fields[${index}] must be an object`); - } - const item = value as Record; - if (typeof item.field !== "string" || !item.field.trim()) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", `compare_fields[${index}].field is required`); - } - const weight = item.weight === undefined ? undefined : Number(item.weight); - if (weight !== undefined && (!Number.isFinite(weight) || weight < 0 || weight > 100)) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", `compare_fields[${index}].weight must be between 0 and 100`); - } - return { field: item.field.trim(), ...(weight !== undefined ? { weight } : {}) }; - }); - - const autoThreshold = finiteThreshold(body.auto_match_threshold, "auto_match_threshold", 0.9); - const reviewThreshold = finiteThreshold(body.review_threshold, "review_threshold", 0.6); - if (reviewThreshold >= autoThreshold) { - throw new SiaxError("INVALID_REQUEST", "0pt.er", "review_threshold must be lower than auto_match_threshold"); - } - - return { - tenant_id: tenantId, - project_id: projectId, - records, - blocking_fields: (body.blocking_fields as string[]).map((value) => value.trim()), - compare_fields: compareFields, - auto_match_threshold: autoThreshold, - review_threshold: reviewThreshold, - ...(typeof body.correlation_id === "string" && body.correlation_id.trim() - ? { correlation_id: body.correlation_id.trim() } - : {}), - }; -} - /** * Company/Work boundary: fuzzy similarity is candidate evidence, never identity truth. - * - * The generic ER engine supports score-based `match` for domains that explicitly - * choose that policy. This internal company endpoint is stricter: only a product - * hard rule backed by stable identifiers may emit `match`. Any score-only match - * is downgraded to `pending_review`, matching the review-gated Python candidate - * layer used by Work/CRM/FIT0 and preventing two ER paths from disagreeing about - * whether fuzzy similarity is sufficient to link an organization. + * Only product hard rules backed by stable identifiers may emit `match` here. */ export function enforceCompanyReviewBoundary(result: ErCandidateResult): ErCandidateResult { const pairs = result.pairs.map((pair) => @@ -188,7 +93,7 @@ export async function POST(request: NextRequest) { if (denied) return denied; try { - const result = er.generateCandidates(parseRequest(await request.json())); + const result = er.generateCandidates(parseErCandidateRequest(await request.json())); return NextResponse.json(enforceCompanyReviewBoundary(result)); } catch (error: unknown) { return siaxErrorResponse(error);