@kontourai/survey 1.3.0 → 1.4.0

package/README.md

@@ -79,7 +79,7 @@ const surveyInput = new SurveyInputBuilder({
     claim: {
       subjectType: "public-record.entity",
       subjectId: "listing-123",
-      surface: "public-record.profile",
+      facet: "public-record.profile",
       claimType: "public-data.field",
       fieldOrBehavior: "availabilityStatus",
       impactLevel: "medium",

package/dist/example-data/corrected-document-candidates.js

@@ -143,7 +143,7 @@ function documentClaim(id, target, candidateId, fieldOrBehavior, status) {
         candidateId: `document:candidate:${candidateId}`,
         subjectType: "verified-record.period",
         subjectId: "entity-1:2026",
-        surface: "document-review",
+        facet: "document-review",
         claimType: "source-field",
         fieldOrBehavior,
         status,
@@ -159,7 +159,7 @@ function computationClaim(id, status, inputClaimIds) {
         candidateId: `document:candidate:statement-position:${id}`,
         subjectType: "verified-record.period",
         subjectId: "entity-1:2026",
-        surface: "document-review",
+        facet: "document-review",
         claimType: "computed-field",
         fieldOrBehavior: "statementPosition",
         status,

package/dist/example-data/public-directory-review-resource.d.ts

@@ -45,7 +45,7 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -97,7 +97,7 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";

package/dist/example-data/public-directory-review-resource.js

@@ -47,7 +47,7 @@ export const publicDirectoryReviewItemExample = {
                     claimId: "public-field.entity-123.availability-status.current",
                     subjectType: "public-record.entity",
                     subjectId: "entity-123",
-                    surface: "public-record.profile",
+                    facet: "public-record.profile",
                     claimType: "public-data.field",
                     fieldOrBehavior: "availabilityStatus",
                     impactLevel: "medium",
@@ -98,7 +98,7 @@ export const publicDirectoryReviewItemExample = {
                     claimId: "public-field.entity-123.availability-status.proposal-456",
                     subjectType: "public-record.entity",
                     subjectId: "entity-123",
-                    surface: "public-record.profile",
+                    facet: "public-record.profile",
                     claimType: "public-data.field-candidate",
                     fieldOrBehavior: "availabilityStatus",
                     impactLevel: "medium",

package/dist/example-data/public-field-review.js

@@ -91,7 +91,7 @@ export const publicFieldReviewExample = {
             candidateId: "public-field:candidate:approved",
             subjectType: "public-record.entity",
             subjectId: "entity-123",
-            surface: "public-record.profile",
+            facet: "public-record.profile",
             claimType: "public-data.field",
             fieldOrBehavior: "availabilityStatus",
             impactLevel: "medium",
@@ -109,7 +109,7 @@ export const publicFieldReviewExample = {
             candidateId: "public-field:candidate:proposal",
             subjectType: "public-record.entity",
             subjectId: "entity-123",
-            surface: "public-record.profile",
+            facet: "public-record.profile",
             claimType: "public-data.field-candidate",
             fieldOrBehavior: "availabilityStatus",
             impactLevel: "medium",

package/dist/example-data/regulated-document-review-resource.d.ts

@@ -48,7 +48,7 @@ export declare const regulatedDocumentReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -96,7 +96,7 @@ export declare const regulatedDocumentReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";

package/dist/example-data/regulated-document-review-resource.js

@@ -50,7 +50,7 @@ export const regulatedDocumentReviewItemExample = {
                     claimId: "document.entity-1.statement-position.original",
                     subjectType: "verified-record.period",
                     subjectId: "entity-1:2026",
-                    surface: "document-review",
+                    facet: "document-review",
                     claimType: "computed-field",
                     fieldOrBehavior: "statementPosition",
                     impactLevel: "high",
@@ -102,7 +102,7 @@ export const regulatedDocumentReviewItemExample = {
                     claimId: "document.entity-1.statement-position.current",
                     subjectType: "verified-record.period",
                     subjectId: "entity-1:2026",
-                    surface: "document-review",
+                    facet: "document-review",
                     claimType: "computed-field",
                     fieldOrBehavior: "statementPosition",
                     impactLevel: "high",

package/dist/examples/public-field-observation.js

@@ -30,7 +30,7 @@ const surveyInput = new SurveyInputBuilder({
     claim: {
         subjectType: "public-record.entity",
         subjectId: "entity-1",
-        surface: "public-record.profile",
+        facet: "public-record.profile",
         claimType: "public-data.field",
         fieldOrBehavior: "availabilityStatus",
         impactLevel: "medium",

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

@@ -201,7 +201,7 @@ function candidateClaimTarget(args, claimId) {
         claimId,
         subjectType: "public-record.entity",
         subjectId: args.proposal.publicRecordId,
-        surface: "public-directory.profile",
+        facet: "public-directory.profile",
         claimType: args.role === "current" ? "public-data.field" : "public-data.field-candidate",
         fieldOrBehavior: args.field,
         impactLevel: "medium",

package/dist/src/agent-utterance.js

@@ -129,7 +129,7 @@ export function utteranceToSurveyInput(utterance, extracted, context) {
             candidateId,
             subjectType: statement.target.subjectType,
             subjectId: statement.target.subjectId,
-            surface: "agent-utterance.profile",
+            facet: "agent-utterance.profile",
             claimType: "agent-extraction",
             fieldOrBehavior: statement.target.fieldOrBehavior,
             value: statement.value,

package/dist/src/index.d.ts

@@ -33,7 +33,7 @@ export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, Sc
 export { buildAuthorizedActionAuthorizing, buildPromptRef, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
 export type { BuildAuthorizedActionAuthorizingInput, BuildPromptRefInput, ReviewAuthorizingIssue, ReviewAuthorizingIssueCode, } from "./review-authorizing.js";
 export { confidenceBasisForReview, defineProductVocabulary, stableId } from "./vocabulary.js";
-export type { ConfidenceBasisForReviewInput, ProductVocabularyDefinition, } from "./vocabulary.js";
+export type { ConfidenceBasisForReviewInput, ProductVocabularyDefinition, ProductVocabularyInput, } from "./vocabulary.js";
 export { currentProposedReviewItem } from "./current-proposed-review-item.js";
 export type { CurrentProposedCandidateInput, CurrentProposedReviewItemInput, } from "./current-proposed-review-item.js";
 export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";

package/dist/src/inquiry-mapping.d.ts

@@ -226,7 +226,7 @@ export declare function buildMappingReviewItems(candidateSets: Array<{
             claimTarget: {
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "low";

package/dist/src/inquiry-mapping.js

@@ -299,7 +299,7 @@ export function buildMappingReviewItems(candidateSets) {
                     claimTarget: {
                         subjectType: meta?.proposedTarget?.subjectType ?? "inquiry",
                         subjectId: meta?.proposedTarget?.subjectId ?? candidateSet.target,
-                        surface: "inquiry.mapping",
+                        facet: "inquiry.mapping",
                         claimType: "inquiry-mapping",
                         fieldOrBehavior: meta?.proposedTarget?.fieldOrBehavior ?? meta?.proposedRuleId ?? "unknown",
                         impactLevel: "low",

package/dist/src/oversight-metrics.d.ts

@@ -113,8 +113,8 @@ export interface OversightMetricsClaimsSubject {
     readonly subjectType: string;
     /** Surface subject id (e.g. a session name or actor id). */
     readonly subjectId: string;
-    /** Surface name (e.g. "review.oversight"). */
-    readonly surface: string;
+    /** Surface facet (e.g. "review.oversight"). */
+    readonly facet: string;
     /** Actor id to record on events. */
     readonly actor: string;
     /** ISO 8601 timestamp for claim created/updated times. */

package/dist/src/oversight-metrics.js

@@ -217,7 +217,7 @@ export function oversightMetricsToClaims(metrics, subject) {
             id: claimId,
             subjectType: subject.subjectType,
             subjectId: subject.subjectId,
-            surface: subject.surface,
+            facet: subject.facet,
             claimType: "oversight-quality",
             fieldOrBehavior,
             value,

package/dist/src/review-proof.d.ts

@@ -31,7 +31,7 @@ export interface CanonicalReviewProofPayload {
             candidateId?: string;
             subjectType: string;
             subjectId: string;
-            surface: string;
+            facet: string;
             claimType: string;
             fieldOrBehavior: string;
         };
@@ -92,7 +92,7 @@ export interface CanonicalReviewProofPayload {
         candidateId?: string;
         subjectType: string;
         subjectId: string;
-        surface: string;
+        facet: string;
         claimType: string;
         fieldOrBehavior: string;
         value?: unknown;

package/dist/src/review-proof.js

@@ -23,7 +23,7 @@ export function buildCanonicalReviewProofPayload(input) {
                 candidateId: input.candidate.id,
                 subjectType: input.claim.subjectType,
                 subjectId: input.claim.subjectId,
-                surface: input.claim.surface,
+                facet: input.claim.facet,
                 claimType: input.claim.claimType,
                 fieldOrBehavior: input.claim.fieldOrBehavior,
             },
@@ -86,7 +86,7 @@ export function buildCanonicalReviewProofPayload(input) {
             candidateId: input.claim.candidateId,
             subjectType: input.claim.subjectType,
             subjectId: input.claim.subjectId,
-            surface: input.claim.surface,
+            facet: input.claim.facet,
             claimType: input.claim.claimType,
             fieldOrBehavior: input.claim.fieldOrBehavior,
             value: input.claim.value,

package/dist/src/review-resource.d.ts

@@ -42,7 +42,11 @@ export interface ClaimTargetHint {
     claimId?: 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).
+     */
+    facet: string;
     claimType: string;
     fieldOrBehavior: string;
     impactLevel: ClaimTarget["impactLevel"];

package/dist/src/review-workbench/review-workbench-data.d.ts

@@ -46,7 +46,7 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -98,7 +98,7 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -184,7 +184,7 @@ export declare const regulatedRuleConflictReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -235,7 +235,7 @@ export declare const regulatedRuleConflictReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -334,7 +334,7 @@ export declare const facilityCredentialReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -395,7 +395,7 @@ export declare const facilityCredentialReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -472,7 +472,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -524,7 +524,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -609,7 +609,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -660,7 +660,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";

package/dist/src/review-workbench/review-workbench-data.js

@@ -49,7 +49,7 @@ export const publicDirectoryReviewItemExample = {
                     claimId: "public-field.entity-123.availability-status.current",
                     subjectType: "public-record.entity",
                     subjectId: "entity-123",
-                    surface: "public-record.profile",
+                    facet: "public-record.profile",
                     claimType: "public-data.field",
                     fieldOrBehavior: "availabilityStatus",
                     impactLevel: "medium",
@@ -100,7 +100,7 @@ export const publicDirectoryReviewItemExample = {
                     claimId: "public-field.entity-123.availability-status.proposal-456",
                     subjectType: "public-record.entity",
                     subjectId: "entity-123",
-                    surface: "public-record.profile",
+                    facet: "public-record.profile",
                     claimType: "public-data.field-candidate",
                     fieldOrBehavior: "availabilityStatus",
                     impactLevel: "medium",
@@ -187,7 +187,7 @@ export const regulatedRuleConflictReviewItemExample = {
                     claimId: "regulated-rule.example-jurisdiction.2026.standard-threshold.current",
                     subjectType: "regulated-rule-source",
                     subjectId: "example-jurisdiction:2026:standardThreshold",
-                    surface: "regulated.rules",
+                    facet: "regulated.rules",
                     claimType: "regulated.rule-source-value",
                     fieldOrBehavior: "standardThreshold",
                     impactLevel: "high",
@@ -235,7 +235,7 @@ export const regulatedRuleConflictReviewItemExample = {
                     claimId: "regulated-rule.example-jurisdiction.2026.standard-threshold.proposed",
                     subjectType: "regulated-rule-source",
                     subjectId: "example-jurisdiction:2026:standardThreshold",
-                    surface: "regulated.rules",
+                    facet: "regulated.rules",
                     claimType: "regulated.rule-source-value",
                     fieldOrBehavior: "standardThreshold",
                     impactLevel: "high",
@@ -332,7 +332,7 @@ export const facilityCredentialReviewItemExample = {
                     claimId: "facility-credential.facility-42.operating-license.current",
                     subjectType: "facility",
                     subjectId: "facility-42",
-                    surface: "facility.credential-profile",
+                    facet: "facility.credential-profile",
                     claimType: "facility.credential",
                     fieldOrBehavior: "operatingLicenseCredential",
                     impactLevel: "high",
@@ -391,7 +391,7 @@ export const facilityCredentialReviewItemExample = {
                     claimId: "facility-credential.facility-42.operating-license.registry",
                     subjectType: "facility",
                     subjectId: "facility-42",
-                    surface: "facility.credential-profile",
+                    facet: "facility.credential-profile",
                     claimType: "facility.credential-candidate",
                     fieldOrBehavior: "operatingLicenseCredential",
                     impactLevel: "high",

package/dist/src/review-workbench/review-workbench.js

@@ -1308,7 +1308,7 @@ function isReviewCandidate(value) {
         && isRecord(value.claimTarget)
         && typeof value.claimTarget.subjectType === "string"
         && typeof value.claimTarget.subjectId === "string"
-        && typeof value.claimTarget.surface === "string"
+        && typeof value.claimTarget.facet === "string"
         && typeof value.claimTarget.claimType === "string"
         && typeof value.claimTarget.fieldOrBehavior === "string"
         && typeof value.claimTarget.impactLevel === "string";

package/dist/src/schema-mapping.js

@@ -198,7 +198,7 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
                 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: {
@@ -342,7 +342,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 },

package/dist/src/to-surface.js

@@ -23,7 +23,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 +120,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
         }
     }
     return {
-        schemaVersion: 3,
+        schemaVersion: 5,
         source: input.source,
         claims,
         evidence,

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.4.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -68,7 +68,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",