@indexnetwork/protocol 66.0.0-rc.608.1 → 66.0.0-rc.610.1

package/CHANGELOG.md

@@ -6,7 +6,9 @@
 
 - Opportunity copy comes only from the LLM presenter. `OpportunityPresenter.present()` and `presentCard()` throw on LLM failure, timeout, or invalid output instead of returning fallback copy; `isFallback` and `fallbackReason` are gone from their results.
 - Remove `presentOpportunity`, `stripUuids`, `truncateAtBoundary`, `safeFallbackSummary`, `DEFAULT_FALLBACK_HEADLINE`, `hasUnsupportedOpportunityClaim`, `stripUnsupportedOpportunityClaims`, and `stripUnsupportedOpportunityClaimsText` from the public entry point. The regex claim-safety guard is deleted; the presenter prompts carry the rule.
-- `readOpportunities` items no longer carry `reasoning`. Radar drops a card when its presenter call fails instead of rendering reasoning-derived fallback copy.
+- `readOpportunities` items no longer carry `reasoning`.
+- Remove `RadarGraphFactory` and the radar graph. Use `listOpportunityCards(deps, { viewerId, statuses, networkId?, intentId?, limit, noCache?, skeleton? })` for a presented card list and `presentOpportunityCard(deps, opportunity, viewerId, { intentId?, skeleton? })` for one card; both return `OpportunityCard`. `statuses` is required, and the list is newest first with one card per counterpart. A card whose presenter call fails is dropped from the list; `presentOpportunityCard` throws.
+- Rename `RadarGraphDatabase` to `OpportunityCardsDatabase` and `buildRadarCardPresentationCacheKey` to `buildOpportunityCardCacheKey` (keys now start with `card:`). Remove `RADAR_SOFT_TARGETS` and `selectByComposition`.
 
 ## 65.0.0
 

package/IMPLEMENTATION.md

@@ -128,26 +128,25 @@ negotiation state and presentation contracts.
 Optional capabilities default to a
 degraded-but-functional mode when omitted.
 
-## Graphs
+## Opportunity cards
 
-A `*GraphFactory` class is exported for each workflow:
+Presented opportunity cards are plain async functions over
+`{ database: OpportunityCardsDatabase, cache: OpportunityCache, presenter: OpportunityPresenter }`:
 
 ```typescript
 import {
-  RadarGraphFactory,
+  listOpportunityCards,
+  presentOpportunityCard,
 } from "@indexnetwork/protocol";
 ```
 
-Each factory takes its typed dependencies in the constructor and exposes a
-`.createGraph()` method that returns a compiled LangGraph ready for `.invoke()`.
+`listOpportunityCards` returns the viewer's opportunities in the requested
+statuses, newest first with one card per counterpart, serving cached cards and
+dropping any whose presenter call fails. `presentOpportunityCard` presents one
+opportunity and throws when the presenter fails.
 
-The intent and community graphs are the exceptions: they are reached through the
-`Intents` and `Networks` module classes rather than factories of their own (see
-[Intents](#intents) and [Networks](#networks) below).
-
-| Factory | Workflow |
-|---|---|
-| `RadarGraphFactory` | Build the radar view: flat presenter-card list, optionally intent-scoped |
+The intent and community graphs are reached through the `Intents` and `Networks`
+module classes (see [Intents](#intents) and [Networks](#networks) below).
 
 ## On-demand discovery
 

package/STABILITY.md

@@ -46,7 +46,6 @@ Covered by SemVer below. Breaking changes require a **major** bump.
 | **Public API** | Model config helpers, request scope helpers (`deriveAllowedNetworkIds`, `deriveDiscoveryNetworkIds`), `requestContext`. |
 | **Interfaces** | Every port you implement to inject infrastructure (databases, embedder, cache, scraper, integration, …). |
 | **Shared schemas** | Zod schemas + inferred types that cross the boundary (underspecification, identity, network-assignment, chat-context, …). |
-| **Graph factories** | `*GraphFactory` classes (for example, `RadarGraphFactory`). |
 | **Intents** | `Intents` — the whole signal capability as one class (lifecycle graph, verification, preparation) plus `IntentsDeps` and the `Prepare*` / `RecoveryField*` types. Replaced the six separate intent exports in 18.0.0. |
 | **Agents** | Structured LLM agents (`OpportunityEvaluator`, …). |
 

package/dist/capabilities/intents.d.ts

@@ -18,10 +18,10 @@ import type { EmbeddingGenerator } from "../platform/discovery/embedder.js";
 import type { IntentFollowUp } from "../platform/runtime/follow-up.js";
 import { ExplicitIntentInferrer } from "../internal/intents/intent.inferrer.js";
 import { SemanticVerifier } from "../internal/intents/intent.verifier.js";
-import type { PrepareInput, PrepareResult } from "../internal/intents/intent.preparer.js";
+import type { AdmissionCheck, PrepareInput, PrepareResult, RecoveryField } from "../internal/intents/intent.preparer.js";
 export type { IntentSemanticMetadata } from "../internal/intents/intent.admission.js";
 export type { PreparedIntent } from "../internal/intents/intent.preparer.js";
-export type { PrepareAnswer, PrepareInput, PrepareResult, RecoveryField, RecoveryFieldKind, RecoveryFieldOption, } from "../internal/intents/intent.preparer.js";
+export type { AdmissionCheck, PrepareAnswer, PrepareInput, PrepareResult, RecoveryField, RecoveryFieldKind, RecoveryFieldOption, } from "../internal/intents/intent.preparer.js";
 /**
  * Host capabilities the intent lifecycle needs.
  *
@@ -421,7 +421,7 @@ export declare class Intents {
                 status: "needs_revision";
                 payload: string;
                 feedback: string;
-                recovery: import("../internal/intents/intent.preparer.js").RecoveryField[];
+                recovery: RecoveryField[];
             };
             actions: never[];
             validationFailures: {
@@ -607,6 +607,10 @@ export declare class Intents {
      * @param input - The payload and any recovery answers gathered so far.
      */
     prepare(input: PrepareInput): Promise<PrepareResult>;
+    /** Jev's pass or the constraints still missing. Does not write questions. */
+    check(input: PrepareInput): Promise<AdmissionCheck>;
+    /** One recovery field per missing constraint. Does not run Jev. */
+    questions(input: PrepareInput, missing: readonly string[]): Promise<RecoveryField[]>;
     /**
      * Measure text without applying any admission filters.
      * @param content - The exact saved description.

package/dist/capabilities/intents.js

@@ -70,6 +70,16 @@ export class Intents {
         this.preparer ?? (this.preparer = new IntentPreparer(this.deps.agents?.verifier));
         return this.preparer.invoke(input);
     }
+    /** Jev's pass or the constraints still missing. Does not write questions. */
+    async check(input) {
+        this.preparer ?? (this.preparer = new IntentPreparer(this.deps.agents?.verifier));
+        return this.preparer.check(input);
+    }
+    /** One recovery field per missing constraint. Does not run Jev. */
+    async questions(input, missing) {
+        this.preparer ?? (this.preparer = new IntentPreparer(this.deps.agents?.verifier));
+        return this.preparer.questions(input, missing);
+    }
     /**
      * Measure text without applying any admission filters.
      * @param content - The exact saved description.

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { requestContext, setRequestContextStore } from "./internal/shared/observ
 export { setLoggerFactory } from "./internal/shared/observability/log.js";
 export { setTimingWrapper } from "./internal/shared/observability/performance.js";
 export type { Cache, CacheOptions, OpportunityCache } from "./platform/discovery/cache.js";
-export type { CompositeDatabase, UserDatabase, SystemDatabase, OpportunityDatabase, OpportunityControllerDatabase, RadarGraphDatabase, IntentGraphDatabase, Opportunity, OpportunityActor, OpportunityStatus, AssignmentNetworkMembership, IntentNetworkFinalAssignmentResult, CreateOpportunityData, IntentLifecycleStatus, TransitionLifecycleResult, NegotiationContextDatabase, NegotiationContextRecord, NegotiationContextOutcome, NegotiationContextTurn, } from "./platform/database.js";
+export type { CompositeDatabase, UserDatabase, SystemDatabase, OpportunityDatabase, OpportunityControllerDatabase, OpportunityCardsDatabase, IntentGraphDatabase, Opportunity, OpportunityActor, OpportunityStatus, AssignmentNetworkMembership, IntentNetworkFinalAssignmentResult, CreateOpportunityData, IntentLifecycleStatus, TransitionLifecycleResult, NegotiationContextDatabase, NegotiationContextRecord, NegotiationContextOutcome, NegotiationContextTurn, } from "./platform/database.js";
 export type { Embedder, VectorStoreOption, VectorSearchResult } from "./platform/discovery/embedder.js";
 export type { IntentFollowUp } from "./platform/runtime/follow-up.js";
 export type { Scraper } from "./platform/discovery/scraper.js";
@@ -29,7 +29,7 @@ export type { NegotiationDatabase } from './platform/database/negotiation.js';
 export { Networks } from "./capabilities/networks.js";
 export type { NetworksDeps } from "./capabilities/networks.js";
 export { Intents } from "./capabilities/intents.js";
-export type { PrepareAnswer, PrepareInput, PrepareResult, RecoveryField, RecoveryFieldKind, RecoveryFieldOption, IntentsDeps, IntentSemanticMetadata, PreparedIntent, } from "./capabilities/intents.js";
+export type { AdmissionCheck, PrepareAnswer, PrepareInput, PrepareResult, RecoveryField, RecoveryFieldKind, RecoveryFieldOption, IntentsDeps, IntentSemanticMetadata, PreparedIntent, } from "./capabilities/intents.js";
 export { normalizeTelegramHandle } from './internal/shared/utils/telegram-handle.js';
 /**
  * opportunity — the capability's sole cross-capability surface.
@@ -44,10 +44,11 @@ export type { CreateIntentCounterpartyData, OpenedNegotiation, } from "./interna
 export { gatherPresenterContext, OpportunityPresenter, } from "./internal/opportunities/opportunity.presentation.js";
 export type { PresenterDatabase, } from "./internal/opportunities/opportunity.presentation.js";
 export { getPrimaryActionLabel, } from "./internal/opportunities/opportunity.labels.js";
-export { buildApiChatCardPresentationCacheKey, buildRadarCardPresentationCacheKey, } from "./internal/opportunities/opportunity.presentation.js";
+export { buildApiChatCardPresentationCacheKey, buildOpportunityCardCacheKey, } from "./internal/opportunities/opportunity.presentation.js";
 export type { UserInfo, } from "./internal/opportunities/opportunity.presentation.js";
-export { canUserSeeOpportunity, classifyOpportunity, isActionableForViewer, RADAR_SOFT_TARGETS, selectByComposition, validateOpportunityActors, } from "./internal/opportunities/opportunity.utils.js";
-export { RadarGraphFactory, } from "./internal/opportunities/radar/radar.graph.js";
+export { canUserSeeOpportunity, classifyOpportunity, isActionableForViewer, validateOpportunityActors, } from "./internal/opportunities/opportunity.utils.js";
+export { listOpportunityCards, presentOpportunityCard, } from "./internal/opportunities/opportunity.cards.js";
+export type { OpportunityCard, } from "./internal/opportunities/opportunity.cards.js";
 export { readOpportunities } from './internal/opportunities/opportunity.graph.modes.js';
 export { admitOpportunityEvent, projectOpportunity } from './internal/opportunities/opportunity.events.js';
 export type { OpportunityAdmission, OpportunityEventType, OpportunityLogEvent, OpportunityProjection, OpportunityProjectionStatus } from './internal/opportunities/opportunity.events.js';

package/dist/index.js

@@ -48,9 +48,9 @@ export { normalizeTelegramHandle } from './internal/shared/utils/telegram-handle
 export { pairKeyOf, } from "./internal/opportunities/opportunity.counterparties.js";
 export { gatherPresenterContext, OpportunityPresenter, } from "./internal/opportunities/opportunity.presentation.js";
 export { getPrimaryActionLabel, } from "./internal/opportunities/opportunity.labels.js";
-export { buildApiChatCardPresentationCacheKey, buildRadarCardPresentationCacheKey, } from "./internal/opportunities/opportunity.presentation.js";
-export { canUserSeeOpportunity, classifyOpportunity, isActionableForViewer, RADAR_SOFT_TARGETS, selectByComposition, validateOpportunityActors, } from "./internal/opportunities/opportunity.utils.js";
-export { RadarGraphFactory, } from "./internal/opportunities/radar/radar.graph.js";
+export { buildApiChatCardPresentationCacheKey, buildOpportunityCardCacheKey, } from "./internal/opportunities/opportunity.presentation.js";
+export { canUserSeeOpportunity, classifyOpportunity, isActionableForViewer, validateOpportunityActors, } from "./internal/opportunities/opportunity.utils.js";
+export { listOpportunityCards, presentOpportunityCard, } from "./internal/opportunities/opportunity.cards.js";
 export { readOpportunities } from './internal/opportunities/opportunity.graph.modes.js';
 export { admitOpportunityEvent, projectOpportunity } from './internal/opportunities/opportunity.events.js';
 export { resolveDiscoveryNetworkScope, renderDiscoveryNetworkContext } from './protocol/discovery.rules.js';

package/dist/internal/intents/graph/intent.graph.reconcile.js

@@ -34,7 +34,7 @@ export async function verificationNode(state, deps) {
                 const verdict = await deps.verifier.invoke(description, state.userProfile);
                 agentTimingsAccum.push({ name: 'intent.verifier', durationMs: Date.now() - verifierStart });
                 _traceEmitterVerifier?.({ type: "agent_end", name: "intent-verifier", durationMs: Date.now() - verifierStart, summary: `Verified: ${verdict.classification}` });
-                const failure = admissionFailure(description, verdict, isExplicitUpdate);
+                const failure = admissionFailure(verdict, isExplicitUpdate);
                 if (failure)
                     return { failure };
                 // Calculate Score

package/dist/internal/intents/intent.admission.d.ts

@@ -1,7 +1,27 @@
 import type { SemanticVerifierOutput } from "./intent.verifier.js";
 import type { IntentValidationFailure } from "./graph/intent.graph.state.js";
+/** A noul at or above this is a yes the admission check acts on. */
+export declare const ADMISSION_NOUL = 0.8;
+export declare const ADMISSION_CONSTRAINTS: readonly ["role", "outcome", "location", "timeframe", "domain", "concrete_need"];
+export type AdmissionConstraint = (typeof ADMISSION_CONSTRAINTS)[number];
+type SpeechAct = "commissive" | "directive" | "declaration" | "other";
+/** One Jev admission call, already read into numbers. */
+export interface AdmissionDecision {
+    speechAct: SpeechAct;
+    tooVague: number;
+    tooBroad: number;
+    constraints: Record<AdmissionConstraint, number>;
+}
 /** The admission policy shared by preparation and explicit updates. */
-export declare function admissionFailure(description: string, verdict: SemanticVerifierOutput, isExplicitUpdate?: boolean): IntentValidationFailure | undefined;
+export declare function admissionFailure(verdict: SemanticVerifierOutput, isExplicitUpdate?: boolean): IntentValidationFailure | undefined;
+/**
+ * The prepare-path admission check. Constraint nouls at or above {@link ADMISSION_NOUL}
+ * are still missing; they do not fail admission on their own.
+ */
+export declare function admissionFromDecision(decision: AdmissionDecision): {
+    failure?: IntentValidationFailure;
+    missing: AdmissionConstraint[];
+};
 /** Measurements of exactly one description, independent of admission. */
 export interface IntentSemanticMetadata {
     semanticEntropy: number;
@@ -14,3 +34,4 @@ export interface IntentSemanticMetadata {
 }
 /** Map even a negative verdict to measurements without applying admission. */
 export declare function semanticMetadata(verdict: SemanticVerifierOutput): IntentSemanticMetadata;
+export {};

package/dist/internal/intents/intent.admission.js

@@ -1,21 +1,42 @@
 const MAX_PERMISSIBLE_ENTROPY = 0.75;
 const MIN_CLEAR_INTENT_SCORE = 40;
-// Match the whole request so qualified job searches use the verifier's verdict.
-const GENERIC_JOB_PHRASE = /^(?:(?:i(?:['’]m|\s+am)?\s+)?(?:want|need|seek(?:ing)?|looking\s+for)\s+)?(?:a|any|some)\s+job[.!?]*$/i;
-const DEFAULT_SPECIFICITY_WARNING = "This signal is broad and may produce many weak matches. Add a more concrete role, outcome, location, timeframe, domain, or specific need to get better recommendations.";
+const NON_ACTIONABLE_MESSAGE = "Describe who you want to reach and what you want to do together.";
+const VAGUE_MESSAGE = "Make the goal more concrete: specify the role, outcome, or particular help you need.";
+const BROAD_MESSAGE = "This signal is broad and may produce many weak matches. Add a more concrete role, outcome, location, timeframe, domain, or specific need to get better recommendations.";
+/** A noul at or above this is a yes the admission check acts on. */
+export const ADMISSION_NOUL = 0.8;
+export const ADMISSION_CONSTRAINTS = ["role", "outcome", "location", "timeframe", "domain", "concrete_need"];
 /** The admission policy shared by preparation and explicit updates. */
-export function admissionFailure(description, verdict, isExplicitUpdate = false) {
+export function admissionFailure(verdict, isExplicitUpdate = false) {
     const details = { classification: verdict.classification, referentialBreadth: verdict.referential_breadth };
     if (!["COMMISSIVE", "DIRECTIVE", "DECLARATION"].includes(verdict.classification)) {
-        return { ...details, category: "non_actionable", message: "Describe who you want to reach and what you want to do together." };
+        return { ...details, category: "non_actionable", message: NON_ACTIONABLE_MESSAGE };
     }
-    if (GENERIC_JOB_PHRASE.test(description.trim()) || verdict.semantic_entropy > MAX_PERMISSIBLE_ENTROPY || verdict.felicity_scores.clarity < MIN_CLEAR_INTENT_SCORE) {
-        return { ...details, category: "vague_or_invalid", message: "Make the goal more concrete: specify the role, outcome, or particular help you need." };
+    if (verdict.semantic_entropy > MAX_PERMISSIBLE_ENTROPY || verdict.felicity_scores.clarity < MIN_CLEAR_INTENT_SCORE) {
+        return { ...details, category: "vague_or_invalid", message: VAGUE_MESSAGE };
     }
     if (!isExplicitUpdate && verdict.referential_breadth === "broad") {
-        return { ...details, category: "vague_or_invalid", message: verdict.specificity_warning?.trim() || DEFAULT_SPECIFICITY_WARNING };
+        return { ...details, category: "vague_or_invalid", message: verdict.specificity_warning?.trim() || BROAD_MESSAGE };
     }
 }
+/**
+ * The prepare-path admission check. Constraint nouls at or above {@link ADMISSION_NOUL}
+ * are still missing; they do not fail admission on their own.
+ */
+export function admissionFromDecision(decision) {
+    const missing = ADMISSION_CONSTRAINTS.filter((name) => decision.constraints[name] >= ADMISSION_NOUL);
+    const classification = decision.speechAct === "other" ? "UNKNOWN" : decision.speechAct.toUpperCase();
+    if (decision.speechAct === "other") {
+        return { missing, failure: { category: "non_actionable", classification, message: NON_ACTIONABLE_MESSAGE } };
+    }
+    if (decision.tooVague >= ADMISSION_NOUL) {
+        return { missing, failure: { category: "vague_or_invalid", classification, message: VAGUE_MESSAGE } };
+    }
+    if (decision.tooBroad >= ADMISSION_NOUL) {
+        return { missing, failure: { category: "vague_or_invalid", classification, referentialBreadth: "broad", message: BROAD_MESSAGE } };
+    }
+    return { missing };
+}
 /** Map even a negative verdict to measurements without applying admission. */
 export function semanticMetadata(verdict) {
     return {

package/dist/internal/intents/intent.preparer.d.ts

@@ -1,4 +1,5 @@
-import { type IntentSemanticMetadata } from "./intent.admission.js";
+import { DecisionClient } from "../shared/agent/decision.client.js";
+import { type AdmissionConstraint, type IntentSemanticMetadata } from "./intent.admission.js";
 import { SemanticVerifier } from "./intent.verifier.js";
 /** One answer paired with the recovery field it fills. */
 export interface PrepareAnswer {
@@ -37,16 +38,40 @@ export type PrepareResult = {
     feedback: string;
     recovery: RecoveryField[];
 };
+/** Jev's read of the current rows. `passed` is the only state that may mint a receipt. */
+export interface AdmissionCheck {
+    passed: boolean;
+    missing: AdmissionConstraint[];
+    message: string;
+}
 /** Folds recovery answers into a draft, admits its final form, and returns a dynamic recovery form on failure. Model failures propagate for retry. */
 export declare class IntentPreparer {
     private readonly verifier;
-    constructor(verifier?: Pick<SemanticVerifier, "invoke">);
+    private readonly decider;
+    constructor(verifier?: Pick<SemanticVerifier, "invoke">, decider?: Pick<DecisionClient, "decide">);
+    /**
+     * Ask Jev whether the current rows would pass. Does not fold text or write questions.
+     * @param input - Opening draft and the answers already on the page.
+     * @param profileContext - The speaker's profile, if supplied by the host.
+     * @throws When Jev fails; the caller keeps the rows and retries.
+     */
+    check(input: PrepareInput, profileContext?: string): Promise<AdmissionCheck>;
+    /**
+     * Write one recovery field per constraint id. Does not run Jev.
+     * @param input - Opening draft and the answers already on the page.
+     * @param missing - Constraint ids that still need a row.
+     */
+    questions(input: PrepareInput, missing: readonly string[]): Promise<RecoveryField[]>;
     /**
-     * Prepare one draft using the creation admission policy.
+     * Fold answers, admit the draft, and return a recovery form when it still fails.
      * @param input - Current payload and pending recovery answers.
      * @param profileContext - The speaker's profile, if supplied by the host.
-     * @returns An admitted draft or admission feedback plus a recovery form.
      * @throws When rewriting, verification, or recovery generation fails; callers must retain the input for retry.
      */
     invoke(input: PrepareInput, profileContext?: string): Promise<PrepareResult>;
+    /** Today's recovery form, used only when the Jev call itself fails. */
+    private legacy;
+    /** One field per constraint still missing. None named means one text field from the admission message. */
+    private revise;
+    private fieldsFor;
 }

package/dist/internal/intents/intent.preparer.js

@@ -1,8 +1,9 @@
 import { HumanMessage, SystemMessage } from "@langchain/core/messages";
 import { z } from "zod";
+import { DecisionClient } from "../shared/agent/decision.client.js";
 import { createStructuredModel } from "../shared/agent/model.config.js";
 import { invokeWithAbortSignal } from "../shared/agent/model-signal.js";
-import { admissionFailure, semanticMetadata } from "./intent.admission.js";
+import { ADMISSION_CONSTRAINTS, admissionFailure, admissionFromDecision, semanticMetadata } from "./intent.admission.js";
 import { SemanticVerifier } from "./intent.verifier.js";
 const payloadSchema = z.object({ payload: z.string().trim().min(1).max(65536) });
 const recoveryOptionSchema = z.object({
@@ -17,34 +18,107 @@ const recoveryFieldSchema = z.object({
     placeholder: z.string().max(200).nullable().optional(),
 });
 const recoverySchema = z.object({
+    recovery: z.array(recoveryFieldSchema).min(1).max(6),
+});
+const legacyRecoverySchema = z.object({
     recovery: z.array(recoveryFieldSchema).min(2).max(6),
 });
-function parseRecoveryFields(result) {
-    return result.recovery.map((field) => {
+const noul = (instructions, yes, no) => ({
+    type: "noul",
+    instructions: `Read \`draft\` and \`answers\` together. ${instructions}`,
+    criteria: { true: yes, false: no },
+});
+/** The admission process: the same questions judge the opening draft and a draft after answers. */
+const ADMISSION_QUESTIONS = {
+    speech_act: {
+        type: "choice",
+        instructions: "Read `draft` and `answers` together. What speech act is `draft`?",
+        criteria: {
+            commissive: "The speaker commits to a future action.",
+            directive: "The speaker is looking for someone, or asking for something to happen with another person.",
+            declaration: "The speaker cancels, closes, or declares a state change.",
+            other: "A fact, opinion, feeling, or anything that is not a search, a commitment, or a declaration.",
+        },
+    },
+    too_vague: noul("Is `draft` still too unconstrained to match someone on? A bare request, such as wanting a job with no role or outcome, is too vague.", "The goal is too unconstrained to match on.", "The goal names a concrete role, outcome, or particular help."),
+    too_broad: noul("Could many people still satisfy `draft`, even if it names a topic?", "Many people could plausibly match.", "A concrete role, outcome, location, timeframe, or specific need narrows who fits."),
+    role: noul("Is a specific role still missing from `draft`?", "No specific role is stated.", "A specific role is stated."),
+    outcome: noul("Is a concrete outcome still missing from `draft`?", "No concrete outcome is stated.", "A concrete outcome is stated."),
+    location: noul("Is a location still missing from `draft` where one would change who fits?", "No location is stated and one would change who fits.", "A location is stated, or none is needed."),
+    timeframe: noul("Is a timeframe still missing from `draft` where one would change who fits?", "No timeframe is stated and one would change who fits.", "A timeframe is stated, or none is needed."),
+    domain: noul("Is a domain still missing from `draft`?", "No domain is stated.", "A domain is stated."),
+    concrete_need: noul("Is the particular help still missing from `draft`?", "The particular help is not stated.", "The particular help is stated."),
+};
+function parseRecoveryFields(fields) {
+    return fields.map((field) => {
         const placeholder = field.placeholder?.trim() || undefined;
         const options = field.options?.length ? field.options : undefined;
         if (field.kind === "text") {
-            if (!placeholder) {
+            if (!placeholder)
                 throw new Error("Text recovery fields require a placeholder.");
-            }
             return { id: field.id, label: field.label, kind: field.kind, placeholder };
         }
-        if (!options?.length) {
+        if (!options?.length)
             throw new Error("Single and multi recovery fields require options.");
-        }
         return { id: field.id, label: field.label, kind: field.kind, options };
     });
 }
+function readDecision(answers) {
+    const speech = answers.speech_act;
+    const speechAct = speech?.type === "choice" ? speech.choice : "";
+    if (speechAct !== "commissive" && speechAct !== "directive" && speechAct !== "declaration" && speechAct !== "other") {
+        throw new Error("Jev speech_act answer was unusable");
+    }
+    const probability = (key) => {
+        const answer = answers[key];
+        if (!answer || answer.type !== "noul")
+            throw new Error(`Jev ${key} answer was unusable`);
+        return answer.noul;
+    };
+    const constraints = Object.fromEntries(ADMISSION_CONSTRAINTS.map((name) => [name, probability(name)]));
+    return { speechAct, tooVague: probability("too_vague"), tooBroad: probability("too_broad"), constraints };
+}
+function textField(message) {
+    return { id: "detail", label: message, kind: "text", placeholder: "Add the missing detail" };
+}
+function isAbort(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
 /** Folds recovery answers into a draft, admits its final form, and returns a dynamic recovery form on failure. Model failures propagate for retry. */
 export class IntentPreparer {
-    constructor(verifier = new SemanticVerifier()) {
+    constructor(verifier = new SemanticVerifier(), decider = new DecisionClient()) {
         this.verifier = verifier;
+        this.decider = decider;
     }
     /**
-     * Prepare one draft using the creation admission policy.
+     * Ask Jev whether the current rows would pass. Does not fold text or write questions.
+     * @param input - Opening draft and the answers already on the page.
+     * @param profileContext - The speaker's profile, if supplied by the host.
+     * @throws When Jev fails; the caller keeps the rows and retries.
+     */
+    async check(input, profileContext = "") {
+        const answers = (input.answers ?? []).filter((answer) => answer.answer.trim());
+        const judged = admissionFromDecision(readDecision(await this.decider.decide({ draft: input.payload, answers, profile: profileContext }, ADMISSION_QUESTIONS)));
+        if (!judged.failure)
+            return { passed: true, missing: [], message: "" };
+        return { passed: false, missing: judged.missing, message: judged.failure.message };
+    }
+    /**
+     * Write one recovery field per constraint id. Does not run Jev.
+     * @param input - Opening draft and the answers already on the page.
+     * @param missing - Constraint ids that still need a row.
+     */
+    async questions(input, missing) {
+        const answers = (input.answers ?? []).filter((answer) => answer.answer.trim());
+        const constraints = [...new Set(missing)].filter((id) => ADMISSION_CONSTRAINTS.includes(id));
+        if (!constraints.length)
+            return [];
+        return this.fieldsFor(input.payload, answers, "", constraints);
+    }
+    /**
+     * Fold answers, admit the draft, and return a recovery form when it still fails.
      * @param input - Current payload and pending recovery answers.
      * @param profileContext - The speaker's profile, if supplied by the host.
-     * @returns An admitted draft or admission feedback plus a recovery form.
      * @throws When rewriting, verification, or recovery generation fails; callers must retain the input for retry.
      */
     async invoke(input, profileContext = "") {
@@ -58,11 +132,28 @@ export class IntentPreparer {
             ]);
             payload = payloadSchema.parse(result).payload;
         }
+        let jevFailed = false;
+        try {
+            const judged = admissionFromDecision(readDecision(await this.decider.decide({ draft: payload, profile: profileContext }, ADMISSION_QUESTIONS)));
+            if (judged.failure)
+                return this.revise(payload, answers, judged.failure.message, judged.missing);
+        }
+        catch (error) {
+            if (isAbort(error))
+                throw error;
+            jevFailed = true;
+        }
         const verdict = await this.verifier.invoke(payload, profileContext);
-        const failure = admissionFailure(payload, verdict);
+        const failure = admissionFailure(verdict);
         if (!failure)
             return { status: "ready", payload, metadata: semanticMetadata(verdict) };
-        const model = createStructuredModel("intentClarifier", recoverySchema, { name: "intent_recovery" });
+        if (jevFailed)
+            return this.legacy(payload, answers, failure, verdict);
+        return this.revise(payload, answers, failure.message, verdict.missing_selectional_constraints);
+    }
+    /** Today's recovery form, used only when the Jev call itself fails. */
+    async legacy(payload, answers, failure, verdict) {
+        const model = createStructuredModel("intentClarifier", legacyRecoverySchema, { name: "intent_recovery" });
         const result = await invokeWithAbortSignal(model, [
             new SystemMessage("Build one recovery form that helps the person concretize their signal. Return 2-6 fields. Each field needs a draft-specific label, a kind (single, multi, or text), and for single/multi 2-5 concrete options anchored to the draft. Text fields need a placeholder. Never re-ask what the draft or answers already settle. Options must be matchable and specific. Do not expose scores, classifications, JSON, or internal vocabulary."),
             new HumanMessage(JSON.stringify({
@@ -77,11 +168,27 @@ export class IntentPreparer {
                 missingConstraints: verdict.missing_selectional_constraints,
             })),
         ]);
-        return {
-            status: "needs_revision",
-            payload,
-            feedback: failure.message,
-            recovery: parseRecoveryFields(recoverySchema.parse(result)),
-        };
+        return { status: "needs_revision", payload, feedback: failure.message, recovery: parseRecoveryFields(legacyRecoverySchema.parse(result).recovery) };
+    }
+    /** One field per constraint still missing. None named means one text field from the admission message. */
+    async revise(payload, answers, feedback, missing) {
+        const constraints = [...new Set(missing)];
+        const recovery = constraints.length === 0
+            ? [textField(feedback)]
+            : await this.fieldsFor(payload, answers, feedback, constraints);
+        return { status: "needs_revision", payload, feedback, recovery };
+    }
+    async fieldsFor(payload, answers, feedback, constraints) {
+        const model = createStructuredModel("intentClarifier", recoverySchema, { name: "intent_recovery" });
+        const result = await invokeWithAbortSignal(model, [
+            new SystemMessage(`Write one recovery field for each missing constraint, in this order: ${constraints.join(", ")}. Set each field's id to that constraint name. Each field needs a draft-specific label, a kind (single, multi, or text), and for single/multi 2-5 concrete options anchored to the draft. Text fields need a placeholder. Do not add any other field. Never re-ask what the draft or answers already settle. Do not expose scores, classifications, JSON, or internal vocabulary.`),
+            new HumanMessage(JSON.stringify({ payload, answers, feedback, missingConstraints: constraints })),
+        ]);
+        const fields = parseRecoveryFields(recoverySchema.parse(result).recovery);
+        const byId = new Map(fields.map((field) => [field.id, field]));
+        const matched = constraints.map((id) => byId.get(id));
+        if (matched.some((field) => !field))
+            throw new Error("Recovery fields did not cover the missing constraints.");
+        return matched;
     }
 }

package/dist/internal/opportunities/opportunity.cards.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Opportunity cards: presenter-texted cards for a viewer, as a list or one at
+ * a time. The list loads, filters, and dedupes the viewer's opportunities,
+ * serves cached cards, and presents the misses through OpportunityPresenter.
+ */
+import type { Opportunity, OpportunityCardsDatabase, OpportunityStatus } from '../../platform/database.js';
+import type { OpportunityCache } from '../../platform/discovery/cache.js';
+import { OpportunityPresenter } from './opportunity.presentation.js';
+/** One opportunity with its presenter-driven display contract. */
+export interface OpportunityCard {
+    opportunityId: string;
+    createdAt?: string;
+    /** Lifecycle status of the underlying opportunity at render time. */
+    status?: OpportunityStatus;
+    userId: string;
+    name: string;
+    avatar: string | null;
+    mainText: string;
+    cta: string;
+    headline?: string;
+    primaryActionLabel: string;
+    secondaryActionLabel: string;
+    mutualIntentsLabel: string;
+    narratorChip?: {
+        name: string;
+        text: string;
+        avatar?: string | null;
+        userId?: string;
+    };
+    /** Viewer's role in this opportunity (e.g. 'party', 'agent', 'patient', 'peer'). */
+    viewerRole?: string;
+    /**
+     * True for a skeleton card: identity fields are real but mainText/cta are
+     * empty because the presenter was skipped. Never cached.
+     */
+    presentationPending?: boolean;
+}
+/** Everything card presentation reaches for. */
+export interface OpportunityCardsDeps {
+    database: OpportunityCardsDatabase;
+    cache: OpportunityCache;
+    presenter: OpportunityPresenter;
+}
+/**
+ * Present one opportunity as a card for the viewer.
+ *
+ * @param deps - Database, cache, and presenter.
+ * @param opportunity - The opportunity to present.
+ * @param viewerId - The viewing user.
+ * @param options - `intentId` focuses viewer context on one intent; `skeleton` skips the presenter.
+ * @returns The card, or null when the counterpart's name cannot be resolved.
+ * @throws When the presenter fails.
+ */
+export declare function presentOpportunityCard(deps: OpportunityCardsDeps, opportunity: Opportunity, viewerId: string, options?: {
+    intentId?: string;
+    skeleton?: boolean;
+}): Promise<OpportunityCard | null>;
+/**
+ * List the viewer's opportunities in the given statuses as presented cards,
+ * newest first, one card per counterpart. Cards whose presentation fails are
+ * dropped.
+ *
+ * @param deps - Database, cache, and presenter.
+ * @param input - Viewer, statuses, optional network/intent scope, limit, cache bypass, skeleton mode.
+ * @returns The cards and the number of opportunities selected.
+ */
+export declare function listOpportunityCards(deps: OpportunityCardsDeps, input: {
+    viewerId: string;
+    statuses: OpportunityStatus[];
+    networkId?: string;
+    intentId?: string;
+    limit: number;
+    noCache?: boolean;
+    skeleton?: boolean;
+}): Promise<{
+    cards: OpportunityCard[];
+    totalOpportunities: number;
+}>;