@kontourai/survey 1.3.0 → 1.5.0

package/dist/src/schema-mapping.js

@@ -20,6 +20,7 @@
  *      so that resolveInquiry can resolve across systems with weakest-link
  *      capping.
  */
+import { AUTO_ACCEPT_ACTOR, AUTO_ACCEPT_WITHIN_COMFORT_ZONE, getProducerProposal, meetsAutoAcceptThreshold, projectProposalsToCandidateSet, } from "./producer-profile.js";
 import { buildSurveyTrustBundle } from "./to-surface.js";
 // ---------------------------------------------------------------------------
 // Canonical pair key
@@ -84,10 +85,7 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
         const subjectId = mappingSubjectId(first.sourceField, first.targetField);
         const candidateSetId = `schema-mapping.candidate-set.${pairKey}`;
         const claimId = `schema-mapping.claim.${pairKey}`;
-        // Detect conflict: proposals disagree on relation
-        const relations = new Set(pairProposals.map((p) => p.relation));
-        const status = relations.size > 1 ? "conflict" : "needs-review";
-        const candidates = pairProposals.map((proposal) => {
+        const candidateSetProposals = pairProposals.map((proposal) => {
             // Use the source system's RawSource for this extraction
             const rawSource = sourceById.get(proposal.sourceField.system) ?? rawSources[0];
             const extractionId = `schema-mapping.extraction.${proposal.id}`;
@@ -120,7 +118,7 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
             };
             extractions.push(extraction);
             return {
-                id: `schema-mapping.candidate.${proposal.id}`,
+                candidateId: `schema-mapping.candidate.${proposal.id}`,
                 extractionId,
                 value: {
                     relation: proposal.relation,
@@ -128,45 +126,41 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
                     conversion: proposal.conversion,
                 },
                 confidence: proposal.confidence,
+                equivalenceKey: proposal.relation,
                 metadata: {
-                    schemaMappingProposal: {
-                        proposalId: proposal.id,
-                        sourceField: proposal.sourceField,
-                        targetField: proposal.targetField,
-                        relation: proposal.relation,
-                        conversion: proposal.conversion,
-                        evidence: proposal.evidence,
-                        confidence: proposal.confidence,
-                        rationale: proposal.rationale,
-                        proposedBy: proposal.proposedBy,
-                        proposedAt: proposal.proposedAt,
-                    },
+                    proposalId: proposal.id,
+                    sourceField: proposal.sourceField,
+                    targetField: proposal.targetField,
+                    relation: proposal.relation,
+                    conversion: proposal.conversion,
+                    evidence: proposal.evidence,
+                    confidence: proposal.confidence,
+                    rationale: proposal.rationale,
+                    proposedBy: proposal.proposedBy,
+                    proposedAt: proposal.proposedAt,
                 },
             };
         });
-        const candidateSet = {
-            id: candidateSetId,
-            target: `schema-mapping:${pairKey}`,
-            candidates,
-            selectedCandidateId: status !== "conflict" ? candidates[0]?.id : undefined,
-            status,
-            rationale: status === "conflict"
-                ? `Proposals disagree on relation for pair ${pairKey}: ${[...relations].join(", ")}`
-                : `${candidates.length} proposal(s) agree on relation "${first.relation}" for pair ${pairKey}.`,
-            metadata: {
+        const { candidateSet, candidates } = projectProposalsToCandidateSet(`schema-mapping:${pairKey}`, candidateSetProposals, {
+            candidateSetId,
+            candidateSetMetadata: {
                 schemaMapping: {
                     pairKey,
                     sourceField: first.sourceField,
                     targetField: first.targetField,
                 },
             },
-        };
+            candidateSetRationale: (status, proposals) => status === "conflict"
+                ? `Proposals disagree on relation for pair ${pairKey}: ${[...new Set(proposals.map((p) => p.equivalenceKey))].join(", ")}`
+                : `${proposals.length} proposal(s) agree on relation "${first.relation}" for pair ${pairKey}.`,
+        });
+        candidateSet.selectedCandidateId = candidateSet.status !== "conflict" ? candidates[0]?.id : undefined;
         candidateSets.push(candidateSet);
         // Auto-accept policy: non-conflicting proposals above threshold → assumed
         let autoReviewStatus;
-        if (status !== "conflict" && options.autoAcceptMinConfidence !== undefined) {
+        if (candidateSet.status !== "conflict" && options.autoAcceptMinConfidence !== undefined) {
             const topConfidence = Math.max(...pairProposals.map((p) => p.confidence));
-            if (topConfidence >= options.autoAcceptMinConfidence) {
+            if (meetsAutoAcceptThreshold(topConfidence, options.autoAcceptMinConfidence)) {
                 autoReviewStatus = "assumed";
             }
         }
@@ -180,10 +174,10 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
                 candidateSetId,
                 candidateId: selectedCandidate.id,
                 status: autoReviewStatus,
-                actor: "auto-accept-policy",
+                actor: AUTO_ACCEPT_ACTOR,
                 reviewedAt: generatedAt,
                 rationale: `Auto-accepted: confidence ${selectedCandidate.confidence} >= threshold ${options.autoAcceptMinConfidence}`,
-                withinComfortZone: true,
+                withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE,
             });
         }
         // Project to ClaimTarget (subjectType "system-field", fieldOrBehavior "maps-to")
@@ -191,14 +185,14 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
             const review = reviewOutcomes.find((r) => r.candidateSetId === candidateSetId);
             const claimStatus = review
                 ? review.status
-                : (status === "conflict" ? "disputed" : undefined);
+                : (candidateSet.status === "conflict" ? "disputed" : undefined);
             const claimTarget = {
                 id: claimId,
                 candidateSetId,
                 candidateId: selectedCandidate.id,
                 subjectType: "system-field",
                 subjectId: subjectId,
-                surface: "schema-mapping.profile",
+                facet: "schema-mapping.profile",
                 claimType: "schema-mapping.field-link",
                 fieldOrBehavior: "maps-to",
                 value: {
@@ -266,7 +260,7 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
     const rawSources = [];
     const seenSources = new Set();
     for (const rm of accepted) {
-        const meta = rm.selectedCandidate.metadata?.schemaMappingProposal;
+        const meta = getProducerProposal(rm.selectedCandidate);
         const sourceField = meta?.sourceField ?? rm.proposal.sourceField;
         const sourceId = `schema-mapping.source.${sourceField.system}`;
         if (!seenSources.has(sourceId)) {
@@ -290,7 +284,7 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
     const reviewOutcomes = [];
     const claims = [];
     for (const rm of accepted) {
-        const meta = rm.selectedCandidate.metadata?.schemaMappingProposal;
+        const meta = getProducerProposal(rm.selectedCandidate);
         const sourceField = meta?.sourceField ?? rm.proposal.sourceField;
         const targetField = meta?.targetField ?? rm.proposal.targetField;
         const relation = (meta?.relation ?? rm.proposal.relation);
@@ -342,7 +336,7 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
             candidateId: rm.selectedCandidate.id,
             subjectType: "system-field",
             subjectId,
-            surface: "schema-mapping.profile",
+            facet: "schema-mapping.profile",
             claimType: "schema-mapping.field-link",
             fieldOrBehavior: "maps-to",
             value: { relation, sourceField, targetField, conversion },
@@ -379,7 +373,7 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
     // subject and back-references the mapping claim via mappingClaimId.
     const identityLinks = [];
     for (const rm of accepted) {
-        const meta = rm.selectedCandidate.metadata?.schemaMappingProposal;
+        const meta = getProducerProposal(rm.selectedCandidate);
         const sourceField = meta?.sourceField ?? rm.proposal.sourceField;
         const targetField = meta?.targetField ?? rm.proposal.targetField;
         const relation = (meta?.relation ?? rm.proposal.relation);

package/dist/src/source-of-authority-observation.js

@@ -1,4 +1,5 @@
 import { buildObservation } from "./observation-helper.js";
+import { assertReviewOutcomeDiscipline } from "./producer-discipline.js";
 export class SourceOfAuthorityObservationBuilder {
     state;
     constructor(args) {
@@ -115,15 +116,11 @@ function assertVerifiedPosture(input) {
     if (!input.extraction.locator) {
         throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without a source locator`);
     }
-    if (!input.reviewOutcome) {
-        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without a review outcome`);
-    }
-    if (!input.reviewOutcome.actor) {
-        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without review actor authority`);
-    }
-    if (!input.reviewOutcome.reviewedAt) {
-        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without reviewedAt`);
-    }
+    assertReviewOutcomeDiscipline({
+        subject: `Source-of-authority observation ${input.id}`,
+        status,
+        review: input.reviewOutcome,
+    });
 }
 function claimStatus(claimStatusValue, reviewStatus) {
     return claimStatusValue ?? reviewStatus;

package/dist/src/to-surface.js

@@ -1,4 +1,5 @@
 import { buildReviewProofAnchor } from "./review-proof.js";
+import { assertReviewOutcomeDiscipline } from "./producer-discipline.js";
 export function buildSurveyTrustBundle(input, options = {}) {
     const rawSources = indexById(input.rawSources, "raw source");
     const extractions = indexById(input.extractions, "extraction");
@@ -23,7 +24,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
             id: projection.id,
             subjectType: projection.subjectType,
             subjectId: projection.subjectId,
-            surface: projection.surface,
+            facet: projection.facet,
             claimType: projection.claimType,
             fieldOrBehavior: projection.fieldOrBehavior,
             value: claimValue,
@@ -120,7 +121,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
         }
     }
     return {
-        schemaVersion: 3,
+        schemaVersion: 5,
         source: input.source,
         claims,
         evidence,
@@ -334,15 +335,11 @@ function statusFor(input) {
     return "proposed";
 }
 function assertProducerDiscipline(input) {
-    if ((input.status === "verified" || input.status === "assumed") && !input.review) {
-        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without a review outcome`);
-    }
-    if ((input.status === "verified" || input.status === "assumed") && !input.review?.actor) {
-        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without review actor authority`);
-    }
-    if ((input.status === "verified" || input.status === "assumed") && !input.review?.reviewedAt) {
-        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without reviewedAt`);
-    }
+    assertReviewOutcomeDiscipline({
+        subject: `Claim ${input.projection.id}`,
+        status: input.status,
+        review: input.review,
+    });
     if (input.rawSource.kind !== "manual-entry" && !input.extraction.locator) {
         throw new Error(`Claim ${input.projection.id} needs a source locator for ${input.rawSource.kind}`);
     }

package/dist/src/types.d.ts

@@ -111,7 +111,12 @@ export interface ClaimTarget {
     candidateId?: string;
     subjectType: string;
     subjectId: string;
-    surface: string;
+    /**
+     * Producer-defined grouping or namespace for this claim (Hachure schema 5,
+     * surface@2.0.0: Claim.surface -> Claim.facet). Projected onto the emitted
+     * Claim's `facet` field by {@link buildSurveyTrustBundle}.
+     */
+    facet: string;
     claimType: string;
     fieldOrBehavior: string;
     value?: unknown;

package/dist/src/vocabulary.d.ts

@@ -11,22 +11,64 @@ import type { ConfidenceBasis, ImpactLevel, TrustStatus } from "@kontourai/surfa
  */
 export declare function stableId(parts: ReadonlyArray<string | number>): string;
 /**
- * A product's Survey/Surface vocabulary: the subject type and surface it
+ * A product's Survey/Surface vocabulary: the subject type and facet it
  * projects onto, its claim-type names, and its decision-effect names. Generic
  * over the caller's claim-type and decision-effect key maps so the concrete
  * string literals stay visible to callers.
+ *
+ * `facet` mirrors Surface's `Claim.facet` (Hachure schema 5 facet rename:
+ * `Claim.surface` -> `Claim.facet`, surface@2.0.0). The now-deprecated
+ * `surface` property is kept, mirroring `facet`, for one release so existing
+ * readers of `.surface` do not break; read `.facet` going forward.
  */
 export interface ProductVocabularyDefinition<TClaimTypes extends Readonly<Record<string, string>>, TDecisionEffects extends Readonly<Record<string, string>>> {
     readonly subjectType: string;
+    readonly facet: string;
+    /**
+     * @deprecated Renamed to {@link ProductVocabularyDefinition.facet} (Hachure
+     * schema 5 facet rename: `Claim.surface` -> `Claim.facet`). Mirrors `facet`
+     * for one release; read `.facet` going forward.
+     */
     readonly surface: string;
     readonly claimTypes: TClaimTypes;
     readonly decisionEffects: TDecisionEffects;
 }
+/**
+ * Input accepted by {@link defineProductVocabulary}: `facet` is the
+ * canonical name; the deprecated `surface` name is still accepted for one
+ * release as a read-compat alias (Hachure schema 5 facet rename). Exactly
+ * one of `facet` / `surface` is required — the union below is what makes
+ * "at least one of these two" a compile-time requirement rather than a
+ * runtime-only check.
+ */
+export type ProductVocabularyInput<TClaimTypes extends Readonly<Record<string, string>>, TDecisionEffects extends Readonly<Record<string, string>>> = {
+    readonly subjectType: string;
+    readonly claimTypes: TClaimTypes;
+    readonly decisionEffects: TDecisionEffects;
+} & ({
+    readonly facet: string;
+    readonly surface?: string;
+} | {
+    readonly facet?: undefined;
+    /**
+     * @deprecated Renamed to `facet` (Hachure schema 5 facet rename:
+     * `Claim.surface` -> `Claim.facet`). Accepted for one release; using it
+     * without also passing `facet` emits a single deprecation warning per
+     * process. Prefer `facet`.
+     */
+    readonly surface: string;
+});
 /**
  * Defines a product vocabulary as a deep-frozen, discoverable value that a
  * `currentProposedReviewItem` caller can pass instead of loose top-level
- * constants. Returns the same shape it received, frozen so callers cannot
- * mutate a shared vocabulary at runtime.
+ * constants. Returns the same shape it received (plus the mirrored
+ * deprecated `surface` alias — see {@link ProductVocabularyDefinition}),
+ * frozen so callers cannot mutate a shared vocabulary at runtime.
+ *
+ * Accepts either the canonical `facet` option or the deprecated `surface`
+ * option (not both required — `facet` wins when both are supplied, and
+ * using `surface` alone emits a single deprecation warning per process; see
+ * {@link ProductVocabularyInput}).
  *
  * The type parameters carry the `const` modifier, so `claimTypes` and
  * `decisionEffects` string properties keep their literal types whether or
@@ -40,7 +82,7 @@ export interface ProductVocabularyDefinition<TClaimTypes extends Readonly<Record
  * `peerDependencies.typescript` and `docs/upgrade-guide.md`); this is a
  * types-only floor and does not affect JavaScript consumers.
  */
-export declare function defineProductVocabulary<const TClaimTypes extends Readonly<Record<string, string>>, const TDecisionEffects extends Readonly<Record<string, string>>>(definition: ProductVocabularyDefinition<TClaimTypes, TDecisionEffects>): ProductVocabularyDefinition<TClaimTypes, TDecisionEffects>;
+export declare function defineProductVocabulary<const TClaimTypes extends Readonly<Record<string, string>>, const TDecisionEffects extends Readonly<Record<string, string>>>(definition: ProductVocabularyInput<TClaimTypes, TDecisionEffects>): ProductVocabularyDefinition<TClaimTypes, TDecisionEffects>;
 export interface ConfidenceBasisForReviewInput {
     readonly status: TrustStatus;
     readonly impactLevel: ImpactLevel;

package/dist/src/vocabulary.js

@@ -16,11 +16,35 @@ export function stableId(parts) {
         .toLowerCase())
         .join(".");
 }
+let warnedLegacyVocabularySurfaceOnce = false;
+function warnLegacyVocabularySurfaceOnce() {
+    if (warnedLegacyVocabularySurfaceOnce)
+        return;
+    warnedLegacyVocabularySurfaceOnce = true;
+    console.warn("[@kontourai/survey] deprecated: defineProductVocabulary's \"surface\" option is renamed to " +
+        "\"facet\" (Hachure schema 5 facet rename: Claim.surface -> Claim.facet, surface@2.0.0). " +
+        "Pass \"facet\" instead of \"surface\"; \"surface\" is accepted for one release as a read-compat alias.");
+}
+function resolveFacet(definition) {
+    if (definition.facet !== undefined)
+        return definition.facet;
+    if (definition.surface !== undefined) {
+        warnLegacyVocabularySurfaceOnce();
+        return definition.surface;
+    }
+    throw new Error('defineProductVocabulary requires "facet" (or deprecated "surface")');
+}
 /**
  * Defines a product vocabulary as a deep-frozen, discoverable value that a
  * `currentProposedReviewItem` caller can pass instead of loose top-level
- * constants. Returns the same shape it received, frozen so callers cannot
- * mutate a shared vocabulary at runtime.
+ * constants. Returns the same shape it received (plus the mirrored
+ * deprecated `surface` alias — see {@link ProductVocabularyDefinition}),
+ * frozen so callers cannot mutate a shared vocabulary at runtime.
+ *
+ * Accepts either the canonical `facet` option or the deprecated `surface`
+ * option (not both required — `facet` wins when both are supplied, and
+ * using `surface` alone emits a single deprecation warning per process; see
+ * {@link ProductVocabularyInput}).
  *
  * The type parameters carry the `const` modifier, so `claimTypes` and
  * `decisionEffects` string properties keep their literal types whether or
@@ -35,9 +59,11 @@ export function stableId(parts) {
  * types-only floor and does not affect JavaScript consumers.
  */
 export function defineProductVocabulary(definition) {
+    const facet = resolveFacet(definition);
     return deepFreeze({
         subjectType: definition.subjectType,
-        surface: definition.surface,
+        facet,
+        surface: facet,
         claimTypes: { ...definition.claimTypes },
         decisionEffects: { ...definition.decisionEffects },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -55,8 +55,11 @@
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test dist/tests/*.test.js",
     "test:browser": "playwright test",
-    "verify": "node scripts/check-content-boundary.cjs && npm run typecheck && npm test && npm run check:review-workbench-assets && npm run check:review-workbench && npm run test:browser",
+    "verify": "node scripts/check-content-boundary.cjs && npm run check:decisions && npm run typecheck && npm test && npm run check:review-workbench-assets && npm run check:review-workbench && npm run test:browser",
     "check:content-boundary": "node scripts/check-content-boundary.cjs",
+    "check:decisions": "node scripts/check-decisions.cjs check",
+    "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
+    "freeze:adrs": "node scripts/freeze-adrs.mjs",
     "sync:review-workbench-assets": "node scripts/sync-review-workbench-assets.cjs",
     "check:review-workbench-assets": "node scripts/sync-review-workbench-assets.cjs --check",
     "check:review-workbench": "npm run check:review-workbench:static && npm run check:generated-css",
@@ -68,7 +71,7 @@
     "check:generated-css": "node scripts/copy-review-workbench-package-assets.cjs --check"
   },
   "dependencies": {
-    "@kontourai/surface": "^1.3.0"
+    "@kontourai/surface": "^2.0.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.20.0",