@kontourai/survey 0.4.2 → 0.4.4

package/README.md

@@ -11,7 +11,7 @@ ingestion platform:
 - `buildSurveyTrustInput` projects those records into `@kontourai/surface`
   `TrustInput`;
 - Surface owns Claim, Subject, Claim Type, Evidence, Status, Claim Dependency,
-  TrustInput, trust reporting, console projections, and downstream transparency.
+  TrustInput, trust reporting, and public reporting surfaces.
 
 The first success criterion is that generic corrected-document and public-field
 fixtures can pass through Survey and produce valid Surface reports without
@@ -64,6 +64,45 @@ const trustInput = validateTrustInput(buildSurveyTrustInput(surveyInput));
 const report = buildTrustReport(trustInput);
 ```
 
+## Contributor checks
+
+Install the repo-owned Git hooks once per clone:
+
+```bash
+npm run setup:repo-hooks
+```
+
+The setup command is idempotent. It sets this repo's local `core.hooksPath` to
+`.githooks` and does not require global Git configuration.
+
+Use the same checks directly when you want to validate hook drift or package
+health before pushing:
+
+```bash
+npm run validate:repo-hooks
+npm run verify
+```
+
+The committed pre-push hook runs both commands from the repo root.
+
+## Producer validation path
+
+Survey producers validate through public `@kontourai/survey` and
+`@kontourai/surface` contracts:
+
+1. Build Survey observations with source, extraction, candidate, review, and
+   claim records.
+2. Call `buildSurveyTrustInput` to project the Survey records into Surface
+   `TrustInput`.
+3. Call Surface `validateTrustInput` on the projected input.
+4. Optionally call public Surface report APIs such as `buildTrustReport` to
+   inspect claims, evidence, status, gaps, and metadata.
+
+Keep producer operational state outside Survey. Queue status, reviewer form
+state, retries, source caches, and product policy decisions belong in the
+producer's own data model. Survey carries only the portable source,
+extraction, candidate, review, and claim projection records needed by Surface.
+
 ## Raw sources
 
 Use raw-source helpers when a producer wants Survey to shape source identity
@@ -113,10 +152,103 @@ const surveyInput = new SurveyInputBuilder({ source: "example-producer:run-1" })
 ```
 
 Survey exports `uploadedDocumentSource`, `apiRecordSource`, `webPageSource`,
-and `manualEntrySource`. Producer-provided `id` values are preserved; otherwise
-Survey derives a stable id from source kind and `sourceRef`. Bare checksum
-values are normalized to `sha256:<value>`, while already-prefixed checksum
-values are preserved. Producer metadata is copied through to Surface evidence.
+`manualEntrySource`, and `policyStandardSource`. Producer-provided `id` values
+are preserved; otherwise Survey derives a stable id from source kind and
+`sourceRef`. Bare checksum values are normalized to `sha256:<value>`, while
+already-prefixed checksum values are preserved. Producer metadata is copied
+through to Surface evidence.
+
+Use `policyStandardSource` when the observed material is the applied standard
+itself. It records `inlineText`, `standardVersion`, and optional `paragraphRef`
+on the `RawSource` and projects to Surface `policy_rule` evidence by default.
+Survey only preserves the producer-applied standard text/version; it does not
+decide whether that standard is correct for the producer's domain.
+
+## Interpretation records
+
+Use `addInterpretation` when a producer records how an actor read a
+`policy-standard` paragraph for one claim. Interpretations are flat provenance
+records with an `appliesTo` edge to a claim and an `anchorsTo` edge to a
+policy-standard raw source; they are not nested claim derivations or rejection
+reasons.
+
+```ts
+import {
+  apiRecordSource,
+  buildSurveyTrustInput,
+  fieldObservation,
+  policyStandardSource,
+  SurveyInputBuilder,
+} from "@kontourai/survey";
+
+const observedAt = new Date().toISOString();
+const standard = policyStandardSource({
+  id: "source.example.policy-standard.rule-1",
+  sourceRef: "policy-standard://example/rules/2026#rule-1",
+  observedAt,
+  inlineText: "A producer reading must cite the applied rule paragraph.",
+  standardVersion: "2026.1",
+  paragraphRef: "rule-1",
+});
+
+const surveyInput = new SurveyInputBuilder({ source: "example-producer:run-1" })
+  .addRawSource(standard)
+  .addObservation(fieldObservation({
+    id: "observation.example.policy-application",
+    field: "policyApplication.status",
+    value: "DOCUMENTED",
+    rawSource: apiRecordSource({
+      id: "source.example.application-record",
+      sourceRef: "example-records://application/application-1",
+      observedAt,
+      checksum: "application-1",
+    }),
+    extraction: {
+      target: "policyApplication.status",
+      locator: "json:$.policyApplication.status",
+      extractor: "example-extractor",
+      extractedAt: observedAt,
+    },
+    claim: {
+      id: "claim.example.policy-application",
+      subjectType: "example.application",
+      subjectId: "application-1",
+      surface: "example.review",
+      claimType: "policy-application.status",
+      impactLevel: "medium",
+      collectedBy: "example-extractor",
+    },
+  }))
+  .addInterpretation({
+    id: "interpretation.example.rule-1",
+    appliesToClaimId: "claim.example.policy-application",
+    anchorsToSourceId: standard.id,
+    ruleLocator: "text:paragraph=rule-1",
+    reading: "The producer read rule 1 as applying to the claim.",
+    actor: "producer-operator",
+    recordedAt: observedAt,
+  })
+  .build();
+
+const trustInput = buildSurveyTrustInput(surveyInput);
+```
+
+Projection emits a normal Surface verification event with
+`method: "survey-interpretation"`, the existing `claimId`, and anchor
+`evidenceIds`. Because current Surface verification events reject unsupported
+keys, typed edge details are preserved on the projected claim at
+`metadata.survey.interpretations[]`. The anchor evidence uses
+`evidenceType: "policy_rule"`, `method: "anchoring"`, the interpretation
+`ruleLocator` as `sourceLocator`, and the policy-standard text/version metadata.
+
+## Review resources
+
+Survey also exports producer-neutral `ReviewItem`, `ReviewCandidate`, and
+`ReviewDecision` TypeScript resource shapes for review UI and adapter fixtures.
+They use `apiVersion`, `kind`, `metadata`, `spec`, and `status` fields while
+mapping back to the existing Survey record layer. See
+[`docs/review-resource-contract.md`](docs/review-resource-contract.md) for
+field ownership, mapping hints, and the `ReviewSession` non-goal.
 
 ## Field observations
 
@@ -185,11 +317,13 @@ assumed.
 
 ## Source-of-authority observations
 
-Use `sourceOfAuthorityObservation` when a producer treats the raw source as
-authoritative for the extracted target: an official publication, registration
-platform page, policy document, contract record, or system-of-record response.
-The helper does not decide whether the source is truly authoritative. It
-enforces record discipline around the producer's declared source posture.
+Use `sourceOfAuthorityObservationBuilder` when a producer treats the raw source
+as authoritative for the extracted target: an official publication,
+registration platform page, policy document, contract record, or
+system-of-record response. The builder does not decide whether the source is
+truly authoritative. It guides producers through the source, extraction,
+source-authority posture, review outcome, and claim fields that make the
+declared source posture auditable.
 
 Verified or assumed source-of-authority observations require:
 
@@ -207,14 +341,14 @@ reserved for actor, credential, role, organization, policy, or system authority.
 ```ts
 import {
   buildSurveyTrustInput,
-  sourceOfAuthorityObservation,
+  sourceOfAuthorityObservationBuilder,
   SurveyInputBuilder,
   uploadedDocumentSource,
 } from "@kontourai/survey";
 
 const observedAt = new Date().toISOString();
 const rawSource = uploadedDocumentSource({
-  sourceRef: "https://rules.example.test/standard-deduction.pdf",
+  sourceRef: "https://rules.example.test/thresholds.pdf",
   observedAt,
   checksum: "abc123",
   locatorScheme: "pdf",
@@ -223,35 +357,36 @@ const rawSource = uploadedDocumentSource({
 const surveyInput = new SurveyInputBuilder({
   source: "rule-producer:run-1",
 })
-  .addObservation(sourceOfAuthorityObservation({
-    id: "rule.standard-deduction.mfj.2026",
-    field: "federal.standardDeduction.mfj.2026",
-    value: 30000,
-    sourceAuthority: {
+  .addObservation(sourceOfAuthorityObservationBuilder({
+    id: "rule.threshold.primary.2026",
+    field: "regulatedRule.threshold.primary.2026",
+    value: 1200,
+  })
+    .withSourceAuthority({
       authorityClass: "official_publication",
       scope: {
-        jurisdiction: "federal",
+        jurisdiction: "example",
         productArea: "regulated-rule",
-        taxYear: 2026,
+        effectiveYear: 2026,
       },
       sourceVersion: "2026",
       declaredBy: "rule-producer",
-    },
-    rawSource,
-    extraction: {
+    })
+    .fromSource(rawSource)
+    .withExtraction({
       confidence: 0.94,
-      locator: "pdf:page=12;table=standard-deduction;row=mfj",
+      locator: "pdf:page=12;table=thresholds;row=primary",
       extractor: "rule-producer",
       extractedAt: observedAt,
-    },
-    reviewOutcome: {
+    })
+    .withReviewOutcome({
       status: "verified",
       actor: "rule-reviewer",
       reviewedAt: new Date().toISOString(),
-    },
-    claim: {
+    })
+    .forClaim({
       subjectType: "regulated-rule",
-      subjectId: "federal:standard-deduction:mfj:2026",
+      subjectId: "example:threshold:primary:2026",
       surface: "regulated.rules",
       claimType: "regulated.rule-value",
       status: "verified",
@@ -259,17 +394,24 @@ const surveyInput = new SurveyInputBuilder({
       evidenceType: "policy_rule",
       evidenceMethod: "extraction",
       collectedBy: "rule-producer",
-    },
-  }))
+    })
+    .build())
   .build();
 
 const trustInput = buildSurveyTrustInput(surveyInput);
 ```
 
-Contextual claims such as "this return position is compliant" or "this camp is
-eligible for an 8-year-old in June" are not source-of-authority observations.
+`sourceOfAuthorityObservation` remains available as the lower-level object
+factory when a producer already has the full observation input assembled.
+
+Contextual claims such as "this submission is compliant" or "this record is
+eligible for a specific requester" are not source-of-authority observations.
 They are Surface claims with Claim Dependencies on source-of-authority claims
-and other product facts. The vertical product owns that domain logic.
+and other producer facts. The producer owns that domain logic.
+
+For the reusable producer workflow, including manual confirmation state,
+source references, Survey review outcomes, and Surface report boundaries, see
+[Source-Authority Review Pattern](docs/source-authority-review-pattern.md).
 
 ## Reviewed candidate resolutions
 
@@ -285,6 +427,13 @@ This is useful for corrected documents, source-of-truth choices, and review
 queues where losing candidates should remain visible for transparency rather
 than disappearing from the trust trail.
 
+Candidates may include an optional `rejectionReason` when a producer wants to
+record why a non-selected alternative was superseded or rejected. Survey
+preserves that producer-provided rationale on the candidate and projects it to
+Surface claim `metadata.survey.candidate.rejectionReason` for that candidate
+while preserving producer-provided `metadata.survey` keys. Survey does not rank
+candidates, choose winners, or define rejection policy.
+
 ## Reviewed current/proposed resolutions
 
 Use `reviewedCurrentProposedResolution` when a producer has exactly two
@@ -467,6 +616,12 @@ shared candidate set while rejecting conflicting duplicate ids. Duplicate
 conflict checks assume Survey records are JSON-shaped data, which is the same
 shape expected by Surface validation and reports.
 
+If an observation candidate includes `rejectionReason`, `candidateReviewRecord`
+preserves it in the shared candidate set. Use this only for producer-authored
+rationale about a candidate that the producer already treats as non-selected,
+superseded, or rejected; it does not affect selected candidate behavior or
+status projection.
+
 A candidate set with status `"conflict"` represents a Survey-side Candidate
 Conflict before review has resolved which candidate should win. When no review
 outcome overrides it, `buildSurveyTrustInput` projects the claim to Surface
@@ -507,6 +662,30 @@ so producers can store or recompute the exact canonical proof material used for
 the anchor. Producer metadata is not part of the canonical payload; any
 non-portable context belongs outside the hash, such as anchor metadata.
 
+The canonical payload is the portable review proof contract. It contains:
+
+| Field | Purpose |
+| --- | --- |
+| `schemaVersion` / `proof.schema` / `proof.schemaVersion` | Stable Survey review proof schema identity. |
+| `proof.packageName` / `proof.packageVersion` | Review proof contract identity. `proof.packageVersion` is the proof contract version, not the npm package release version. Package releases do not change canonical proof hashes unless this explicit proof contract version or another canonical field changes. |
+| `proof.issuer` | Survey producer identity, derived from the claim collector. |
+| `proof.producer` | Extraction producer identity, derived from the extractor id. |
+| `proof.issuedAt` | Proof envelope time, derived from review time, then claim update time, then extraction time. |
+| `proof.subject` | Claim identity: claim id, candidate set id, reviewed candidate id, subject, surface, claim type, and field/behavior. If the claim also names a candidate id, it must match the reviewed candidate id. |
+| `proof.sourcePayload` / `rawSource.checksum` | Source payload identity, ref, and producer-supplied checksum when present. |
+| `extraction` | Extracted target, value, locator, excerpt, extractor, confidence, and extraction time. |
+| `candidate` / `candidateSet` | Candidate identity/value plus the ordered candidate set, selected candidate, status, and rationale. |
+| `reviewOutcome` | Review decision/status, actor, review time, rationale, and evidence ids. |
+| `claim` | Projected claim identity, status/value, impact, evidence method, derivation links, collector, actor, and event method. |
+
+To recompute the anchor value, rebuild the same canonical payload from the
+reviewed Survey records, call `canonicalReviewProofJson(payload)`, and compute
+SHA-256 over that JSON. The result should equal
+`claim.currentIntegrityAnchor.value`. The Surface anchor remains generic:
+`kind: "hash"`, `algorithm: "sha256"`, `verificationStatus: "unverified"`, no
+Survey-specific anchor metadata, and a source/time pointer for display. Claims
+without a selected review outcome are not anchored by `{ reviewProofs: true }`.
+
 When the Surface projection proof option is enabled, `buildSurveyTrustInput`
 will attach the same kind of anchor to the projected reviewed claim:
 
@@ -519,6 +698,12 @@ trail in the canonical payload. It does not authenticate an actor, sign the
 payload, or prove the real-world truth of the claim. Non-goals include JWT/JWS
 signing, key management, a transparency log, and any veracity guarantee.
 
+JWT-adjacent words in the payload are process-envelope vocabulary, not a v0 JWT
+implementation. `issuer` identifies the Survey producer for recomputation,
+`subject` identifies the claim being reviewed, and `issuedAt` records the review
+proof time. Audience restrictions, expiry, cryptographic signing, key discovery,
+and legal non-repudiation are deferred concepts for a future signed envelope.
+
 ## Computed values
 
 Computed values are normal `ClaimTarget` entries in `claims`. Producers should
@@ -656,8 +841,9 @@ in Surface with a `candidate-escalation` event.
 Use `withinComfortZone: false` on a `ReviewOutcome` when the reviewer is
 recording a decision outside their domain expertise or is flagging that the
 conclusion requires a different authority to confirm. The flag and optional
-`comfortZoneNote` are carried forward to the Surface verification event `notes`
-so the reviewer chain sees the signal without having to read into the rationale.
+`comfortZoneNote` are carried forward as structured Survey metadata on the
+projected Surface claim at `metadata.survey.comfortZone`. Verification event
+`notes` carry the normal review or candidate-set rationale only.
 
 ```ts
 reviewOutcome: {
@@ -670,6 +856,32 @@ reviewOutcome: {
 },
 ```
 
+## Learning projections
+
+Use `buildSurveyLearningProjections(input)` when producer or review tooling needs
+workflow/evaluation signals without changing Surface `TrustInput`.
+
+```ts
+import {
+  buildSurveyLearningProjections,
+  buildSurveyTrustInput,
+} from "@kontourai/survey";
+
+const learning = buildSurveyLearningProjections(surveyInput);
+const trustInput = buildSurveyTrustInput(surveyInput);
+```
+
+Learning projections are product-neutral `learning.*` records. Survey currently
+emits `learning.comfort-zone` from structured `ReviewOutcome.withinComfortZone
+=== false` data and `learning.escalation` from unresolved `EscalationRecord`s,
+including unattached records that producer tooling can route but Surface cannot
+attach to a claim event.
+
+These projections are producer/review workflow and evaluation signals. They are
+not claims about truth or veracity, not Surface claim status, not evidence, and
+not verification events. Calling `buildSurveyLearningProjections` does not alter
+`buildSurveyTrustInput`, trust status derivation, or escalation event projection.
+
 ## Product Boundary
 
 Survey does not crawl pages, parse PDFs, rank candidates, decide review policy,

package/dist/examples/review-workbench/downstream-public-directory-adapter.d.ts

@@ -0,0 +1,3 @@
+import { type ReviewItem } from "../../src/review-resource.js";
+import type { DownstreamPublicDirectoryProposal } from "../../fixtures/downstream-public-directory-proposal.js";
+export declare function downstreamPublicDirectoryProposalToReviewItem(proposal: DownstreamPublicDirectoryProposal, field?: string): ReviewItem;

package/dist/examples/review-workbench/downstream-public-directory-adapter.js

@@ -0,0 +1,262 @@
+import { reviewResourceApiVersion } from "../../src/review-resource.js";
+export function downstreamPublicDirectoryProposalToReviewItem(proposal, field = firstProposedField(proposal)) {
+    const diff = proposal.proposedChanges[field];
+    if (!diff) {
+        throw new Error(`Proposal ${proposal.id} does not include proposed field ${field}.`);
+    }
+    const reviewState = reviewStateForProposal(proposal.status, field);
+    const currentCandidate = currentReviewCandidate(proposal, field, diff, reviewState.selectedRole);
+    const proposedCandidate = proposedReviewCandidate(proposal, field, diff, reviewState.selectedRole);
+    return {
+        apiVersion: reviewResourceApiVersion,
+        kind: "ReviewItem",
+        metadata: reviewItemMetadata(proposal, field),
+        spec: {
+            target: field,
+            candidateSetStatus: reviewState.candidateSetStatus,
+            ...optionalSelectedCandidateId(reviewState.selectedCandidateId),
+            rationale: proposal.reviewerNotes ?? downstreamDecisionRationale(proposal.status),
+            candidates: [currentCandidate, proposedCandidate],
+            producerPolicy: {
+                owner: "downstream-adapter",
+                sourceShape: "public-directory-current-proposed-proposal",
+                proposalStatus: proposal.status,
+                ...rejectionPolicyForProposal(proposal.status),
+                approvedFields: proposal.appliedFields,
+                feedbackTags: proposal.feedbackTags,
+                opaquePolicyMetadata: {
+                    priority: proposal.priority,
+                    crawlTrigger: proposal.crawlTrigger,
+                    communityScope: proposal.communitySlug,
+                },
+            },
+            projection: selectedProjection(reviewState.selectedRole, currentCandidate, proposedCandidate),
+        },
+        status: {
+            observedCandidateCount: 2,
+            ...optionalSelectedCandidateId(reviewState.selectedCandidateId),
+            reviewDecisionName: proposal.reviewedAt
+                ? `public-directory-${proposal.publicRecordId}-${field}-${proposal.id}-decision`
+                : undefined,
+        },
+    };
+}
+function reviewItemMetadata(proposal, field) {
+    return {
+        name: `public-directory-${proposal.publicRecordId}-${field}-${proposal.id}`,
+        uid: proposal.id,
+        labels: {
+            domain: "public-directory",
+            field,
+        },
+        annotations: {
+            "survey.kontourai.io/adapter": "downstream-public-directory",
+            "survey.kontourai.io/source-shape": "sanitized-copied-proposal",
+        },
+        producer: {
+            displayName: proposal.recordName ?? "Example Public Record",
+            slug: proposal.recordSlug ?? proposal.publicRecordId,
+        },
+    };
+}
+function firstProposedField(proposal) {
+    const [field] = Object.keys(proposal.proposedChanges);
+    if (!field) {
+        throw new Error(`Proposal ${proposal.id} does not include proposed changes.`);
+    }
+    return field;
+}
+function currentFieldSource(proposal, field) {
+    const fieldSources = proposal.recordData?.fieldSources;
+    if (!isRecord(fieldSources)) {
+        return {};
+    }
+    const source = fieldSources[field];
+    return isRecord(source)
+        ? {
+            excerpt: typeof source.excerpt === "string" ? source.excerpt : undefined,
+            sourceUrl: typeof source.sourceUrl === "string" ? source.sourceUrl : undefined,
+            approvedAt: typeof source.approvedAt === "string" ? source.approvedAt : undefined,
+        }
+        : {};
+}
+function currentReviewCandidate(proposal, field, diff, selectedRole) {
+    const currentSource = currentFieldSource(proposal, field);
+    const observedAt = currentSource.approvedAt ?? proposal.reviewedAt ?? proposal.createdAt;
+    return reviewCandidate({
+        proposal,
+        field,
+        diff,
+        role: "current",
+        value: diff.old,
+        sourceId: `public-directory:source:${proposal.publicRecordId}:${field}:current`,
+        sourceRef: currentSource.sourceUrl ?? `current-record:${proposal.publicRecordId}:${field}`,
+        observedAt,
+        excerpt: currentSource.excerpt ?? `Current ${field} value from the reviewed public record.`,
+        extractor: "downstream-current-record",
+        extractedAt: observedAt,
+        confidence: 1,
+        sourceRank: selectedRole === "current" ? 1 : 2,
+    });
+}
+function proposedReviewCandidate(proposal, field, diff, selectedRole) {
+    return reviewCandidate({
+        proposal,
+        field,
+        diff,
+        role: "proposed",
+        value: diff.new,
+        sourceId: `public-directory:source:${proposal.publicRecordId}:${field}:${proposal.id}`,
+        sourceRef: diff.sourceUrl ?? proposal.sourceUrl,
+        observedAt: proposal.createdAt,
+        excerpt: diff.excerpt ?? `Proposed ${field} value from downstream extraction.`,
+        extractor: proposal.extractionModel,
+        extractedAt: proposal.createdAt,
+        confidence: diff.confidence,
+        sourceRank: selectedRole === "proposed" ? 1 : 2,
+    });
+}
+function reviewCandidate(args) {
+    const id = candidateId(args.field, args.role);
+    const extractionId = `public-directory:extraction:${args.proposal.publicRecordId}:${args.field}:${args.proposal.id}:${args.role}`;
+    const claimId = candidateClaimId(args);
+    return {
+        id,
+        role: args.role,
+        value: args.value,
+        confidence: args.confidence,
+        sourceRank: args.sourceRank,
+        source: candidateSource(args),
+        locator: candidateLocator(args),
+        extraction: candidateExtraction(args, extractionId),
+        claimTarget: candidateClaimTarget(args, claimId),
+        projection: candidateProjection(args, id, extractionId, claimId),
+        producer: candidateProducerMetadata(args),
+    };
+}
+function reviewStateForProposal(status, field) {
+    if (status === "APPROVED") {
+        return {
+            candidateSetStatus: "resolved",
+            selectedRole: "proposed",
+            selectedCandidateId: candidateId(field, "proposed"),
+        };
+    }
+    if (status === "REJECTED") {
+        return {
+            candidateSetStatus: "resolved",
+            selectedRole: "current",
+            selectedCandidateId: candidateId(field, "current"),
+        };
+    }
+    return {
+        candidateSetStatus: "needs-review",
+    };
+}
+function optionalSelectedCandidateId(selectedCandidateId) {
+    return selectedCandidateId ? { selectedCandidateId } : {};
+}
+function rejectionPolicyForProposal(status) {
+    return status === "REJECTED"
+        ? { rejectionSemantics: "selected-current-keeps-existing-value-and-rejects-proposed-candidate" }
+        : {};
+}
+function selectedProjection(selectedRole, currentCandidate, proposedCandidate) {
+    if (selectedRole === "current") {
+        return currentCandidate.projection;
+    }
+    if (selectedRole === "proposed") {
+        return proposedCandidate.projection;
+    }
+    return undefined;
+}
+function candidateSource(args) {
+    return {
+        sourceId: args.sourceId,
+        sourceRef: args.sourceRef,
+        kind: args.sourceRef.startsWith("http") ? "web-page" : "manual-entry",
+        observedAt: args.observedAt,
+        fetchedAt: args.role === "proposed" ? args.proposal.crawlCompletedAt ?? args.observedAt : args.observedAt,
+        locatorScheme: args.sourceRef.startsWith("http") ? "html" : "structured-field",
+    };
+}
+function candidateLocator(args) {
+    return {
+        scheme: args.sourceRef.startsWith("http") ? "html" : "structured-field",
+        locator: `field:${args.field}`,
+        excerpt: args.excerpt,
+    };
+}
+function candidateExtraction(args, extractionId) {
+    return {
+        extractionId,
+        target: args.field,
+        confidence: args.confidence,
+        extractor: args.extractor,
+        extractedAt: args.extractedAt,
+    };
+}
+function candidateClaimTarget(args, claimId) {
+    return {
+        claimId,
+        subjectType: "public-record.entity",
+        subjectId: args.proposal.publicRecordId,
+        surface: "public-directory.profile",
+        claimType: args.role === "current" ? "public-data.field" : "public-data.field-candidate",
+        fieldOrBehavior: args.field,
+        impactLevel: "medium",
+        evidenceType: "source_excerpt",
+        evidenceMethod: args.role === "current" ? "attestation" : "extraction",
+        collectedBy: args.extractor,
+    };
+}
+function candidateProjection(args, candidateIdValue, extractionId, claimId) {
+    return {
+        rawSourceId: args.sourceId,
+        extractionId,
+        candidateSetId: `public-directory:candidates:${args.proposal.publicRecordId}:${args.field}:${args.proposal.id}`,
+        candidateId: candidateIdValue,
+        reviewOutcomeId: rejectedCurrentReviewOutcomeId(args),
+        claimId,
+    };
+}
+function candidateProducerMetadata(args) {
+    const selectedWhenRejected = rejectedCurrentReviewOutcomeId(args) ? { selectedWhenRejected: true } : {};
+    return {
+        proposalId: args.proposal.id,
+        proposalStatus: args.proposal.status,
+        previousValue: args.diff.old,
+        diffMode: args.diff.mode,
+        ...selectedWhenRejected,
+        sourceAuthority: {
+            authorityClass: "public-directory-listing",
+            declaredBy: args.role === "current" ? "Downstream reviewed record" : "Downstream extraction pipeline",
+            scope: `${args.field} field on ${args.proposal.publicRecordId}`,
+        },
+    };
+}
+function candidateClaimId(args) {
+    return args.role === "current"
+        ? `public-directory.${args.proposal.publicRecordId}.${args.field}.current`
+        : `public-directory.${args.proposal.publicRecordId}.${args.field}.${args.proposal.id}.proposed`;
+}
+function rejectedCurrentReviewOutcomeId(args) {
+    return args.role === "current" && args.proposal.status === "REJECTED"
+        ? `public-directory:review:${args.proposal.publicRecordId}:${args.field}:${args.proposal.id}:keep-current`
+        : undefined;
+}
+function candidateId(field, role) {
+    return `public-directory:candidate:${field}:${role}`;
+}
+function downstreamDecisionRationale(status) {
+    if (status === "APPROVED") {
+        return "Downstream reviewer accepted the proposed value.";
+    }
+    if (status === "REJECTED") {
+        return "Downstream reviewer rejected the proposed value and kept the current value.";
+    }
+    return "Downstream proposal is awaiting review.";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}