typeglish 0.1.0

package/dist/index-Df_QnTgq.d.ts

@@ -0,0 +1,313 @@
+import { C as CompileOptions, S as Span, D as Deontic, k as PredicateIR, B as Bag } from './compile-DViQS2oG.js';
+import { S as Severity, D as Diagnostic } from './diagnostics-BWJ_oMd8.js';
+
+type Importance = 'critical' | 'important' | 'advisory';
+/** Is `a` at least as important as `b`? (`critical ≥ important ≥ advisory`.) */
+declare function atLeastImportant(a: Importance, b: Importance): boolean;
+/**
+ * How much a diagnostic matters, independent of its severity level. An `error` is always `critical`; a
+ * correctness-category warning/info is `important`; a style / quality / grammar / spelling nudge is `advisory`.
+ */
+declare function importanceOf(code: string, severity: Severity): Importance;
+
+/** How strict to be — a product tightens the compiler here so no IMPORTANT warning slips through unblocking. */
+interface StrictnessPolicy {
+    /** Escalate every `warn` to a blocking `error` (the blunt "warnings as errors" switch). `info` stays advisory. */
+    strict?: boolean;
+    /** Escalate specific diagnostics to `error` — by full code (`structure/unused-tool`) or whole category (`style`). */
+    escalate?: string[];
+    /** Escalate any diagnostic at or above this IMPORTANCE to a blocking error — the precise "strict about what
+     *  MATTERS" knob. `'important'` blocks every correctness finding (dangling refs, dead rules, leaked secrets)
+     *  while leaving style / quality nudges advisory; `'critical'` blocks only hard errors. */
+    escalateImportance?: Importance;
+    /** The ONLY way to make a warning non-blocking: name its code / category here. Explicit and auditable — never
+     *  silent. A relaxed diagnostic still appears in the report, demoted to `info`, so nothing disappears. */
+    relax?: string[];
+}
+interface ReportRange {
+    line: number;
+    column: number;
+    endColumn: number;
+}
+interface ReportDiagnostic {
+    code: string;
+    category: string;
+    name: string;
+    importance: Importance;
+    severity: Severity;
+    effectiveSeverity: Severity;
+    blocking: boolean;
+    range: ReportRange;
+    message: string;
+    fix?: {
+        title: string;
+        replacement: string;
+    };
+}
+interface ProgramSummary {
+    inputs: {
+        name: string;
+        type: string;
+    }[];
+    defines: string[];
+    sections: string[];
+    tools: string[];
+    routes: string[];
+    steps: number;
+    switches: {
+        value: number;
+        predicate: number;
+        tuple: number;
+        inline: number;
+    };
+}
+interface TgReport {
+    ok: boolean;
+    consistent: boolean;
+    wellFormed: boolean;
+    counts: {
+        error: number;
+        warn: number;
+        info: number;
+    };
+    diagnostics: ReportDiagnostic[];
+    program: ProgramSummary;
+    xml: string;
+}
+/** The compile knobs a report caller may thread through — the ambient project layer (`glish.tgc`), the
+ *  edge-injected dictionary, and extra addressee nouns. A subset of {@link CompileOptions}: the report stays
+ *  the agent envelope; rubric/instructions belong to richer compile callers. */
+type ReportCompileOptions = Pick<CompileOptions, 'glishConfig' | 'isWord' | 'addressees'>;
+/**
+ * The agent-consumable compile report. Pure and JSON-serializable. Pass `extraDiagnostics` to fold in the async
+ * solver tiers (numeric conflicts, Z3 exhaustiveness) a Node/server caller has already computed, so the report
+ * reflects the FULL check, not just the synchronous one. Pass `compile` to thread the project's `glish.tgc` /
+ * dictionary / addressees into the underlying compile — same knobs, same envelope.
+ */
+declare function report(source: string, opts?: {
+    policy?: StrictnessPolicy;
+    extraDiagnostics?: Diagnostic[];
+    compile?: ReportCompileOptions;
+}): TgReport;
+
+/**
+ * Compile the TypeGlish source into the prompt the agent runs: declarations expanded, comments and IMPORT
+ * manifests stripped, cosmetic indentation removed — System then Instructions.
+ *
+ * Markdown headers (`# Role`) and XML tags (`<examples>…</examples>`) are PRESERVED AS AUTHORED — the two are
+ * NOT interconverted. They solve different problems and the model leans on them differently: a `#` heading
+ * signals document structure and semantic weight (section / subsection), while a `<tag>` marks a hard block
+ * boundary the model treats as a delimiter ("everything here is examples"). Rewriting `#` into `<tag>` (as an
+ * earlier version did) erased that distinction and made it ambiguous which one was authoritative; leaving each
+ * as written keeps the signal clean. (The name is historical — the output is a compiled prompt, not only XML.)
+ */
+declare function compileToXml(systemContent: string, instructionsContent: string): string;
+
+interface EditResult {
+    /** Did the edit apply? When false, `source` is unchanged and `error` says why. */
+    ok: boolean;
+    source: string;
+    changed: number;
+    error?: string;
+}
+/**
+ * Rename a declared `$REQUIRE variable` or `$DEFINE` — the declaration AND every `$name` reference (guards,
+ * switches, other defines, prose) — leaving quotes, comments, and `$TOOL`/`$SERVICE` block bodies untouched.
+ * Refuses an invalid target (bad identifier, reserved word, name already taken, a no-op) so the result is
+ * always well-formed. Pure and stateless.
+ */
+declare function rename(source: string, kind: 'variable' | 'define', from: string, to: string): EditResult;
+
+/** One atomic claim extracted from a line. A compound line (`IF g THEN a; b`) yields several atoms —
+ *  the spike showed sentence-level entailment fails on compound lines (0.01 ent on real paraphrase
+ *  pairs) while atom-level matching recovers them at ≥0.96, so atoms are the unit of comparison. */
+interface SemanticAtom {
+    /** Content hash of (text + guard) — durable identity across line moves and renumbering. The
+     *  verdict cache keys on this, so an unchanged claim never re-scores. */
+    id: string;
+    /** 0-based source line the atom came from — session-local position, NOT identity. */
+    line: number;
+    span: Span;
+    /** The self-contained claim an entailment model reads: guard folded in, polarity re-injected
+     *  ("When <guard>, you must not <action>."). */
+    text: string;
+    kind: 'directive' | 'declaration' | 'prose';
+    /** Deontic force when the atom came from a directive. */
+    deontic?: Deontic;
+    /** Normalized subject ('' is the implicit agent) when directive-derived. */
+    subject?: string;
+    /** The original guard text when the claim is conditional. */
+    guard?: string;
+    /** Parsed predicates (verb + theme + roles + tool) — the structured view of what the claim DOES.
+     *  Directive atoms carry their IR predicate; prose atoms carry recall-oriented chunk parses.
+     *  Feeds the candidate gate; never the claim text or id (cache/fixtures stay valid). */
+    predicates?: PredicateIR[];
+}
+/** The five semantic relations between two claims. `covers` is read from `a`'s perspective:
+ *  a is the broader claim and fully implies b. */
+type OverlapRelation = 'equivalent' | 'covers' | 'covered_by' | 'contradicts' | 'distinct';
+/** A scored relation between two atoms. Raw model scores ride along as the receipt — every finding
+ *  the UI shows can point at the numbers behind it. */
+interface PairVerdict {
+    /** Atom ids, in canonical (sorted) order. */
+    a: string;
+    b: string;
+    relation: OverlapRelation;
+    /** P(a entails b) — a as premise. High means a is at least as strong as b. */
+    entAB: number;
+    /** P(b entails a). */
+    entBA: number;
+    /** max of the two directions' contradiction probability — the display receipt. */
+    conMax: number;
+    /** min of the two directions — the TRIGGER: true contradictions are symmetric (~1.00 both ways
+     *  on the bench) while several distinct-but-related traps fire only one way. */
+    conMin: number;
+    /** How sure we are about WHICH side covers the other. NLI alone is unreliable on deontic
+     *  direction (0.17 in the spike), so nli-tier verdicts cap this below the actionable threshold;
+     *  the judge tier raises it. */
+    directionConfidence: number;
+    tier: 'nli' | 'nli+judge';
+    modelVersion: string;
+}
+/** How well one atom is covered by the rest of the prompt: the conjunction-coverage receipt. */
+interface AtomCoverage {
+    atom: string;
+    /** ent(conjunction-of-coverers ⊨ atom) — 0.99 vs 0.002 solo in the spike. */
+    score: number;
+    /** The atoms whose conjunction covers this one. */
+    coveredBy: string[];
+}
+/** The per-line audit — the product's unit of output: what this line uniquely contributes. */
+interface LineAudit {
+    /** 0-based source line. */
+    line: number;
+    atoms: string[];
+    /** 1 − min coverage across the line's atoms: the least-covered atom rules, so a line is only
+     *  low-residual when EVERYTHING it says is already said elsewhere. */
+    residual: number;
+    /** Receipt: which lines cover this one, through which atoms, at what strength. */
+    coveredBy: {
+        line: number;
+        atoms: string[];
+        ent: number;
+    }[];
+    /** Lines this one semantically conflicts with. `confirmed` = a judge-tier verdict (warn-worthy);
+     *  unconfirmed entries are NLI candidates and stay panel-only. */
+    contradicts: {
+        line: number;
+        conf: number;
+        confirmed: boolean;
+    }[];
+    /** True when every atom's coverage clears the removable threshold. Advisory — the behavioral
+     *  ablation verifier (existing profiler) confirms before anyone acts on it. */
+    proposedRemovable: boolean;
+    /** Filled by the behavioral verifier: score delta when this line is ablated. */
+    verified?: {
+        delta: number;
+        stderr: number;
+        samples: number;
+    };
+}
+/** One step of the greedy reduction loop: cut lowest-residual, recompute, repeat. */
+interface ReductionStep {
+    order: number;
+    line: number;
+    text: string;
+    residualAtCut: number;
+    coveredBy: {
+        line: number;
+        ent: number;
+    }[];
+}
+interface SemanticReport {
+    atoms: SemanticAtom[];
+    pairs: PairVerdict[];
+    coverage: AtomCoverage[];
+    lines: LineAudit[];
+    stats: {
+        pairsScored: number;
+        pairsFromCache: number;
+        pairsTruncated: number;
+        /** Fresh judge-tier calls this analysis (cached judge verdicts don't re-bill). */
+        judgeCalls?: number;
+        ms: number;
+    };
+}
+
+/** Decompose a whole prompt into atomic claims. Lines the compiler already understands (directives,
+ *  conditionals, declarations) become IR-derived atoms; remaining content lines fall back to
+ *  sentence + `;` segmentation. Comments, blanks, headings, fenced code, and $-command manifests
+ *  yield nothing — the same gates runDiagnostics applies. */
+declare function decompose(source: string): SemanticAtom[];
+
+interface CandidatePair {
+    a: SemanticAtom;
+    b: SemanticAtom;
+    /** The lexical-overlap gate score — kept as a fusion feature and for truncation ordering. */
+    jaccard: number;
+    /** Which gate admitted the pair — 'predicate' marks zero-lexical-overlap recoveries. */
+    via: 'lexical' | 'predicate' | 'both';
+}
+interface CandidateSet {
+    pairs: CandidatePair[];
+    /** Pairs dropped by MAX_PAIRS — surfaced in stats, never silent. */
+    truncated: number;
+}
+/** Gate all cross-line atom pairs down to the candidates worth scoring. Same-line pairs are never
+ *  candidates: a line doesn't overlap itself, it IS itself. */
+declare function candidatePairs(atoms: SemanticAtom[]): CandidateSet;
+
+interface PairScores {
+    /** P(a entails b) — a as premise. */
+    entAB: number;
+    /** P(b entails a). */
+    entBA: number;
+    /** P(contradiction) with a as premise. */
+    conAB: number;
+    /** P(contradiction) with b as premise. */
+    conBA: number;
+}
+/** Classify one scored pair. Contradiction triggers on the SYMMETRIC signal — min of both
+ *  directions: bench data shows every true contradiction fires ~1.00 both ways while several traps
+ *  fire only one way (min kills 4 of 9 trap false positives outright). Even so, NLI contradiction
+ *  precision on rule-prose caps at ~0.62, so a contradicts verdict is a CANDIDATE — the warn
+ *  diagnostic is gated on judge confirmation; unconfirmed conflicts surface panel-only. Direction
+ *  confidence from NLI alone is capped below the actionable threshold: the spike measured NLI at
+ *  0.17 on deontic direction (worse than chance), so "which side is broader" must come from the
+ *  judge tier or the fine-tuned model, never from these scores. */
+declare function classifyPair(s: PairScores): {
+    relation: OverlapRelation;
+    directionConfidence: number;
+};
+/** Build a full PairVerdict from scores (canonical atom order preserved by the caller). */
+declare function verdictFrom(a: string, b: string, s: PairScores, tier?: PairVerdict['tier']): PairVerdict;
+/** Assemble per-line audits from atoms + verdicts + coverage. Residual is 1 − the line's WORST
+ *  atom coverage: a line is only as redundant as its least-covered claim, so nothing gets proposed
+ *  for removal while any part of it is unique. */
+declare function assembleAudits(atoms: SemanticAtom[], verdicts: PairVerdict[], coverage: AtomCoverage[]): LineAudit[];
+/** Assemble the full report the API returns and the UI renders. */
+declare function buildReport(atoms: SemanticAtom[], verdicts: PairVerdict[], coverage: AtomCoverage[], stats: SemanticReport['stats']): SemanticReport;
+
+interface ReduceOptions {
+    /** Runaway backstop — a prompt proposing more cuts than this deserves human eyes first. */
+    maxCuts?: number;
+}
+declare function proposeReduction(source: string, analyze: (source: string) => Promise<SemanticReport>, opts?: ReduceOptions): Promise<ReductionStep[]>;
+
+/** Fold a semantic report into advisory diagnostics — the strongest finding per line, receipts in
+ *  the message, everything else left to the findings panel. Priority: a semantic conflict outranks
+ *  redundancy (a wrong rule beats a repeated one), full coverage outranks pairwise equivalence
+ *  (it's the stronger, direction-free claim). */
+declare function semanticDiagnostics(report: SemanticReport, source: string, displaySource?: string): Diagnostic[];
+
+/** Knobs for WHERE a resolve runs. The default is the FINAL, model-facing render: an undecidable guard
+ *  strips fail-open (the model must never read `when=` scaffolding). The import pipeline's INTERMEDIATE
+ *  resolve opts into `keepUndecidedGuards`: an unbound guard's tag line stays VERBATIM (attribute and
+ *  `@{}` pointers intact), so conditionality SURVIVES the module boundary and the host's own resolve —
+ *  which holds the runtime bag — decides it. */
+interface ResolveOptions {
+    keepUndecidedGuards?: boolean;
+}
+declare function resolve(source: string, bag: Bag, opts?: ResolveOptions): string;
+
+export { type AtomCoverage as A, type EditResult as E, type Importance as I, type LineAudit as L, type OverlapRelation as O, type PairVerdict as P, type ReportCompileOptions as R, type StrictnessPolicy as S, type TgReport as T, type ProgramSummary as a, type ReductionStep as b, type ReportDiagnostic as c, type ReportRange as d, type SemanticAtom as e, type SemanticReport as f, assembleAudits as g, atLeastImportant as h, buildReport as i, candidatePairs as j, classifyPair as k, compileToXml as l, decompose as m, importanceOf as n, report as o, proposeReduction as p, resolve as q, rename as r, semanticDiagnostics as s, verdictFrom as v };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { A as AgentBundle, B as Bag, C as CompileOptions, a as CompileResult, E as Expr, H as HttpMethod, I as IR, b as IRNode, P as ParamType, c as PreparedTemplate, R as ResolvedModel, T as ToolBinding, d as ToolDef, e as ToolParam, f as compile, g as evalExpr, h as exprAtoms, n as numericDiagnostics, p as parseExpr, i as parseTools, j as prepareTemplate, s as structuralDiagnostics, t as toolInputSchema } from './compile-DViQS2oG.js';
+export { A as AtomCoverage, E as EditResult, I as Importance, L as LineAudit, O as OverlapRelation, P as PairVerdict, a as ProgramSummary, b as ReductionStep, c as ReportDiagnostic, d as ReportRange, e as SemanticAtom, f as SemanticReport, S as StrictnessPolicy, T as TgReport, g as assembleAudits, h as atLeastImportant, i as buildReport, j as candidatePairs, k as classifyPair, l as compileToXml, m as decompose, n as importanceOf, p as proposeReduction, r as rename, o as report, q as resolve, s as semanticDiagnostics, v as verdictFrom } from './index-Df_QnTgq.js';
+export { D as Diagnostic, R as RubricDim, S as Severity, a as SpellChecker, b as applyFix, c as composeSpans, r as runDiagnostics } from './diagnostics-BWJ_oMd8.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+import './chunk-PXAMTGYY.js';
+export { applyFix, assembleAudits, atLeastImportant, buildReport, candidatePairs, classifyPair, compile, composeSpans, decompose, importanceOf, numericDiagnostics, prepareTemplate, proposeReduction, rename, report, resolve, runDiagnostics, semanticDiagnostics, structuralDiagnostics, verdictFrom } from './chunk-KRYC4OTL.js';
+export { compileToXml, evalExpr, exprAtoms, parseExpr, parseTools, toolInputSchema } from './chunk-YH4ZLQ4G.js';
+import './chunk-Y64EAEYB.js';
+import './chunk-PR4QN5HX.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/mcp.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface McpOptions {
+    cwd?: string;
+    version?: string;
+}
+declare function createTypeglishServer(opts?: McpOptions): McpServer;
+/** `typeglish mcp` — serve the tools over stdio until the host closes the pipe. */
+declare function startMcpServer(opts?: McpOptions): Promise<void>;
+
+export { type McpOptions, createTypeglishServer, startMcpServer };