@kontourai/survey 0.6.0 → 0.7.1

package/dist/src/index.d.ts

@@ -33,3 +33,5 @@ export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping,
 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";
+export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";
+export type { AggregateOversightMetrics, DeriveOversightMetricsOptions, OversightMetrics, OversightMetricsClaimsSubject, OversightQualityClaim, ReviewerOversightMetrics, } from "./oversight-metrics.js";

package/dist/src/index.js

@@ -15,3 +15,4 @@ export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, loo
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";
 export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
 export { buildAuthorizedActionAuthorizing, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
+export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";

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

@@ -0,0 +1,146 @@
+/**
+ * Oversight-quality metrics for EU AI Act Art. 14 "effective oversight" / automation-bias evidence.
+ *
+ * These metrics are INDICATORS, not proof of reviewer cognition. See the Honest Limits section
+ * in docs/record-contracts.md. Pace statistics can be gamed; metrics complement (not replace)
+ * identity signing and authorizing provenance.
+ *
+ * All computations are deterministic with injected `now`.
+ */
+import type { Claim, Evidence, TrustBundle, VerificationEvent } from "@kontourai/surface";
+import type { ReviewDecision } from "./review-resource.js";
+export interface ReviewerOversightMetrics {
+    /** Actor id this row belongs to. */
+    readonly actorId: string;
+    /** Total decisions made by this reviewer in the window. */
+    readonly decisionCount: number;
+    /**
+     * Average decisions per hour, computed as decisionCount / elapsed hours between
+     * the first and last reviewedAt timestamp (or 0 when decisionCount < 2).
+     */
+    readonly decisionsPerHour: number;
+    /**
+     * Fraction of decisions where the reviewer chose a candidate that differs from
+     * the item's pre-selected (proposed) candidate — i.e. the reviewer changed the
+     * outcome suggested by the system. Ranges 0–1.
+     */
+    readonly overrideRate: number;
+    /**
+     * Fraction of decisions where the authorizing block carries action === "typed",
+     * indicating the reviewer also wrote a rationale note. Ranges 0–1.
+     */
+    readonly typedRationaleRate: number;
+    /**
+     * Median inter-decision gap in seconds.  Undefined when fewer than 2 decisions.
+     */
+    readonly medianInterDecisionSeconds: number | undefined;
+    /**
+     * Fraction of presented items that were decided, when the caller supplies
+     * presentedCount. Omitted (undefined) otherwise.
+     */
+    readonly samplingCoverage: number | undefined;
+}
+export interface AggregateOversightMetrics {
+    /** Total decisions across all reviewers. */
+    readonly decisionCount: number;
+    /**
+     * Average decisions per hour across the full window (first decision to last
+     * decision, all reviewers combined).
+     */
+    readonly decisionsPerHour: number;
+    /** Override rate across all decisions. */
+    readonly overrideRate: number;
+    /** Typed-rationale rate across all decisions. */
+    readonly typedRationaleRate: number;
+    /** Median inter-decision gap in seconds across all decisions. */
+    readonly medianInterDecisionSeconds: number | undefined;
+    /**
+     * Fraction of presented items decided, when presentedCount was supplied.
+     * Omitted otherwise.
+     */
+    readonly samplingCoverage: number | undefined;
+}
+export interface OversightMetrics {
+    /** One row per unique actorId found in the decisions. */
+    readonly byReviewer: readonly ReviewerOversightMetrics[];
+    /** Aggregate across all reviewers. */
+    readonly aggregate: AggregateOversightMetrics;
+    /** ISO 8601 timestamp of the earliest decision in the window. */
+    readonly windowStart: string | undefined;
+    /** ISO 8601 timestamp of the latest decision in the window. */
+    readonly windowEnd: string | undefined;
+    /** Number of calendar days covered by the window (may be fractional). */
+    readonly windowDays: number | undefined;
+    /** Number of input decisions used for these metrics. */
+    readonly inputDecisionCount: number;
+}
+export interface DeriveOversightMetricsOptions {
+    /** Current time — injected for determinism. */
+    readonly now: Date;
+    /**
+     * Optional rolling window in days. Decisions older than `now - windowDays`
+     * are excluded. When omitted all supplied decisions are included.
+     */
+    readonly windowDays?: number;
+    /**
+     * Optional total number of items that were PRESENTED to reviewers (the
+     * denominator for samplingCoverage). When omitted, samplingCoverage is
+     * not computed.
+     */
+    readonly presentedCount?: number;
+}
+/**
+ * Derives per-reviewer and aggregate oversight-quality metrics from a stream
+ * of ReviewDecision resources.
+ *
+ * @param decisions - Array of ReviewDecision Kubernetes-style resources as
+ *   produced by the review workbench or adapters.
+ * @param options - `now` is required for determinism; `windowDays` and
+ *   `presentedCount` are optional.
+ */
+export declare function deriveOversightMetrics(decisions: readonly ReviewDecision[], options: DeriveOversightMetricsOptions): OversightMetrics;
+/**
+ * A single projected oversight-quality claim from the metrics layer.
+ * Uses claimType "oversight-quality" per the task specification.
+ */
+export interface OversightQualityClaim {
+    readonly claim: Claim;
+    readonly evidence: Evidence;
+    readonly event: VerificationEvent;
+}
+export interface OversightMetricsClaimsSubject {
+    /** Surface subject type (e.g. "review-session", "reviewer-actor"). */
+    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;
+    /** Actor id to record on events. */
+    readonly actor: string;
+    /** ISO 8601 timestamp for claim created/updated times. */
+    readonly observedAt: string;
+    /** Producer identifier for collectedBy field. */
+    readonly collectedBy: string;
+}
+/**
+ * Projects oversight metrics as Surface-ready claims.
+ *
+ * Produces one claim per measurable metric in `aggregate` (per task spec: claimType
+ * "oversight-quality", fieldOrBehavior per metric, numeric value). Evidence excerpts
+ * summarise the computation inputs (count, window) so Annex-pack rules can apply value
+ * predicates.
+ *
+ * Callers can pass these claims into buildSurveyTrustBundle by constructing a
+ * minimal SurveyInput with manual-entry raw sources, or merge the returned Claim /
+ * Evidence / VerificationEvent objects directly into an existing TrustBundle.
+ *
+ * @param metrics - Output of `deriveOversightMetrics`.
+ * @param subject - Surface identity for the claims.
+ */
+export declare function oversightMetricsToClaims(metrics: OversightMetrics, subject: OversightMetricsClaimsSubject): OversightQualityClaim[];
+/**
+ * Merges oversight-quality claims into an existing TrustBundle.
+ * Convenience wrapper for callers who already have a bundle and want to append
+ * oversight metrics without rebuilding from SurveyInput.
+ */
+export declare function mergeTrustBundleWithOversightMetrics(bundle: TrustBundle, claims: readonly OversightQualityClaim[]): TrustBundle;

package/dist/src/oversight-metrics.js

@@ -0,0 +1,296 @@
+/**
+ * Oversight-quality metrics for EU AI Act Art. 14 "effective oversight" / automation-bias evidence.
+ *
+ * These metrics are INDICATORS, not proof of reviewer cognition. See the Honest Limits section
+ * in docs/record-contracts.md. Pace statistics can be gamed; metrics complement (not replace)
+ * identity signing and authorizing provenance.
+ *
+ * All computations are deterministic with injected `now`.
+ */
+// ---------------------------------------------------------------------------
+// deriveOversightMetrics
+// ---------------------------------------------------------------------------
+/**
+ * Derives per-reviewer and aggregate oversight-quality metrics from a stream
+ * of ReviewDecision resources.
+ *
+ * @param decisions - Array of ReviewDecision Kubernetes-style resources as
+ *   produced by the review workbench or adapters.
+ * @param options - `now` is required for determinism; `windowDays` and
+ *   `presentedCount` are optional.
+ */
+export function deriveOversightMetrics(decisions, options) {
+    const cutoff = options.windowDays !== undefined
+        ? new Date(options.now.getTime() - options.windowDays * 24 * 60 * 60 * 1000)
+        : undefined;
+    const windowed = cutoff
+        ? decisions.filter((d) => {
+            const t = d.spec.reviewedAt ? Date.parse(d.spec.reviewedAt) : NaN;
+            return !isNaN(t) && t >= cutoff.getTime();
+        })
+        : [...decisions];
+    const inputDecisionCount = windowed.length;
+    if (inputDecisionCount === 0) {
+        return {
+            byReviewer: [],
+            aggregate: {
+                decisionCount: 0,
+                decisionsPerHour: 0,
+                overrideRate: 0,
+                typedRationaleRate: 0,
+                medianInterDecisionSeconds: undefined,
+                samplingCoverage: options.presentedCount !== undefined ? 0 : undefined,
+            },
+            windowStart: undefined,
+            windowEnd: undefined,
+            windowDays: options.windowDays,
+            inputDecisionCount: 0,
+        };
+    }
+    // Group by actor
+    const byActor = new Map();
+    for (const d of windowed) {
+        const actor = d.spec.actor?.id ?? "unknown";
+        const existing = byActor.get(actor) ?? [];
+        byActor.set(actor, [...existing, d]);
+    }
+    // Compute timestamps for window bounds
+    const allTimestamps = windowed
+        .map((d) => d.spec.reviewedAt ? Date.parse(d.spec.reviewedAt) : NaN)
+        .filter((t) => !isNaN(t))
+        .sort((a, b) => a - b);
+    const windowStart = allTimestamps.length > 0 ? new Date(allTimestamps[0]).toISOString() : undefined;
+    const windowEnd = allTimestamps.length > 0 ? new Date(allTimestamps[allTimestamps.length - 1]).toISOString() : undefined;
+    // Per-reviewer rows
+    const byReviewer = [];
+    for (const [actorId, actorDecisions] of byActor) {
+        byReviewer.push(computeReviewerMetrics(actorId, actorDecisions, options.presentedCount));
+    }
+    // Aggregate
+    const aggregate = computeAggregateMetrics(windowed, allTimestamps, options.presentedCount);
+    return {
+        byReviewer,
+        aggregate,
+        windowStart,
+        windowEnd,
+        windowDays: options.windowDays,
+        inputDecisionCount,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function computeReviewerMetrics(actorId, decisions, presentedCount) {
+    const decisionCount = decisions.length;
+    const timestamps = decisions
+        .map((d) => d.spec.reviewedAt ? Date.parse(d.spec.reviewedAt) : NaN)
+        .filter((t) => !isNaN(t))
+        .sort((a, b) => a - b);
+    const decisionsPerHour = computeDecisionsPerHour(decisionCount, timestamps);
+    const overrideCount = decisions.filter(isOverrideDecision).length;
+    const overrideRate = decisionCount > 0 ? overrideCount / decisionCount : 0;
+    const typedCount = decisions.filter(isTypedRationale).length;
+    const typedRationaleRate = decisionCount > 0 ? typedCount / decisionCount : 0;
+    const medianInterDecisionSeconds = computeMedianInterDecisionSeconds(timestamps);
+    const samplingCoverage = presentedCount !== undefined
+        ? (presentedCount > 0 ? decisionCount / presentedCount : 0)
+        : undefined;
+    return {
+        actorId,
+        decisionCount,
+        decisionsPerHour,
+        overrideRate,
+        typedRationaleRate,
+        medianInterDecisionSeconds,
+        samplingCoverage,
+    };
+}
+function computeAggregateMetrics(decisions, sortedTimestamps, presentedCount) {
+    const decisionCount = decisions.length;
+    const decisionsPerHour = computeDecisionsPerHour(decisionCount, sortedTimestamps);
+    const overrideCount = decisions.filter(isOverrideDecision).length;
+    const overrideRate = decisionCount > 0 ? overrideCount / decisionCount : 0;
+    const typedCount = decisions.filter(isTypedRationale).length;
+    const typedRationaleRate = decisionCount > 0 ? typedCount / decisionCount : 0;
+    const medianInterDecisionSeconds = computeMedianInterDecisionSeconds(sortedTimestamps);
+    const samplingCoverage = presentedCount !== undefined
+        ? (presentedCount > 0 ? decisionCount / presentedCount : 0)
+        : undefined;
+    return {
+        decisionCount,
+        decisionsPerHour,
+        overrideRate,
+        typedRationaleRate,
+        medianInterDecisionSeconds,
+        samplingCoverage,
+    };
+}
+/**
+ * A decision is an "override" when the reviewer chose a candidate whose id
+ * differs from the item's pre-selected (proposed) candidate.
+ *
+ * The item's proposed candidate id is carried in
+ * `decision.spec.projection.candidateId` when set; if absent we fall back to
+ * checking whether the decision status is "rejected" (reviewer rejected the
+ * proposal entirely). When neither signal is available the decision is treated
+ * as non-override to avoid false positives.
+ */
+function isOverrideDecision(decision) {
+    // "rejected" status always means the reviewer disagreed with the proposed value
+    if (decision.spec.status === "rejected") {
+        return true;
+    }
+    // If the decision carries a projection hint we can compare candidate ids.
+    // The proposed/pre-selected candidate is carried as the projection candidateId
+    // in ReviewDecision.spec.projection from the workbench accept-proposed path.
+    // When the reviewer keeps-current, the projection candidateId is the current
+    // candidate id, which differs from the proposed candidate — that counts as override.
+    // We detect this by checking whether the candidateId on the decision spec
+    // matches the projection candidateId and neither is undefined.
+    const decisionCandidateId = decision.spec.candidateId;
+    const projectionCandidateId = decision.spec.projection?.candidateId;
+    if (decisionCandidateId && projectionCandidateId && decisionCandidateId !== projectionCandidateId) {
+        return true;
+    }
+    return false;
+}
+/**
+ * A decision carries a "typed" rationale when the authorizing block is an
+ * `authorized-action` block with `action === "typed"`, indicating the reviewer
+ * explicitly wrote a note.
+ */
+function isTypedRationale(decision) {
+    const auth = decision.spec.authorizing;
+    return auth?.kind === "authorized-action" && auth.action === "typed";
+}
+function computeDecisionsPerHour(decisionCount, sortedTimestamps) {
+    if (decisionCount < 2 || sortedTimestamps.length < 2) {
+        return 0;
+    }
+    const first = sortedTimestamps[0];
+    const last = sortedTimestamps[sortedTimestamps.length - 1];
+    const elapsedHours = (last - first) / (1000 * 60 * 60);
+    if (elapsedHours <= 0) {
+        return 0;
+    }
+    return decisionCount / elapsedHours;
+}
+function computeMedianInterDecisionSeconds(sortedTimestamps) {
+    if (sortedTimestamps.length < 2) {
+        return undefined;
+    }
+    const gaps = [];
+    for (let i = 1; i < sortedTimestamps.length; i++) {
+        gaps.push((sortedTimestamps[i] - sortedTimestamps[i - 1]) / 1000);
+    }
+    gaps.sort((a, b) => a - b);
+    const mid = Math.floor(gaps.length / 2);
+    return gaps.length % 2 === 0
+        ? ((gaps[mid - 1] + gaps[mid]) / 2)
+        : gaps[mid];
+}
+/**
+ * Projects oversight metrics as Surface-ready claims.
+ *
+ * Produces one claim per measurable metric in `aggregate` (per task spec: claimType
+ * "oversight-quality", fieldOrBehavior per metric, numeric value). Evidence excerpts
+ * summarise the computation inputs (count, window) so Annex-pack rules can apply value
+ * predicates.
+ *
+ * Callers can pass these claims into buildSurveyTrustBundle by constructing a
+ * minimal SurveyInput with manual-entry raw sources, or merge the returned Claim /
+ * Evidence / VerificationEvent objects directly into an existing TrustBundle.
+ *
+ * @param metrics - Output of `deriveOversightMetrics`.
+ * @param subject - Surface identity for the claims.
+ */
+export function oversightMetricsToClaims(metrics, subject) {
+    const results = [];
+    const windowDesc = metrics.windowStart && metrics.windowEnd
+        ? `window ${metrics.windowStart} to ${metrics.windowEnd}`
+        : "all available decisions";
+    const inputSummary = `${metrics.inputDecisionCount} decisions, ${windowDesc}`;
+    const push = (fieldOrBehavior, value, excerptDetail) => {
+        const claimId = `oversight-quality.${subject.subjectId}.${fieldOrBehavior}`;
+        const evidenceId = `${claimId}.evidence`;
+        const claim = {
+            id: claimId,
+            subjectType: subject.subjectType,
+            subjectId: subject.subjectId,
+            surface: subject.surface,
+            claimType: "oversight-quality",
+            fieldOrBehavior,
+            value,
+            status: "proposed",
+            createdAt: subject.observedAt,
+            updatedAt: subject.observedAt,
+            impactLevel: "medium",
+            confidenceBasis: {
+                sourceQuality: "moderate",
+                reviewerAuthority: "none",
+                evidenceStrength: "weak",
+                impactLevel: "medium",
+            },
+            metadata: {
+                oversightMetrics: {
+                    inputDecisionCount: metrics.inputDecisionCount,
+                    windowStart: metrics.windowStart,
+                    windowEnd: metrics.windowEnd,
+                    windowDays: metrics.windowDays,
+                },
+            },
+        };
+        const evidence = {
+            id: evidenceId,
+            claimId,
+            evidenceType: "attestation",
+            method: "extraction",
+            sourceRef: "oversight-metrics://computed",
+            excerptOrSummary: `oversight-quality.${fieldOrBehavior}: ${excerptDetail}; computed from ${inputSummary}`,
+            observedAt: subject.observedAt,
+            collectedBy: subject.collectedBy,
+        };
+        const event = {
+            id: `${claimId}.event`,
+            claimId,
+            status: "proposed",
+            actor: subject.actor,
+            method: "candidate-proposal",
+            evidenceIds: [evidenceId],
+            createdAt: subject.observedAt,
+        };
+        results.push({ claim, evidence, event });
+    };
+    const agg = metrics.aggregate;
+    push("decisionCount", agg.decisionCount, `total decisions = ${agg.decisionCount}`);
+    push("decisionsPerHour", roundTo(agg.decisionsPerHour, 4), `decisions/hr = ${roundTo(agg.decisionsPerHour, 4)}`);
+    push("overrideRate", roundTo(agg.overrideRate, 4), `override rate = ${roundTo(agg.overrideRate, 4)} (${countFromRate(agg.overrideRate, agg.decisionCount)} of ${agg.decisionCount} decisions differed from proposed)`);
+    push("typedRationaleRate", roundTo(agg.typedRationaleRate, 4), `typed rationale rate = ${roundTo(agg.typedRationaleRate, 4)} (${countFromRate(agg.typedRationaleRate, agg.decisionCount)} of ${agg.decisionCount} decisions had typed note)`);
+    if (agg.medianInterDecisionSeconds !== undefined) {
+        push("medianInterDecisionSeconds", roundTo(agg.medianInterDecisionSeconds, 2), `median gap between decisions = ${roundTo(agg.medianInterDecisionSeconds, 2)} s`);
+    }
+    if (agg.samplingCoverage !== undefined) {
+        push("samplingCoverage", roundTo(agg.samplingCoverage, 4), `sampling coverage = ${roundTo(agg.samplingCoverage, 4)} (decided / presented)`);
+    }
+    return results;
+}
+/**
+ * Merges oversight-quality claims into an existing TrustBundle.
+ * Convenience wrapper for callers who already have a bundle and want to append
+ * oversight metrics without rebuilding from SurveyInput.
+ */
+export function mergeTrustBundleWithOversightMetrics(bundle, claims) {
+    return {
+        ...bundle,
+        claims: [...bundle.claims, ...claims.map((c) => c.claim)],
+        evidence: [...bundle.evidence, ...claims.map((c) => c.evidence)],
+        events: [...bundle.events, ...claims.map((c) => c.event)],
+    };
+}
+function roundTo(value, decimals) {
+    const factor = Math.pow(10, decimals);
+    return Math.round(value * factor) / factor;
+}
+function countFromRate(rate, total) {
+    return Math.round(rate * total);
+}

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

@@ -30,6 +30,72 @@
  */
 import { mountReviewWorkbench, } from "./review-workbench.js";
 import { REVIEW_WORKBENCH_CSS } from "./review-workbench-css.generated.js";
+/** @internal Second adopted stylesheet: host token defaults + inheritance delegation.
+ *
+ * This sheet is adopted AFTER the main workbench CSS (adoptedStyleSheets[1]).
+ * It serves two purposes:
+ *
+ * 1.  :host literal defaults — non-self-referential literal values for all --k-* tokens.
+ *     These provide a baseline when the host page does not load Console Kit.
+ *     Because they are literal (not var()), there is no self-reference cycle.
+ *     Inline styles on the host element always win over :host rules, so setting
+ *     `--k-brand: hotpink` on the element naturally overrides the #5ce0c6 default.
+ *
+ * 2.  .survey-workbench-embed[class] inherit delegation — using specificity (0,2,0)
+ *     to match the theme class selectors (e.g. .survey-workbench-embed.theme-survey).
+ *     Source order (after the workbench sheet) makes these inherit rules win, so the
+ *     embed's tokens propagate upward to :host, picking up any host overrides.
+ */
+const TOKEN_INHERIT_CSS = `/* 1. Host token defaults — literal values, not var() self-references.
+   Inline styles on the host element always win over :host rules so external
+   overrides (e.g. style="--k-brand: hotpink") propagate through automatically. */
+:host {
+  display: block;
+  container-type: inline-size;
+  --k-bg: #060a10;
+  --k-panel: #101822;
+  --k-panel-raised: #161e2b;
+  --k-text: #e8eaf0;
+  --k-text-muted: #8b93a8;
+  --k-text-faint: #4e5870;
+  --k-line: rgba(255,255,255,0.08);
+  --k-line-strong: rgba(255,255,255,0.14);
+  --k-brand: #5ce0c6;
+  --k-active: #7aa2ff;
+  --k-positive: #34d399;
+  --k-caution: #f3b14b;
+  --k-negative: #ff6f6f;
+  --k-neutral: #8b93a8;
+  --k-radius-md: 10px;
+  --k-radius-sm: 6px;
+  --k-font-ui: "Hanken Grotesk", system-ui, sans-serif;
+}
+/* 2. Token inheritance delegation — re-delegate --k-* tokens on the embed root
+   to inherit from :host, so external overrides set on the host element propagate
+   through the shadow boundary. The [class] attribute selector raises specificity
+   to (0,2,0) — matching the theme class selectors — and this sheet comes AFTER
+   the workbench defaults, so source order makes these rules win. */
+.survey-workbench-embed[class] {
+  --k-bg: inherit;
+  --k-panel: inherit;
+  --k-panel-raised: inherit;
+  --k-text: inherit;
+  --k-text-muted: inherit;
+  --k-text-faint: inherit;
+  --k-line: inherit;
+  --k-line-strong: inherit;
+  --k-brand: inherit;
+  --k-active: inherit;
+  --k-positive: inherit;
+  --k-caution: inherit;
+  --k-negative: inherit;
+  --k-neutral: inherit;
+  --k-radius-md: inherit;
+  --k-radius-sm: inherit;
+  --k-font-ui: inherit;
+  --k-font-mono: inherit;
+  --k-font-display: inherit;
+}`;
 export class SurveyReviewWorkbenchElement extends HTMLElement {
     static observedAttributes = ["theme", "color-scheme", "src"];
     #session = null;
@@ -49,33 +115,34 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
             styleEl.textContent = REVIEW_WORKBENCH_CSS;
             this.#root.appendChild(styleEl);
         }
-        // Host token defaults: CSS custom properties inherit through the shadow
-        // boundary so host overrides win automatically. These are the defaults
-        // that apply when no ancestor sets the tokens.
+        // Fallback <style> element for browsers that do not support adoptedStyleSheets.
+        // When adoptedStyleSheets are available, TOKEN_INHERIT_CSS (the second adopted
+        // sheet) handles :host defaults and embed token delegation — and wins over this
+        // <style> element in the cascade.  This <style> is only active in the fallback
+        // path, so using literal values here is safe: there is no self-reference cycle.
         const hostStyle = document.createElement("style");
         hostStyle.textContent = `
       :host {
         display: block;
         container-type: inline-size;
-        /* --k-bg, --k-panel, etc. are set by the Console Kit theme stylesheet.
-           Declare fallback token values here so shadow content has something
-           to work with even if the host doesn't load Console Kit. */
-        --k-bg: var(--k-bg, #060a10);
-        --k-panel: var(--k-panel, #101822);
-        --k-panel-raised: var(--k-panel-raised, #161e2b);
-        --k-text: var(--k-text, #e8eaf0);
-        --k-text-muted: var(--k-text-muted, #8b93a8);
-        --k-text-faint: var(--k-text-faint, #4e5870);
-        --k-line: var(--k-line, rgba(255,255,255,0.08));
-        --k-line-strong: var(--k-line-strong, rgba(255,255,255,0.14));
-        --k-brand: var(--k-brand, #5ce0c6);
-        --k-active: var(--k-active, #7aa2ff);
-        --k-positive: var(--k-positive, #34d399);
-        --k-caution: var(--k-caution, #f3b14b);
-        --k-negative: var(--k-negative, #ff6f6f);
-        --k-radius-md: var(--k-radius-md, 10px);
-        --k-radius-sm: var(--k-radius-sm, 6px);
-        --k-font-ui: var(--k-font-ui, "Hanken Grotesk", system-ui, sans-serif);
+        /* Literal token defaults (no var() self-references) so the values resolve
+           correctly even when the adopted inheritance sheet is unavailable. */
+        --k-bg: #060a10;
+        --k-panel: #101822;
+        --k-panel-raised: #161e2b;
+        --k-text: #e8eaf0;
+        --k-text-muted: #8b93a8;
+        --k-text-faint: #4e5870;
+        --k-line: rgba(255,255,255,0.08);
+        --k-line-strong: rgba(255,255,255,0.14);
+        --k-brand: #5ce0c6;
+        --k-active: #7aa2ff;
+        --k-positive: #34d399;
+        --k-caution: #f3b14b;
+        --k-negative: #ff6f6f;
+        --k-radius-md: 10px;
+        --k-radius-sm: 6px;
+        --k-font-ui: "Hanken Grotesk", system-ui, sans-serif;
       }
       .workbench-empty, .workbench-error {
         display: flex;
@@ -92,6 +159,30 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
       .workbench-error {
         color: var(--k-negative, #ff6f6f);
       }
+      /* Delegate k-tokens from :host to the embed container so host-element inline
+         style overrides propagate through the shadow boundary. This rule has same
+         specificity as the workbench CSS token defaults but comes after them in
+         document order, so it wins and allows inheritance from :host. */
+      .survey-workbench-embed {
+        --k-bg: inherit;
+        --k-panel: inherit;
+        --k-panel-raised: inherit;
+        --k-text: inherit;
+        --k-text-muted: inherit;
+        --k-text-faint: inherit;
+        --k-line: inherit;
+        --k-line-strong: inherit;
+        --k-brand: inherit;
+        --k-active: inherit;
+        --k-positive: inherit;
+        --k-caution: inherit;
+        --k-negative: inherit;
+        --k-radius-md: inherit;
+        --k-radius-sm: inherit;
+        --k-font-ui: inherit;
+        --k-font-mono: inherit;
+        --k-font-display: inherit;
+      }
     `;
         this.#root.appendChild(hostStyle);
         this.#mountRoot = document.createElement("div");
@@ -186,15 +277,27 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
         this.#mountRoot.innerHTML = `<div class="workbench-error">${escapeHtml(message)}</div>`;
         this.#mounted = false;
     }
-    /** Attempt to inject the workbench CSS via constructable CSSStyleSheet. */
+    /** Attempt to inject the workbench CSS via constructable CSSStyleSheet.
+     *
+     * Two sheets are adopted: the main workbench CSS first, then a
+     * token-inheritance sheet that resets all --k-* tokens to `inherit`
+     * on .survey-workbench-embed.  Because later entries in adoptedStyleSheets
+     * win over earlier ones at equal specificity, the inheritance rules
+     * override the workbench token defaults.  This allows host-element inline
+     * style overrides (or any ancestor's CSS custom properties) to propagate
+     * through the shadow boundary.
+     */
     #adoptCss() {
         try {
             if (typeof CSSStyleSheet === "undefined" || !this.#root.adoptedStyleSheets) {
                 return false;
             }
-            const sheet = new CSSStyleSheet();
-            sheet.replaceSync(REVIEW_WORKBENCH_CSS);
-            this.#root.adoptedStyleSheets = [sheet];
+            const workbenchSheet = new CSSStyleSheet();
+            workbenchSheet.replaceSync(REVIEW_WORKBENCH_CSS);
+            // Inheritance delegation sheet — must come AFTER the workbench sheet.
+            const inheritanceSheet = new CSSStyleSheet();
+            inheritanceSheet.replaceSync(TOKEN_INHERIT_CSS);
+            this.#root.adoptedStyleSheets = [workbenchSheet, inheritanceSheet];
             return true;
         }
         catch {

package/package.json

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