dsh-scout 0.9.2 → 0.9.4

package/dist/model.d.ts

@@ -15,7 +15,7 @@ export type Decision = 'PROCEED' | 'VERIFY' | 'STOP';
 export declare const DECISION_REASON_CODES: readonly ["identity", "unresolved", "missing_dimension", "proceed"];
 export type DecisionReasonCode = typeof DECISION_REASON_CODES[number];
 export declare function isDecisionReasonCode(value: unknown): value is DecisionReasonCode;
-export declare const EVENT_TYPES: readonly ["case_started", "source_added", "claim_added", "identity_verified", "claim_verified", "case_exported", "case_imported", "case_rehydrated"];
+export declare const EVENT_TYPES: readonly ["case_started", "source_added", "source_updated", "claim_added", "identity_verified", "claim_verified", "case_exported", "case_imported", "case_rehydrated"];
 export type ScoutEventType = typeof EVENT_TYPES[number];
 export interface ScoutEvent {
     eventId: string;
@@ -45,6 +45,8 @@ export interface ScoutClaim {
     sourceIds: string[];
     nextAction: string;
     confidenceNote: string;
+    /** Optional model-written interview question; the only claim field that feeds the question list. */
+    interviewQuestion?: string;
     history?: Array<{
         status: ClaimStatus;
         evidenceLevel: EvidenceLevel;
@@ -53,6 +55,22 @@ export interface ScoutClaim {
         confidenceNote: string;
     }>;
 }
+/** The five identity fields a caller asserts when verifying the subject. */
+export declare const IDENTITY_FIELDS: readonly ["legalEntity", "registrationNumber", "registeredRegion", "legalRepresentative", "brandRelationship"];
+export type IdentityField = typeof IDENTITY_FIELDS[number];
+/**
+ * Identity confidence tiers.
+ *
+ * - `verified`: an E3 registry/regulator/official-filing source backs the
+ *   registration number itself (the strongest claim a due-diligence tool can make).
+ * - `corroborated`: no E3 registration evidence, but at least two independent
+ *   sources cover every identity field consistently (typically 工商 aggregators).
+ *   This is a *decision-useful* tier, never presented as official verification.
+ * - `needs_verification`: anything weaker.
+ */
+export declare const IDENTITY_STATUSES: readonly ["verified", "corroborated", "needs_verification"];
+export type IdentityStatus = typeof IDENTITY_STATUSES[number];
+export declare function isIdentityStatus(value: unknown): value is IdentityStatus;
 export interface ScoutCase {
     schemaVersion: 'dsh-scout.case.v0';
     caseId: string;
@@ -67,7 +85,9 @@ export interface ScoutCase {
         legalRepresentative?: string;
         brandRelationship?: string;
         identitySourceIds: string[];
-        identityStatus: 'verified' | 'needs_verification';
+        identityStatus: IdentityStatus;
+        /** Optional per-field provenance: which sources support which identity field. */
+        identityEvidence?: Partial<Record<IdentityField, string[]>>;
     };
     role: {
         title: string;
@@ -105,7 +125,9 @@ export declare function inferEvidenceLevel(url: string | null, type: SourceType,
 };
 /**
  * Normalize a source URL for deduplication: trim, lowercase the host, drop a
- * trailing slash and any fragment. Empty or unparsable URLs return `undefined`.
+ * trailing slash, the fragment, and known campaign/tracking query parameters.
+ * Query parameters that can select the document itself (e.g. `?id=42`) are kept.
+ * Empty or unparsable URLs return `undefined`.
  */
 export declare function normalizeSourceUrl(value: string | null | undefined): string | undefined;
 /** Find a source by normalized URL (trim + trailing-slash + host case insensitive). */
@@ -118,14 +140,31 @@ export declare function verifyClaim(scoutCase: ScoutCase, input: {
     nextAction: string;
     confidenceNote: string;
 }): ScoutCase;
-export declare function verifyIdentity(scoutCase: ScoutCase, input: {
+export interface IdentityVerificationInput {
     legalEntity: string;
     registrationNumber: string;
     registeredRegion: string;
     legalRepresentative: string;
     brandRelationship: string;
     sourceIds: string[];
-}, authoritySuffixes?: readonly string[]): ScoutCase;
+    /**
+     * Optional per-field provenance. When provided, every field must be covered
+     * and the tier is derived from what actually supports the registration
+     * number: an E3 authoritative source there means `verified`, otherwise
+     * two-or-more independent sources covering all fields means `corroborated`.
+     */
+    fieldSources?: Partial<Record<IdentityField, string[]>>;
+}
+/**
+ * Verify the legal subject.
+ *
+ * Reaching `verified` requires an E3 registry/regulator/official-filing source
+ * that backs the registration number — a page that merely mentions the company
+ * does not count. Without that, two independent sources covering every identity
+ * field yield `corroborated`: decision-useful and honestly labelled, never
+ * presented as official verification.
+ */
+export declare function verifyIdentity(scoutCase: ScoutCase, input: IdentityVerificationInput, authoritySuffixes?: readonly string[]): ScoutCase;
 /** Pure decision reason code recomputed from the subject and claims, without stored state. */
 export declare function explainDecision(scoutCase: ScoutCase): DecisionReasonCode;
 export declare function decideCase(scoutCase: ScoutCase, opts?: {
@@ -141,14 +180,28 @@ export interface DimensionCoverage {
 export declare function computeCoverage(scoutCase: ScoutCase): DimensionCoverage[];
 /**
  * Derive a deduplicated, prioritized interview question list from the case.
- * Order: pending next actions, missing required dimensions, untouched
- * dimensions, then the case's own curated questions. The curated questions
- * reserve their full quota, so an uninvestigated case cannot crowd them out of
- * the 12-item cap.
+ *
+ * Only two sources feed the list now:
+ * - explicit `claim.interviewQuestion` values (what the model actually decided
+ *   is worth asking), ordered by claim impact;
+ * - one dimension-default question for missing required dimensions, dimensions
+ *   with open claims, and untouched dimensions.
+ *
+ * `claim.nextAction` is deliberately excluded — it is a research instruction
+ * ("verify this claim"), not something a candidate can ask in an interview.
+ * The case's curated questions reserve their full quota and are always kept.
  */
 export declare function generateInterviewQuestions(scoutCase: ScoutCase, opts?: {
     language?: ScoutLanguage;
 }): string[];
+/**
+ * Stage-based evidence report (0.9.4 readability rework).
+ *
+ * The body speaks the reader's language: no E-codes, no source ids, no internal
+ * status enums, and no item rendered five times. Sections follow the decision
+ * stages (verdict -> subject -> confirmed -> open -> risks -> questions -> gap),
+ * with a technical audit trail in the appendices.
+ */
 export declare function renderReport(scoutCase: ScoutCase, opts?: {
     language?: ScoutLanguage;
 }): string;