@michaelborck/honeyguide-core 0.6.0 → 0.7.0

package/dist/types.d.ts

@@ -6,6 +6,15 @@ export type ResourceFormat = 'video' | 'website' | 'podcast' | 'paper' | 'white-
  * resource is gone). Unverifiable resources are flagged, never hidden.
  */
 export type VerificationStatus = 'verified' | 'paywalled' | 'blocked' | 'dead' | 'unverified';
+/**
+ * How verification was established. `database` means the record came out of a
+ * database seconds earlier (existence attested); `url-check` means a live HTTP
+ * probe ran; `none` means neither could be done. The distinction matters: a
+ * database record can still sit behind a paywall.
+ */
+export type VerificationBasis = 'database' | 'url-check' | 'none';
+/** Access status for a paper: freely readable, subscription, or unknown. */
+export type AccessStatus = 'open' | 'subscription' | 'unknown';
 export type LicensingStatus = 'oer' | 'creative-commons' | 'library-subscription' | 'link-only' | 'unknown';
 /**
  * Which rung of the annotation ladder produced the text (ADR-0011):
@@ -25,6 +34,37 @@ export interface Annotation {
  * retrieved to challenge it (counterpoint mode, spec §3 point 3).
  */
 export type Stance = 'supporting' | 'counterpoint';
+/** Optional constraints from the interview brief (ADR-0018). */
+export interface SearchConstraints {
+    /** Prefer freely readable papers; known subscription records are dropped. */
+    openAccessOnly?: boolean;
+    /** Formats to omit entirely (e.g. video). */
+    excludeFormats?: ResourceFormat[];
+    /** Drop resources with a known year older than this. */
+    minYear?: number;
+}
+/** A unit learning outcome, used for optional alignment (ADR-0017). */
+export interface Outcome {
+    id: string;
+    text: string;
+}
+export type AlignmentConfidence = 'high' | 'medium' | 'low';
+/**
+ * A proposed link between a resource and an outcome. The model proposes; the
+ * human confirms. Only confirmed alignments are exported.
+ */
+export interface Alignment {
+    outcomeId: string;
+    /** Copied so collections and exports are self-contained. */
+    outcomeText: string;
+    /** Choice probability or embedding similarity, 0..1. */
+    score: number;
+    confidence: AlignmentConfidence;
+    proposedBy: 'decision' | 'embeddings';
+    /** One-line "why this outcome" from the local LLM, when available. */
+    reason?: string;
+    confirmed: boolean;
+}
 export interface Resource {
     stance: Stance;
     title: string;
@@ -36,6 +76,10 @@ export interface Resource {
     /** Journal, publisher or channel, when known. */
     venue: string | null;
     verification: VerificationStatus;
+    /** How that verification was established (database vs URL probe). */
+    verificationBasis: VerificationBasis;
+    /** Paper access status; 'unknown' for non-papers or when no signal exists. */
+    access: AccessStatus;
     /** Consultant reports are marketing artefacts as often as evidence. */
     commerciallyInterested: boolean;
     licensing: LicensingStatus;
@@ -44,6 +88,8 @@ export interface Resource {
     /** oEmbed or og:image URL; null when unavailable (ADR-0005). */
     thumbnailUrl: string | null;
     accessibilityNotes: string[];
+    /** Proposed outcome alignment, if the request supplied outcomes (ADR-0017). */
+    alignment: Alignment | null;
 }
 export interface SuggestRequest {
     /** A topic string, or extracted text from an uploaded document. */
@@ -54,8 +100,24 @@ export interface SuggestRequest {
      * or complicates the input's framing, clearly labelled (spec §3).
      */
     counterpoint?: boolean;
+    /** Optional unit outcomes; when present the pipeline proposes alignments. */
+    outcomes?: Outcome[];
+    /** Interview brief constraints (ADR-0018). */
+    constraints?: SearchConstraints;
+    /** Teaching context from the interview; used to frame rationales. */
+    context?: string;
 }
 export type ComponentState = 'ok' | 'degraded' | 'unavailable';
+/** Stages reported by the pipeline while a suggestion is running. */
+export type PipelineStage = 'query' | 'retrieve' | 'verify' | 'rank' | 'annotate' | 'align' | 'done';
+export interface ProgressEvent {
+    stage: PipelineStage;
+    /** Optional detail, e.g. "counterpoints" or the resource being annotated. */
+    detail?: string;
+    current?: number;
+    total?: number;
+}
+export type ProgressListener = (event: ProgressEvent) => void;
 export interface SuggestResult {
     resources: Resource[];
     /** Health of each enrichment component for this request (ADR-0006). */

package/dist/verify/verify.d.ts

@@ -1,9 +1,18 @@
-import type { VerificationStatus } from '../types.js';
+import type { VerificationBasis, VerificationStatus } from '../types.js';
 import type { Candidate } from '../retrieval/candidates.js';
+export interface VerificationOutcome {
+    status: VerificationStatus;
+    basis: VerificationBasis;
+}
 /**
  * Map cite-sight-core's UrlStatus onto Honeyguide's VerificationStatus.
  * `unverified` means the check could not run or was inconclusive — never
  * silently upgraded (ADR-0006).
  */
 export declare function mapUrlStatus(status: string): VerificationStatus;
-export declare function verifyCandidate(candidate: Candidate): Promise<VerificationStatus>;
+/**
+ * Human label that keeps the two verification bases distinct: a database
+ * record is not the same claim as a live link.
+ */
+export declare function verificationText(status: VerificationStatus, basis: VerificationBasis): string;
+export declare function verifyCandidate(candidate: Candidate): Promise<VerificationOutcome>;

package/dist/verify/verify.js

@@ -17,19 +17,28 @@ export function mapUrlStatus(status) {
             return 'unverified';
     }
 }
+/**
+ * Human label that keeps the two verification bases distinct: a database
+ * record is not the same claim as a live link.
+ */
+export function verificationText(status, basis) {
+    if (status !== 'verified')
+        return status;
+    return basis === 'database' ? 'record found' : 'link live';
+}
 export async function verifyCandidate(candidate) {
     // Academic-database results are existence-attested by retrieval itself:
     // the DOI/entry came out of Crossref/OpenAlex/iTunes/Open Library seconds
     // ago. Probing doi.org links additionally hits publisher bot-walls and
-    // reports false "blocked".
+    // reports false "blocked". The basis records that distinction.
     if (candidate.databaseAttested)
-        return 'verified';
+        return { status: 'verified', basis: 'database' };
     try {
         const result = await checkUrl(candidate.url);
-        return mapUrlStatus(result.status);
+        return { status: mapUrlStatus(result.status), basis: 'url-check' };
     }
     catch {
-        return 'unverified';
+        return { status: 'unverified', basis: 'none' };
     }
 }
 //# sourceMappingURL=verify.js.map

package/dist/verify/verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/verify/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAIzD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB;YACE,OAAO,YAAY,CAAC;IACxB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,SAAoB;IACxD,wEAAwE;IACxE,0EAA0E;IAC1E,uEAAuE;IACvE,2BAA2B;IAC3B,IAAI,SAAS,CAAC,gBAAgB;QAAE,OAAO,UAAU,CAAC;IAClD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC7C,OAAO,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,YAAY,CAAC;IACtB,CAAC;AACH,CAAC"}
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/verify/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AASzD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB;YACE,OAAO,YAAY,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA0B,EAC1B,KAAwB;IAExB,IAAI,MAAM,KAAK,UAAU;QAAE,OAAO,MAAM,CAAC;IACzC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC;AAC7D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,SAAoB;IACxD,wEAAwE;IACxE,0EAA0E;IAC1E,uEAAuE;IACvE,+DAA+D;IAC/D,IAAI,SAAS,CAAC,gBAAgB;QAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IACjF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACjD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelborck/honeyguide-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Honeyguide core: retrieval, verification, ranking and rationale. No UI assumptions.",
   "license": "MIT",
   "author": "Michael Borck",