@kontourai/survey 0.5.1 → 0.5.2

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, LocatorScheme, RawSource, RawSourceKind, ReviewOutcome, ReviewStatus, SurveyInput, } from "./types.js";
+export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, LocatorScheme, RawSource, RawSourceKind, ReviewAuthorizing, ReviewAuthorizingAuthorizedAction, ReviewAuthorizingExchange, ReviewAuthorizingExplicitStatement, ReviewAuthorizingKind, ReviewOutcome, ReviewStatus, SurveyInput, } from "./types.js";
 export { reviewResourceApiVersion } from "./review-resource.js";
 export type { CandidateRole, ClaimTargetHint, ExtractionReference, ResourceEnvelope, ResourceMetadata, ReviewActor, ReviewCandidate, ReviewDecision, ReviewDecisionSpec, ReviewDecisionStatus, ReviewItem, ReviewItemSpec, ReviewItemStatus, ReviewLocator, ReviewResource, ReviewResourceApiVersion, ReviewResourceKind, ReviewSession, ReviewSessionEvent, ReviewSessionEventSpec, ReviewSessionEventStatus, ReviewSessionEventType, ReviewSessionSpec, ReviewSessionStatus, SourceReference, SurveyRecordProjectionHint, } from "./review-resource.js";
 export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
@@ -31,3 +31,5 @@ export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInp
 export type { ExtractedStatement, StatementBadge, UtteranceClaimExtractor, UtteranceStatement, UtteranceStatementRecords, UtteranceTrustReport, } from "./agent-utterance.js";
 export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
 export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, SchemaMappingOptions, SystemFieldRef, } from "./schema-mapping.js";
+export { buildAuthorizedActionAuthorizing, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
+export type { BuildAuthorizedActionAuthorizingInput, ReviewAuthorizingIssue, ReviewAuthorizingIssueCode, } from "./review-authorizing.js";

package/dist/src/index.js

@@ -14,3 +14,4 @@ export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocum
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";
 export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
+export { buildAuthorizedActionAuthorizing, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";

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

@@ -0,0 +1,39 @@
+import type { ReviewAuthorizing, ReviewAuthorizingAuthorizedAction } from "./types.js";
+export type ReviewAuthorizingIssueCode = "not-an-object" | "missing-kind" | "unknown-kind" | "missing-statement" | "missing-prompt" | "missing-response" | "missing-prompt-ref" | "missing-rendered-prompt" | "missing-action" | "invalid-action" | "missing-authority-ref";
+export interface ReviewAuthorizingIssue {
+    readonly code: ReviewAuthorizingIssueCode;
+    readonly message: string;
+}
+/**
+ * Validates an `authorizing` block on a ReviewOutcome for admissibility.
+ *
+ * Per-kind required fields:
+ *   explicit-statement — `statement` (string, non-empty)
+ *   exchange           — `prompt` and `response` (both strings, non-empty;
+ *                        both halves required for self-contained testimony)
+ *   authorized-action  — `promptRef`, `renderedPrompt`, `action`, and
+ *                        `authorityRef` (all required; action must be
+ *                        "affirmed-control" or "typed")
+ *
+ * Returns an empty array when the block is valid.
+ */
+export declare function validateAuthorizing(block: unknown): ReviewAuthorizingIssue[];
+/**
+ * Type guard: returns true if a ReviewAuthorizing block passes all validation checks.
+ */
+export declare function isValidAuthorizing(block: unknown): block is ReviewAuthorizing;
+export interface BuildAuthorizedActionAuthorizingInput {
+    readonly promptRef: string;
+    readonly renderedPrompt: string;
+    readonly action: ReviewAuthorizingAuthorizedAction["action"];
+    readonly authorityRef: string;
+}
+/**
+ * Helper for consumers building `authorized-action` authorizing blocks outside
+ * the workbench. Constructs the block and validates it; throws if the result
+ * would be invalid so callers catch configuration errors at build time.
+ *
+ * For workbench-internal construction, use the workbench path directly — it
+ * runs validateAuthorizing and degrades gracefully instead of throwing.
+ */
+export declare function buildAuthorizedActionAuthorizing(input: BuildAuthorizedActionAuthorizingInput): ReviewAuthorizingAuthorizedAction;

package/dist/src/review-authorizing.js

@@ -0,0 +1,125 @@
+const VALID_ACTIONS = new Set(["affirmed-control", "typed"]);
+/**
+ * Validates an `authorizing` block on a ReviewOutcome for admissibility.
+ *
+ * Per-kind required fields:
+ *   explicit-statement — `statement` (string, non-empty)
+ *   exchange           — `prompt` and `response` (both strings, non-empty;
+ *                        both halves required for self-contained testimony)
+ *   authorized-action  — `promptRef`, `renderedPrompt`, `action`, and
+ *                        `authorityRef` (all required; action must be
+ *                        "affirmed-control" or "typed")
+ *
+ * Returns an empty array when the block is valid.
+ */
+export function validateAuthorizing(block) {
+    if (block === null || typeof block !== "object" || Array.isArray(block)) {
+        return [{ code: "not-an-object", message: "authorizing block must be a plain object." }];
+    }
+    const record = block;
+    if (!("kind" in record) || record.kind === undefined) {
+        return [{ code: "missing-kind", message: "authorizing block is missing the required 'kind' field." }];
+    }
+    const kind = record.kind;
+    if (kind === "explicit-statement") {
+        return validateExplicitStatement(record);
+    }
+    if (kind === "exchange") {
+        return validateExchange(record);
+    }
+    if (kind === "authorized-action") {
+        return validateAuthorizedAction(record);
+    }
+    return [{
+            code: "unknown-kind",
+            message: `authorizing kind '${String(kind)}' is not admissible. Use 'explicit-statement', 'exchange', or 'authorized-action'.`,
+        }];
+}
+function validateExplicitStatement(block) {
+    const issues = [];
+    if (!block.statement || typeof block.statement !== "string" || block.statement.trim() === "") {
+        issues.push({
+            code: "missing-statement",
+            message: "explicit-statement authorizing block requires a non-empty 'statement' string.",
+        });
+    }
+    return issues;
+}
+function validateExchange(block) {
+    const issues = [];
+    if (!block.prompt || typeof block.prompt !== "string" || block.prompt.trim() === "") {
+        issues.push({
+            code: "missing-prompt",
+            message: "exchange authorizing block requires a non-empty 'prompt' string (both halves required for self-contained testimony).",
+        });
+    }
+    if (!block.response || typeof block.response !== "string" || block.response.trim() === "") {
+        issues.push({
+            code: "missing-response",
+            message: "exchange authorizing block requires a non-empty 'response' string (both halves required for self-contained testimony).",
+        });
+    }
+    return issues;
+}
+function validateAuthorizedAction(block) {
+    const issues = [];
+    if (!block.promptRef || typeof block.promptRef !== "string" || block.promptRef.trim() === "") {
+        issues.push({
+            code: "missing-prompt-ref",
+            message: "authorized-action authorizing block requires a non-empty 'promptRef' string.",
+        });
+    }
+    if (!block.renderedPrompt || typeof block.renderedPrompt !== "string" || block.renderedPrompt.trim() === "") {
+        issues.push({
+            code: "missing-rendered-prompt",
+            message: "authorized-action authorizing block requires a non-empty 'renderedPrompt' string.",
+        });
+    }
+    if (block.action === undefined) {
+        issues.push({
+            code: "missing-action",
+            message: "authorized-action authorizing block requires an 'action' field.",
+        });
+    }
+    else if (!VALID_ACTIONS.has(block.action)) {
+        issues.push({
+            code: "invalid-action",
+            message: `authorized-action 'action' must be 'affirmed-control' or 'typed'; received '${String(block.action)}'.`,
+        });
+    }
+    if (!block.authorityRef || typeof block.authorityRef !== "string" || block.authorityRef.trim() === "") {
+        issues.push({
+            code: "missing-authority-ref",
+            message: "authorized-action authorizing block requires a non-empty 'authorityRef' string linking an AuthorityTrace.",
+        });
+    }
+    return issues;
+}
+/**
+ * Type guard: returns true if a ReviewAuthorizing block passes all validation checks.
+ */
+export function isValidAuthorizing(block) {
+    return validateAuthorizing(block).length === 0;
+}
+/**
+ * Helper for consumers building `authorized-action` authorizing blocks outside
+ * the workbench. Constructs the block and validates it; throws if the result
+ * would be invalid so callers catch configuration errors at build time.
+ *
+ * For workbench-internal construction, use the workbench path directly — it
+ * runs validateAuthorizing and degrades gracefully instead of throwing.
+ */
+export function buildAuthorizedActionAuthorizing(input) {
+    const block = {
+        kind: "authorized-action",
+        promptRef: input.promptRef,
+        renderedPrompt: input.renderedPrompt,
+        action: input.action,
+        authorityRef: input.authorityRef,
+    };
+    const issues = validateAuthorizedAction(block);
+    if (issues.length > 0) {
+        throw new Error(`buildAuthorizedActionAuthorizing: invalid authorized-action block: ${issues.map((issue) => issue.message).join(" ")}`);
+    }
+    return block;
+}

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

@@ -1,4 +1,4 @@
-import type { CandidateSetStatus, ClaimTarget, Extraction, RawSource, ReviewOutcome } from "./types.js";
+import type { CandidateSetStatus, ClaimTarget, Extraction, RawSource, ReviewAuthorizing, ReviewOutcome } from "./types.js";
 export declare const reviewResourceApiVersion = "survey.kontourai.io/v1alpha1";
 export type ReviewResourceApiVersion = typeof reviewResourceApiVersion;
 export type ReviewResourceKind = "ReviewItem" | "ReviewDecision" | "ReviewSession" | "ReviewSessionEvent";
@@ -102,6 +102,10 @@ export interface ReviewDecisionSpec {
     evidenceIds?: string[];
     withinComfortZone?: boolean;
     comfortZoneNote?: string;
+    /** Optional testimony provenance. Populated by the workbench on the
+     *  `authorized-action` channel; consumers on other channels may supply
+     *  their own admissible block. */
+    authorizing?: ReviewAuthorizing;
     projection?: SurveyRecordProjectionHint;
 }
 export interface ReviewDecisionStatus {

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

@@ -3,6 +3,8 @@ import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay
 import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-preview.js";
 import { buildReviewCandidatePresentation, buildReviewItemPresentation, } from "./review-presentation.js";
 import { reviewResourceApiVersion, } from "../review-resource.js";
+import { validateAuthorizing, buildAuthorizedActionAuthorizing } from "../review-authorizing.js";
+import { humanizeIdentifier } from "./review-presentation.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, } from "./review-surface-preview.js";
@@ -35,6 +37,7 @@ export function buildReviewDecision(state) {
             },
             reviewedAt: state.reviewedAt,
             rationale: state.note,
+            authorizing: buildDecisionCardAuthorizing(state),
             projection,
         },
         status: {
@@ -42,6 +45,61 @@ export function buildReviewDecision(state) {
         },
     };
 }
+/**
+ * Stable versioned prompt identifier for the workbench decision card control.
+ * Derived from the component naming convention: <module>/<component>@<version>.
+ */
+const DECISION_CARD_PROMPT_REF = "review-workbench/decision-card@v1";
+/**
+ * Constructs the `authorized-action` authorizing block for a workbench decision.
+ * On validation failure, emits a console warning and returns undefined so the
+ * outcome is recorded without authorizing (transparency-gap-not-blocker per ADR 0004).
+ */
+function buildDecisionCardAuthorizing(state) {
+    if (!state.decision) {
+        return undefined;
+    }
+    const targetLabel = humanizeIdentifier(state.item.spec.target);
+    const renderedPrompt = decisionCardRenderedPrompt(state, targetLabel);
+    // Reviewer note present means the reviewer also typed a rationale — "typed".
+    // Control-only affirmation (no note) is "affirmed-control".
+    const action = state.note?.trim() ? "typed" : "affirmed-control";
+    const authorityRef = `actor:${state.actorId}`;
+    try {
+        const block = buildAuthorizedActionAuthorizing({
+            promptRef: DECISION_CARD_PROMPT_REF,
+            renderedPrompt,
+            action,
+            authorityRef,
+        });
+        const issues = validateAuthorizing(block);
+        if (issues.length > 0) {
+            console.warn("[survey] buildDecisionCardAuthorizing: authorizing block failed validation — recording outcome without authorizing.", issues);
+            return undefined;
+        }
+        return block;
+    }
+    catch (err) {
+        console.warn("[survey] buildDecisionCardAuthorizing: failed to construct authorizing block — recording outcome without authorizing.", err);
+        return undefined;
+    }
+}
+/**
+ * Derives the exact decision prompt rendered on the workbench decision card
+ * for a given review item and decision.
+ *
+ * Format mirrors the review question shown in the workbench header:
+ * "For {target}, decide whether {proposed} should replace {current}."
+ * followed by the selected decision label so the block is self-contained.
+ */
+function decisionCardRenderedPrompt(state, targetLabel) {
+    const currentCandidate = state.item.spec.candidates.find((c) => c.role === "current");
+    const proposedCandidate = state.item.spec.candidates.find((c) => c.role === "proposed");
+    const currentValue = formatValue(currentCandidate?.value ?? "");
+    const proposedValue = formatValue(proposedCandidate?.value ?? "");
+    const decisionLabel = state.decision ? workbenchDecisionDefinitions[state.decision].label : "";
+    return `For ${targetLabel}, decide whether ${proposedValue} should replace ${currentValue}. Selected decision: ${decisionLabel}.`;
+}
 export class ReviewApplyActionMappingError extends Error {
     name = "ReviewApplyActionMappingError";
     issues;

package/dist/src/types.d.ts

@@ -47,6 +47,26 @@ export interface CandidateSet {
     metadata?: Record<string, unknown>;
 }
 export type ReviewStatus = Extract<TrustStatus, "verified" | "assumed" | "rejected" | "proposed">;
+export type ReviewAuthorizingKind = "explicit-statement" | "exchange" | "authorized-action";
+export interface ReviewAuthorizingExplicitStatement {
+    kind: "explicit-statement";
+    statement: string;
+    source?: string;
+}
+export interface ReviewAuthorizingExchange {
+    kind: "exchange";
+    prompt: string;
+    response: string;
+    source?: string;
+}
+export interface ReviewAuthorizingAuthorizedAction {
+    kind: "authorized-action";
+    promptRef: string;
+    renderedPrompt: string;
+    action: "affirmed-control" | "typed";
+    authorityRef: string;
+}
+export type ReviewAuthorizing = ReviewAuthorizingExplicitStatement | ReviewAuthorizingExchange | ReviewAuthorizingAuthorizedAction;
 export interface ReviewOutcome {
     id: string;
     candidateSetId: string;
@@ -58,6 +78,9 @@ export interface ReviewOutcome {
     evidenceIds?: string[];
     withinComfortZone?: boolean;
     comfortZoneNote?: string;
+    /** Optional testimony provenance. When present, records how this decision
+     *  was authorized — interpreted by downstream verifiers for admissibility. */
+    authorizing?: ReviewAuthorizing;
     metadata?: Record<string, unknown>;
 }
 export interface EscalationRecord {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",