@illuminis/comprism 0.1.0

package/out/lib/types.d.ts

@@ -0,0 +1,417 @@
+/**
+ * Shared types for the CompletionPrism Companion. No logic lives here.
+ *
+ * Frozen build spec Part C, section 0.5, extended with the v3.2 schema
+ * additions the kickoff brief names: `ExecutedArm`, `LedgerRowV32`,
+ * `DecisionSnapshotV32`, `ProvenanceMeta`, `PersistedTurn`, `ShadowDecision`.
+ *
+ * Three rules shape almost every field below, and they are worth stating once
+ * rather than repeating in forty comments:
+ *
+ *   1. Append-only. Nothing here is ever mutated in place. A correction is a
+ *      new row carrying `supersedes`. `DecisionSnapshot` is stricter still and
+ *      carries no `supersedes` field at all, because it never has one.
+ *   2. Provenance on every derived field. A number says whether it was
+ *      observed, inferred or estimated, and anything inferred says by what
+ *      method.
+ *   3. Content-blind by default. The record carries a fingerprint of a request
+ *      and never the request. Response text is a character count, not text.
+ */
+import type { TaskRepresentation } from '../internal/representation';
+export type Provider = 'anthropic' | 'openai';
+/** Coarse structural bands. Never the model's lookup key on its own. */
+export type Tier = 'simple' | 'standard' | 'complex';
+export type ContextState = 'fresh' | 'warm';
+/** How a number came to exist. Rule 2 of the frozen spec's ground rules. */
+export type Derivation = 'observed' | 'inferred' | 'estimated';
+/**
+ * Where a record came from, which decides what it is allowed to influence.
+ *
+ * `imported` rows - provider exports, log scans, anything reconstructed after
+ * the fact - can be reported on and can never reach an estimator. That
+ * separation is enforced by schema rather than by convention, which is why it
+ * is a field on every row and not a flag someone remembers to check.
+ */
+export type Provenance = 'first_party' | 'imported';
+/** The surface a record entered through, in descending order of fidelity. */
+export type SourceSurface = 'sdk' | 'cli' | 'proxy' | 'vscode' | 'mcp' | 'provider_export' | 'scan';
+/**
+ * What a cost figure actually is.
+ *
+ * A cost the provider billed is not the same object as one we computed from the
+ * published catalog, and neither is the same as one a customer's export
+ * reported to us. Collapsing the three into a single `cost_usd` column is how a
+ * savings figure ends up indefensible.
+ */
+export type CostSemantic = 'billed_actual' | 'catalog_computed' | 'imported_reported' | 'unpriced';
+/**
+ * How an unsuccessful attempt surfaced. The economics live here: a refusal
+ * costs seconds, a plausible wrong answer that survives review costs the most.
+ * Phase 2 measures these; Phase 1 records the raw material for them.
+ */
+export type FailureMode = 'refusal_or_error' | 'incomplete' | 'plausible_wrong' | 'latent' | 'unknown';
+/** What the policy did at a decision point. */
+export type PolicyAction = 'initial' | 'continue_same' | 'switch_model' | 'abandon_recommended';
+/**
+ * Whether the Companion may alter dispatch.
+ *
+ * `monitor` is the only mode this release ships behavior for: the engine runs,
+ * records everything a decision would need, and changes nothing. `active`
+ * exists in the schema so a decision made later is permanently distinguishable
+ * from one made now. It is not a flag that turns selection on - there is no
+ * selection to turn on until the model program delivers tables.
+ */
+export type ExecutionMode = 'monitor' | 'active';
+export interface ModelInfo {
+    id: string;
+    provider: Provider;
+    inPerMTok: number;
+    outPerMTok: number;
+    reportsReasoningTokens: boolean;
+    /** The structural band this model is the default candidate for. */
+    tier: Tier;
+    /** Human label for reports. */
+    label: string;
+}
+export interface Usage {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    reasoningTokens?: number | null;
+}
+/**
+ * Provenance metadata carried alongside any derived figure (v3.2).
+ *
+ * `method` is required whenever `derivation` is `inferred`, and `confidence`
+ * whenever it is `estimated`. A derived number with neither cannot be restated
+ * later and so cannot serve as evidence.
+ */
+export interface ProvenanceMeta {
+    derivation: Derivation;
+    provenance: Provenance;
+    /** Required when derivation is 'inferred'. How the number was arrived at. */
+    method?: string;
+    /** Required when derivation is 'estimated'. 0..1. */
+    confidence?: number;
+    source_surface: SourceSurface;
+}
+/**
+ * One persisted turn of a working conversation (v3.2), content-blind.
+ *
+ * The frozen spec's section 1.5 stores turn content in `sessions.json`. That
+ * conflicts with ground rule 6 and with the Phase 1 canary test that no request
+ * text reaches any file, so the persisted form carries the shape of a turn and
+ * not its words: role, fingerprint, size, and which model answered. `content`
+ * appears only when the tenant has explicitly turned text storage on.
+ *
+ * The consequence is deliberate and worth knowing: a session resumed in a new
+ * process cannot replay what was said unless text storage is enabled. Being
+ * content-blind has a cost, and paying it visibly is better than storing the
+ * text and describing the product as content-blind anyway.
+ */
+export interface PersistedTurn {
+    role: 'user' | 'assistant';
+    ts: string;
+    fingerprint: string;
+    chars: number;
+    approx_tokens: number;
+    model?: string;
+    provider?: Provider;
+    /** Present only when contentPolicy.storeText is true. Default: absent. */
+    content?: string;
+}
+export interface Session {
+    session_id: string;
+    title: string;
+    created: string;
+    updated: string;
+    source_surface: SourceSurface;
+    turns: PersistedTurn[];
+}
+/** An in-memory conversation turn. Never written to disk in this shape. */
+export interface Message {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/**
+ * One row per provider call, or per imported usage record.
+ *
+ * Absent by design: prompt text, response text, API keys.
+ *
+ * Token counts and cost are nullable, and that is not laziness. A streamed
+ * response whose provider did not report usage has no token count, and writing
+ * a zero there would understate a real cost while looking like a measurement.
+ * `cost_semantic: 'unpriced'` says so out loud, and the report counts those
+ * calls on their own line rather than folding them silently into a total.
+ */
+export interface LedgerRowV32 {
+    event_id: string;
+    /** The DecisionSnapshot that caused this call. Always resolves. */
+    decision_id: string;
+    ts: string;
+    source_system: SourceSurface;
+    granularity: 'request' | 'daily_aggregate';
+    session_id: string;
+    turn_index: number;
+    user: string;
+    task_tier: Tier;
+    context_tokens: number;
+    prompt_tokens: number;
+    fresh_context: boolean;
+    provider: Provider;
+    model_dispatched: string;
+    attempt_index: number;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    reasoning_tokens?: number | null;
+    finish_reason: string;
+    latency_ms: number;
+    cost_usd: number | null;
+    cost_semantic: CostSemantic;
+    /** sha256 of the normalized prompt. NOT the prompt. */
+    prompt_fingerprint: string;
+    /** Length only. */
+    response_chars: number;
+    catalog_version: string;
+    mode: ExecutionMode;
+    supersedes?: string;
+    meta: ProvenanceMeta;
+    comprism_version: string;
+}
+/** The frozen spec's Phase 1 name for the same object. */
+export type LedgerRow = LedgerRowV32;
+/**
+ * Per-candidate cost breakdown at decision time.
+ *
+ * Every figure is zero and `excludedReason` is set in this release: with no
+ * estimate tables there is nothing to break down, and inventing a number to
+ * fill the shape would be exactly the behavior this product exists to replace.
+ * The shape ships now so the record written today has the same schema as the
+ * record written the day tables arrive.
+ */
+export type EccBreakdown = Record<string, never>;
+/**
+ * Why no recommendation was made. Recorded on every decision in this release.
+ *
+ * Recording the reason rather than a null is what lets a historical request be
+ * re-evaluated the day tables exist: we know exactly what was missing.
+ */
+export type WithheldReason = 'insufficient_evidence' | 'estimator_inert' | 'confidence_below_floor' | 'component_error' | 'no_decision';
+/**
+ * What the system knew and chose at the moment of a decision.
+ *
+ * Written once. Never updated, never superseded, never backfilled. There is no
+ * `supersedes` field and no `chain_id`: chain membership is retrospective
+ * knowledge and lives in its own linkage record, because putting it here would
+ * either make this record mutable or make it a lie.
+ *
+ * That single property - this record means one thing forever - is worth a large
+ * fraction of the calibration, audit and evidence value of the whole system.
+ */
+export interface DecisionSnapshotV32 {
+    decision_id: string;
+    ts: string;
+    session_id: string;
+    turn_index: number;
+    attempt_index: number;
+    action: PolicyAction;
+    task_tier: Tier;
+    classifier_signals: string[];
+    classifier_version: string;
+    /**
+     * The full task representation as it stood at decision time: structural
+     * signals, the locally computed reduced vector, deployment context and the
+     * reporting labels, each with its own version.
+     *
+     * Optional only because records written before the representation shipped do
+     * not carry one, and a record is never rewritten to add a field it did not
+     * have. Everything written from now on has it.
+     */
+    task_representation?: TaskRepresentation;
+    context_tokens: number;
+    fresh_context: boolean;
+    /** sha256 of the normalized prompt, never the prompt. */
+    prompt_fingerprint: string;
+    eligible_candidates: string[];
+    chosen_model: string;
+    chosen_by: 'policy' | 'caller_override';
+    ecc_breakdown: Record<string, EccBreakdown>;
+    /** Content hash of every estimate table consulted. Empty while inert. */
+    survival_table_hashes: Record<string, string>;
+    baseline_version: string | null;
+    policy_version: string;
+    /** Present on every decision in this release: why nothing was recommended. */
+    recommendation_withheld: WithheldReason | null;
+    recommendation_withheld_detail?: string;
+    fallback_used: boolean;
+    fallback_reason?: string;
+    mode: ExecutionMode;
+    meta: ProvenanceMeta;
+    comprism_version: string;
+}
+export type DecisionSnapshot = DecisionSnapshotV32;
+/**
+ * What the policy would have done, recorded without acting on it (v3.2).
+ *
+ * The type ships now so the schema is fixed; the recorder that writes it is
+ * Phase 3 work. While the estimator is inert a shadow decision would carry no
+ * recommendation, which is why nothing writes one yet.
+ */
+export interface ShadowDecision {
+    shadow_id: string;
+    decision_id: string;
+    ts: string;
+    would_have_dispatched: string | null;
+    actually_dispatched: string;
+    ecc_breakdown: Record<string, EccBreakdown>;
+    recommendation_withheld: WithheldReason | null;
+    policy_version: string;
+    meta: ProvenanceMeta;
+}
+/**
+ * One arm of a head-to-head observation (v3.2): a model that actually ran on a
+ * task, with what it cost and how it turned out.
+ */
+export interface ExecutedArm {
+    decision_id: string;
+    event_id: string;
+    model: string;
+    provider: Provider;
+    attempt_index: number;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    cost_usd: number | null;
+    latency_ms: number;
+    finish_reason: string;
+    failure_mode: FailureMode | null;
+    response_chars: number;
+}
+export interface ProviderCall {
+    model: string;
+    messages: Message[];
+    maxTokens?: number;
+}
+export interface ProviderResult {
+    text: string;
+    usage: Usage;
+    finishReason: string;
+    latencyMs: number;
+    /** True when the provider itself reported the token counts. */
+    usageReported: boolean;
+    /**
+     * Present only on a failure. A status line or transport error - never a
+     * response body, because a provider's error body can echo the request back,
+     * and the request is the customer's content.
+     */
+    errorMessage?: string;
+}
+export interface SendOptions {
+    sessionId?: string;
+    /** Dispatch this model regardless of the policy. Records a caller override. */
+    model?: string;
+    maxTokens?: number;
+    /** Which surface is calling. Defaults to 'sdk'. */
+    surface?: SourceSurface;
+}
+/**
+ * What a caller gets back. The receipt fields are returned here and rendered by
+ * the client, never appended to the message history: a caller holding a result
+ * object already has somewhere to put a receipt, so there is nothing to gain by
+ * writing one into the conversation.
+ *
+ * The proxy is the one surface where that is not true - the customer's client
+ * renders the message body and nothing else - so it injects a sentinel-wrapped
+ * footer and strips it back out of every later request. See `footer.ts`.
+ */
+export interface SendResult {
+    text: string;
+    model: string;
+    provider: Provider;
+    usage: Usage;
+    costUsd: number | null;
+    costSemantic: CostSemantic;
+    decisionId: string;
+    eventId: string;
+    sessionId: string;
+    attempts: number;
+    remediated: boolean;
+    taskTier: Tier;
+    classifierSignals: string[];
+    recommendationWithheld: WithheldReason | null;
+    latencyMs: number;
+    /** Every ledger row this send produced, in dispatch order. */
+    ledger: LedgerRowV32[];
+}
+/** Which of the shipped footer layouts the proxy renders. */
+export type FooterTemplate = 
+/** The default: money, attempts and human time - the day-one promise. */
+'completion'
+/** The patent's four cost mechanics, itemized. For technical demos. */
+ | 'mechanics' | 'compact' | 'cumulative' | 'detailed';
+/**
+ * A per-model price the tenant states themselves, layered over the catalog.
+ *
+ * It exists because published list price is not what a large customer pays, and
+ * a savings figure computed from a price the customer knows to be wrong is
+ * worse than no figure at all. Cache prices are optional: left out, they are
+ * derived from the input price by the provider's published multipliers.
+ */
+export interface FooterPriceOverride {
+    inPerMTok: number;
+    outPerMTok: number;
+    cacheReadPerMTok?: number;
+    cacheWritePerMTok?: number;
+}
+export interface FooterConfig {
+    /** Kill switch. Off means the proxy is byte-faithful in both directions. */
+    enabled: boolean;
+    template: FooterTemplate;
+    /**
+     * The model the saving is measured against: what the customer would have
+     * spent had the company mandated one capable model for everything. Named in
+     * the footer itself, because a saving is only meaningful against a stated
+     * alternative.
+     */
+    baselineModel: string;
+    /** Model id to price. Empty means the catalog's published prices. */
+    pricing: Record<string, FooterPriceOverride>;
+    /**
+     * How the receipt is delimited.
+     *
+     * `comment` wraps it in an HTML comment, which renders as nothing. `visible`
+     * uses plain text markers instead - needed on any surface whose renderer
+     * strips comments before display, and the way to tell the two failures apart.
+     */
+    marker?: 'comment' | 'visible' | 'none';
+    /**
+     * The tenant's own portal, linked at the end of every receipt.
+     *
+     * The receipt is two lines and can never carry the whole story, so it ends
+     * with where the whole story is: the tenant's stats, traceable to the records
+     * behind them. Empty means no link rather than a broken one.
+     */
+    tenant?: string;
+    /**
+     * Let the model choose which model answers.
+     *
+     * Off means observe and report a counterfactual. On means the request is
+     * rewritten to the model with the lowest expected cost to complete, and the
+     * receipt describes what actually happened rather than what might have.
+     */
+    route?: boolean;
+    /**
+     * Where the receipt's link points.
+     *
+     * Production is `{tenant}.{app}.illuminis.ai` - the tenant's own subdomain of
+     * the app's own subdomain of the company domain. In development it points at
+     * the app running on this machine instead, so the link is clickable rather
+     * than decorative.
+     */
+    portal?: {
+        /** Set false to link at production. */
+        useDev?: boolean;
+        /** The app running locally, e.g. http://localhost:5182 */
+        devUrl?: string;
+        /** The production suffix after the tenant, e.g. completionprism.illuminis.ai */
+        domain?: string;
+    };
+}

package/out/lib/types.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Shared types for the CompletionPrism Companion. No logic lives here.
+ *
+ * Frozen build spec Part C, section 0.5, extended with the v3.2 schema
+ * additions the kickoff brief names: `ExecutedArm`, `LedgerRowV32`,
+ * `DecisionSnapshotV32`, `ProvenanceMeta`, `PersistedTurn`, `ShadowDecision`.
+ *
+ * Three rules shape almost every field below, and they are worth stating once
+ * rather than repeating in forty comments:
+ *
+ *   1. Append-only. Nothing here is ever mutated in place. A correction is a
+ *      new row carrying `supersedes`. `DecisionSnapshot` is stricter still and
+ *      carries no `supersedes` field at all, because it never has one.
+ *   2. Provenance on every derived field. A number says whether it was
+ *      observed, inferred or estimated, and anything inferred says by what
+ *      method.
+ *   3. Content-blind by default. The record carries a fingerprint of a request
+ *      and never the request. Response text is a character count, not text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/lib/ui.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Terminal presentation.
+ *
+ * This is a developer product, so the terminal IS the interface, and it gets the
+ * same care a screen would. Three rules hold it together:
+ *
+ *   1. **The brand shows up here.** The prism spectrum and the illuminis palette
+ *      are the same ones the portal and the documents use, rendered in 24-bit
+ *      color where the terminal supports it.
+ *   2. **Color is never the only signal.** Every state that matters also has a
+ *      glyph and a word, so the output survives `NO_COLOR`, a pipe, a CI log and
+ *      a color-blind reader unchanged.
+ *   3. **Nothing here is decoration for its own sake.** Every panel answers a
+ *      question the person actually has: what did that cost, what was wasted,
+ *      and how sure are we of the number.
+ */
+export declare function width(): number;
+export declare const c: {
+    blue: (s: string) => string;
+    deep: (s: string) => string;
+    purple: (s: string) => string;
+    green: (s: string) => string;
+    amber: (s: string) => string;
+    red: (s: string) => string;
+    muted: (s: string) => string;
+    text: (s: string) => string;
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+};
+/**
+ * Any glyph, in one of the eight spectrum colors.
+ *
+ * Exported so the logo and the rule under it are drawn from the SAME eight
+ * values. Two hand-picked palettes in one product drift apart within a release,
+ * and the brand is the one thing a customer notices before the engine.
+ */
+export declare function spectrumAt(index: number, glyph: string): string;
+export declare function prismRule(w?: number): string;
+export declare function banner(subtitle?: string): string;
+export declare function money(v: number | null): string;
+/** Clip to a visible width, with an ellipsis, so a card never bleeds. */
+export declare function clip(s: string, n: number): string;
+export declare function pad(s: string, n: number): string;
+export declare function padLeft(s: string, n: number): string;
+export declare function stripAnsi(s: string): string;
+/**
+ * A row of KPI cards - the same shape the portal's summary tab uses, so the two
+ * surfaces read as one product rather than two tools that happen to share a name.
+ */
+export declare function kpiCards(cards: {
+    label: string;
+    value: string;
+    note?: string;
+    tone?: 'good' | 'warn' | 'plain';
+}[]): string;
+/**
+ * A Pareto bar: sorted descending with a running cumulative share.
+ *
+ * Pareto rather than a plain bar chart because the question a spend screen has
+ * to answer is not "how much did each cost" but "how few of these carry most of
+ * the bill" - the answer is usually two or three, and that is the whole insight.
+ */
+export declare function paretoBars(rows: {
+    label: string;
+    value: number;
+    sub?: string;
+}[], opts?: {
+    unit?: (v: number) => string;
+    barWidth?: number;
+}): string;
+export declare function table(headers: string[], rows: string[][]): string;
+/**
+ * The thing that makes it visible that something is between the person and the
+ * provider.
+ *
+ * Without this, an instrumented session looks exactly like an uninstrumented
+ * one, and a product nobody can see is a product nobody renews. It shows the
+ * work as it happens - characterising, dispatching, recording - and then gets
+ * out of the way, leaving the answer and a one-line receipt.
+ */
+export declare class LiveIndicator {
+    private timer;
+    private frame;
+    private label;
+    private readonly frames;
+    start(label: string): void;
+    update(label: string): void;
+    stop(): void;
+}
+export interface ReceiptData {
+    model: string;
+    tier: string;
+    signals: string[];
+    inputTokens: number | null;
+    outputTokens: number | null;
+    costUsd: number | null;
+    latencyMs: number;
+    attempts: number;
+    remediated: boolean;
+    wastedUsd: number | null;
+    withheld: string | null;
+}
+/**
+ * The receipt, rendered by the client and never injected into the conversation.
+ *
+ * Injected text is re-sent on every later turn, so a receipt in the message
+ * array is a line item the customer pays for again on every turn for the rest of
+ * the session. It belongs on the screen, not in the context window.
+ */
+export declare function receipt(r: ReceiptData): string;
+export declare function ok(msg: string): string;
+export declare function warn(msg: string): string;
+export declare function fail(msg: string): string;
+export declare function info(msg: string): string;