@kontourai/survey 0.4.2 → 0.4.4

package/dist/src/to-surface.js

@@ -43,14 +43,7 @@ export function buildSurveyTrustInput(input, options = {}) {
             },
             metadata: {
                 ...projection.metadata,
-                survey: {
-                    ...(isRecord(projection.metadata?.survey) ? projection.metadata.survey : {}),
-                    rawSourceId: rawSource.id,
-                    extractionId: extraction.id,
-                    candidateSetId: candidateSet.id,
-                    candidateId: candidate.id,
-                    reviewOutcomeId: review?.id,
-                },
+                survey: buildSurveyMetadata({ projection, rawSource, extraction, candidateSet, candidate, review }),
             },
         };
         if (options.reviewProofs && review) {
@@ -68,6 +61,7 @@ export function buildSurveyTrustInput(input, options = {}) {
             });
         }
         claims.push(claim);
+        const policyStandard = policyStandardFields(rawSource);
         evidence.push({
             id: evidenceId,
             claimId: projection.id,
@@ -75,7 +69,7 @@ export function buildSurveyTrustInput(input, options = {}) {
             method: projection.evidenceMethod ?? "extraction",
             sourceRef: rawSource.sourceRef,
             sourceLocator: extraction.locator,
-            excerptOrSummary: extraction.excerpt ?? `Extracted ${projection.fieldOrBehavior} from ${rawSource.kind}.`,
+            excerptOrSummary: evidenceExcerptOrSummary({ rawSource, extraction, projection, policyStandard }),
             observedAt: rawSource.observedAt,
             collectedBy: projection.collectedBy,
             integrityRef: rawSource.checksum,
@@ -83,15 +77,13 @@ export function buildSurveyTrustInput(input, options = {}) {
                 ...rawSource.metadata,
                 ...extraction.metadata,
                 ...candidate.metadata,
+                ...(policyStandard ? { policyStandard } : {}),
                 rawSourceKind: rawSource.kind,
                 locatorScheme: rawSource.locatorScheme,
                 confidence: candidate.confidence ?? extraction.confidence,
             },
         });
         const rationale = review?.rationale ?? candidateSet.rationale;
-        const comfortZoneNote = review?.withinComfortZone === false
-            ? `[outside comfort zone] ${review.comfortZoneNote ?? "reviewer flagged this as outside their comfort zone"}`
-            : undefined;
         events.push({
             id: `${projection.id}.event.${status}`,
             claimId: projection.id,
@@ -101,9 +93,10 @@ export function buildSurveyTrustInput(input, options = {}) {
             evidenceIds: review?.evidenceIds?.length ? review.evidenceIds : [evidenceId],
             createdAt: review?.reviewedAt ?? input.generatedAt,
             verifiedAt: status === "verified" || status === "assumed" ? review?.reviewedAt ?? input.generatedAt : undefined,
-            notes: [rationale, comfortZoneNote].filter(Boolean).join(" | ") || undefined,
+            notes: rationale,
         });
     }
+    projectInterpretations({ input, rawSources, claims, evidence, events });
     if (input.escalations) {
         const claimIds = new Set(claims.map((c) => c.id));
         for (const escalation of input.escalations) {
@@ -135,6 +128,199 @@ export function buildSurveyTrustInput(input, options = {}) {
         events,
     };
 }
+function projectInterpretations(input) {
+    const interpretations = input.input.interpretations
+        ? [...indexById(input.input.interpretations, "interpretation").values()]
+        : [];
+    if (interpretations.length === 0)
+        return;
+    const claimsById = new Map(input.claims.map((claim) => [claim.id, claim]));
+    for (const interpretation of interpretations) {
+        const projection = buildInterpretationProjection({
+            interpretation,
+            rawSources: input.rawSources,
+            claims: input.claims,
+            claimsById,
+            input: input.input,
+        });
+        input.evidence.push(projection.evidence);
+        input.events.push(projection.event);
+        attachInterpretationClaimMetadata({
+            claim: projection.claim,
+            interpretation,
+            anchorSource: projection.anchorSource,
+            evidenceId: projection.evidence.id,
+        });
+    }
+}
+function buildInterpretationProjection(input) {
+    const anchorSource = requirePolicyStandardAnchor(input.interpretation, input.rawSources);
+    const claim = resolveInterpretationClaim(input.interpretation, input.claims, input.input);
+    if (!input.claimsById.has(claim.id)) {
+        throw new Error(`Interpretation ${input.interpretation.id} resolved unknown claim ${claim.id}`);
+    }
+    const policyStandard = policyStandardFields(anchorSource);
+    const evidence = createInterpretationAnchorEvidence({
+        interpretation: input.interpretation,
+        claim,
+        anchorSource,
+        policyStandard,
+    });
+    return {
+        claim,
+        anchorSource,
+        evidence,
+        event: createInterpretationEvent({
+            interpretation: input.interpretation,
+            claim,
+            evidenceId: evidence.id,
+        }),
+    };
+}
+function requirePolicyStandardAnchor(interpretation, rawSources) {
+    const anchorSource = requireMapValue(rawSources, interpretation.anchorsToSourceId, "interpretation anchor raw source");
+    if (anchorSource.kind !== "policy-standard") {
+        throw new Error(`Interpretation ${interpretation.id} anchors to raw source ${anchorSource.id}, but expected policy-standard source`);
+    }
+    return anchorSource;
+}
+function createInterpretationAnchorEvidence(input) {
+    return {
+        id: `${input.interpretation.id}.evidence.anchor`,
+        claimId: input.claim.id,
+        evidenceType: "policy_rule",
+        method: "anchoring",
+        sourceRef: input.anchorSource.sourceRef,
+        sourceLocator: input.interpretation.ruleLocator,
+        excerptOrSummary: input.policyStandard?.inlineText ?? `Anchored policy-standard reading at ${input.interpretation.ruleLocator}.`,
+        observedAt: input.anchorSource.observedAt,
+        collectedBy: input.interpretation.actor,
+        integrityRef: input.anchorSource.checksum,
+        metadata: {
+            ...input.anchorSource.metadata,
+            ...(input.interpretation.metadata ? { interpretation: input.interpretation.metadata } : {}),
+            ...(input.policyStandard ? { policyStandard: input.policyStandard } : {}),
+            rawSourceKind: input.anchorSource.kind,
+            locatorScheme: input.anchorSource.locatorScheme,
+            anchorsToSourceId: input.anchorSource.id,
+            ruleLocator: input.interpretation.ruleLocator,
+        },
+    };
+}
+function createInterpretationEvent(input) {
+    return {
+        id: `${input.interpretation.id}.event`,
+        claimId: input.claim.id,
+        status: input.claim.status ?? "proposed",
+        actor: input.interpretation.actor,
+        method: "survey-interpretation",
+        evidenceIds: [input.evidenceId],
+        createdAt: input.interpretation.recordedAt,
+        verifiedAt: input.claim.status === "verified" || input.claim.status === "assumed" ? input.interpretation.recordedAt : undefined,
+        notes: input.interpretation.reading,
+    };
+}
+function attachInterpretationClaimMetadata(input) {
+    const claimMetadata = isRecord(input.claim.metadata) ? input.claim.metadata : {};
+    const surveyMetadata = isRecord(claimMetadata.survey) ? claimMetadata.survey : {};
+    const existingInterpretations = Array.isArray(surveyMetadata.interpretations) ? surveyMetadata.interpretations : [];
+    input.claim.metadata = {
+        ...claimMetadata,
+        survey: {
+            ...surveyMetadata,
+            interpretations: [
+                ...existingInterpretations,
+                {
+                    interpretationId: input.interpretation.id,
+                    ruleLocator: input.interpretation.ruleLocator,
+                    reading: input.interpretation.reading,
+                    actor: input.interpretation.actor,
+                    recordedAt: input.interpretation.recordedAt,
+                    ...(input.interpretation.metadata ? { metadata: input.interpretation.metadata } : {}),
+                    edges: [
+                        {
+                            type: "appliesTo",
+                            targetKind: "claim",
+                            targetId: input.claim.id,
+                        },
+                        {
+                            type: "anchorsTo",
+                            targetKind: "rawSource",
+                            targetId: input.anchorSource.id,
+                            evidenceId: input.evidenceId,
+                            ruleLocator: input.interpretation.ruleLocator,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
+function resolveInterpretationClaim(interpretation, claims, input) {
+    if (interpretation.appliesToClaimId) {
+        const claim = claims.find((item) => item.id === interpretation.appliesToClaimId);
+        if (!claim) {
+            throw new Error(`Interpretation ${interpretation.id} references unknown claim ${interpretation.appliesToClaimId}`);
+        }
+        if (interpretation.appliesToTarget) {
+            const targetClaim = resolveInterpretationTargetClaim(interpretation, claims, input);
+            if (targetClaim.id !== claim.id) {
+                throw new Error(`Interpretation ${interpretation.id} has conflicting appliesToClaimId ${claim.id} and appliesToTarget ${interpretation.appliesToTarget} resolved to ${targetClaim.id}`);
+            }
+        }
+        return claim;
+    }
+    if (!interpretation.appliesToTarget) {
+        throw new Error(`Interpretation ${interpretation.id} needs appliesToClaimId or appliesToTarget`);
+    }
+    return resolveInterpretationTargetClaim(interpretation, claims, input);
+}
+function resolveInterpretationTargetClaim(interpretation, claims, input) {
+    const candidateSetIdsByTarget = new Set(input.candidateSets
+        .filter((candidateSet) => candidateSet.target === interpretation.appliesToTarget)
+        .map((candidateSet) => candidateSet.id));
+    const matches = input.claims.filter((claim) => claim.fieldOrBehavior === interpretation.appliesToTarget ||
+        candidateSetIdsByTarget.has(claim.candidateSetId));
+    const uniqueClaimIds = [...new Set(matches.map((claim) => claim.id))];
+    if (uniqueClaimIds.length === 0) {
+        throw new Error(`Interpretation ${interpretation.id} target ${interpretation.appliesToTarget} did not match any claim`);
+    }
+    if (uniqueClaimIds.length > 1) {
+        throw new Error(`Interpretation ${interpretation.id} target ${interpretation.appliesToTarget} is ambiguous across claims: ${uniqueClaimIds.join(", ")}`);
+    }
+    const claim = claims.find((item) => item.id === uniqueClaimIds[0]);
+    if (!claim)
+        throw new Error(`Interpretation ${interpretation.id} resolved unknown claim ${uniqueClaimIds[0]}`);
+    return claim;
+}
+function buildSurveyMetadata(input) {
+    const producerSurveyMetadata = isRecord(input.projection.metadata?.survey) ? input.projection.metadata.survey : {};
+    const producerCandidateMetadata = isRecord(producerSurveyMetadata.candidate) ? producerSurveyMetadata.candidate : {};
+    return {
+        ...producerSurveyMetadata,
+        rawSourceId: input.rawSource.id,
+        extractionId: input.extraction.id,
+        candidateSetId: input.candidateSet.id,
+        candidateId: input.candidate.id,
+        reviewOutcomeId: input.review?.id,
+        ...(input.candidate.rejectionReason !== undefined
+            ? {
+                candidate: {
+                    ...producerCandidateMetadata,
+                    rejectionReason: input.candidate.rejectionReason,
+                },
+            }
+            : {}),
+        ...(input.review?.withinComfortZone === false
+            ? {
+                comfortZone: {
+                    withinComfortZone: false,
+                    ...(input.review.comfortZoneNote ? { note: input.review.comfortZoneNote } : {}),
+                },
+            }
+            : {}),
+    };
+}
 function statusFor(input) {
     if (input.review)
         return input.review.status;
@@ -173,12 +359,39 @@ function selectReview(reviews, candidateId) {
     return reviews.find((review) => review.candidateId === candidateId) ?? reviews.find((review) => !review.candidateId);
 }
 function evidenceTypeFor(rawSource) {
+    if (rawSource.kind === "policy-standard")
+        return "policy_rule";
     if (rawSource.kind === "uploaded-document")
         return "document_citation";
     if (rawSource.kind === "web-page")
         return "crawl_observation";
     return "attestation";
 }
+function policyStandardFields(rawSource) {
+    const metadata = rawSource.metadata?.policyStandard;
+    const metadataRecord = isRecord(metadata) ? metadata : {};
+    const inlineText = rawSource.inlineText ?? stringValue(metadataRecord.inlineText) ?? stringValue(metadataRecord.text);
+    const standardVersion = rawSource.standardVersion ?? stringValue(metadataRecord.standardVersion) ?? stringValue(metadataRecord.version);
+    const paragraphRef = rawSource.paragraphRef ?? stringValue(metadataRecord.paragraphRef);
+    const reference = stringValue(metadataRecord.reference);
+    if (!inlineText && !standardVersion && !paragraphRef && !reference)
+        return undefined;
+    return {
+        inlineText,
+        standardVersion,
+        paragraphRef,
+        reference,
+    };
+}
+function evidenceExcerptOrSummary(input) {
+    if (input.rawSource.kind === "policy-standard" && input.policyStandard?.inlineText) {
+        return input.policyStandard.inlineText;
+    }
+    return input.extraction.excerpt ?? `Extracted ${input.projection.fieldOrBehavior} from ${input.rawSource.kind}.`;
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
 function eventMethodFor(status, candidateSet) {
     if (status === "verified")
         return "survey-review";

package/dist/src/types.d.ts

@@ -1,5 +1,5 @@
 import type { ConfidenceBasis, DerivationEdge, EvidenceMethod, EvidenceType, ImpactLevel, TrustStatus } from "@kontourai/surface";
-export type RawSourceKind = "uploaded-document" | "web-page" | "api-record" | "manual-entry";
+export type RawSourceKind = "uploaded-document" | "web-page" | "api-record" | "manual-entry" | "policy-standard";
 export type LocatorScheme = "pdf" | "text" | "html" | "structured-field";
 export interface RawSource {
     id: string;
@@ -9,6 +9,9 @@ export interface RawSource {
     fetchedAt?: string;
     checksum?: string;
     locatorScheme: LocatorScheme;
+    inlineText?: string;
+    standardVersion?: string;
+    paragraphRef?: string;
     metadata?: Record<string, unknown>;
 }
 export interface Extraction {
@@ -31,6 +34,7 @@ export interface Candidate {
     value: unknown;
     confidence?: number;
     sourceRank?: number;
+    rejectionReason?: string;
     metadata?: Record<string, unknown>;
 }
 export interface CandidateSet {
@@ -67,6 +71,17 @@ export interface EscalationRecord {
     resolvedBy?: string;
     metadata?: Record<string, unknown>;
 }
+export interface Interpretation {
+    id: string;
+    appliesToTarget?: string;
+    appliesToClaimId?: string;
+    anchorsToSourceId: string;
+    ruleLocator: string;
+    reading: string;
+    actor: string;
+    recordedAt: string;
+    metadata?: Record<string, unknown>;
+}
 export interface ClaimTarget {
     id: string;
     candidateSetId: string;
@@ -100,4 +115,5 @@ export interface SurveyInput {
     reviewOutcomes: ReviewOutcome[];
     claims: ClaimTarget[];
     escalations?: EscalationRecord[];
+    interpretations?: Interpretation[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,7 +19,9 @@
   "exports": {
     ".": "./dist/src/index.js",
     "./fixtures/public-field-review": "./dist/fixtures/public-field-review.js",
-    "./fixtures/corrected-document-candidates": "./dist/fixtures/corrected-document-candidates.js"
+    "./fixtures/corrected-document-candidates": "./dist/fixtures/corrected-document-candidates.js",
+    "./fixtures/public-directory-review-resource": "./dist/fixtures/public-directory-review-resource.js",
+    "./fixtures/regulated-document-review-resource": "./dist/fixtures/regulated-document-review-resource.js"
   },
   "files": [
     "dist/examples/",
@@ -31,8 +33,12 @@
     "build": "rm -rf dist && tsc",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test dist/tests/*.test.js",
-    "verify": "node scripts/check-content-boundary.cjs && npm run typecheck && npm test",
-    "check:content-boundary": "node scripts/check-content-boundary.cjs"
+    "verify": "node scripts/check-content-boundary.cjs && npm run typecheck && npm test && npm run check:review-workbench",
+    "check:content-boundary": "node scripts/check-content-boundary.cjs",
+    "check:review-workbench": "npm run check:review-workbench:static",
+    "check:review-workbench:static": "npm run build && node scripts/check-review-workbench.cjs",
+    "setup:repo-hooks": "node scripts/setup-repo-hooks.cjs",
+    "validate:repo-hooks": "node scripts/validate-repo-hooks.cjs"
   },
   "dependencies": {
     "@kontourai/surface": "^0.5.1"